diff --git a/CHANGELOG.md b/CHANGELOG.md index 574795a4..1eaf498d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,28 @@ +## Unreleased + +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 +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. 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 Added `useRequests(filter?)` and `useRequestsWithProgress(filter?)`, React diff --git a/README.md b/README.md index 525c964f..d3b5e19b 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,24 @@ while the app was dead from being sent twice. # Reliable delivery +**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)`. +- 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 durably on disk (temp file, rename, then a sync of the directory), so the @@ -309,9 +327,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 +348,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 +360,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 +438,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 +459,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 +486,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 +913,11 @@ 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. 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/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..43f80a2b 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 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; + +/** 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..e537760c 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. 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 4bd96fc9..18d72a51 100644 --- a/src/types.ts +++ b/src/types.ts @@ -24,14 +24,22 @@ 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. 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' | 'network' | 'file' + /** @deprecated Produced only by an earlier version. See `ErrorKind`. */ | 'expired' | 'truncated' | 'unknown'; @@ -126,7 +134,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 +408,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`