@akterjs/conformance 0.0.0-stage → 0.1.1

package/src/client-contract.suite.ts

@@ -0,0 +1,413 @@
+import { ActorAlreadyExistsError, CallerNotAllowedError, UnauthenticatedError } from "@akterjs/effect/contract/errors";
+import { expect } from "@effect/vitest";
+import type { Vitest } from "@effect/vitest";
+import type { TestContext } from "vitest";
+import {
+  Array as Arr,
+  Effect,
+  Exit,
+  Function,
+  MutableRef,
+  Option,
+  Queue,
+  Record as Rec,
+  Schedule,
+  Schema,
+  Scope,
+  Stream,
+} from "effect";
+import type { Cause } from "effect";
+import { SecureRandom } from "effect/crypto";
+
+import { ClientTargetUnsetError } from "./client-target.errors.js";
+import type { RejectedError } from "./rejected.errors.js";
+import { clients, wired } from "./tally-clients.layer.js";
+import type { Connect, Headers, TallyHandle, Update, Wire } from "./tally-clients.layer.js";
+import { ShortError } from "./tally.contract.js";
+
+interface ClientCallers {
+  readonly foreign?: Headers;
+  readonly stranger: Headers;
+  readonly unauthenticated: Headers;
+  readonly user: Headers;
+}
+
+interface ClientTarget {
+  readonly callers: ClientCallers;
+  // A new actor key for each case, by default a random `tally-<uuid>`.
+  // A target that serves only some shards, such as a local Cloud harness, supplies keys on those shards.
+  readonly freshKey?: Effect.Effect<string>;
+  readonly url: string;
+}
+
+type Target<Failure, Services> = Effect.Effect<ClientTarget, ClientTargetUnsetError | Failure, Scope.Scope | Services>;
+
+interface Case {
+  readonly connect: Connect;
+  readonly target: ClientTarget;
+  readonly wire: Wire;
+}
+
+type ContractCase = (test: Case) => Effect.Effect<void, Cause.NoSuchElementError | RejectedError, Scope.Scope>;
+
+type Updates<Value> = Queue.Dequeue<Update<Value>, RejectedError>;
+
+const none = 0;
+
+const one = 1;
+
+const two = 2;
+
+const three = 3;
+
+const four = 4;
+
+const five = 5;
+
+const eight = 8;
+
+const nine = 9;
+
+const pollTries = 250;
+
+const abnormalClose = 4000;
+
+const dropped = "dropped by the client contract fixture";
+
+const resubscribed = "250 millis";
+
+const updateDeadline = "10 seconds";
+
+const randomKey = Effect.sync(() => `tally-${SecureRandom.uuidV4Unsafe()}`);
+
+const freshKeyOf = ({ freshKey }: ClientTarget): Effect.Effect<string> =>
+  Option.getOrElse(Option.fromNullishOr(freshKey), () => randomKey);
+
+const polled = <Value>(read: Effect.Effect<Value>, done: (value: Value) => boolean): Effect.Effect<Value> =>
+  Effect.filterOrFail(read, done, () => "not yet").pipe(
+    Effect.retry({ schedule: Schedule.spaced("20 millis"), times: pollTries }),
+    Effect.orDie,
+  );
+
+const nextOf = <Value>(queue: Updates<Value>): Effect.Effect<Update<Value>, RejectedError> =>
+  Effect.timeoutOrElse(Queue.take(queue), {
+    duration: updateDeadline,
+    orElse: () => Effect.die(`no live update arrived within ${updateDeadline}`),
+  });
+
+const collected = <Value>(
+  updates: Stream.Stream<Update<Value>, RejectedError>,
+): Effect.Effect<Updates<Value>, never, Scope.Scope> =>
+  Effect.gen(function* collect() {
+    const queue = yield* Queue.unbounded<Update<Value>, RejectedError>();
+
+    yield* Effect.forkScoped(
+      Effect.matchEffect(
+        Stream.runForEach(updates, (update) => Queue.offer(queue, update)),
+        { onFailure: (failure) => Queue.fail(queue, failure), onSuccess: () => Effect.void },
+      ),
+    );
+
+    return queue;
+  });
+
+const headOf = <Value>(
+  updates: Stream.Stream<Update<Value>, RejectedError>,
+): Effect.Effect<Update<Value>, Cause.NoSuchElementError | RejectedError> =>
+  Effect.flatMap(Stream.runHead(updates), Effect.fromOption);
+
+const handle = (
+  { connect, target, wire }: Case,
+  headers: Headers,
+  key: string,
+): Effect.Effect<TallyHandle, never, Scope.Scope> =>
+  Effect.map(connect({ headers, url: target.url, wire }), (connected) => connected(key));
+
+const reasonOf = (effect: Effect.Effect<unknown, RejectedError>): Effect.Effect<unknown> =>
+  Effect.match(effect, { onFailure: (failure) => failure.reason, onSuccess: (succeeded) => ({ succeeded }) });
+
+const created = Effect.fnUntraced(function* created(test: Case) {
+  const key = yield* freshKeyOf(test.target);
+  const tally = yield* handle(test, test.target.callers.user, key);
+
+  yield* tally.create("ada");
+
+  return { key, tally };
+});
+
+const creation = Effect.fnUntraced(function* creation(test: Case) {
+  const { tally } = yield* created(test);
+  const again = yield* reasonOf(tally.create("bob"));
+
+  yield* tally.ensure("bob");
+
+  const owner = yield* tally.owner;
+
+  expect(again).toBeInstanceOf(ActorAlreadyExistsError);
+  expect(owner).toBe("ada");
+});
+
+const commands = Effect.fnUntraced(function* commands(test: Case) {
+  const { tally } = yield* created(test);
+  const added = yield* tally.add(five);
+  const short = yield* reasonOf(tally.take(nine));
+  const taken = yield* tally.take(two);
+
+  expect([added, taken]).toStrictEqual([five, three]);
+  expect(short).toBeInstanceOf(ShortError);
+  expect(short).toStrictEqual(ShortError.make({ total: five }));
+});
+
+const reads = Effect.fnUntraced(function* reads(test: Case) {
+  const { tally } = yield* created(test);
+
+  yield* tally.add(four);
+
+  const totals = yield* collected(tally.totals);
+  const [total, first, state] = yield* Effect.all([tally.total, nextOf(totals), headOf(tally.state)]);
+
+  yield* tally.add(one);
+
+  const next = yield* nextOf(totals);
+
+  expect([total, first.value, next.value]).toStrictEqual([four, four, five]);
+  expect(state).toStrictEqual({ value: { owner: "ada", total: four }, version: first.version });
+  expect(next.version).toBeGreaterThan(first.version);
+});
+
+// Each round first reads the total, which a cache may then hold, and reads it again right after the caller's own command.
+const readYourWrites = Effect.fnUntraced(function* readYourWrites(test: Case) {
+  const { tally } = yield* created(test);
+
+  const seen = yield* Effect.forEach(Arr.makeBy(five, Function.identity), () =>
+    Effect.andThen(tally.total, Effect.andThen(tally.add(one), tally.total)),
+  );
+
+  expect(seen).toStrictEqual([one, two, three, four, five]);
+});
+
+// Two fresh keys to fork into, and a third that another caller creates, with a handle on it.
+const forkTargets = Effect.fnUntraced(function* forkTargets(test: Case) {
+  const [first, second, taken] = yield* Effect.all([
+    freshKeyOf(test.target),
+    freshKeyOf(test.target),
+    freshKeyOf(test.target),
+  ]);
+
+  const occupied = yield* handle(test, test.target.callers.user, taken);
+
+  return { first, occupied, second, taken };
+});
+
+// A fork copies the actor at the moment it runs: its sibling forked later sees later state, and neither copy nor the
+// Parent sees the others' commands. A lost fork reply retried with its id makes one copy.
+const forking = Effect.fnUntraced(function* forking(test: Case) {
+  const { tally } = yield* created(test);
+  const { first, occupied, second, taken } = yield* forkTargets(test);
+
+  yield* Effect.andThen(tally.add(three), test.wire.loseNextReply);
+
+  const child = yield* tally.fork(first);
+  const sibling = yield* Effect.andThen(tally.add(one), tally.fork(second));
+
+  yield* Effect.andThen(child.add(five), occupied.create("bob"));
+
+  const totals = Effect.all([tally.total, child.total, sibling.total, child.owner, occupied.owner]);
+  const [refused, read] = yield* Effect.all([reasonOf(tally.fork(taken)), totals]);
+
+  expect(read).toStrictEqual([four, eight, four, "ada", "bob"]);
+  expect(refused).toBeInstanceOf(ActorAlreadyExistsError);
+});
+
+const warming = Effect.fnUntraced(function* warming(test: Case) {
+  const { tally } = yield* created(test);
+  const never = yield* Effect.flatMap(freshKeyOf(test.target), (key) => handle(test, test.target.callers.user, key));
+  const before = yield* headOf(tally.state);
+
+  yield* Effect.all([tally.warm, never.warm]);
+
+  const after = yield* headOf(tally.state);
+
+  yield* never.create("bob");
+
+  const owner = yield* never.owner;
+
+  expect([after, owner]).toStrictEqual([before, "bob"]);
+});
+
+const refusals = Effect.fnUntraced(function* refusals(test: Case) {
+  const { key, tally } = yield* created(test);
+  const { stranger, unauthenticated } = test.target.callers;
+  const [robot, anyone] = yield* Effect.all([handle(test, stranger, key), handle(test, unauthenticated, key)]);
+  const refused = yield* reasonOf(robot.add(one));
+  const anonymous = yield* reasonOf(anyone.add(one));
+  const total = yield* tally.total;
+
+  expect(refused).toBeInstanceOf(CallerNotAllowedError);
+  expect(anonymous).toBeInstanceOf(UnauthenticatedError);
+  expect(total).toBe(none);
+});
+
+const outsiders = (headers: Headers): ContractCase =>
+  Effect.fnUntraced(function* refuseOutsiders(test: Case) {
+    const { key } = yield* created(test);
+    const outsider = yield* handle(test, headers, key);
+    const refused = yield* reasonOf(outsider.add(one));
+    const read = yield* reasonOf(outsider.total);
+
+    expect(refused).toBeInstanceOf(CallerNotAllowedError);
+    expect(read).toBeInstanceOf(CallerNotAllowedError);
+  });
+
+const lostReply = Effect.fnUntraced(function* lostReply(test: Case) {
+  const { tally } = yield* created(test);
+
+  yield* test.wire.loseNextReply;
+
+  const added = yield* tally.add(three);
+  const total = yield* tally.total;
+
+  expect([added, total]).toStrictEqual([three, three]);
+});
+
+const dropSockets = ({ wire }: Case): Effect.Effect<void> =>
+  Effect.gen(function* dropEverySocket() {
+    const before = MutableRef.get(wire.opened);
+
+    yield* Effect.sync(() => {
+      for (const socket of wire.sockets) {
+        socket.close(abnormalClose, dropped);
+      }
+    });
+    yield* polled(
+      Effect.sync(() => MutableRef.get(wire.opened)),
+      (count) => count > before,
+    );
+    yield* Effect.sleep(resubscribed);
+  });
+
+const reconnect = Effect.fnUntraced(function* reconnect(test: Case) {
+  const { tally } = yield* created(test);
+  const totals = yield* collected(tally.totals);
+  const first = yield* nextOf(totals);
+
+  const next = yield* Effect.andThen(Effect.andThen(dropSockets(test), tally.add(two)), nextOf(totals));
+
+  yield* tally.add(one);
+
+  const last = yield* nextOf(totals);
+
+  expect([first.value, next.value, last.value]).toStrictEqual([none, two, three]);
+  expect(next.version).toBeGreaterThan(first.version);
+  expect(last.version).toBeGreaterThan(next.version);
+});
+
+const disposal = Effect.fnUntraced(function* disposal(test: Case) {
+  const scope = yield* Scope.make();
+  const { tally } = yield* Scope.provide(created(test), scope);
+  const totals = yield* Scope.provide(collected(tally.totals), scope);
+
+  yield* nextOf(totals);
+
+  const open = test.wire.sockets.size;
+
+  yield* Scope.close(scope, Exit.void);
+
+  const left = yield* polled(
+    Effect.sync(() => test.wire.sockets.size),
+    (size) => size === none,
+  );
+
+  expect([open, left]).toStrictEqual([one, none]);
+});
+
+type CaseName =
+  | "commands"
+  | "creation"
+  | "disposal"
+  | "foreign"
+  | "forking"
+  | "lostReply"
+  | "readYourWrites"
+  | "reads"
+  | "reconnect"
+  | "refusals"
+  | "warming";
+
+const titles: Readonly<Record<CaseName, string>> = {
+  commands: "a command replies with its success or the contract's typed error",
+  creation: "create makes the actor once, and ensure attaches to it",
+  disposal: "disposing the client closes its live sockets",
+  foreign: "a caller from another organization or app is refused with CallerNotAllowedError",
+  forking:
+    "a fork copies the actor at one cut into a new key, independent of its parent and siblings, once per fork id",
+  lostReply: "a command whose reply was lost is retried with its id and runs once",
+  readYourWrites: "a query right after the caller's own command reads that command's write",
+  reads: "queries and state read committed state, and live updates carry increasing versions",
+  reconnect: "a subscription that loses its socket reconnects and resumes without repeating an update",
+  refusals: "a caller the contract doesn't allow, or one without valid credentials, is refused and changes nothing",
+  warming: "warm opens an actor without changing it, and does nothing for a key never created",
+};
+
+const casesOf = (callers: ClientCallers): Readonly<Record<CaseName, ContractCase>> => ({
+  commands,
+  creation,
+  disposal,
+  foreign: Option.match(Option.fromNullishOr(callers.foreign), {
+    onNone: () => () => Effect.die("this target declares no caller from another organization or app"),
+    onSome: outsiders,
+  }),
+  forking,
+  lostReply,
+  readYourWrites,
+  reads,
+  reconnect,
+  refusals,
+  warming,
+});
+
+interface ClientContract<Failure, Services> {
+  readonly skip: Readonly<Partial<Record<CaseName, string>>>;
+  readonly target: Target<Failure, Services>;
+}
+
+const perTest = 60_000;
+
+const isUnset = Schema.is(ClientTargetUnsetError);
+
+const clientConformanceOf =
+  <Failure, Services>({ skip, target }: ClientContract<Failure, Services>) =>
+  (test: Vitest.MethodsNonLive<Services>): void => {
+    for (const [client, connect] of clients) {
+      for (const name of Rec.keys(titles)) {
+        const title = `${client}: ${titles[name]}`;
+
+        const run = ({
+          skip: skipCase,
+        }: TestContext): Effect.Effect<void, Cause.NoSuchElementError | Failure | RejectedError, Services> =>
+          Effect.scoped(
+            Effect.gen(function* runCase() {
+              const resolved = yield* target;
+              const wire = yield* wired;
+
+              yield* casesOf(resolved.callers)[name]({ connect, target: resolved, wire });
+            }),
+          ).pipe(Effect.catchIf(isUnset, ({ reason }) => Effect.sync(() => skipCase(reason))));
+
+        Option.match(Option.fromNullishOr(skip[name]), {
+          onNone: () => {
+            test.effect(title, run, perTest);
+          },
+          onSome: (reason) => {
+            test.effect.skip(`${title} (skipped: ${reason})`, run);
+          },
+        });
+      }
+    }
+  };
+
+export { clientConformanceOf };
+
+export { ClientTargetUnsetError } from "./client-target.errors.js";
+
+export type { CaseName, ClientCallers, ClientTarget };

package/src/client-target.errors.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+
+// A target that can't serve this run, such as a deployed stage nobody configured, fails with this and the case is skipped.
+export class ClientTargetUnsetError extends Schema.TaggedError<
+  ClientTargetUnsetError,
+  { readonly brand: unique symbol }
+>()("ClientTargetUnsetError", { reason: Schema.String }) {}