@boxxy/server 0.0.1 → 0.1.4

package/src/handlers/relation-handlers.ts

@@ -0,0 +1,143 @@
+import type { ItemId, RelationRow, RelationTypeName } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import { api } from './api.ts';
+import { buildOwnerFact } from './build-owner-fact.ts';
+import { readItemIds } from './read-item-ids.ts';
+
+// The owner's relation commands. A refusal that the owner acts on is an answer, not an error.
+export const relationHandlers = {
+  add: api.relation.add.handler((options) => {
+    const input = options.input;
+    const notFound = options.errors.NOT_FOUND;
+    const deps = options.context.deps;
+    const rules = deps.rulesState().rules;
+
+    return deps.store.exclusive(async (tx) => {
+      const found = await readItemIds(tx, deps, [input.source, input.target]);
+
+      if (found.kind === 'not-found') {
+        throw notFound({ data: { item: found.item } });
+      }
+
+      const [source, target] = found.items;
+      const type = brandSchemas.relationTypeName.safeParse(input.type);
+
+      if (source === undefined || target === undefined) {
+        throw notFound({ data: { item: input.source } });
+      }
+
+      if (!type.success || !rules.relationTypes.has(type.data)) {
+        return { kind: 'refused', reason: 'unknown-type' } as const;
+      }
+
+      const now = deps.clock.now();
+
+      const snapshot = await tx.readSnapshot(now, rules);
+
+      const refusal = pickRelationRefusal(snapshot.relations, source, target, type.data);
+
+      if (refusal !== null) {
+        return { kind: 'refused', reason: refusal } as const;
+      }
+
+      const row: RelationRow = {
+        source,
+        target,
+        type: type.data,
+        addedBy: 'boxxy:owner:local',
+        addedAt: now,
+        removedAt: null,
+      };
+
+      await tx.applyChange({
+        at: now,
+        writes: [{ op: 'insert', table: 'relations', row }],
+        facts: [
+          buildOwnerFact(deps, source, 'boxxy.relation.added', { source, target, type: type.data }),
+        ],
+      });
+
+      return { kind: 'added' } as const;
+    });
+  }),
+  remove: api.relation.remove.handler((options) => {
+    const input = options.input;
+    const notFound = options.errors.NOT_FOUND;
+    const deps = options.context.deps;
+
+    return deps.store.exclusive(async (tx) => {
+      const found = await readItemIds(tx, deps, [input.source, input.target]);
+
+      if (found.kind === 'not-found') {
+        throw notFound({ data: { item: found.item } });
+      }
+
+      const now = deps.clock.now();
+
+      const snapshot = await tx.readSnapshot(now, deps.rulesState().rules);
+
+      const live = snapshot.relations.find(
+        (row) =>
+          row.source === input.source && row.target === input.target && row.type === input.type,
+      );
+
+      if (live === undefined) {
+        return { removed: false };
+      }
+
+      const key = { source: live.source, target: live.target, type: live.type };
+
+      await tx.applyChange({
+        at: now,
+        writes: [
+          {
+            op: 'update',
+            table: 'relations',
+            key,
+            expect: { removedAt: null },
+            set: { removedAt: now },
+          },
+        ],
+        facts: [buildOwnerFact(deps, live.source, 'boxxy.relation.removed', key)],
+      });
+
+      return { removed: true };
+    });
+  }),
+};
+
+// `exists`: the same live relation is there. `cycle`: the target already reaches the source
+// through relations of the type, so the new one would close a loop.
+function pickRelationRefusal(
+  relations: readonly RelationRow[],
+  source: ItemId,
+  target: ItemId,
+  type: RelationTypeName,
+): 'exists' | 'cycle' | null {
+  const ofType = relations.filter((row) => row.type === type);
+
+  if (ofType.some((row) => row.source === source && row.target === target)) {
+    return 'exists';
+  }
+
+  return isReachable(ofType, target, source) ? 'cycle' : null;
+}
+
+function isReachable(relations: readonly RelationRow[], from: ItemId, to: ItemId): boolean {
+  const seen = new Set<ItemId>();
+
+  const queue: ItemId[] = [from];
+
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    if (next === to) {
+      return true;
+    }
+
+    if (!seen.has(next)) {
+      seen.add(next);
+      queue.push(...relations.filter((row) => row.source === next).map((row) => row.target));
+    }
+  }
+
+  return false;
+}

package/src/handlers/report-handlers.ts

