@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/events.js

@@ -0,0 +1,222 @@
+// An app's emitted events, served live to its page (#148). Any program of an
+// app emits events ({kind: "event", event, app, topic, …}, log.zig
+// eventRecord, #119); the kernel lists each on its step's update (`emitted`)
+// and, once the step is committed, hands it to the host with its place in the
+// log (providers.ts: the `emitted` hook, for every event whatever its name). This module serves
+// them on the instance's origin, the host's own route (no program, no entry,
+// nothing logged, unsigned — a read like /.live, #138, #143):
+//
+//   GET /<app>/.events?event=<name>&topic=<t1>&topic=<t2>…
+//
+//   `event` is required, one name; `topic` is repeated, one per topic (at
+//   least one; a topic is any text, so no separator is taken out of it). Sent:
+//   only the events of that app (the record's `app`, the kernel's), that name,
+//   whose `topic` is one of those. Nothing about any name is the host's: a
+//   price is one more event.
+//
+// The answer is a Server-Sent Events stream (text/event-stream), one message
+// per event record, in log order:
+//
+//   id: <n>.<seq>.<i>.<thread>   the event's place in the log: the entry its step processed (`n`), the
+//                                step's place in its thread (`seq`), the record's place in the update's
+//                                `emitted` (`i`), the thread (its origin's CID). The entry alone is not a
+//                                place: one entry can step several threads
+//   event: <name>                the event's name
+//   data: <the record>           the record as DAG-JSON (as the explorer renders records: a link
+//                                {"/": "<cid>"}, bytes {"/": {"bytes": "<base64>"}}), one line
+//
+// On connect:
+//   - with Last-Event-ID (the browser's EventSource sends it on reconnect):
+//     every matching event after that place, folded from the log (p2p.ts
+//     emittedEvents, the order the kernel folds by), then live. A place no
+//     longer in the log (or never in it) resumes after its entry: the
+//     matching events of later entries. One that is not a place: 400;
+//   - without: the current value — the LAST matching event per requested
+//     topic (one per topic that has one), in log order — then live.
+//
+// Live: the kernel's `emit` notice carries each event's place in the log
+// beside the record (`place`: {n, seq, i, thread}; the record is unchanged),
+// so a live event is sent as it is handed over, its id made from the notice,
+// with no log read; the log is read only for a new subscription's first
+// messages (Last-Event-ID, or the current value). An id handed over again (a
+// start re-offers what a waiting thread awaits) is not sent again. Nothing is
+// kept but the open subscriptions and the ids lately sent: one registry per
+// instance, in memory. An app's subscriptions close at its uninstall (no row
+// of it left in the dispatch table), all of an instance's when it stops (the
+// instance manager, a reclaim) and when the host shuts down.
+//
+// Beats (#138) are not events: not served here (GET /<app>/.live/<topic>).
+import * as dagCbor from "@ipld/dag-cbor";
+import * as dagJson from "@ipld/dag-json";
+import { emittedEvents } from "./p2p.js";
+/** The query of GET /<app>/.events (`event`, `topic` repeated) and Last-Event-ID, or why it is not one. */
+export function eventsQuery(app, params, lastEventId) {
+    const event = params.get("event") ?? "";
+    if (!event)
+        return { problem: "event: the event's name (required)" };
+    if (params.getAll("event").length > 1)
+        return { problem: "event: one name" };
+    const topics = [...new Set(params.getAll("topic"))];
+    if (!topics.length || topics.some((t) => !t))
+        return { problem: "topic: one or more topics (repeat topic=, one per topic)" };
+    const after = lastEventId?.trim() || undefined;
+    if (after !== undefined && !placeOf(after))
+        return { problem: `Last-Event-ID: ${JSON.stringify(after)} is not an event's place (<n>.<seq>.<i>.<thread>)` };
+    return { app, event, topics, ...(after ? { after } : {}) };
+}
+/** An event id's parts, or undefined. */
+export function placeOf(id) {
+    const m = /^(\d+)\.(\d+)\.(\d+)\.([a-z0-9]+)$/.exec(id);
+    return m ? { n: Number(m[1]), seq: Number(m[2]), i: Number(m[3]), thread: m[4] } : undefined;
+}
+/** One event as an SSE message. */
+export function sseMessage(d) {
+    return `id: ${d.id}\nevent: ${d.event}\ndata: ${d.data}\n\n`;
+}
+/** Every event record a stream serves in the log, in log order, as delivered (resume and the current value). */
+export async function foldEvents(store) {
+    const places = await emittedEvents(store, (rec, p) => typeof rec.event === "string" && typeof rec.app === "string" && typeof rec.topic === "string" ? p : undefined);
+    const out = [];
+    for (const p of places) {
+        const d = deliveredOf(dagCbor.decode(await store.bytes(p.record)), p);
+        if (d)
+            out.push(d);
+    }
+    return out;
+}
+/** Whether a subscription takes an event. */
+const takes = (q, d) => d.app === q.app && d.event === q.event && q.topics.includes(d.topic);
+/** What a subscription is sent first (folded from the log): after its Last-Event-ID, else the last per topic. */
+export function backlog(all, q) {
+    if (q.after !== undefined) {
+        const i = all.findIndex((d) => d.id === q.after);
+        const n = placeOf(q.after).n;
+        return (i >= 0 ? all.slice(i + 1) : all.filter((d) => d.n > n)).filter((d) => takes(q, d));
+    }
+    const last = new Map();
+    for (const d of all)
+        if (takes(q, d))
+            last.set(d.topic, d);
+    const ids = new Set([...last.values()].map((d) => d.id));
+    return all.filter((d) => ids.has(d.id));
+}
+/** The id of the event at `p`: `<n>.<seq>.<i>.<thread>` — the fold's (foldEvents), free from the notice. */
+export const idOf = (p) => `${p.n}.${p.seq}.${p.i}.${p.thread}`;
+/** A handed-over event as delivered, or undefined when it is not one a stream serves (no app, no topic). */
+export function deliveredOf(rec, p) {
+    if (rec.kind !== "event" || typeof rec.event !== "string" || typeof rec.app !== "string" || typeof rec.topic !== "string")
+        return undefined;
+    return { id: idOf(p), n: p.n, event: rec.event, app: rec.app, topic: rec.topic, data: new TextDecoder().decode(dagJson.encode(rec)) };
+}
+/** How many ids sent an instance remembers (a start hands an awaited event over again). */
+const SENT_MAX = 10_000;
+/** The registry of open subscriptions, per instance (#148). */
+export class EventStreams {
+    subs = new Map();
+    /** Per instance: the ids handed over lately, in order: one handed over again is not sent again. */
+    sent = new Map();
+    o;
+    constructor(o) { this.o = o; }
+    /** Whether `handle` has an open subscription. */
+    open(handle) { return (this.subs.get(handle)?.size ?? 0) > 0; }
+    /** How many subscriptions `handle` has open (tests). */
+    count(handle) { return this.subs.get(handle)?.size ?? 0; }
+    /**
+     * Open a subscription for `handle`: its backlog folded from the log and sent, then each new
+     * matching event as it is handed over (what came during the fold, after it, once). `send` writes
+     * one event; `close` ends the stream (the host's: an uninstall, the instance stopping). The
+     * returned function forgets it (the client went).
+     */
+    async subscribe(handle, q, send, close) {
+        const sub = { q, send, close, held: [] };
+        let set = this.subs.get(handle);
+        if (!set)
+            this.subs.set(handle, set = new Set());
+        set.add(sub);
+        const forget = () => this.remove(handle, sub);
+        try {
+            const s = this.o.open(handle);
+            let all = [];
+            if (s)
+                try {
+                    all = await foldEvents(s);
+                }
+                finally {
+                    s.close();
+                }
+            const first = backlog(all, q);
+            const had = new Set(first.map((d) => d.id));
+            const held = sub.held;
+            delete sub.held;
+            if (!set.has(sub))
+                return forget; // gone meanwhile
+            for (const d of first)
+                sub.send(d);
+            for (const d of held)
+                if (!had.has(d.id))
+                    sub.send(d);
+        }
+        catch (e) {
+            forget();
+            throw e;
+        }
+        return forget;
+    }
+    /**
+     * An event handed over for `handle` (after its step's commit), with its place in the log: sent
+     * as it is to each open subscription it matches — no log read. One handed over again (a start
+     * re-offers what a waiting thread awaits) is not sent again.
+     */
+    emitted(handle, rec, place) {
+        const subs = this.subs.get(handle);
+        if (!subs?.size)
+            return;
+        const d = deliveredOf(rec, place);
+        if (!d)
+            return;
+        let sent = this.sent.get(handle);
+        if (!sent)
+            this.sent.set(handle, sent = new Set());
+        if (sent.has(d.id))
+            return;
+        sent.add(d.id);
+        if (sent.size > SENT_MAX)
+            sent.delete(sent.values().next().value);
+        for (const s of subs)
+            if (takes(s.q, d)) {
+                if (s.held)
+                    s.held.push(d);
+                else
+                    s.send(d);
+            }
+    }
+    /** The apps `handle` has installed now (rows in its dispatch table): the others' subscriptions close. */
+    keep(handle, apps) {
+        for (const s of [...this.subs.get(handle) ?? []])
+            if (!apps.has(s.q.app))
+                this.end(handle, s);
+    }
+    /** Close every subscription of `handle` (it stops). */
+    drop(handle) {
+        for (const s of [...this.subs.get(handle) ?? []])
+            this.end(handle, s);
+    }
+    /** Close them all (the host shuts down). */
+    stop() { for (const h of [...this.subs.keys()])
+        this.drop(h); }
+    remove(handle, s) {
+        const set = this.subs.get(handle);
+        set?.delete(s);
+        if (set && !set.size) {
+            this.subs.delete(handle);
+            this.sent.delete(handle);
+        }
+    }
+    end(handle, s) {
+        this.remove(handle, s);
+        try {
+            s.close();
+        }
+        catch { /* the client's socket is gone already */ }
+    }
+}

