@zukhruf/single-flight 0.3.15 → 0.3.16

package/README.md

@@ -1,6 +1,6 @@
 # @zukhruf/single-flight
 
-Callers of one key share the flight in progress, in one process or across the processes of a host. A caller that comes while a flight runs does not start a second flight and does not fail with a "busy" error. It joins the flight and gets its outcome. This pattern is also known as single-flight or request coalescing, as in Go's `golang.org/x/sync/singleflight`.
+Callers of one key share the flight in progress, in one process and across all the processes that use one directory. A caller that comes while a flight runs does not start a second flight and does not fail with a "busy" error. It joins the flight and gets its outcome. This pattern is also known as single-flight or request coalescing, as in Go's `golang.org/x/sync/singleflight`.
 
 The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
 
@@ -14,11 +14,18 @@ A user runs `sync`. A second `sync` starts while the first one runs. The mutex o
 The user wanted a sync to happen. Thus the second `sync` must tell the user that a sync runs, wait for it, and report its outcome. That is a join:
 
 ```ts
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 
 import { SingleFlight } from '@zukhruf/single-flight';
 
-const flights = new SingleFlight<string>();
+const directory = await mkdtemp(join(tmpdir(), 'reports-'));
+const flights = new SingleFlight<string>({
+  directory,
+  codec: { encode: (report) => report, decode: (text) => text },
+});
 let builds = 0;
 
 async function buildReport() {
@@ -33,6 +40,8 @@ const calls = [1, 2, 3].map(() =>
   }),
 );
 console.log(await Promise.all(calls), { builds });
+await flights[Symbol.asyncDispose]();
+await rm(directory, { recursive: true, force: true });
 ```
 
 Output:
@@ -47,7 +56,7 @@ A report is being built. Waiting for it…
 ] { builds: 1 }
 ```
 
-The first caller is the leader: its call runs the flight. The other two callers join it. `onJoin` runs once for each joiner, before it waits. A call after the flight ended starts a new flight: a flight is not a cache. To keep a value after its flight, see the mutex recipe [Compute a value once and share it](../mutex/docs/recipes/compute-once-and-share-it.md).
+The first caller is the leader: its call runs the work of the flight. The other two callers join it. `onJoin` runs once for each joiner, before it waits. A call after the flight ended starts a new flight: a flight is not a cache. To keep a value after its flight, see the mutex recipe [Compute a value once and share it](../mutex/docs/recipes/compute-once-and-share-it.md).
 
 ## Use it
 
@@ -57,126 +66,133 @@ This project is an experiment.
 npm install @zukhruf/single-flight @zukhruf/mutex
 ```
 
-`@zukhruf/mutex` is a peer dependency. `SharedFlight` uses its mutex, and `SingleFlight` does not.
+`@zukhruf/mutex` is a peer dependency. The lease that the work gets, and its token, come from it.
+
+## The directory
+
+The directory is the local folder where the processes that share flights meet. Each process that uses a `SingleFlight` keeps three files there: `flight.lock`, `flight.epoch` and `flight.sock`. All the processes that name the same directory are one group, and the callers of one key share a flight in that group only.
 
-## In one process: `SingleFlight`
+There is no default directory. One default would put each application on the host into one group, and unrelated applications that use the same key would join each other's flights. Give each group its own directory, for example a folder of your application's data.
+
+- The directory must be on a local file system. On a network file system, a call rejects with `NetworkDirectoryError`.
+- On macOS and Linux, the path of `flight.sock` must have 103 bytes or fewer. A longer path throws a `RangeError` when you create the `SingleFlight`. On Windows, the socket is a named pipe, and the length of the directory does not matter.
+- A single flight and a socket lock store of `@zukhruf/mutex` can use one directory. They use different files, and they never meet.
+
+## Run a flight
 
 `flights.run(key, work, { onJoin, signal })` resolves with `{ value, joined }`. `joined` is `false` for the leader and `true` for each joiner.
 