@@ -0,0 +1,112 @@
+import type { ItemId, PepysAnswer, PepysReader } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { ServerDeps } from '../types.ts';
+import { api } from './api.ts';
+
+// The two reads of pepys. A server with no pepys section answers PEPYS_NOT_CONFIGURED; a pepys
+// that does not answer is PEPYS_UNAVAILABLE. `behind` counts the item's facts that the outbox has
+// not sent, from boxxy's own store.
+export const reportHandlers = {
+  cost: api.report.cost.handler(async (options) => {
+    const item = options.input.item;
+
+    const report = await readReport(options.context.deps, item, (pepys, id) =>
+      pepys.readCostToLand(id),
+    );
+
+    return report.kind === 'value'
+      ? { ...report.value, item, behind: report.behind }
+      : throwReportError(report, options.errors, item);
+  }),
+  stageTimes: api.report.stageTimes.handler(async (options) => {
+    const item = options.input.item;
+
+    const report = await readReport(options.context.deps, item, (pepys, id) =>
+      pepys.readStageTime(id),
+    );
+
+    return report.kind === 'value'
+      ? { ...report.value, item, behind: report.behind }
+      : throwReportError(report, options.errors, item);
+  }),
+};
+
+type Report<Value> =
+  | {
+      readonly kind: 'value';
+      readonly value: Value;
+      readonly behind: { readonly facts: number; readonly oldestAt: number | null };
+    }
+  | { readonly kind: 'not-found' }
+  | { readonly kind: 'not-configured' }
+  | { readonly kind: 'unavailable'; readonly reason: string };
+
+async function readReport<Value>(
+  deps: ServerDeps,
+  rawItem: string,
+  read: (pepys: PepysReader, item: ItemId) => Promise<PepysAnswer<Value>>,
+): Promise<Report<Value>> {
+  const parsed = brandSchemas.itemId.safeParse(rawItem);
+
+  if (!parsed.success) {
+    return { kind: 'not-found' };
+  }
+
+  const item = parsed.data;
+  const now = deps.clock.now();
+  const rules = deps.rulesState().rules;
+
+  const [view, behind] = await deps.store.read((tx) =>
+    Promise.all([tx.readItem(item, now, rules), tx.readItemBehind(item)]),
+  );
+
+  if (view === null) {
+    return { kind: 'not-found' };
+  }
+
+  if (deps.pepys === null) {
+    return { kind: 'not-configured' };
+  }
+
+  const answer = await read(deps.pepys, item);
+
+  return answer.kind === 'value'
+    ? { kind: 'value', value: answer.value, behind }
+    : { kind: 'unavailable', reason: answer.reason };
+}
+
+interface NotFoundOptions {
+  readonly data: { readonly item: string };
+}
+
+interface UnavailableOptions {
+  readonly data: { readonly reason: string };
+}
+
+interface ReportErrors {
+  readonly NOT_FOUND: (options: NotFoundOptions) => Error;
+  readonly PEPYS_NOT_CONFIGURED: () => Error;
+  readonly PEPYS_UNAVAILABLE: (options: UnavailableOptions) => Error;
+}
+
+// The contract's error constructors carry the contract's message, which a bare `ORPCError` would
+// drop; a lowercase name keeps the call clear of the `new-cap` lint.
+function throwReportError(
+  report: Exclude<Report<unknown>, { kind: 'value' }>,
+  errors: ReportErrors,
+  item: string,
+): never {
+  const notFound = errors.NOT_FOUND;
+  const notConfigured = errors.PEPYS_NOT_CONFIGURED;
+  const unavailable = errors.PEPYS_UNAVAILABLE;
+
+  if (report.kind === 'not-found') {
+    throw notFound({ data: { item } });
+  }
+
+  if (report.kind === 'not-configured') {
+    throw notConfigured();
+  }
+
+  throw unavailable({ data: { reason: report.reason } });
+}

package/src/handlers/rules-handlers.ts