package/dist/host/fake-arcade.d.ts

@@ -0,0 +1,40 @@
+import { Transaction } from "@bsv/sdk";
+export interface ArcadeStatus {
+    txStatus: string;
+    merklePath?: string;
+    blockHash?: string;
+    blockHeight?: number;
+}
+export declare class FakeArcade {
+    url: string;
+    eventsUrl: string;
+    /** "ok"; "reject": a 400 with a reason; "busy": 503 + Retry-After (not taken). */
+    mode: "ok" | "reject" | "busy";
+    readonly txs: Map<string, ArcadeStatus & {
+        token: string;
+    }>;
+    readonly posts: Uint8Array[];
+    readonly postHeaders: Array<Record<string, string | string[] | undefined>>;
+    readonly gets: string[];
+    /** The Last-Event-ID of each SSE connection, in order (undefined: none sent). */
+    readonly connects: Array<string | undefined>;
+    private log;
+    private conns;
+    private clock;
+    private servers;
+    static start(): Promise<FakeArcade>;
+    /** The transaction Arcade received in a POST body: Extended Format, else raw. */
+    static txOf(body: Uint8Array): Transaction;
+    private api;
+    private events;
+    private write;
+    /** A status for a transaction Arcade took: recorded, and streamed to its token's connections. The event's id. */
+    emit(txid: string, s: ArcadeStatus): string;
+    /** The body Arcade would post to a webhook for the last status of `txid`. */
+    webhookBody(txid: string): Record<string, unknown>;
+    /** Open SSE connections. */
+    get streams(): number;
+    /** Drop every SSE connection (a network blip). */
+    drop(): void;
+    close(): Promise<void>;
+}

