@rikalabs/akter 0.1.0-alpha.0

package/dist/testing/conformance/properties.js

@@ -0,0 +1,295 @@
+import { isDeepStrictEqual } from "node:util";
+import { Effect, Match, Predicate, Schema } from "effect";
+import { Arbitrary } from "effect";
+import { Actor, Actors, CommandExpired, InvalidCommandId } from "../../index.js";
+import { ActorTest } from "../actor-test.js";
+import { checkProperty } from "../property.js";
+import { payloadHash } from "./admission.js";
+import { bodies, cursors, Feed, prune, eventsSuite } from "./events.js";
+import { Outboxer, receivedBodies, outboxSuite } from "./outbox.js";
+class Refused extends Schema.TaggedError()("Refused", { amount: Schema.Int }) {
+}
+const Add = Actor.command("Add", { payload: Schema.Int, success: Schema.Int });
+const Refuse = Actor.command("Refuse", { payload: Schema.Int, error: Refused });
+const Echo = Actor.command("Echo", { payload: Schema.String, success: Schema.String });
+const Tally = Actor.make("PropertyTally", {
+    key: Schema.String,
+    state: Actor.state({ count: Schema.Int.pipe(Schema.withDecodingDefault(Effect.succeed(0))) }),
+    api: { Add, Refuse, Echo },
+});
+export const propertiesLayer = Tally.toLayer(Effect.succeed({
+    Add: Effect.fnUntraced(function* (amount) {
+        const turn = yield* Tally.Turn;
+        yield* turn.state.set({ count: turn.state.count + amount });
+        return turn.state.count;
+    }),
+    Refuse: Effect.fnUntraced(function* (amount) {
+        const turn = yield* Tally.Turn;
+        yield* turn.state.set({ count: -1 });
+        return yield* Refused.make({ amount });
+    }),
+    Echo: (text) => Effect.succeed(text),
+}));
+const CRASH_RUNS = 8;
+const small = (maximum) => Arbitrary.schema(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum })));
+let cases = 0;
+const nextCase = (prefix) => {
+    cases += 1;
+    return `property-${prefix}-${cases}`;
+};
+const CrashPoint = Schema.Literals(["beforeHandler", "beforeCommit", "afterCommit"]);
+const ReceiptOp = Schema.Struct({
+    slot: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 2 })),
+    kind: Schema.Literals(["Add", "Refuse"]),
+    amount: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 2 })),
+});
+const receiptOps = Arbitrary.array(Arbitrary.schema(ReceiptOp), { minLength: 1, maxLength: 6 });
+const StoredCount = Schema.Struct({ count: Schema.optionalKey(Schema.Int) });
+const receiptModel = Effect.fnUntraced(function* (ops, crash) {
+    const test = yield* ActorTest;
+    const actors = yield* Actors;
+    const tally = yield* Tally.get(nextCase("receipts"));
+    const ids = [
+        yield* actors.mintCommandId,
+        yield* actors.mintCommandId,
+        yield* actors.mintCommandId,
+    ];
+    const stored = new Map();
+    let count = 0;
+    const fresh = ops.flatMap((op, index) => ops.findIndex(({ slot }) => slot === op.slot) === index ? [index] : []);
+    const crashAt = crash === undefined ? -1 : (fresh.find((index) => index >= crash.at) ?? fresh.at(-1));
+    for (const [index, op] of ops.entries()) {
+        const receipt = stored.get(op.slot);
+        let expected;
+        if (receipt === undefined) {
+            if (op.kind === "Add")
+                count += op.amount;
+            expected = op.kind === "Add" ? `ok:${count}` : `refused:${op.amount}`;
+            stored.set(op.slot, { kind: op.kind, amount: op.amount, reply: expected });
+            if (crash !== undefined && index === crashAt)
+                yield* test.crashNext(crash.point);
+        }
+        else
+            expected =
+                receipt.kind === op.kind && receipt.amount === op.amount ? receipt.reply : "CommandConflict";
+        const id = Actor.commandId(ids[op.slot]);
+        const reply = op.kind === "Add"
+            ? yield* tally.Add(op.amount).pipe(id, Effect.map((value) => `ok:${value}`), Effect.catch((error) => Effect.succeed(error.reason._tag)))
+            : yield* tally.Refuse(op.amount).pipe(id, Effect.as("replied"), Effect.catchTag("Refused", (error) => Effect.succeed(`refused:${error.amount}`)), Effect.catch((error) => Effect.succeed(error.reason._tag)));
+        if (reply !== expected)
+            return false;
+    }
+    const inspection = yield* test.inspect(tally.ref);
+    const state = yield* Schema.decodeUnknownEffect(StoredCount)(inspection.state).pipe(Effect.orDie);
+    return inspection.receipts === stored.size && (state.count ?? 0) === count;
+});
+const Json = Schema.Json;
+const encodeJson = (value) => Schema.encodeEffect(Schema.fromJsonString(Json))(value).pipe(Effect.orDie);
+const EventOp = Schema.Union([
+    Schema.TaggedStruct("Post", { body: Schema.Literals(["a", "b", "c"]) }),
+    Schema.TaggedStruct("Archive", {}),
+    Schema.TaggedStruct("Prune", {
+        by: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 3 })),
+    }),
+    Schema.TaggedStruct("Read", {
+        after: Schema.Union([
+            Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 8 })),
+            Schema.Literals(["x", "-1", "01", "1.0", " 1", "9223372036854775807", "9223372036854775808"]),
+        ]),
+        archived: Schema.Boolean,
+    }),
+]);
+const eventOps = Arbitrary.array(Arbitrary.schema(EventOp), { minLength: 1, maxLength: 8 });
+const TimerOp = Schema.Union([
+    Schema.TaggedStruct("Schedule", { key: Schema.optionalKey(Schema.Literals(["a", "b", "c"])) }),
+    Schema.TaggedStruct("Cancel", { key: Schema.Literals(["a", "b", "c"]) }),
+    Schema.TaggedStruct("CancelThenRefuse", { key: Schema.Literals(["a", "b", "c"]) }),
+]);
+const timerOps = Arbitrary.array(Arbitrary.schema(TimerOp), { minLength: 1, maxLength: 6 });
+const isJsonObject = Schema.is(Schema.JsonObject);
+/** Reorders every object's keys, which JSONB canonicalization must undo. */
+const reversed = (value) => {
+    if (Array.isArray(value))
+        return value.map(reversed);
+    if (isJsonObject(value))
+        return Object.fromEntries(Object.entries(value)
+            .reverse()
+            .map(([key, entry]) => [key, reversed(entry)]));
+    return value;
+};
+const storableText = (text) => !text.includes("\u0000") && new TextDecoder().decode(new TextEncoder().encode(text)) === text;
+const storable = (value) => {
+    if (Predicate.isString(value))
+        return storableText(value);
+    if (Array.isArray(value))
+        return value.every(storable);
+    if (isJsonObject(value))
+        return Object.entries(value).every(([key, entry]) => storableText(key) && storable(entry));
+    return true;
+};
+/** Property cases: payload hashing and receipts checked against a model over generated inputs. */
+export const propertiesConformance = [
+    {
+        name: "property: hashes a payload by its JSONB canonical text regardless of key order or spacing",
+        timeoutMs: 120_000,
+        run: ({ environment }) => environment.run(checkProperty({
+            name: "canonical payload hash",
+            arbitrary: Arbitrary.filter(Arbitrary.schema(Json), storable).pipe(Arbitrary.map((value) => ({ value, escapes: ["\\^@", "\\u0000"] }))),
+            property: Effect.fnUntraced(function* (value) {
+                const text = yield* encodeJson(value);
+                const reorderedText = yield* encodeJson(reversed(value));
+                const hash = yield* payloadHash(text);
+                return (/^[0-9a-f]{64}$/.test(hash) &&
+                    hash === (yield* payloadHash(reorderedText)) &&
+                    hash === (yield* payloadHash(`\n\t ${reorderedText} \n`)));
+            }),
+        }).pipe(Effect.asVoid)),
+    },
+    {
+        name: "property: rejects malformed and expired identities as terminal for payloads Postgres cannot store",
+        timeoutMs: 120_000,
+        run: ({ environment }) => environment.run(Effect.gen(function* () {
+            const tally = yield* Tally.get(nextCase("unstorable"));
+            return yield* checkProperty({
+                name: "terminal identities with NUL payloads",
+                arbitrary: Arbitrary.all([Arbitrary.schema(Schema.String), small(16)]),
+                property: Effect.fnUntraced(function* ([text, at]) {
+                    const index = Math.min(at, text.length);
+                    const payload = `${text.slice(0, index)}\u0000${text.slice(index)}`;
+                    const malformed = `v1.1000.6000.${payload}`;
+                    const expired = "v1.1000.61000.17b3670b-3f17-4a9b-aade-037e1dd1bba8";
+                    const invalid = yield* tally
+                        .Echo(payload)
+                        .pipe(Actor.commandId(malformed), Effect.flip);
+                    const late = yield* tally.Echo(payload).pipe(Actor.commandId(expired), Effect.flip);
+                    return (Schema.is(InvalidCommandId)(invalid.reason) &&
+                        invalid.reason.commandId === malformed &&
+                        Schema.is(CommandExpired)(late.reason) &&
+                        late.reason.commandId === expired);
+                }),
+            }).pipe(Effect.asVoid);
+        })),
+    },
+    {
+        name: "property: receipts match a model under duplicate ids, conflicting payloads, and declared failures",
+        timeoutMs: 600_000,
+        run: ({ environment }) => environment.run(checkProperty({
+            name: "receipt model",
+            arbitrary: receiptOps,
+            property: (ops) => receiptModel(ops, undefined),
+        }).pipe(Effect.asVoid)),
+    },
+    {
+        name: "property: receipts match the same model when one generated turn crashes and retries",
+        timeoutMs: 600_000,
+        run: ({ environment }) => environment.run(checkProperty({
+            name: "receipt model with crashes",
+            arbitrary: Arbitrary.all([receiptOps, small(5), Arbitrary.schema(CrashPoint)]),
+            property: ([ops, at, point]) => receiptModel(ops, { at, point }),
+            runs: CRASH_RUNS,
+        }).pipe(Effect.asVoid)),
+    },
+    {
+        name: "property: event cursors stay monotonic and replay exclusively under random pruning, against a model",
+        timeoutMs: 600_000,
+        run: ({ environment }) => environment.run(checkProperty({
+            name: "event cursor model",
+            arbitrary: eventOps,
+            property: Effect.fnUntraced(function* (ops) {
+                const id = nextCase("events");
+                const feed = yield* Feed.get(id);
+                let retained = [];
+                let head = 0;
+                const read = (after, archived) => feed.History({ after, archived }).pipe(Effect.map((entries) => [cursors(entries), bodies(entries)]), Effect.catchTags({
+                    UnknownCursor: ({ cursor }) => Effect.succeed(`UnknownCursor:${cursor}`),
+                    RetentionGap: ({ cursor }) => Effect.succeed(`RetentionGap:${cursor}`),
+                    ActorError: ({ reason }) => Effect.succeed(reason._tag),
+                }), Effect.map((replay) => {
+                    const canonical = /^(0|[1-9][0-9]{0,18})$/.test(after);
+                    const position = canonical ? BigInt(after) : -1n;
+                    const oldest = retained[0]?.sequence;
+                    const tag = archived ? "Archived" : "Posted";
+                    const matching = retained.filter((event) => BigInt(event.sequence) > position && event.tag === tag);
+                    const expected = !canonical || position > 2n ** 63n - 1n || position > BigInt(head)
+                        ? `UnknownCursor:${after}`
+                        : position < BigInt(head) &&
+                            (oldest === undefined || BigInt(oldest) > position + 1n)
+                            ? `RetentionGap:${after}`
+                            : [
+                                matching.map(({ sequence }) => String(sequence)),
+                                matching.map(({ body }) => body),
+                            ];
+                    return isDeepStrictEqual(replay, expected);
+                }));
+                const append = (tag, body) => {
+                    head += 1;
+                    retained.push({ sequence: head, tag, body });
+                    return true;
+                };
+                for (const op of ops) {
+                    const agrees = yield* Match.value(op).pipe(Match.tagsExhaustive({
+                        Post: ({ body }) => feed.Post(body).pipe(Effect.map(() => append("Posted", body))),
+                        Archive: () => feed.Archive().pipe(Effect.map(() => append("Archived", "Archived"))),
+                        Prune: ({ by }) => {
+                            const oldest = retained[0]?.sequence ?? head + 1;
+                            const through = Math.min(head, oldest - 1 + by);
+                            return prune(id, through).pipe(Effect.map(() => {
+                                retained = retained.filter(({ sequence }) => sequence > through);
+                                return true;
+                            }));
+                        },
+                        Read: ({ after, archived }) => read(String(after), archived),
+                    }));
+                    if (!agrees)
+                        return false;
+                }
+                const all = yield* feed.History({}).pipe(Effect.orElseSucceed(() => []));
+                const sequences = all.map(({ cursor }) => Number(cursor));
+                return sequences.every((sequence, index) => index === 0 || sequence > sequences[index - 1]);
+            }),
+        }).pipe(Effect.asVoid)),
+    },
+    {
+        name: "property: keyed timers replace and cancel exactly as a model predicts",
+        timeoutMs: 600_000,
+        run: ({ environment }) => environment.run(checkProperty({
+            name: "keyed timer model",
+            arbitrary: timerOps,
+            property: Effect.fnUntraced(function* (ops) {
+                const test = yield* ActorTest;
+                const to = nextCase("timers");
+                const outboxer = yield* Outboxer.get(to);
+                const keyed = new Map();
+                const unkeyed = [];
+                for (const [index, op] of ops.entries())
+                    yield* Match.value(op).pipe(Match.tagsExhaustive({
+                        Schedule: ({ key }) => {
+                            const body = `${index}`;
+                            if (key === undefined)
+                                unkeyed.push(body);
+                            else
+                                keyed.set(key, body);
+                            return outboxer.Schedule({ to, body, afterMs: 60_000, ...op });
+                        },
+                        Cancel: ({ key }) => {
+                            keyed.delete(key);
+                            return outboxer.Cancel(key);
+                        },
+                        CancelThenRefuse: ({ key }) => outboxer.CancelThenRefuse(key).pipe(Effect.flip, Effect.asVoid),
+                    }));
+                const pending = (yield* test.inspect(outboxer.ref)).outbox;
+                yield* test.advance("61 seconds");
+                const received = [...(yield* receivedBodies(to))].sort();
+                const expected = [...unkeyed, ...keyed.values()].sort();
+                return (pending === expected.length &&
+                    isDeepStrictEqual(received, expected) &&
+                    (yield* test.inspect(outboxer.ref)).outbox === 0);
+            }),
+        }).pipe(Effect.asVoid)),
+    },
+];
+/** Property actors, beside the feed and outbox actors the properties drive. */
+export const propertiesSuite = {
+    layer: () => propertiesLayer,
+    uses: [eventsSuite, outboxSuite],
+};

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

@@ -0,0 +1,4 @@
+import type { ConformanceCase, ConformanceSuite } from "../conformance.ts";
+export declare const protocolsConformance: ReadonlyArray<ConformanceCase>;
+/** Protocol cases call the served HTTP actors. */
+export declare const protocolsSuite: ConformanceSuite;