@rikalabs/akter 0.1.0-alpha.0

package/dist/testing/conformance/multi-runner.d.ts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+import type { ConformanceCase } from "../conformance.ts";
+/** A commutative reducer: calls already waiting on the owner merge into one turn. */
+export declare const Tick: import("../../index.ts").Reducer<"Tick", {
+    readonly count: Schema.withDecodingDefault<Schema.Finite, never>;
+}, Schema.Finite, Schema.Void, Schema.Never>;
+/** Multi-runner cases on three runners: placement on exactly one runner, merging of commutative calls into one turn, and retry on the next owner after a kill. */
+export declare const multiRunnerConformance: ReadonlyArray<ConformanceCase>;

package/dist/testing/conformance/multi-runner.js

@@ -0,0 +1,403 @@
+import { Effect, Fiber, Layer, Result, Schedule, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { Actor, Actors, System, User } from "../../index.js";
+import { InternalActors } from "../../runtime/actors.js";
+import { ActorTest } from "../actor-test.js";
+import { ActorCluster } from "../cluster.js";
+const Tallied = Actor.event("Tallied", { amount: Schema.Finite });
+const Add = Actor.command("Add", { payload: Schema.Finite, success: Schema.Finite });
+const Whoami = Actor.command("Whoami", { success: Schema.String });
+const Log = Actor.query("Log", {
+    success: Schema.Array(Schema.Struct({ cursor: Schema.String, commandId: Schema.String })),
+});
+const TallyState = Actor.state({
+    count: Schema.Finite.pipe(Schema.withDecodingDefault(Effect.succeed(0))),
+});
+const tickReductions = { count: 0 };
+/** Runs of the `Add` handler, committed or not, across every runner. */
+const addRuns = { count: 0 };
+/** A commutative reducer: calls already waiting on the owner merge into one turn. */
+export const Tick = Actor.reducer("Tick", {
+    state: TallyState,
+    payload: Schema.Finite,
+    reduce: (state, amount) => {
+        tickReductions.count += 1;
+        return Result.succeed({ count: state.count + amount });
+    },
+    batch: { combine: (first, second) => first + second },
+});
+const Tally = Actor.make("Tally", {
+    key: Schema.String,
+    state: TallyState,
+    events: [Tallied],
+    api: { Add, Whoami, Log, Tick },
+});
+const TallyLive = Layer.mergeAll(Tally.toLayer(Effect.succeed({
+    Add: Effect.fnUntraced(function* (amount) {
+        addRuns.count += 1;
+        const turn = yield* Tally.Turn;
+        yield* turn.state.set({ count: turn.state.count + amount });
+        yield* turn.emit(Tallied.make({ amount }));
+        return turn.state.count;
+    }),
+    Whoami: Effect.fnUntraced(function* () {
+        const turn = yield* Tally.Turn;
+        return Schema.is(User)(turn.caller) ? turn.caller.subject : turn.caller._tag;
+    }),
+})), Tally.toQueryLayer(Effect.succeed({
+    Log: Effect.fnUntraced(function* () {
+        const entries = yield* (yield* Tally.Read).events(Tallied);
+        return entries.map(({ cursor, commandId }) => ({ cursor, commandId }));
+    }, Effect.orDie),
+})));
+const Dispatch = Actor.command("Dispatch", { payload: Schema.String });
+const Hear = Actor.command("Hear");
+const Heard = Actor.query("Heard", { success: Schema.String });
+/** Hears the principal a relay-delivered intent carries: the sender's caller as `onBehalfOf`. */
+const Envoy = Actor.make("Envoy", {
+    key: Schema.String,
+    state: Actor.state({
+        heard: Schema.String.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
+    }),
+    api: { Dispatch, Heard },
+    internal: { Hear },
+});
+const EnvoyLive = Layer.mergeAll(Envoy.toLayer(Effect.succeed({
+    Dispatch: Effect.fnUntraced(function* (target) {
+        yield* Envoy.Turn;
+        yield* (yield* Envoy.intents(target)).Hear();
+    }),
+    Hear: Effect.fnUntraced(function* () {
+        const turn = yield* Envoy.Turn;
+        yield* turn.state.set({
+            heard: Schema.is(System)(turn.caller) ? (turn.caller.onBehalfOf?.subject ?? "") : "",
+        });
+    }),
+})), Envoy.toQueryLayer(Effect.succeed({
+    Heard: Effect.fnUntraced(function* () {
+        return (yield* Envoy.Read).state.heard;
+    }),
+})));
+const EXPIRATION_SECONDS = 3;
+/** Builds a fresh database and a cluster of `runners` on it for one case. */
+const withCluster = (environment, runners, body) => environment.run(Effect.gen(function* () {
+    const database = yield* environment.freshDatabase;
+    const context = yield* Layer.build(ActorTest.cluster({
+        database,
+        runners,
+        shardLockExpiration: `${EXPIRATION_SECONDS} seconds`,
+        actors: Layer.merge(TallyLive, EnvoyLive),
+        as: User.make({ subject: "alice" }),
+        authorize: () => Effect.succeed(true),
+    }));
+    return yield* body.pipe(Effect.provideContext(context));
+}));
+const add = (runner, id, amount) => Effect.gen(function* () {
+    const cluster = yield* ActorCluster;
+    return yield* cluster.on(runner)(Tally.get(id).pipe(Effect.flatMap((tally) => tally.Add(amount))));
+});
+const refOf = (id) => Effect.gen(function* () {
+    const cluster = yield* ActorCluster;
+    return (yield* cluster.on(0)(Tally.get(id))).ref;
+});
+const inspect = (runner, ref) => Effect.gen(function* () {
+    const cluster = yield* ActorCluster;
+    return yield* cluster.on(runner)(ActorTest.use((test) => test.inspect(ref)));
+});
+/** Polls until `ref`'s shard lock is held by a runner that `accept`s it. */
+const awaitOwner = (ref, accept) => Effect.gen(function* () {
+    const cluster = yield* ActorCluster;
+    return yield* cluster.owner(ref).pipe(Effect.repeat({ schedule: Schedule.spaced("25 millis"), until: accept }), Effect.timeoutOrElse({
+        duration: "30 seconds",
+        orElse: () => Effect.die(new Error("The actor's shard did not move")),
+    }));
+});
+/** A shard lock row with database-clock times in epoch milliseconds. */
+const lockOf = (runner, ref) => Effect.gen(function* () {
+    const cluster = yield* ActorCluster;
+    return yield* cluster.on(runner)(Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const shard = yield* (yield* InternalActors).shardId(ref);
+        const [row] = yield* sql `
+          SELECT address,
+            (EXTRACT(EPOCH FROM acquired_at) * 1000)::float8 AS acquired,
+            (EXTRACT(EPOCH FROM LOCALTIMESTAMP) * 1000)::float8 AS now
+          FROM cluster_locks WHERE shard_id = ${shard}`.pipe(Effect.orDie);
+        return row;
+    }));
+});
+/**
+ * Kills an actor's owner while a command from another runner is paused at
+ * `point` on it, then checks that no survivor took the shard before the dead
+ * runner's lock expired and that the caller's in-flight command, under its
+ * original id, committed exactly once.
+ */
+const killDuringTurn = (expect, point) => Effect.gen(function* () {
+    const cluster = yield* ActorCluster;
+    const id = `killed-${point}`;
+    const ref = yield* refOf(id);
+    const owner = (yield* cluster.owner(ref));
+    const caller = (owner + 1) % 3;
+    expect(yield* add(caller, id, 1)).toBe(1);
+    const commandId = yield* cluster.on(caller)(Effect.gen(function* () {
+        return yield* (yield* Actors).mintCommandId;
+    }));
+    const pause = yield* cluster.on(owner)(ActorTest.use((test) => test.pauseNext(point)));
+    const retried = yield* cluster
+        .on(caller)(Tally.get(id).pipe(Effect.flatMap((tally) => tally.Add(2).pipe(Actor.commandId(commandId)))))
+        .pipe(Effect.forkChild);
+    yield* pause.reached;
+    const killed = (yield* lockOf(caller, ref)).now;
+    yield* cluster.kill(owner);
+    const held = yield* lockOf(caller, ref);
+    yield* pause.release;
+    expect(yield* inspect(caller, ref)).toMatchObject(point === "beforeCommit"
+        ? { state: { count: 1 }, receipts: 1, events: 1 }
+        : { state: { count: 3 }, receipts: 2, events: 2 });
+    const taken = yield* lockOf(caller, ref).pipe(Effect.repeat({
+        schedule: Schedule.spaced("10 millis"),
+        until: (lock) => lock.address !== held.address,
+    }), Effect.timeoutOrElse({
+        duration: "30 seconds",
+        orElse: () => Effect.die(new Error("No survivor took the dead runner's shard")),
+    }));
+    const next = (yield* cluster.owner(ref));
+    expect(next === owner).toBe(false);
+    expect(taken.acquired - held.acquired >= EXPIRATION_SECONDS * 1000).toBe(true);
+    expect(yield* Fiber.join(retried)).toBe(3);
+    const resumed = (yield* lockOf(next, ref)).now;
+    expect(resumed >= taken.acquired && taken.acquired >= killed).toBe(true);
+    expect(yield* inspect(next, ref)).toMatchObject({
+        state: { count: 3 },
+        receipts: 2,
+        events: 2,
+    });
+    const log = yield* cluster.on(next)(Tally.get(id).pipe(Effect.flatMap((tally) => tally.Log())));
+    expect(log.map((entry) => entry.commandId).filter((entry) => entry === commandId).length).toBe(1);
+});
+/** Multi-runner cases on three runners: placement on exactly one runner, merging of commutative calls into one turn, and retry on the next owner after a kill. */
+export const multiRunnerConformance = [
+    {
+        name: "merges commutative calls from three runners on the owner into one turn with one receipt per command id",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const id = "merged-ticks";
+            const ref = yield* refOf(id);
+            expect(yield* add(0, id, 1)).toBe(1);
+            const owner = (yield* cluster.owner(ref));
+            const onOwner = cluster.on(owner);
+            const held = yield* onOwner(ActorTest.use((test) => test.pauseNext("beforeCommit")));
+            const first = yield* add((owner + 1) % 3, id, 1).pipe(Effect.forkChild);
+            yield* held.reached;
+            const calls = [];
+            const ticks = [];
+            for (let runner = 0; runner < 3; runner++)
+                for (let call = 0; call < 4; call++) {
+                    const commandId = yield* cluster.on(runner)(Effect.gen(function* () {
+                        return yield* (yield* Actors).mintCommandId;
+                    }));
+                    const queued = yield* onOwner(ActorTest.use((test) => test.pauseNext("queued")));
+                    ticks.push(yield* cluster
+                        .on(runner)(Tally.get(id).pipe(Effect.flatMap((tally) => tally.Tick(1).pipe(Actor.commandId(commandId)))))
+                        .pipe(Effect.forkChild));
+                    yield* queued.reached;
+                    yield* queued.release;
+                    yield* Effect.yieldNow;
+                    calls.push({ runner, commandId });
+                }
+            const before = tickReductions.count;
+            yield* held.release;
+            expect(yield* Fiber.join(first)).toBe(2);
+            expect(yield* Effect.forEach(ticks, Fiber.join)).toEqual(calls.map(() => undefined));
+            expect(tickReductions.count - before).toBe(1);
+            const receipts = yield* cluster.on(owner)(Effect.gen(function* () {
+                const sql = yield* SqlClient.SqlClient;
+                return yield* sql `
+                SELECT command_id, xmin::text AS tx FROM actor_receipts
+                WHERE tenant_id = ${ref.tenant} AND actor_type = 'Tally' AND actor_id = ${ref.id}
+                  AND command = 'Tick'`;
+            }).pipe(Effect.orDie));
+            expect(receipts.map((row) => row.command_id).sort()).toEqual(calls.map((call) => call.commandId).sort());
+            expect(new Set(receipts.map((row) => row.tx)).size).toBe(1);
+            expect(yield* inspect((owner + 2) % 3, ref)).toMatchObject({
+                state: { count: 14 },
+                receipts: 14,
+            });
+            const retried = calls[5];
+            expect(yield* cluster.on((retried.runner + 1) % 3)(Tally.get(id).pipe(Effect.flatMap((tally) => tally.Tick(1).pipe(Actor.commandId(retried.commandId)))))).toBe(undefined);
+            expect(tickReductions.count - before).toBe(1);
+        })),
+    },
+    {
+        name: "places each actor on exactly one of three runners, reachable through every runner",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const ids = Array.from({ length: 24 }, (_, index) => `spread-${index}`);
+            const owners = new Set();
+            for (const id of ids) {
+                yield* add(0, id, 1);
+                const activated = (yield* inspect(0, yield* refOf(id))).generation;
+                for (let runner = 1; runner < 3; runner++)
+                    yield* add(runner, id, 1);
+                expect((yield* inspect(0, yield* refOf(id))).generation).toBe(activated);
+                const owner = yield* cluster.owner(yield* refOf(id));
+                expect(owner === undefined).toBe(false);
+                owners.add(owner);
+            }
+            expect(owners.size > 1).toBe(true);
+            for (const id of ids)
+                expect(yield* inspect(1, yield* refOf(id))).toMatchObject({
+                    state: { count: 3 },
+                    receipts: 3,
+                    events: 3,
+                });
+        })),
+    },
+    {
+        name: "rolls back a killed runner's paused turn and retries it once on the next owner after lock expiry",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, killDuringTurn(expect, "beforeCommit")),
+    },
+    {
+        name: "replays a killed runner's committed turn on the next owner instead of running it again",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 3, killDuringTurn(expect, "afterCommit")),
+    },
+    {
+        name: "fails a stale activation's fence once another runner commits for the actor, then reloads",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 2, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const ref = yield* refOf("stale");
+            const stale = (yield* cluster.owner(ref));
+            const rival = 1 - stale;
+            expect(yield* add(stale, "stale", 1)).toBe(1);
+            const first = Number((yield* inspect(rival, ref)).generation);
+            const heartbeat = yield* cluster.pauseHeartbeat(stale);
+            yield* awaitOwner(ref, (current) => current === rival);
+            expect(yield* add(rival, "stale", 10)).toBe(11);
+            expect(yield* add(stale, "stale", 100)).toBe(111);
+            yield* heartbeat.resume;
+            const inspection = yield* inspect(rival, ref);
+            expect(inspection).toMatchObject({ state: { count: 111 }, receipts: 3, events: 3 });
+            expect(Number(inspection.generation) >= first + 2).toBe(true);
+        })),
+    },
+    {
+        name: "runs a brand-new actor's first command once when two runners race it under one command id",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 2, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const ref = yield* refOf("brand-new");
+            const paused = (yield* cluster.owner(ref));
+            const rival = 1 - paused;
+            expect((yield* inspect(rival, ref)).generation).toBe(undefined);
+            const heartbeat = yield* cluster.pauseHeartbeat(paused);
+            yield* awaitOwner(ref, (current) => current === rival);
+            const id = yield* cluster.on(rival)(Effect.gen(function* () {
+                return yield* (yield* Actors).mintCommandId;
+            }));
+            const before = addRuns.count;
+            const replies = yield* Effect.forEach([paused, rival], (runner) => cluster.on(runner)(Tally.get("brand-new").pipe(Effect.flatMap((tally) => tally.Add(5).pipe(Actor.commandId(id))))), { concurrency: 2 });
+            yield* heartbeat.resume;
+            expect(replies).toEqual([5, 5]);
+            expect(addRuns.count - before).toBe(1);
+            expect(yield* inspect(rival, ref)).toMatchObject({
+                state: { count: 5 },
+                receipts: 1,
+                events: 1,
+            });
+        })),
+    },
+    {
+        name: "orders events gap-free when two real runners race for one actor",
+        requiresIndependentConnections: true,
+        timeoutMs: 90_000,
+        run: ({ expect, environment }) => withCluster(environment, 2, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const ref = yield* refOf("raced");
+            const paused = (yield* cluster.owner(ref));
+            const rival = 1 - paused;
+            yield* add(paused, "raced", 1);
+            const first = Number((yield* inspect(rival, ref)).generation);
+            const heartbeat = yield* cluster.pauseHeartbeat(paused);
+            yield* awaitOwner(ref, (current) => current === rival);
+            yield* Effect.forEach(Array.from({ length: 24 }, (_, index) => index), (index) => add(index % 2 === 0 ? paused : rival, "raced", 1), { concurrency: 8, discard: true });
+            yield* heartbeat.resume;
+            const log = yield* cluster.on(rival)(Tally.get("raced").pipe(Effect.flatMap((tally) => tally.Log())));
+            expect(log.map(({ cursor }) => cursor)).toEqual(Array.from({ length: 25 }, (_, index) => String(index + 1)));
+            expect(new Set(log.map(({ commandId }) => commandId)).size).toBe(25);
+            const inspection = yield* inspect(rival, ref);
+            expect(inspection).toMatchObject({ state: { count: 25 }, receipts: 25, events: 25 });
+            expect(Number(inspection.generation) >= first + 2).toBe(true);
+        })),
+    },
+    {
+        name: "restarts a killed runner, which serves its shards again",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 2, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const ref = yield* refOf("restart");
+            const owner = (yield* cluster.owner(ref));
+            const other = 1 - owner;
+            expect(yield* add(other, "restart", 1)).toBe(1);
+            yield* cluster.kill(owner);
+            expect(yield* add(other, "restart", 1)).toBe(2);
+            expect(yield* cluster.owner(ref)).toBe(other);
+            yield* cluster.restart(owner);
+            yield* cluster.ready;
+            expect((yield* cluster.owner(ref)) === undefined).toBe(false);
+            expect(yield* add(owner, "restart", 1)).toBe(3);
+            expect(yield* add(other, "restart", 1)).toBe(4);
+            expect(yield* inspect(owner, ref)).toMatchObject({ state: { count: 4 }, receipts: 4 });
+        })),
+    },
+    {
+        name: "serializes a 512-byte subject through a cross-runner command",
+        requiresIndependentConnections: true,
+        timeoutMs: 60_000,
+        run: ({ expect, environment }) => withCluster(environment, 2, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const subject = "é".repeat(256);
+            const ids = Array.from({ length: 16 }, (_, index) => `principal-${index}`);
+            for (const id of ids) {
+                yield* add(0, id, 1);
+                const owner = yield* cluster.owner(yield* refOf(id));
+                const caller = owner === 0 ? 1 : 0;
+                const echoed = yield* cluster.on(caller)(Tally.get(id).pipe(Effect.flatMap((tally) => tally.Whoami()), Actor.as(User.make({ subject }))));
+                expect(owner === 0 || owner === 1).toBe(true);
+                expect(echoed).toBe(subject);
+            }
+        })),
+    },
+    {
+        name: "carries the largest supported principal as onBehalfOf through a relay-delivered intent between runners",
+        requiresIndependentConnections: true,
+        timeoutMs: 90_000,
+        run: ({ expect, environment }) => withCluster(environment, 2, Effect.gen(function* () {
+            const cluster = yield* ActorCluster;
+            const subject = "é".repeat(256);
+            const receivers = Array.from({ length: 12 }, (_, index) => `receiver-${index}`);
+            for (const receiver of receivers)
+                yield* cluster.on(0)(Envoy.get("sender").pipe(Effect.flatMap((envoy) => envoy.Dispatch(receiver)), Actor.as(User.make({ subject }))));
+            const owners = new Set();
+            for (const receiver of receivers) {
+                owners.add(yield* cluster.owner((yield* cluster.on(0)(Envoy.get(receiver))).ref));
+                const heard = yield* cluster
+                    .on(1)(Envoy.get(receiver).pipe(Effect.flatMap((envoy) => envoy.Heard()), Effect.filterOrFail((value) => value !== "")))
+                    .pipe(Effect.retry({ times: 60, schedule: Schedule.spaced("500 millis") }));
+                expect(heard).toBe(subject);
+            }
+            expect(owners.size).toBe(2);
+        })),
+    },
+];

