ankka 0.6.0

package/dist/testkit/kinds.js

@@ -0,0 +1,398 @@
+// Unit testkits for the other kinds: key value entities, workflows, views, consumers, timed actions and
+// agents. Same rules as the event sourced kit: no sidecar, effects as values, every value round-tripped
+// through the component's codecs, the server's reduction.
+import { ComponentClient, noClient } from "../client.js";
+import { binaryCodecs, codecFor } from "../codec.js";
+import { commandContext } from "../context.js";
+import { CommandError, ErrorCode } from "../effects/common.js";
+import { materialiseKeyValue, materialiseStep, materialiseWorkflowCommand } from "../materialise.js";
+import { Ankka } from "../service.js";
+import { checkPlan, runTool } from "../server/agent.js";
+function roundTrip(codec, value) {
+    return codec.decode(codec.encode(value));
+}
+function findHandler(handlers, handler, who) {
+    const name = typeof handler === "string" ? handler : handler.name;
+    const found = handlers.get(name);
+    if (!found)
+        throw new Error(`${who} has no handler ${JSON.stringify(name)}; declared: ${[...handlers.keys()].sort().join(", ")}`);
+    return found;
+}
+function registryFor(cls, client) {
+    return Ankka.service({ client, log: () => { } })
+        .register(cls)
+        .validate();
+}
+/** Drives one key value entity instance through its handlers. */
+export class KeyValueTestKit {
+    #registered;
+    #entity;
+    #client;
+    entityId;
+    state;
+    constructor(cls, entityId, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#entity = new cls();
+        this.#entity._bindInstance(entityId);
+        this.#client = client;
+        this.entityId = entityId;
+        this.state = this.#entity.emptyState();
+    }
+    static of(cls, entityId = "test", client = noClient()) {
+        return new KeyValueTestKit(cls, entityId, client);
+    }
+    async call(handler, input, metadata = {}) {
+        const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
+        const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
+        this.#entity._bindCommand(this.state, commandContext(this.#registered.id, this.entityId, 0n, metadata), this.#client.withMetadata(metadata));
+        let effect;
+        try {
+            effect = (await ref.run(this.#entity, wireInput));
+        }
+        finally {
+            this.#entity._unbindCommand();
+        }
+        if (ref.readOnly && effect.kind !== "read-only")
+            throw new Error(`${this.#registered.id}/${ref.name} is a query and returned an updating effect`);
+        const m = materialiseKeyValue(effect, this.state);
+        if (m.error)
+            return m;
+        const newState = roundTrip(this.#registered.stateCodec, m.newState);
+        const replyCodec = (ref.reply ? codecFor(ref.reply) : binaryCodecs.done);
+        const reply = m.noReply ? undefined : roundTrip(replyCodec, m.reply);
+        this.state = newState;
+        return Object.freeze({ ...m, newState, reply });
+    }
+}
+/** Drives one workflow instance: commands, steps, and the transitions between them, stopping at a pause. */
+export class WorkflowTestKit {
+    #registered;
+    #cls;
+    #client;
+    entityId;
+    state;
+    #progress = { pending: null, paused: null, ended: false, failed: null };
+    constructor(cls, entityId, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+        this.entityId = entityId;
+        const instance = new cls();
+        instance._bindInstance(entityId);
+        this.state = instance.emptyState();
+    }
+    static of(cls, entityId = "test", client = noClient()) {
+        return new WorkflowTestKit(cls, entityId, client);
+    }
+    get progress() {
+        return this.#progress;
+    }
+    #instance() {
+        const w = new this.#cls();
+        w._bindInstance(this.entityId);
+        return w;
+    }
+    async call(handler, input, metadata = {}) {
+        const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
+        const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
+        const w = this.#instance();
+        w._bindCommand(this.state, commandContext(this.#registered.id, this.entityId, 0n, metadata), this.#client.withMetadata(metadata));
+        let effect;
+        try {
+            effect = (await ref.run(w, wireInput));
+        }
+        finally {
+            w._unbindCommand();
+        }
+        if (ref.readOnly && effect.kind !== "read-only")
+            throw new Error(`${this.#registered.id}/${ref.name} is a query and returned a changing effect`);
+        const m = materialiseWorkflowCommand(effect, this.state);
+        if (m.error)
+            return m;
+        const newState = roundTrip(this.#registered.stateCodec, m.newState);
+        const replyCodec = (ref.reply ? codecFor(ref.reply) : binaryCodecs.done);
+        const reply = m.noReply ? undefined : roundTrip(replyCodec, m.reply);
+        this.state = newState;
+        if (m.transition) {
+            this.#checkStep(m.transition);
+            this.#progress = { pending: m.transition, paused: null, ended: false, failed: null };
+        }
+        return Object.freeze({ ...m, newState, reply });
+    }
+    #checkStep(ref) {
+        if (!this.#registered.steps.has(ref.step))
+            throw new Error(`${this.#registered.id} transitions to ${JSON.stringify(ref.step)}, which is not a declared step`);
+    }
+    /** Runs one step, by name or declaration, with an input (or the pending transition's). */
+    async runStep(step, input) {
+        const ref = findHandler(this.#registered.steps, step, this.#registered.cls.name);
+        const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
+        const w = this.#instance();
+        w._bindCommand(this.state, commandContext(this.#registered.id, this.entityId, 0n, {}), this.#client);
+        let effect;
+        try {
+            effect = (await ref.run(w, wireInput));
+        }
+        finally {
+            w._unbindCommand();
+        }
+        const m = materialiseStep(effect, this.state);
+        const newState = roundTrip(this.#registered.stateCodec, m.newState);
+        this.state = newState;
+        switch (m.next.kind) {
+            case "transition":
+                this.#checkStep(m.next.ref);
+                this.#progress = { pending: m.next.ref, paused: null, ended: false, failed: null };
+                break;
+            case "pause":
+                if (m.next.onTimeout)
+                    this.#checkStep(m.next.onTimeout);
+                this.#progress = { pending: null, paused: { after: m.next.after?.toMillis() ?? null, onTimeout: m.next.onTimeout }, ended: false, failed: null };
+                break;
+            case "end":
+                this.#progress = { pending: null, paused: null, ended: true, failed: null };
+                break;
+            case "fail":
+                this.#progress = { pending: null, paused: null, ended: true, failed: m.next.error };
+                break;
+        }
+        return Object.freeze({ ...m, newState });
+    }
+    /** Follows transitions until the workflow ends or pauses. Returns the progress reached. */
+    async runUntilEnd(limit = 100) {
+        for (let i = 0; i < limit && this.#progress.pending; i++) {
+            const ref = this.#progress.pending;
+            await this.runStep(ref.step, ref.input);
+        }
+        if (this.#progress.pending)
+            throw new Error(`the workflow did not end or pause within ${limit} steps`);
+        return this.#progress;
+    }
+    /** As the engine would when a pause's timeout passes: runs `onTimeout`, then follows transitions. */
+    async resume() {
+        if (!this.#progress.paused)
+            throw new Error("the workflow is not paused");
+        const ref = this.#progress.paused.onTimeout;
+        if (!ref)
+            throw new Error("the pause has no onTimeout step; a command must move the workflow on");
+        await this.runStep(ref.step, ref.input);
+        return this.runUntilEnd();
+    }
+}
+/** Feeds a view events by source key and keeps the rows as the sidecar would. */
+export class ViewTestKit {
+    #registered;
+    #cls;
+    #client;
+    rows = new Map();
+    constructor(cls, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+    }
+    static of(cls, client = noClient()) {
+        return new ViewTestKit(cls, client);
+    }
+    async #apply(key, fn, metadata) {
+        const view = new this.#cls();
+        const rowCodec = this.#registered.rowCodec;
+        const current = this.rows.get(key);
+        view._bind(current === undefined ? null : roundTrip(rowCodec, current), { "ce-subject": key, ...metadata }, this.#client.withMetadata(metadata));
+        const effect = await fn(view);
+        switch (effect.kind) {
+            case "update-row":
+                this.rows.set(key, roundTrip(rowCodec, effect.row));
+                break;
+            case "delete-row":
+                this.rows.delete(key);
+                break;
+            case "ignore":
+                break;
+        }
+        return effect;
+    }
+    /** A change from source instance `key`: the event, round-tripped through the source's event codec. */
+    onChange(key, event, metadata = {}) {
+        const wire = roundTrip(this.#registered.eventCodec, event);
+        return this.#apply(key, (v) => v.onChange(wire), metadata);
+    }
+    /** The source instance `key` was deleted. */
+    onDelete(key, metadata = {}) {
+        return this.#apply(key, (v) => v.onDelete(), metadata);
+    }
+    get(key) {
+        return this.rows.get(key) ?? null;
+    }
+}
+/** Feeds a consumer messages and collects what it produced. */
+export class ConsumerTestKit {
+    #registered;
+    #cls;
+    #client;
+    /** Everything `produce` sent, round-tripped through the out codec. */
+    produced = [];
+    constructor(cls, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+    }
+    static of(cls, client = noClient()) {
+        return new ConsumerTestKit(cls, client);
+    }
+    async #apply(fn, metadata) {
+        const consumer = new this.#cls();
+        consumer._bind(metadata, this.#client.withMetadata(metadata));
+        const effect = await fn(consumer);
+        if (effect.kind === "produce") {
+            const outCodec = this.#registered.outCodec;
+            if (!outCodec)
+                throw new Error(`${this.#registered.id} produced a message but declares no out shape`);
+            this.produced.push({ payload: roundTrip(outCodec, effect.payload), metadata: effect.metadata });
+        }
+        return effect;
+    }
+    /** A message from source instance `subject`. */
+    onMessage(message, subject = "test", metadata = {}) {
+        const wire = roundTrip(this.#registered.messageCodec, message);
+        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, ...metadata });
+    }
+    onDelete(subject = "test", metadata = {}) {
+        return this.#apply((c) => c.onDelete(), { "ce-subject": subject, ...metadata });
+    }
+}
+/** Invokes a timed action's handlers as the sweeper would. */
+export class TimedActionTestKit {
+    #registered;
+    #cls;
+    #client;
+    constructor(cls, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+    }
+    static of(cls, client = noClient()) {
+        return new TimedActionTestKit(cls, client);
+    }
+    async invoke(action, input, metadata = {}) {
+        const ref = findHandler(this.#registered.actions, action, this.#registered.cls.name);
+        const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
+        const instance = new this.#cls();
+        instance._bind({ "ankka.timer": "test", "ankka.attempts": "1", ...metadata }, this.#client.withMetadata(metadata));
+        return (await ref.run(instance, wireInput));
+    }
+}
+/** A model that answers from a script and fails loudly when the script runs out. */
+export class ScriptedModel {
+    #script = [];
+    calls = [];
+    expectText(text) {
+        this.#script.push({ kind: "text", text });
+        return this;
+    }
+    expectToolCall(tool, args = {}) {
+        this.#script.push({ kind: "tool-call", tool, argumentsJson: typeof args === "string" ? args : JSON.stringify(args) });
+        return this;
+    }
+    expectRefusal(message) {
+        this.#script.push({ kind: "refusal", message });
+        return this;
+    }
+    get remaining() {
+        return this.#script.length;
+    }
+    /** @internal */
+    _next(call) {
+        this.calls.push(call);
+        const next = this.#script.shift();
+        if (!next)
+            throw new Error(`the scripted model ran out of responses after ${this.calls.length} call(s); script more with expectText/expectToolCall/expectRefusal`);
+        return next;
+    }
+}
+/**
+ * Runs an agent's turn the way the sidecar does, in process: the plan, input guardrails, the model
+ * (scripted), tool calls back into the agent, output guardrails, and the session's history.
+ */
+export class AgentTestKit {
+    #registered;
+    #cls;
+    #client;
+    #model;
+    sessionId;
+    /** The session's memory: what the user said and the agent answered, turn after turn. */
+    history = [];
+    constructor(cls, sessionId, model, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+        this.#model = model;
+        this.sessionId = sessionId;
+    }
+    static of(cls, sessionId, model, client = noClient()) {
+        return new AgentTestKit(cls, sessionId, model, client);
+    }
+    #agent() {
+        const a = new this.#cls();
+        a._bind(this.sessionId, {}, this.#client);
+        return a;
+    }
+    /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`. */
+    async ask(handler, input) {
+        const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
+        const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
+        const agent = this.#agent();
+        const plan = (await ref.run(agent, wireInput));
+        if (plan?.kind !== "agent")
+            throw new Error(`${this.#registered.id}/${ref.name} returned something that is not an agent effect`);
+        const problem = checkPlan(this.#registered, plan);
+        if (problem)
+            throw new Error(problem);
+        if (plan.failure)
+            throw new CommandError(plan.failure);
+        const guard = async (stage, text) => {
+            for (const name of plan.guardrailNames) {
+                const reason = await this.#registered.guardrails.get(name).check(stage, text);
+                if (reason)
+                    throw new CommandError({ message: `${name}: ${reason}`, code: ErrorCode.Forbidden });
+            }
+        };
+        const user = [...plan.context, plan.user ?? ""].filter((t) => t !== "").join("\n\n");
+        await guard("input", user);
+        const messages = plan.sessionMemory ? this.history.map((h) => ({ ...h })) : [];
+        messages.push({ role: "user", text: user });
+        for (let step = 0; step <= this.#registered.maxToolCallSteps; step++) {
+            const answer = this.#model._next({ system: plan.system, messages: [...messages], tools: [...plan.toolNames] });
+            switch (answer.kind) {
+                case "refusal":
+                    throw new CommandError({ message: answer.message, code: ErrorCode.BadRequest });
+                case "tool-call": {
+                    if (!plan.toolNames.includes(answer.tool))
+                        throw new Error(`the model called ${JSON.stringify(answer.tool)}, which the plan did not offer`);
+                    let result;
+                    try {
+                        result = await runTool(this.#registered, this.#agent(), answer.tool, answer.argumentsJson);
+                    }
+                    catch (e) {
+                        result = `error: ${e instanceof Error ? e.message : String(e)}`;
+                    }
+                    messages.push({ role: "assistant", text: `[tool call ${answer.tool} ${answer.argumentsJson}]` }, { role: "tool", text: result });
+                    break;
+                }
+                case "text": {
+                    await guard("output", answer.text);
+                    if (plan.sessionMemory)
+                        this.history.push({ role: "user", text: plan.user ?? "" }, { role: "assistant", text: answer.text });
+                    return answer.text;
+                }
+            }
+        }
+        throw new CommandError({ message: `the agent made more than ${this.#registered.maxToolCallSteps} tool calls`, code: ErrorCode.Internal });
+    }
+    /** A streaming handler's turn, token by token: the reply split on spaces, as a model streams words. */
+    async *stream(handler, input) {
+        const text = await this.ask(handler, input);
+        const parts = text.split(/(?<= )/);
+        for (const part of parts)
+            yield part;
+    }
+}

package/dist/testkit/unit.d.ts

@@ -0,0 +1,54 @@
+import { ComponentClient } from "../client.ts";
+import { type Principal } from "../context.ts";
+import type { ErrorDetail, Metadata, Retention } from "../effects/common.ts";
+import type { Endpoint, EndpointClass } from "../endpoint.ts";
+import { EventSourcedEntity, type EventSourcedEntityClass } from "../eventSourcedEntity.ts";
+import type { HandlerRef } from "../handlers.ts";
+import { type Materialised } from "../materialise.ts";
+export type { Materialised };
+/** Drives one event sourced entity instance through its handlers, folding events as it goes. */
+export declare class EventSourcedTestKit<S, E, C extends EventSourcedEntity<S, E>> {
+    #private;
+    readonly entityId: string;
+    /** The state now, after every call so far. */
+    state: S;
+    /** The sequence number of the last event, `0n` before any. */
+    sequence: bigint;
+    /** Every event persisted so far, in order. */
+    readonly allEvents: E[];
+    private constructor();
+    /** A kit for `cls` as instance `entityId`. Calls to other components reach `client`, which by default refuses them. */
+    static of<S, E, C extends EventSourcedEntity<S, E>>(cls: EventSourcedEntityClass<S, E, C>, entityId?: string, client?: ComponentClient): EventSourcedTestKit<S, E, C>;
+    /** Sends a command or query and returns what its effect amounts to. */
+    call<I, R>(handler: HandlerRef<C, I, R, any> | string, input?: I, metadata?: Metadata): Promise<Materialised<S, E, R>>;
+}
+/** A reply from the endpoint testkit. */
+export declare class Response {
+    readonly status: number;
+    readonly contentType: string;
+    readonly body: Uint8Array;
+    constructor(status: number, contentType: string, body: Uint8Array);
+    text(): string;
+    json(): unknown;
+}
+export interface RequestOptions {
+    readonly query?: Readonly<Record<string, string | readonly string[]>>;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly principal?: Principal;
+    readonly metadata?: Metadata;
+}
+/** Calls an endpoint's routes by path, matching them as the sidecar's router does: literal segments outrank parameters. */
+export declare class EndpointTestKit<C extends Endpoint> {
+    #private;
+    private constructor();
+    static of<C extends Endpoint>(cls: EndpointClass<C>, client?: ComponentClient): EndpointTestKit<C>;
+    request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    /** The frames of an SSE route, each string one frame. */
+    sse(path: string, options?: RequestOptions): Promise<string[]>;
+    get(path: string, options?: RequestOptions): Promise<Response>;
+    post(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    put(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    patch(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    delete(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+}
+export type { ErrorDetail, Retention };

package/dist/testkit/unit.js

@@ -0,0 +1,224 @@
+// The unit testkits: one component, no sidecar, no database, no network. Effects come back as values.
+// Every input, event, state and reply is encoded and decoded through the component's own codecs on the
+// way in and out, so a shape the codec cannot express fails here rather than on first deployment. The
+// reduction is the server's (`materialise.ts`), so a test cannot pass on something the sidecar would
+// not do.
+import { create } from "@bufbuild/protobuf";
+import { HttpRequestSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
+import { ComponentClient, noClient } from "../client.js";
+import { binaryCodecs, codecFor } from "../codec.js";
+import { commandContext } from "../context.js";
+import { EventSourcedEntity } from "../eventSourcedEntity.js";
+import { materialiseEventSourced } from "../materialise.js";
+import { Ankka } from "../service.js";
+import { createHttpDispatcher } from "../server/http.js";
+function roundTrip(codec, value) {
+    return codec.decode(codec.encode(value));
+}
+function findHandler(handlers, handler, who) {
+    const name = typeof handler === "string" ? handler : handler.name;
+    const found = handlers.get(name);
+    if (!found)
+        throw new Error(`${who} has no handler ${JSON.stringify(name)}; declared: ${[...handlers.keys()].sort().join(", ")}`);
+    return found;
+}
+/** Drives one event sourced entity instance through its handlers, folding events as it goes. */
+export class EventSourcedTestKit {
+    #registered;
+    #entity;
+    #client;
+    entityId;
+    /** The state now, after every call so far. */
+    state;
+    /** The sequence number of the last event, `0n` before any. */
+    sequence = 0n;
+    /** Every event persisted so far, in order. */
+    allEvents = [];
+    constructor(cls, entityId, client) {
+        const registry = Ankka.service({ client, log: () => { } })
+            .register(cls)
+            .validate();
+        this.#registered = registry.component(cls.componentId);
+        this.#entity = new cls();
+        this.#entity._bindInstance(entityId);
+        this.#client = client;
+        this.entityId = entityId;
+        this.state = this.#entity.emptyState();
+    }
+    /** A kit for `cls` as instance `entityId`. Calls to other components reach `client`, which by default refuses them. */
+    static of(cls, entityId = "test", client = noClient()) {
+        return new EventSourcedTestKit(cls, entityId, client);
+    }
+    /** Sends a command or query and returns what its effect amounts to. */
+    async call(handler, input, metadata = {}) {
+        const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
+        const inputCodec = ref.input ? codecFor(ref.input) : undefined;
+        const wireInput = inputCodec ? roundTrip(inputCodec, input) : undefined;
+        const context = commandContext(this.#registered.id, this.entityId, this.sequence, metadata);
+        this.#entity._bindCommand(this.state, context, this.#client.withMetadata(metadata));
+        let effect;
+        try {
+            effect = (await ref.run(this.#entity, wireInput));
+        }
+        finally {
+            this.#entity._unbindCommand();
+        }
+        if (ref.readOnly && effect.kind !== "read-only")
+            throw new Error(`${this.#registered.id}/${ref.name} is a query and returned a persisting effect`);
+        const m = materialiseEventSourced(effect, this.state, (s, e) => this.#entity.applyEvent(s, e));
+        const eventCodec = this.#registered.eventCodec;
+        const stateCodec = this.#registered.stateCodec;
+        const events = m.events.map((e) => roundTrip(eventCodec, e));
+        if (m.error)
+            return Object.freeze({ events: [], newState: this.state, retention: m.retention, reply: undefined, error: m.error, noReply: false });
+        const newState = roundTrip(stateCodec, m.newState);
+        const replyCodec = (ref.reply ? codecFor(ref.reply) : binaryCodecs.done);
+        const reply = m.noReply ? undefined : roundTrip(replyCodec, m.reply);
+        this.state = newState;
+        this.sequence += BigInt(events.length);
+        this.allEvents.push(...events);
+        return Object.freeze({ events, newState, retention: m.retention, reply, error: undefined, noReply: m.noReply });
+    }
+}
+/** A reply from the endpoint testkit. */
+export class Response {
+    status;
+    contentType;
+    body;
+    constructor(status, contentType, body) {
+        this.status = status;
+        this.contentType = contentType;
+        this.body = body;
+        Object.freeze(this);
+    }
+    text() {
+        return new TextDecoder().decode(this.body);
+    }
+    json() {
+        return JSON.parse(this.text());
+    }
+}
+const PLACEHOLDER = /\{[A-Za-z_][A-Za-z0-9_]*\}/g;
+/** Calls an endpoint's routes by path, matching them as the sidecar's router does: literal segments outrank parameters. */
+export class EndpointTestKit {
+    #cls;
+    #dispatcher;
+    constructor(cls, client) {
+        this.#cls = cls;
+        const registry = Ankka.service({ client, log: () => { } })
+            .register(cls)
+            .validate();
+        this.#dispatcher = createHttpDispatcher({ registry, client, log: () => { } });
+    }
+    static of(cls, client = noClient()) {
+        return new EndpointTestKit(cls, client);
+    }
+    #match(method, path) {
+        const prefix = this.#cls.prefix;
+        const withoutQuery = path.split("?")[0];
+        const rest = withoutQuery.startsWith(prefix) ? withoutQuery.slice(prefix.length) || "/" : withoutQuery;
+        const candidates = [];
+        for (const [id, route] of Object.entries(this.#cls.routes)) {
+            if (route.method !== method.toUpperCase())
+                continue;
+            const pattern = new RegExp("^" + route.template.replace(/[.*+?^$()|[\]\\]/g, "\\$&").replace(PLACEHOLDER, "([^/]+)") + "$");
+            const m = pattern.exec(rest);
+            if (!m)
+                continue;
+            const literals = route.template.split("/").filter((seg) => seg && !seg.startsWith("{")).length;
+            candidates.push({ literals, id, route, args: m.slice(1).map(decodeURIComponent) });
+        }
+        candidates.sort((a, b) => b.literals - a.literals);
+        return candidates[0];
+    }
+    #request(method, path, body, options) {
+        const matched = this.#match(method, path);
+        if (!matched)
+            return undefined;
+        let bytes = new Uint8Array();
+        if (body !== undefined && body !== null) {
+            if (body instanceof Uint8Array)
+                bytes = new Uint8Array(body);
+            else if (typeof body === "string")
+                bytes = new TextEncoder().encode(body);
+            else if (matched.route.body)
+                bytes = codecFor(matched.route.body).encode(body);
+            else
+                bytes = new TextEncoder().encode(JSON.stringify(body));
+        }
+        const query = [];
+        const fromPath = path.includes("?") ? new URLSearchParams(path.slice(path.indexOf("?") + 1)) : undefined;
+        for (const [name, value] of fromPath ?? [])
+            query.push({ name, value });
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            for (const v of typeof value === "string" ? [value] : value)
+                query.push({ name, value: v });
+        }
+        const headers = Object.entries(options.headers ?? {}).map(([name, value]) => ({ name, value }));
+        const principal = options.principal
+            ? { subject: options.principal.subject, name: options.principal.name ?? undefined, email: options.principal.email ?? undefined, emailVerified: options.principal.emailVerified, roles: [...options.principal.roles] }
+            : undefined;
+        const req = create(HttpRequestSchema, {
+            endpointId: this.#cls.name,
+            routeId: matched.id,
+            pathArgs: matched.args,
+            query,
+            headers,
+            contentType: matched.route.body ? codecFor(matched.route.body).contentType : "",
+            body: bytes,
+            principal,
+            metadata: { entries: Object.entries(options.metadata ?? {}).map(([key, value]) => ({ key, value })) },
+        });
+        return { req, route: matched.route };
+    }
+    async request(method, path, body, options = {}) {
+        const prepared = this.#request(method, path, body, options);
+        if (!prepared)
+            return new Response(404, "text/plain", new TextEncoder().encode(`no route ${method.toUpperCase()} ${path}`));
+        if (prepared.route.streaming) {
+            const frames = [];
+            for await (const f of this.#dispatcher.handleStream(prepared.req)) {
+                if (f.frame.case === "text")
+                    frames.push(f.frame.value);
+                if (f.frame.case === "failed")
+                    return new Response(500, "text/plain", new TextEncoder().encode(f.frame.value.message));
+            }
+            return new Response(200, "text/event-stream", new TextEncoder().encode(frames.join("\n")));
+        }
+        const reply = await this.#dispatcher.handle(prepared.req);
+        if (reply.message.case === "response") {
+            const r = reply.message.value;
+            return new Response(r.status, r.contentType, r.body);
+        }
+        return new Response(500, "text/plain", new TextEncoder().encode(reply.message.case === "failure" ? reply.message.value.error?.message ?? "failure" : "no reply"));
+    }
+    /** The frames of an SSE route, each string one frame. */
+    async sse(path, options = {}) {
+        const prepared = this.#request("GET", path, undefined, options);
+        if (!prepared)
+            throw new Error(`no route GET ${path}`);
+        const frames = [];
+        for await (const f of this.#dispatcher.handleStream(prepared.req)) {
+            if (f.frame.case === "text")
+                frames.push(f.frame.value);
+            if (f.frame.case === "failed")
+                throw new Error(f.frame.value.message);
+        }
+        return frames;
+    }
+    get(path, options) {
+        return this.request("GET", path, undefined, options);
+    }
+    post(path, body, options) {
+        return this.request("POST", path, body, options);
+    }
+    put(path, body, options) {
+        return this.request("PUT", path, body, options);
+    }
+    patch(path, body, options) {
+        return this.request("PATCH", path, body, options);
+    }
+    delete(path, body, options) {
+        return this.request("DELETE", path, body, options);
+    }
+}