-- A failed flight rejects each caller with the original error of the work.
-- `work` gets a signal that aborts when the flight is abandoned. Read it only when the work can stop early.
+All the processes of the directory take part in one election. The winner is the coordinator. Each call asks the coordinator, in one step, to lead a new flight of the key or to join the flight in progress. When the work of the leader ends, the coordinator pushes the outcome to each joiner. Callers in the same process go through the coordinator too, also in worker threads. [ADR 0003](./docs/adr/0003-a-caller-leads-or-joins-in-one-request-to-an-elected-coordinator.md) tells why.
+
+The work gets the lease of the flight:
+
+- `token`: a fencing token. Its high 32 bits are the epoch of the coordinator's term, so a newer term always gives higher tokens.
+- `signal`: it aborts with `LockLostError` when the flight is no longer the leader's. This occurs when the leader misses the grace window of a new coordinator.
 
-## Across processes: `SharedFlight`
+| Option        | What it does                                                                                                                                                                                   |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `directory`   | The local folder where the processes of one group meet. See [The directory](#the-directory).                                                                                                   |
+| `codec`       | Turns the value of a flight into text for the joiners, and back. See [The codec](#the-codec).                                                                                                  |
+| `graceWindow` | Milliseconds that a new coordinator starts no flight, so the leaders of the flights in progress can reassert them. It must be longer than a process takes to connect again. Defaults to `500`. |
 
-A `SharedFlight` makes a flight visible to the other processes of the host. It uses three parts:
+`flights[Symbol.asyncDispose]()` waits until each landing of this process reached a coordinator, and then it disconnects. When this process is the coordinator, the other processes elect a new one.
 
-- A `SingleFlight`: the callers in one process share one flight first.
-- The mutex: the holder of the key is the leader. The other processes learn that the key is busy.
-- The records: the leader writes the flight record, and joiners in other processes read it.
+## The codec
+
+The value of a flight goes to the joiners as text. The codec has two functions: `encode` turns a value into text, and `decode` turns the text back into a value. The coordinator only carries the text. Thus the format is yours: JSON, or a format that keeps what JSON drops, such as `undefined` and `Map`. The leader gets `decode(encode(value))` too, so each caller gets the value in the same shape.
 
 ```ts
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { Mutex, SqliteStore } from '@zukhruf/mutex';
-import { FileFlightRecords, SharedFlight } from '@zukhruf/single-flight';
-
-const directory = await mkdtemp(join(tmpdir(), 'app-'));
+import { type Codec, SingleFlight } from '@zukhruf/single-flight';
 
-const flights = new SharedFlight({
-  mutex: new Mutex(new SqliteStore(join(directory, 'locks'))),
-  records: new FileFlightRecords(join(directory, 'flights')),
-  parse: (value) => {
-    if (typeof value !== 'string') throw new TypeError('Not a sync summary.');
-    return value;
-  },
-});
+interface Sync {
+  at: Date;
+  files: number;
+}
 
-const { value, joined } = await flights.run(
-  'sync',
-  async () => 'synced 42 files',
-  {
-    onJoin: () => console.log('A sync is running. Waiting for it…'),
+const syncs: Codec<Sync> = {
+  encode: (sync) => JSON.stringify(sync),
+  decode: (text) => {
+    const { at, files } = JSON.parse(text);
+    return { at: new Date(at), files };
   },
-);
-console.log({ value, joined });
+};
+
+const directory = await mkdtemp(join(tmpdir(), 'syncs-'));
+const flights = new SingleFlight({ directory, codec: syncs });
+const { value } = await flights.run('sync', async () => ({
+  at: new Date('2026-10-09T12:00:00Z'),
+  files: 42,
+}));
+console.log(value.at instanceof Date, value.files);
+await flights[Symbol.asyncDispose]();
 await rm(directory, { recursive: true, force: true });
 ```
 
 Output:
 
 ```
-{ value: 'synced 42 files', joined: false }
+true 42
 ```
 
-The program with three processes is in the recipe [Join a run that is still in flight](./docs/recipes/join-a-run-in-flight.md).
-
-| Option         | What it does                                                                                                                                                        |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mutex`        | Decides which caller is the leader. All processes must use one lock directory, with a host lock store such as `SqliteStore`.                                        |
-| `records`      | Keeps the flight records. All processes must use the same records. Give the records a directory of their own, never the lock directory.                             |
-| `parse`        | Turns a value read from a flight record into your type. The value travels as JSON, so a `Date` arrives as a string. The leader also gets `parse` of the JSON value. |
-| `pollInterval` | Milliseconds between two reads of a flight record while a caller joins. Defaults to `100`.                                                                          |
-
-The work gets the lease of the key. A leader whose lease is lost records the flight as interrupted, and the call rejects with the reason of the lease.
-
-A joiner never acquires the key. It reads the flight record until the flight has an outcome, and it asks the mutex only whether a running flight still has a holder. [ADR 0001](./docs/adr/0001-a-joiner-follows-its-flight-record-without-acquiring-the-key.md) tells why.
+A codec that cannot encode the value fails the flight for all callers. A codec that cannot decode the text fails only the call that decodes it.
 
 ## Errors
 
-| The caller is                          | The flight                                             | The call rejects with          |
-| -------------------------------------- | ------------------------------------------------------ | ------------------------------ |
-| The leader, or a joiner in its process | Failed                                                 | The original error of the work |
-| A joiner in another process            | Failed                                                 | `FlightFailedError`            |
-| A joiner in another process            | Interrupted: the holder stopped, or its lease was lost | `FlightInterruptedError`       |
-| A joiner in another process            | Its flight record is gone, before the joiner read it   | `FlightOutcomeLostError`       |
-| The leader, or a joiner in its process | Ended, and the records refused its outcome             | The error of the records       |
-| A joiner in another process            | Ended, and the records refused its outcome             | `FlightInterruptedError`       |
-
-`FlightFailedError` has the `key` and the `failure`: the `name`, the `message` and the `code` of the error. A thrown value that is not an error keeps only its text. A value that JSON cannot carry, such as a `BigInt`, fails the flight.
+| The caller is | The flight                                                      | The call rejects with                                            |
+| ------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
+| The leader    | Its work threw                                                  | The original error of the work                                   |
+| A joiner      | Its work threw                                                  | `FlightFailedError`                                              |
+| A joiner      | Interrupted: the leader's process stopped, or it lost the lease | `FlightInterruptedError`                                         |
+| The leader    | It lost the lease                                               | The reason of the lease's signal: `LockLostError`                |
+| Each caller   | `encode` threw in the leader                                    | The leader: the error of `encode`. A joiner: `FlightFailedError` |
+| One caller    | Its own `decode` threw                                          | The error of `decode`, for that caller only                      |
+| Each caller   | The coordinator speaks another protocol version                 | `ProtocolVersionError`                                           |
+| Each caller   | The directory is on a network file system                       | `NetworkDirectoryError`                                          |
+| Each caller   | The `SingleFlight` is disposed                                  | `Error('This single flight is closed.')`                         |
 
-When the holder of a flight stops and the next holder begins a new flight, the new flight is the successor. A joiner of the stopped flight continues with the successor and gets its outcome.
+A joiner in the leader's own process is a joiner too: it gets `FlightFailedError`, not the original error. `FlightFailedError` has the `key` and the `failure`: the `name`, the `message` and the `code` of the error. A thrown value that is not an error keeps only its text.
 
 ## Cancel a wait
 
-Give a signal to stop the wait of one caller: `flights.run(key, work, { signal: AbortSignal.timeout(30_000) })`. The call rejects with the reason of the signal. The flight continues for the other callers, also when the leader's caller cancels.
+Give a signal to stop the wait of one caller: `flights.run(key, work, { signal: AbortSignal.timeout(30_000) })`. The call rejects with the reason of the signal. The flight continues for the other callers. When the caller of the leader cancels, the work continues and lands for the joiners. A call whose signal aborted before the call rejects at once: it never leads and never joins. [ADR 0004](./docs/adr/0004-a-cancel-withdraws-only-its-caller.md) tells why.
 
-When all callers of a flight cancel, the flight is abandoned:
+## When a process stops
 
-- The next call of the key starts a new flight.
-- In `SingleFlight`, the signal of the work aborts.
-- In `SharedFlight`, a process that joins stops to read the flight record, and it never starts a flight for callers that left. A flight that a process leads continues to its end, because joiners in other processes can wait for its outcome.
+- **The process of a leader stops.** The coordinator tells each joiner that the flight is interrupted, and each joiner rejects with `FlightInterruptedError` at once. No joiner runs the work again. The next call of the key leads a new flight.
+- **The coordinator stops.** The other processes elect a new coordinator. Its term starts with a grace window. In the grace window:
+  - Each leader reasserts its flight, and sends its landing again when it has one.
+  - Each joiner rejoins its flight by the flight's token, and it gets the outcome of that flight.
+  - A new call waits for the grace window to end. Then it leads or joins.
+- **A leader misses the grace window**, for example because its process was frozen. Its lease is lost: the signal of the lease aborts with `LockLostError`, and its call rejects with that error. Its joiners get `FlightInterruptedError`.
+- **A joiner's leader and the coordinator stop together.** The joiner gets `FlightInterruptedError` at the end of the grace window. It never runs the work again.
 
-[ADR 0002](./docs/adr/0002-a-flight-that-all-callers-left-is-abandoned.md) tells how other tools solve this.
+A call that was on its way to a coordinator that stopped joined nothing. It goes again to the next coordinator as a new call. [ADR 0005](./docs/adr/0005-a-joiner-rejoins-its-flight-by-its-token.md) tells why.
 
-## Records
+## Changes from 0.3.x
 
-`new FileFlightRecords(directory, { keepFor })` keeps one JSON file for each key. The name of the file is the SHA-256 of the key, so any key is a valid file name. The leader replaces the file in one step, so a joiner never reads a part of it.
-
-`keepFor` is the keep window, in milliseconds. It defaults to `60_000`. Keep it at least 20 times the `pollInterval` of each joiner. A joiner that reads the flight record after the keep window gets `FlightOutcomeLostError`.
-
-To keep the flight records in another place, for example a table of your database, write your own `FlightRecords`:
-
-```ts
-interface FlightRecords {
-  begin(key: string): Promise<string>;
-  finish(key: string, id: string, outcome: Finished): Promise<void>;
-  latest(key: string): Promise<LatestFlight | undefined>;
-  outcome(key: string, id: string): Promise<Outcome>;
-}
-```
+Version 0.3.13 to 0.3.15 had a pull design. These parts changed:
 
-- `begin` records a new running flight and returns a new id. A flight of the key that is still running becomes interrupted, and the new flight is its successor.
-- `finish` records the outcome. It does nothing when the flight is not running.
-- `outcome` returns `running`, the outcome, or `missing` when the flight record is gone.
-- Only the holder of the key calls `begin` and `finish`. Joiners call only `latest` and `outcome`.
+- `SharedFlight`, `FlightRecords` and `FileFlightRecords` are gone. Each `SingleFlight` now works across processes. Give it a `directory` and a `codec`.
+- `parse` is gone. The `codec` replaces it.
+- The records, `keepFor` and `pollInterval` are gone. The coordinator pushes each outcome, so nothing is kept and nothing is read again. `FlightOutcomeLostError` is gone too.
+- A joiner in the leader's own process now gets `FlightFailedError`, not the original error of the work. Each caller goes through the coordinator.
+- The signal that told the work that all its callers left is gone. The work gets the lease of the flight.
+- A caller whose signal aborted before the call rejects at once.
+- A joiner of an interrupted flight no longer continues with the next flight of the key. It gets `FlightInterruptedError`.
 
 ## Documentation
 
 - [Join a run that is still in flight](./docs/recipes/join-a-run-in-flight.md): three processes, one sync.
-- [ADR 0001: A joiner follows its flight record without acquiring the key](./docs/adr/0001-a-joiner-follows-its-flight-record-without-acquiring-the-key.md)
-- [ADR 0002: A flight that all callers left is abandoned](./docs/adr/0002-a-flight-that-all-callers-left-is-abandoned.md)
+- [ADR 0003: A caller leads or joins in one request to an elected coordinator](./docs/adr/0003-a-caller-leads-or-joins-in-one-request-to-an-elected-coordinator.md)
+- [ADR 0004: A cancel withdraws only its caller](./docs/adr/0004-a-cancel-withdraws-only-its-caller.md)
+- [ADR 0005: A joiner rejoins its flight by its token](./docs/adr/0005-a-joiner-rejoins-its-flight-by-its-token.md)
+- [ADR 0006: The election and the connection are a copy of the mutex code](./docs/adr/0006-the-election-and-the-connection-are-a-copy-of-the-mutex-code.md)
+- [Code copied from the mutex](./docs/copied-from-mutex.md): each copied file, what changed, and why.
+- Superseded: [ADR 0001](./docs/adr/0001-a-joiner-follows-its-flight-record-without-acquiring-the-key.md) and [ADR 0002](./docs/adr/0002-a-flight-that-all-callers-left-is-abandoned.md).
 
 ## Development
 
@@ -189,16 +205,19 @@ npx nx run single-flight:typecheck   # formats, lints, then type checks
 npx nx run single-flight:build       # compiles src/ to dist/
 ```
 
-The tests run from `src/`, not from `dist/`. The tests across processes start `src/testing/caller.fixture.ts` in child processes.
+The tests run from `src/`, not from `dist/`. The tests across processes start the script of `src/testing/caller.ts` in child processes.
 
 ```
 src/
-  single-flight.ts         SingleFlight: the flights of one process
-  flight.ts                one flight of this process and its callers
-  shared-flight.ts         SharedFlight: the leader, and joiners across processes
-  follow.ts                how a joiner finds and follows a flight record
-  flight-records.ts        the FlightRecords interface and the outcomes
-  file-flight-records.ts   FileFlightRecords: one JSON file for each key
-  errors.ts                FlightFailedError, FlightInterruptedError, FlightOutcomeLostError
-  testing/                 the caller process that the tests start
+  single-flight.ts      SingleFlight: each call goes to the coordinator
+  codec.ts              the Codec interface
+  errors.ts             FlightFailedError, FlightInterruptedError
+  client/               the requests of one process: runs, leads, landings
+  coordinator/          the coordinator of one term: flights, sessions, its server
+  protocol/             the messages between a process and its coordinator
+  election/             the election in a directory (a copy of the mutex code)
+  connection/           the socket, the handshake and the supervisor (a copy)
+  local-directory/      the check for a network file system (a copy)
+  shared/               file and SQLite helpers (a copy)
+  testing/              the caller process that the tests start
 ```

package/dist/client/flight-client.d.ts

@@ -0,0 +1,44 @@
+import { FencingToken } from '@zukhruf/mutex';
+import type { ConnectionSupervisor } from '../connection/connection-supervisor.ts';
+import type { FlightRequest, FlightResponse, Outcome } from '../protocol/flight-protocol.ts';
+/** This process leads a flight: it runs the work and lands the outcome. */
+export interface Lead {
+    readonly token: FencingToken;
+    /** Aborts with a `LockLostError` once the flight is no longer this leader's. */
+    readonly signal: AbortSignal;
+    /** Ends the flight with `outcome` for every joiner. Kept and sent again until a coordinator acknowledges it. */
+    land(outcome: Outcome): void;
+}
+/** How the coordinator answered a run for good. */
+export type Answer = {
+    kind: 'lead';
+    lead: Lead;
+} | {
+    kind: 'landed';
+    outcome: Outcome;
+} | {
+    kind: 'interrupted';
+};
+export interface RunRequest {
+    signal?: AbortSignal | undefined;
+    onJoin?: (() => void) | undefined;
+}
+/**
+ * Sends runs to the coordinator over a supervised connection. When the
+ * connection is replaced, it reasserts the flights this process leads, sends
+ * their landings again, and sends again the runs that wait for an answer. A
+ * run that had joined a flight rejoins that flight only, so it never leads; a
+ * run that got no answer had joined nothing, and goes again as a plain run.
+ */
+export declare class FlightClient {
+    #private;
+    constructor(link: ConnectionSupervisor<FlightRequest, FlightResponse>);
+    run(key: string, { signal, onJoin }: RunRequest): Promise<Answer>;
+    /**
+     * Disconnects for good, once every landing reached a coordinator: a landing
+     * is the outcome its joiners wait for. The coordinator then interrupts the
+     * flights this process still leads without an outcome.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=flight-client.d.ts.map

package/dist/client/flight-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-client.d.ts","sourceRoot":"","sources":["../../src/client/flight-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAiB,MAAM,gBAAgB,CAAC;AAE7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AACnF,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,OAAO,EACR,MAAM,gCAAgC,CAAC;AAExC,2EAA2E;AAC3E,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,gHAAgH;IAChH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED,mDAAmD;AACnD,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAE5B,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACnC;AAuBD;;;;;;GAMG;AACH,qBAAa,YAAY;;gBAOX,IAAI,EAAE,oBAAoB,CAAC,aAAa,EAAE,cAAc,CAAC;IAQ/D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA2BvE;;;;OAIG;IACG,KAAK;CAiKZ"}

package/dist/client/flight-client.js

@@ -0,0 +1,222 @@
+import { randomUUID } from 'node:crypto';
+import { untilAborted } from '@zukhruf/async';
+import { FencingToken, LockLostError } from '@zukhruf/mutex';
+/**
+ * Sends runs to the coordinator over a supervised connection. When the
+ * connection is replaced, it reasserts the flights this process leads, sends
+ * their landings again, and sends again the runs that wait for an answer. A
+ * run that had joined a flight rejoins that flight only, so it never leads; a
+ * run that got no answer had joined nothing, and goes again as a plain run.
+ */
+export class FlightClient {
+    #link;
+    #pending = new Map();
+    #held = new Map();
+    /** Wakes `close` each time a flight this process leads is acknowledged or lost. */
+    #released = new Set();
+    constructor(link) {
+        this.#link = link;
+        link.on('connected', () => this.#resume());
+        link.on('message', (response) => this.#receive(response));
+        link.on('disconnected', () => this.#interrupt());
+        link.on('failed', (error) => this.#fail(error));
+    }
+    async run(key, { signal, onJoin }) {
+        signal?.throwIfAborted();
+        if (this.#link.status === 'closed') {
+            throw new Error('This single flight is closed.');
+        }
+        const id = randomUUID();
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const pending = {
+            key,
+            onJoin,
+            delivery: 'queued',
+            flight: undefined,
+            resolve,
+            reject,
+        };
+        this.#pending.set(id, pending);
+        this.#updateRef();
+        this.#link.open();
+        this.#dispatch(id, pending);
+        try {
+            return await untilAborted(promise, signal);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                this.#withdraw(id);
+            throw error;
+        }
+    }
+    /**
+     * Disconnects for good, once every landing reached a coordinator: a landing
+     * is the outcome its joiners wait for. The coordinator then interrupts the
+     * flights this process still leads without an outcome.
+     */
+    async close() {
+        while ([...this.#held.values()].some(({ landing }) => landing)) {
+            await new Promise((resolve) => this.#released.add(resolve));
+        }
+        const closing = this.#link.close();
+        for (const id of [...this.#pending.keys()]) {
+            this.#take(id)?.reject(new Error('This single flight is closed.'));
+        }
+        await closing;
+    }
+    #dispatch(id, pending) {
+        const { key, flight } = pending;
+        const request = flight === undefined
+            ? { op: 'run', id, key }
+            : { op: 'run', id, key, flight };
+        if (this.#link.send(request))
+            pending.delivery = 'sent';
+    }
+    /**
+     * The caller gave up. A run the coordinator may have heard is withdrawn;
+     * one that already leads is not pending any more, so its flight runs on.
+     */
+    #withdraw(id) {
+        const pending = this.#take(id);
+        if (pending?.delivery === 'sent')
+            this.#link.send({ op: 'cancel', id });
+    }
+    #hold(id, key, token) {
+        const held = {
+            key,
+            token,
+            lost: new AbortController(),
+            landing: undefined,
+        };
+        this.#held.set(id, held);
+        return {
+            token,
+            signal: held.lost.signal,
+            land: (outcome) => {
+                // A lost flight is no longer this leader's to land.
+                if (this.#held.get(id) !== held || held.landing)
+                    return;
+                held.landing = outcome;
+                this.#updateRef();
+                this.#link.send({ op: 'land', id, outcome });
+            },
+        };
+    }
+    /** The flight of `id` is no longer this leader's, so its lease is told and nothing reasserts it. */
+    #lose(id) {
+        const held = this.#held.get(id);
+        if (!held)
+            return;
+        this.#release(id);
+        held.lost.abort(new LockLostError(held.key));
+    }
+    /** The flight of `id` needs nothing more from this process. */
+    #release(id) {
+        this.#held.delete(id);
+        this.#updateRef();
+        const waiting = [...this.#released];
+        this.#released.clear();
+        for (const wake of waiting)
+            wake();
+    }
+    #receive(response) {
+        switch (response.op) {
+            case 'lead': {
+                // A run withdrawn meanwhile sent `cancel`, which interrupts the flight at the coordinator.
+                const pending = this.#take(response.id);
+                if (!pending)
+                    return;
+                const token = new FencingToken(BigInt(response.token));
+                pending.resolve({
+                    kind: 'lead',
+                    lead: this.#hold(response.id, pending.key, token),
+                });
+                return;
+            }
+            case 'joined': {
+                const pending = this.#pending.get(response.id);
+                if (!pending)
+                    return;
+                const first = pending.flight === undefined;
+                pending.flight = response.flight;
+                if (first)
+                    this.#tellJoined(response.id, pending);
+                return;
+            }
+            case 'landed':
+                this.#take(response.id)?.resolve({
+                    kind: 'landed',
+                    outcome: response.outcome,
+                });
+                return;
+            case 'interrupted':
+                this.#take(response.id)?.resolve({ kind: 'interrupted' });
+                return;
+            case 'ack':
+                // The joiners have the outcome, so there is nothing left to reassert.
+                if (this.#held.get(response.id)?.landing)
+                    this.#release(response.id);
+                return;
+            case 'rejected':
+                this.#lose(response.id);
+                return;
+            case 'unsupported':
+                this.#take(response.id)?.reject(new Error("The single flight's coordinator does not know a run."));
+                return;
+        }
+    }
+    /** The caller's `onJoin` runs once per run; a throw from it fails that run only. */
+    #tellJoined(id, pending) {
+        try {
+            pending.onJoin?.();
+        }
+        catch (error) {
+            this.#withdraw(id);
+            pending.reject(error);
+        }
+    }
+    /** A new connection: reassert the flights this process leads and land them again, then send what waits. */
+    #resume() {
+        // A new connection starts with its adapter's default, which may not match whether this client waits.
+        this.#updateRef();
+        for (const [id, { key, token, landing }] of this.#held) {
+            this.#link.send({ op: 'reassert', id, key, token: token.toString() });
+            if (landing)
+                this.#link.send({ op: 'land', id, outcome: landing });
+        }
+        for (const [id, pending] of this.#pending) {
+            if (pending.delivery === 'queued')
+                this.#dispatch(id, pending);
+        }
+    }
+    /** Nothing sent on the lost connection will be answered, so every run goes again on the next one. */
+    #interrupt() {
+        for (const pending of this.#pending.values())
+            pending.delivery = 'queued';
+    }
+    /** No coordinator heard the reassertions, so the flights this process leads may be interrupted already. */
+    #fail(error) {
+        for (const id of [...this.#held.keys()])
+            this.#lose(id);
+        for (const id of [...this.#pending.keys()])
+            this.#take(id)?.reject(error);
+    }
+    /** Removes a run that is about to be answered, so a late answer for it is ignored. */
+    #take(id) {
+        const pending = this.#pending.get(id);
+        if (!pending)
+            return undefined;
+        this.#pending.delete(id);
+        this.#updateRef();
+        return pending;
+    }
+    /** A run waiting for its answer, or a landing not yet acknowledged, keeps the process alive. */
+    #updateRef() {
+        const landing = [...this.#held.values()].some(({ landing }) => landing);
+        if (this.#pending.size > 0 || landing)
+            this.#link.ref();
+        else
+            this.#link.unref();
+    }
+}
+//# sourceMappingURL=flight-client.js.map

package/dist/client/flight-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-client.js","sourceRoot":"","sources":["../../src/client/flight-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAkD7D;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAsD;IAC3D,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IACtC,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IACzC,mFAAmF;IAC1E,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAE3C,YAAY,IAAyD;QACnE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,EAAE,MAAM,EAAE,MAAM,EAAc;QACnD,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;QACxB,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,EAAU,CAAC;QACrE,MAAM,OAAO,GAAY;YACvB,GAAG;YACH,MAAM;YACN,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,SAAS;YACjB,OAAO;YACP,MAAM;SACP,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC5B,IAAI,CAAC;YACH,OAAO,MAAM,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,EAAE,OAAO;gBAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACxC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnC,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,OAAO,CAAC;IAChB,CAAC;IAED,SAAS,CAAC,EAAU,EAAE,OAAgB;QACpC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAChC,MAAM,OAAO,GACX,MAAM,KAAK,SAAS;YAClB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE;YACxB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,EAAU;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,OAAO,EAAE,QAAQ,KAAK,MAAM;YAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,EAAU,EAAE,GAAW,EAAE,KAAmB;QAChD,MAAM,IAAI,GAAS;YACjB,GAAG;YACH,KAAK;YACL,IAAI,EAAE,IAAI,eAAe,EAAE;YAC3B,OAAO,EAAE,SAAS;SACnB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACzB,OAAO;YACL,KAAK;YACL,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;YACxB,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE;gBAChB,oDAAoD;gBACpD,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO;oBAAE,OAAO;gBACxD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;gBACvB,IAAI,CAAC,UAAU,EAAE,CAAC;gBAClB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAC/C,CAAC;SACF,CAAC;IACJ,CAAC;IAED,oGAAoG;IACpG,KAAK,CAAC,EAAU;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,+DAA+D;IAC/D,QAAQ,CAAC,EAAU;QACjB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,OAAO;YAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IAED,QAAQ,CAAC,QAAwB;QAC/B,QAAQ,QAAQ,CAAC,EAAE,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,2FAA2F;gBAC3F,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBACxC,IAAI,CAAC,OAAO;oBAAE,OAAO;gBACrB,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;gBACvD,OAAO,CAAC,OAAO,CAAC;oBACd,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC;iBAClD,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAC/C,IAAI,CAAC,OAAO;oBAAE,OAAO;gBACrB,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC;gBAC3C,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;gBACjC,IAAI,KAAK;oBAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;gBAClD,OAAO;YACT,CAAC;YACD,KAAK,QAAQ;gBACX,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;oBAC/B,IAAI,EAAE,QAAQ;oBACd,OAAO,EAAE,QAAQ,CAAC,OAAO;iBAC1B,CAAC,CAAC;gBACH,OAAO;YACT,KAAK,aAAa;gBAChB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC1D,OAAO;YACT,KAAK,KAAK;gBACR,sEAAsE;gBACtE,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO;oBAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBACrE,OAAO;YACT,KAAK,UAAU;gBACb,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBACxB,OAAO;YACT,KAAK,aAAa;gBAChB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAC7B,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAClE,CAAC;gBACF,OAAO;QACX,CAAC;IACH,CAAC;IAED,oFAAoF;IACpF,WAAW,CAAC,EAAU,EAAE,OAAgB;QACtC,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,2GAA2G;IAC3G,OAAO;QACL,qGAAqG;QACrG,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACvD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YACtE,IAAI,OAAO;gBAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1C,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;gBAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,qGAAqG;IACrG,UAAU;QACR,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE;YAAE,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC5E,CAAC;IAED,2GAA2G;IAC3G,KAAK,CAAC,KAAc;QAClB,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACxD,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5E,CAAC;IAED,sFAAsF;IACtF,KAAK,CAAC,EAAU;QACd,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAC/B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,gGAAgG;IAChG,UAAU;QACR,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;QACxE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;;YACnD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/codec.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Turns a flight's value into text and back. The value crosses to the
+ * processes whose callers joined the flight, and the coordinator only carries
+ * the text, so the format is the caller's: JSON, or any other that keeps what
+ * JSON would drop. The leader gets `decode(encode(value))` too, so every
+ * caller sees the value in the same shape.
+ */
+export interface Codec<T> {
+    encode(value: T): string;
+    decode(text: string): T;
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;CACzB"}

package/dist/codec.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":""}