@kottera/tera-web 0.0.0-stage → 0.1.0-rc.2

package/dist/feed/connection.d.ts

@@ -0,0 +1,158 @@
+import type { FeedFrameRecord, FeedFrameStatus } from "../generated/feed.ts";
+import { type FeedOpenError, type FeedOpener } from "./sse.ts";
+export declare const BASE_DELAY_MS = 1000;
+export declare const MAX_DELAY_MS = 30000;
+/** Replays allowed in {@link REPLAY_WINDOW_MS} before a loss is surfaced. */
+export declare const REPLAY_LIMIT = 3;
+export declare const REPLAY_WINDOW_MS: number;
+/** Added to twice the feed's heartbeat interval before a silent stream is given up on. */
+export declare const HEARTBEAT_GRACE_MS = 5000;
+/** The SSE event the kit closes a stream with when the person's token expires (D2 item 6). */
+export declare const REAUTHENTICATE_EVENT = "reauthenticate";
+/**
+ * One feed frame as the stream carried it, before its `type` is read. A frame
+ * of a known type is handed on as the type generated for it from
+ * `sdk/feed/schema/` ({@link FeedFrameRecord}, {@link FeedFrameStatus}); one
+ * of a type this package does not know is skipped (ADR-143 D13). The
+ * connection reads a frame's `type`, a status frame's `status` and drop
+ * counts, and a record's order key — and nothing else: the payload's contract
+ * is its publishing family's.
+ */
+export type FeedFrame = {
+    readonly type: string;
+    readonly [field: string]: unknown;
+};
+/**
+ * Where the connection is.
+ *
+ *   reconnecting  a stream is being opened, or will be in `delayMs`; attempt 0
+ *                 is the first open and an immediate reopen
+ *   replaying     open, and the run's stored history is still arriving
+ *   live          open, history read: records now are live
+ *   refused       the route refused; a person has to act
+ *   stopped       nothing is wanted any more
+ */
+export type FeedConnectionPhase = "reconnecting" | "replaying" | "live" | "refused" | "stopped";
+/** A loss no replay is repairing, surfaced to the page. */
+export interface FeedLoss {
+    /** The status value that reported it (`records_dropped`, `backfill_gap`, …). */
+    readonly status: string;
+    /**
+     * `replays-exhausted`: {@link REPLAY_LIMIT} replays in {@link REPLAY_WINDOW_MS}
+     * did not stop it. `unrepairable`: a replay cannot bring the records back.
+     */
+    readonly reason: "replays-exhausted" | "unrepairable";
+}
+export interface FeedConnectionState {
+    readonly phase: FeedConnectionPhase;
+    /** Consecutive failed attempts; 0 once a connection has gone live. */
+    readonly attempt: number;
+    /** How long until the scheduled reconnect, while `reconnecting`; 0 when it is under way. */
+    readonly delayMs: number;
+    /** Why the last stream ended, in the words it ended with. */
+    readonly lastError: string | null;
+    /** The refusal, while `refused`. */
+    readonly refusal: FeedOpenError | null;
+    /** A loss no replay is repairing, or null. */
+    readonly loss: FeedLoss | null;
+}
+export interface Clock {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    /** A number in [0, 1), for the jitter. */
+    random(): number;
+}
+/** Something outside the stream saying now is a good time to reconnect. */
+export type FeedSignal = "visible" | "online";
+/** Subscribes to {@link FeedSignal}s; returns the unsubscribe. */
+export type FeedSignals = (notify: (signal: FeedSignal) => void) => () => void;
+/** The browser's signals: the document becoming visible, and the window coming online. */
+export declare const browserSignals: FeedSignals;
+/**
+ * defaultOrderKey reads the order ADR-083 D7's contract names: the id of a
+ * Work Order event (ADR-078 D3), monotonic across every Work Order and the
+ * cursor `work_order.events` replays from, carried as the record payload's
+ * `id`. A record without one has no key.
+ */
+export declare function defaultOrderKey(record: FeedFrameRecord): number | undefined;
+export interface FeedConnectionOptions {
+    /** The feed's name, as the plugin's manifest declares it. */
+    feed: string;
+    /** Narrows the feed to these of its topic filters (the feed's `topics` parameter). */
+    topics?: readonly string[];
+    /** Each record not already delivered, in order. */
+    onRecord: (record: FeedFrameRecord) => void;
+    /** Every status frame, as it arrives. Heartbeats are absorbed and never reach it (ADR-083 D7). */
+    onStatus?: (status: FeedFrameStatus) => void;
+    /** Every change of {@link FeedConnectionState}. */
+    onChange?: (state: FeedConnectionState) => void;
+    /**
+     * A record's place in the feed's order, for de-duplication across replays;
+     * {@link defaultOrderKey} when absent. A record with no key cannot be told
+     * apart from one already delivered, so it is delivered every time it
+     * arrives: a feed whose records carry no Work Order event id passes the key
+     * its own records are ordered by.
+     */
+    orderKey?: (record: FeedFrameRecord) => number | undefined;
+    /** Opens one stream; {@link fetchOpener} when absent. */
+    open?: FeedOpener;
+    clock?: Clock;
+    /** {@link browserSignals} when absent. */
+    signals?: FeedSignals;
+}
+export declare class FeedConnection {
+    private readonly options;
+    private readonly clock;
+    private readonly open;
+    private readonly orderKey;
+    private view;
+    private unsubscribe;
+    private generation;
+    private controller;
+    private retryTimer;
+    private silenceTimer;
+    private high;
+    private replays;
+    private opened;
+    private replaying;
+    private silenceMs;
+    private droppedSeen;
+    private lossPending;
+    private streamLoss;
+    constructor(options: FeedConnectionOptions);
+    get state(): FeedConnectionState;
+    /** The stream's URL: the feed route, narrowed to the topics, asking for the backfill. */
+    get url(): string;
+    /** Opens the first stream. Nothing delivered before is remembered. */
+    start(): void;
+    /** Ends everything; nothing this connection opened may deliver again. */
+    stop(): void;
+    /** A person asked: reopens from any ending, resetting the backoff and the replay ration. */
+    retry(): void;
+    private nudge;
+    private set;
+    private teardown;
+    private connect;
+    private event;
+    /**
+     * The person's token expired under an open stream (D7), told by a
+     * `reauthenticate` event or a `credential_expired` status: reconnecting
+     * carries a fresh assertion, so it is at once. A stream that never opened is
+     * not one the token ended, so it backs off rather than looping at once.
+     */
+    private expired;
+    private frame;
+    private status;
+    private deliver;
+    private droppedRose;
+    private unrepairable;
+    private lost;
+    private goLive;
+    /** One replay for a loss, within the ration; past it, the loss is surfaced. */
+    private replay;
+    /** Ends the current stream as a failure and schedules the next with backoff. */
+    private reopen;
+    private schedule;
+    private armSilence;
+}

