ankka 0.10.0 → 0.12.0

package/dist/testkit/unit.js

@@ -4,10 +4,11 @@
 // 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 { HttpRequestSchema, SocketInSchema } 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 { commandContext, eventContext } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
 import { EventSourcedEntity } from "../eventSourcedEntity.js";
 import { materialiseEventSourced } from "../materialise.js";
 import { Ankka } from "../service.js";
@@ -22,19 +23,24 @@ function findHandler(handlers, handler, who) {
         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;
+    #mode;
+    #here;
     entityId;
+    /** The handover or change to the replication set the last call asked for, if any. */
+    lastReplication = undefined;
     /** 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) {
+    constructor(cls, entityId, client, mode = { kind: "unreplicated" }) {
+        this.#mode = mode;
+        this.#here = mode.kind === "unreplicated" ? null : (mode.installation ?? "test");
         const registry = Ankka.service({ client, log: () => { } })
             .register(cls)
             .validate();
@@ -46,15 +52,36 @@ export class EventSourcedTestKit {
         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);
+    static of(cls, entityId = "test", client = noClient(), 
+    /**
+     * How a replicated entity's copy stands (1.19): `{ kind: "home" }`, where every command runs, or
+     * `{ kind: "follower", home }`, where a command that may persist is refused `NOT_HOME` and a query is
+     * answered from what `replay` gave it. Not replicated by default.
+     */
+    mode = { kind: "unreplicated" }) {
+        return new EventSourcedTestKit(cls, entityId, client, mode);
+    }
+    /**
+     * Applies `events` as history the copy already holds, written at `writtenAt` (this installation by
+     * default): for a follower, what it has mirrored from its home.
+     */
+    replay(events, writtenAt = this.#here) {
+        for (const event of events) {
+            this.sequence += 1n;
+            this.state = this.#entity.applyEvent(this.state, event, eventContext(writtenAt, writtenAt === this.#here, this.sequence));
+        }
     }
     /** 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);
+        if (this.#mode.kind === "follower" && !ref.readOnly) {
+            // The runtime forwards such a command to the home; here there is no home to forward to.
+            const error = { message: `the home of '${this.entityId}' is '${this.#mode.home}'; a follower handles no command that may persist`, code: ErrorCode.NotHome };
+            return Object.freeze({ events: [], newState: this.state, retention: null, reply: undefined, error, noReply: false });
+        }
         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);
+        const context = commandContext(this.#registered.id, this.entityId, this.sequence, metadata, undefined, this.#here, this.#mode.kind !== "follower");
         this.#entity._bindCommand(this.state, context, this.#client.withMetadata(metadata));
         let effect;
         try {
@@ -65,7 +92,20 @@ export class EventSourcedTestKit {
         }
         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));
+        let applied = this.sequence;
+        const m = materialiseEventSourced(effect, this.state, (s, e) => {
+            applied += 1n;
+            return this.#entity.applyEvent(s, e, eventContext(this.#here, true, applied));
+        });
+        const replication = effect.kind === "persist" ? effect.replication : undefined;
+        if (!m.error && replication && this.#mode.kind === "unreplicated") {
+            const error = {
+                message: `${this.#registered.id} is not replicated in this test kit; drive it with { kind: "home" } to see the handover or the change to the replication set it asks for`,
+                code: ErrorCode.BadRequest,
+            };
+            return Object.freeze({ events: [], newState: this.state, retention: null, reply: undefined, error, noReply: false });
+        }
+        this.lastReplication = m.error ? undefined : replication;
         const eventCodec = this.#registered.eventCodec;
         const stateCodec = this.#registered.stateCodec;
         const events = m.events.map((e) => roundTrip(eventCodec, e));
@@ -119,7 +159,8 @@ export class EndpointTestKit {
         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())
+            // A socket route is opened through `socket`, never answered as a GET.
+            if ((route.socket ? "SOCKET" : route.method) !== method.toUpperCase())
                 continue;
             const pattern = new RegExp("^" + route.template.replace(/[.*+?^$()|[\]\\]/g, "\\$&").replace(PLACEHOLDER, "([^/]+)") + "$");
             const m = pattern.exec(rest);
@@ -156,7 +197,15 @@ export class EndpointTestKit {
         }
         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] }
+            ? {
+                subject: options.principal.subject,
+                name: options.principal.name ?? undefined,
+                email: options.principal.email ?? undefined,
+                emailVerified: options.principal.emailVerified,
+                roles: [...options.principal.roles],
+                claims: { ...(options.principal.claims ?? {}) },
+                issuer: options.principal.issuer ?? undefined,
+            }
             : undefined;
         const req = create(HttpRequestSchema, {
             endpointId: this.#cls.name,
@@ -192,6 +241,34 @@ export class EndpointTestKit {
         }
         return new Response(500, "text/plain", new TextEncoder().encode(reply.message.case === "failure" ? reply.message.value.error?.message ?? "failure" : "no reply"));
     }
+    /**
+     * Opens a socket route with no runtime: the handler is given `frames` one at a time and then told the
+     * socket is closed, as when the client closes it after sending them. Answers what the handler sent, in
+     * order, and how it ended: `finished` when it returned, `failed` (with `error`) when it threw.
+     */
+    async socket(path, frames = [], options = {}) {
+        const prepared = this.#request("SOCKET", path, undefined, options);
+        if (!prepared)
+            throw new Error(`no socket route at ${path}`);
+        const requests = [
+            create(SocketInSchema, { message: { case: "open", value: prepared.req } }),
+            ...frames.map((text) => create(SocketInSchema, { message: { case: "frame", value: { kind: { case: "text", value: text } } } })),
+            create(SocketInSchema, { message: { case: "closed", value: { reason: "client" } } }),
+        ];
+        async function* script() {
+            yield* requests;
+        }
+        const sent = [];
+        for await (const out of this.#dispatcher.handleSocket(script())) {
+            if (out.message.case === "frame" && out.message.value.kind.case === "text")
+                sent.push(out.message.value.kind.value);
+            if (out.message.case === "completed")
+                return { sent, ended: "finished" };
+            if (out.message.case === "failed")
+                return { sent, ended: "failed", error: out.message.value.message };
+        }
+        return { sent, ended: "finished" };
+    }
     /** The frames of an SSE route, each string one frame. */
     async sse(path, options = {}) {
         const prepared = this.#request("GET", path, undefined, options);

package/dist/timedAction.d.ts

@@ -1,13 +1,28 @@
 import type { Metadata } from "./effects/common.ts";
-import type { ComponentClient } from "./client.ts";
+import { type ComponentClient, type Secrets } from "./client.ts";
 import type { HandlerTable } from "./handlers.ts";
 import { TimedActionEffects } from "./effects/stateless.ts";
+import { type Services } from "./services.ts";
 export declare abstract class TimedAction {
     #private;
     readonly effects: TimedActionEffects;
-    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired. */
+    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired, `ankka.due` the due time in epoch milliseconds. */
     get metadata(): Metadata;
+    /**
+     * The due time this run is for, from `ankka.due`: the same on every retry of one due time, and for a
+     * recurring timer a whole number of periods after the one before. `undefined` on a runtime older
+     * than protocol 1.12, which does not send it.
+     */
+    get dueTime(): Date | undefined;
     get client(): ComponentClient;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
     /** @internal */
     get _kind(): "timed-action";
     /** @internal */

package/dist/timedAction.js

@@ -2,20 +2,52 @@
 // sweeper delivers it here, retrying a failure with backoff.
 //
 //   static readonly actions = { remind: action("remind", s.string, (t: Reminder, id) => t.remind(id)) }
+import { secretsFor } from "./client.js";
 import { TimedActionEffects } from "./effects/stateless.js";
+import { servicesFor } from "./services.js";
 export class TimedAction {
     effects = new TimedActionEffects();
     #metadata = {};
     #client;
-    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired. */
+    /** `ankka.timer` is the timer's id, `ankka.attempts` how many times it has fired, `ankka.due` the due time in epoch milliseconds. */
     get metadata() {
         return this.#metadata;
     }
+    /**
+     * The due time this run is for, from `ankka.due`: the same on every retry of one due time, and for a
+     * recurring timer a whole number of periods after the one before. `undefined` on a runtime older
+     * than protocol 1.12, which does not send it.
+     */
+    get dueTime() {
+        const raw = this.#metadata["ankka.due"];
+        if (raw === undefined || !/^-?\d+$/.test(raw.trim()))
+            return undefined;
+        const date = new Date(Number(raw.trim()));
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
     get client() {
         if (!this.#client)
             throw new Error("client is only available inside an action");
         return this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     get _kind() {
         return "timed-action";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.10.0";
+export declare const VERSION = "0.12.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Written by scripts/proto.ts from package.json; do not edit. 0.0.0 in the tree, the tag's version in a release.
-export const VERSION = "0.10.0";
+export const VERSION = "0.12.0";

package/dist/view.d.ts

@@ -1,9 +1,34 @@
+import type { StartFrom } from "./startFrom.ts";
+import type { Contract } from "./contract.ts";
 import type { Shape } from "./codec.ts";
 import type { Metadata } from "./effects/common.ts";
 import type { ComponentClient } from "./client.ts";
 import type { ComponentRef } from "./client.ts";
 import { ViewEffects, type ViewEffect } from "./effects/stateless.ts";
+import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * A question a view can be asked by name: one SQL statement over the view's own table, whose values
+ * are the `:name`s it holds. The platform checks the statement when the service starts — one that is
+ * not a single read of the view's own table stops the service, naming the view and the query — and
+ * binds each value as a parameter, never as part of the text. The answer is rows of the view's row
+ * shape, read from the statement's `payload` column.
+ */
+export interface DeclaredQuery {
+    readonly name: string;
+    readonly statement: string;
+    /** Whether it may be watched: its statement selects `row_key` beside `payload`, with no limit and no aggregate. */
+    readonly watched?: boolean;
+}
+/**
+ * Declares a query for a view's `static declared`. The SDK sends the statement as written.
+ * `{ watched: true }` declares that it may also be watched, which the platform checks at start.
+ */
+export declare function declaredQuery(name: string, statement: string, options?: {
+    readonly watched?: boolean;
+}): DeclaredQuery;
+/** The table a view's rows are kept in, for a declared query's statement to name. */
+export declare function tableOf(componentId: string): string;
 export declare abstract class View<E, Row> {
     #private;
     readonly effects: ViewEffects<Row>;
@@ -13,6 +38,8 @@ export declare abstract class View<E, Row> {
     get metadata(): Metadata;
     /** The id of the source instance the change came from. */
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     get client(): ComponentClient;
     /** @internal */
     get _kind(): "view";
@@ -21,7 +48,7 @@ export declare abstract class View<E, Row> {
     /** The source was deleted. The row goes with it unless this says otherwise — an order history keeps a checked-out cart's row. */
     onDelete(): MaybePromise<ViewEffect<Row>>;
     /** @internal */
-    _bind(row: Row | null, metadata: Metadata, client: ComponentClient): void;
+    _bind(row: Row | null, metadata: Metadata, client: ComponentClient, standing?: Standing): void;
 }
 export interface ViewClass<E = unknown, Row = unknown, C extends View<E, Row> = View<E, Row>> {
     new (): C;
@@ -29,9 +56,29 @@ export interface ViewClass<E = unknown, Row = unknown, C extends View<E, Row> =
     /** The component whose changes feed the view, or `topic`. */
     readonly source?: ComponentRef;
     readonly topic?: string;
+    /** Where a topic source starts the first time its group reads the topic. */
+    readonly startFrom?: StartFrom;
+    /**
+     * Raised to have the view emptied and read again: a topic from its start position, under a group of
+     * its own, as far back as the broker retains; an entity from its first event or state. Absent is 1.
+     */
+    readonly version?: number;
+    /** The contract the topic read is expected to carry, checked at start against the project's declaration. */
+    readonly contract?: Contract;
+    /** The declared broker the topic read is on; absent is the installation's. */
+    readonly broker?: string;
+    /**
+     * Another project's topic (1.15): the id of the project whose topic `topic` is. The broker serves it
+     * while that project grants this service consume on it.
+     */
+    readonly project?: string;
+    /** Whether the partitions an instance holds are handled at once, each in order. */
+    readonly parallel?: boolean;
     readonly events: Shape<E>;
     readonly row: Shape<Row>;
     /** The query names the view answers; `get` and `all` by default. */
     readonly queries?: readonly string[];
+    /** The queries the view can be asked by name, each a statement over its own table (protocol 1.13). */
+    readonly declared?: readonly DeclaredQuery[];
 }
 export {};

package/dist/view.js

@@ -9,10 +9,22 @@
 //     onChange(event) { ... return this.effects.updateRow(...) }
 //   }
 import { ViewEffects } from "./effects/stateless.js";
+/**
+ * Declares a query for a view's `static declared`. The SDK sends the statement as written.
+ * `{ watched: true }` declares that it may also be watched, which the platform checks at start.
+ */
+export function declaredQuery(name, statement, options = {}) {
+    return Object.freeze({ name, statement, watched: options.watched ?? false });
+}
+/** The table a view's rows are kept in, for a declared query's statement to name. */
+export function tableOf(componentId) {
+    return "ankka_view_" + componentId.replace(/[^A-Za-z0-9]/g, "_");
+}
 export class View {
     effects = new ViewEffects();
     #row = null;
     #metadata = {};
+    #standing = undefined;
     #client;
     #bound = false;
     /** The current row, or `null` when there is none yet. */
@@ -29,6 +41,10 @@ export class View {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
     get client() {
         if (!this.#client)
             throw new Error("client is only available inside onChange or onDelete");
@@ -43,9 +59,10 @@ export class View {
         return this.effects.deleteRow();
     }
     /** @internal */
-    _bind(row, metadata, client) {
+    _bind(row, metadata, client, standing) {
         this.#row = row;
         this.#metadata = metadata;
+        this.#standing = standing;
         this.#client = client;
         this.#bound = true;
     }

package/dist/workflow.d.ts

@@ -1,8 +1,9 @@
 import type { Shape } from "./codec.ts";
 import type { CommandContext } from "./context.ts";
 import type { HandlerTable } from "./handlers.ts";
-import type { ComponentClient } from "./client.ts";
+import { type ComponentClient, type Secrets } from "./client.ts";
 import { StepEffects, WorkflowEffects, type WorkflowSettings } from "./effects/workflow.ts";
+import { type Services } from "./services.ts";
 export declare abstract class Workflow<S> {
     #private;
     /** Inside a command handler. */
@@ -13,6 +14,22 @@ export declare abstract class Workflow<S> {
     get entityId(): string;
     get context(): CommandContext;
     get client(): ComponentClient;
+    /**
+     * The service's secret store, in a step. A command handler is refused: it would put a database read
+     * on the workflow's single-writer path, as an entity's would.
+     */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's. */
+    set secrets(store: Secrets);
+    /**
+     * Other services, called as this one, in a step. A command handler is refused, as for the secret
+     * store: it would block the workflow's other commands behind another service.
+     */
+    get services(): Services;
+    /** A unit test's in place of the runtime's. */
+    set services(services: Services);
+    /** @internal The server marks a step's binding, which is how a step is told from a command. */
+    _enterStep(): void;
     /** @internal */
     get _kind(): "workflow";
     abstract emptyState(): S;

package/dist/workflow.js

@@ -5,7 +5,10 @@
 //
 //   static readonly steps = { reserve: step("reserve", (w: CheckoutWorkflow) => w.reserve()), charge: step("charge", s.int, (w, q) => w.charge(q)) }
 //   static readonly settings = workflowSettings({ steps: { charge: { recovery: { maxRetries: 1, failoverTo: "compensate" } } } })
+import { secretsFor } from "./client.js";
+import { CommandError } from "./effects/common.js";
 import { StepEffects, WorkflowEffects } from "./effects/workflow.js";
+import { servicesFor } from "./services.js";
 export class Workflow {
     /** Inside a command handler. */
     effects = new WorkflowEffects();
@@ -36,6 +39,41 @@ export class Workflow {
             throw new Error("client is only available inside a handler or a step");
         return this.#client;
     }
+    #inStep = false;
+    #secrets;
+    /**
+     * The service's secret store, in a step. A command handler is refused: it would put a database read
+     * on the workflow's single-writer path, as an entity's would.
+     */
+    get secrets() {
+        if (!this.#inStep) {
+            throw new CommandError({ message: "a workflow reads and keeps a service secret in a step, not in a command handler", code: "BAD_REQUEST" });
+        }
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /**
+     * Other services, called as this one, in a step. A command handler is refused, as for the secret
+     * store: it would block the workflow's other commands behind another service.
+     */
+    get services() {
+        if (!this.#inStep) {
+            throw new CommandError({ message: "a workflow calls another service in a step, not in a command handler", code: "BAD_REQUEST" });
+        }
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's. */
+    set services(services) {
+        this.#services = services;
+    }
+    /** @internal The server marks a step's binding, which is how a step is told from a command. */
+    _enterStep() {
+        this.#inStep = true;
+    }
     /** @internal */
     get _kind() {
         return "workflow";
@@ -57,5 +95,6 @@ export class Workflow {
         this.#context = undefined;
         this.#client = undefined;
         this.#bound = false;
+        this.#inStep = false;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ankka",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Build services on ankka in TypeScript: entities, views, workflows, agents and endpoints hosted by the ankka sidecar.",
   "license": "Apache-2.0",
   "type": "module",
@@ -50,7 +50,8 @@
   "dependencies": {
     "@bufbuild/protobuf": "^2.15.0",
     "@connectrpc/connect": "^2.2.0",
-    "@connectrpc/connect-node": "^2.2.0"
+    "@connectrpc/connect-node": "^2.2.0",
+    "canonicalize": "^2.1.0"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",