From cbe461ef2a5a089f977bba6b08363483d4675c30 Mon Sep 17 00:00:00 2001 From: Dylan Murphy Date: Wed, 18 Nov 2026 16:14:54 -0500 Subject: [PATCH 1/2] Remove deadlines from the JS contract The library never expires a request. expiresAt on a descriptor and lifetimeMs in configure() stay in the types, deprecated and ignored: mutate() and configure() accept any value and warn once per client in development. configure() no longer sends lifetimeMs. Every enqueue sends expiresAt 8640000000000000, because native in 11.3.0 rejects an entry without one. errorKind 'expired' is deprecated; an outcome an earlier version journaled still reaches onError. README, CHANGELOG, the codegen spec comments, the fake native docs and the example app's expiry steps now describe no deadlines. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 22 ++++ README.md | 50 ++++--- example/RNBGUExample/App.tsx | 2 +- example/RNBGUExample/README.md | 22 ++-- example/RNBGUExample/harness/uploads.ts | 5 +- src/NativeRNFileUploader.ts | 21 +-- src/__tests__/client.test.ts | 168 +++++++++++++++++------- src/__tests__/delivery.test.ts | 36 +++++ src/__tests__/registry.test.ts | 115 ++++++++++++---- src/__tests__/testing.test.ts | 48 ++++++- src/__typetests__/deadlines.ts | 49 +++++++ src/index.ts | 43 +++--- src/registry.ts | 41 +++--- src/testing.ts | 5 +- src/types.ts | 25 +++- 15 files changed, 499 insertions(+), 153 deletions(-) create mode 100644 src/__typetests__/deadlines.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 574795a4..b0f63723 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,25 @@ +## Unreleased + +The library has no deadlines. It never expires a request: it keeps an +entry, and retries it, until the retry rules settle it or the app calls +`cancel(id)`. An app that needs a bound calls `cancel(id)` itself. +`expiresAt` on a descriptor and `lifetimeMs` in `configure()` are +deprecated and ignored. They stay in the types, so code written for 11.3.0 +compiles and runs with no change, and they leave the types in the next +major release. `mutate()` and `configure()` no longer reject a value for +them that is not finite, zero or negative. In development, the first +`mutate()` whose descriptor sets `expiresAt`, and the first `configure()` +that sets `lifetimeMs`, warn one time per client (to `onWarning`, or +`console.warn` when none is set). +`configure()` no longer sends `lifetimeMs` to native. Every enqueue sends +`expiresAt: 8640000000000000` (the largest valid `Date`), because native in +11.3.0 and earlier rejects an entry without one. Entries queued by an +earlier version keep going. `errorKind: 'expired'` is deprecated: only an +outcome that an earlier version journaled, and that was not yet +acknowledged, carries it, and it still reaches `onError`. The fake native +module never expired an entry and still does not. This JS change ships in +the same release as the Android and iOS changes that remove expiry. + ## 11.3.0 Added `useRequests(filter?)` and `useRequestsWithProgress(filter?)`, React diff --git a/README.md b/README.md index 525c964f..739efd91 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,8 @@ export const addComment = uploads.define({ store.dispatch(commentsLoaded({ noteId, content })); }, onError: (error, vars, meta) => { - // error.errorKind: 'http' | 'network' | 'file' | 'expired' | 'truncated' | 'unknown' + // error.errorKind: 'http' | 'network' | 'file' | 'truncated' | 'unknown' + // ('expired' only from an earlier version; see "No deadlines") }, }); @@ -137,7 +138,7 @@ TypeScript does not flag a misspelled key on an inferred arrow return. | `file` | Whole file body. Copied. Moved when `parts` is set. | | `parts` | Chunked over `file`: `[{ url, headers?, range: { start, end } }]`, bytes, end exclusive, tiling the file from 0. | | `accept` | Non-2xx responses to treat as success: `[{ status, bodyIncludes? }]`. | -| `expiresAt` | Epoch ms. Default now + `lifetimeMs` (14 days). Past it: `error` with `errorKind: 'expired'`. | +| `expiresAt` | Deprecated. Ignored: the library has no deadlines. See "No deadlines" under "Reliable delivery". | | `retry` | Per-request override of the `configure()` retry defaults: `backoff`, `terminalHttp.exempt`, and `transient` rules. See "Reliable delivery". | | `wifiOnly` | `true` waits for Wi-Fi before each attempt; `false` never waits. Overrides `setWifiOnly()` for this entry. Omit it to follow `setWifiOnly()`, including later toggles. | | `priority` | `'high'` or `'normal'` (default). On Android at most 4 requests transmit at once, and one of those slots is kept for `'high'`. Normal requests can use only the other 3, so a high-priority request, such as a small JSON POST that creates a session, gets a slot without waiting behind a backlog of file parts. It can still wait when other high-priority requests hold every slot. iOS ignores it for now. | @@ -190,12 +191,11 @@ Nothing else deletes them. different `url` or `method` counts as a different body. `mutate()` with an id that exists: -- Same body: resume. New headers, `expiresAt`, and `vars` replace the stored - ones. +- Same body: resume. New headers and `vars` replace the stored ones. - Different body (`data`, `form`, `file`, or `parts`) and the entry is not running (queued, paused, awaiting-auth, or settled): the descriptor, staged - body, `vars`, headers, and `expiresAt` are replaced and the entry reopens. - It settles once more. + body, `vars`, and headers are replaced and the entry reopens. It settles + once more. - Different body, entry running: `mutate()` rejects with `E_RUNNING`. - A cancelled entry whose outcome is not yet acknowledged: a fresh generation. The old outcome's ack forgets the entry only when the @@ -286,6 +286,21 @@ while the app was dead from being sent twice. # Reliable delivery +**No deadlines.** The library never expires a request. It keeps an entry, +and retries it, until the retry rules below settle it or the app calls +`cancel(id)`. + +- `expiresAt` on a descriptor and `lifetimeMs` in `configure()` are + deprecated and do nothing. `mutate()` and `configure()` accept any value + for them, and in development the first call that sets one logs a warning. + They leave the types in the next major release. +- An app that needs a bound keeps its own clock and calls `cancel(id)`. +- Entries queued by an earlier version keep going. The deadline they stored + is ignored too. +- An outcome with `errorKind: 'expired'` that an earlier version journaled, + and that was not yet acknowledged, still reaches `onError` after the + upgrade. The library produces no new `expired` outcomes. + 1. **Write-ahead.** Entry, descriptor, and staged body persist before any attempt. `mutate()` resolves after the row and every staged body copy are durably on disk (temp file, rename, then a sync of the directory), so the @@ -309,9 +324,8 @@ while the app was dead from being sent twice. never gives up on its own; the app decides a poison policy from that number. 3. **One outcome per settle cycle.** `pause()` produces none, for the whole - queue or for a set of keys. A paused entry past `expiresAt` settles - `error` with `errorKind: 'expired'` when it is resumed. A same-id - `mutate()` on a settled entry reopens it, and it settles once more. + queue or for a set of keys. A same-id `mutate()` on a settled entry + reopens it, and it settles once more. 4. **Never before `mutate()` resolves.** Delivery for an id waits for the caller's promise. While native has not answered `enqueue`, the id's outcomes wait too. They stay journaled and unacknowledged, so none is @@ -331,7 +345,7 @@ while the app was dead from being sent twice. ack, a `completed` or `cancelled` entry leaves `getRequests()` without a `state` event, and an `error` entry stays with its `error` row. 7. **Completed entries are forgotten after ack.** Row and bytes go. An `error` - or `expired` entry keeps both until `cancel()` or a same-id `mutate()`. + entry keeps both until `cancel()` or a same-id `mutate()`. 8. **Ordering holds per id only.** The outcomes of one id are delivered in order. One exception: when one id has held outcomes under two keys, the key defined first delivers first (rule 5). There is no ordering guarantee @@ -343,13 +357,12 @@ Retry classes: | Attempt outcome | Action | | --- | --- | | 2xx, or an `accept` rule matches | settle `completed` | -| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2) until `expiresAt` | +| network failure, 5xx, 408, 429 | exponential backoff (base 1 s, max 2 h, jitter 0.2), with no limit on attempts or time | | 401, 403 | park as `awaiting-auth`; resume on `updateHeaders()` | | other 4xx matching a `retry.transient` rule (`status`, optional `bodyIncludes`), under the rule's `maxRetries` | as transient. The first matching rule in the list wins. `maxRetries: 3` retries three matching responses; the fourth settles. No `maxRetries` means no cap. See "Transient rule counts" below. A rule for 401, 403, 408 or 429 is rejected at the call | | other 4xx in `retry.terminalHttp.exempt` (default `[404]`), when no rule matched | as transient, with no cap | | other 4xx, or a rule past its `maxRetries` | settle `error` with `errorKind: 'http'`, response attached | | payload missing on disk | settle `error` with `errorKind: 'file'` | -| `expiresAt` passed | settle `error` with `errorKind: 'expired'`; bytes kept | | response body over 1 MB with a `response` parser | `onError` with `errorKind: 'truncated'`; the entry is `completed` | **Transient rule counts.** The library counts the responses each rule @@ -422,8 +435,7 @@ live, so its first delivery, at the boot replay, is 1. ### `mutate(vars, { id? }): Promise<{ id }>` Runs `request(vars)` once, merges `configure().headers()` under the -descriptor's headers, validates the descriptor, defaults `expiresAt`, and -persists the entry. Resolves with the id after the row and every staged body +descriptor's headers, validates the descriptor, and persists the entry. Resolves with the id after the row and every staged body copy are on disk. Rejects on a malformed descriptor, an unknown descriptor field, a GET with a body, input native cannot send (`E_INVALID`), a missing file (`E_FILE_MISSING`), a storage failure (`E_STORAGE`), a running entry @@ -444,7 +456,7 @@ reached its key before it; see rule 5 of "Reliable delivery". | Option | Notes | | --- | --- | | `definitions` | Optional. Every definition, as `define()` returned it. Listing a handle imports its module, so its `define()` runs before replay starts. In development, a later `define()` of a key that is not listed logs a warning. That key still receives its outcomes, and `mutate()` works for it. Throws when it is not an array of handles. | -| `lifetimeMs` | Default `expiresAt` distance. Default 14 days. | +| `lifetimeMs` | Deprecated. Ignored: the library has no deadlines. See "No deadlines" under "Reliable delivery". | | `maxVarsBytes` | Cap on the JSON length of `vars`. Default 1 MB. `mutate()` rejects above it. JS-side only. | | `retry` | `{ backoff?: { baseMs, maxMs, jitter }, terminalHttp?: { exempt }, transient?: Array<{ status, bodyIncludes?, maxRetries? }> }`. Each object is optional, but one you give must be complete. Defaults 1 s, 2 h, 0.2, `[404]`, `[]`. A descriptor's `retry` replaces each field it names. | | `headers` | `() => Record`, called at `mutate()`. The descriptor merges over it. | @@ -471,8 +483,7 @@ await Upload.resume({ keys: ['capture.upload'] }); // captures run Both states are persisted natively. Each entry that moves emits one `state` event (`paused`, then `queued`). No outcome is produced and the bytes are -kept. A paused entry past `expiresAt` settles `error` with -`errorKind: 'expired'` when it is resumed. +kept. A paused entry waits with no time limit. Neither call rejects because the settings cannot be saved. On Android, either call can still reject `E_STORAGE` when an entry file cannot be saved. @@ -899,7 +910,10 @@ behind a held one, as they do on a device. On release they all run in order, as usual, and a failure that `failNext()` queued goes to the first call that runs. `reset()` drops held calls and the calls behind them. `seedUnacknowledged()` and `seedRows()` model a journal and rows left by a dead session, so `configure()` replays -them. `seedDiagnostics()` adds records for `takeDiagnostics()`, and +them. Like native, the fake never expires an entry. To test the `expired` +outcome an earlier version may have journaled, seed one: +`native.seedUnacknowledged([native.buildSettled(id, { kind: 'error', error: { errorKind: 'expired' } })])`. +`seedDiagnostics()` adds records for `takeDiagnostics()`, and `seedBootSnapshot({ v9Leftovers: { unownedUploads: 2 } })` adds a boot record with those counts, the others 0 and no ids. diff --git a/example/RNBGUExample/App.tsx b/example/RNBGUExample/App.tsx index 9a954cfd..30444443 100644 --- a/example/RNBGUExample/App.tsx +++ b/example/RNBGUExample/App.tsx @@ -320,7 +320,7 @@ const App = () => { onChangeText={setCustomId} /> ; // Removes journaled outcomes by eventId. Resolves void. Idempotent; unknown // ids are ignored. An acknowledged 'completed' is the one moment native diff --git a/src/__tests__/client.test.ts b/src/__tests__/client.test.ts index df173d80..6914e80a 100644 --- a/src/__tests__/client.test.ts +++ b/src/__tests__/client.test.ts @@ -152,26 +152,93 @@ describe('client shape', () => { }); describe('configure', () => { - it('forwards lifetimeMs, retry and the flattened android config', () => { + it('forwards retry and the flattened android config, and not lifetimeMs', () => { const client = createUploadClient(); const retry = { terminalHttp: { exempt: [] } }; + const warn = jest.spyOn(console, 'warn').mockImplementation(() => {}); client.configure({ lifetimeMs: 1000, retry, headers: () => ({}), android: { notificationTitle: 'Backing up', notificationChannel: 'ch' }, }); + warn.mockRestore(); expect(native.configure).toHaveBeenCalledWith({ - lifetimeMs: 1000, retry, notificationTitle: 'Backing up', notificationChannel: 'ch', }); }); + describe('lifetimeMs (deprecated, ignored)', () => { + let consoleWarn: jest.SpyInstance; + beforeEach(() => { + consoleWarn = jest.spyOn(console, 'warn').mockImplementation(() => {}); + }); + afterEach(() => consoleWarn.mockRestore()); + + // An ignored value must never be the reason a call is refused. + it.each([0, -1, NaN, Infinity, 1000, 'long'])( + 'accepts lifetimeMs %p and applies the rest of the call', + (lifetimeMs) => { + const client = createUploadClient(); + expect(() => + client.configure({ + lifetimeMs: lifetimeMs as number, + retry: { terminalHttp: { exempt: [] } }, + }), + ).not.toThrow(); + expect(native.configure).toHaveBeenCalledWith({ + retry: { terminalHttp: { exempt: [] } }, + }); + expect(native.getUnacknowledgedEvents).toHaveBeenCalledTimes(1); + }, + ); + + it('does not change the expiresAt that mutate() sends', async () => { + const client = createUploadClient(); + client.configure({ lifetimeMs: 1000 }); + const send = client.define({ + key: 'k', + request: (_v: null) => ({ url: 'https://x', data: 1 }), + }); + await send.mutate(null); + expect(native.enqueue.mock.calls[0][0].descriptor.expiresAt).toBe( + 8_640_000_000_000_000, + ); + }); + + it('warns one time per client, in development, through onWarning', () => { + const onWarning = jest.fn(); + const client = createUploadClient(); + client.configure({ onWarning }); + expect(onWarning).not.toHaveBeenCalled(); + client.configure({ lifetimeMs: 1000, onWarning }); + client.configure({ lifetimeMs: 2000, onWarning }); + expect(onWarning.mock.calls).toEqual([ + [ + 'configure: lifetimeMs is deprecated and ignored: the library has no deadlines. To bound a request, call cancel(id). It leaves the types in the next major release.', + ], + ]); + expect(consoleWarn).not.toHaveBeenCalled(); + }); + + it('does not warn outside development', () => { + const global = globalThis as { __DEV__?: boolean }; + global.__DEV__ = false; + try { + const onWarning = jest.fn(); + createUploadClient().configure({ lifetimeMs: 1000, onWarning }); + expect(onWarning).not.toHaveBeenCalled(); + } finally { + delete global.__DEV__; + } + }); + }); + it('validates retry the way mutate() does, naming configure', async () => { const client = createUploadClient(); - client.configure({ lifetimeMs: 1000 }); + client.configure({ headers: () => ({ A: '1' }) }); native.configure.mockClear(); expect(() => client.configure({ retry: { transient: [{ status: 500 }] } }), @@ -182,17 +249,15 @@ describe('configure', () => { client.configure({ retry: { terminalHttp: { exmpt: [] } } } as never), ).toThrow(/^configure: unknown retry\.terminalHttp field "exmpt"/); expect(native.configure).not.toHaveBeenCalled(); - // A rejected call leaves the earlier configuration whole: the 1 s - // lifetime from the first call still sets expiresAt. + // A rejected call leaves the earlier configuration whole: the headers + // provider from the first call still applies. const d = client.define({ key: 'k', request: (_v: null) => ({ url: 'https://x', data: 1 }), }); - const before = Date.now(); await d.mutate(null); const entry = native.enqueue.mock.calls[0][0]; - expect(entry.descriptor.expiresAt).toBeGreaterThanOrEqual(before + 1000); - expect(entry.descriptor.expiresAt).toBeLessThan(before + 1000 + 5000); + expect(entry.descriptor.headers).toEqual({ A: '1' }); const retry = { transient: [{ status: 404, maxRetries: 48 }] }; client.configure({ retry }); expect(native.configure).toHaveBeenCalledWith( @@ -206,49 +271,39 @@ describe('configure', () => { key: 'k', request: (_v: { s: string }) => ({ url: 'https://x', data: 1 }), }); - client.configure({ lifetimeMs: 1000, maxVarsBytes: 16 }); + client.configure({ headers: () => ({ A: '1' }), maxVarsBytes: 16 }); native.configure.mockClear(); expect(() => - client.configure({ lifetimeMs: 5, enqueueTimeoutMs: 0 }), + client.configure({ headers: () => ({ B: '2' }), enqueueTimeoutMs: 0 }), ).toThrow(/enqueueTimeoutMs/); expect(() => client.configure({ - lifetimeMs: 5, + headers: () => ({ B: '2' }), maxVarsBytes: 64, enqueueTimeoutMs: 5, retry: 7 as never, }), ).toThrow(/^configure: /); expect(() => - client.configure({ lifetimeMs: 5, enqueueTimeoutMs: 5, maxVarsBytes: 0 }), + client.configure({ + headers: () => ({ B: '2' }), + enqueueTimeoutMs: 5, + maxVarsBytes: 0, + }), ).toThrow(/maxVarsBytes/); expect(native.configure).not.toHaveBeenCalled(); - // The first call's lifetime and vars cap still apply. - const before = Date.now(); + // The first call's headers provider and vars cap still apply. await send.mutate({ s: 'a'.repeat(8) }); const entry = native.enqueue.mock.calls.at(-1)![0]; - expect(entry.descriptor.expiresAt).toBeGreaterThanOrEqual(before + 1000); - expect(entry.descriptor.expiresAt).toBeLessThan(before + 1000 + 5000); + expect(entry.descriptor.headers).toEqual({ A: '1' }); await expect(send.mutate({ s: 'a'.repeat(9) })).rejects.toThrow( /is 17 bytes; the limit is 16/, ); }); - it('sends the 14 day default lifetime and no retry when neither is given', () => { + it('sends an empty object when no option is given', () => { createUploadClient().configure({}); - expect(native.configure).toHaveBeenCalledWith({ - lifetimeMs: 14 * 24 * 60 * 60 * 1000, - }); - expect(native.configure.mock.calls[0][0]).not.toHaveProperty('retry'); - }); - - it('rejects a non-positive lifetime', () => { - expect(() => createUploadClient().configure({ lifetimeMs: 0 })).toThrow( - /lifetimeMs/, - ); - expect(() => createUploadClient().configure({ lifetimeMs: NaN })).toThrow( - /lifetimeMs/, - ); + expect(native.configure).toHaveBeenCalledWith({}); }); it('rejects a non-positive maxVarsBytes and keeps it on the JS side', () => { @@ -271,13 +326,11 @@ describe('configure', () => { request: (_v: { s: string }) => ({ url: 'https://x', data: 1 }), }); client.configure({ - lifetimeMs: 1000, maxVarsBytes: 16, headers: () => ({ A: '1' }), }); expect(() => client.configure({ - lifetimeMs: 2000, enqueueTimeoutMs: 50, maxVarsBytes: 64, headers: () => ({ B: '2' }), @@ -285,12 +338,9 @@ describe('configure', () => { }), ).toThrow(/onWarning/); expect(native.configure).toHaveBeenCalledTimes(1); - const before = Date.now(); await send.mutate({ s: 'a'.repeat(8) }); const entry = native.enqueue.mock.calls.at(-1)![0]; expect(entry.descriptor.headers).toEqual({ A: '1' }); - expect(entry.descriptor.expiresAt).toBeGreaterThanOrEqual(before + 1000); - expect(entry.descriptor.expiresAt).toBeLessThan(before + 2000); await expect(send.mutate({ s: 'a'.repeat(9) })).rejects.toThrow( /the limit is 16/, ); @@ -312,7 +362,7 @@ describe('configure', () => { it('starts replay once; a second call updates settings without replaying', async () => { const client = createUploadClient(); client.configure({}); - client.configure({ lifetimeMs: 5 }); + client.configure({ maxVarsBytes: 5 }); await flush(); expect(native.getUnacknowledgedEvents).toHaveBeenCalledTimes(1); expect(native.onSettled).toHaveBeenCalledTimes(1); @@ -326,7 +376,7 @@ describe('configure', () => { expect(native.onSettled).not.toHaveBeenCalled(); }); - it('applies the headers provider and lifetime to later mutates', async () => { + it('applies the headers provider to later mutates', async () => { const client = createUploadClient(); const send = client.define({ key: 'k', @@ -336,13 +386,10 @@ describe('configure', () => { headers: { B: '2' }, }), }); - client.configure({ lifetimeMs: 1000, headers: () => ({ A: '1' }) }); - const before = Date.now(); + client.configure({ headers: () => ({ A: '1' }) }); await send.mutate(null); const entry = native.enqueue.mock.calls.at(-1)![0]; expect(entry.descriptor.headers).toEqual({ A: '1', B: '2' }); - expect(entry.descriptor.expiresAt).toBeGreaterThanOrEqual(before + 1000); - expect(entry.descriptor.expiresAt).toBeLessThan(before + 1000 + 5000); }); }); @@ -662,7 +709,7 @@ describe('end to end', () => { url: 'https://x/3', dataJson: '{"n":3}', headers: { Authorization: 'Bearer t' }, - expiresAt: expect.any(Number), + expiresAt: 8_640_000_000_000_000, }, }); fire('settled', { @@ -934,7 +981,7 @@ describe('with a fake native', () => { method: 'PUT', data: { n: 3, note: null }, headers: { Authorization: 'Bearer t' }, - expiresAt: expect.any(Number), + expiresAt: 8_640_000_000_000_000, }, raw: expect.objectContaining({ varsJson: '{"n":3}' }), }, @@ -996,6 +1043,34 @@ describe('with a fake native', () => { expect.objectContaining({ state: 'error' }), ]); }); + + it('replays an expired outcome that an earlier version journaled to onError', async () => { + const fake = createFakeNative(); + const client = createUploadClient({ native: fake }); + const onError = jest.fn(); + const send = client.define({ + key: 'item.send', + request: (_v: null) => ({ url: 'https://x' }), + onError, + }); + const { id } = await send.mutate(); + const event = fake.buildSettled(id, { + kind: 'error', + error: { errorKind: 'expired' }, + }); + fake.seedUnacknowledged([{ ...event, deliveries: 0 }]); + + client.configure({}); + await flush(); + + expect(onError).toHaveBeenCalledTimes(1); + expect(onError).toHaveBeenCalledWith( + { errorKind: 'expired', message: 'expired' }, + null, + expect.objectContaining({ id, deliveries: 1 }), + ); + expect(fake.ackedEventIds).toEqual([event.eventId]); + }); }); describe('a definition that arrives after configure()', () => { @@ -1142,11 +1217,14 @@ describe('a definition that arrives after configure()', () => { const send = client.define({ key: 'item.send', request, onSuccess }); const ping = client.define({ key: 'ping', request }); - client.configure({ definitions: [send, ping], lifetimeMs: 1000 }); + client.configure({ + definitions: [send, ping], + android: { notificationTitle: 'Up' }, + }); await acked; expect(onSuccess).toHaveBeenCalledTimes(1); // The list stays on the JS side. - expect(fake.calls.configure).toEqual([{ lifetimeMs: 1000 }]); + expect(fake.calls.configure).toEqual([{ notificationTitle: 'Up' }]); // A hot reload of a listed key replaces it without the list warning. client.define({ key: 'ping', request }); diff --git a/src/__tests__/delivery.test.ts b/src/__tests__/delivery.test.ts index 0e7d78ae..4b9fa45f 100644 --- a/src/__tests__/delivery.test.ts +++ b/src/__tests__/delivery.test.ts @@ -867,6 +867,42 @@ describe('error', () => { expect(onSuccess).not.toHaveBeenCalled(); expect(native.ackEvents).toHaveBeenCalledWith(['e1']); }); + + // The library no longer expires a request, but an outcome that an earlier + // version journaled and JS did not acknowledge still replays after the + // upgrade. It reaches onError as before. + it('replays an expired outcome journaled by an earlier version to onError, then acks', async () => { + const onError = jest.fn(); + const onSuccess = jest.fn(); + const error = { + errorKind: 'expired' as const, + message: 'expiresAt passed before the request completed', + }; + const { start, native, stateEvents } = setup( + { k: { key: 'k', request: jest.fn(), onError, onSuccess } }, + [ + completed({ + eventId: 'old', + kind: 'error', + state: 'error', + response: undefined, + error, + deliveries: 0, + }), + ], + ); + start(); + await flush(); + expect(onError).toHaveBeenCalledTimes(1); + expect(onError).toHaveBeenCalledWith( + error, + { n: 1 }, + expect.objectContaining({ id: 'u1', key: 'k' }), + ); + expect(onSuccess).not.toHaveBeenCalled(); + expect(stateEvents).toEqual([]); + expect(native.ackEvents).toHaveBeenCalledWith(['old']); + }); }); describe('cancelled', () => { diff --git a/src/__tests__/registry.test.ts b/src/__tests__/registry.test.ts index fb6b748b..cf22722c 100644 --- a/src/__tests__/registry.test.ts +++ b/src/__tests__/registry.test.ts @@ -1,6 +1,5 @@ import { createRegistry, - DEFAULT_LIFETIME_MS, MAX_VARS_BYTES, utf8ByteLength, uuidV4, @@ -9,7 +8,9 @@ import { type Settings, } from '../registry'; -const NOW = 1_700_000_000_000; +// The expiresAt that every enqueue sends: the largest valid Date. Native on +// 11.3.0 and earlier requires a number there, and never reaches this one. +const NO_DEADLINE = 8_640_000_000_000_000; const setup = (settings: Partial = {}) => { const enqueue = jest.fn(async (entry: EnqueueEntry) => entry.id); @@ -17,7 +18,6 @@ const setup = (settings: Partial = {}) => { const trackMutate = jest.fn(); const warn = jest.fn(); const current: Settings = { - lifetimeMs: DEFAULT_LIFETIME_MS, enqueueTimeoutMs: 10_000, maxVarsBytes: MAX_VARS_BYTES, ...settings, @@ -28,7 +28,6 @@ const setup = (settings: Partial = {}) => { getSettings: () => current, trackMutate, warn, - now: () => NOW, }); const lastEntry = (): EnqueueEntry => enqueue.mock.calls.at(-1)![0]; return { ...registry, enqueue, definitions, trackMutate, warn, lastEntry }; @@ -443,12 +442,20 @@ describe('mutate', () => { ).rejects.toThrow(/method must be one of/); }); - it.each([NaN, Infinity, 0, -5])( - 'rejects expiresAt %p', + // expiresAt is deprecated and ignored. An ignored value must never be + // the reason a request is refused. + it.each([NaN, Infinity, 0, -5, 42, 'soon', null])( + 'accepts expiresAt %p and sends the no-deadline value', async (expiresAt) => { - await expect( - mutateWith({ url: 'https://x', data: {}, expiresAt }).promise, - ).rejects.toThrow(/expiresAt/); + const { promise, enqueue } = mutateWith({ + url: 'https://x', + data: {}, + expiresAt, + }); + await expect(promise).resolves.toBeDefined(); + expect(enqueue.mock.calls[0]![0].descriptor.expiresAt).toBe( + NO_DEADLINE, + ); }, ); @@ -843,30 +850,18 @@ describe('mutate', () => { }); }); - describe('expiresAt', () => { - it('defaults to now + lifetimeMs', async () => { - const { define, lastEntry } = setup({ lifetimeMs: 1000 }); - const send = define({ - key: 'k', - request: (_vars: null) => ({ url: 'https://x', data: {} }), - }); - await send.mutate(null); - expect(lastEntry().descriptor.expiresAt).toBe(NOW + 1000); - }); - - it('defaults the lifetime to 14 days', async () => { + describe('expiresAt (deprecated, ignored)', () => { + it('sends the no-deadline value when the descriptor sets none', async () => { const { define, lastEntry } = setup(); const send = define({ key: 'k', request: (_vars: null) => ({ url: 'https://x', data: {} }), }); await send.mutate(null); - expect(lastEntry().descriptor.expiresAt).toBe( - NOW + 14 * 24 * 60 * 60 * 1000, - ); + expect(lastEntry().descriptor.expiresAt).toBe(NO_DEADLINE); }); - it('keeps an explicit expiresAt', async () => { + it("ignores the descriptor's expiresAt", async () => { const { define, lastEntry } = setup(); const send = define({ key: 'k', @@ -877,7 +872,75 @@ describe('mutate', () => { }), }); await send.mutate(null); - expect(lastEntry().descriptor.expiresAt).toBe(42); + expect(lastEntry().descriptor.expiresAt).toBe(NO_DEADLINE); + }); + + it('sends the same entry for a same-id mutate whatever expiresAt it sets', async () => { + const { define, enqueue } = setup(); + let expiresAt: number | undefined = 1; + const send = define({ + key: 'k', + request: (_vars: null) => ({ url: 'https://x', data: {}, expiresAt }), + }); + await send.mutate(null, { id: 'same' }); + expiresAt = 2; + await send.mutate(null, { id: 'same' }); + expiresAt = undefined; + await send.mutate(null, { id: 'same' }); + const [first, ...rest] = enqueue.mock.calls.map(([entry]) => entry); + rest.forEach((entry) => expect(entry).toEqual(first)); + expect(rest).toHaveLength(2); + }); + + it('warns one time per client, in development, when a descriptor sets it', async () => { + const { define, warn } = setup(); + const plain = define({ + key: 'plain', + request: (_vars: null) => ({ url: 'https://x', data: {} }), + }); + await plain.mutate(null); + expect(warn).not.toHaveBeenCalled(); + const timed = (key: string) => + define({ + key, + request: (_vars: null) => ({ + url: 'https://x', + data: {}, + expiresAt: 42, + }), + }); + await timed('a').mutate(null); + await timed('a').mutate(null); + await timed('b').mutate(null); + // The duplicate-key warning of the second define('a') is the other one. + const deprecations = warn.mock.calls.filter(([m]) => + /expiresAt/.test(m), + ); + expect(deprecations).toEqual([ + [ + 'mutate: the descriptor of "a" sets expiresAt. expiresAt is deprecated and ignored: the library has no deadlines. To bound a request, call cancel(id). It leaves the types in the next major release.', + ], + ]); + }); + + it('does not warn outside development', async () => { + const global = globalThis as { __DEV__?: boolean }; + global.__DEV__ = false; + try { + const { define, warn, lastEntry } = setup(); + await define({ + key: 'k', + request: (_vars: null) => ({ + url: 'https://x', + data: {}, + expiresAt: 42, + }), + }).mutate(null); + expect(warn).not.toHaveBeenCalled(); + expect(lastEntry().descriptor.expiresAt).toBe(NO_DEADLINE); + } finally { + delete global.__DEV__; + } }); }); }); diff --git a/src/__tests__/testing.test.ts b/src/__tests__/testing.test.ts index 8f19ca58..9add1f05 100644 --- a/src/__tests__/testing.test.ts +++ b/src/__tests__/testing.test.ts @@ -101,11 +101,11 @@ describe('enqueue', () => { describe('queue controls', () => { it('records configure, setWifiOnly and updateHeaders', async () => { const fake = createFakeNative(); - fake.configure({ lifetimeMs: 5 }); + fake.configure({ notificationTitle: 'Up' }); await fake.setWifiOnly(true); await fake.updateHeaders({ Authorization: 'Bearer u' }); expect(fake.calls).toMatchObject({ - configure: [{ lifetimeMs: 5 }], + configure: [{ notificationTitle: 'Up' }], setWifiOnly: [true], updateHeaders: [{ Authorization: 'Bearer u' }], }); @@ -251,6 +251,50 @@ describe('queue controls', () => { }); }); +describe('no deadlines', () => { + it('never expires an entry, whatever expiresAt it carries', async () => { + jest.useFakeTimers({ now: 1_000 }); + try { + const fake = createFakeNative(); + const settled: unknown[] = []; + fake.onSettled((e) => { + settled.push(e); + }); + await fake.enqueue(entry({ id: 'past' })); + await fake.pause({}); + jest.advanceTimersByTime(30 * 24 * 60 * 60 * 1000); + await fake.resume({}); + jest.advanceTimersByTime(30 * 24 * 60 * 60 * 1000); + expect(fake.getRequests()).toEqual([ + expect.objectContaining({ id: 'past', state: 'queued' }), + ]); + expect(settled).toEqual([]); + await expect(fake.getUnacknowledgedEvents()).resolves.toEqual([]); + } finally { + jest.useRealTimers(); + } + }); + + it('stores an expired outcome from an earlier version for replay', async () => { + const fake = createFakeNative(); + await fake.enqueue(entry({ id: 'old' })); + const event = fake.buildSettled('old', { + kind: 'error', + error: { errorKind: 'expired' }, + }); + fake.seedUnacknowledged([{ ...event, deliveries: 0 }]); + await expect(fake.getUnacknowledgedEvents()).resolves.toEqual([ + expect.objectContaining({ + eventId: event.eventId, + id: 'old', + kind: 'error', + error: { errorKind: 'expired', message: 'expired' }, + deliveries: 1, + }), + ]); + }); +}); + describe('takeDiagnostics', () => { it('returns seeded records once, then an empty list', async () => { const fake = createFakeNative(); diff --git a/src/__typetests__/deadlines.ts b/src/__typetests__/deadlines.ts new file mode 100644 index 00000000..1d6f9cfc --- /dev/null +++ b/src/__typetests__/deadlines.ts @@ -0,0 +1,49 @@ +// Type-level tests for the fields the library no longer uses. tsc compiles +// this file (yarn typecheck); nothing here runs. The library has no +// deadlines, but these stay in the types until the next major release, so +// an app written for 11.3.0 compiles with no change. +import type { + ConfigureOptions, + ErrorKind, + OutcomeError, + RequestDescriptor, +} from '../types'; + +type Equal = (() => T extends A ? 1 : 2) extends () => T extends B + ? 1 + : 2 + ? true + : false; +const assertEqual = ( + _proof: Equal extends true ? true : never, +) => {}; + +// A descriptor that sets expiresAt still compiles. The value is ignored. +export const timed: RequestDescriptor = { + url: 'https://api/x', + data: {}, + expiresAt: Date.now() + 60_000, +}; + +// configure() with lifetimeMs still compiles. The value is ignored. +export const options: ConfigureOptions = { lifetimeMs: 10 * 365 * 86_400_000 }; + +// 'expired' stays in ErrorKind: an outcome that an earlier version journaled +// still reaches onError with it, so an exhaustive switch keeps its case. +assertEqual< + ErrorKind, + 'http' | 'network' | 'file' | 'expired' | 'truncated' | 'unknown' +>(true); + +export const label = (error: OutcomeError): string => { + switch (error.errorKind) { + case 'http': + case 'network': + case 'file': + case 'truncated': + case 'unknown': + return error.errorKind; + case 'expired': + return 'expired under an earlier version'; + } +}; diff --git a/src/index.ts b/src/index.ts index a36bc010..acaab970 100644 --- a/src/index.ts +++ b/src/index.ts @@ -17,7 +17,6 @@ import { import { createRegistry, DEFAULT_ENQUEUE_TIMEOUT_MS, - DEFAULT_LIFETIME_MS, isDev, MAX_VARS_BYTES, type AnyDefinition, @@ -98,7 +97,6 @@ export const createUploadClient = ({ native = NativeRNFileUploader, }: UploadClientOptions = {}): UploadClient => { const settings: Settings = { - lifetimeMs: DEFAULT_LIFETIME_MS, enqueueTimeoutMs: DEFAULT_ENQUEUE_TIMEOUT_MS, maxVarsBytes: MAX_VARS_BYTES, }; @@ -152,6 +150,8 @@ export const createUploadClient = ({ // already warned about. let listedKeys: Set | undefined; const warnedKeys = new Set(); + // The lifetimeMs deprecation warns one time per client. + let warnedLifetimeMs = false; const onDefine = (key: string): void => { if ( @@ -179,15 +179,19 @@ export const createUploadClient = ({ /** * One-time setup. Call it at boot, after every define() call. Stores the - * lifetime, the vars cap, the headers provider, the warning sink and the - * retry defaults, forwards the - * lifetime, retry and Android notification settings to native, then starts - * replaying journaled outcomes. A second call updates the settings and does - * not replay again. Each call replaces the full configuration. + * vars cap, the enqueue warning time, the headers provider, the warning + * sink and the retry defaults, forwards the retry and Android notification + * settings to native, then starts replaying journaled outcomes. A second + * call updates the settings and does not replay again. Each call replaces + * the full configuration. * * `definitions` is optional. Each listed handle came from define(), so its * key is registered already. The list only pins the keys, so that a later * define() of another key warns in development. + * + * `lifetimeMs` is deprecated and ignored: any value is accepted, it does + * not cross to native, and in development the first call that sets it + * warns. */ const configure = (options: ConfigureOptions): void => { // Every check runs before any setting changes, so a rejected call leaves @@ -205,12 +209,6 @@ export const createUploadClient = ({ 'configure: definitions must be an array of the handles that define() returned', ); } - const lifetimeMs = options.lifetimeMs ?? DEFAULT_LIFETIME_MS; - if (!Number.isFinite(lifetimeMs) || lifetimeMs <= 0) { - throw new Error( - `configure: lifetimeMs must be a positive number, got ${options.lifetimeMs}`, - ); - } const enqueueTimeoutMs = options.enqueueTimeoutMs ?? DEFAULT_ENQUEUE_TIMEOUT_MS; if (!Number.isFinite(enqueueTimeoutMs) || enqueueTimeoutMs <= 0) { @@ -232,16 +230,21 @@ export const createUploadClient = ({ `configure: onWarning must be a function when given, got ${typeof options.onWarning}`, ); } - settings.lifetimeMs = lifetimeMs; settings.enqueueTimeoutMs = enqueueTimeoutMs; settings.maxVarsBytes = maxVarsBytes; settings.headers = options.headers; settings.retry = options.retry; settings.onWarning = options.onWarning; - const forwarded: Record = { - lifetimeMs, - ...options.android, - }; + // After the sink is set, so the warning goes to this call's onWarning. + if (options.lifetimeMs !== undefined && !warnedLifetimeMs && isDev()) { + warnedLifetimeMs = true; + warn( + 'configure: lifetimeMs is deprecated and ignored: the library has no deadlines. To bound a request, call cancel(id). It leaves the types in the next major release.', + ); + } + // lifetimeMs does not cross: native never needed it, because JS used to + // turn it into each entry's expiresAt. + const forwarded: Record = { ...options.android }; if (options.retry !== undefined) { forwarded.retry = options.retry; } @@ -256,8 +259,8 @@ export const createUploadClient = ({ /** * No scope pauses the whole queue. `{ keys }` pauses the entries of those * keys, queued and future. No outcome is produced; live rows show - * 'paused'. A paused entry past its expiresAt settles error/expired when - * it resumes. + * 'paused'. A paused entry waits with no time limit; it runs again when it + * resumes. */ const pause = async (scope?: PauseScope): Promise => native.pause(toNativeScope('pause', scope)); diff --git a/src/registry.ts b/src/registry.ts index aa4bf9d3..50acf5db 100644 --- a/src/registry.ts +++ b/src/registry.ts @@ -10,7 +10,18 @@ import type { Vars, } from './types'; -export const DEFAULT_LIFETIME_MS = 14 * 24 * 60 * 60 * 1000; +/** + * The `expiresAt` that every enqueue sends. The library has no deadlines, and + * native ignores the field. Native on 11.3.0 and earlier rejects an entry + * with no `expiresAt` number, so the field still crosses. This value is the + * largest valid `Date`, so a native that still expires never reaches it. + */ +export const NO_DEADLINE_EXPIRES_AT = 8_640_000_000_000_000; + +/** The deprecation warning for a descriptor that sets `expiresAt`. */ +const expiresAtWarning = (key: string): string => + `mutate: the descriptor of "${key}" sets expiresAt. expiresAt is deprecated and ignored: the library has no deadlines. To bound a request, call cancel(id). It leaves the types in the next major release.`; + /** * How long mutate() waits for native enqueue() before it warns. mutate() * keeps waiting after the warning and settles only with native's answer. @@ -61,7 +72,6 @@ const ANDROID_KEYS = ['noNotification']; /** The JS-side settings that `configure()` stores. */ export type Settings = { - lifetimeMs: number; enqueueTimeoutMs: number; maxVarsBytes: number; headers?: () => Record; @@ -87,6 +97,7 @@ export const warnIfSlow = ( * The descriptor as it crosses to native. `dataJson` is `JSON.stringify(data)` * and replaces `data`. It is absent for a bodiless request. `wifiOnly` crosses * only when the definition set it; absent means "follow setWifiOnly()". + * `expiresAt` is always `NO_DEADLINE_EXPIRES_AT`, whatever the definition set. */ export type NativeDescriptor = Omit & { dataJson?: string; @@ -118,7 +129,6 @@ type RegistryDeps = { /** Called after `define()` has registered `key`. */ onDefine?: (key: string) => void; warn?: (message: string) => void; - now?: () => number; }; /** @@ -564,14 +574,9 @@ export const validateDescriptor = (descriptor: unknown): NativeDescriptor => { ) { throw new Error("mutate: priority must be 'high' or 'normal' when present"); } - if ( - d.expiresAt !== undefined && - (!Number.isFinite(d.expiresAt) || d.expiresAt <= 0) - ) { - throw new Error( - `mutate: expiresAt must be a finite epoch-ms timestamp, got ${d.expiresAt}`, - ); - } + // expiresAt is not checked: it is deprecated and ignored, and an ignored + // value must never be the reason a request is refused. It stays in + // DESCRIPTOR_KEYS, so a descriptor that sets it is accepted. const { data, ...rest } = d; return data === undefined ? rest : { ...rest, dataJson: serializeData(data) }; }; @@ -579,8 +584,9 @@ export const validateDescriptor = (descriptor: unknown): NativeDescriptor => { /** * Holds the definitions of one client and builds `define()`. Every `mutate()` * validates `vars` and the descriptor, merges the configured headers under the - * descriptor's (names matched without regard to case), defaults `expiresAt`, - * hands the entry to native, and resolves with the entry's own id. + * descriptor's (names matched without regard to case), sets `expiresAt` to + * `NO_DEADLINE_EXPIRES_AT`, hands the entry to native, and resolves with the + * entry's own id. */ export const createRegistry = ({ native, @@ -589,8 +595,9 @@ export const createRegistry = ({ trackMutate, onDefine, warn = console.warn, - now = Date.now, }: RegistryDeps): Registry => { + // The expiresAt deprecation warns one time per client. + let warnedExpiresAt = false; // The overloads on Define keep the with-parser and without-parser shapes // apart for callers. The client applies them; one implementation serves // both. @@ -639,6 +646,10 @@ export const createRegistry = ({ if (!isPlainObject(provided)) { throw new Error('mutate: configure().headers() must return an object'); } + if (descriptor.expiresAt !== undefined && !warnedExpiresAt && isDev()) { + warnedExpiresAt = true; + warn(expiresAtWarning(key)); + } const entry: EnqueueEntry = { id: options?.id ?? uuidV4(), key, @@ -646,7 +657,7 @@ export const createRegistry = ({ descriptor: { ...descriptor, headers: mergeHeaders(provided, descriptor.headers), - expiresAt: descriptor.expiresAt ?? now() + settings.lifetimeMs, + expiresAt: NO_DEADLINE_EXPIRES_AT, }, }; // mutate() settles only with native's answer. A late answer is not a diff --git a/src/testing.ts b/src/testing.ts index 4aef5f59..664d7f10 100644 --- a/src/testing.ts +++ b/src/testing.ts @@ -10,7 +10,10 @@ * The fake keeps a small model of the native queue. enqueue() adds a row, * settle() journals an outcome and emits it, and ackEvents() forgets a * completed or cancelled row. It emits a 'state' row for each of these - * transitions, as native does. It never sends HTTP and never retries. + * transitions, as native does. It never sends HTTP and never retries. Like + * native, it never expires an entry. To test an `expired` outcome that an + * earlier version journaled, pass an event from buildSettled() to + * seedUnacknowledged(). * pause() and resume() keep the whole-queue gate and the paused-keys set, * and move rows between 'paused' and 'queued' as native does. It records * setWifiOnly() and a descriptor's wifiOnly but has no network to gate. diff --git a/src/types.ts b/src/types.ts index 4bd96fc9..38d67554 100644 --- a/src/types.ts +++ b/src/types.ts @@ -24,14 +24,20 @@ export type Method = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET'; /** * Why a request failed. `http` means the server answered and the status was * not accepted. `network` is a transport failure. `file` means the payload is - * missing on disk, so a retry can never succeed. `expired` means `expiresAt` - * passed. `truncated` means the response body hit the 1 MB cap, so the - * `response` parser could not run. `unknown` covers a parser throw. + * missing on disk, so a retry can never succeed. `truncated` means the + * response body hit the 1 MB cap, so the `response` parser could not run. + * `unknown` covers a parser throw. + * + * `expired` is deprecated. The library has no deadlines and no longer + * produces it. Only an entry that settled under an earlier version, and whose + * outcome was not yet acknowledged, carries it; that outcome still reaches + * `onError`. It leaves the type in the next major release. */ export type ErrorKind = | 'http' | 'network' | 'file' + /** @deprecated Produced only by an earlier version. See `ErrorKind`. */ | 'expired' | 'truncated' | 'unknown'; @@ -126,7 +132,12 @@ export type RequestDescriptor = { /** Chunked over `file`. Each part sends its own byte range. */ parts?: Part[]; accept?: AcceptRule[]; - /** Epoch ms. Default now + `lifetimeMs`. */ + /** + * @deprecated Ignored. The library has no deadlines: it keeps an entry + * until the retry rules settle it or the app calls `cancel(id)`. To bound + * a request, call `cancel(id)`. Any value is accepted. Leaves the type in + * the next major release. + */ expiresAt?: number; retry?: Partial; /** @@ -395,7 +406,11 @@ export type ConfigureOptions = { * unlisted key still receives its outcomes. */ definitions?: readonly AnyDefined[]; - /** Default 14 days. Sets the default `expiresAt` of every entry. */ + /** + * @deprecated Ignored. The library has no deadlines. To bound a request, + * call `cancel(id)`. Any value is accepted. Leaves the type in the next + * major release. + */ lifetimeMs?: number; /** * Default 1 MB. `mutate()` rejects `vars` whose JSON is longer. Only `vars` From b41e1492359a98fa3670cbebb513a71584908d57 Mon Sep 17 00:00:00 2001 From: Dylan Murphy Date: Wed, 18 Nov 2026 16:24:58 -0500 Subject: [PATCH 2/2] Say what is true about deadlines before the native removals land JS sends every new or re-queued request with a fixed far-future deadline, so it cannot expire. A live entry that an earlier version queued keeps its stored deadline until the native side stops reading it, in the same release. An entry that already settled expired stays an error row. The README's seeding example now passes deliveries: 0, so the first delivery counts 1. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 15 +++++++++------ README.md | 26 +++++++++++++++----------- src/NativeRNFileUploader.ts | 8 +++++--- src/registry.ts | 8 ++++---- src/testing.ts | 8 ++++---- src/types.ts | 10 ++++++---- 6 files changed, 43 insertions(+), 32 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b0f63723..1eaf498d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ ## Unreleased -The library has no deadlines. It never expires a request: it keeps an +The library has no deadlines. It sets no deadline on a request: it keeps an entry, and retries it, until the retry rules settle it or the app calls `cancel(id)`. An app that needs a bound calls `cancel(id)` itself. `expiresAt` on a descriptor and `lifetimeMs` in `configure()` are @@ -13,11 +13,14 @@ that sets `lifetimeMs`, warn one time per client (to `onWarning`, or `console.warn` when none is set). `configure()` no longer sends `lifetimeMs` to native. Every enqueue sends `expiresAt: 8640000000000000` (the largest valid `Date`), because native in -11.3.0 and earlier rejects an entry without one. Entries queued by an -earlier version keep going. `errorKind: 'expired'` is deprecated: only an -outcome that an earlier version journaled, and that was not yet -acknowledged, carries it, and it still reaches `onError`. The fake native -module never expired an entry and still does not. This JS change ships in +11.3.0 and earlier rejects an entry without one. So every new or re-queued +request cannot expire. A live entry that an earlier version queued, and +that is never queued again, keeps its stored deadline until the native side +stops reading it, in the same release; after that it keeps going. An entry +that settled `expired` under an earlier version stays an `error` row until +`cancel()` or a same-id `mutate()`, and an unacknowledged `expired` outcome +still reaches `onError`. `errorKind: 'expired'` is deprecated. The fake +native module never expired an entry and still does not. This JS change ships in the same release as the Android and iOS changes that remove expiry. ## 11.3.0 diff --git a/README.md b/README.md index 739efd91..d3b5e19b 100644 --- a/README.md +++ b/README.md @@ -286,20 +286,23 @@ while the app was dead from being sent twice. # Reliable delivery -**No deadlines.** The library never expires a request. It keeps an entry, -and retries it, until the retry rules below settle it or the app calls -`cancel(id)`. +**No deadlines.** The library sets no deadline on a request. It keeps an +entry, and retries it, until the retry rules below settle it or the app +calls `cancel(id)`. - `expiresAt` on a descriptor and `lifetimeMs` in `configure()` are deprecated and do nothing. `mutate()` and `configure()` accept any value for them, and in development the first call that sets one logs a warning. They leave the types in the next major release. - An app that needs a bound keeps its own clock and calls `cancel(id)`. -- Entries queued by an earlier version keep going. The deadline they stored - is ignored too. -- An outcome with `errorKind: 'expired'` that an earlier version journaled, - and that was not yet acknowledged, still reaches `onError` after the - upgrade. The library produces no new `expired` outcomes. +- JS sends every new or re-queued request to native with a fixed far-future + deadline, so it cannot expire. +- A live entry that an earlier version queued, and that is never queued + again, keeps its stored deadline until the native side stops reading it, + in the same release. After that it keeps going. +- An entry that settled `expired` under an earlier version stays an `error` + row until `cancel()` or a same-id `mutate()`. If its outcome was not yet + acknowledged, the outcome still reaches `onError` after the upgrade. 1. **Write-ahead.** Entry, descriptor, and staged body persist before any attempt. `mutate()` resolves after the row and every staged body copy are @@ -910,9 +913,10 @@ behind a held one, as they do on a device. On release they all run in order, as usual, and a failure that `failNext()` queued goes to the first call that runs. `reset()` drops held calls and the calls behind them. `seedUnacknowledged()` and `seedRows()` model a journal and rows left by a dead session, so `configure()` replays -them. Like native, the fake never expires an entry. To test the `expired` -outcome an earlier version may have journaled, seed one: -`native.seedUnacknowledged([native.buildSettled(id, { kind: 'error', error: { errorKind: 'expired' } })])`. +them. The fake never expires an entry. To test the `expired` outcome an +earlier version may have journaled, seed one with `deliveries: 0`, so its +first delivery counts 1: +`native.seedUnacknowledged([native.buildSettled(id, { kind: 'error', error: { errorKind: 'expired' } }, { deliveries: 0 })])`. `seedDiagnostics()` adds records for `takeDiagnostics()`, and `seedBootSnapshot({ v9Leftovers: { unownedUploads: 2 } })` adds a boot record with those counts, the others 0 and no ids. diff --git a/src/NativeRNFileUploader.ts b/src/NativeRNFileUploader.ts index fc19e195..656428b5 100644 --- a/src/NativeRNFileUploader.ts +++ b/src/NativeRNFileUploader.ts @@ -26,10 +26,12 @@ export interface Spec extends TurboModule { // { status: null } would arrive as {}. Native parses them. dataJson // "null" is the JSON body null, a real body, not an absent one. // - // No deadlines: native never expires an entry. descriptor.expiresAt is - // ignored, and native accepts an entry with or without it. JS always sends + // descriptor.expiresAt is deprecated. JS always sends // 8_640_000_000_000_000 (the largest valid Date), because native on 11.3.0 - // and earlier rejects an entry with no expiresAt number. + // rejects an entry with no expiresAt number. So a new or re-queued entry + // cannot expire. A live entry that an earlier version queued, and that is + // never queued again, keeps its stored deadline until the native side + // stops reading it, in the same release. // // Resolves AFTER the row and every staged body copy are durably on disk // (tmp file + rename), never on the network. Staging copies a `file` body diff --git a/src/registry.ts b/src/registry.ts index 50acf5db..43f80a2b 100644 --- a/src/registry.ts +++ b/src/registry.ts @@ -11,10 +11,10 @@ import type { } from './types'; /** - * The `expiresAt` that every enqueue sends. The library has no deadlines, and - * native ignores the field. Native on 11.3.0 and earlier rejects an entry - * with no `expiresAt` number, so the field still crosses. This value is the - * largest valid `Date`, so a native that still expires never reaches it. + * The `expiresAt` that every enqueue sends. The library sets no deadline. + * Native on 11.3.0 rejects an entry with no `expiresAt` number, so the field + * still crosses. This value is the largest valid `Date`, so a native that + * still reads it never reaches it. */ export const NO_DEADLINE_EXPIRES_AT = 8_640_000_000_000_000; diff --git a/src/testing.ts b/src/testing.ts index 664d7f10..e537760c 100644 --- a/src/testing.ts +++ b/src/testing.ts @@ -10,10 +10,10 @@ * The fake keeps a small model of the native queue. enqueue() adds a row, * settle() journals an outcome and emits it, and ackEvents() forgets a * completed or cancelled row. It emits a 'state' row for each of these - * transitions, as native does. It never sends HTTP and never retries. Like - * native, it never expires an entry. To test an `expired` outcome that an - * earlier version journaled, pass an event from buildSettled() to - * seedUnacknowledged(). + * transitions, as native does. It never sends HTTP and never retries. It + * never expires an entry. To test an `expired` outcome that an + * earlier version journaled, pass an event from buildSettled() with the + * override `{ deliveries: 0 }` to seedUnacknowledged(). * pause() and resume() keep the whole-queue gate and the paused-keys set, * and move rows between 'paused' and 'queued' as native does. It records * setWifiOnly() and a descriptor's wifiOnly but has no network to gate. diff --git a/src/types.ts b/src/types.ts index 38d67554..18d72a51 100644 --- a/src/types.ts +++ b/src/types.ts @@ -28,10 +28,12 @@ export type Method = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET'; * response body hit the 1 MB cap, so the `response` parser could not run. * `unknown` covers a parser throw. * - * `expired` is deprecated. The library has no deadlines and no longer - * produces it. Only an entry that settled under an earlier version, and whose - * outcome was not yet acknowledged, carries it; that outcome still reaches - * `onError`. It leaves the type in the next major release. + * `expired` is deprecated. JS sends every new or re-queued request with a + * fixed far-future deadline, so such a request never settles `expired`. Only + * an entry that an earlier version queued can: its stored deadline holds + * until the native side stops reading it, in the same release. An `expired` + * outcome that was not yet acknowledged still reaches `onError`. It leaves + * the type in the next major release. */ export type ErrorKind = | 'http'