package/dist/feed/connection.js

@@ -0,0 +1,427 @@
+/**
+ * The feed connection: one ADR-083 feed held open for a page over D3's
+ * `GET /tera/v1/feeds/{feed}` stream, reopened after anything that ends it but
+ * a refusal (ADR-162 D4 item 2). It is wo-dashboard's `activity-connection.ts`
+ * moved here, read over the feed's own frames, which the kit relays verbatim
+ * (D2 item 6), rather than over that dashboard's relay protocol.
+ *
+ * # What ends a stream, and what happens next
+ *
+ * | Ending                                              | Next                               |
+ * |-----------------------------------------------------|------------------------------------|
+ * | the open fails with no answer (network, sleep)      | reconnect with backoff             |
+ * | a 5xx, a 408 or a 429                               | reconnect with backoff             |
+ * | the stream ends, with or without a terminal status  | reconnect with backoff             |
+ * | nothing read past the heartbeat budget              | reconnect with backoff             |
+ * | a `reauthenticate` event (D7: the token expired)    | reconnect at once                  |
+ * | a `credential_expired` status (D7, the same ending)  | reconnect at once                  |
+ * | a status reporting loss                             | one replay, rationed (see Loss)    |
+ * | any other 4xx, a 501, or a success that is not an   | STOP: a refusal. A person has to   |
+ * | event stream                                        | act ({@link FeedConnection.retry}) |
+ *
+ * # Replay, and what is delivered
+ *
+ * Every connection asks for the run's stored history (`backfill=all`, the
+ * only start position the feed's splice has, ADR-112 D5), so every reconnect
+ * replays it. The connection is `replaying` from the feed's `open` status
+ * until `backfill_complete`, and `live` after. What it delivers is only the
+ * records not already delivered, in order: each record's order key — by
+ * default the Work Order event id ADR-083 D7's cursor orders by — must exceed
+ * the highest one delivered, so a replay adds what arrived while the
+ * connection was down and nothing it already handed over. A record carries
+ * nothing else the connection reads; its payload is the page's.
+ *
+ * # Loss
+ *
+ * A status saying records may have been lost — `records_dropped`,
+ * `upstream_lost`, a status this package does not know (ADR-143 D13), a
+ * batch that shed records, a running drop total that rose — is repaired by
+ * a replay, which reopens the stream at once. A replay re-reads the whole
+ * run, so it is rationed:
+ *
+ * - Not while history is still arriving. A replay that outruns the page drops
+ *   at the same place every time, so the history is read to its end and the
+ *   replay made once after.
+ * - Not for a loss a replay cannot repair: a `backfill_gap` (the store no
+ *   longer reaches) or a drop for the feed's own `rate_limit`. Those are
+ *   surfaced at once.
+ * - Not for a terminal status: the stream is ending, and the reconnect after
+ *   it replays anyway.
+ * - At most {@link REPLAY_LIMIT} in {@link REPLAY_WINDOW_MS}. Past that the
+ *   loss is surfaced on the state's `loss` rather than the run re-read for
+ *   ever.
+ *
+ * # Backoff
+ *
+ * {@link BASE_DELAY_MS} doubling to {@link MAX_DELAY_MS}, each delay scaled by
+ * a jitter in [0.5, 1] so a daemon restart does not bring every tab back in
+ * the same millisecond. It resets when a connection goes live, not on a mere
+ * open, so a feed that accepts and then drops every connection still backs
+ * off. A scheduled reconnect is taken at once when the tab becomes visible or
+ * the network returns: the reason it failed has plausibly gone.
+ *
+ * It is a plain class with an injected clock, opener and signals, so its tests
+ * drive it with fake timers and a scripted stream and no network.
+ */
+import { routePath } from "../routes.js";
+import { fetchOpener, isRefusal } from "./sse.js";
+export const BASE_DELAY_MS = 1_000;
+export const MAX_DELAY_MS = 30_000;
+/** Replays allowed in {@link REPLAY_WINDOW_MS} before a loss is surfaced. */
+export const REPLAY_LIMIT = 3;
+export const REPLAY_WINDOW_MS = 5 * 60_000;
+/** Added to twice the feed's heartbeat interval before a silent stream is given up on. */
+export const HEARTBEAT_GRACE_MS = 5_000;
+/** The SSE event the kit closes a stream with when the person's token expires (D2 item 6). */
+export const REAUTHENTICATE_EVENT = "reauthenticate";
+/**
+ * The SSE events the kit relays a feed frame as: the event named after the
+ * frame's type (sdk/plugin/webui `EventRecord`, `EventStatus`). An unnamed
+ * event (`message`) is read as well, its frame's own `type` deciding. Any
+ * other event is skipped, as a frame type this package does not know is.
+ */
+const FRAME_EVENTS = new Set(["message", "record", "status"]);
+/**
+ * The feed status the daemon closes a person's feed with at the token's
+ * expiry (D7, `feed.StatusCredentialExpired`). It is the ending a
+ * `reauthenticate` event reports, reaching the connection as the feed's own
+ * frame, and it reconnects the same way: at once.
+ */
+const CREDENTIAL_EXPIRED = "credential_expired";
+const realClock = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    random: () => Math.random(),
+};
+/** The browser's signals: the document becoming visible, and the window coming online. */
+export const browserSignals = (notify) => {
+    const doc = globalThis.document;
+    const win = globalThis;
+    const onVisibility = () => {
+        if (doc?.visibilityState === "visible")
+            notify("visible");
+    };
+    const onOnline = () => notify("online");
+    doc?.addEventListener("visibilitychange", onVisibility);
+    win.addEventListener?.("online", onOnline);
+    return () => {
+        doc?.removeEventListener("visibilitychange", onVisibility);
+        win.removeEventListener?.("online", onOnline);
+    };
+};
+/**
+ * defaultOrderKey reads the order ADR-083 D7's contract names: the id of a
+ * Work Order event (ADR-078 D3), monotonic across every Work Order and the
+ * cursor `work_order.events` replays from, carried as the record payload's
+ * `id`. A record without one has no key.
+ */
+export function defaultOrderKey(record) {
+    const payload = record.payload;
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const id = payload.id;
+    return typeof id === "number" && Number.isSafeInteger(id) ? id : undefined;
+}
+/** The statuses that report no loss. Every other one this package does not handle by name is read as possible loss (ADR-143 D13). */
+const INFORMATIONAL = new Set(["partial_authorization", "narrowed", "backfill_degraded"]);
+const initialState = { phase: "stopped", attempt: 0, delayMs: 0, lastError: null, refusal: null, loss: null };
+export class FeedConnection {
+    options;
+    clock;
+    open;
+    orderKey;
+    view = initialState;
+    unsubscribe = null;
+    // Every stream and timer this connection starts belongs to one generation;
+    // a callback from an older one writes nothing.
+    generation = 0;
+    controller = null;
+    retryTimer = null;
+    silenceTimer = null;
+    // Across streams: the highest order key delivered, and when replays were made.
+    high = -Infinity;
+    replays = [];
+    // Per stream.
+    opened = false;
+    replaying = false;
+    silenceMs = 0;
+    droppedSeen = 0;
+    lossPending = null;
+    streamLoss = null;
+    constructor(options) {
+        this.options = options;
+        this.clock = options.clock ?? realClock;
+        this.open = options.open ?? fetchOpener();
+        this.orderKey = options.orderKey ?? defaultOrderKey;
+    }
+    get state() {
+        return this.view;
+    }
+    /** The stream's URL: the feed route, narrowed to the topics, asking for the backfill. */
+    get url() {
+        const query = new URLSearchParams();
+        for (const topic of this.options.topics ?? [])
+            query.append("topics", topic);
+        query.set("backfill", "all");
+        return routePath("feeds", this.options.feed) + "?" + query.toString();
+    }
+    /** Opens the first stream. Nothing delivered before is remembered. */
+    start() {
+        this.stop();
+        this.high = -Infinity;
+        this.replays = [];
+        this.view = initialState;
+        this.unsubscribe = (this.options.signals ?? browserSignals)((signal) => this.nudge(signal));
+        this.connect();
+    }
+    /** Ends everything; nothing this connection opened may deliver again. */
+    stop() {
+        this.generation += 1;
+        this.teardown();
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        if (this.view.phase !== "stopped")
+            this.set({ phase: "stopped", delayMs: 0 });
+    }
+    /** A person asked: reopens from any ending, resetting the backoff and the replay ration. */
+    retry() {
+        this.replays = [];
+        this.view = { ...this.view, attempt: 0, loss: null };
+        this.connect();
+    }
+    nudge(_signal) {
+        if (this.retryTimer !== null)
+            this.connect();
+    }
+    set(patch) {
+        this.view = { ...this.view, ...patch };
+        this.options.onChange?.(this.view);
+    }
+    teardown() {
+        this.controller?.abort();
+        this.controller = null;
+        if (this.retryTimer !== null)
+            this.clock.clearTimeout(this.retryTimer);
+        if (this.silenceTimer !== null)
+            this.clock.clearTimeout(this.silenceTimer);
+        this.retryTimer = null;
+        this.silenceTimer = null;
+    }
+    connect() {
+        this.teardown();
+        const mine = ++this.generation;
+        const controller = new AbortController();
+        this.controller = controller;
+        this.opened = false;
+        this.replaying = false;
+        this.silenceMs = 0;
+        this.droppedSeen = 0;
+        this.lossPending = null;
+        this.streamLoss = null;
+        this.set({ phase: "reconnecting", delayMs: 0, refusal: null });
+        this.open(this.url, (e) => {
+            if (mine === this.generation)
+                this.event(e);
+        }, controller.signal).then(() => {
+            if (mine === this.generation)
+                this.reopen("the stream ended");
+        }, (err) => {
+            if (mine !== this.generation)
+                return;
+            if (isRefusal(err)) {
+                this.generation += 1;
+                this.teardown();
+                this.set({ phase: "refused", refusal: err, lastError: err.message, delayMs: 0 });
+                return;
+            }
+            this.reopen(err instanceof Error ? err.message : String(err));
+        });
+    }
+    event(e) {
+        this.armSilence();
+        if (e.event === REAUTHENTICATE_EVENT) {
+            this.expired("reauthenticate");
+            return;
+        }
+        if (!FRAME_EVENTS.has(e.event))
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(e.data);
+        }
+        catch {
+            return;
+        }
+        if (typeof frame !== "object" || frame === null || typeof frame.type !== "string")
+            return;
+        // A named event carries the frame of its name; one that disagrees is not trusted.
+        if (e.event !== "message" && frame.type !== e.event)
+            return;
+        this.frame(frame);
+    }
+    /**
+     * The person's token expired under an open stream (D7), told by a
+     * `reauthenticate` event or a `credential_expired` status: reconnecting
+     * carries a fresh assertion, so it is at once. A stream that never opened is
+     * not one the token ended, so it backs off rather than looping at once.
+     */
+    expired(how) {
+        if (this.opened)
+            this.schedule(0, this.view.attempt, "the person's token expired");
+        else
+            this.reopen(`${how} before the stream opened`);
+    }
+    frame(f) {
+        switch (f.type) {
+            case "record":
+                this.deliver(f);
+                return;
+            case "batch": {
+                const records = Array.isArray(f.records) ? f.records : [];
+                for (const r of records) {
+                    if (typeof r === "object" && r !== null && r.type === "record")
+                        this.deliver(r);
+                }
+                const rose = this.droppedRose(f.dropped_total);
+                if (count(f.dropped) === 0 && !rose)
+                    return;
+                if (f.drop_reason === "rate_limit")
+                    this.unrepairable("records_dropped");
+                else
+                    this.lost("records_dropped");
+                return;
+            }
+            case "heartbeat":
+                if (this.droppedRose(f.dropped_total))
+                    this.lost("records_dropped");
+                return;
+            case "status":
+                this.options.onStatus?.(f);
+                this.status(f);
+                return;
+        }
+        // A frame type this package does not know is skipped (ADR-143 D13): loss
+        // is only ever reported on a status frame.
+    }
+    status(f) {
+        const status = typeof f.status === "string" ? f.status : "";
+        if (status === CREDENTIAL_EXPIRED) {
+            this.expired(status);
+            return;
+        }
+        if (count(f.close_code) > 0 || status === "shutting_down") {
+            // Terminal: the stream ends next, and the reconnect after it replays.
+            return;
+        }
+        switch (status) {
+            case "open":
+                this.opened = true;
+                this.droppedSeen = count(f.dropped_total);
+                this.silenceMs = count(f.heartbeat_interval_seconds) > 0 ? 2 * count(f.heartbeat_interval_seconds) * 1000 + HEARTBEAT_GRACE_MS : 0;
+                this.armSilence();
+                this.replaying = true;
+                this.set({ phase: "replaying" });
+                return;
+            case "backfill_complete":
+            case "backfill_unavailable":
+                this.goLive();
+                return;
+            case "backfill_gap":
+                this.unrepairable(status);
+                return;
+            case "records_dropped":
+                this.droppedRose(f.dropped_total);
+                if (f.drop_reason === "rate_limit")
+                    this.unrepairable(status);
+                else
+                    this.lost(status);
+                return;
+        }
+        if (!INFORMATIONAL.has(status))
+            this.lost(status);
+    }
+    deliver(record) {
+        const key = this.orderKey(record);
+        if (key !== undefined) {
+            if (key <= this.high)
+                return;
+            this.high = key;
+        }
+        this.options.onRecord(record);
+    }
+    droppedRose(total) {
+        const n = count(total);
+        if (n <= this.droppedSeen)
+            return false;
+        this.droppedSeen = n;
+        return true;
+    }
+    unrepairable(status) {
+        this.streamLoss = { status, reason: "unrepairable" };
+        this.set({ loss: this.streamLoss });
+    }
+    lost(status) {
+        if (this.replaying) {
+            this.lossPending ??= status;
+            return;
+        }
+        this.replay(status);
+    }
+    goLive() {
+        if (!this.replaying)
+            return;
+        this.replaying = false;
+        // A replay that went live without a loss of its own repaired the last one.
+        this.set({ phase: "live", attempt: 0, delayMs: 0, lastError: null, loss: this.streamLoss });
+        const pending = this.lossPending;
+        this.lossPending = null;
+        if (pending !== null)
+            this.replay(pending);
+    }
+    /** One replay for a loss, within the ration; past it, the loss is surfaced. */
+    replay(status) {
+        const now = this.clock.now();
+        this.replays = this.replays.filter((at) => now - at < REPLAY_WINDOW_MS);
+        if (this.replays.length >= REPLAY_LIMIT) {
+            this.set({ loss: { status, reason: "replays-exhausted" } });
+            return;
+        }
+        this.replays.push(now);
+        this.schedule(0, this.view.attempt, `records were reported lost (${status})`);
+    }
+    /** Ends the current stream as a failure and schedules the next with backoff. */
+    reopen(why) {
+        const attempt = this.view.attempt + 1;
+        const exp = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** (attempt - 1));
+        this.schedule(Math.round(exp * (0.5 + this.clock.random() * 0.5)), attempt, why);
+    }
+    schedule(delayMs, attempt, why) {
+        this.generation += 1;
+        this.teardown();
+        this.set({ phase: "reconnecting", attempt, delayMs, lastError: why });
+        if (delayMs === 0) {
+            this.connect();
+            return;
+        }
+        this.retryTimer = this.clock.setTimeout(() => {
+            this.retryTimer = null;
+            this.connect();
+        }, delayMs);
+    }
+    armSilence() {
+        if (this.silenceTimer !== null)
+            this.clock.clearTimeout(this.silenceTimer);
+        this.silenceTimer = null;
+        if (this.silenceMs <= 0)
+            return;
+        const mine = this.generation;
+        this.silenceTimer = this.clock.setTimeout(() => {
+            if (mine === this.generation)
+                this.reopen(`the stream fell silent past its heartbeat budget (${this.silenceMs}ms)`);
+        }, this.silenceMs);
+    }
+}
+function count(v) {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0;
+}

