@sparkvault/sdk-mobile 7.0.0 → 7.0.1

package/dist/app-sdk/transfer-retry.d.ts

@@ -0,0 +1,298 @@
+/**
+ * @typedef {'ok'|'retry'|'resync'|'deferred'|'gone'|'refused'} TransferVerdict
+ */
+/**
+ * The verdicts a transfer recovers from by trying again that count as
+ * failures: the ones a budget's `failed` records.
+ * @typedef {'retry'|'resync'} RetryableTransferVerdict
+ */
+/**
+ * @typedef {Object} TransferOutcome
+ * @property {TransferVerdict} verdict - What the client does next
+ * @property {number|null} retryAfterMs - The answer's `Retry-After`, in ms from
+ *   the answer (an HTTP-date already past reads as 0); null when absent or unreadable
+ * @property {number|null} offset - The answer's `Upload-Offset`; null when absent or unreadable
+ * @property {string|null} coreCode - The code Core ended the upload with, as a
+ *   terminal answer named it (a 404, 410 or 412: its body's details or, those
+ *   naming none, its `X-Upload-Refusal`): REFUSED for a final refusal
+ *   (`UPLOAD_POOL_FULL`, `UPLOAD_SUPERSEDED`), GONE for any other code
+ *   (`NOT_FOUND`, `UPLOAD_PROTOCOL_RETIRED`, a 412's, one this policy does not
+ *   know); null when the answer names none
+ */
+/**
+ * Read the answer to a transfer request the way the policy does.
+ *
+ * @param {Object} response
+ * @param {number} response.status - The HTTP status; 0 when the request got no answer
+ * @param {((name: string) => string|null)|null} [response.headers] - Reads a
+ *   response header by name: a fetch `Headers`' `get` or an XHR's
+ *   `getResponseHeader`, bound to its owner (`(name) => xhr.getResponseHeader(name)`)
+ * @param {unknown} [response.details] - The `details` of the error envelope the
+ *   answer's body carries (`{ error: { code, message, details } }`), as the
+ *   runtime's one reader of a failed answer parsed it from the whole body;
+ *   where Forge names the refusal Core decided (`coreCode`), ahead of the
+ *   answer's `X-Upload-Refusal`. Anything that is not an object names none.
+ * @param {boolean} [response.receipt] - The request was the receipt: the PATCH
+ *   at the final offset, whose 503 carrying `Retry-After` is a deferral
+ * @param {number} [response.now] - When the answer arrived (epoch ms), which an
+ *   HTTP-date `Retry-After` counts from
+ * @returns {TransferOutcome}
+ * @throws {TypeError} When the status is not a whole number, headers is not a
+ *   function, or receipt is not a boolean
+ */
+export function classifyTransferResponse({ status, headers, details, receipt, now }: {
+    status: number;
+    headers?: ((name: string) => string | null) | null | undefined;
+    details?: unknown;
+    receipt?: boolean | undefined;
+    now?: number | undefined;
+}): TransferOutcome;
+/**
+ * When a session lapses, read from its `Upload-Expires` (an HTTP-date).
+ *
+ * @param {unknown} headerValue - The header as received (null when absent)
+ * @param {number} [now] - epoch ms, which places an obsolete two-digit year
+ * @returns {number|null} epoch ms, or null when absent or not an HTTP-date
+ */
+export function parseUploadExpires(headerValue: unknown, now?: number): number | null;
+/**
+ * 32-bit FNV-1a over the text's UTF-8 bytes: the jitter's hash. A retry's
+ * delay only has to spread, so it hashes what identifies the retry and draws
+ * nothing (docs/CONVENTIONS.md → Randomness).
+ *
+ * @param {string} text
+ * @returns {number} An unsigned 32-bit integer
+ * @throws {TypeError} When the text is not a string
+ */
+export function fnv1a32(text: string): number;
+/**
+ * What a transfer's retries spread by when no session URL keys them yet (a
+ * session create) or ever (a download, whose link carries its token): the
+ * scope (the create endpoint, or the kind of transfer), when the transfer
+ * started, and this runtime's count of keyed transfers, which tell
+ * concurrent transfers apart. A transfer's token is a credential and never
+ * feeds anything observable such as a delay, so no part of the key derives
+ * from it (docs/CONVENTIONS.md → Randomness).
+ *
+ * @param {string} scope - The endpoint or the kind of transfer
+ * @returns {string} The key, for every retry of this one transfer
+ * @throws {TypeError} For a scope that is not a non-empty string
+ */
+export function transferJitterKey(scope: string): string;
+/**
+ * How long to wait before retry `attempt` of a transfer: `baseMs` doubling per
+ * attempt, capped at `capMs`, plus a jitter in [0, 1000) ms hashed from the
+ * transfer and the attempt, and never less than the server's `Retry-After`.
+ * The same transfer and attempt always wait the same; different transfers
+ * failing together spread out.
+ *
+ * @param {Object} options
+ * @param {number} options.attempt - Which retry this is, from 1
+ * @param {number|null} [options.retryAfterMs] - The answer's `Retry-After`: a floor
+ * @param {number} [options.baseMs] - The first retry's backoff
+ * @param {number} [options.capMs] - The longest backoff, before jitter
+ * @param {string} options.jitterKey - What identifies the transfer (its session
+ *   URL, or a `transferJitterKey`)
+ * @returns {number} ms
+ * @throws {TypeError} For an attempt that is not a whole number from 1, a
+ *   missing jitter key, or a delay bound that is not a positive number of ms
+ */
+export function retryDelayMs({ attempt, retryAfterMs, baseMs, capMs, jitterKey }: {
+    attempt: number;
+    retryAfterMs?: number | null | undefined;
+    baseMs?: number | undefined;
+    capMs?: number | undefined;
+    jitterKey: string;
+}): number;
+/**
+ * @typedef {Object} TransferBudget
+ * @property {() => void} progressed - The server confirmed progress (bytes
+ *   landed, or the offset it names moved forward): the failures in a row and
+ *   the idle clock start over
+ * @property {() => void} alive - A sign of life the server has not confirmed
+ *   (bytes are leaving, or the device is back online): the idle clock starts
+ *   over and the failures in a row stand, so attempts that die before the
+ *   server confirms anything still end the transfer
+ * @property {(verdict: RetryableTransferVerdict, retryAfterMs?: number|null) => boolean} failed -
+ *   Records a retryable answer (RETRY or RESYNC) and says whether another
+ *   attempt is allowed: the failures in a row stay under the max, and the
+ *   attempt `retryAfterMs` allows would start inside the idle limit, so a
+ *   transfer never sleeps on a Retry-After longer than its budget. The limit
+ *   bounds when a retry is decided; a retry decided inside it still waits its
+ *   own backoff, so a transfer ends within one backoff of the limit.
+ * @property {(retryAfterMs?: number|null) => boolean} deferred - Records a
+ *   DEFERRED answer and says whether to ask again: only the idle limit bounds
+ *   it, as `failed` applies it, because a deferral is the server at work,
+ *   never a failure, so the failures in a row stand
+ * @property {number} consecutiveFailures - Retryable failures since the last progress
+ * @property {number} attempt - Failures and deferrals since the last progress:
+ *   the attempt the next wait's delay is computed for, so each deferral backs
+ *   the next ask off as a failure does, sparing a Core that is struggling to
+ *   publish
+ * @property {number} msSinceProgress - ms since the last progress or sign of life
+ */
+/**
+ * The retry budget of one transfer: retries are bounded by failures in a row
+ * and by time without progress, deferrals by time alone, and both bounds
+ * start over whenever the server confirms progress, so a slow transfer that
+ * keeps landing bytes is never cut off while a dead one ends in bounded time.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.idleLimitMs] - How long the transfer may go without
+ *   progress or a sign of life
+ * @param {number} [options.maxConsecutiveFailures] - Failures in a row that end the transfer
+ * @param {() => number} [options.now] - The clock, epoch ms
+ * @returns {TransferBudget}
+ * @throws {TypeError} For a limit that is not a positive number, or a clock that is not a function
+ */
+export function createTransferBudget({ idleLimitMs, maxConsecutiveFailures, now }?: {
+    idleLimitMs?: number | undefined;
+    maxConsecutiveFailures?: number | undefined;
+    now?: (() => number) | undefined;
+}): TransferBudget;
+/**
+ * Why a session offset the server named (a HEAD's, or a 409's `Upload-Offset`)
+ * cannot be resumed from, or null when it can. Forge commits whole chunks, so
+ * a session stands at a multiple of its chunk size or at its total.
+ *
+ * @param {number|null} offset
+ * @param {Object} geometry
+ * @param {number} geometry.totalSize - The upload's length (a non-negative whole number)
+ * @param {number} geometry.chunkSize - The session's chunk size (a positive whole number)
+ * @returns {'invalid'|'beyond_total'|'misaligned'|null}
+ * @throws {TypeError} When the length is not a non-negative whole number or
+ *   the chunk size not a positive one
+ */
+export function resumeOffsetProblem(offset: number | null, { totalSize, chunkSize }: {
+    totalSize: number;
+    chunkSize: number;
+}): "invalid" | "beyond_total" | "misaligned" | null;
+/** What a client does after a transfer request, read from its answer. */
+export const TRANSFER_VERDICT: Readonly<{
+    /** 2xx: the request did what it asked. */
+    OK: "ok";
+    /**
+     * No answer (a reset, a timeout), 408, 425, 429, a 5xx, or a 409 without
+     * `Upload-Offset` (another request holds the session's lease): back off,
+     * never sooner than `Retry-After`, then ask the server's offset before
+     * sending a chunk again.
+     */
+    RETRY: "retry";
+    /** 409 with `Upload-Offset`: the session stands elsewhere; continue from that offset at once. */
+    RESYNC: "resync";
+    /**
+     * 503 with `Retry-After` to the receipt: every byte is received and the
+     * publication is still running. Ask again after a backoff that grows with
+     * each deferral, never sooner than `Retry-After`; only the idle limit ends
+     * the asking, never the failures in a row.
+     */
+    DEFERRED: "deferred";
+    /**
+     * 404 or 410 naming no code, or a 404, 410 or 412 naming a code of Core's
+     * that is not a final refusal (`coreCode` carries it): the session no
+     * longer exists; only a new upload from byte 0 can succeed.
+     */
+    GONE: "gone";
+    /**
+     * Any other status, or a 404, 410 or 412 naming a final refusal of Core's
+     * (`coreCode`: UPLOAD_POOL_FULL, UPLOAD_SUPERSEDED): the server's verdict on
+     * this request, which repeating it, or a new upload of the same file,
+     * earns again.
+     */
+    REFUSED: "refused";
+}>;
+/** The tus `expiration` extension's header: when the session lapses, as an HTTP-date. */
+export const UPLOAD_EXPIRES_HEADER: "Upload-Expires";
+/**
+ * How long a client waits for the answer to an offset HEAD or a receipt
+ * PATCH, whatever its other requests get: on a received upload, Forge answers
+ * either only after its own call to Core (up to 30 s) has published the
+ * upload or deferred it, so each gets twice that.
+ */
+export const HEAD_AND_RECEIPT_TIMEOUT_MS: 60000;
+/** Why an offset the server names cannot be resumed from. */
+export const RESUME_OFFSET_PROBLEM: Readonly<{
+    /** Not a non-negative whole number of bytes. */
+    INVALID: "invalid";
+    /** Past the upload's length: resuming from it would report a partial upload complete. */
+    BEYOND_TOTAL: "beyond_total";
+    /** Inside a chunk: a session commits whole chunks only, so the answer is corrupt. */
+    MISALIGNED: "misaligned";
+}>;
+export type TransferVerdict = "ok" | "retry" | "resync" | "deferred" | "gone" | "refused";
+/**
+ * The verdicts a transfer recovers from by trying again that count as
+ * failures: the ones a budget's `failed` records.
+ */
+export type RetryableTransferVerdict = "retry" | "resync";
+export type TransferOutcome = {
+    /**
+     * - What the client does next
+     */
+    verdict: TransferVerdict;
+    /**
+     * - The answer's `Retry-After`, in ms from
+     * the answer (an HTTP-date already past reads as 0); null when absent or unreadable
+     */
+    retryAfterMs: number | null;
+    /**
+     * - The answer's `Upload-Offset`; null when absent or unreadable
+     */
+    offset: number | null;
+    /**
+     * - The code Core ended the upload with, as a
+     * terminal answer named it (a 404, 410 or 412: its body's details or, those
+     * naming none, its `X-Upload-Refusal`): REFUSED for a final refusal
+     * (`UPLOAD_POOL_FULL`, `UPLOAD_SUPERSEDED`), GONE for any other code
+     * (`NOT_FOUND`, `UPLOAD_PROTOCOL_RETIRED`, a 412's, one this policy does not
+     * know); null when the answer names none
+     */
+    coreCode: string | null;
+};
+export type TransferBudget = {
+    /**
+     * - The server confirmed progress (bytes
+     * landed, or the offset it names moved forward): the failures in a row and
+     * the idle clock start over
+     */
+    progressed: () => void;
+    /**
+     * - A sign of life the server has not confirmed
+     * (bytes are leaving, or the device is back online): the idle clock starts
+     * over and the failures in a row stand, so attempts that die before the
+     * server confirms anything still end the transfer
+     */
+    alive: () => void;
+    /**
+     * -
+     * Records a retryable answer (RETRY or RESYNC) and says whether another
+     * attempt is allowed: the failures in a row stay under the max, and the
+     * attempt `retryAfterMs` allows would start inside the idle limit, so a
+     * transfer never sleeps on a Retry-After longer than its budget. The limit
+     * bounds when a retry is decided; a retry decided inside it still waits its
+     * own backoff, so a transfer ends within one backoff of the limit.
+     */
+    failed: (verdict: RetryableTransferVerdict, retryAfterMs?: number | null) => boolean;
+    /**
+     * - Records a
+     * DEFERRED answer and says whether to ask again: only the idle limit bounds
+     * it, as `failed` applies it, because a deferral is the server at work,
+     * never a failure, so the failures in a row stand
+     */
+    deferred: (retryAfterMs?: number | null) => boolean;
+    /**
+     * - Retryable failures since the last progress
+     */
+    consecutiveFailures: number;
+    /**
+     * - Failures and deferrals since the last progress:
+     * the attempt the next wait's delay is computed for, so each deferral backs
+     * the next ask off as a failure does, sparing a Core that is struggling to
+     * publish
+     */
+    attempt: number;
+    /**
+     * - ms since the last progress or sign of life
+     */
+    msSinceProgress: number;
+};