fix: handle canonicalized route responses

Handle moved-resource responses from the backend without generic write
retries, and retry updateProject once with the canonical route so
saving existing projects still works after a project rename.

Replace unresolved user, project, and editor routes with canonical
backend values after loading so subsequent UI behavior uses canonical
identifiers consistently.

Updates #2993

Signed-off-by: Aofei Sheng <aofei@aofeisheng.com>

Author: aofei

spx-gui/src/apis/common/client.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiException, ApiExceptionCode } from './exception'
+import { Client } from './client'
+
+function makeMovedResponse(canonicalPath: string) {
+  return new Response(
+    JSON.stringify({
+      code: ApiExceptionCode.errorResourceMoved,
+      msg: 'Resource moved',
+      canonical: {
+        path: canonicalPath
+      }
+    }),
+    {
+      status: 409,
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+  )
+}
+
+describe('Client', () => {
+  let client: Client
+  let fetchMock: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    client = new Client()
+    ;(client as any).baseUrl = 'https://api.example.com'
+    fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  describe('path-based moved conflicts', () => {
+    it('should surface the moved conflict without retrying', async () => {
+      fetchMock.mockResolvedValueOnce(makeMovedResponse('/project/john/demo/view'))
+
+      try {
+        await client.post('/project/John/demo/view')
+        throw new Error('expected moved conflict')
+      } catch (e) {
+        expect(e).toBeInstanceOf(ApiException)
+        expect(e).toMatchObject({
+          code: ApiExceptionCode.errorResourceMoved,
+          meta: {
+            path: '/project/john/demo/view'
+          }
+        })
+      }
+
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+      expect(new URL((fetchMock.mock.calls[0]![0] as Request).url).pathname).toBe('/project/John/demo/view')
+    })
+  })
+})

spx-gui/src/apis/common/client.ts

@@ -6,7 +6,7 @@ import * as Sentry from '@sentry/vue'
 import { apiBaseUrl } from '@/utils/env'
 import { TimeoutException } from '@/utils/exception/base'
 import { mergeSignals } from '@/utils/disposable'
-import { ApiException } from './exception'
+import { ApiException, isMovedResourceCanonical } from './exception'
 import { parseSSE, type SSEEvent } from './sse'
 
 /** Response body when exception encountered for API calling */
@@ -15,12 +15,18 @@ export type ApiExceptionPayload = {
   code: number
   /** Message for developer reading */
   msg: string
+  canonical?: unknown
 }
 
 function isApiExceptionPayload(body: any): body is ApiExceptionPayload {
   return body && typeof body.code === 'number' && typeof body.msg === 'string'
 }
 
+function getMovedResourceCanonical(body: ApiExceptionPayload | undefined) {
+  const canonical = body?.canonical
+  return isMovedResourceCanonical(canonical) ? canonical : null
+}
+
 /** TokenProvider provides access token used for the Authorization header */
 export type TokenProvider = () => Promise<string | null>
 
@@ -83,8 +89,13 @@ export class Client {
       } catch {
         // ignore
       }
+      const movedCanonical = getMovedResourceCanonical(payload)
       if (payload == null) throw new Error(`status ${resp.status} for api call: ${req.url.slice(0, 200)}`)
-      throw new ApiException(payload.code, payload.msg, { req, resp })
+      throw new ApiException(payload.code, payload.msg, {
+        req,
+        resp,
+        meta: movedCanonical ?? undefined
+      })
     }
     return resp
   }

spx-gui/src/apis/common/exception.ts

@@ -14,11 +14,11 @@ export class ApiException extends Exception {
   constructor(
     public code: number,
     message: string,
-    { req, resp }: { req: Request; resp: Response }
+    { req, resp, meta }: { req: Request; resp: Response; meta?: unknown }
   ) {
     super(`[${code}] ${message} (${req.method} ${req.url.slice(0, 200)})`)
     this.userMessage = codeMessages[this.code as ApiExceptionCode] ?? null
-    this.meta = codeMetas[this.code as ApiExceptionCode]?.(resp.headers) ?? null
+    this.meta = meta ?? codeMetas[this.code as ApiExceptionCode]?.(resp.headers) ?? null
   }
 }
 
@@ -28,12 +28,32 @@ export enum ApiExceptionCode {
   errorForbidden = 40300,
   errorQuotaExceeded = 40301,
   errorNotFound = 40400,
+  errorResourceMoved = 40901,
   errorTooManyRequests = 42900,
   errorRateLimitExceeded = 42901,
   errorScratchFeatureNotSupported = 50101,
   errorUnknown = 50000
 }
 
