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
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,33 @@
## Unreleased

Added the JavaScript side of two native changes that come later. One
behavior changes now: every handler's `meta` has `ambiguousAttempts`, which
is 0 for today's events. A test that compares the whole `meta` object, and a
`Meta` built by hand, need the new field. Nothing else changes until native
code sends the new fields.

- `Meta.ambiguousAttempts` (a number) counts the attempts of the current
generation that ended with no answer from the server after the whole
request can have reached it. The library sends the request again after
each one, so a count above 0 means the server can have more than one copy.
It reads 0 when native does not send it, which is the case for now.
- `AttemptEvent.bodySent` (`'none' | 'partial' | 'full'`, optional) says how
much of the request body had left when the attempt ended.
- `RawResponse.bodyUnknown` (`true`, optional) marks a request the server
accepted whose response body the library did not get. The outcome is
`completed`, is never sent again, and is never the `truncated` error. A
definition without a `response` parser gets it in `onSuccess`. A
definition with one gets the new optional handler
`onBodyUnknown(response, vars, meta)` instead of the parser and
`onSuccess`. A definition with a parser and `onSuccess` but no
`onBodyUnknown` gets no call: the outcome is held unacknowledged with a
warning per outcome, and is delivered when a `define()` of the key adds
the handler, or at the next launch. With neither `onSuccess` nor
`onBodyUnknown`, the outcome is acknowledged with no call.
- `createFakeNative()` can settle such an outcome
(`response: { bodyUnknown: true }`) and set `ambiguousAttempts` in the
overrides.

## 11.3.0

