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,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiException, ApiExceptionCode, isQuotaExceededMeta } 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'
+      }
+    }
+  )
+}
+
+function makeQuotaExceededResponse(retryAfter: string) {
+  return new Response(
+    JSON.stringify({
+      code: ApiExceptionCode.errorQuotaExceeded,
+      msg: 'Quota exceeded'
+    }),
+    {
+      status: 403,
+      headers: {
+        'Content-Type': 'application/json',
+        'Retry-After': retryAfter
+      }
+    }
+  )
+}
+
+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')
+    })
+  })
+
+  describe('quota exceeded metadata', () => {
+    it('should parse retry-after metadata from headers', async () => {
+      const retryAfter = 'Wed, 09 Apr 2026 08:00:00 GMT'
+      fetchMock.mockResolvedValueOnce(makeQuotaExceededResponse(retryAfter))
+
+      try {
+        await client.get('/quota')
+        throw new Error('expected quota exceeded error')
+      } catch (e) {
+        expect(e).toBeInstanceOf(ApiException)
+        expect(e).toMatchObject({
+          code: ApiExceptionCode.errorQuotaExceeded
+        })
+        expect(isQuotaExceededMeta((e as ApiException).code, (e as ApiException).meta)).toBe(true)
+        expect((e as ApiException).meta).toMatchObject({
+          retryAfter: new Date(retryAfter).valueOf()
+        })
+      }
+    })
+  })
+})

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

@@ -3,10 +3,11 @@
  */
 
 import * as Sentry from '@sentry/vue'
+import dayjs from 'dayjs'
 import { apiBaseUrl } from '@/utils/env'
 import { TimeoutException } from '@/utils/exception/base'
 import { mergeSignals } from '@/utils/disposable'
-import { ApiException } from './exception'
+import { ApiException, ApiExceptionCode, type MovedResourceCanonical, type QuotaExceededMeta } from './exception'
 import { parseSSE, type SSEEvent } from './sse'
 
 /** Response body when exception encountered for API calling */
@@ -15,12 +16,36 @@ export type ApiExceptionPayload = {
   code: number
   /** Message for developer reading */
   msg: string
+  canonical?: MovedResourceCanonical
 }
 
 function isApiExceptionPayload(body: any): body is ApiExceptionPayload {
   return body && typeof body.code === 'number' && typeof body.msg === 'string'
 }
 
+function getQuotaExceededMeta(headers: Headers): QuotaExceededMeta {
+  const retryAfter = headers.get('Retry-After')
+  let date
+  if (retryAfter != null) {
+    const seconds = Number(retryAfter)
+    date = Number.isFinite(seconds) ? dayjs().add(seconds, 's') : dayjs(retryAfter)
+  }
+  return {
+    retryAfter: date?.isValid() ? date.valueOf() : null
+  }
+}
+
+function getApiExceptionMeta(code: number, resp: Response, payload: ApiExceptionPayload): unknown {
+  switch (code) {
+    case ApiExceptionCode.errorQuotaExceeded:
+      return getQuotaExceededMeta(resp.headers)
+    case ApiExceptionCode.errorResourceMoved:
+      return payload.canonical ?? null
+    default:
+      return null
+  }
+}
+
 /** TokenProvider provides access token used for the Authorization header */
 export type TokenProvider = () => Promise<string | null>
 
@@ -84,7 +109,10 @@ export class Client {
         // ignore
       }
       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,
+        meta: getApiExceptionMeta(payload.code, resp, payload)
+      })
     }
     return resp
   }

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

@@ -4,7 +4,6 @@
 
 import type { LocaleMessage } from '@/utils/i18n'
 import { Exception } from '@/utils/exception'
-import dayjs from 'dayjs'
 
 export class ApiException extends Exception {
   name = 'ApiException'
@@ -14,11 +13,11 @@ export class ApiException extends Exception {
   constructor(
     public code: number,
     message: string,
-    { req, resp }: { req: Request; resp: Response }
+    { req, meta }: { req: Request; 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 ?? null
   }
 }
 
@@ -28,29 +27,26 @@ 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 type QuotaExceededMeta = {
   // milliseconds or null
   retryAfter: number | null
 }
-const codeMetas: { [key in ApiExceptionCode]?: (headers: Headers) => unknown } = {
-  [ApiExceptionCode.errorQuotaExceeded]: (headers): QuotaExceededMeta => {
-    const retryAfter = headers.get('Retry-After')
-    let date
-    if (retryAfter != null) {
-      const seconds = Number(retryAfter)
-      date = Number.isFinite(seconds) ? dayjs().add(seconds, 's') : dayjs(retryAfter)
-    }
-    return {
-      retryAfter: date?.isValid() ? date.valueOf() : null
-    }
-  }
-}
+
 export function isQuotaExceededMeta(code: number, meta: unknown): meta is QuotaExceededMeta {
   return code === ApiExceptionCode.errorQuotaExceeded && meta != null
 }
@@ -72,6 +68,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 +84,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,109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { client } from './common'
+import { ApiException, ApiExceptionCode, type MovedResourceCanonical } from './common/exception'
+import { isProjectNameTaken, 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' }),
+    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)
+  })
+})
+
+describe('isProjectNameTaken', () => {
+  let mockedGet: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    mockedGet = vi.spyOn(client, 'get')
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should return true for a canonical project route hit', async () => {
+    mockedGet.mockResolvedValueOnce({
+      owner: 'john',
+      name: 'demo'
+    })
+
+    await expect(isProjectNameTaken('john', 'demo')).resolves.toBe(true)
+  })
+
+  it('should return true when the canonical project route only differs by casing', async () => {
+    mockedGet.mockResolvedValueOnce({
+      owner: 'john',
+      name: 'demo'
+    })
+
+    await expect(isProjectNameTaken('John', 'Demo')).resolves.toBe(true)
+  })
+
+  it('should return false for an alias hit that resolves to another canonical project name', async () => {
+    mockedGet.mockResolvedValueOnce({
+      owner: 'john',
+      name: 'renamed-demo'
+    })
+
+    await expect(isProjectNameTaken('john', 'demo')).resolves.toBe(false)
+  })
+
+  it('should return false when the project route is not found', async () => {
+    mockedGet.mockRejectedValueOnce(
+      new ApiException(ApiExceptionCode.errorNotFound, 'Not found', {
+        req: new Request('https://api.example.com/project/john/demo', { method: 'GET' })
+      })
+    )
+
+    await expect(isProjectNameTaken('john', 'demo')).resolves.toBe(false)
+  })
+})