@xandreed/core 0.13.0 → 0.14.0

package/dist/session/session-log.recovery.conformance.d.ts

@@ -0,0 +1,40 @@
+import { Effect, Scope } from "effect";
+import type { Context } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { SessionLog } from "../ports/session-log.port.js";
+import type { SessionLogError } from "./session-log.entity.js";
+type Log = Context.Service.Shape<typeof SessionLog>;
+/**
+ * A SessionLog backend as the recovery kit opens it. Each run of `open` is a
+ * new handle on the same stored data (a new connection to the same file or
+ * server), released with its scope; the kit opens several at once and opens
+ * again after closing. An in-memory backend passes only when every `open`
+ * returns a log over the same store (build it once and `Effect.succeed` it):
+ * a fresh `SessionLogMemoryLive` per open starts empty.
+ */
+export interface SessionLogSubject {
+    readonly open: Effect.Effect<Log, SessionLogError, Scope.Scope>;
+    /**
+     * The backend stamps commits and heads with the caller's Effect `Clock`
+     * (the memory and SQLite logs do), so the kit can stop the clock and check
+     * the `notAfter` boundary to the millisecond.
+     */
+    readonly callerClock?: boolean;
+}
+/**
+ * What a SessionLog backend must keep across handles, restarts and
+ * interruptions, as checks: commits survive closing and opening again
+ * (twice); two open handles see each other's commits and race by
+ * compare-and-swap with exactly one winner per revision and no lost or
+ * doubled event; an interrupted commit is stored whole or not at all, and has
+ * settled by the time the interrupt returns (a backend whose write can land
+ * after its caller stops waiting, such as a request already sent to a
+ * server, makes that write uninterruptible); a handle whose scope never
+ * closed (leaked, or held by a process that hangs) blocks nobody; and, with
+ * `callerClock`, a commit at exactly its `notAfter` is stored at that time
+ * while one a millisecond later is refused. Every check uses fresh ids and
+ * owners, so the kit is safe on a shared database; each must finish within
+ * 30 seconds, so a handle that waits on another fails instead of hanging.
+ */
+export declare const sessionLogRecoveryConformance: (subject: SessionLogSubject) => ReadonlyArray<ConformanceCheck>;
+export {};

package/dist/session/session-log.recovery.conformance.js

