@abide/abide 0.114.1 → 0.115.0

package/src/ui/outboxQueue.ts

@@ -0,0 +1,427 @@
+// 46 — THE BROWSER'S OUTBOX: the mutation calls a page could not deliver, kept on the device and sent
+// once the network answers, oldest first and one at a time, by one tab for all of them.
+//
+// KEPT IN IndexedDB, where the browser has it (46.2): the one store a page can write that outlives
+// it, holds what JSON cannot (a photo's bytes ride in a call's args), and the worker can read too.
+// Where there is none — a DOM emulator — the calls are kept in memory, which is the same queue for
+// as long as the page lives.
+//
+// WHAT `outbox` SHOWS IS WHAT IS KEPT: every change is written first and published after, so a
+// reader is never shown a call a reload would lose.
+
+import {
+    type Answer,
+    answered as answeredValue,
+    answerOf,
+    unanswered,
+} from '#shared/answerOf.ts'
+import { failedFrom, isFailed, problemOf } from '#shared/Failed.ts'
+import type { Problem } from '#shared/Failed.ts'
+import { type ShownCall, showLine, showSending } from '#shared/outbox.ts'
+import { onPrincipalRotated } from '#shared/principalRotated.ts'
+import {
+    isReactive,
+    produceInto,
+    type Reactive,
+    reactive,
+    refuseInto,
+    standIn,
+} from '#shared/reactive/index.ts'
+import { rpcRequest } from '#shared/rpcRequest.ts'
+
+const DATABASE = 'abide-outbox'
+/** The `localStorage` key set while the line holds a call, so a page with none opens no database. */
+const MARKER = 'abide-outbox'
+const STORE = 'calls'
+const CHANNEL = 'abide-outbox'
+const RETRY_FLOOR_MS = 1_000
+const RETRY_CEILING_MS = 60_000
+
+/** One call as it is kept: what `outbox` shows of it, its place in line, and how it was refused. */
+type Kept = Omit<ShownCall, 'value' | 'retry' | 'discard'> & {
+    seq: number | undefined
+    error: Problem | undefined
+    /** 46.19 — what the call settled to, where the browser could keep it. */
+    standIn: unknown
+}
+
+/** Where the calls are kept: IndexedDB where the browser has it, this page's memory where not. */
+type Shelf = {
+    load(): Promise<Kept[]>
+    add(call: Kept): Promise<number>
+    put(call: Kept): Promise<void>
+    remove(seq: number): Promise<void>
+}
+
+/** The line, oldest first, as this tab last read it. */
+let LINE: Kept[] = []
+/** Whether this tab is sending. */
+let sending = false
+/** 46.6 — a call refused 401 holds the line until `principal` changes or `retry` is called. */
+let held = false
+let retrying: ReturnType<typeof setTimeout> | undefined
+let backoff = RETRY_FLOOR_MS
+let askedToPersist = false
+/**
+ * The value each call stands in for, by its id: the one its call settled, where this page made it,
+ * and one rebuilt from what was kept where not (46.18) — what `outbox` shows as `value`, and what
+ * the answer lands in (46.7). Held for as long as the call is in the line.
+ */
+const VALUES = new Map<string, Reactive<unknown>>()
+/** What wants to hear the line empty of calls not yet delivered (18.35). */
+const DRAINED: (() => void)[] = []
+
+const shelf: Shelf =
+    typeof indexedDB === 'undefined' ? memoryShelf() : databaseShelf()
+const channel =
+    typeof BroadcastChannel === 'undefined'
+        ? undefined
+        : new BroadcastChannel(CHANNEL)
+
+/** The calls not yet delivered: what is waiting, as against what was refused. */
+export function undelivered(): number {
+    let count = 0
+    for (const call of LINE) if (call.error === undefined) count += 1
+    return count
+}
+
+/** Runs `listener` each time the line holds no call waiting to be delivered (18.35). */
+export function whenDelivered(listener: () => void): void {
+    DRAINED.push(listener)
+}
+
+/**
+ * Queues a call that could not be delivered; answers whether it is kept (16.82).
+ *
+ * `standing` holds the value the call settled, and `settledTo` is the stand-in it settled to.
+ */
+export async function enqueue(
+    call: Pick<Kept, 'id' | 'method' | 'address' | 'url' | 'args'>,
+    standing: { value: unknown },
+    settledTo: unknown,
+): Promise<boolean> {
+    const kept: Kept = {
+        seq: undefined,
+        ...call,
+        queuedAt: Date.now(),
+        attempts: 1,
+        error: undefined,
+        standIn: settledTo,
+    }
+    try {
+        kept.seq = await shelf.add(kept)
+    } catch (refused) {
+        // 46.19 — A STAND-IN THE BROWSER CANNOT KEEP — a function, a DOM node — is left out, and the
+        // call is kept without it; anything else that stops the write stops the call (16.82).
+        if ((refused as { name?: string })?.name !== 'DataCloneError')
+            return false
+        kept.standIn = undefined
+        try {
+            kept.seq = await shelf.add(kept)
+        } catch {
+            return false
+        }
+    }
+    const reached = standing.value
+    if (isReactive(reached)) VALUES.set(call.id, reached as Reactive<unknown>)
+    LINE.push(kept)
+    publish()
+    changed()
+    // 46.14 — a call waiting on the network is one the browser must not clear to make room.
+    if (!askedToPersist) {
+        askedToPersist = true
+        void navigator.storage?.persist?.().catch(() => {})
+    }
+    retryLater()
+    return true
+}
+
+/** Sends every call waiting, oldest first and one at a time, where this tab may (46.3, 46.9). */
+export function deliver(): void {
+    // Another tab's calls reach this one's line through `changed`, and an earlier visit's at boot.
+    if (sending || held || undelivered() === 0) return
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) return
+    // Where there is none — a DOM emulator's is `null` — this tab is the only one there is to ask.
+    const locks = (navigator as { locks?: LockManager | null }).locks
+    if (locks === undefined || locks === null) {
+        void sendLine()
+        return
+    }
+    void locks
+        .request(DATABASE, { ifAvailable: true }, async (lock) => {
+            if (lock !== null) await sendLine()
+        })
+        .catch(() => {})
+}
+
+async function sendLine(): Promise<void> {
+    sending = true
+    try {
+        // Another tab may have sent or queued since this one last read the line.
+        LINE = await shelf.load()
+        publish()
+        for (const call of [...LINE]) {
+            if (call.error !== undefined) continue
+            // 46.13 — a call discarded since the line was read is not sent.
+            if (!LINE.some((each) => each.id === call.id)) continue
+            showSending(call)
+            const answer = await send(call)
+            showSending(undefined)
+            if (unanswered(answer)) {
+                call.attempts += 1
+                await shelf.put(call)
+                publish()
+                retryLater()
+                return
+            }
+            const value = answeredValue(answer)
+            if (isFailed(value)) {
+                call.error = problemOf(value)
+                await shelf.put(call)
+                publish()
+                refuseInto(valueStanding(call), value)
+                // 46.6 — whoever is signed in has to change before the line can go on.
+                if (value.status === 401) {
+                    held = true
+                    return
+                }
+                continue
+            }
+            await shelf.remove(call.seq as number)
+            LINE = LINE.filter((each) => each.id !== call.id)
+            publish()
+            produceInto(valueStanding(call), value)
+            VALUES.delete(call.id)
+        }
+        backoff = RETRY_FLOOR_MS
+    } catch {
+        retryLater()
+    } finally {
+        sending = false
+        showSending(undefined)
+        changed()
+    }
+}
+
+/** One send of a call, carrying the key it carries every time (46.10). */
+async function send(call: Kept): Promise<Answer> {
+    const request = rpcRequest(call.method, call.address, call.args, 'no-store')
+    request.init.headers = {
+        ...(request.init.headers as Record<string, string> | undefined),
+        'idempotency-key': call.id,
+    }
+    return await answerOf(request, false, undefined)
+}
+
+/**
+ * The value `kept` stands in for: this page's own, or one rebuilt from what was kept (46.18) —
+ * written here, so its `synced` is false (46.19), and refused where the call was.
+ */
+function valueStanding(kept: Kept): Reactive<unknown> {
+    let value = VALUES.get(kept.id)
+    if (value === undefined) {
+        const settled = kept.standIn
+        value = reactive(() => standIn(settled)) as Reactive<unknown>
+        // Landed now, so a refusal written below is not cleared by the body's first run (4.11).
+        value.peek()
+        if (kept.error !== undefined) refuseInto(value, failedFrom(kept.error))
+        VALUES.set(kept.id, value)
+    }
+    return value
+}
+
+/** 46.8 — the next try, backing off from a second to a minute while nothing answers. */
+function retryLater(): void {
+    clearTimeout(retrying)
+    retrying = setTimeout(() => {
+        retrying = undefined
+        deliver()
+    }, backoff)
+    backoff = Math.min(backoff * 2, RETRY_CEILING_MS)
+}
+
+/** Whether the line last held a call waiting, so the move to none is heard once. */
+let waiting = false
+
+/** Shows the line as `outbox` answers it, and tells who asked once nothing is waiting (18.35). */
+function publish(): void {
+    const now = undelivered() !== 0
+    if (waiting && !now)
+        queueMicrotask(() => {
+            for (const listener of DRAINED) listener()
+        })
+    waiting = now
+    mark(LINE.length !== 0)
+    const calls: ShownCall[] = []
+    for (const call of LINE) {
+        const id = call.id
+        calls.push({
+            id,
+            method: call.method,
+            address: call.address,
+            url: call.url,
+            args: call.args,
+            queuedAt: call.queuedAt,
+            attempts: call.attempts,
+            value: valueStanding(call),
+            retry: () => void retry(id),
+            discard: () => void discard(id),
+        })
+    }
+    showLine(calls)
+}
+
+/**
+ * Says whether the line holds a call, for the next page this browser opens to read before it opens
+ * the database (`listen`). Written on every change rather than when it flips: another tab may have
+ * emptied the line since this one last wrote it.
+ */
+function mark(holds: boolean): void {
+    try {
+        if (holds) localStorage.setItem(MARKER, '1')
+        else localStorage.removeItem(MARKER)
+    } catch {}
+}
+
+/** Whether the line held a call when it last changed — `true` where `localStorage` cannot say. */
+function marked(): boolean {
+    try {
+        return localStorage.getItem(MARKER) !== null
+    } catch {
+        return true
+    }
+}
+
+/** 46.9 — tells every other tab the line moved, so each shows the one line. */
+function changed(): void {
+    channel?.postMessage('changed')
+}
+
+async function reread(): Promise<void> {
+    LINE = await shelf.load()
+    publish()
+}
+
+/** 46.12 — sends the call `id` names again, at once, and lets go of a line 46.6 held. */
+async function retry(id: string): Promise<void> {
+    held = false
+    for (const call of LINE)
+        if (call.id === id && call.error !== undefined) {
+            call.error = undefined
+            await shelf.put(call)
+            // An accepted write clears the refusal (4.11) and is a write here, so the value is
+            // waiting again rather than refused, and still not the server's.
+            const value = valueStanding(call)
+            value.set(value.peek())
+        }
+    publish()
+    changed()
+    backoff = RETRY_FLOOR_MS
+    deliver()
+}
+
+/** 46.13 — drops the call `id` names, sent or not. */
+async function discard(id: string): Promise<void> {
+    const kept: Kept[] = []
+    for (const call of LINE) {
+        if (call.id === id) {
+            await shelf.remove(call.seq as number)
+            VALUES.delete(call.id)
+        } else kept.push(call)
+    }
+    LINE = kept
+    publish()
+    changed()
+}
+
+function memoryShelf(): Shelf {
+    const calls = new Map<number, Kept>()
+    let next = 1
+    return {
+        load: async () => [...calls.values()].map((call) => ({ ...call })),
+        add: async (call) => {
+            const seq = next
+            next += 1
+            calls.set(seq, { ...call, seq })
+            return seq
+        },
+        put: async (call) => {
+            calls.set(call.seq as number, { ...call })
+        },
+        remove: async (seq) => {
+            calls.delete(seq)
+        },
+    }
+}
+
+function databaseShelf(): Shelf {
+    let opening: Promise<IDBDatabase> | undefined
+    const database = (): Promise<IDBDatabase> => {
+        opening ??= new Promise((resolve, reject) => {
+            const asked = indexedDB.open(DATABASE, 1)
+            asked.onupgradeneeded = () =>
+                asked.result.createObjectStore(STORE, {
+                    keyPath: 'seq',
+                    autoIncrement: true,
+                })
+            asked.onsuccess = () => resolve(asked.result)
+            asked.onerror = () => reject(asked.error)
+        })
+        return opening
+    }
+    const inStore = async <Result>(
+        mode: IDBTransactionMode,
+        work: (store: IDBObjectStore) => IDBRequest<Result>,
+    ): Promise<Result> => {
+        const store = (await database())
+            .transaction(STORE, mode)
+            .objectStore(STORE)
+        return new Promise((resolve, reject) => {
+            const request = work(store)
+            request.onsuccess = () => resolve(request.result)
+            request.onerror = () => reject(request.error)
+        })
+    }
+    return {
+        load: () => inStore('readonly', (store) => store.getAll()),
+        add: async (call) => {
+            const { seq: _, ...unnumbered } = call
+            return (await inStore('readwrite', (store) =>
+                store.add(unnumbered),
+            )) as number
+        },
+        put: async (call) => {
+            await inStore('readwrite', (store) => store.put(call))
+        },
+        remove: async (seq) => {
+            await inStore('readwrite', (store) => store.delete(seq))
+        },
+    }
+}
+
+/**
+ * Reads the line kept, and sends on what 46.8 names.
+ *
+ * 46.8 — WHAT SENDS: the page arriving with calls kept, the network coming back, the page coming into
+ * view, and `principal` changing, which also lets go of a line 46.6 held.
+ */
+function listen(): void {
+    if (typeof window === 'undefined') return
+    // 46.2, 46.20 — a line kept from an earlier visit, read where one was left: a page with no call kept
+    // opens no database, which costs every page with a handler a read before it hydrates.
+    if (marked()) void reread().then(deliver, () => {})
+    window.addEventListener('online', () => {
+        backoff = RETRY_FLOOR_MS
+        deliver()
+    })
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible') deliver()
+    })
+    onPrincipalRotated(() => {
+        held = false
+        deliver()
+    }, true)
+    channel?.addEventListener('message', () => void reread())
+}
+
+listen()

