@akterjs/conformance 0.0.0-stage → 0.1.1

package/src/ledger/plain-ledger.actor.ts

@@ -0,0 +1,246 @@
+import { Akter as Engine } from "@akterjs/effect";
+import { Akter } from "@akterjs/sdk";
+import type { CommandContext, JobResult, JobSteps, Migrations, PlainActor, Sql, SqlRow } from "@akterjs/sdk";
+import { engineOf } from "@akterjs/sdk/engine";
+import { Array as Arr, Effect, Layer } from "effect";
+import { z } from "zod";
+
+import { fileWriter } from "./ledger-calls.pure.js";
+import { doubled } from "./ledger.contract.js";
+import type { LedgerLayer, Ledgers } from "./ledger.actor.js";
+
+/** The plain SDK's Ledger: the wire contract of the Effect Ledger in `ledger.contract.ts`, so one suite checks both SDKs. */
+const Cents = z.number().int();
+
+const Amount = z.object({ amount: Cents });
+
+const Later = z.object({ amount: Cents, minutes: z.number().int() });
+
+const Approving = z.object({ amount: Cents, job: z.string(), refuse: z.boolean() });
+
+const Release = z.object({});
+
+const Transfer = z.object({ amount: Cents, to: z.string() });
+
+const EntryId = z.string();
+
+const OverdrawnError = Akter.error("OverdrawnError", z.object({ balance: Cents }));
+
+const Account = z.object({ balance: Cents, closed: z.boolean() });
+
+const Entries = z.array(z.object({ amount: Cents, id: EntryId }));
+
+const TableNames = z.array(z.object({ name: z.string() }));
+
+const TableList = z.array(z.string()).readonly();
+
+/** Everything the plain Ledger declares but its `release` job, which the two builds below declare with different patches. */
+const ledgerOptions = {
+  callers: { actor: Akter.ActorPrincipal, service: z.object({ id: z.string() }), user: Akter.Principal },
+  commands: {
+    approve: Akter.command({ payload: Approving }),
+    close: Akter.command({ callers: ["service"] }),
+    crash: Akter.command({ payload: Amount }),
+    credit: Akter.command({ callers: ["actor"], payload: Amount, success: EntryId }),
+    deposit: Akter.command({ payload: Amount, success: EntryId }),
+    depositLater: Akter.command({ payload: Later }),
+    hold: Akter.command({ success: z.string() }),
+    tamper: Akter.command({ payload: Amount }),
+    transfer: Akter.command({ errors: [OverdrawnError], payload: Transfer, success: EntryId }),
+    withdraw: Akter.command({ errors: [OverdrawnError], payload: Amount, success: EntryId }),
+  },
+  files: Akter.fileAccess({ callers: ["user"] }),
+  initial: () => ({ balance: 0, closed: false }),
+  key: z.string(),
+  queries: {
+    account: Akter.query({ success: Account }),
+    entries: Akter.query({ success: Entries }),
+    scribble: Akter.query(),
+    tables: Akter.query({ success: TableList }),
+  },
+  state: Account,
+} as const;
+
+const noPatches: readonly string[] = [];
+
+const doubling: readonly string[] = [doubled];
+
+const Ledger = Akter.make("Ledger", {
+  ...ledgerOptions,
+  jobs: { release: Akter.job({ patches: noPatches, payload: Release, success: Cents }) },
+});
+
+/** The Ledger deployed again with its `release` job patched, over holds the earlier build started. */
+const PatchedLedger = Akter.make("Ledger", {
+  ...ledgerOptions,
+  jobs: { release: Akter.job({ patches: doubling, payload: Release, success: Cents }) },
+});
+
+type LedgerContext =
+  typeof Ledger extends PlainActor<infer Name, infer Options> ? CommandContext<Name, Options> : never;
+
+const lowestBalance = 0;
+
+const millisPerMinute = 60_000;
+
+const scribbled = 1;
+
+const insert = (sql: Sql, id: string, amount: number): readonly SqlRow[] =>
+  sql`INSERT INTO entries (id, amount) VALUES (${id}, ${amount})`;
+
+/** Records an entry and moves the balance, as the Effect Ledger's `record` does. */
+const record = (ctx: LedgerContext, balance: number, amount: number): string => {
+  const id = ctx.id();
+
+  insert(ctx.sql, id, amount);
+  ctx.update({ balance });
+
+  return id;
+};
+
+const withdrawal = (ctx: LedgerContext, amount: number): string => {
+  const balance = ctx.state.balance - amount;
+  const id = record(ctx, balance, amount);
+
+  if (balance < lowestBalance) {
+    throw new OverdrawnError({ balance });
+  }
+
+  return id;
+};
+
+/** Reads the engine's journal, then writes the engine's state table, which no handler may do. */
+const tamperWith = (sql: Sql): readonly SqlRow[] =>
+  Arr.appendAll(sql`SELECT count(*) AS commands FROM akter_commands`, sql`UPDATE akter_state SET value = value`);
+
+const tableNames = (sql: Sql): readonly string[] =>
+  Arr.map(
+    TableNames.parse(
+      sql`SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'akter_%' AND name NOT LIKE 'sqlite_%' ORDER BY name`,
+    ),
+    (row) => row.name,
+  );
+
+/** Signals the held job, then throws after the signal when `refuse` is set, so the command rolls back with it. */
+const approve = (ctx: LedgerContext, { amount, job, refuse }: z.infer<typeof Approving>): void => {
+  ctx.signal(job, "approval", amount);
+
+  if (refuse) {
+    throw new Error("the approval was refused after signalling");
+  }
+};
+
+/** Waits for the approved amount and returns it, so its result records the entry. */
+const release = (_payload: z.infer<typeof Release>, steps: JobSteps): Promise<number> =>
+  Effect.runPromise(
+    Effect.map(
+      Effect.promise(() => steps.waitFor("approval")),
+      (value) => Cents.parse(value),
+    ),
+  );
+
+const twice = 2;
+
+/** The later build's release: twice the approved amount, but only for a hold this build started. */
+const doublingRelease = (payload: z.infer<typeof Release>, steps: JobSteps): Promise<number> =>
+  Effect.runPromise(
+    Effect.map(
+      Effect.promise(() => release(payload, steps)),
+      (amount) => {
+        if (steps.patched(doubled)) {
+          return amount * twice;
+        }
+
+        return amount;
+      },
+    ),
+  );
+
+const released = (ctx: LedgerContext, result: JobResult<number, never>): void => {
+  if (result.outcome === "success") {
+    record(ctx, ctx.state.balance + result.value, result.value);
+  }
+};
+
+interface PlainBuild {
+  readonly job: typeof release;
+  readonly ledger: typeof Ledger;
+}
+
+/** The build the suite opens first: the Ledger without patches. */
+const firstBuild: PlainBuild = { job: release, ledger: Ledger };
+
+const plainLedgerLayer = (migrations: Migrations, { job, ledger }: PlainBuild = firstBuild): LedgerLayer => {
+  const implemented = ledger.implement({
+    commands: {
+      approve,
+      close: (ctx) => {
+        ctx.update({ closed: true });
+      },
+      crash: (ctx, { amount }) => {
+        record(ctx, ctx.state.balance + amount, amount);
+
+        throw new Error("the handler crashed after writing");
+      },
+      credit: (ctx, { amount }) => record(ctx, ctx.state.balance + amount, amount),
+      deposit: (ctx, { amount }) => record(ctx, ctx.state.balance + amount, amount),
+      depositLater: (ctx, { amount, minutes }) => {
+        ctx.schedule(minutes * millisPerMinute, Ledger.commands.deposit, { amount });
+      },
+      hold: (ctx) => ctx.start(ledger.jobs.release, {}),
+      tamper: (ctx, { amount }) => {
+        record(ctx, ctx.state.balance + amount, amount);
+        tamperWith(ctx.sql);
+      },
+      transfer: (ctx, { amount, to }) => {
+        ctx.send(Ledger.commands.credit, to, { amount });
+
+        return withdrawal(ctx, amount);
+      },
+      withdraw: (ctx, { amount }) => withdrawal(ctx, amount),
+    },
+    files: {
+      authorize: (ctx, { access }) => access === "read" || (ctx.principal.id === fileWriter && !ctx.state.closed),
+    },
+    jobs: { release: job },
+    migrations,
+    queries: {
+      account: (ctx) => ({ balance: ctx.state.balance, closed: ctx.state.closed }),
+      entries: (ctx) => Entries.parse(ctx.sql`SELECT id, amount FROM entries ORDER BY rowid`),
+      scribble: (ctx) => {
+        insert(ctx.sql, "query", scribbled);
+      },
+      tables: (ctx) => tableNames(ctx.sql),
+    },
+    results: { release: released },
+  });
+
+  return engineOf(Akter.app([implemented])).layer.pipe(Layer.provide(Engine.jobs));
+};
+
+const createEntries = "CREATE TABLE entries (id TEXT PRIMARY KEY, amount INTEGER NOT NULL)";
+
+const createNotes = "CREATE TABLE notes (id TEXT PRIMARY KEY, text TEXT NOT NULL)";
+
+const entriesVersion = 1;
+
+const notesVersion = 2;
+
+const reservedVersion = 3;
+
+const plainLedgerIntruding = (prefix: string): LedgerLayer =>
+  plainLedgerLayer({
+    [entriesVersion]: createEntries,
+    [notesVersion]: createNotes,
+    [reservedVersion]: `CREATE TABLE "${prefix}intruder" (id TEXT PRIMARY KEY)`,
+  });
+
+/** The plain SDK's Ledgers, for `conformanceOf({ engine, ledgers: plainLedgers, skip })`: every engine must pass the suite on both SDKs. */
+const plainLedgers: Ledgers = {
+  intruding: plainLedgerIntruding,
+  live: plainLedgerLayer({ [entriesVersion]: createEntries }),
+  patched: plainLedgerLayer({ [entriesVersion]: createEntries }, { job: doublingRelease, ledger: PatchedLedger }),
+  withNotes: plainLedgerLayer({ [entriesVersion]: createEntries, [notesVersion]: createNotes }),
+};
+
+export { plainLedgers };