@@ -0,0 +1,46 @@
+import { collectRetries, collectSettled } from '@boxxy/model';
+import { dryRunRules } from '@boxxy/rules';
+import { api } from './api.ts';
+
+// The rules dry run loads the given rules file in place of the server's own, beside the server's
+// prompts, and folds each open item under both rules sets. It writes nothing.
+export const rulesHandlers = {
+  dryRun: api.rules.dryRun.handler(async (options) => {
+    const deps = options.context.deps;
+    const proposed = deps.loadProposedRules(options.input.rules);
+
+    if (proposed.kind === 'rejected') {
+      return { kind: 'rejected', rejections: [...proposed.rejections] } as const;
+    }
+
+    const current = deps.rulesState().rules;
+    const now = deps.clock.now();
+
+    const items = await deps.store.read(async (tx) => {
+      const open = await tx.listItems({}, now, current);
+
+      return Promise.all(
+        open
+          .filter((item) => item.closedAt === null)
+          .map(async (item) => {
+            const attempts = await tx.listItemAttempts(item.id);
+
+            return {
+              item,
+              attempts: collectSettled(attempts),
+              retries: collectRetries(item.levers),
+            };
+          }),
+      );
+    });
+
+    const lines = dryRunRules({ current, proposed: proposed.rules, items });
+
+    return {
+      kind: 'loaded',
+      version: proposed.rules.version,
+      moved: lines.filter((line) => line.moved).length,
+      items: lines,
+    } as const;
+  }),
+};

package/src/handlers/runner-handlers.ts

@@ -0,0 +1,117 @@
+import { findWaitingSince, noticeLimits, timeouts } from '@boxxy/dispatch';
+import type { AttemptRow, Instant, RowWrite, RunnerRow } from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { ServerDeps } from '../types.ts';
+import { api } from './api.ts';
+
+const hourMs = 3_600_000;
+
+// The runner's status, and its two switches. A switch writes the runner's row and no fact: the
+// fact catalog has no runner fact.
+export const runnerHandlers = {
+  status: api.runner.status.handler(async (options) => {
+    const deps = options.context.deps;
+    const state = deps.rulesState();
+    const now = deps.clock.now();
+    const since = now - timeouts.strayHours * hourMs;
+
+    const read = await deps.store.read(async (tx) => {
+      const live = await tx.listLiveAttempts();
+
+      return {
+        runner: await tx.readRunner(deps.runner),
+        limits: await tx.listLimits(),
+        attempts: await Promise.all(
+          live.map(async (attempt) => {
+            const item = await tx.readItem(attempt.item, now, state.rules);
+
+            return { attempt, title: item?.title ?? '' };
+          }),
+        ),
+        strays: await tx.listStrayAttempts(brandSchemas.instant.parse(Math.max(0, since))),
+        notices: await tx.listUnsentNotices(noticeLimits.readRows),
+      };
+    });
+
+    const outbox = await deps.outbox.status();
+
+    return {
+      paused: read.runner?.paused ?? false,
+      limits: read.limits,
+      attempts: read.attempts.map((entry) => ({
+        ...entry,
+        waitingSince: findAttemptWaitingSince(deps, entry.attempt),
+      })),
+      strays: read.strays,
+      notices: { unsent: read.notices.length },
+      outbox,
+      rules: {
+        version: state.rules.version,
+        commit: state.rules.commit,
+        lastRejected:
+          state.lastRejected === null
+            ? null
+            : { ...state.lastRejected, rejections: [...state.lastRejected.rejections] },
+      },
+    };
+  }),
+  pause: api.runner.pause.handler(async (options) => {
+    await writePaused(options.context.deps, true);
+
+    return { paused: true } as const;
+  }),
+  resume: api.runner.resume.handler(async (options) => {
+    await writePaused(options.context.deps, false);
+
+    return { paused: false } as const;
+  }),
+};
+
+function findAttemptWaitingSince(deps: ServerDeps, attempt: AttemptRow) {
+  const reading = deps.readings.get(attempt.id);
+
+  return reading === undefined
+    ? null
+    : findWaitingSince({
+        attempt,
+        reading,
+        quietAfterMinutes: deps.rulesState().rules.sleep.afterQuietMinutes,
+        now: deps.clock.now(),
+      });
+}
+
+function writePaused(deps: ServerDeps, paused: boolean) {
+  return deps.store.exclusive(async (tx) => {
+    const now = deps.clock.now();
+
+    const row = await tx.readRunner(deps.runner);
+
+    const write = pickPausedWrite(row, deps, paused, now);
+
+    if (write !== null) {
+      await tx.applyChange({ at: now, writes: [write], facts: [] });
+    }
+  });
+}
+
+// the runner's row before its first heartbeat is inserted, so a pause holds from the start
+function pickPausedWrite(
+  row: RunnerRow | null,
+  deps: ServerDeps,
+  paused: boolean,
+  now: Instant,
+): RowWrite | null {
+  if (row === null) {
+    return { op: 'insert', table: 'runners', row: { id: deps.runner, heartbeatAt: now, paused } };
+  }
+
+  return row.paused === paused
+    ? null
+    : {
+        op: 'update',
+        table: 'runners',
+        key: { id: deps.runner },
+        expect: { paused: !paused },
+        set: { paused },
+      };
+}