@@ -0,0 +1,143 @@
+import { Effect, Exit, Fiber, Option, Scope } from "effect";
+import { atTime, check, expect, fail, freshId, headerOf } from "../conformance.functions.js";
+import { canonicalJson } from "../memory/memory-log.entity.functions.js";
+const draft = (kind, data, turn = Option.none()) => ({ kind, turn, data }), noState = { notAfter: Option.none(), state: Option.none() }, everything = { after: 0, limit: Option.none(), kinds: [] }, range = (length) => Array.from({ length }, (_, n) => n), rich = { zeta: 1, alpha: { b: [!0, !1, { y: "\xFC", x: 0.5 }], a: "text \u2713" }, empty: {}, list: [] }, seen = (log, id) => Effect.all([log.head(id), log.read(id, everything)]).pipe(Effect.map(([head, events]) => ({
+  seq: head.seq,
+  revision: head.revision,
+  state: head.state,
+  events,
+  text: canonicalJson({
+    header: { ...head.header, parent: Option.getOrNull(head.header.parent) },
+    seq: head.seq,
+    revision: head.revision,
+    state: head.state,
+    updatedAt: head.updatedAt,
+    events: events.map((event) => ({ ...event, turn: Option.getOrNull(event.turn) }))
+  })
+}))), listed = (log, owner) => log.list({ owner, limit: 10, before: Option.none(), parent: Option.none() }).pipe(Effect.map((heads) => canonicalJson(heads.map((head) => ({ id: head.header.id, seq: head.seq, revision: head.revision, updatedAt: head.updatedAt }))))), increment = (log, id, by, n, tries = 0) => Effect.gen(function* () {
+  const head = yield* log.head(id);
+  yield* Effect.yieldNow;
+  const count = typeof head.state.count === "number" ? head.state.count : 0, outcome = yield* Effect.result(log.commit(id, {
+    expect: head.revision,
+    notAfter: Option.none(),
+    events: [draft("increment", { by, n })],
+    state: Option.some({ count: count + 1 })
+  }));
+  if (outcome._tag === "Success")
+    return outcome.success.revision;
+  return outcome.failure._tag === "RevisionConflict" && tries < 100 ? yield* increment(log, id, by, n, tries + 1) : yield* Effect.fail(outcome.failure);
+});
+export const sessionLogRecoveryConformance = (subject) => {
+  const recovery = (name, id, body) => check(name, id, (owner) => Effect.timeoutOrElse(Effect.scoped(body(owner)), {
+    duration: "30 seconds",
+    orElse: () => fail(id, "the check did not finish in 30 seconds: a handle waits on another")
+  })), reading = (id) => Effect.scoped(subject.open.pipe(Effect.flatMap((log) => seen(log, id))));
+  return [
+    recovery("what a handle committed is all there after it closes and the store is opened again", "reopen", (owner) => Effect.gen(function* () {
+      const [id, other] = [yield* freshId, yield* freshId], before = yield* Effect.scoped(Effect.gen(function* () {
+        const log = yield* subject.open;
+        yield* log.create(headerOf(id, owner));
+        yield* log.create(headerOf(other, owner));
+        yield* log.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("a", { n: 1 }, Option.some(1)), draft("b", rich, Option.some(1))], state: Option.some({ open: { turn: 1 } }) });
+        yield* log.commit(id, { expect: 1, ...noState, events: [draft("c", { n: 3 })] });
+        yield* log.commit(other, { expect: 0, notAfter: Option.none(), events: [], state: Option.some({ title: "other" }) });
+        return { session: yield* seen(log, id), listing: yield* listed(log, owner) };
+      }));
+      yield* expect("reopen", before.session.seq === 3 && before.session.revision === 2, `the writing handle read seq ${before.session.seq}, revision ${before.session.revision}`);
+      const after = yield* subject.open.pipe(Effect.flatMap((log) => Effect.all({ session: seen(log, id), listing: listed(log, owner) })));
+      yield* expect("reopen", after.session.text === before.session.text, `after reopening the session reads ${after.session.text}, not ${before.session.text}`);
+      yield* expect("reopen", after.listing === before.listing, `after reopening the listing is ${after.listing}, not ${before.listing}`);
+    })),
+    recovery("opening an existing store again is idempotent: twice more, nothing is lost and commits go on", "reopen-twice", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, written = yield* Effect.scoped(Effect.gen(function* () {
+        const log = yield* subject.open;
+        yield* log.create(headerOf(id, owner));
+        yield* log.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("a", { n: 1 })], state: Option.some({ n: 1 }) });
+        return yield* seen(log, id);
+      })), first = yield* reading(id), second = yield* reading(id);
+      yield* expect("reopen-twice", first.text === written.text && second.text === written.text, "opening the store again changed what it holds");
+      const next = yield* (yield* subject.open).commit(id, { expect: 1, ...noState, events: [draft("b", { n: 2 })] });
+      yield* expect("reopen-twice", next.revision === 2 && next.seq === 2 && next.events[0]?.seq === 2, `the next commit stored revision ${next.revision}, seq ${next.seq}`);
+    })),
+    recovery("two open handles see each other's commits at once, and a stale revision through either is refused", "cross-handle", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, [a, b] = [yield* subject.open, yield* subject.open];
+      yield* a.create(headerOf(id, owner));
+      yield* expect("cross-handle", (yield* b.head(id)).revision === 0, "the other handle reads a revision for a new session");
+      yield* a.commit(id, { expect: 0, ...noState, events: [draft("a", { by: "a" })] });
+      const fromB = yield* seen(b, id);
+      yield* expect("cross-handle", fromB.revision === 1 && fromB.events.map((event) => event.kind).join() === "a", `the other handle reads revision ${fromB.revision}`);
+      yield* b.commit(id, { expect: 1, notAfter: Option.none(), events: [draft("b", { by: "b" })], state: Option.some({ by: "b" }) });
+      const fromA = yield* seen(a, id);
+      yield* expect("cross-handle", fromA.revision === 2 && fromA.events.map((event) => event.kind).join() === "a,b" && fromA.state.by === "b", `the first handle reads revision ${fromA.revision}`);
+      yield* expect("cross-handle", fromA.text === (yield* seen(b, id)).text, "the two handles read the session differently");
+      const stale = yield* Effect.flip(a.commit(id, { expect: 1, ...noState, events: [draft("stale", {})] }));
+      yield* expect("cross-handle", stale._tag === "RevisionConflict" && stale.actual === 2, `a stale commit gave ${stale._tag}`);
+      const listing = yield* b.list({ owner, limit: 10, before: Option.none(), parent: Option.none() });
+      yield* expect("cross-handle", listing.length === 1 && listing[0]?.revision === 2, "the other handle does not list the session as it is");
+    })),
+    recovery("of compare-and-swap commits racing through two handles, exactly one wins each revision, and none is lost or stored twice", "cross-handle-race", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, handles = [yield* subject.open, yield* subject.open];
+      yield* handles[0].create(headerOf(id, owner));
+      const attempts = yield* Effect.forEach(range(8), (n) => Effect.result(handles[n % 2].commit(id, {
+        expect: 0,
+        notAfter: Option.none(),
+        events: [draft("attempt", { n })],
+        state: Option.some({ winner: n })
+      })), { concurrency: "unbounded" }), won = attempts.filter((attempt) => attempt._tag === "Success"), refused = attempts.filter((attempt) => attempt._tag === "Failure" && attempt.failure._tag === "RevisionConflict");
+      yield* expect("cross-handle-race", won.length === 1 && refused.length === 7, `of eight commits against one revision, ${won.length} won and ${refused.length} were refused`);
+      const rounds = 12, revisions = (yield* Effect.forEach(handles, (log, side) => Effect.forEach(range(rounds), (n) => increment(log, id, `handle-${side}`, n)), { concurrency: "unbounded" })).flat().toSorted((left, right) => left - right);
+      yield* expect("cross-handle-race", revisions.join() === range(rounds * 2).map((n) => n + 2).join(), `the increments stored revisions ${revisions.join()}`);
+      const final = yield* reading(id), increments = final.events.filter((event) => event.kind === "increment");
+      yield* expect("cross-handle-race", final.revision === rounds * 2 + 1 && final.seq === rounds * 2 + 1 && final.state.count === rounds * 2, `after ${rounds * 2} increments: revision ${final.revision}, seq ${final.seq}, count ${JSON.stringify(final.state.count)}`);
+      yield* expect("cross-handle-race", handles.every((_, side) => increments.filter((event) => event.data.by === `handle-${side}`).map((event) => event.data.n).join() === range(rounds).join()), "an increment was lost, stored twice or out of order");
+    })),
+    recovery("an interrupted commit leaves all of its events or none, and the session takes the next commit", "interrupted-commit", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, parts = 40, before = yield* Effect.scoped(Effect.gen(function* () {
+        const log = yield* subject.open;
+        yield* log.create(headerOf(id, owner));
+        yield* Effect.forEach([0, 1, 4], (yields, batch) => Effect.gen(function* () {
+          const head = yield* log.head(id), fiber = yield* Effect.forkChild(log.commit(id, {
+            expect: head.revision,
+            notAfter: Option.none(),
+            events: range(parts).map((n) => draft("part", { batch, n })),
+            state: Option.some({ batch })
+          }));
+          yield* Effect.forEach(range(yields), () => Effect.yieldNow, { discard: !0 });
+          yield* Fiber.interrupt(fiber);
+          const after = yield* seen(log, id), written = after.events.filter((event) => event.data.batch === batch).length, whole = written === parts && after.revision === head.revision + 1 && canonicalJson(after.state) === canonicalJson({ batch }), nothing = written === 0 && after.revision === head.revision && after.seq === head.seq;
+          yield* expect("interrupted-commit", whole || nothing, `an interrupted commit left ${written} of its ${parts} events at revision ${after.revision}`);
+          yield* expect("interrupted-commit", after.events.every((event, index) => event.seq === index + 1) && after.seq === after.events.length, "the sequence has a gap");
+        }), { discard: !0 });
+        return yield* seen(log, id);
+      })), log = yield* subject.open, reopened = yield* seen(log, id);
+      yield* expect("interrupted-commit", reopened.text === before.text, "after reopening the session differs from what the interrupted handle read");
+      const next = yield* log.commit(id, { expect: reopened.revision, ...noState, events: [draft("next", {})] });
+      yield* expect("interrupted-commit", next.revision === reopened.revision + 1 && next.seq === reopened.seq + 1, "the commit after the interrupted ones was not stored next");
+    })),
+    recovery("a handle whose scope never closed blocks nothing: a new handle reads all it committed and commits after it", "unclosed-handle", (owner) => Effect.gen(function* () {
+      const id = yield* freshId, abandoned = yield* Scope.make();
+      yield* Effect.addFinalizer(() => Scope.close(abandoned, Exit.void));
+      const left = yield* subject.open.pipe(Scope.provide(abandoned));
+      yield* left.create(headerOf(id, owner));
+      yield* left.commit(id, { expect: 0, notAfter: Option.none(), events: [draft("a", { n: 1 }), draft("b", { n: 2 })], state: Option.some({ by: "abandoned" }) });
+      const wrote = yield* seen(left, id), continued = yield* Effect.scoped(Effect.gen(function* () {
+        const log = yield* subject.open;
+        yield* expect("unclosed-handle", (yield* seen(log, id)).text === wrote.text, "a new handle does not read what the unclosed one committed");
+        yield* log.commit(id, { expect: 1, ...noState, events: [draft("c", { n: 3 })] });
+        return yield* seen(log, id);
+      })), again = yield* reading(id);
+      yield* expect("unclosed-handle", continued.seq === 3 && continued.revision === 2 && again.text === continued.text, `after the unclosed handle: seq ${again.seq}, revision ${again.revision}`);
+    })),
+    ...subject.callerClock === !0 ? [
+      recovery("with the caller's clock, a commit at exactly its notAfter is stored at that time, and one a millisecond later is refused", "expiry-boundary", (owner) => Effect.gen(function* () {
+        const id = yield* freshId, log = yield* subject.open, deadline = (yield* log.create(headerOf(id, owner))).now + 60000, onTime = yield* atTime(deadline)(log.commit(id, { expect: 0, notAfter: Option.some(deadline), events: [draft("on-time", {})], state: Option.none() }));
+        yield* expect("expiry-boundary", onTime.at === deadline && onTime.events.every((event) => event.at === deadline), `a commit at its notAfter was stored at ${onTime.at}, not ${deadline}`);
+        const late = yield* Effect.flip(atTime(deadline + 1)(log.commit(id, { expect: 1, notAfter: Option.some(deadline), events: [draft("late", {})], state: Option.some({ late: !0 }) })));
+        yield* expect("expiry-boundary", late._tag === "LeaseExpired" && late.notAfter === deadline && late.now === deadline + 1, `a commit a millisecond late gave ${JSON.stringify(late)}`);
+        const head = yield* atTime(deadline + 1)(log.head(id));
+        yield* expect("expiry-boundary", head.revision === 1 && head.seq === 1 && head.updatedAt === deadline && canonicalJson(head.state) === "{}", "the late commit wrote something");
+        yield* expect("expiry-boundary", head.now === deadline + 1, `the head was read at ${head.now}, not at the caller's ${deadline + 1}`);
+      }))
+    ] : []
+  ];
+};