package/src/rejected.errors.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+
+export class RejectedError extends Schema.TaggedError<RejectedError, { readonly brand: unique symbol }>()(
+  "RejectedError",
+  { reason: Schema.Unknown },
+) {}

package/src/tally-clients.layer.ts

@@ -0,0 +1,221 @@
+import { createClient } from "@akterjs/client";
+import { akterClient } from "@akterjs/client/effect";
+import { Cause, Effect, Layer, MutableRef, Option, Queue, Schema, Stream } from "effect";
+import type { Scope } from "effect";
+import { FetchHttpClient } from "effect/http";
+
+import { RejectedError } from "./rejected.errors.js";
+import { Tally } from "./tally.contract.js";
+
+type Headers = Readonly<Record<string, string>>;
+
+interface Update<Value> {
+  readonly value: Value;
+  readonly version: number;
+}
+
+interface Owned {
+  readonly owner: string;
+  readonly total: number;
+}
+
+interface TallyHandle {
+  readonly add: (amount: number) => Effect.Effect<number, RejectedError>;
+  readonly create: (owner: string) => Effect.Effect<void, RejectedError>;
+  readonly ensure: (owner: string) => Effect.Effect<void, RejectedError>;
+  readonly fork: (into: string) => Effect.Effect<TallyHandle, RejectedError>;
+  readonly owner: Effect.Effect<string, RejectedError>;
+  readonly state: Stream.Stream<Update<Owned>, RejectedError>;
+  readonly take: (amount: number) => Effect.Effect<number, RejectedError>;
+  readonly total: Effect.Effect<number, RejectedError>;
+  readonly totals: Stream.Stream<Update<number>, RejectedError>;
+  readonly warm: Effect.Effect<void, RejectedError>;
+}
+
+interface Wire {
+  readonly fetch: typeof globalThis.fetch;
+  readonly loseNextReply: Effect.Effect<void>;
+  readonly opened: MutableRef.MutableRef<number>;
+  readonly sockets: Set<globalThis.WebSocket>;
+  readonly webSocket: typeof globalThis.WebSocket;
+}
+
+interface Connection {
+  readonly headers: Headers;
+  readonly url: string;
+  readonly wire: Wire;
+}
+
+type Connect = (connection: Connection) => Effect.Effect<(key: string) => TallyHandle, never, Scope.Scope>;
+
+type Subscribe<Value> = (onUpdate: (update: Update<Value>) => void, onFailure: (failure: Error) => void) => () => void;
+
+const noSockets = 0;
+
+type NoPayload = Schema.Void["Type"];
+
+const withoutPayload = <Reply>(send: (payload: NoPayload) => Reply, payload?: NoPayload): Reply => send(payload);
+
+const settle = <Success>(promise: () => Promise<Success>): Effect.Effect<Success, RejectedError> =>
+  Effect.tryPromise({ catch: (reason) => RejectedError.make({ reason }), try: promise });
+
+const effectClient: Connect = ({ headers, url, wire }) =>
+  Effect.map(
+    Layer.build(akterClient({ fetch: wire.fetch, headers: () => headers, url, webSocket: wire.webSocket })),
+    (services) =>
+      function handleOf(key): TallyHandle {
+        const client = Tally.client(key);
+
+        const run = <Success, Failure>(
+          use: (tally: Effect.Success<typeof client>) => Effect.Effect<Success, Failure>,
+        ): Effect.Effect<Success, RejectedError> =>
+          Effect.scoped(Effect.flatMap(client, use)).pipe(
+            Effect.mapError((reason) => RejectedError.make({ reason })),
+            Effect.provide(services),
+          );
+
+        const watch = <Value, Failure>(
+          use: (tally: Effect.Success<typeof client>) => Stream.Stream<Update<Value>, Failure>,
+        ): Stream.Stream<Update<Value>, RejectedError> =>
+          Stream.unwrap(Effect.map(client, use)).pipe(
+            Stream.mapError((reason) => RejectedError.make({ reason })),
+            Stream.provide(services),
+          );
+
+        return {
+          add: (amount) => run((tally) => tally.add({ amount })),
+          create: (owner) => run((tally) => tally.create({ owner })),
+          ensure: (owner) => run((tally) => tally.ensure({ owner })),
+          // The copy's client the fork answers must reach the copy, so the fixture reads through it once.
+          fork: (into) =>
+            Effect.as(
+              run((tally) => Effect.flatMap(tally.fork(into), (copy) => withoutPayload(copy.owner))),
+              handleOf(into),
+            ),
+          owner: run((tally) => withoutPayload(tally.owner)),
+          state: watch((tally) => tally.state),
+          take: (amount) => run((tally) => tally.take({ amount })),
+          total: run((tally) => withoutPayload(tally.total)),
+          totals: watch((tally) => withoutPayload(tally.total.subscribe)),
+          warm: run((tally) => tally.warm),
+        };
+      },
+  );
+
+const listened = <Value>(subscribe: Subscribe<Value>): Stream.Stream<Update<Value>, RejectedError> =>
+  Stream.callback<Update<Value>, RejectedError>((queue) =>
+    Effect.acquireRelease(
+      Effect.sync(() =>
+        subscribe(
+          (update) => {
+            Queue.offerUnsafe(queue, update);
+          },
+          (failure) => {
+            Queue.failCauseUnsafe(queue, Cause.fail(RejectedError.make({ reason: failure })));
+          },
+        ),
+      ),
+      (stop) => Effect.sync(stop),
+    ),
+  );
+
+const promiseClient: Connect = ({ headers, url, wire }) =>
+  Effect.map(
+    Effect.acquireRelease(
+      Effect.sync(() =>
+        createClient({ actors: [Tally], fetch: wire.fetch, headers: () => headers, url, webSocket: wire.webSocket }),
+      ),
+      (client) => Effect.promise(() => client.close()),
+    ),
+    (client) =>
+      function handleOf(key): TallyHandle {
+        const tally = client.Tally(key);
+
+        return {
+          add: (amount) => settle(() => tally.add({ amount })),
+          create: (owner) => settle(() => tally.create({ owner })),
+          ensure: (owner) => settle(() => tally.ensure({ owner })),
+          // The copy's client the fork answers must reach the copy, so the fixture reads through it once.
+          fork: (into) =>
+            Effect.as(
+              Effect.flatMap(
+                settle(() => tally.fork(into)),
+                (copy) => settle(() => withoutPayload(copy.owner)),
+              ),
+              handleOf(into),
+            ),
+          owner: settle(() => withoutPayload(tally.owner)),
+          state: listened((onUpdate, onFailure) => tally.state.subscribe(onUpdate, onFailure)),
+          take: (amount) => settle(() => tally.take({ amount })),
+          total: settle(() => withoutPayload(tally.total)),
+          totals: listened((onUpdate, onFailure) => tally.total.subscribe(onUpdate, onFailure)),
+          warm: settle(() => tally.warm()),
+        };
+      },
+  );
+
+const clients: readonly (readonly [string, Connect])[] = [
+  ["the Effect client", effectClient],
+  ["the Promise client", promiseClient],
+];
+
+const isSocket = Schema.is(Schema.instanceOf(globalThis.WebSocket));
+
+// A proxy rather than a subclass keeps the constructor's own type, whose overloads differ between runtimes' typings.
+const trackedSockets = (
+  sockets: Set<globalThis.WebSocket>,
+  opened: MutableRef.MutableRef<number>,
+): typeof globalThis.WebSocket =>
+  new Proxy(globalThis.WebSocket, {
+    construct: (native, socket: readonly unknown[]): globalThis.WebSocket => {
+      const constructed: unknown = Reflect.construct(native, socket);
+      const tracked = Option.getOrThrow(Option.liftPredicate(constructed, isSocket));
+
+      sockets.add(tracked);
+      MutableRef.increment(opened);
+      tracked.addEventListener("close", () => {
+        sockets.delete(tracked);
+      });
+
+      return tracked;
+    },
+  });
+
+const wired: Effect.Effect<Wire> = Effect.gen(function* wired() {
+  const losing = MutableRef.make(false);
+  const sockets = new Set<globalThis.WebSocket>();
+  const opened = MutableRef.make(noSockets);
+  const services = yield* Effect.context();
+  const send = yield* FetchHttpClient.Fetch;
+
+  const losingFetch = (input: Request | URL | string, init?: RequestInit): Promise<Response> =>
+    Effect.runPromiseWith(services)(
+      Effect.gen(function* fetchOrLoseReply() {
+        const response = yield* Effect.promise(() => send(input, init));
+
+        if (MutableRef.get(losing)) {
+          MutableRef.set(losing, false);
+          yield* Effect.promise(() => response.arrayBuffer());
+
+          return yield* Effect.die("the fixture dropped the connection after the server replied");
+        }
+
+        return response;
+      }),
+    );
+
+  // Runtimes' typings add their own members to fetch, such as Bun's preconnect, which the fixture passes through.
+  const fetch = Object.assign(losingFetch, send);
+
+  return {
+    fetch,
+    loseNextReply: Effect.sync(() => MutableRef.set(losing, true)),
+    opened,
+    sockets,
+    webSocket: trackedSockets(sockets, opened),
+  } satisfies Wire;
+});
+
+export { clients, wired };
+
+export type { Connect, Headers, TallyHandle, Update, Wire };

