@rikalabs/akter 0.1.0-alpha.0 → 0.1.0-alpha.3

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

@@ -1,8 +0,0 @@
-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

@@ -1,403 +0,0 @@
-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

@@ -1,19 +0,0 @@
-/** 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

@@ -1,30 +0,0 @@
-/**
- * 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

@@ -1,3 +0,0 @@
-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>;