package/dist/host/fake-arcade.js

@@ -0,0 +1,149 @@
+// A fake Arcade (bsv-blockchain/arcade) for the tests (#58): its API on one
+// port — POST /tx (Extended Format or raw bytes; 202 {txid, status,
+// txStatus: "RECEIVED"}, a duplicate echoing its current status, 400 with a
+// reason, 503 + Retry-After under "backpressure"), GET /tx/:txid (404 for a
+// txid it never took) — and its SSE service on another: GET
+// /events?callbackToken=<token>, every transaction submitted under the
+// token, ids increasing (nanosecond timestamps, as Arcade's), `Last-Event-ID`
+// replaying what came after it, the current status of each transaction
+// without one. The test drives the statuses (`emit`); Arcade's webhook is the
+// test's to post.
+import { createServer } from "node:http";
+import { Transaction } from "@bsv/sdk";
+export class FakeArcade {
+    url = "";
+    eventsUrl = "";
+    /** "ok"; "reject": a 400 with a reason; "busy": 503 + Retry-After (not taken). */
+    mode = "ok";
+    txs = new Map();
+    posts = [];
+    postHeaders = [];
+    gets = [];
+    /** The Last-Event-ID of each SSE connection, in order (undefined: none sent). */
+    connects = [];
+    log = [];
+    conns = [];
+    clock = 1790000000000000000n;
+    servers = [];
+    static async start() {
+        const a = new FakeArcade();
+        const api = createServer((req, res) => void a.api(req, res));
+        const events = createServer((req, res) => a.events(req, res));
+        for (const s of [api, events])
+            await new Promise((r) => s.listen(0, "127.0.0.1", r));
+        a.servers = [api, events];
+        a.url = `http://127.0.0.1:${api.address().port}`;
+        a.eventsUrl = `http://127.0.0.1:${events.address().port}/events`;
+        return a;
+    }
+    /** The transaction Arcade received in a POST body: Extended Format, else raw. */
+    static txOf(body) {
+        try {
+            return Transaction.fromEF([...body]);
+        }
+        catch {
+            return Transaction.fromBinary([...body]);
+        } // not EF: raw, whose failure the caller answers 400
+    }
+    async api(req, res) {
+        const chunks = [];
+        for await (const c of req)
+            chunks.push(c);
+        const body = new Uint8Array(Buffer.concat(chunks));
+        const send = (status, v, h = {}) => { res.writeHead(status, { "content-type": "application/json", ...h }); res.end(JSON.stringify(v)); };
+        const path = new URL(req.url ?? "/", "http://x").pathname;
+        if (req.method === "POST" && path === "/tx") {
+            this.posts.push(body);
+            this.postHeaders.push({ ...req.headers });
+            if (this.mode === "busy")
+                return send(503, { status: 503, title: "Service Unavailable", detail: "backpressure" }, { "retry-after": "1" });
+            let tx;
+            try {
+                tx = FakeArcade.txOf(body);
+            }
+            catch (e) {
+                return send(400, { status: 400, reason: `not a transaction: ${e.message}` });
+            }
+            const txid = tx.id("hex");
+            if (this.mode === "reject")
+                return send(400, { status: 400, txid, reason: "rejected by the test" });
+            const had = this.txs.get(txid);
+            if (had)
+                return send(202, { txid, status: 202, txStatus: had.txStatus });
+            this.txs.set(txid, { txStatus: "RECEIVED", token: String(req.headers["x-callbacktoken"] ?? "") });
+            return send(202, { txid, status: 202, txStatus: "RECEIVED" });
+        }
+        const m = /^\/tx\/([0-9a-f]{64})$/.exec(path);
+        if (req.method === "GET" && m) {
+            this.gets.push(m[1]);
+            const t = this.txs.get(m[1]);
+            if (!t)
+                return send(404, { status: 404, title: "Not Found", detail: "transaction not found" });
+            return send(200, { txid: m[1], txStatus: t.txStatus, status: t.txStatus, blockHash: t.blockHash ?? null, blockHeight: t.blockHeight ?? 0, merklePath: t.merklePath ?? null, extraInfo: "" });
+        }
+        send(404, { status: 404, title: "Not Found" });
+    }
+    events(req, res) {
+        const u = new URL(req.url ?? "/", "http://x");
+        if (u.pathname !== "/events") {
+            res.writeHead(404).end();
+            return;
+        }
+        const token = u.searchParams.get("callbackToken") ?? "";
+        const last = req.headers["last-event-id"];
+        this.connects.push(last);
+        res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+        res.write(": keepalive\n\n");
+        const mine = this.log.filter((e) => e.token === token);
+        if (last !== undefined) {
+            for (const e of mine)
+                if (BigInt(e.id) > BigInt(last))
+                    this.write(res, e);
+        }
+        else {
+            // No id: the current status of every transaction under the token.
+            const latest = new Map();
+            for (const e of mine)
+                latest.set(String(e.data.txid), e);
+            for (const e of latest.values())
+                this.write(res, e);
+        }
+        const c = { res, token };
+        this.conns.push(c);
+        res.on("close", () => { this.conns = this.conns.filter((x) => x !== c); });
+    }
+    write(res, e) {
+        res.write(`id: ${e.id}\nevent: status\ndata: ${JSON.stringify(e.data)}\n\n`);
+    }
+    /** A status for a transaction Arcade took: recorded, and streamed to its token's connections. The event's id. */
+    emit(txid, s) {
+        const t = this.txs.get(txid);
+        if (!t)
+            throw new Error(`the fake Arcade never took ${txid}`);
+        // Its status now (a reorg's SEEN_ON_NETWORK drops the block and the path).
+        this.txs.set(txid, { token: t.token, ...s });
+        this.clock += 1000000n;
+        const e = { id: String(this.clock), token: t.token, data: { timestamp: new Date().toISOString(), txid, ...s } };
+        this.log.push(e);
+        for (const c of this.conns)
+            if (c.token === t.token)
+                this.write(c.res, e);
+        return e.id;
+    }
+    /** The body Arcade would post to a webhook for the last status of `txid`. */
+    webhookBody(txid) {
+        const e = this.log.filter((x) => x.data.txid === txid).at(-1);
+        if (!e)
+            throw new Error(`no status for ${txid}`);
+        return e.data;
+    }
+    /** Open SSE connections. */
+    get streams() { return this.conns.length; }
+    /** Drop every SSE connection (a network blip). */
+    drop() { for (const c of this.conns)
+        c.res.end(); this.conns = []; }
+    async close() {
+        this.drop();
+        await Promise.all(this.servers.map((s) => new Promise((r) => { s.closeAllConnections?.(); s.close(() => r()); })));
+    }
+}