package/src/handlers/to-wire-json.ts

@@ -0,0 +1,20 @@
+import type { JsonValue } from '@boxxy/model';
+
+// the JSON type of the contract's `z.json()` fields, whose arrays and records are mutable
+export type WireJSON = null | boolean | number | string | WireJSON[] | { [key: string]: WireJSON };
+
+export function toWireJSON(value: JsonValue): WireJSON {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+
+  if (isJsonArray(value)) {
+    return value.map((entry) => toWireJSON(entry));
+  }
+
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, toWireJSON(entry)]));
+}
+
+function isJsonArray(value: JsonValue): value is readonly JsonValue[] {
+  return Array.isArray(value);
+}

package/src/handlers/write-levers.ts

@@ -0,0 +1,53 @@
+import type { ItemId, LeverRow, StoreTx } from '@boxxy/model';
+import type { ServerDeps } from '../types.ts';
+import { buildOwnerFact } from './build-owner-fact.ts';
+import { readItemIds } from './read-item-ids.ts';
+
+export type LeverDraft = Pick<LeverRow, 'kind' | 'until' | 'expiresAt' | 'reason' | 'phase'>;
+
+export type LeverAnswer =
+  | { readonly kind: 'recorded'; readonly levers: readonly number[] }
+  | { readonly kind: 'not-found'; readonly item: string };
+
+// Records one lever per item, in one change with one `boxxy.lever.recorded` each. The store
+// numbers the levers; the answer reads the numbers back in the same lock.
+export function writeLevers(
+  deps: ServerDeps,
+  items: readonly string[],
+  draft: LeverDraft,
+): Promise<LeverAnswer> {
+  return deps.store.exclusive(async (tx) => {
+    const now = deps.clock.now();
+
+    const found = await readItemIds(tx, deps, items);
+
+    if (found.kind === 'not-found') {
+      return found;
+    }
+
+    const rows = found.items.map((item): LeverRow => ({
+      ...draft,
+      seq: 0,
+      item,
+      actor: 'boxxy:owner:local',
+      at: now,
+    }));
+
+    await tx.applyChange({
+      at: now,
+      writes: rows.map((row) => ({ op: 'insert', table: 'levers', row }) as const),
+      facts: rows.map((row) => buildOwnerFact(deps, row.item, 'boxxy.lever.recorded', row)),
+    });
+
+    const levers = await Promise.all(found.items.map((item) => readLastLeverSeq(tx, deps, item)));
+
+    return { kind: 'recorded', levers };
+  });
+}
+
+// The item's newest lever is the one this change wrote: the lock holds every other writer off.
+async function readLastLeverSeq(tx: StoreTx, deps: ServerDeps, item: ItemId): Promise<number> {
+  const detail = await tx.readItemDetail(item, deps.clock.now(), deps.rulesState().rules);
+
+  return Math.max(0, ...(detail?.item.levers.map((lever) => lever.seq) ?? []));
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { serverConfigSchema } from './config/server-config-schema.ts';
+export type { ServerConfig } from './config/server-config-schema.ts';
+export { noCallerProof } from './no-caller-proof.ts';
+export { loadServerRules } from './rules/load-server-rules.ts';
+export type { RulesCheckout } from './rules/load-server-rules.ts';
+export { readRulesCheckout } from './rules/read-rules-checkout.ts';
+export type { CheckoutAnswer } from './rules/read-rules-checkout.ts';
+export { serveApi } from './serve-api.ts';
+export type { ApiListeners } from './serve-api.ts';
+export { startServer } from './start-server.ts';
+export type { RunningServer, StartAnswer, StartServerInput } from './start-server.ts';
+export type { ServerDeps, ServerLog } from './types.ts';

package/src/main.ts

@@ -0,0 +1,31 @@
+import type { RunningServer } from './start-server.ts';
+import { startServer } from './start-server.ts';
+
+// The server's entry: `bun apps/server/src/main.ts`. It exits 1 when the server cannot start.
+const answer = await startServer({
+  env: process.env,
+  log: {
+    warn: (message, fields) => {
+      console.warn(JSON.stringify({ level: 'warn', message, ...fields }));
+    },
+  },
+});
+
+if (answer.kind === 'refused') {
+  console.error(answer.message);
+  process.exit(1);
+}
+
+const server = answer.server;
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.once(signal, () => {
+    void stopAndExit(server);
+  });
+}
+
+async function stopAndExit(running: RunningServer): Promise<void> {
+  await running.stop();
+
+  process.exit(0);
+}