package/src/tally.actor.ts

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+
+import { ShortError, Tally } from "./tally.contract.js";
+
+const empty = 0;
+
+const TallyLive = Tally.toLayer({
+  commands: {
+    add: (tally, { amount }) => Effect.as(Tally.update({ total: tally.total + amount }), tally.total + amount),
+    take: (tally, { amount }) => {
+      if (amount > tally.total) {
+        return ShortError.make({ total: tally.total });
+      }
+
+      return Effect.as(Tally.update({ total: tally.total - amount }), tally.total - amount);
+    },
+  },
+  create: ({ owner }) => Effect.succeed({ owner, total: empty }),
+  queries: {
+    owner: (tally) => Effect.succeed(tally.owner),
+    total: (tally) => Effect.succeed(tally.total),
+  },
+});
+
+// The app `akter deploy --entry` takes, so a deployed stage can serve the client contract's actor.
+const app = { actors: [Tally], layer: TallyLive } as const;
+
+export { app, TallyLive };

package/src/tally.contract.ts

@@ -0,0 +1,22 @@
+import { Akter } from "@akterjs/effect/contract";
+import { Schema } from "effect";
+
+class ShortError extends Schema.TaggedError<ShortError, { readonly brand: unique symbol }>()("ShortError", {
+  total: Schema.Int,
+}) {}
+
+const Tally = Akter.make("Tally", {
+  commands: {
+    add: Akter.command({ payload: { amount: Schema.Int }, success: Schema.Int }),
+    take: Akter.command({ error: ShortError, payload: { amount: Schema.Int }, success: Schema.Int }),
+  },
+  create: { owner: Schema.String },
+  key: Schema.String,
+  queries: {
+    owner: Akter.query({ success: Schema.String }),
+    total: Akter.query({ success: Schema.Int }),
+  },
+  state: Schema.Struct({ owner: Schema.String, total: Schema.Int }),
+});
+
+export { ShortError, Tally };