Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
54 changes: 36 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")
},
});

Expand Down Expand Up @@ -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. |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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<string, string>`, called at `mutate()`. The descriptor merges over it. |
Expand All @@ -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.
Expand Down Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion example/RNBGUExample/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,7 @@ const App = () => {
onChangeText={setCustomId}
/>
<Field
label="Expires in s (blank = default)"
label="Expires in s (ignored; blank = none)"
value={expiresInS}
onChangeText={setExpiresInS}
keyboardType="number-pad"
Expand Down
22 changes: 11 additions & 11 deletions example/RNBGUExample/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,9 @@ writes the bytes at their offset into `example/server/received/`. It prints
requests use the same value.
- **Options for new requests.** The server mode. "Id" sets the id of the next
request (blank gives a UUID). "Expires in s" sets `expiresAt` to now plus
that many seconds. "File size MiB" sets the size of the file and chunked
uploads (chunked parts are 5 MiB). "Silent" sends
that many seconds. The library ignores `expiresAt` (it has no deadlines),
so this only checks that nothing expires. "File size MiB" sets the size of
the file and chunked uploads (chunked parts are 5 MiB). "Silent" sends
`android: { noNotification: true }`. "Handlers throw" makes `onSuccess` and
`onError` throw after they log, so outcomes stay unacknowledged. The app
keeps these two switches and the server field after a relaunch.
Expand Down Expand Up @@ -176,11 +177,11 @@ back to `Bearer bad` before a step that needs a 401.
time. Keep it for 10 minutes: the gaps keep growing (64 s, 128 s, and on)
and do not drop back to 1 s. `adb shell dumpsys jobscheduler | grep -A3 '#wake'`
shows the wake job. Cancel the row after.
9. **Expiry.** Mode `down`, "Expires in s" 20. Press "JSON POST". Pass: an
outcome `error errorKind=expired` at about 20 s. The row stays `error`.
"Cancel" clears it. Variant: mode `auth` with `Bearer bad`, expiry 20:
the row parks, then settles `expired` at about 20 s. Clear "Expires in s"
after.
9. **No deadline.** Mode `down`, "Expires in s" 20. Press "JSON POST".
Pass: after 60 s there is no outcome, attempts keep coming with backoff,
and the row is `running` or `queued`. Variant: mode `auth` with
`Bearer bad`, "Expires in s" 20: the row parks on `awaiting-auth` and
stays there after 60 s. Cancel the rows and clear "Expires in s" after.
10. **Kill and relaunch.** Mode `ok`, size 50. Press "Chunked PUT" and kill
the app at about 40 %. Pass: the server keeps getting parts and prints
`ASSEMBLED`, and a file appears in `rnbgupload-settled/`. Open the app.
Expand Down Expand Up @@ -280,10 +281,9 @@ step says otherwise.
phone at once for 1 minute. Pass: the server shows hits 1, 2, and 3 at
about 0 s, +1 s, and +3 s. After unlock, the outcome is `ok` with
`attempts=3`. The row shows "next in Ns" between attempts.
13. **Expired.** Mode `down`, "Expires in s" 60. Press "JSON POST". Pass: an
outcome `errorKind=expired` about 60 s later, and the row stays `error`.
Press "Same id, same body" on it. Pass: the entry opens again and runs
(a new generation). Cancel it and clear "Expires in s".
13. **No deadline.** Mode `down`, "Expires in s" 20. Press "JSON POST".
Pass: after 60 s there is no outcome, and attempts keep coming with
backoff. Cancel it and clear "Expires in s".
14. **v9 import.** Install the v9.0.0 build. Start one chunked upload (half
done) and one simple upload that errors, then kill the app. Install this
build. Pass: the rows show a `legacy` row for the errored upload, and
Expand Down
5 changes: 4 additions & 1 deletion example/RNBGUExample/harness/uploads.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,10 @@ type Target = {
host: string;
/** Starts with the mode, for example /ok/json/abc. */
path: string;
/** Seconds from mutate() to expiresAt. Absent means the default. */
/**
* Seconds from mutate() to expiresAt. expiresAt is deprecated and
* ignored, so this checks that nothing expires. Absent sends none.
*/
expiresInS?: number;
silent?: boolean;
};
Expand Down
23 changes: 15 additions & 8 deletions src/NativeRNFileUploader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ import { TurboModuleRegistry } from 'react-native';
// README's "API" and "Reliable delivery" sections and the plan's sections 5.4
// and 6 mirror them.
export interface Spec extends TurboModule {
// Queue-wide settings: { lifetimeMs, retry, ...androidNotificationConfig }.
// Queue-wide settings: { retry?, ...androidNotificationConfig }. JS no
// longer sends lifetimeMs; native ignores it when an older JS sends it.
// Android persists the notification config, so a headless WorkManager
// relaunch (no JS) can read it. Each call replaces the full configuration.
configure(options: CodegenTypes.UnsafeObject): void;
Expand All @@ -25,6 +26,13 @@ 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.
//
// descriptor.expiresAt is deprecated. JS always sends
// 8_640_000_000_000_000 (the largest valid Date), because native on 11.3.0
// 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
// and form `path` parts, so a large file takes longer. The caller may
Expand All @@ -36,12 +44,11 @@ export interface Spec extends TurboModule {
//
// Same id, again. The body is data/form/file/parts, and a different url or
// method is a different body.
// - 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/parts) and the entry is NOT running
// (queued, paused, awaiting-auth, or settled): replace the descriptor,
// staged body, vars, headers and expiresAt, and reopen the entry. It
// settles once more.
// staged body, vars and headers, and reopen the entry. It settles once
// more.
// - Different body, entry running: reject E_RUNNING.
// - Cancelled-but-unacked entry: a fresh generation. ack forgets the entry
// only when the generation matches.
Expand All @@ -63,8 +70,7 @@ export interface Spec extends TurboModule {
// Each live entry that becomes paused moves to 'paused', and each that
// stops being paused moves back to 'queued', with one 'state' event per
// entry. A running attempt stops. No outcome is produced and no attempt
// event is emitted. A paused entry past expiresAt settles error/expired
// when it stops being paused.
// event is emitted. A paused entry waits with no time limit.
//
// pause, resume, setWifiOnly, updateHeaders and configure apply the new
// settings in memory, then save them best-effort. A failed settings save
Expand Down Expand Up @@ -104,7 +110,8 @@ export interface Spec extends TurboModule {
getRequests(): CodegenTypes.UnsafeObject[];
// Settled outcomes that JS has not acknowledged, in the onSettled shape,
// including ones journaled while JS was dead. Internal: ./delivery drains
// them after configure().
// them after configure(). An outcome journaled by an earlier version can
// carry errorKind 'expired'; it is returned like any other.
getUnacknowledgedEvents(): Promise<CodegenTypes.UnsafeObject[]>;
// Removes journaled outcomes by eventId. Resolves void. Idempotent; unknown
// ids are ignored. An acknowledged 'completed' is the one moment native
Expand Down
Loading
Loading