package/src/no-caller-proof.ts

@@ -0,0 +1,7 @@
+import type { CallerProof } from '@boxxy/model';
+
+// The server's proof when its configuration names no trusted issuer: it proves no request, so
+// every session and hook call is refused.
+export const noCallerProof: CallerProof = {
+  prove: () => Promise.resolve(null),
+};

package/src/outbox/create-off-outbox.ts

@@ -0,0 +1,21 @@
+import { buildInitialSenderState, buildOutboxStatus } from '@boxxy/dispatch';
+import type { ClaimStore, Clock } from '@boxxy/model';
+import type { OutboxControl } from '../types.ts';
+
+// The outbox of a server with no pepys section: the facts wait in the store, the status says
+// `off`, and a nudge has no sender to wake.
+export function createOffOutbox(store: ClaimStore, clock: Clock): OutboxControl {
+  return {
+    status: async () =>
+      buildOutboxStatus({
+        sink: 'none',
+        state: buildInitialSenderState(),
+        counts: await store.read((tx) => tx.readOutboxCounts()),
+        now: clock.now(),
+        isSending: false,
+      }),
+    nudge: () => {
+      // no sender runs, so the facts wait in the store
+    },
+  };
+}

package/src/outbox/start-outbox-sender.ts

@@ -0,0 +1,89 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { buildInitialSenderState, buildOutboxStatus, runSenderOnce } from '@boxxy/dispatch';
+import type { SenderDeps, SenderState, SenderTurn } from '@boxxy/dispatch';
+import { match } from 'ts-pattern';
+import type { OutboxControl, ServerLog } from '../types.ts';
+
+export interface OutboxSenderInput extends SenderDeps {
+  // the wait after a turn that found nothing to send
+  readonly idleMs: number;
+  readonly log: ServerLog;
+}
+
+export interface OutboxSender extends OutboxControl {
+  // ends the loop after the turn in flight
+  readonly stop: () => Promise<void>;
+}
+
+// The timer around the sender's turns. It waits as the last turn says, and a nudge, as after
+// `outbox.retry`, ends the wait early. A turn that throws is logged, and the loop waits `idleMs`.
+export function startOutboxSender(input: OutboxSenderInput): OutboxSender {
+  let state: SenderState = buildInitialSenderState();
+  let isSending = false;
+
+  // set by `stop`, which runs outside the loop
+  const run = { isStopped: false };
+
+  let wake = new AbortController();
+
+  const runLoop = async (): Promise<void> => {
+    while (!run.isStopped) {
+      const waitMs = await runTurn();
+
+      if (waitMs > 0 && !run.isStopped) {
+        await sleep(waitMs, null, { signal: wake.signal }).catch(() => null);
+      }
+
+      wake = wake.signal.aborted ? new AbortController() : wake;
+    }
+  };
+
+  const runTurn = async (): Promise<number> => {
+    isSending = true;
+
+    try {
+      const turn = await runSenderOnce(input, state);
+
+      state = turn.state;
+
+      return pickWaitMs(turn, input.clock.now(), input.idleMs);
+    } catch (error) {
+      input.log.warn('the outbox sender turn failed', { error: String(error) });
+
+      return input.idleMs;
+    } finally {
+      isSending = false;
+    }
+  };
+
+  const loop = runLoop();
+
+  return {
+    status: async () =>
+      buildOutboxStatus({
+        sink: 'pepys',
+        state,
+        counts: await input.store.read((tx) => tx.readOutboxCounts()),
+        now: input.clock.now(),
+        isSending,
+      }),
+    nudge: () => {
+      wake.abort();
+    },
+    stop: async () => {
+      run.isStopped = true;
+
+      wake.abort();
+
+      await loop;
+    },
+  };
+}
+
+function pickWaitMs(turn: SenderTurn, now: number, idleMs: number): number {
+  return match(turn.step)
+    .with('stored', 'split', 'parked', () => 0)
+    .with('idle', () => idleMs)
+    .with('retry', 'blocked', () => Math.max(0, (turn.state.nextTryAt ?? now) - now))
+    .exhaustive();
+}