package/dist/feed/sse.d.ts

@@ -0,0 +1,51 @@
+/** One dispatched server-sent event. `event` is `message` when none was named. */
+export interface SSEEvent {
+    readonly event: string;
+    readonly data: string;
+}
+/**
+ * SSEParser turns the text of an event stream, in whatever chunks it arrives,
+ * into events, as the WHATWG event-stream grammar reads it: `\n`, `\r\n` and
+ * `\r` all end a line, a blank line dispatches, a line starting `:` is a
+ * comment, and `data` lines join with `\n`. `id` and `retry` are read and
+ * dropped — the connection keeps its own cursor and its own backoff.
+ */
+export declare class SSEParser {
+    private buffer;
+    private event;
+    private data;
+    push(chunk: string): SSEEvent[];
+    private line;
+}
+/**
+ * Opens one stream: resolves when the stream ends, rejects when it could not
+ * be opened or failed while being read. Every event read is handed to
+ * `onEvent`, in order. Aborting `signal` ends it.
+ */
+export type FeedOpener = (url: string, onEvent: (e: SSEEvent) => void, signal: AbortSignal) => Promise<void>;
+/** A feed route that answered with something other than an event stream. */
+export declare class FeedOpenError extends Error {
+    /** The HTTP status the route answered with. */
+    readonly status: number;
+    /** The answer's content type. */
+    readonly contentType: string;
+    /** As much of the body as was read: the kit's error envelope, on a refusal (ADR-162 D2 item 8). */
+    readonly body: string;
+    constructor(status: number, contentType: string, body: string);
+}
+/**
+ * isRefusal reports whether an open failed in a way trying again cannot fix,
+ * so the connection stops rather than retrying it (ADR-162 D4 item 2). A 4xx
+ * is a refusal — the person may not, or the feed is not there — except 408 and
+ * 429, which say "later". So is 501, and so is a success that is not an event
+ * stream: that is a page served where the kit's route should be, which no
+ * retry turns into a feed. Anything else — a 5xx, a dropped connection — is a
+ * transport failure, and is retried.
+ */
+export declare function isRefusal(err: unknown): err is FeedOpenError;
+/**
+ * fetchOpener is the {@link FeedOpener} a browser uses: a same-origin `GET`
+ * read as an event stream. `fetchFn` is injectable so the transport itself is
+ * tested without a network.
+ */
+export declare function fetchOpener(fetchFn?: typeof fetch): FeedOpener;