Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(gfs): r4-h1 fail closed on invalid upload capabilities

Josuéb632331cf523
diff --git a/control-ui/components/GfsBrowser.tsx b/control-ui/components/GfsBrowser.tsx
index 220abc1c4..75838c0c0 100644
--- a/control-ui/components/GfsBrowser.tsx
+++ b/control-ui/components/GfsBrowser.tsx
@@ -391,7 +391,7 @@ export function GfsBrowser(): React.JSX.Element {
await refreshCurrent()
return 'completed'
} catch (error) {
- if (!(error instanceof GfsUploadCapabilityError)) throw error
+ if (!(error instanceof GfsUploadCapabilityError) || !error.allowLegacyFallback) throw error
if (input.resumeUploadId) {
throw new GfsUploadCapabilityError(
'The persisted resumable session cannot be resumed while GFS Upload v2 is unavailable.',
@@ -495,7 +495,7 @@ export function GfsBrowser(): React.JSX.Element {
await refreshCurrent()
} catch (err) {
if (uploadJobRef.current?.snapshot().state === 'aborted') return
- if (err instanceof GfsUploadCapabilityError) {
+ if (err instanceof GfsUploadCapabilityError && err.allowLegacyFallback) {
if (resumeUploadId) {
showToast(
'The persisted resumable session cannot be resumed while GFS Upload v2 is unavailable.',
diff --git a/control-ui/components/__tests__/GfsBrowser.test.tsx b/control-ui/components/__tests__/GfsBrowser.test.tsx
index c2fd50456..f345c8f4f 100644
--- a/control-ui/components/__tests__/GfsBrowser.test.tsx
+++ b/control-ui/components/__tests__/GfsBrowser.test.tsx
@@ -16,7 +16,12 @@ import {
gfsFetchFileBlob,
putGfsGrant,
} from '@lib/api'
-import { GfsUploadCapabilityError, createGfsUploadJob, uploadGfsFile } from '@lib/gfsFileUpload'
+import {
+ GfsUploadCapabilityError,
+ createGfsUploadJob,
+ normalizeUploadProductMaxBytes,
+ uploadGfsFile,
+} from '@lib/gfsFileUpload'
import { normalizeGfsResourceName } from '@lib/gfsResourceName'
import { GfsBrowser } from '../GfsBrowser'
import { ToastProvider } from '../Toast'
@@ -459,7 +464,11 @@ describe('GfsBrowser', () => {
)
mockApiGet.mockResolvedValue({ rootResourceId: rootId, items: [], nextCursor: null })
mockCreateGfsUploadJob.mockImplementationOnce(() => ({
- start: vi.fn().mockRejectedValue(new GfsUploadCapabilityError('writer unavailable')),
+ start: vi
+ .fn()
+ .mockRejectedValue(
+ new GfsUploadCapabilityError('writer unavailable', { allowLegacyFallback: true })
+ ),
snapshot: vi.fn(() => ({ state: 'failed' })),
pause: vi.fn(),
resume: vi.fn(),
@@ -488,6 +497,40 @@ describe('GfsBrowser', () => {
})
})
+ it('fails loudly without legacy fallback for malformed resumable capabilities', async () => {
+ const rootId = '11111111-1111-1111-1111-111111111111'
+ mockApiGet.mockResolvedValue({ rootResourceId: rootId, items: [], nextCursor: null })
+ let malformed: unknown
+ try {
+ normalizeUploadProductMaxBytes(0)
+ } catch (error) {
+ malformed = error
+ }
+ expect(malformed).toBeInstanceOf(GfsUploadCapabilityError)
+ mockCreateGfsUploadJob.mockImplementationOnce(() => ({
+ start: vi.fn().mockRejectedValue(malformed),
+ snapshot: vi.fn(() => ({ state: 'failed' })),
+ pause: vi.fn(),
+ resume: vi.fn(),
+ cancel: vi.fn(),
+ }))
+ renderBrowser()
+ await screen.findByText('No resources are visible in this folder.')
+
+ const browser = screen.getByRole('region', { name: 'Global File System browser' })
+ fireEvent.drop(browser.querySelector('.cu-gfs-card')!, {
+ dataTransfer: {
+ dropEffect: 'none',
+ files: [new File(['payload'], 'payload.bin')],
+ types: ['Files'],
+ },
+ })
+
+ await waitFor(() => expect(screen.getByText((malformed as Error).message)).toBeTruthy())
+ expect(mockApiSend).not.toHaveBeenCalled()
+ expect(screen.queryByText(/using the legacy 16 MiB path/i)).toBeNull()
+ })
+
it('shows byte progress and exposes pause/resume/cancel through the visible upload modal', async () => {
const rootId = '11111111-1111-1111-1111-111111111111'
const rootRid = '11111111111111111111111111111111'
@@ -850,7 +893,9 @@ describe('GfsBrowser', () => {
items: [child('report.md', 'file', 2)],
nextCursor: null,
})
- const capabilityError = new GfsUploadCapabilityError('writer unavailable')
+ const capabilityError = new GfsUploadCapabilityError('writer unavailable', {
+ allowLegacyFallback: true,
+ })
mockCreateGfsUploadJob.mockImplementationOnce(() => ({
start: vi.fn().mockRejectedValue(capabilityError),
snapshot: vi.fn(() => ({ state: 'failed' })),
diff --git a/control-ui/lib/__tests__/gfsFileUpload.test.ts b/control-ui/lib/__tests__/gfsFileUpload.test.ts
index 294a2fe6d..619c8bc5c 100644
--- a/control-ui/lib/__tests__/gfsFileUpload.test.ts
+++ b/control-ui/lib/__tests__/gfsFileUpload.test.ts
@@ -3,12 +3,14 @@ import {
GFS_LEGACY_UPLOAD_MAX_BYTES,
GfsUploadJob,
type GfsUploadStatus,
+ allowsLegacyCapabilityFallback,
assertGfsFileUploadSize,
isAmbiguousUploadStatus,
isRetryableUploadStatus,
normalizeInstabilityFailureThreshold,
normalizeUploadProductMaxBytes,
parseRetryAfter,
+ signalWithTimeout,
uploadGfsFileLegacy,
} from '@lib/gfsFileUpload'
@@ -25,6 +27,45 @@ describe('assertGfsFileUploadSize', () => {
})
})
+describe('Upload v2 capability fallback classification', () => {
+ it.each([
+ ['network failure', new TypeError('fetch failed'), true],
+ ['timeout', Object.assign(new Error('timed out'), { name: 'TimeoutError' }), true],
+ ['request timeout', Object.assign(new Error('timed out'), { status: 408 }), true],
+ ['unsupported endpoint', Object.assign(new Error('missing'), { status: 404 }), true],
+ ['not implemented', Object.assign(new Error('unsupported'), { status: 501 }), true],
+ ['gateway unavailable', Object.assign(new Error('unavailable'), { status: 503 }), true],
+ ['caller abort', Object.assign(new Error('aborted'), { name: 'AbortError' }), false],
+ ['malformed JSON', new SyntaxError('bad JSON'), false],
+ ['unauthorized', Object.assign(new Error('unauthorized'), { status: 401 }), false],
+ ['forbidden', Object.assign(new Error('forbidden'), { status: 403 }), false],
+ ['invalid request', Object.assign(new Error('invalid'), { status: 422 }), false],
+ ['writer failure', Object.assign(new Error('failed'), { status: 500 }), false],
+ ['unknown failure', new Error('unexpected'), false],
+ ])('classifies %s for bounded legacy fallback', (_label, error, expected) => {
+ expect(allowsLegacyCapabilityFallback(error)).toBe(expected)
+ })
+
+ it('classifies the real request timeout reason for bounded legacy fallback', async () => {
+ vi.useFakeTimers()
+ try {
+ const timed = signalWithTimeout(undefined, 25)
+ const aborted = new Promise<void>(resolve => {
+ timed.signal.addEventListener('abort', () => resolve(), { once: true })
+ })
+
+ await vi.advanceTimersByTimeAsync(25)
+ await aborted
+
+ expect(timed.signal.reason).toMatchObject({ name: 'TimeoutError' })
+ expect(allowsLegacyCapabilityFallback(timed.signal.reason)).toBe(true)
+ timed.cancel()
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+})
+
describe('uploadGfsFileLegacy', () => {
afterEach(() => {
vi.unstubAllGlobals()
@@ -163,6 +204,10 @@ class FakeXhr {
}
describe('GfsUploadJob', () => {
+ it('pins the missing-field compatibility default independently of the implementation', () => {
+ expect(normalizeUploadProductMaxBytes(undefined)).toBe(209_715_200)
+ })
+
beforeEach(() => {
FakeXhr.requests = []
FakeXhr.statuses = []
@@ -271,11 +316,52 @@ describe('GfsUploadJob', () => {
expect(createCalls).toBe(0)
})
+ it('marks a valid disabled-v2 response as eligible for bounded fresh legacy fallback', async () => {
+ const file = new File([new Uint8Array([1])], 'disabled-v2.bin')
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(
+ async () =>
+ new Response(JSON.stringify({ upload: { resumableV2: { enabled: false } } }), {
+ status: 200,
+ })
+ )
+ )
+
+ await expect(
+ new GfsUploadJob({
+ file,
+ name: file.name,
+ target: { operation: 'create', parentRid: 'parent-disabled-v2' },
+ }).start()
+ ).rejects.toMatchObject({
+ name: 'GfsUploadCapabilityError',
+ allowLegacyFallback: true,
+ })
+ })
+
+ it('fails closed on an authenticated capability rejection instead of selecting legacy', async () => {
+ const file = new File([new Uint8Array([1])], 'capability-auth.bin')
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => new Response('{"error":"unauthorized"}', { status: 401 }))
+ )
+
+ await expect(
+ new GfsUploadJob({
+ file,
+ name: file.name,
+ target: { operation: 'create', parentRid: 'parent-capability-auth' },
+ }).start()
+ ).rejects.toMatchObject({
+ name: 'GfsUploadCapabilityError',
+ allowLegacyFallback: false,
+ })
+ })
+
it('reports the default compatibility limit when an enabled writer omits maxFileBytes', async () => {
const file = new File([new Uint8Array([1])], 'missing-limit.bin')
const compatibilityMaxFileBytes = normalizeUploadProductMaxBytes(undefined)
- const compatibilityLimit = `${compatibilityMaxFileBytes / (1024 * 1024)} MiB`
- Object.defineProperty(file, 'size', { value: compatibilityMaxFileBytes + 1 })
let createCalls = 0
vi.stubGlobal(
'fetch',
@@ -285,21 +371,30 @@ describe('GfsUploadJob', () => {
return new Response(JSON.stringify({ upload: { resumableV2: { enabled: true } } }), {
status: 200,
})
- if (method === 'POST') createCalls += 1
+ if (method === 'POST') {
+ createCalls += 1
+ return new Response(JSON.stringify({ error: 'session admission reached' }), {
+ status: 422,
+ headers: { 'Content-Type': 'application/json' },
+ })
+ }
return new Response(null, { status: 204 })
})
)
+ const compatibilityWarning = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
await expect(
new GfsUploadJob({
file,
name: file.name,
target: { operation: 'create', parentRid: 'parent-missing-limit' },
}).start()
- ).rejects.toThrow(
- `GFS uploads use the ${compatibilityLimit} compatibility limit because the writer omitted maxFileBytes.`
+ ).rejects.toThrow()
+ expect(compatibilityWarning).toHaveBeenCalledWith(
+ 'GFS Upload v2 writer omitted maxFileBytes; using the 209715200-byte compatibility limit.'
)
- expect(createCalls).toBe(0)
+ expect(createCalls).toBe(1)
+ expect(file.size).toBeLessThanOrEqual(compatibilityMaxFileBytes)
})
it.each([0, -1, 1.5, 1024 * 1024 * 1024 + 1, Number.MAX_SAFE_INTEGER + 1, '314572800', null])(
diff --git a/control-ui/lib/gfsFileUpload.ts b/control-ui/lib/gfsFileUpload.ts
index fcf1de5a0..d25eb5295 100644
--- a/control-ui/lib/gfsFileUpload.ts
+++ b/control-ui/lib/gfsFileUpload.ts
@@ -151,12 +151,35 @@ interface UploadCapabilities {
}
export class GfsUploadCapabilityError extends Error {
- constructor(message: string, options?: { cause?: unknown }) {
+ readonly allowLegacyFallback: boolean
+
+ constructor(message: string, options?: { cause?: unknown; allowLegacyFallback?: boolean }) {
super(message, options)
this.name = 'GfsUploadCapabilityError'
+ this.allowLegacyFallback = options?.allowLegacyFallback === true
}
}
+const LEGACY_FALLBACK_CAPABILITY_STATUSES = new Set([408, 404, 501, 502, 503, 504])
+
+export function allowsLegacyCapabilityFallback(error: unknown): boolean {
+ const status = statusOf(error)
+ if (status !== undefined) return LEGACY_FALLBACK_CAPABILITY_STATUSES.has(status)
+ if (!(error instanceof Error) || error.name === 'AbortError' || error instanceof SyntaxError)
+ return false
+ if (error.name === 'TimeoutError' || error instanceof TypeError) return true
+ const code = String(
+ (error as Error & { code?: unknown; cause?: { code?: unknown } }).cause?.code ||
+ (error as Error & { code?: unknown }).code ||
+ ''
+ )
+ return (
+ ['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT'].includes(
+ code
+ ) || /socket hang up|fetch failed|network error/i.test(error.message)
+ )
+}
+
function plainObject(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
}
@@ -236,15 +259,16 @@ function endpoint(path: string): string {
return `${API_BASE}${path}`
}
-function signalWithTimeout(
+export function signalWithTimeout(
signal: AbortSignal | undefined,
timeoutMs: number
): { signal: AbortSignal; cancel: () => void } {
const controller = new AbortController()
- const timer = window.setTimeout(
- () => controller.abort(new Error('GFS upload request timed out')),
- timeoutMs
- )
+ const timer = window.setTimeout(() => {
+ const timeout = new Error('GFS upload request timed out')
+ timeout.name = 'TimeoutError'
+ controller.abort(timeout)
+ }, timeoutMs)
const abort = () => controller.abort(signal?.reason)
signal?.addEventListener('abort', abort, { once: true })
return {
@@ -1155,13 +1179,17 @@ export class GfsUploadJob {
)
capabilityData = capabilities.data
} catch (error) {
+ const allowLegacyFallback = allowsLegacyCapabilityFallback(error)
throw new GfsUploadCapabilityError('Resumable GFS upload capabilities are unavailable.', {
cause: error,
+ allowLegacyFallback,
})
}
const upload = parseUploadCapabilities(capabilityData)
if (!upload.resumableV2?.enabled)
- throw new GfsUploadCapabilityError('Resumable GFS uploads are not enabled on this writer.')
+ throw new GfsUploadCapabilityError('Resumable GFS uploads are not enabled on this writer.', {
+ allowLegacyFallback: true,
+ })
return upload
}
@@ -1173,6 +1201,11 @@ export class GfsUploadJob {
const upload = await this.loadCapabilities()
const resumable = upload.resumableV2!
const productMaxFileBytes = normalizeUploadProductMaxBytes(resumable.maxFileBytes)
+ if (resumable.maxFileBytes === undefined) {
+ console.warn(
+ `GFS Upload v2 writer omitted maxFileBytes; using the ${GFS_FILE_UPLOAD_DEFAULT_PRODUCT_MAX_BYTES}-byte compatibility limit.`
+ )
+ }
const resumeId = this.session?.uploadId ?? this.input.resumeUploadId
if (resumeId) {
const { session, parts } = (
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index 314c50b2c..c6b258943 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.445",
+ "version": "0.1.446",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.445",
+ "version": "0.1.446",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/llm-providers": "file:../packages/llm-providers",
diff --git a/control-ui/package.json b/control-ui/package.json
index b26a1c932..73e7bf984 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.445",
+ "version": "0.1.446",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/desktop-app/src/__tests__/appService.gfs.test.ts b/desktop-app/src/__tests__/appService.gfs.test.ts
index 36421bb23..52576d0aa 100644
--- a/desktop-app/src/__tests__/appService.gfs.test.ts
+++ b/desktop-app/src/__tests__/appService.gfs.test.ts
@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { AppService, legacyEncodedFile, migrateDesktopGfsUploadState } from '../appService.js'
import { config, getActiveEnvKey } from '../config.js'
-import { DesktopUploadCapabilityError } from '../gfs/upload.js'
+import { DesktopUploadCapabilityError, normalizeUploadProductMaxBytes } from '../gfs/upload.js'
vi.mock('../chatStoreBinding.js', () => ({
bindChatStoreForUser: vi.fn(),
@@ -312,7 +312,9 @@ describe('AppService GFS upload security scope', () => {
await writeFile(filePath, Buffer.from('legacy payload'))
const service = authenticatedUploadService(join(root, 'gfs-upload-sessions.json'))
service.startDesktopGfsUpload.mockRejectedValue(
- new DesktopUploadCapabilityError('resumable uploads are disabled')
+ new DesktopUploadCapabilityError('resumable uploads are disabled', {
+ allowLegacyFallback: true,
+ })
)
service.gfsClient = {
createResource: vi.fn().mockResolvedValue({
@@ -354,6 +356,34 @@ describe('AppService GFS upload security scope', () => {
}
})
+ it('fails loudly without legacy fallback for malformed v2 capabilities', async () => {
+ const root = await mkdtemp(join(tmpdir(), 'evenfire-gfs-malformed-capability-'))
+ try {
+ const filePath = join(root, 'payload.bin')
+ await writeFile(filePath, Buffer.from('payload'))
+ const service = authenticatedUploadService(join(root, 'gfs-upload-sessions.json'))
+ let malformed: unknown
+ try {
+ normalizeUploadProductMaxBytes(0)
+ } catch (error) {
+ malformed = error
+ }
+ expect(malformed).toBeInstanceOf(DesktopUploadCapabilityError)
+ service.startDesktopGfsUpload.mockRejectedValue(malformed)
+ service.gfsClient = {
+ createResource: vi.fn(),
+ replaceFile: vi.fn(),
+ }
+
+ await expect(
+ service.startGfsFileUpload('parent-rid', 'payload.bin', filePath, 'main')
+ ).rejects.toBe(malformed)
+ expect(service.gfsClient.createResource).not.toHaveBeenCalled()
+ } finally {
+ await rm(root, { recursive: true, force: true })
+ }
+ })
+
it('rejects above the legacy limit before invoking the fallback request', async () => {
const root = await mkdtemp(join(tmpdir(), 'evenfire-gfs-legacy-limit-fallback-'))
try {
@@ -362,7 +392,9 @@ describe('AppService GFS upload security scope', () => {
await truncate(filePath, 16 * 1024 * 1024 + 1)
const service = authenticatedUploadService(join(root, 'gfs-upload-sessions.json'))
service.startDesktopGfsUpload.mockRejectedValue(
- new DesktopUploadCapabilityError('resumable uploads are disabled')
+ new DesktopUploadCapabilityError('resumable uploads are disabled', {
+ allowLegacyFallback: true,
+ })
)
service.gfsClient = {
createResource: vi.fn(),
@@ -386,7 +418,9 @@ describe('AppService GFS upload security scope', () => {
await writeFile(filePath, Buffer.from('resume payload'))
const service = authenticatedUploadService(join(root, 'gfs-upload-sessions.json'))
service.startDesktopGfsUpload.mockRejectedValue(
- new DesktopUploadCapabilityError('resumable uploads are disabled')
+ new DesktopUploadCapabilityError('resumable uploads are disabled', {
+ allowLegacyFallback: true,
+ })
)
service.gfsClient = {
createResource: vi.fn(),
@@ -410,7 +444,9 @@ describe('AppService GFS upload security scope', () => {
await writeFile(filePath, Buffer.from('replace payload'))
const service = authenticatedUploadService(join(root, 'gfs-upload-sessions.json'))
service.startDesktopGfsUpload.mockRejectedValue(
- new DesktopUploadCapabilityError('resumable uploads are disabled')
+ new DesktopUploadCapabilityError('resumable uploads are disabled', {
+ allowLegacyFallback: true,
+ })
)
service.gfsClient = {
createResource: vi.fn(),
diff --git a/desktop-app/src/appService.ts b/desktop-app/src/appService.ts
index 3a2483dc3..b221b8d33 100644
--- a/desktop-app/src/appService.ts
+++ b/desktop-app/src/appService.ts
@@ -2224,7 +2224,12 @@ export class AppService {
// A legacy fallback is valid only for a fresh upload. An explicit resume
// must remain a v2 operation so a missing capability cannot silently turn
// a persisted session into a second non-resumable resource.
- if (!(error instanceof DesktopUploadCapabilityError) || resumeUploadId) throw error
+ if (
+ !(error instanceof DesktopUploadCapabilityError) ||
+ !error.allowLegacyFallback ||
+ resumeUploadId
+ )
+ throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
@@ -2258,7 +2263,12 @@ export class AppService {
resumeUploadId,
})
} catch (error) {
- if (!(error instanceof DesktopUploadCapabilityError) || resumeUploadId) throw error
+ if (
+ !(error instanceof DesktopUploadCapabilityError) ||
+ !error.allowLegacyFallback ||
+ resumeUploadId
+ )
+ throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
@@ -2422,7 +2432,8 @@ export class AppService {
}
return await entry.promise
} catch (error) {
- if (!(error instanceof DesktopUploadCapabilityError)) throw error
+ if (!(error instanceof DesktopUploadCapabilityError) || !error.allowLegacyFallback)
+ throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
@@ -2467,7 +2478,8 @@ export class AppService {
}
return await entry.promise
} catch (error) {
- if (!(error instanceof DesktopUploadCapabilityError)) throw error
+ if (!(error instanceof DesktopUploadCapabilityError) || !error.allowLegacyFallback)
+ throw error
const resource = await this.runScopedLegacyGfsUpload(scope, async (token, signal) => {
const encodedData = await legacyEncodedFile(filePath)
this.assertCurrentDesktopGfsUploadScope(scope)
diff --git a/desktop-app/src/gfs/upload.test.ts b/desktop-app/src/gfs/upload.test.ts
index 0f2a41034..8625d9b90 100644
--- a/desktop-app/src/gfs/upload.test.ts
+++ b/desktop-app/src/gfs/upload.test.ts
@@ -1,10 +1,11 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
import { createHash } from 'node:crypto'
-import { mkdtemp, rm, truncate, writeFile } from 'node:fs/promises'
+import { mkdtemp, rm, stat, truncate, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import {
DesktopGfsUploadJob,
+ allowsLegacyCapabilityFallback,
isAmbiguousUploadStatus,
isRetryableUploadStatus,
normalizeInstabilityFailureThreshold,
@@ -25,6 +26,10 @@ function enabledCapabilities(overrides: Record<string, unknown> = {}) {
}
describe('desktop GFS indexed uploader', () => {
+ it('pins the missing-field compatibility default independently of the implementation', () => {
+ expect(normalizeUploadProductMaxBytes(undefined)).toBe(209_715_200)
+ })
+
it('uses the writer threshold and rejects invalid capability values', () => {
expect(normalizeInstabilityFailureThreshold(undefined)).toBe(3)
expect(normalizeInstabilityFailureThreshold(1)).toBe(1)
@@ -44,6 +49,24 @@ describe('desktop GFS indexed uploader', () => {
expect(isAmbiguousUploadStatus(507)).toBe(false)
})
+ it.each([
+ ['network failure', new TypeError('fetch failed'), true],
+ ['timeout', Object.assign(new Error('timed out'), { name: 'TimeoutError' }), true],
+ ['request timeout', Object.assign(new Error('timed out'), { status: 408 }), true],
+ ['unsupported endpoint', Object.assign(new Error('missing'), { status: 404 }), true],
+ ['not implemented', Object.assign(new Error('unsupported'), { status: 501 }), true],
+ ['gateway unavailable', Object.assign(new Error('unavailable'), { status: 503 }), true],
+ ['caller abort', Object.assign(new Error('aborted'), { name: 'AbortError' }), false],
+ ['malformed JSON', new SyntaxError('bad JSON'), false],
+ ['unauthorized', Object.assign(new Error('unauthorized'), { status: 401 }), false],
+ ['forbidden', Object.assign(new Error('forbidden'), { status: 403 }), false],
+ ['invalid request', Object.assign(new Error('invalid'), { status: 422 }), false],
+ ['writer failure', Object.assign(new Error('failed'), { status: 500 }), false],
+ ['unknown failure', new Error('unexpected'), false],
+ ])('classifies %s capability failures for legacy fallback', (_label, error, expected) => {
+ expect(allowsLegacyCapabilityFallback(error)).toBe(expected)
+ })
+
it('reaches writer admission for a 250 MiB file under a 300 MiB capability', async () => {
const root = await mkdtemp(join(tmpdir(), 'evenfire-gfs-upload-runtime-raise-'))
try {
@@ -125,26 +148,93 @@ describe('desktop GFS indexed uploader', () => {
}
})
+ it('marks a valid disabled-v2 response as eligible for bounded fresh legacy fallback', async () => {
+ const root = await mkdtemp(join(tmpdir(), 'evenfire-gfs-upload-v2-disabled-'))
+ try {
+ const filePath = join(root, 'payload.bin')
+ await writeFile(filePath, Buffer.from([1]))
+ const transport = {
+ async requestJson<T>() {
+ return { upload: { resumableV2: { enabled: false } } } as T
+ },
+ async requestPart() {
+ throw new Error('part request was not expected')
+ },
+ }
+
+ await expect(
+ new DesktopGfsUploadJob({
+ baseUrl: 'https://api.example',
+ token: 'token',
+ filePath,
+ name: 'payload.bin',
+ drive: 'main',
+ operation: 'create',
+ parentRid: 'parent-disabled-v2',
+ transport,
+ }).start()
+ ).rejects.toMatchObject({
+ name: 'DesktopUploadCapabilityError',
+ allowLegacyFallback: true,
+ })
+ } finally {
+ await rm(root, { recursive: true, force: true })
+ }
+ })
+
+ it('fails closed on an authenticated capability rejection instead of selecting legacy', async () => {
+ const root = await mkdtemp(join(tmpdir(), 'evenfire-gfs-upload-capability-auth-'))
+ try {
+ const filePath = join(root, 'payload.bin')
+ await writeFile(filePath, Buffer.from([1]))
+ const transport = {
+ async requestJson() {
+ throw Object.assign(new Error('unauthorized'), { status: 401 })
+ },
+ async requestPart() {
+ throw new Error('part request was not expected')
+ },
+ }
+
+ await expect(
+ new DesktopGfsUploadJob({
+ baseUrl: 'https://api.example',
+ token: 'token',
+ filePath,
+ name: 'payload.bin',
+ drive: 'main',
+ operation: 'create',
+ parentRid: 'parent-capability-auth',
+ transport,
+ }).start()
+ ).rejects.toMatchObject({
+ name: 'DesktopUploadCapabilityError',
+ allowLegacyFallback: false,
+ })
+ } finally {
+ await rm(root, { recursive: true, force: true })
+ }
+ })
+
it('reports the default compatibility limit when an enabled writer omits maxFileBytes', async () => {
const root = await mkdtemp(join(tmpdir(), 'evenfire-gfs-upload-missing-limit-'))
try {
const filePath = join(root, 'payload.bin')
const compatibilityMaxFileBytes = normalizeUploadProductMaxBytes(undefined)
- const compatibilityLimit = `${compatibilityMaxFileBytes / (1024 * 1024)} MiB`
- await writeFile(filePath, Buffer.alloc(0))
- await truncate(filePath, compatibilityMaxFileBytes + 1)
+ await writeFile(filePath, Buffer.from([1]))
let createCalls = 0
const transport = {
async requestJson<T>(method: 'GET' | 'POST') {
if (method === 'GET') return enabledCapabilities() as T
createCalls += 1
- throw new Error('unexpected session creation')
+ throw Object.assign(new Error('session admission reached'), { status: 422 })
},
async requestPart() {
throw new Error('part request was not expected')
},
}
+ const compatibilityWarning = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
await expect(
new DesktopGfsUploadJob({
baseUrl: 'https://api.example',
@@ -156,10 +246,12 @@ describe('desktop GFS indexed uploader', () => {
parentRid: 'parent-missing-limit',
transport,
}).start()
- ).rejects.toThrow(
- `GFS files are limited to the ${compatibilityLimit} compatibility limit because the writer omitted maxFileBytes`
+ ).rejects.toThrow('session admission reached')
+ expect(compatibilityWarning).toHaveBeenCalledWith(
+ 'GFS Upload v2 writer omitted maxFileBytes; using the 209715200-byte compatibility limit'
)
- expect(createCalls).toBe(0)
+ expect(createCalls).toBe(1)
+ expect((await stat(filePath)).size).toBeLessThanOrEqual(compatibilityMaxFileBytes)
} finally {
await rm(root, { recursive: true, force: true })
}
@@ -412,8 +504,8 @@ describe('desktop GFS indexed uploader', () => {
}).start()
).rejects.toMatchObject({
name: 'DesktopUploadCapabilityError',
- message: 'GFS resumable upload capabilities are unavailable',
- cause: expect.objectContaining({ message: expect.stringContaining(drift.cause) }),
+ message: expect.stringContaining(drift.cause),
+ allowLegacyFallback: false,
})
expect(sessionRequests).toBe(0)
}
diff --git a/desktop-app/src/gfs/upload.ts b/desktop-app/src/gfs/upload.ts
index 46b638c7d..bd42d2b4e 100644
--- a/desktop-app/src/gfs/upload.ts
+++ b/desktop-app/src/gfs/upload.ts
@@ -4,9 +4,9 @@ import { stat } from 'node:fs/promises'
import { type Readable, Transform } from 'node:stream'
const GFS_UPLOAD_V2_DEFAULT_PRODUCT_MAX_BYTES = 200 * 1024 * 1024
-const GFS_UPLOAD_V2_PROTOCOL_MAX_BYTES = 1024 * 1024 * 1024
+export const GFS_UPLOAD_V2_PROTOCOL_MAX_BYTES = 1024 * 1024 * 1024
const GFS_UPLOAD_V2_PREFERRED_PART_BYTES = 8 * 1024 * 1024
-const GFS_UPLOAD_V2_MAX_PART_BYTES = 16 * 1024 * 1024
+export const GFS_UPLOAD_V2_MAX_PART_BYTES = 16 * 1024 * 1024
const GFS_UPLOAD_V2_DEFAULT_CONCURRENCY = 4
const GFS_UPLOAD_V2_FALLBACK_CONCURRENCY = 2
const GFS_UPLOAD_V2_PART_TIMEOUT_MS = 5 * 60 * 1000
@@ -113,29 +113,63 @@ interface UploadCapabilities {
function parseUploadCapabilities(value: unknown): UploadCapabilities {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
- throw new Error('invalid GFS upload capabilities response: expected a plain JSON object')
+ throw new DesktopUploadCapabilityError(
+ 'invalid GFS upload capabilities response: expected a plain JSON object'
+ )
}
const upload = (value as { upload?: unknown }).upload
if (!upload || typeof upload !== 'object' || Array.isArray(upload)) {
- throw new Error('invalid GFS upload capabilities response: missing upload object')
+ throw new DesktopUploadCapabilityError(
+ 'invalid GFS upload capabilities response: missing upload object'
+ )
}
const resumableV2 = (upload as { resumableV2?: unknown }).resumableV2
if (!resumableV2 || typeof resumableV2 !== 'object' || Array.isArray(resumableV2)) {
- throw new Error('invalid GFS upload capabilities response: missing resumableV2 object')
+ throw new DesktopUploadCapabilityError(
+ 'invalid GFS upload capabilities response: missing resumableV2 object'
+ )
}
if (typeof (resumableV2 as { enabled?: unknown }).enabled !== 'boolean') {
- throw new Error('invalid GFS upload capabilities response: resumableV2.enabled must be boolean')
+ throw new DesktopUploadCapabilityError(
+ 'invalid GFS upload capabilities response: resumableV2.enabled must be boolean'
+ )
}
return value as UploadCapabilities
}
export class DesktopUploadCapabilityError extends Error {
- constructor(message: string, options?: { cause?: unknown }) {
+ readonly allowLegacyFallback: boolean
+
+ constructor(message: string, options?: { cause?: unknown; allowLegacyFallback?: boolean }) {
super(message, options)
this.name = 'DesktopUploadCapabilityError'
+ this.allowLegacyFallback = options?.allowLegacyFallback === true
}
}
+const LEGACY_FALLBACK_CAPABILITY_STATUSES = new Set([408, 404, 501, 502, 503, 504])
+
+export function allowsLegacyCapabilityFallback(error: unknown): boolean {
+ const status =
+ error && typeof error === 'object' && typeof (error as { status?: unknown }).status === 'number'
+ ? Number((error as { status: number }).status)
+ : undefined
+ if (status !== undefined) return LEGACY_FALLBACK_CAPABILITY_STATUSES.has(status)
+ if (!(error instanceof Error) || error.name === 'AbortError' || error instanceof SyntaxError)
+ return false
+ if (error.name === 'TimeoutError' || error instanceof TypeError) return true
+ const code = String(
+ (error as Error & { code?: unknown; cause?: { code?: unknown } }).cause?.code ||
+ (error as Error & { code?: unknown }).code ||
+ ''
+ )
+ return (
+ ['ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT'].includes(
+ code
+ ) || /socket hang up|fetch failed|network error/i.test(error.message)
+ )
+}
+
export function normalizeUploadProductMaxBytes(value: unknown): number {
if (value === undefined) return GFS_UPLOAD_V2_DEFAULT_PRODUCT_MAX_BYTES
if (
@@ -1342,39 +1376,46 @@ export class DesktopGfsUploadJob {
throw new Error('GFS files cannot exceed the 1 GiB Upload v2 protocol maximum')
}
this.totalBytes = file.size
- let capabilities: UploadCapabilities
+ let capabilityData: unknown
try {
this.assertAuthEpoch()
// GFSC capabilities are a plain JSON document. Only upload lifecycle
// receipts use the { ok, data, error } envelope; accepting an envelope
// here would hide drift between Desktop and the writer's public contract.
- capabilities = parseUploadCapabilities(
- await requestWithLifecycleRetries(
- this.input,
- () =>
- this.input.transport.requestJson<UploadCapabilities>(
- 'GET',
- joinUrl(this.input.baseUrl, uploadPath(drive, '/api/v1/me/gfs/capabilities')),
- {
- token: this.input.token,
- timeoutMs: UPLOAD_TIMEOUT_MS,
- signal: this.abortController.signal,
- }
- ),
- { signal: this.abortController.signal }
- )
+ capabilityData = await requestWithLifecycleRetries(
+ this.input,
+ () =>
+ this.input.transport.requestJson<UploadCapabilities>(
+ 'GET',
+ joinUrl(this.input.baseUrl, uploadPath(drive, '/api/v1/me/gfs/capabilities')),
+ {
+ token: this.input.token,
+ timeoutMs: UPLOAD_TIMEOUT_MS,
+ signal: this.abortController.signal,
+ }
+ ),
+ { signal: this.abortController.signal }
)
} catch (error) {
+ const allowLegacyFallback = allowsLegacyCapabilityFallback(error)
throw new DesktopUploadCapabilityError('GFS resumable upload capabilities are unavailable', {
cause: error,
+ allowLegacyFallback,
})
}
+ const capabilities = parseUploadCapabilities(capabilityData)
const resumable = capabilities.upload?.resumableV2
if (!resumable?.enabled)
throw new DesktopUploadCapabilityError(
- 'Resumable GFS uploads are not enabled on this writer.'
+ 'Resumable GFS uploads are not enabled on this writer.',
+ { allowLegacyFallback: true }
)
const productMaxFileBytes = normalizeUploadProductMaxBytes(resumable.maxFileBytes)
+ if (resumable.maxFileBytes === undefined) {
+ console.warn(
+ `GFS Upload v2 writer omitted maxFileBytes; using the ${GFS_UPLOAD_V2_DEFAULT_PRODUCT_MAX_BYTES}-byte compatibility limit`
+ )
+ }
this.input.advertisedConcurrency = resumable.maxConcurrentPartsPerSession
this.input.instabilityFailureThreshold = normalizeInstabilityFailureThreshold(
resumable.instabilityFailureThreshold