ankka 0.6.0

package/dist/testkit/integration.js

@@ -0,0 +1,284 @@
+// The integration testkit: this process, a real sidecar, a real Postgres.
+//
+// Starts Postgres with the platform's schema (copied out of the sidecar image, so a test can never pass
+// against a schema the platform does not have), the `ankka-sidecar` image pointed at this process through
+// `host.docker.internal`, and this process's server. `http` talks to the sidecar's HTTP port, where the
+// declared routes are served; `restart` replaces the sidecar container against the same database, which
+// is how a test proves durability rather than caching.
+//
+// Needs Docker, and `testcontainers` with `@testcontainers/postgresql` installed (optional peers of this
+// package). The image is `$ANKKA_SIDECAR_IMAGE` or `ankka-sidecar:latest`.
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const POSTGRES_IMAGE = "postgres:17-alpine";
+const HTTP_PORT = 9000;
+const CALLBACK_PORT = 9011;
+/** What `http` answers with. */
+export class HttpResponse {
+    status;
+    headers;
+    body;
+    constructor(status, headers, body) {
+        this.status = status;
+        this.headers = headers;
+        this.body = body;
+        Object.freeze(this);
+    }
+    text() {
+        return new TextDecoder().decode(this.body);
+    }
+    json() {
+        return JSON.parse(this.text());
+    }
+}
+/** A small HTTP client over `fetch` for the sidecar's routes. */
+export class Http {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+        Object.freeze(this);
+    }
+    async request(method, path, body, headers = {}) {
+        const init = { method, headers: { ...headers } };
+        if (body !== undefined) {
+            if (body instanceof Uint8Array)
+                init.body = body;
+            else if (typeof body === "string") {
+                init.body = body;
+                init.headers["content-type"] ??= "text/plain; charset=utf-8";
+            }
+            else {
+                init.body = JSON.stringify(body);
+                init.headers["content-type"] ??= "application/json";
+            }
+        }
+        const r = await fetch(this.baseUrl + path, init);
+        return new HttpResponse(r.status, r.headers, new Uint8Array(await r.arrayBuffer()));
+    }
+    get(path, headers) {
+        return this.request("GET", path, undefined, headers);
+    }
+    post(path, body, headers) {
+        return this.request("POST", path, body, headers);
+    }
+    put(path, body, headers) {
+        return this.request("PUT", path, body, headers);
+    }
+    delete(path, headers) {
+        return this.request("DELETE", path, undefined, headers);
+    }
+    /** The frames of an SSE response, each `data:` line decoded from its JSON. */
+    async sse(path, headers) {
+        const r = await this.get(path, headers);
+        return r
+            .text()
+            .split("\n")
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => JSON.parse(line.slice(5).trim()));
+    }
+}
+function sidecarImage() {
+    return process.env.ANKKA_SIDECAR_IMAGE ?? "ankka-sidecar:latest";
+}
+/** The DDL as files, from `/opt/docker/ddl` in the sidecar image, without running the image. */
+function copyDdl(image, into) {
+    const id = execFileSync("docker", ["create", image], { encoding: "utf8" }).trim();
+    try {
+        execFileSync("docker", ["cp", `${id}:/opt/docker/ddl/.`, into], { stdio: "pipe" });
+    }
+    finally {
+        try {
+            execFileSync("docker", ["rm", "-f", id], { stdio: "ignore" });
+        }
+        catch {
+            // the container may already be gone
+        }
+    }
+    // Readable by the container's own `postgres` user: the entrypoint lists the directory under `set -e`
+    // before initdb, and a private directory fails that check on Linux (Docker Desktop hides it).
+    chmodSync(into, 0o755);
+    for (const f of readdirSync(into))
+        if (statSync(join(into, f)).isFile())
+            chmodSync(join(into, f), 0o644);
+}
+async function logsOf(container) {
+    if (!container)
+        return "";
+    try {
+        const stream = await container.logs();
+        return await new Promise((resolve) => {
+            let out = "";
+            stream.on("data", (line) => (out += line));
+            stream.on("end", () => resolve(out));
+            stream.on("error", () => resolve(out));
+            setTimeout(() => resolve(out), 2000);
+        });
+    }
+    catch {
+        return "(no logs could be read)";
+    }
+}
+export class AnkkaTestKit {
+    #service;
+    #image;
+    #env;
+    #postgresImage;
+    #readyTimeoutMs;
+    #log;
+    #ddlDir;
+    #network;
+    #postgres;
+    #sidecar;
+    #server;
+    #processPort = 0;
+    #http;
+    /** The component client every handler in `service` uses, pointed at the sidecar's mapped callback port. */
+    client;
+    constructor(service, options) {
+        this.#service = service;
+        this.#image = options.image ?? sidecarImage();
+        this.#env = options.env ?? {};
+        this.#postgresImage = options.postgresImage ?? POSTGRES_IMAGE;
+        this.#readyTimeoutMs = options.readyTimeoutMs ?? 120_000;
+        this.#log = options.log ?? (() => { });
+        this.client = service.client;
+    }
+    /** Starts Postgres, this process's server and the sidecar; a start that fails half-way stops what it started. */
+    static async start(service, options = {}) {
+        const kit = new AnkkaTestKit(service, options);
+        try {
+            await kit.#start();
+        }
+        catch (e) {
+            const logs = await logsOf(kit.#sidecar);
+            await kit.stop();
+            if (logs)
+                throw new Error(`${e instanceof Error ? e.message : String(e)}\n--- sidecar logs ---\n${logs.slice(-4000)}`, { cause: e });
+            throw e;
+        }
+        return kit;
+    }
+    /** The sidecar's HTTP surface: the routes this service declared. */
+    get http() {
+        if (!this.#http)
+            throw new Error("the testkit is not started");
+        return this.#http;
+    }
+    get baseUrl() {
+        return this.http.baseUrl;
+    }
+    /** The JDBC URL of the throwaway database. */
+    get jdbcUrl() {
+        if (!this.#postgres)
+            throw new Error("the testkit is not started");
+        return `jdbc:postgresql://${this.#postgres.getHost()}:${this.#postgres.getPort()}/${this.#postgres.getDatabase()}`;
+    }
+    async #start() {
+        const tc = await import("testcontainers");
+        const pg = await import("@testcontainers/postgresql");
+        this.#ddlDir = mkdtempSync(join(tmpdir(), "ankka-ddl-"));
+        copyDdl(this.#image, this.#ddlDir);
+        this.#network = await new tc.Network().start();
+        this.#postgres = await new pg.PostgreSqlContainer(this.#postgresImage)
+            .withDatabase("ankka")
+            .withUsername("ankka")
+            .withPassword("ankka")
+            .withNetwork(this.#network)
+            .withNetworkAliases("postgres")
+            .withCopyDirectoriesToContainer([{ source: this.#ddlDir, target: "/docker-entrypoint-initdb.d", mode: 0o755 }])
+            .start();
+        // This process's server, on all interfaces: the sidecar is in a container and dials in.
+        this.#server = this.#service.server({ host: "0.0.0.0", port: 0, log: this.#log });
+        this.#processPort = (await this.#server.start()).port;
+        await this.#startSidecar();
+    }
+    async #startSidecar() {
+        const tc = await import("testcontainers");
+        const container = await new tc.GenericContainer(this.#image)
+            .withNetwork(this.#network)
+            .withExtraHosts([{ host: "host.docker.internal", ipAddress: "host-gateway" }])
+            .withEnvironment({
+            ANKKA_PROCESS_ADDRESS: `host.docker.internal:${this.#processPort}`,
+            ANKKA_SIDECAR_BIND: "0.0.0.0",
+            ANKKA_HTTP_PORT: String(HTTP_PORT),
+            ANKKA_DB_HOST: "postgres",
+            ANKKA_DB_PORT: "5432",
+            ANKKA_DB_NAME: "ankka",
+            ANKKA_DB_USER: "ankka",
+            ANKKA_DB_PASSWORD: "ankka",
+            ...this.#env,
+        })
+            .withExposedPorts(HTTP_PORT, CALLBACK_PORT)
+            .withWaitStrategy(tc.Wait.forHttp("/_ankka/health", HTTP_PORT).forStatusCode(200))
+            .withStartupTimeout(this.#readyTimeoutMs)
+            .start();
+        this.#sidecar = container;
+        this.client.reconnect(`${container.getHost()}:${container.getMappedPort(CALLBACK_PORT)}`);
+        this.#http = new Http(`http://${container.getHost()}:${container.getMappedPort(HTTP_PORT)}`);
+    }
+    /** Replaces the sidecar against the same database: every instance is gone from memory, so the next read rebuilds from the journal. */
+    async restart() {
+        if (this.#sidecar) {
+            await this.#sidecar.stop();
+            this.#sidecar = undefined;
+        }
+        await this.#startSidecar();
+    }
+    /** Starts another image against this kit's Postgres — the Scala cart, say, to prove the journal is shared. */
+    async startBeside(image, env = {}, httpPort = HTTP_PORT) {
+        const tc = await import("testcontainers");
+        const container = await new tc.GenericContainer(image)
+            .withNetwork(this.#network)
+            .withEnvironment({
+            ANKKA_HTTP_PORT: String(httpPort),
+            ANKKA_DB_HOST: "postgres",
+            ANKKA_DB_PORT: "5432",
+            ANKKA_DB_NAME: "ankka",
+            ANKKA_DB_USER: "ankka",
+            ANKKA_DB_PASSWORD: "ankka",
+            ...env,
+        })
+            .withExposedPorts(httpPort)
+            .withWaitStrategy(tc.Wait.forHttp("/_ankka/health", httpPort).forStatusCode(200))
+            .withStartupTimeout(this.#readyTimeoutMs)
+            .start();
+        return {
+            http: new Http(`http://${container.getHost()}:${container.getMappedPort(httpPort)}`),
+            logs: () => logsOf(container),
+            stop: async () => {
+                await container.stop();
+            },
+        };
+    }
+    /** The sidecar container's log so far. */
+    sidecarLogs() {
+        return logsOf(this.#sidecar);
+    }
+    async stop() {
+        if (this.#server) {
+            await this.#server.stop().catch(() => undefined);
+            this.#server = undefined;
+        }
+        if (this.#sidecar) {
+            await this.#sidecar.stop().catch(() => undefined);
+            this.#sidecar = undefined;
+        }
+        if (this.#postgres) {
+            await this.#postgres.stop().catch(() => undefined);
+            this.#postgres = undefined;
+        }
+        if (this.#network) {
+            await this.#network.stop().catch(() => undefined);
+            this.#network = undefined;
+        }
+        if (this.#ddlDir) {
+            rmSync(this.#ddlDir, { recursive: true, force: true });
+            this.#ddlDir = undefined;
+        }
+    }
+    async [Symbol.asyncDispose]() {
+        await this.stop();
+    }
+}

package/dist/testkit/kinds.d.ts

@@ -0,0 +1,133 @@
+import { ComponentClient } from "../client.ts";
+import { type ErrorDetail, type Metadata } from "../effects/common.ts";
+import type { StepRef } from "../effects/workflow.ts";
+import type { ConsumerEffect, TimedActionEffect, ViewEffect } from "../effects/stateless.ts";
+import type { KeyValueEntity, KeyValueEntityClass } from "../keyValueEntity.ts";
+import type { Workflow, WorkflowClass } from "../workflow.ts";
+import type { View, ViewClass } from "../view.ts";
+import type { Consumer, ConsumerClass } from "../consumer.ts";
+import type { TimedAction, TimedActionClass } from "../timedAction.ts";
+import type { Agent, AgentClass } from "../agent.ts";
+import type { HandlerRef } from "../handlers.ts";
+import { type MaterialisedKeyValue, type MaterialisedStep, type MaterialisedWorkflowCommand } from "../materialise.ts";
+/** Drives one key value entity instance through its handlers. */
+export declare class KeyValueTestKit<S, C extends KeyValueEntity<S>> {
+    #private;
+    readonly entityId: string;
+    state: S;
+    private constructor();
+    static of<S, C extends KeyValueEntity<S>>(cls: KeyValueEntityClass<S, C>, entityId?: string, client?: ComponentClient): KeyValueTestKit<S, C>;
+    call<I, R>(handler: HandlerRef<C, I, R, any> | string, input?: I, metadata?: Metadata): Promise<MaterialisedKeyValue<S, R>>;
+}
+/** What a workflow is doing, as the kit tracks it between calls. */
+export interface WorkflowProgress {
+    /** The step the last effect asked to run next, not yet run. */
+    readonly pending: StepRef | null;
+    /** Set while the workflow is paused; `resume()` runs `onTimeout` as the engine would after `after`. */
+    readonly paused: {
+        readonly after: number | null;
+        readonly onTimeout: StepRef | null;
+    } | null;
+    readonly ended: boolean;
+    readonly failed: ErrorDetail | null;
+}
+/** Drives one workflow instance: commands, steps, and the transitions between them, stopping at a pause. */
+export declare class WorkflowTestKit<S, C extends Workflow<S>> {
+    #private;
+    readonly entityId: string;
+    state: S;
+    private constructor();
+    static of<S, C extends Workflow<S>>(cls: WorkflowClass<S, C>, entityId?: string, client?: ComponentClient): WorkflowTestKit<S, C>;
+    get progress(): WorkflowProgress;
+    call<I, R>(handler: HandlerRef<C, I, R, any> | string, input?: I, metadata?: Metadata): Promise<MaterialisedWorkflowCommand<S, R>>;
+    /** Runs one step, by name or declaration, with an input (or the pending transition's). */
+    runStep(step: HandlerRef<C, any, any, any> | string, input?: unknown): Promise<MaterialisedStep<S>>;
+    /** Follows transitions until the workflow ends or pauses. Returns the progress reached. */
+    runUntilEnd(limit?: number): Promise<WorkflowProgress>;
+    /** As the engine would when a pause's timeout passes: runs `onTimeout`, then follows transitions. */
+    resume(): Promise<WorkflowProgress>;
+}
+/** Feeds a view events by source key and keeps the rows as the sidecar would. */
+export declare class ViewTestKit<E, Row, C extends View<E, Row>> {
+    #private;
+    readonly rows: Map<string, Row>;
+    private constructor();
+    static of<E, Row, C extends View<E, Row>>(cls: ViewClass<E, Row, C>, client?: ComponentClient): ViewTestKit<E, Row, C>;
+    /** A change from source instance `key`: the event, round-tripped through the source's event codec. */
+    onChange(key: string, event: E, metadata?: Metadata): Promise<ViewEffect<Row>>;
+    /** The source instance `key` was deleted. */
+    onDelete(key: string, metadata?: Metadata): Promise<ViewEffect<Row>>;
+    get(key: string): Row | null;
+}
+/** Feeds a consumer messages and collects what it produced. */
+export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
+    #private;
+    /** Everything `produce` sent, round-tripped through the out codec. */
+    readonly produced: {
+        readonly payload: Out;
+        readonly metadata: Metadata;
+    }[];
+    private constructor();
+    static of<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>, client?: ComponentClient): ConsumerTestKit<M, Out, C>;
+    /** A message from source instance `subject`. */
+    onMessage(message: M, subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
+    onDelete(subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
+}
+/** Invokes a timed action's handlers as the sweeper would. */
+export declare class TimedActionTestKit<C extends TimedAction> {
+    #private;
+    private constructor();
+    static of<C extends TimedAction>(cls: TimedActionClass<C>, client?: ComponentClient): TimedActionTestKit<C>;
+    invoke<I>(action: HandlerRef<C, I, any, any> | string, input?: I, metadata?: Metadata): Promise<TimedActionEffect>;
+}
+/** What a scripted model answers next. */
+export type ModelResponse = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "tool-call";
+    readonly tool: string;
+    readonly argumentsJson: string;
+} | {
+    readonly kind: "refusal";
+    readonly message: string;
+};
+/** What the model saw when it answered: the kit records one per model call. */
+export interface ModelCall {
+    readonly system: string | null;
+    readonly messages: readonly {
+        readonly role: "user" | "assistant" | "tool";
+        readonly text: string;
+    }[];
+    readonly tools: readonly string[];
+}
+/** A model that answers from a script and fails loudly when the script runs out. */
+export declare class ScriptedModel {
+    #private;
+    readonly calls: ModelCall[];
+    expectText(text: string): this;
+    expectToolCall(tool: string, args?: Record<string, unknown> | string): this;
+    expectRefusal(message: string): this;
+    get remaining(): number;
+    /** @internal */
+    _next(call: ModelCall): ModelResponse;
+}
+/**
+ * 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 declare class AgentTestKit<C extends Agent> {
+    #private;
+    readonly sessionId: string;
+    /** The session's memory: what the user said and the agent answered, turn after turn. */
+    readonly history: {
+        role: "user" | "assistant";
+        text: string;
+    }[];
+    private constructor();
+    static of<C extends Agent>(cls: AgentClass<C>, sessionId: string, model: ScriptedModel, client?: ComponentClient): AgentTestKit<C>;
+    /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`. */
+    ask<I>(handler: HandlerRef<C, I, any, any> | string, input?: I): Promise<string>;
+    /** A streaming handler's turn, token by token: the reply split on spaces, as a model streams words. */
+    stream<I>(handler: HandlerRef<C, I, any, any> | string, input?: I): AsyncIterable<string>;
+}