package/dist/host/fake-discovery.d.ts

@@ -0,0 +1,4 @@
+import type { HostDb } from "./instances.ts";
+import type { Router, RouterRequest, RouterResponse } from "./router.ts";
+/** The router's `discovery` option: manifest and resolve over host.db's rows. */
+export declare function fakeDiscovery(db: HostDb, router: () => Router): (req: RouterRequest, url: URL) => Promise<RouterResponse | undefined>;

package/dist/host/fake-discovery.js

@@ -0,0 +1,58 @@
+// A stand-in for the host skein's BRC-169 server, for tests and equivs that
+// run no host skein (#113). On a host, the router's own origin's discovery
+// requests go to the host skein's onboarding app (shruggr/skein-onboard),
+// which answers from its records; a test host that only wants its agents
+// and mailbox instances to find each other (the resolve program, the loop,
+// the corpus) answers them here instead, from host.db, as the router did
+// before #113: an agent's own identity, a mailbox instance's owner's, the
+// instance's origin as the messagebox, a certificate signed by the
+// certifier key with a serial number of the binding; and a registration
+// (POST /account/register, the #113 contract: signed over `register
+// <name>@<domain>`) answered with the mailbox instance the manager's create
+// makes, without a certificate (the browser page's own mailbox). Not part of
+// anything that runs (the router's `discovery` option is a test's).
+import { Hash, ProtoWallet, Utils } from "@bsv/sdk";
+import { issueHandleCertificate, RESOLVE_PATH, SEARCH_PATH } from "./handles.js";
+import { domainOf, REGISTER_PROTOCOL } from "./router.js";
+const json = (status, v) => ({ status, headers: { "content-type": "application/json" }, body: new TextEncoder().encode(JSON.stringify(v)) });
+/** The router's `discovery` option: manifest and resolve over host.db's rows. */
+export function fakeDiscovery(db, router) {
+    return async (req, url) => {
+        const r = router();
+        if (req.method === "GET" && url.pathname === "/manifest.json") {
+            const { publicKey } = await r.certifier.getPublicKey({ identityKey: true });
+            return json(200, { metanet: { trust: { publicKey }, handles: { version: "1.0", resolve: `${r.origin()}${RESOLVE_PATH}`, search: `${r.origin()}${SEARCH_PATH}` } } });
+        }
+        if (req.method === "GET" && url.pathname === RESOLVE_PATH) {
+            const q = (url.searchParams.get("handle") ?? "").replace(/^@/, "");
+            const own = domainOf(url.hostname);
+            const [h0, d] = q.includes("@") ? q.split("@") : [q, own];
+            const handle = h0.split("+")[0].toLowerCase(), domain = (d ?? own).toLowerCase();
+            if (!handle)
+                return json(400, { metanetHandles: "1.0", error: { code: "malformed-handle", message: "want ?handle=<handle>" } });
+            const row = db.get(handle);
+            const key = db.identityOf(handle, domain);
+            if (!row || row.status !== "enabled" || !key)
+                return json(404, { metanetHandles: "1.0", error: { code: "handle-not-found", message: `no handle ${handle}@${domain} here` } });
+            const serial = Utils.toBase64(Hash.sha256(Utils.toArray(`${handle}@${domain} ${key}`, "utf8")));
+            const c = await issueHandleCertificate(r.certifier, handle, domain, key, serial);
+            const certificate = { type: c.type, serialNumber: c.serialNumber, subject: c.subject, certifier: c.certifier, revocationOutpoint: c.revocationOutpoint, fields: c.fields, signature: c.signature };
+            return json(200, { metanetHandles: "1.0", handle, domain, identityKey: key, certificate, messagebox: r.originOf(handle), ttl: 300, revoked: false });
+        }
+        if (req.method === "POST" && url.pathname === "/account/register") {
+            const b = JSON.parse(new TextDecoder().decode(req.body));
+            const domain = await r.handleDomain();
+            const v = await new ProtoWallet("anyone").verifySignature({ protocolID: REGISTER_PROTOCOL, keyID: b.username, counterparty: b.identityKey, data: Utils.toArray(`register ${b.username}@${domain}`, "utf8"), signature: Utils.toArray(b.signature, "hex") }).catch(() => ({ valid: false }));
+            if (!v.valid)
+                return json(401, { error: "the signature does not verify for that identity" });
+            try {
+                const c = await r.createInstance(b.username, b.identityKey, { image: "mailbox", domain });
+                return json(200, { handle: c.handle, domain, identityKey: b.identityKey, messagebox: c.url });
+            }
+            catch (e) {
+                return json(409, { error: e.message });
+            }
+        }
+        return undefined;
+    };
+}

