@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/host/providers.d.ts

@@ -0,0 +1,238 @@
+import { type PrivateKey } from "@bsv/sdk";
+import type { CID } from "multiformats/cid";
+/** The signing a provider's answer and an intention's request get (BRC-169 §7.2, on skein's mail record); an emit is unsigned (#126 step 4). */
+export declare const MESSAGE_PROTOCOL: [2, string];
+export declare const MESSAGE_KEY_ID = "send";
+/** The stream protocol a signed message travels on to a libp2p recipient. */
+export declare const MESSAGE_STREAM = "/skein/message/1.0.0";
+/** A message as the kernel keeps it: an emit's unsigned, a provider's answer and an intention's request signed. */
+export interface MailRecord {
+    kind: "mail";
+    op: "put";
+    sender: Uint8Array;
+    recipient: Uint8Array;
+    box: string;
+    body: CID;
+    subject?: CID;
+    nonce?: Uint8Array;
+    signature?: Uint8Array;
+    [k: string]: unknown;
+}
+/** What the kernel hands over (the serve frame `emit`). */
+export interface Outgoing {
+    message: MailRecord;
+    body: Uint8Array;
+    transport: string;
+    address: string;
+    /** #148: an event's place in the log, beside the record (the kernel's notice): the entry its step processed, the update's seq, the index in `emitted`, the thread. */
+    place?: {
+        n: number | bigint;
+        seq: number | bigint;
+        i: number | bigint;
+        thread: CID;
+    };
+}
+/** The stock providers' names (each one's address on this host: `local`, <name>). */
+export declare const PROVIDERS: readonly ["fetch", "waker", "cron", "libp2p", "status", "manager", "certifier", "billing"];
+/** The providers only the host skein's address book names (#90, #113): they act for it alone. */
+export declare const HOST_SKEIN_PROVIDERS: readonly ProviderName[];
+/** Keys no address book names (#130: the host's billing key signs its ticks; it is not reached). */
+export declare const UNADDRESSED: readonly ProviderName[];
+export type ProviderName = typeof PROVIDERS[number];
+/** The intentions a step records and the runtime answers (#126). */
+export type Intention = "fetch" | "deadline";
+export type HttpRequest = {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    timeoutMs?: number;
+    maxBytes?: number;
+};
+export type HttpResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array;
+};
+export interface ProvidersOptions {
+    /** A provider's key (the reference host: a child of its master secret). */
+    keyOf(name: ProviderName): PrivateKey;
+    /** The instance `handle`'s identity key (33 bytes), or undefined when it is not known. */
+    identity(handle: string): Promise<Uint8Array | undefined>;
+    /** Append a message (its package: a provider's signed answer, or the loopback's own emit) into `handle` as a `local` request. */
+    append(handle: string, pkg: {
+        kind: "message";
+        message: MailRecord;
+        body: Uint8Array;
+    }): Promise<unknown>;
+    /**
+     * Sign `data` with the instance `handle`'s own key, BRC-169's way ([2, "metanet handles
+     * envelope"], key "send", counterparty anyone) → the DER signature (#126: the request the
+     * runtime sends for an intention a step recorded is the instance's, signed by its wallet).
+     */
+    sign(handle: string, data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Where this host sends an intention (#126) — host wiring, not an instance setting nor an
+     * address-book role: the service by name (`fetch`: the HTTP proxy; `deadline`: the waker), on
+     * this host (`local`, the only transport wired so far). Default: this host's own providers.
+     */
+    route?: Partial<Record<Intention, {
+        transport: "local";
+        address: ProviderName;
+    }>>;
+    /** The HTTP proxy's network: one request, this host's own URLs in process. */
+    fetch(req: HttpRequest, from: string): Promise<HttpResponse>;
+    /** The broadcaster (#58, #65: the host's Arcade), when the host has one: a broadcast event's transaction and BEEF, queued. */
+    broadcast?(handle: string, tx: Uint8Array, beef?: Uint8Array): void;
+    /** The libp2p node's subscriptions (#119), beacons (#126) and liveness (#138): a `subscribe` / `unsubscribe` / `beacon` / `unbeacon` / `liveness` / `unliveness` record {kind: "event", event, app, topic, …} from `handle`. Absent: no libp2p node (dropped). */
+    topicEvent?(handle: string, record: Record<string, unknown>): void;
+    /** #148: every event record {kind: "event", event, …} from `handle`, whatever its name, as it is handed over (after its step's commit), with its place in the log — sent on to the event streams (events.ts). Besides what its name is wired to. */
+    emitted?(handle: string, record: Record<string, unknown>, place: {
+        n: number;
+        seq: number;
+        i: number;
+        thread: CID;
+    }): void;
+    /** The cron provider's schedule (#69, cron.ts): a request from `handle` (key `sender`), the message `id` → the answer body. Absent: no cron provider. */
+    cron?(handle: string, sender: string, id: string, body: unknown): Record<string, unknown>;
+    /**
+     * The instance manager (#90, Router): `from()` names the host skein (its
+     * handle and identity, hex) — the one sender it acts for (none: it acts for
+     * nobody); `request` does a create, start or stop → the answer body.
+     */
+    manager?: {
+        from(): {
+            handle: string;
+            identity: string;
+        } | undefined;
+        /** #162 (SKEIN_MANAGER_FOR): the other instances the instance manager acts for (not the certifier), each its handle and identity (hex). */
+        alsoFor?(): Array<{
+            handle: string;
+            identity: string;
+        }>;
+        request(box: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    };
+    /** The certifier (#113): an issue request from the host skein → the answer body (handles.ts). Absent: none. */
+    certifier?(box: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * #164: an application host's wiring — an event record {kind: "event", event, app?, …} from `handle`
+     * whose name no stock wiring takes (not broadcast, an intention, payment, nor the libp2p node's),
+     * handed over after its step's commit as `topicEvent`'s are. Absent: logged as ignored.
+     */
+    appEvent?(handle: string, record: Record<string, unknown>): void;
+    /**
+     * #157: a `deliver` event from `handle` (its CID and record): the host carries it (deliver.ts) and
+     * admits the answer → whether an answer was admitted. Handed over again at the instance's next
+     * start while the thread awaits it: carried again then only if no answer came. Absent: ignored.
+     */
+    deliver?(handle: string, event: CID, record: Record<string, unknown>): Promise<boolean>;
+    /** #130: a `payment` event from `handle` — its pay step's (the kernel lets no other step emit one). Absent: no billing (ignored). */
+    payment?(handle: string, record: Record<string, unknown>): void;
+    /** The libp2p host, when there is one: the instance's node does the work. */
+    p2p?: {
+        publish(handle: string, topic: string, body: Uint8Array): Promise<{
+            seqno: Uint8Array;
+            recipients: number;
+        }>;
+        dial(handle: string, peer: string, protocol: string, frames: (f: {
+            body: Uint8Array;
+        } | {
+            closed: true;
+            error?: string;
+        }) => void): Promise<number>;
+        send(handle: string, stream: number, body: Uint8Array): Promise<void>;
+        close(handle: string, stream: number): Promise<void>;
+    };
+    /** The clock (ms), as entries are stamped. */
+    now(): number;
+    log?(source: string, line: string): void;
+}
+/** The fetch provider's refusal of a response over the request's `maxBytes` (#91). */
+export declare const tooLarge: (max: number) => string;
+export declare class Providers {
+    readonly o: ProvidersOptions;
+    private wallets;
+    private keys;
+    /** Messages taken (handle + CID), so a message handed over again (a kernel's start) is acted on once. */
+    private taken;
+    /** The waker's timers, by handle + the wake-me's CID. */
+    private timers;
+    /** Messages being carried now, and the waker's answers being appended. */
+    private inflight;
+    private stopped;
+    constructor(o: ProvidersOptions);
+    private say;
+    /** A provider's identity key (hex). */
+    key(name: ProviderName): string;
+    private wallet;
+    /** The address book entries a genesis seeds for this host's providers: key, transport `local`, address the name (#126: no role). */
+    entries(names?: readonly ProviderName[]): Array<{
+        key: Uint8Array;
+        transport: "local";
+        address: string;
+    }>;
+    /** Stop the timers; nothing more is carried. */
+    stop(): void;
+    /** A message (or an event, #65) from `handle` to carry out (the kernel's `emit` notice). */
+    deliver(handle: string, out: Outgoing): void;
+    private track;
+    /** Whether anything is being carried now (a waker's timer is not: it is waiting). */
+    busy(): boolean;
+    /** Until what is being carried now is done (tests, the corpus: Router.settled). */
+    idle(): Promise<void>;
+    /**
+     * An event out (#65, #119): addressed to no one, acted on by its name —
+     * `broadcast` → the broadcaster (Arcade); `subscribe` / `unsubscribe` → the
+     * libp2p node (the topics it subscribes: p2p.ts; delivery is the kernel's, by the subscription); any other name: the application host's `appEvent` when it has one (#164), else a log
+     * line, nothing else (the step is not told). A broadcast is acted on every
+     * time it is handed over (a kernel's start hands over again what a waiting
+     * thread awaits: the queue takes a transaction once); any other event is
+     * handed over once.
+     */
+    private event;
+    private carry;
+    /** A signed message from provider `name` to the instance that sent `to`, in `to`'s box: {replyTo, …answer}, appended. */
+    answer(handle: string, name: ProviderName, to: MailRecord, id: CID, answer: Record<string, unknown>, box?: string): Promise<void>;
+    /**
+     * A signed message from provider `name` to `recipient` (the instance
+     * `handle`), in `box`, its body `body` — an answer, a tick (#69), a status
+     * (#65) — appended there as a `local` request (what the append answers:
+     * the entry). Its own message (two like bodies are two messages:
+     * `nonce`), about `subject` if given.
+     */
+    send(handle: string, name: ProviderName, recipient: Uint8Array, box: string, body: Record<string, unknown>, subject?: CID): Promise<unknown>;
+    /** A message to the fetch provider (a module on an SDK before #126: fetch was a message to it). */
+    private fetch;
+    /** The HTTP proxy (#70, #126): one request {method, url, headers?, body?, timeoutMs?, maxBytes?} → {status, headers, body} | {error}. */
+    private proxy;
+    /**
+     * An intention a step recorded (#126: a `deadline`, a `fetch` event), handed
+     * over once its step is committed: the request is the instance's, signed by
+     * its wallet — the mail record {kind: "mail", op: "put", sender: <the
+     * instance>, recipient: <the service's key>, box, body: <the event's CID>,
+     * nonce, signature} — sent where this host is wired (`route`: its own waker
+     * or HTTP proxy, `local`). The service's answer is a signed message from its
+     * key whose body names the event (`replyTo`) and carries that request
+     * (`request`), appended as a `local` request: the front door checks its
+     * signature, the kernel the request's (scheduler.zig intentionAnswer), and
+     * the thread awaiting the event steps — `woke` at a deadline, `reply` with a
+     * fetch's response ({status, headers, body} | {error}).
+     */
+    private intention;
+    /** Run `fire` at `at` (by the clock `now`), once per (handle, id). */
+    private timer;
+    /** A wake-me message (a kernel before #126: a deadline was a message to the waker), kept for such a log's waiting threads. */
+    private wake;
+    /**
+     * Answer now every wake-me that is due by the clock (`now`): what the
+     * timers do in real time, for a clock that is not (a script clock: tests,
+     * the corpus). The answers are being appended when it returns (idle()).
+     */
+    wakeDue(): void;
+    /** The earliest wake the waker owes `handle` (ms), if any (the host page). */
+    nextWake(handle: string): number | undefined;
+    private p2p;
+    /** A message to a libp2p recipient: its package published on the topic, or written to the peer on MESSAGE_STREAM. */
+    private libp2pRecipient;
+    private cron;
+}