ankka 0.9.1 → 0.11.0

package/dist/testkit/unit.js

@@ -4,7 +4,7 @@
 // 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";
@@ -119,7 +119,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 +157,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 +201,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.9.1";
+export declare const VERSION = "0.11.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.9.1";
+export const VERSION = "0.11.0";

package/dist/view.d.ts

@@ -1,9 +1,26 @@
+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";
 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;
+}
+/** Declares a query for a view's `static declared`. The SDK sends the statement as written. */
+export declare function declaredQuery(name: string, statement: string): 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>;
@@ -29,9 +46,24 @@ 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;
+    /** 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,6 +9,14 @@
 //     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. */
+export function declaredQuery(name, statement) {
+    return Object.freeze({ name, statement });
+}
+/** 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;

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.9.1",
+  "version": "0.11.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",