package/dist/session/session-log.recovery.conformance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session/sessions.conformance.d.ts

@@ -0,0 +1,79 @@
+import { Effect, Option, Scope } from "effect";
+import type { Context } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { TurnActivity } from "../ports/activity.port.js";
+import type { Sessions } from "../ports/sessions.port.js";
+import { TurnAdmission } from "../ports/turn-admission.port.js";
+type Service = Context.Service.Shape<typeof Sessions>;
+type Admission = Context.Service.Shape<typeof TurnAdmission>;
+/** One `Sessions` instance as the kit builds it. */
+export interface SessionsInstance {
+    readonly sessions: Service;
+    /** Its `TurnActivity` (the turns it has in flight), when it provides one: then checked against what it opens. */
+    readonly activity: Option.Option<Context.Service.Shape<typeof TurnActivity>>;
+}
+/** A process as the kit names one, for process ownership: its host, its pid and when it started. */
+export interface SessionsProcess {
+    readonly host: string;
+    readonly pid: number;
+    readonly startedAt: number;
+}
+/**
+ * A Sessions backend as the kit builds it. Every instance runs over the same
+ * store, as one per server would; the kit opens several at once, and uses
+ * fresh owners and session ids in every check, so the store may be shared.
+ */
+export interface SessionsSubject {
+    /**
+     * Another instance over the same store each time it runs, released with
+     * its scope, whose turns `admission` admits and which holds its turns by
+     * a lease of `ttlMs` of storage time from their begin, renewed by each of
+     * their writes and by nothing else (no keep-alive).
+     */
+    readonly leased: (options: {
+        readonly ttlMs: number;
+        readonly admission: Admission;
+    }) => Effect.Effect<SessionsInstance, unknown, Scope.Scope>;
+    /**
+     * The same, holding its turns for as long as the process that began them
+     * runs: the instance runs in `self`, and of the pids of its host only
+     * `running` run (the liveness check it asks). Leave it out for a backend
+     * without process ownership: the dead-holder check is then not run.
+     */
+    readonly processOwned?: (options: {
+        readonly self: SessionsProcess;
+        readonly running: ReadonlyArray<number>;
+        readonly admission: Admission;
+    }) => Effect.Effect<SessionsInstance, unknown, Scope.Scope>;
+    /** Move the clock the store and the instances read forward by `millis`: `TestClock.adjust`, or a sleep on a live clock. */
+    readonly advance: (millis: number) => Effect.Effect<void>;
+}
+/**
+ * The Sessions contract, as checks any backend must pass: sessions created,
+ * read only by their owner, listed in pages and forked; one open turn per
+ * session (`SessionBusy`, on any instance, and exactly one winner of a
+ * race); a key's retry is the same turn (`TurnDuplicate`, whatever the
+ * `meta`) and anything else under it a `KeyConflict`; `meta` stored,
+ * admitted and shown to the host's admission; the resume rules and every
+ * `NotResumable` reason; an image its bytes do not support refused with
+ * `AttachmentRejected` and an inbox turn with nothing to take with
+ * `NothingPending`, opening nothing; the writer storing in order and its
+ * end storing how the turn ended (completed, failed with a code, a scope
+ * closed unended or interrupted); writing outside a turn and the reserved
+ * kinds; cancel and removal closing the writer; the inbox (delivered once
+ * per id, taken by one inbox turn, waiting for the open turn, given back
+ * when its turn is interrupted from outside, done when its turn is
+ * cancelled); a turn whose lease ran out shown closed, left alone by a
+ * drain with nothing to take and reaped by the next begin; a write renewing
+ * the lease from that write; with `processOwned`, a turn whose process
+ * stopped reaped, and one whose process runs held; and, for an instance
+ * with a `TurnActivity`, its activity agreeing with what is open, per
+ * session and turn, a begin counting from the moment it is asked for (an
+ * instance without one passes that check unchecked).
+ *
+ * Checks that move the clock (`advance`) run leases of a second: give the
+ * kit a clock it can move at once (`TestClock`) or expect them to take
+ * seconds. Run each check under the clock `advance` moves.
+ */
+export declare const sessionsConformance: (subject: SessionsSubject) => ReadonlyArray<ConformanceCheck>;
+export {};