ankka 0.6.0

package/dist/server/eventSourced.js

@@ -0,0 +1,168 @@
+// The event sourced conversation: one bidirectional stream per loaded instance. The sidecar sends
+// `Init` (with the recovered snapshot, if any), the events after it, then commands one at a time; we fold
+// the events, run each command against the state we hold, and answer with the effect as data — the
+// events to persist, the retention, and a reply computed from the state *after* those events.
+//
+// The generator's locals are the instance's whole state. Commands are awaited in arrival order inside
+// it, which is what makes "one command in flight" true without a lock. When the stream ends — the
+// sidecar passivated the instance or went away, and we cannot tell which — the locals go with it.
+import { create } from "@bufbuild/protobuf";
+import { EventSourced, EventSourcedOutSchema, } from "../_proto/ankka/protocol/v1/event_sourced_pb.js";
+import { codecFor } from "../codec.js";
+import { commandContext, metadataFromProto } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
+import { binaryCodecs } from "../codec.js";
+import { errorCodeToProto } from "../kinds.js";
+import { materialiseEventSourced } from "../materialise.js";
+import { decodePayload, encodePayload } from "./payloads.js";
+/** Retention as the protocol carries it; `undefined` when the effect asked for none. */
+export function retentionToProto(retention) {
+    if (!retention)
+        return undefined;
+    switch (retention.kind) {
+        case "delete-now":
+            return { retention: { case: "deleteNow", value: {} } };
+        case "expire-after":
+            return { retention: { case: "expireAfter", value: { millis: BigInt(retention.after.toMillis()) } } };
+    }
+}
+function failure(commandId, error) {
+    return create(EventSourcedOutSchema, { message: { case: "failure", value: { commandId, error: { message: error.message, code: errorCodeToProto(error.code) } } } });
+}
+function messageOf(e) {
+    return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+export function eventSourcedRoutes(router, ctx) {
+    router.service(EventSourced, {
+        handle: (requests) => handleEventSourced(requests, ctx),
+    });
+}
+export async function* handleEventSourced(requests, ctx) {
+    let registered;
+    let entity;
+    let entityId = "";
+    let state;
+    let sequence = 0n;
+    for await (const m of requests) {
+        switch (m.message.case) {
+            case "init": {
+                const init = m.message.value;
+                const found = ctx.registry.component(init.componentId);
+                if (!found || found.kind !== "event-sourced") {
+                    yield failure(0n, { message: `no event sourced entity ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound });
+                    return;
+                }
+                registered = found;
+                entityId = init.entityId;
+                try {
+                    entity = new registered.cls();
+                    entity._bindInstance(entityId);
+                    if (init.snapshot) {
+                        state = decodePayload(registered.stateCodec, init.snapshot.payload);
+                        sequence = init.snapshot.sequence;
+                    }
+                    else {
+                        state = entity.emptyState();
+                        sequence = 0n;
+                    }
+                }
+                catch (e) {
+                    ctx.log(`ankka: ${init.componentId}/${entityId}: recovery failed: ${messageOf(e)}`);
+                    yield failure(0n, { message: `recovery failed: ${messageOf(e)}`, code: ErrorCode.Internal });
+                    return;
+                }
+                break;
+            }
+            case "event": {
+                if (!registered || !entity) {
+                    yield failure(0n, { message: "an event arrived before Init", code: ErrorCode.Internal });
+                    return;
+                }
+                const ev = m.message.value;
+                try {
+                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload));
+                    sequence = ev.sequence;
+                }
+                catch (e) {
+                    ctx.log(`ankka: ${registered.id}/${entityId}: replay of event ${ev.sequence} failed: ${messageOf(e)}`);
+                    yield failure(0n, { message: `replay of event ${ev.sequence} failed: ${messageOf(e)}`, code: ErrorCode.Internal });
+                    return;
+                }
+                break;
+            }
+            case "command": {
+                if (!registered || !entity) {
+                    yield failure(m.message.value.id, { message: "a command arrived before Init", code: ErrorCode.Internal });
+                    return;
+                }
+                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx);
+                yield result.out;
+                if (result.newState !== undefined) {
+                    state = result.newState.state;
+                    sequence = result.newState.sequence;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+}
+async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx) {
+    const handler = registered.handlers.get(cmd.name);
+    if (!handler)
+        return { out: failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound }) };
+    let input;
+    try {
+        input = handler.input ? decodePayload(codecFor(handler.input), cmd.payload) : undefined;
+    }
+    catch (e) {
+        return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest }) };
+    }
+    const metadata = metadataFromProto(cmd.metadata);
+    const context = commandContext(registered.id, entityId, sequence, metadata);
+    let effect;
+    entity._bindCommand(state, context, ctx.client.withMetadata(metadata));
+    try {
+        effect = (await handler.run(entity, input));
+    }
+    catch (e) {
+        ctx.log(`ankka: ${registered.id}/${entityId}/${cmd.name} threw: ${messageOf(e)}`);
+        return { out: failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal }) };
+    }
+    finally {
+        entity._unbindCommand();
+    }
+    if (handler.readOnly && effect?.kind !== "read-only") {
+        return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name} is a query and returned a persisting effect`, code: ErrorCode.Internal }) };
+    }
+    try {
+        const m = materialiseEventSourced(effect, state, (s, e) => entity.applyEvent(s, e));
+        const events = m.events.map((e) => encodePayload(registered.eventCodec, e));
+        const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
+        const outcome = m.error
+            ? { outcome: { case: "error", value: { message: m.error.message, code: errorCodeToProto(m.error.code) } } }
+            : m.noReply
+                ? { outcome: { case: "noReply", value: {} } }
+                : { outcome: { case: "reply", value: { payload: encodePayload(replyCodec, m.reply), metadata: { entries: [] } } } };
+        const out = create(EventSourcedOutSchema, {
+            message: {
+                case: "reply",
+                value: {
+                    commandId: cmd.id,
+                    events,
+                    retention: retentionToProto(m.retention),
+                    outcome,
+                    snapshot: cmd.snapshotRequested ? encodePayload(registered.stateCodec, m.newState) : undefined,
+                },
+            },
+        });
+        if (m.error)
+            return { out };
+        return { out, newState: { state: m.newState, sequence: sequence + BigInt(events.length) } };
+    }
+    catch (e) {
+        ctx.log(`ankka: ${registered.id}/${entityId}/${cmd.name}: the effect could not be applied: ${messageOf(e)}`);
+        return { out: failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal }) };
+    }
+}

package/dist/server/http.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type HttpRequest, type HttpReply, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
+import type { ServerContext } from "./server.ts";
+export interface HttpDispatcher {
+    handle(req: HttpRequest): Promise<HttpReply>;
+    handleStream(req: HttpRequest): AsyncIterable<StreamFrame>;
+}
+/** The behaviour behind `Http.Handle` and `Http.HandleStream`, over the registry's endpoints. */
+export declare function createHttpDispatcher(ctx: ServerContext): HttpDispatcher;
+export declare function httpRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/http.js

@@ -0,0 +1,153 @@
+// HTTP requests the sidecar forwards for the routes we declared. The sidecar's router matched the route,
+// applied the access rule and opened the span; here the handler runs. One endpoint instance serves every
+// request, so the request itself lives in the async context (`this.request`), never on the instance.
+//
+// `createHttpDispatcher` is the whole behaviour; the Connect servicer and the endpoint unit testkit both
+// call it, so a test cannot pass on a path the sidecar would not take.
+import { create } from "@bufbuild/protobuf";
+import { Http, HttpReplySchema, StreamFrameSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
+import { codecFor } from "../codec.js";
+import { Headers, Query, metadataFromProto, withRequest } from "../context.js";
+import { CommandError, ErrorCode, httpStatusOf } from "../effects/common.js";
+import { DecodingError } from "../json.js";
+import { errorCodeToProto } from "../kinds.js";
+import { HttpProblem } from "../routes.js";
+import { done, resolve } from "../schema.js";
+import { AsyncQueue } from "./queue.js";
+const utf8 = new TextEncoder();
+function textResponse(status, text) {
+    return create(HttpReplySchema, { message: { case: "response", value: { status, contentType: "text/plain; charset=utf-8", body: utf8.encode(text), headers: [] } } });
+}
+function failureReply(message) {
+    return create(HttpReplySchema, { message: { case: "failure", value: { commandId: 0n, error: { message, code: errorCodeToProto(ErrorCode.Internal) } } } });
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function principalOf(req) {
+    const p = req.principal;
+    if (!p)
+        return null;
+    return Object.freeze({ subject: p.subject, name: p.name ?? null, email: p.email ?? null, emailVerified: p.emailVerified, roles: Object.freeze([...p.roles]) });
+}
+/** A path parameter as its declared schema: strings as they are, scalars through their text codec. */
+function parseParam(name, text, shape) {
+    if (!shape)
+        return text;
+    const r = resolve(shape);
+    if (r.kind === "string")
+        return text;
+    const codec = codecFor(shape);
+    if (codec.contentType !== "text/plain")
+        throw new DecodingError(`a path parameter must be a scalar, not ${r.kind}`, name);
+    try {
+        return codec.decode(utf8.encode(text));
+    }
+    catch (e) {
+        throw new DecodingError(`path parameter ${name}: ${messageOf(e)}`, name);
+    }
+}
+function encodeResult(route, result) {
+    if (result === undefined || result === done) {
+        return create(HttpReplySchema, { message: { case: "response", value: { status: 204, contentType: "", body: new Uint8Array(), headers: [] } } });
+    }
+    if (!route.reply)
+        return failureReply(`route ${route.method} ${route.template} returned a value but declares no reply shape`);
+    const codec = codecFor(route.reply);
+    const contentType = codec.contentType === "text/plain" ? "text/plain; charset=utf-8" : codec.contentType;
+    return create(HttpReplySchema, { message: { case: "response", value: { status: 200, contentType, body: codec.encode(result), headers: [] } } });
+}
+/** The behaviour behind `Http.Handle` and `Http.HandleStream`, over the registry's endpoints. */
+export function createHttpDispatcher(ctx) {
+    const instances = new Map();
+    function prepare(req) {
+        const endpoint = ctx.registry.endpoint(req.endpointId);
+        const route = endpoint?.routes.get(req.routeId);
+        if (!endpoint || !route)
+            return { ok: false, reply: textResponse(404, `no route ${req.endpointId}/${req.routeId}`) };
+        let instance = instances.get(endpoint.id);
+        if (!instance) {
+            instance = new endpoint.cls();
+            instance._bindClient(ctx.client);
+            instances.set(endpoint.id, instance);
+        }
+        try {
+            const params = {};
+            route.paramNames.forEach((name, i) => {
+                params[name] = parseParam(name, req.pathArgs[i] ?? "", route.paramShapes[name]);
+            });
+            const request = Object.freeze({
+                params: Object.freeze(params),
+                query: new Query(req.query.map((p) => [p.name, p.value])),
+                headers: new Headers(req.headers.map((p) => [p.name, p.value])),
+                principal: principalOf(req),
+                metadata: metadataFromProto(req.metadata),
+            });
+            const body = route.body ? codecFor(route.body).decode(req.body) : undefined;
+            return { ok: true, prepared: { endpoint, route, instance, request, body } };
+        }
+        catch (e) {
+            return { ok: false, reply: textResponse(400, messageOf(e)) };
+        }
+    }
+    function errorReply(e, where) {
+        if (e instanceof HttpProblem)
+            return textResponse(e.status, e.message);
+        if (e instanceof CommandError)
+            return textResponse(httpStatusOf(e.code), e.message);
+        if (e instanceof DecodingError)
+            return textResponse(400, e.message);
+        ctx.log(`ankka: ${where} threw: ${e instanceof Error ? `${e.name}: ${e.message}` : String(e)}`);
+        return failureReply(messageOf(e));
+    }
+    return {
+        async handle(req) {
+            const prep = prepare(req);
+            if (!prep.ok)
+                return prep.reply;
+            const { route, instance, request, body } = prep.prepared;
+            try {
+                const result = await withRequest(request, () => route.run(instance, request, body));
+                return encodeResult(route, result);
+            }
+            catch (e) {
+                return errorReply(e, `${req.endpointId}/${req.routeId}`);
+            }
+        },
+        async *handleStream(req) {
+            const prep = prepare(req);
+            if (!prep.ok) {
+                const r = prep.reply.message.case === "response" ? prep.reply.message.value : undefined;
+                yield create(StreamFrameSchema, { frame: { case: "failed", value: { message: r ? new TextDecoder().decode(r.body) : "no route", code: errorCodeToProto(ErrorCode.NotFound) } } });
+                return;
+            }
+            const { route, instance, request } = prep.prepared;
+            // Produce inside the request's async context, consume here: the handler's `this.request` stays visible.
+            const queue = new AsyncQueue();
+            void withRequest(request, async () => {
+                try {
+                    const frames = (await route.run(instance, request, undefined));
+                    for await (const text of frames)
+                        queue.push(create(StreamFrameSchema, { frame: { case: "text", value: text } }));
+                    queue.push(create(StreamFrameSchema, { frame: { case: "completed", value: {} } }));
+                }
+                catch (e) {
+                    const code = e instanceof CommandError ? e.code : ErrorCode.Internal;
+                    ctx.log(`ankka: ${req.endpointId}/${req.routeId} (stream) threw: ${messageOf(e)}`);
+                    queue.push(create(StreamFrameSchema, { frame: { case: "failed", value: { message: messageOf(e), code: errorCodeToProto(code) } } }));
+                }
+                finally {
+                    queue.close();
+                }
+            });
+            yield* queue;
+        },
+    };
+}
+export function httpRoutes(router, ctx) {
+    const dispatcher = createHttpDispatcher(ctx);
+    router.service(Http, {
+        handle: (req) => dispatcher.handle(req),
+        handleStream: (req) => dispatcher.handleStream(req),
+    });
+}

package/dist/server/keyValue.d.ts

@@ -0,0 +1,5 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type KeyValueIn, type KeyValueOut } from "../_proto/ankka/protocol/v1/key_value_pb.ts";
+import type { ServerContext } from "./server.ts";
+export declare function keyValueRoutes(router: ConnectRouter, ctx: ServerContext): void;
+export declare function handleKeyValue(requests: AsyncIterable<KeyValueIn>, ctx: ServerContext): AsyncIterable<KeyValueOut>;

package/dist/server/keyValue.js

@@ -0,0 +1,122 @@
+// The key value conversation: the event sourced one without a fold. `Init` carries the stored state, if
+// any; each command's effect names the new state to store, or nothing.
+import { create } from "@bufbuild/protobuf";
+import { KeyValue, KeyValueOutSchema } from "../_proto/ankka/protocol/v1/key_value_pb.js";
+import { binaryCodecs, codecFor } from "../codec.js";
+import { commandContext, metadataFromProto } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
+import { errorCodeToProto } from "../kinds.js";
+import { materialiseKeyValue } from "../materialise.js";
+import { retentionToProto } from "./eventSourced.js";
+import { decodePayload, encodePayload } from "./payloads.js";
+function failure(commandId, error) {
+    return create(KeyValueOutSchema, { message: { case: "failure", value: { commandId, error: { message: error.message, code: errorCodeToProto(error.code) } } } });
+}
+function messageOf(e) {
+    return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+export function keyValueRoutes(router, ctx) {
+    router.service(KeyValue, {
+        handle: (requests) => handleKeyValue(requests, ctx),
+    });
+}
+export async function* handleKeyValue(requests, ctx) {
+    let registered;
+    let entity;
+    let entityId = "";
+    let state;
+    for await (const m of requests) {
+        switch (m.message.case) {
+            case "init": {
+                const init = m.message.value;
+                const found = ctx.registry.of("key-value", init.componentId);
+                if (!found) {
+                    yield failure(0n, { message: `no key value entity ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound });
+                    return;
+                }
+                registered = found;
+                entityId = init.entityId;
+                try {
+                    entity = new registered.cls();
+                    entity._bindInstance(entityId);
+                    state = init.state ? decodePayload(registered.stateCodec, init.state) : entity.emptyState();
+                }
+                catch (e) {
+                    ctx.log(`ankka: ${init.componentId}/${entityId}: recovery failed: ${messageOf(e)}`);
+                    yield failure(0n, { message: `recovery failed: ${messageOf(e)}`, code: ErrorCode.Internal });
+                    return;
+                }
+                break;
+            }
+            case "command": {
+                if (!registered || !entity) {
+                    yield failure(m.message.value.id, { message: "a command arrived before Init", code: ErrorCode.Internal });
+                    return;
+                }
+                const result = await runCommand(registered, entity, entityId, state, m.message.value, ctx);
+                yield result.out;
+                if (result.newState !== undefined)
+                    state = result.newState;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+}
+async function runCommand(registered, entity, entityId, state, cmd, ctx) {
+    const handler = registered.handlers.get(cmd.name);
+    if (!handler)
+        return { out: failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound }) };
+    let input;
+    try {
+        input = handler.input ? decodePayload(codecFor(handler.input), cmd.payload) : undefined;
+    }
+    catch (e) {
+        return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest }) };
+    }
+    const metadata = metadataFromProto(cmd.metadata);
+    const context = commandContext(registered.id, entityId, 0n, metadata);
+    let effect;
+    entity._bindCommand(state, context, ctx.client.withMetadata(metadata));
+    try {
+        effect = (await handler.run(entity, input));
+    }
+    catch (e) {
+        ctx.log(`ankka: ${registered.id}/${entityId}/${cmd.name} threw: ${messageOf(e)}`);
+        return { out: failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal }) };
+    }
+    finally {
+        entity._unbindCommand();
+    }
+    if (handler.readOnly && effect?.kind !== "read-only") {
+        return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name} is a query and returned an updating effect`, code: ErrorCode.Internal }) };
+    }
+    try {
+        const m = materialiseKeyValue(effect, state);
+        const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
+        const outcome = m.error
+            ? { outcome: { case: "error", value: { message: m.error.message, code: errorCodeToProto(m.error.code) } } }
+            : m.noReply
+                ? { outcome: { case: "noReply", value: {} } }
+                : { outcome: { case: "reply", value: { payload: encodePayload(replyCodec, m.reply), metadata: { entries: [] } } } };
+        const out = create(KeyValueOutSchema, {
+            message: {
+                case: "reply",
+                value: {
+                    commandId: cmd.id,
+                    newState: m.changed && !m.error ? encodePayload(registered.stateCodec, m.newState) : undefined,
+                    retention: m.error ? undefined : retentionToProto(m.retention),
+                    outcome,
+                },
+            },
+        });
+        if (m.error)
+            return { out };
+        return { out, newState: m.newState };
+    }
+    catch (e) {
+        ctx.log(`ankka: ${registered.id}/${entityId}/${cmd.name}: the effect could not be applied: ${messageOf(e)}`);
+        return { out: failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal }) };
+    }
+}

package/dist/server/payloads.d.ts

@@ -0,0 +1,6 @@
+import { type Payload } from "../_proto/ankka/protocol/v1/payload_pb.ts";
+import type { Codec } from "../codec.ts";
+export declare function encodePayload<T>(codec: Codec<T>, value: T): Payload;
+/** Decodes a payload with `codec`. An absent payload is the empty payload, which is what `unit` and `done` are. */
+export declare function decodePayload<T>(codec: Codec<T>, payload: Payload | undefined): T;
+export declare const EMPTY_PAYLOAD: Payload;

package/dist/server/payloads.js

@@ -0,0 +1,11 @@
+// The bridge between a codec and the protocol's `Payload`: `{ content_type, manifest, data }`.
+import { create } from "@bufbuild/protobuf";
+import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
+export function encodePayload(codec, value) {
+    return create(PayloadSchema, { contentType: codec.contentType, manifest: codec.manifest, data: codec.encode(value) });
+}
+/** Decodes a payload with `codec`. An absent payload is the empty payload, which is what `unit` and `done` are. */
+export function decodePayload(codec, payload) {
+    return codec.decode(payload?.data ?? new Uint8Array());
+}
+export const EMPTY_PAYLOAD = create(PayloadSchema, { contentType: "application/octet-stream", manifest: "unit", data: new Uint8Array() });

package/dist/server/queue.d.ts

@@ -0,0 +1,10 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    #private;
+    push(item: T): void;
+    /** Ends the iteration once the queued items are drained. */
+    close(): void;
+    /** Ends the iteration with an error once the queued items are drained. */
+    fail(error: unknown): void;
+    get closed(): boolean;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/server/queue.js

@@ -0,0 +1,67 @@
+// A small async queue: producers push, one consumer iterates. Used where replies from more than one
+// source leave through one stream (a workflow's commands and its running step), and where a handler's
+// output must be produced inside a request's async context but consumed outside it.
+export class AsyncQueue {
+    #items = [];
+    #waiting;
+    #closed = false;
+    #failure;
+    push(item) {
+        if (this.#closed)
+            return;
+        if (this.#waiting) {
+            const w = this.#waiting;
+            this.#waiting = undefined;
+            w({ value: item, done: false });
+        }
+        else {
+            this.#items.push(item);
+        }
+    }
+    /** Ends the iteration once the queued items are drained. */
+    close() {
+        this.#closed = true;
+        if (this.#waiting && this.#items.length === 0) {
+            const w = this.#waiting;
+            this.#waiting = undefined;
+            w({ value: undefined, done: true });
+        }
+    }
+    /** Ends the iteration with an error once the queued items are drained. */
+    fail(error) {
+        this.#failure = error;
+        this.close();
+    }
+    get closed() {
+        return this.#closed;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.#items.length > 0)
+                    return Promise.resolve({ value: this.#items.shift(), done: false });
+                if (this.#closed) {
+                    if (this.#failure !== undefined) {
+                        const f = this.#failure;
+                        this.#failure = undefined;
+                        return Promise.reject(f);
+                    }
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => {
+                    this.#waiting = resolve;
+                });
+            },
+            return: () => {
+                this.#closed = true;
+                return Promise.resolve({ value: undefined, done: true });
+            },
+            // Connect's bidi client requires the request iterable to implement `throw`.
+            throw: (error) => {
+                this.#closed = true;
+                this.#items.length = 0;
+                return Promise.reject(error);
+            },
+        };
+    }
+}

package/dist/server/server.d.ts

@@ -0,0 +1,34 @@
+import type { Registry } from "../service.ts";
+import type { ComponentClient } from "../client.ts";
+export interface ServerOptions {
+    /** `127.0.0.1` by default; `0.0.0.0` for the testkit; anything else is refused. */
+    readonly host?: string;
+    /** `ANKKA_PROCESS_PORT`, default 9010; `0` for an ephemeral port. */
+    readonly port?: number;
+    /** The largest message accepted from the sidecar; 64 MiB by default. */
+    readonly readMaxBytes?: number;
+    readonly log?: (message: string) => void;
+}
+/** What every servicer needs. */
+export interface ServerContext {
+    readonly registry: Registry;
+    readonly client: ComponentClient;
+    readonly log: (message: string) => void;
+}
+export declare class Server {
+    #private;
+    readonly closed: Promise<void>;
+    constructor(registry: Registry, client: ComponentClient, options?: ServerOptions);
+    /** Binds and starts serving. Resolves with the bound address, which matters when `port` was 0. */
+    start(): Promise<{
+        host: string;
+        port: number;
+    }>;
+    /** The bound address; throws before `start`. */
+    get address(): {
+        host: string;
+        port: number;
+    };
+    /** Aborts every stream, closes every session and the listener, and resolves `closed`. */
+    stop(): Promise<void>;
+}