package/dist/host/feeds.d.ts

@@ -0,0 +1,127 @@
+import { CID } from "multiformats/cid";
+export type FeedSpec = {
+    kind: "headers";
+    url: string;
+    box?: string;
+};
+export interface FeedsOptions {
+    /** A run of headers (parents first) for `handle`'s box: into the host chain, the event on a change (Router.chainHeaders, #156). */
+    headers(handle: string, box: string, raws: Uint8Array[]): Promise<unknown>;
+    log?(source: string, line: string): void;
+    /** Items waiting for admission per instance (default 1000). */
+    maxQueue?: number;
+    /** Reconnect backoff, ms (default 500 → 30 000, doubling). */
+    backoff?: {
+        min: number;
+        max: number;
+    };
+    fetch?: typeof fetch;
+}
+export declare const DEFAULT_BOX = "chain";
+/** A transaction's CID: bitcoin-tx (0xb1), dbl-sha2-256 (0x56) over the txid in internal byte order. */
+export declare function txCid(txid: string): CID;
+/** The feeds a genesis declares (`feeds`), the malformed ones (and a pre-#58 `arc-callback`) left out. */
+export declare function feedsOf(g: Record<string, unknown> | null | undefined): FeedSpec[];
+/**
+ * The 80 bytes of a header given as chaintracks' JSON (Arcade's tip stream):
+ * version, previousHash, merkleRoot (display order: reversed into raw),
+ * time, bits, nonce — and, with `hash`, checked against their sha256d. Not
+ * that form: undefined. A `hash` that does not match: an Error saying so.
+ */
+export declare function headerOfFields(o: Record<string, unknown>): Uint8Array | Error | undefined;
+/**
+ * Header bytes out of one SSE event's data: hex, JSON with header/raw/hex,
+ * chaintracks' fields (headerOfFields), or an array of those. A header whose
+ * `hash` is not its fields' is left out, and `drop` told why.
+ */
+export declare function headersOf(data: string, drop?: (why: string) => void): Uint8Array[];
+/** Arcade's (and ARC's) status JSON — an SSE event's data, a webhook's body — as a `status` event record, or why not. */
+export declare function statusOf(v: unknown): Record<string, unknown> | string;
+/** One event of a text/event-stream: its data lines joined, its `id` and `event` fields if it had them. */
+export interface SseEvent {
+    data: string;
+    id?: string;
+    event?: string;
+}
+export interface SseOptions {
+    /** Request headers besides Accept and Last-Event-ID. */
+    headers?: Record<string, string>;
+    /** Resume after this event id (a remembered one: the first connection sends it as Last-Event-ID). */
+    lastId?: string;
+    /** Reconnect backoff, ms (default 500 → 30 000, doubling; back to the minimum once an event arrived). */
+    backoff?: {
+        min: number;
+        max: number;
+    };
+    fetch?: typeof fetch;
+    log?(line: string): void;
+}
+/**
+ * One SSE subscription held open (#33, #58): connects, parses the stream,
+ * hands each event to `onEvent` — awaited before the next one is read and
+ * before its id counts as seen, so a caller that remembers `lastId` after it
+ * never skips an event — and reconnects with backoff, sending the last id
+ * seen as `Last-Event-ID`.
+ */
+export declare class SseStream {
+    readonly url: string;
+    lastId?: string;
+    private abort;
+    private stopped;
+    private readonly o;
+    private readonly onEvent;
+    private running?;
+    constructor(url: string, onEvent: (ev: SseEvent) => Promise<void> | void, o?: SseOptions);
+    start(): this;
+    /** Close the connection; no reconnect. Resolves once the loop has ended (an event being handled finishes first). */
+    stop(): Promise<void>;
+    private say;
+    private connect;
+    /** Parse the event stream (text/event-stream): `data:` lines until a blank line make one event; `id:` and `event:` go with it. */
+    private read;
+}
+/** Headers per backfill run (#141): one `headers` frame each, parents first (#156). */
+export declare const BACKFILL_RUN = 2016;
+export declare class Feeds {
+    readonly o: FeedsOptions;
+    private sse;
+    private declared;
+    private hosted;
+    private listeners;
+    private queues;
+    private stopped;
+    constructor(o: FeedsOptions);
+    private say;
+    /** `handle`'s feeds are these (replacing what it declared before). */
+    declare(handle: string, specs: FeedSpec[]): void;
+    /**
+     * The host's own feed (#102) for `handle`: subscribed to it (`spec`), or not (undefined); a genesis's feeds are kept.
+     * `backfill` (#141): on subscribing, the headers the instance lacks up to the host's tip — read after the
+     * subscription is in place; until they are queued, the live items wait behind them (held), and a live header
+     * the backfill carries too is dropped. Admitted first, in runs of BACKFILL_RUN, then the live stream.
+     */
+    host(handle: string, spec: FeedSpec | undefined, backfill?: () => Promise<Uint8Array[]>): Promise<void>;
+    private queue;
+    /**
+     * The host's own listener on a headers feed (#132: the default image's
+     * chain part grows by it): every header the stream brings, as well as the
+     * subscribers'. The connection stays open while a listener is on it.
+     */
+    listen(url: string, fn: (raws: Uint8Array[]) => void): void;
+    /** Whether `handle` is subscribed to the host's own feed. */
+    hosts(handle: string): boolean;
+    /** Subscribe `handle` to what it declared and the host's feed for it, and to nothing else. */
+    private subscribe;
+    /** The one connection to `url`, opened if it is not. */
+    private connect;
+    /** The declared feeds of `handle`. */
+    of(handle: string): FeedSpec[];
+    /** Close every connection (no reconnect); resolves once their loops have ended. */
+    stop(): Promise<void>;
+    /** Queue a run of headers for `handle` (bounded), and drain the queue serially. */
+    push(handle: string, box: string, raws: Uint8Array[]): void;
+    /** How many items wait for `handle` (tests). */
+    pending(handle: string): number;
+    private drain;
+    private dispatch;
+}