package/src/ui/socketWire.ts

@@ -8,13 +8,17 @@ import { canonicalKey } from '#shared/reactive/canonicalKey.ts'
 import {
     heldGenerationOf,
     loadOf,
+    patchInto,
+    produceInto,
     type Reactive,
+    writtenLocally,
 } from '#shared/reactive/index.ts'
 import { PATCHES } from '#shared/reactive/PATCHES.ts'
 import type { BrowserFrame, ServerFrame } from '#shared/muxFrames.ts'
 import { applyPatch } from '#shared/applyPatch.ts'
 import { onPrincipalRotated } from '#shared/principalRotated.ts'
 import { HYDRATE_LOG } from './Mismatch.ts'
+import { undelivered, whenDelivered } from './outboxQueue.ts'
 
 const RETRY_FLOOR_MS = 250
 const RETRY_CEILING_MS = 10_000
@@ -104,9 +108,18 @@ class Following {
 
     receive(frame: ServerFrame): void {
         const copy = this.entry() as Reactive<unknown>
+        // 18.35 — A COPY WRITTEN HERE WAITS OUT THE CALLS THAT WROTE IT: what the server sends before
+        // they are delivered is the value without them, and taking it would undo what is on screen.
+        if (
+            (frame.op === 'value' || frame.op === 'patch') &&
+            writtenLocally(copy) &&
+            undelivered() !== 0
+        )
+            return
         if (frame.op === 'value') {
             this.version = frame.version
-            copy.set(frame.value)
+            // 18.10 — the server's value is the copy's producer's, not a write made here (3.11).
+            produceInto(copy, frame.value)
             this.inStep()
         } else if (frame.op === 'patch') {
             // 18.12 — WRITES MADE OVER ANOTHER VERSION WOULD LAND SOMEWHERE ELSE, and 18.21 over a
@@ -116,7 +129,7 @@ class Following {
                 copy.refresh()
             else {
                 this.version = frame.version
-                copy.patch((value) => applyPatch(value, frame.ops ?? []))
+                patchInto(copy, (value) => applyPatch(value, frame.ops ?? []))
                 this.inStep()
             }
         } else if (frame.op === 'invalidate') copy.invalidate()
@@ -246,6 +259,8 @@ function muxFor(address: string): Mux {
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
     let mux = MUXES.get(url.href)
     if (mux === undefined) {
+        // Heard from the first follow on, which is the first copy it could read again.
+        if (MUXES.size === 0) whenDelivered(readAgainWritten)
         mux = new Mux(url.href)
         MUXES.set(url.href, mux)
     }
@@ -260,6 +275,20 @@ function muxFor(address: string): Mux {
  */
 const FOLLOWING = new Map<string, Following>()
 
+/**
+ * Reads again every followed copy written here, once the outbox holds no call waiting.
+ *
+ * 18.35 — the server's value, with every queued call that was delivered in it and none of one it
+ * refused. Every such copy, not only one a frame was held back from: a refused call may have left
+ * the server with nothing to send.
+ */
+function readAgainWritten(): void {
+    for (const following of FOLLOWING.values()) {
+        const copy = following.entry() as Reactive<unknown>
+        if (writtenLocally(copy)) copy.refresh()
+    }
+}
+
 /**
  * Follows a loaded `GET`'s copy over the mux, raising its version and resetting its expiry.
  *

package/src/ui/wire.ts

@@ -17,19 +17,28 @@
 // An entry of its own (`@abide/abide/wire`) rather than a name on the runtime barrel: only a generated
 // wrapper imports it, and a page with no handler pays nothing for it.
 
-import { type Answer, answered, answerOf } from '#shared/answerOf.ts'
+import {
+    type Answer,
+    answered,
+    answerOf,
+    noAnswer,
+    unanswered,
+} from '#shared/answerOf.ts'
 import type { CopyOptions } from '#shared/CopyOptions.ts'
 import { isFailed } from '#shared/Failed.ts'
 import { answerChunks } from '#shared/framing.ts'
 import { HandlerRoute } from '#shared/HandlerRoute.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
+import { LOAD_OFFLINE } from '#shared/LOAD_OFFLINE.ts'
 import { LOAD_SIGNAL } from '#shared/LOAD_SIGNAL.ts'
-import { reactive, structural } from '#shared/reactive/index.ts'
+import { reactive, standIn, structural } from '#shared/reactive/index.ts'
 import {
     type Defaults,
     declareDefaults,
 } from '#shared/reactive/parameterDefaults.ts'
 import { declare, type Method } from '#shared/rpc.ts'
-import { rpcRequest } from '#shared/rpcRequest.ts'
+import { type RpcRequest, rpcRequest } from '#shared/rpcRequest.ts'
+import { enqueue, undelivered } from './outboxQueue.ts'
 import { followRpc } from './socketWire.ts'
 
 /** The browser's `Rpc` for a handler: the server's declaration over a body that fetches. */
@@ -43,18 +52,90 @@ export function wire(
 ): unknown {
     // 16.9 — the handler's route, compiled once for every call through the copy.
     const route = new HandlerRoute(address)
+    // 16.80 — the requests this page has had an answer to, whose next load asks past every cache.
+    // A first load is the worker's to answer from its copy, where one answers this page: anywhere
+    // else the cache below is the browser's, which would hand back a week-stale answer as the server's.
+    const answeredOnce = new Set<string>()
+    const requestOf = (args: Record<string, unknown> | undefined) => {
+        const request = rpcRequest(method, route, args)
+        if (
+            !answeredOnce.has(request.key) &&
+            navigator.serviceWorker?.controller
+        )
+            request.init.cache = 'force-cache'
+        return request
+    }
+    // 16.81 — WHAT STANDS IN FOR A `GET`'s ANSWER, per args, as the last call reaching them gave it:
+    // a reload no call starts — a refresh, the network coming back — has no `offline` of its own.
+    const standIns = new Map<string, (args: unknown) => unknown>()
     // ONE PARAMETER, so the value is keyed by args whatever the handler declared (16.6's arity rule):
     // an unkeyed handler is reached with no args, which is one key.
     const body = (args: Record<string, unknown> | undefined) => {
-        // 16.49 — the load's own signal, set by the call starting it and read before anything awaits.
+        // 16.49, 16.81 — the load's own signal and stand-in, set by the call starting it and read
+        // before anything awaits.
         const signal = LOAD_SIGNAL.current
+        const request = requestOf(args)
+        let offline = LOAD_OFFLINE.current
+        // A reload no call started — a refresh, or the one `whenOnline` asks — that gets no answer
+        // waits before asking again, where asking at once would get none on every tick.
+        const retryIn = offline === undefined ? UNANSWERED_RETRY_MS : 0
+        if (method === 'GET') {
+            if (offline === undefined) offline = standIns.get(request.key)
+            else standIns.set(request.key, offline)
+        }
+        // A STAND-IN IS FOR A COPY HOLDING NOTHING: a reload that gets no answer over one this page
+        // already holds keeps serving it (7.4, 7.19) rather than trading it for a default.
+        const first = !answeredOnce.has(request.key)
+        // 16.82, 46.10 — a mutation that may be queued carries the key it is sent under every time.
+        const queued =
+            offline !== undefined && method !== 'GET'
+                ? queuedCall(request, address, args)
+                : undefined
+        let standing: { value: unknown } | undefined
+        if (queued !== undefined)
+            LOAD_OFFLINE.standing = standing = { value: undefined }
+        const stoodIn = (failed: Answer): unknown => {
+            const value = (offline as (args: unknown) => unknown)(args)
+            if (queued === undefined) {
+                whenOnline(args, retryIn)
+                return standIn(value)
+            }
+            return enqueue(queued, standing as { value: unknown }, value).then(
+                (kept) => (kept ? standIn(value) : answered(failed)),
+            )
+        }
+        // 16.83 — BEHIND CALLS NOT YET DELIVERED A CALL WAITS ITS TURN, rather than overtaking them.
+        if (queued !== undefined && undelivered() !== 0)
+            return Promise.resolve(stoodIn(noAnswer()))
         const settle = (answer: Answer): unknown => {
+            if (answer.ok) answeredOnce.add(request.key)
+            if (
+                offline !== undefined &&
+                unanswered(answer) &&
+                (first || queued !== undefined)
+            )
+                return stoodIn(answer)
             follow(args, answer)
+            // 16.85 — A COPY THE WORKER KEPT IS NOT THE SERVER'S ANSWER: held as written here, and
+            // asked of the network once there is one.
+            if (answer.kept) {
+                whenOnline(args, 0)
+                return standIn(answered(answer))
+            }
             return answered(answer)
         }
-        const answer = answerOf(rpcRequest(method, route, args), false, signal)
+        const answer = answerOf(request, false, signal)
         return answer instanceof Promise ? answer.then(settle) : settle(answer)
     }
+    // 16.81, 16.85 — A COPY HOLDING A STAND-IN ASKS THE NETWORK AGAIN once there is one: now, past the
+    // landing (or `delay` past it), where the browser says it is online, and when it says so otherwise.
+    const whenOnline = (args: unknown, delay: number): void => {
+        if (method !== 'GET') return
+        const again = (): void =>
+            (value as (args: unknown) => { refresh(): void })(args).refresh()
+        if (navigator.onLine) setTimeout(again, delay)
+        else addEventListener('online', again, { once: true })
+    }
     // 16.32 — A STREAMING HANDLER'S COPY IS A STREAM OF ITS OWN, whose chunks land as the answer's
     // lines arrive: collected into one value, a page reading it showed nothing until the handler's
     // last chunk. A refusal is thrown, which is how a stream refuses (9.6).
@@ -64,11 +145,9 @@ export function wire(
         // 16.49 — read on the first line: the core's pump takes the first step inside the reach, so
         // this runs while the call that started the load still has its signal set.
         const signal = LOAD_SIGNAL.current
-        const answer = await answerOf(
-            rpcRequest(method, route, args),
-            true,
-            signal,
-        )
+        const request = requestOf(args)
+        const answer = await answerOf(request, true, signal)
+        if (answer.ok) answeredOnce.add(request.key)
         follow(args, answer)
         if (answer.body !== undefined && answer.body !== null) {
             yield* answerChunks(answer.body, answer.framing)
@@ -112,6 +191,28 @@ export function wire(
     return rpc
 }
 
+/** How long a reload that got no answer waits to ask again where the browser says it is online. */
+const UNANSWERED_RETRY_MS = 5_000
+
+/** A mutation's call as the outbox keeps it, under the key it is sent with every time (46.10). */
+function queuedCall(
+    request: RpcRequest,
+    address: string,
+    args: Record<string, unknown> | undefined,
+): Parameters<typeof enqueue>[0] {
+    const id = crypto.randomUUID()
+    const headers = new Headers(request.init.headers)
+    headers.set('idempotency-key', id)
+    request.init.headers = headers
+    return {
+        id,
+        method: request.method,
+        address,
+        url: request.url,
+        args: args as Record<string, JsonValue> | undefined,
+    }
+}
+
 /**
  * The build's copy options as a value takes them, `structural` resolved to its function.
  *