+export type MovedResourceCanonical = {
+  path: string
+  username?: string
+  owner?: string
+  name?: string
+  release?: string
+}
+
+export function isMovedResourceCanonical(meta: unknown): meta is MovedResourceCanonical {
+  if (meta == null || typeof meta !== 'object') return false
+  const canonical = meta as Record<string, unknown>
+  if (typeof canonical.path !== 'string') return false
+  if (canonical.username != null && typeof canonical.username !== 'string') return false
+  if (canonical.owner != null && typeof canonical.owner !== 'string') return false
+  if (canonical.name != null && typeof canonical.name !== 'string') return false
+  if (canonical.release != null && typeof canonical.release !== 'string') return false
+  return true
+}
+
 export type QuotaExceededMeta = {
   // milliseconds or null
   retryAfter: number | null
@@ -72,6 +92,14 @@ const codeMessages: Record<ApiExceptionCode, LocaleMessage> = {
     en: 'quota exceeded',
     zh: '超出配额'
   },
+  [ApiExceptionCode.errorNotFound]: {
+    en: 'resource not exist',
+    zh: '资源不存在'
+  },
+  [ApiExceptionCode.errorResourceMoved]: {
+    en: 'resource moved',
+    zh: '资源已迁移'
+  },
   [ApiExceptionCode.errorTooManyRequests]: {
     en: 'too many requests',
     zh: '请求太频繁了'
@@ -80,10 +108,6 @@ const codeMessages: Record<ApiExceptionCode, LocaleMessage> = {
     en: 'rate limit exceeded, please retry later',
     zh: '触发频率限制，请稍后重试'
   },
-  [ApiExceptionCode.errorNotFound]: {
-    en: 'resource not exist',
-    zh: '资源不存在'
-  },
   [ApiExceptionCode.errorScratchFeatureNotSupported]: {
     en: 'Some Scratch features are not supported yet',
     zh: '部分 Scratch 特性暂不支持'

spx-gui/src/apis/project.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { client } from './common'
+import { ApiException, ApiExceptionCode, type MovedResourceCanonical } from './common/exception'
+import { updateProject } from './project'
+
+function makeMovedException(canonical: MovedResourceCanonical) {
+  return new ApiException(ApiExceptionCode.errorResourceMoved, 'Resource moved', {
+    req: new Request('https://api.example.com/project/John/Demo', { method: 'PATCH' }),
+    resp: new Response(null, { status: 409 }),
+    meta: canonical
+  })
+}
+
+describe('updateProject', () => {
+  let mockedPatch: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    mockedPatch = vi.spyOn(client, 'patch')
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should retry once with the canonical project route', async () => {
+    mockedPatch
+      .mockRejectedValueOnce(makeMovedException({ path: '/project/john/demo', owner: 'john', name: 'demo' }))
+      .mockResolvedValueOnce({
+        owner: 'john',
+        name: 'demo'
+      })
+
+    const saved = await updateProject('John', 'Demo', { displayName: 'Demo' })
+
+    expect(saved).toMatchObject({
+      owner: 'john',
+      name: 'demo'
+    })
+    expect(mockedPatch).toHaveBeenCalledTimes(2)
+    expect(mockedPatch.mock.calls[0]![0]).toBe('/project/John/Demo')
+    expect(mockedPatch.mock.calls[1]![0]).toBe('/project/john/demo')
+  })
+
+  it('should surface moved errors without canonical project route fields', async () => {
+    const movedError = makeMovedException({ path: '/project/john/demo' })
+    mockedPatch.mockRejectedValueOnce(movedError)
+
+    await expect(updateProject('John', 'Demo', { displayName: 'Demo' })).rejects.toBe(movedError)
+
+    expect(mockedPatch).toHaveBeenCalledTimes(1)
+  })
+
+  it('should surface moved errors with empty canonical project route fields', async () => {
+    const movedError = makeMovedException({ path: '/project/john/demo', owner: '', name: 'demo' })
+    mockedPatch.mockRejectedValueOnce(movedError)
+
+    await expect(updateProject('John', 'Demo', { displayName: 'Demo' })).rejects.toBe(movedError)
+
+    expect(mockedPatch).toHaveBeenCalledTimes(1)
+  })
+})

spx-gui/src/apis/project.ts

@@ -1,7 +1,7 @@
 import dayjs from 'dayjs'
 import type { FileCollection, ByPage, PaginationParams, Perspective, ArtStyle } from './common'
 import { client, Visibility, ownerAll, timeStringify } from './common'
-import { ApiException, ApiExceptionCode } from './common/exception'
+import { ApiException, ApiExceptionCode, isMovedResourceCanonical } from './common/exception'
 import { parseProjectReleaseFullName, stringifyProjectReleaseFullName, type ProjectRelease } from './project-release'
 import type { Prettify } from '@/utils/types'
 
@@ -101,11 +101,34 @@ export type UpdateProjectParams = Prettify<
 >
 
 export function updateProject(owner: string, name: string, params: UpdateProjectParams, signal?: AbortSignal) {
+  return updateProjectOnce(owner, name, params, signal).catch((err) => {
+    const movedProjectRoute = getMovedProjectRoute(err)
+    if (movedProjectRoute == null) throw err
+
+    const { owner: canonicalOwner, name: canonicalName } = movedProjectRoute
+    if (canonicalOwner === owner && canonicalName === name) throw err
+
+    return updateProjectOnce(canonicalOwner, canonicalName, params, signal)
+  })
+}
+
+function updateProjectOnce(owner: string, name: string, params: UpdateProjectParams, signal?: AbortSignal) {
   return client.patch(`/project/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`, params, {
     signal
   }) as Promise<ProjectData>
 }
 
+function getMovedProjectRoute(err: unknown): { owner: string; name: string } | null {
+  if (!(err instanceof ApiException) || err.code !== ApiExceptionCode.errorResourceMoved) return null
+  if (!isMovedResourceCanonical(err.meta)) return null
+  if (err.meta.owner == null || err.meta.name == null) return null
+  if (err.meta.owner === '' || err.meta.name === '') return null
+  return {
+    owner: err.meta.owner,
+    name: err.meta.name
+  }
+}
+
 export function deleteProject(owner: string, name: string) {
   return client.delete(`/project/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`) as Promise<void>
 }