package/dist/testing/conformance/neki/plan.d.ts

@@ -0,0 +1,19 @@
+/** One node of a Neki plan printed with `FORMAT TEXT`. */
+export interface NekiPlanNode {
+    /** `Route`, `Collapse`, `Aggregate`, `Limit`, and any other router operator. */
+    readonly operator: string;
+    /** The bracketed routing choice, e.g. `EqualUnique`, `IN` or `Scatter`. */
+    readonly kind: string | undefined;
+}
+/**
+ * The router operators of a plan printed by `EXPLAIN (NEKI_PLAN, FORMAT TEXT)`,
+ * in print order. Tree glyphs and indentation are dropped.
+ */
+export declare const nekiPlanNodes: (plan: string) => ReadonlyArray<NekiPlanNode>;
+/**
+ * Whether a plan is one route to one shard and nothing else. A router
+ * operator above the route, a second route, a scatter, an `IN` list, and a
+ * routing choice not known to be single-shard all fail: an unfamiliar plan is
+ * reported, never assumed safe.
+ */
+export declare const touchesOneShard: (plan: string) => boolean;

package/dist/testing/conformance/neki/plan.js

@@ -0,0 +1,30 @@
+/**
+ * A node line is an operator name with an optional bracketed kind. Attribute
+ * lines such as `Query:` and `ShardGroup:` carry a colon and are not nodes.
+ */
+const NODE = /^([A-Za-z][A-Za-z ]*?)(?: \[([^\]]+)\])?$/;
+/**
+ * The router operators of a plan printed by `EXPLAIN (NEKI_PLAN, FORMAT TEXT)`,
+ * in print order. Tree glyphs and indentation are dropped.
+ */
+export const nekiPlanNodes = (plan) => plan
+    .split("\n")
+    .map((line) => line.replace(/^[│├└─\s]+/u, "").trim())
+    .flatMap((line) => {
+    const match = NODE.exec(line);
+    return match === null || line.includes(":") ? [] : [{ operator: match[1], kind: match[2] }];
+});
+/** The routing choices that Neki documents as reaching exactly one shard. */
+const SINGLE_SHARD_ROUTES = new Set(["EqualUnique"]);
+/**
+ * Whether a plan is one route to one shard and nothing else. A router
+ * operator above the route, a second route, a scatter, an `IN` list, and a
+ * routing choice not known to be single-shard all fail: an unfamiliar plan is
+ * reported, never assumed safe.
+ */
+export const touchesOneShard = (plan) => {
+    const nodes = nekiPlanNodes(plan);
+    return (nodes.length === 1 &&
+        nodes[0].operator === "Route" &&
+        SINGLE_SHARD_ROUTES.has(nodes[0].kind ?? ""));
+};

package/dist/testing/conformance/observability.d.ts

@@ -0,0 +1,3 @@
+import type { ConformanceCase } from "../conformance.ts";
+/** Observability cases: turn and admission spans, defect logs, and metrics correlate with the command id. */
+export declare const observabilityConformance: ReadonlyArray<ConformanceCase>;