Added `useRequests(filter?)` and `useRequestsWithProgress(filter?)`, React
Expand Down
102 changes: 95 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -351,6 +351,7 @@ Retry classes:
| 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` |
| accepted, but the response body was not received (`bodyUnknown`; not yet sent by native) | settle `completed`; never sent again. Without a `response` parser, `onSuccess` gets the response with `bodyUnknown: true`. With one, `onBodyUnknown` runs instead. See "Accepted, body unknown" below |

**Transient rule counts.** The library counts the responses each rule
excuses. It keeps the count by the rule's `status` and `bodyIncludes`, not by
Expand All @@ -367,6 +368,59 @@ its place in the list:
- A same-id `mutate()` that reopens a settled entry starts every count at 0.
A same-id `mutate()` on a live entry keeps the counts.

**Accepted, body unknown.** Sometimes the library knows the server accepted
a request but did not get the response body. For example, the status line
said 201 and the connection dropped before the body arrived. The request is
done: the library does not send it again, and it is not an error. The
outcome is `completed`, and its `RawResponse` has `bodyUnknown: true` and no
`body`. This is not `bodyTruncated`, which means the body was over 1 MB.

The app handles it in one place, typically by fetching the object from the
server:

- A definition without a `response` parser gets it in `onSuccess`, like any
completed outcome. Check `response.bodyUnknown` there. Once native sends
the flag, an `onSuccess` that reads `response.body` without that check
throws on such a response, and a handler that throws is delivered again
at every launch.
- A definition with a parser cannot get typed data, so the parser and
`onSuccess` do not run, and `onError` is not called. `onBodyUnknown(response,
vars, meta)` runs instead.
- A definition with a parser and `onSuccess` but no `onBodyUnknown` gets no
call. The outcome is held unacknowledged, and native keeps the row. It is
delivered when a `define()` of the key adds `onBodyUnknown`, or at the
next launch, with `meta.deliveries` grown. Unlike a key with no
definition, this hold emits no `state` event: the row stays `completed`
until the outcome is acknowledged. The only signal is a warning through
`onWarning`, one per outcome, with the outcome (and its `vars`) as
`detail`, so an app should set `onWarning`. This is an exception to the
order per id in rule 5: when a same-id `mutate()` with a different body
reopens the entry while the outcome is held, the later outcome of that id
can be delivered first.
- A definition with a parser and neither `onSuccess` nor `onBodyUnknown`
asked for no result, so its outcome is acknowledged with no call and no
warning.

```ts
const createNote = uploads.define({
key: 'note.create',
request: (vars: NoteVars) => ({ url: notesUrl(vars), data: vars.note }),
response: (raw) => noteSchema.parse(raw),
onSuccess: (note) => {
store.dispatch(noteSaved(note));
},
// The server has the note, but its answer was lost. Fetch it.
onBodyUnknown: (_response, vars) => {
store.dispatch(fetchNote(vars.noteId));
},
});
```

As with the other handlers, the outcome is acknowledged after the handler's
promise resolves, and a handler that rejects runs again at the next launch.

Native code does not set `bodyUnknown` yet, so for now no outcome carries it.

Every attempt sends an `X-Request-Id` header, minted per attempt. `Meta.requestId`
carries the last one.

Expand All @@ -385,6 +439,7 @@ type Definition<V extends object | null, T> =
response: (raw: unknown, vars: V) => T; // JSON-parsed body, or undefined when there is none
onSuccess?: (data: T, vars: V, meta: Meta) => void | Promise<void>;
onError?: (error: OutcomeError, vars: V, meta: Meta) => void | Promise<void>;
onBodyUnknown?: (response: RawResponse, vars: V, meta: Meta) => void | Promise<void>;
}
| {
key: string;
Expand All @@ -399,7 +454,7 @@ type Definition<V extends object | null, T> =
return type. `response` also receives the entry's `vars`, for a parser that
needs the request context; a one-argument parser such as `schema.parse` is
assignable as it is. Without `response`, `onSuccess` receives the `RawResponse`
(`{ status?, headers?, body?, bodyTruncated }`), and an `onSuccess` annotated
(`{ status?, headers?, body?, bodyTruncated, bodyUnknown? }`), and an `onSuccess` annotated
with any other type is a compile error. `V` is any object or `null`, so a
generated API request type works as it is. `mutate()` rejects vars and
`data` that do not serialize: a cycle, a function, a BigInt, or a value that
Expand All @@ -408,16 +463,35 @@ dropped. A `request` that declares no parameter gives `V = null`, and
`mutate()` then takes no arguments. When `response` is set and
the body was truncated, `onError` gets `errorKind: 'truncated'`. When
`response` throws, `onError` gets `errorKind: 'unknown'` with the thrown
message; the entry still settles as completed. A key that is already defined
message; the entry still settles as completed. When `response` is set and
the server accepted the request but the body is unknown, `onBodyUnknown`
runs instead of the parser and `onSuccess` (see "Accepted, body unknown").
Only a definition with `response` takes `onBodyUnknown`. A key that is already defined
is replaced, with a warning in development. A `cancelled` outcome calls no
handler.

`Meta` is `{ id, key, at, attempts, requestId?, deliveries }`; `at` is the
`Meta` is `{ id, key, at, attempts, requestId?, deliveries, ambiguousAttempts }`; `at` is the
native outcome time. `attempts` counts attempts in the current generation; a
same-id `mutate()` that reopens the entry starts a new one. `deliveries`
counts deliveries that reached a JS listener: 1 on the first, +1 per replay.
An outcome journaled while no listener exists starts at 0 and is not emitted
live, so its first delivery, at the boot replay, is 1.
live, so its first delivery, at the boot replay, is 1. `ambiguousAttempts`
counts the attempts of the current generation that ended with no answer from
the server after the whole request can have reached it. The library always
sends the request again after such an attempt, so a count above 0 means the
server can have more than one copy. Native code does not count these yet, so
for now it is 0, and an outcome journaled before the count existed reads 0.

```ts
onSuccess: (data, vars, meta) => {
if (meta.ambiguousAttempts > 0) {
analytics.track('upload sent in doubt', {
key: meta.key,
count: meta.ambiguousAttempts,
});
}
},
```

### `mutate(vars, { id? }): Promise<{ id }>`

Expand Down Expand Up @@ -605,8 +679,10 @@ const CaptureBadge = ({ captureId }: { captureId: string }) => {
- Completed rows are included. A completed row stays until its outcome is
acknowledged. When its handler rejects, or its key has no definition and
no `define()` of the key runs in this session (rule 5 of "Reliable
delivery"), the outcome is not acknowledged, so the row stays for the whole
session. Do not treat a completed row as work still to do.
delivery"), or its body is unknown and its definition has a parser and
`onSuccess` but no `onBodyUnknown` ("Accepted, body unknown"), the outcome
is not acknowledged, so the row stays for the whole session. Do not treat a
completed row as work still to do.
- `useRequests()` re-renders when a row appears, changes state, or goes. A
row's bytes are those of its last `state` event.
- `useRequestsWithProgress()` also re-renders on each `progress` event of a
Expand Down Expand Up @@ -779,7 +855,7 @@ Fires when the Android progress notification is pressed. No event data.
| --- | --- |
| `state` | A full `RequestRow`, one per transition, plus `reason: 'unhandled-key'` for an outcome whose key has no definition. A consumer's reducer is one upsert. |
| `progress` | `{ id, bytesSent, totalBytes }`, byte-weighted across a chunked upload's parts. |
| `attempt` | One HTTP attempt: `{ id, key, requestId, attempt, url, method, partIndex?, outcome, httpCode?, responseBody? (4 KB cap), responseBodyTruncated?, responseHeaders?, errorKind?, errorMessage?, at }`. `outcome` is `completed` for an accepted response (2xx or a matching `accept` rule). Any other HTTP response is `error` with `errorKind: 'http'`; a transport failure is `error` with its own `errorKind`. Pause, cancel, and supersede emit no attempt event. Live-only; never journaled or replayed. |
| `attempt` | One HTTP attempt: `{ id, key, requestId, attempt, url, method, partIndex?, outcome, httpCode?, responseBody? (4 KB cap), responseBodyTruncated?, responseHeaders?, errorKind?, errorMessage?, bodySent?, at }`. `bodySent` is `'none'`, `'partial'` or `'full'`: how much of the request body (for a chunked upload, the part's range) had left when the attempt ended. It is absent when native does not report it; native code does not report it yet. `outcome` is `completed` for an accepted response (2xx or a matching `accept` rule). Any other HTTP response is `error` with `errorKind: 'http'`; a transport failure is `error` with its own `errorKind`. Pause, cancel, and supersede emit no attempt event. Live-only; never journaled or replayed. |

Terminal outcomes do not appear here. They go to the definition's handlers.

Expand Down Expand Up @@ -903,6 +979,18 @@ them. `seedDiagnostics()` adds records for `takeDiagnostics()`, and
`seedBootSnapshot({ v9Leftovers: { unownedUploads: 2 } })` adds a boot record
with those counts, the others 0 and no ids.

To test an accepted response whose body is unknown, settle it with the flag.
To test the count of attempts in doubt, pass it in the overrides; the fake
leaves it out by default, so `meta.ambiguousAttempts` is 0:

```ts
await native.settle(
id,
{ kind: 'completed', response: { status: 201, bodyUnknown: true } },
{ ambiguousAttempts: 1 },
);
```

An app that builds its client at module load can use the fake from the mock
for every client instead. Get it with
`TurboModuleRegistry.getEnforcing('RNFileUploader')`, and call
Expand Down
12 changes: 11 additions & 1 deletion src/NativeRNFileUploader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,9 @@ export interface Spec extends TurboModule {
// accepted response. Any other HTTP response is 'error' with errorKind
// 'http'. A transport failure is 'error' with its own errorKind. Pause,
// cancel, and supersede emit no attempt event. Live-only: never journaled,
// never replayed.
// never replayed. Optional bodySent: 'none' | 'partial' | 'full', how much
// of the request body (a part's range for a chunked upload) had left when
// the attempt ended.
readonly onAttempt: CodegenTypes.EventEmitter<CodegenTypes.UnsafeObject>;
// The journaled terminal outcome, emitted after the journal write, in the
// ./delivery SettledEvent shape: { eventId, id, key, vars, at, attempts,
Expand All @@ -144,6 +146,14 @@ export interface Spec extends TurboModule {
// layer treats it as 1. No ordering
// guarantee between different ids; the JS layer orders one id's outcomes.
// ./delivery routes it to the definition's handlers.
//
// Optional ambiguousAttempts: attempts of this generation that ended with
// no server answer after the whole request can have reached the server.
// Persisted with the entry; JS reads a missing value as 0. A completed
// outcome whose status was accepted but whose body was not received sets
// response.bodyUnknown to the JSON boolean true and leaves response.body
// out. JS reads any truthy value as the flag. It settles completed, is
// never sent again, and is never the truncated error.
readonly onSettled: CodegenTypes.EventEmitter<CodegenTypes.UnsafeObject>;
readonly onNotification: CodegenTypes.EventEmitter<CodegenTypes.UnsafeObject>;
}
Expand Down
Loading
Loading