@boxxy/server 0.0.0-stage → 0.1.3

package/src/read-limited-request.ts

@@ -0,0 +1,43 @@
+import invariant from 'tiny-invariant';
+
+// The request with its body read whole, or null when the body is over `maxBytes`. It stops
+// reading at the first byte over the limit, so a streamed body with no length header cannot fill
+// the memory: Bun's own body limit lets such a body through.
+export async function readLimitedRequest(
+  request: Request,
+  maxBytes: number,
+): Promise<Request | null> {
+  if (Number(request.headers.get('content-length') ?? 0) > maxBytes) {
+    return null;
+  }
+
+  if (request.body === null) {
+    return request;
+  }
+
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  const reader = request.body.getReader();
+
+  for (let read = await reader.read(); !read.done; read = await reader.read()) {
+    const chunk: unknown = read.value;
+
+    invariant(chunk instanceof Uint8Array, 'a request body streams bytes');
+
+    total += chunk.byteLength;
+
+    if (total > maxBytes) {
+      await reader.cancel();
+
+      return null;
+    }
+
+    chunks.push(chunk);
+  }
+
+  return new Request(request.url, {
+    method: request.method,
+    headers: request.headers,
+    body: Buffer.concat(chunks),
+  });
+}

package/src/rules/create-rules-holder.ts

@@ -0,0 +1,107 @@
+import { hashTree } from '@boxxy/content-hash';
+import type { LoadRejection, LoadResult } from '@boxxy/model';
+import type { RulesState, ServerLog } from '../types.ts';
+import type { RulesCheckout } from './load-server-rules.ts';
+import { loadServerRules, makeProposedRulesLoader } from './load-server-rules.ts';
+import { readRulesCheckout } from './read-rules-checkout.ts';
+
+interface RulesHolder {
+  readonly state: () => RulesState;
+
+  // the dry run's load, beside the checkout the live rules came from
+  readonly loadProposed: (text: string) => LoadResult;
+
+  // the text of each file of the checkout the live rules came from, by its path, for the prompts
+  readonly texts: () => ReadonlyMap<string, string>;
+
+  // reads the checkout again, and loads it when it changed; a refused load keeps the rules
+  readonly reload: () => Promise<void>;
+}
+
+export type RulesHolderAnswer =
+  | { readonly kind: 'loaded'; readonly holder: RulesHolder }
+  | { readonly kind: 'rejected'; readonly reason: string }
+  | { readonly kind: 'refused'; readonly rejections: readonly LoadRejection[] };
+
+interface Held {
+  readonly state: RulesState;
+  readonly checkout: RulesCheckout;
+  readonly signature: string;
+}
+
+// Loads the rules folder once, and swaps the rules, their checkout and the last refusal together
+// on each reload, so a dry run never pairs new rules with an old checkout.
+export async function createRulesHolder(
+  folder: string,
+  log: ServerLog,
+): Promise<RulesHolderAnswer> {
+  const first = await readRulesCheckout(folder);
+
+  if (first.kind === 'rejected') {
+    return { kind: 'rejected', reason: first.reason };
+  }
+
+  const loaded = loadServerRules(first.checkout);
+
+  if (loaded.kind === 'rejected') {
+    return { kind: 'refused', rejections: loaded.rejections };
+  }
+
+  let held: Held = {
+    state: { rules: loaded.rules, lastRejected: null },
+    checkout: first.checkout,
+    signature: buildSignature(first.checkout),
+  };
+
+  const reload = async () => {
+    const read = await readRulesCheckout(folder);
+
+    if (read.kind === 'rejected') {
+      log.warn('the rules checkout could not be read; the rules stay', { reason: read.reason });
+
+      return;
+    }
+
+    const signature = buildSignature(read.checkout);
+
+    if (signature === held.signature) {
+      return;
+    }
+
+    const next = loadServerRules(read.checkout);
+
+    if (next.kind === 'rejected') {
+      log.warn('the rules load was refused; the rules stay', { commit: read.checkout.commit });
+
+      const lastRejected = { commit: read.checkout.commit, rejections: next.rejections };
+
+      held = { ...held, signature, state: { ...held.state, lastRejected } };
+
+      return;
+    }
+
+    held = { state: { rules: next.rules, lastRejected: null }, checkout: read.checkout, signature };
+  };
+
+  return {
+    kind: 'loaded',
+    holder: {
+      state: () => held.state,
+      loadProposed: (text) => makeProposedRulesLoader(held.checkout)(text),
+      texts: () => toTexts(held.checkout),
+      reload,
+    },
+  };
+}
+
+function buildSignature(checkout: RulesCheckout): string {
+  const files = [...checkout.files].map(([path, bytes]) => ({ path, bytes, executable: false }));
+
+  return `${checkout.commit}:${hashTree(files)}`;
+}
+
+function toTexts(checkout: RulesCheckout): ReadonlyMap<string, string> {
+  const decoder = new TextDecoder();
+
+  return new Map([...checkout.files].map(([path, bytes]) => [path, decoder.decode(bytes)]));
+}

package/src/rules/load-server-rules.ts

@@ -0,0 +1,24 @@
+import { phaseKinds } from '@boxxy/closeout';
+import type { LoadResult } from '@boxxy/model';
+import { conceptPins, concepts } from '@boxxy/planning';
+import { loadRules, rulesFileName } from '@boxxy/rules';
+
+export interface RulesCheckout {
+  // the commit of a git checkout, or `folder` for a plain folder
+  readonly commit: string;
+  readonly files: ReadonlyMap<string, Uint8Array>;
+}
+
+// Loads a checkout with the concepts and the phase kinds that this server registers.
+export function loadServerRules(checkout: RulesCheckout): LoadResult {
+  return loadRules({ checkout, concepts, pins: conceptPins, phases: phaseKinds });
+}
+
+// The dry run's load: the server's own checkout with the given text as its rules file.
+export function makeProposedRulesLoader(checkout: RulesCheckout): (text: string) => LoadResult {
+  return (text) =>
+    loadServerRules({
+      commit: checkout.commit,
+      files: new Map([...checkout.files, [rulesFileName, new TextEncoder().encode(text)]]),
+    });
+}

package/src/rules/read-rules-checkout.ts

@@ -0,0 +1,65 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { $ } from 'bun';
+import type { RulesCheckout } from './load-server-rules.ts';
+
+export type CheckoutAnswer =
+  | { readonly kind: 'read'; readonly checkout: RulesCheckout }
+  | { readonly kind: 'rejected'; readonly reason: string };
+
+// A git checkout gives its committed files at HEAD, and a checkout with uncommitted changes is
+// refused. A folder with no `.git` gives every file that is not hidden.
+export function readRulesCheckout(folder: string): Promise<CheckoutAnswer> {
+  return existsSync(path.join(folder, '.git')) ? readGitCheckout(folder) : readFolder(folder);
+}
+
+async function readGitCheckout(folder: string): Promise<CheckoutAnswer> {
+  const status = await $`git -C ${folder} status --porcelain`.quiet().nothrow();
+
+  if (status.exitCode !== 0) {
+    return { kind: 'rejected', reason: `git could not read ${folder}` };
+  }
+
+  if (status.text().trim() !== '') {
+    return { kind: 'rejected', reason: 'the rules checkout has uncommitted changes' };
+  }
+
+  const commit = await $`git -C ${folder} rev-parse HEAD`.quiet().text();
+  const listed = await $`git -C ${folder} ls-files -z`.quiet().text();
+
+  const paths = listed.split('\0').filter((entry) => entry !== '');
+
+  const files = await readFiles(folder, paths);
+
+  return { kind: 'read', checkout: { commit: commit.trim(), files } };
+}
+
+async function readFiles(
+  folder: string,
+  paths: readonly string[],
+): Promise<ReadonlyMap<string, Uint8Array>> {
+  const entries = await Promise.all(
+    paths.toSorted().map(async (file): Promise<[string, Uint8Array]> => {
+      const bytes = await Bun.file(path.join(folder, file)).bytes();
+
+      return [file, bytes];
+    }),
+  );
+
+  return new Map(entries);
+}
+
+// The commit of a checkout that is a plain folder. Its rules version is still the content hash
+// of its files.
+const folderCommit = 'folder';
+
+async function readFolder(folder: string): Promise<CheckoutAnswer> {
+  if (!existsSync(folder)) {
+    return { kind: 'rejected', reason: `no rules folder at ${folder}` };
+  }
+
+  const paths = await Array.fromAsync(new Bun.Glob('**/*').scan({ cwd: folder, dot: false }));
+  const files = await readFiles(folder, paths);
+
+  return { kind: 'read', checkout: { commit: folderCommit, files } };
+}

package/src/serve-api.ts

@@ -0,0 +1,178 @@
+import type { ProcedureName } from '@boxxy/contract';
+import { access } from '@boxxy/contract';
+import { McpServer, createMcpHandler } from '@modelcontextprotocol/server';
+import { McpRegistrar } from '@orpc/mcp';
+import { COMMON_ERROR_STATUS_MAP } from '@orpc/server';
+import { RPCHandler } from '@orpc/server/fetch';
+import { Elysia } from 'elysia';
+import invariant from 'tiny-invariant';
+import { isBrowserRequest } from './auth/is-browser-request.ts';
+import { pickRequestScope } from './auth/pick-request-scope.ts';
+import { api } from './handlers/api.ts';
+import { attemptHandlers } from './handlers/attempt-handlers.ts';
+import { itemHandlers } from './handlers/item-handlers.ts';
+import { outboxHandlers } from './handlers/outbox-handlers.ts';
+import { planHandlers } from './handlers/plan-handlers.ts';
+import { relationHandlers } from './handlers/relation-handlers.ts';
+import { reportHandlers } from './handlers/report-handlers.ts';
+import { rulesHandlers } from './handlers/rules-handlers.ts';
+import { runnerHandlers } from './handlers/runner-handlers.ts';
+import { readLimitedRequest } from './read-limited-request.ts';
+import type { Listener, RequestContext, ServerDeps } from './types.ts';
+
+// the route refuses a larger request body (rule 5 of the contract)
+export const maxRequestBytes = 256 * 1024;
+
+// `owner`: the owner's private network, with `/rpc`, `/mcp` and `/healthz`. `worker`: the
+// broker's target, with `/rpc` and `/mcp/session`, and the worker token on every request.
+export type ApiListeners = ReturnType<typeof serveApi>;
+
+const router = api.router({
+  item: itemHandlers,
+  relation: relationHandlers,
+  attempt: attemptHandlers,
+  plan: planHandlers,
+  runner: runnerHandlers,
+  outbox: outboxHandlers,
+  rules: rulesHandlers,
+  report: reportHandlers,
+});
+
+// In oRPC v2 a typed error's HTTP status comes from this map alone; a code not in it answers 400.
+const rpc = new RPCHandler(router, {
+  errorStatusMap: {
+    ...COMMON_ERROR_STATUS_MAP,
+    PEPYS_UNAVAILABLE: 503,
+    PEPYS_NOT_CONFIGURED: 501,
+    UNKNOWN_PHASE: 422,
+  },
+});
+
+const ownerTools = new McpRegistrar(router, {
+  filter: (_procedure, path) => getAccess(path).tool === 'owner',
+});
+
+const sessionTools = new McpRegistrar(router, {
+  filter: (_procedure, path) => getAccess(path).tool === 'session',
+});
+
+// One router behind three doors on two listeners. Every request picks its scope from its
+// listener and its bearer token before any procedure runs; the root middleware of the router
+// then checks the access table for each call.
+export function serveApi(deps: ServerDeps) {
+  const ownerMcp = makeMcpDoor(deps, 'owner', ownerTools, 'boxxy');
+  const sessionMcp = makeMcpDoor(deps, 'worker', sessionTools, 'boxxy-session');
+
+  const owner = new Elysia()
+    .get('/healthz', { parse: 'none' }, (route) =>
+      handleDoor(deps, 'owner', route.request, () => Promise.resolve(new Response('ok'))),
+    )
+    .all('/rpc/*', { parse: 'none' }, (route) =>
+      handleDoor(deps, 'owner', route.request, (request) => handleRPC(deps, 'owner', request)),
+    )
+    .all('/mcp', { parse: 'none' }, (route) => handleDoor(deps, 'owner', route.request, ownerMcp));
+
+  const worker = new Elysia()
+    .all('/rpc/*', { parse: 'none' }, (route) =>
+      handleDoor(deps, 'worker', route.request, (request) => handleRPC(deps, 'worker', request)),
+    )
+    .all('/mcp/session', { parse: 'none' }, (route) =>
+      handleDoor(deps, 'worker', route.request, sessionMcp),
+    )
+
+    // the token check also guards a path the listener does not serve, so a caller with no token
+    // learns nothing of the routes
+    .all('*', { parse: 'none' }, (route) =>
+      handleDoor(deps, 'worker', route.request, () => Promise.resolve(answerNotFound())),
+    );
+
+  return { owner, worker };
+}
+
+function makeMcpDoor(
+  deps: ServerDeps,
+  listener: Listener,
+  registrar: McpRegistrar<typeof router>,
+  name: string,
+) {
+  // one MCP server per request, so the endpoint keeps no session and each call has its request
+  const handler = createMcpHandler(async (extra) => {
+    const requestInfo = extra.requestInfo;
+
+    invariant(requestInfo !== undefined, 'an HTTP request reaches the MCP door');
+
+    const server = new McpServer({ name, version: '1.0.0' });
+
+    await registrar.register(server, { context: buildContext(deps, listener, requestInfo) });
+
+    return server;
+  });
+
+  return (request: Request) => handler.fetch(request);
+}
+
+// The door checked the token already; this reads the same scope for the router's context.
+function buildContext(deps: ServerDeps, listener: Listener, request: Request): RequestContext {
+  const scope = pickRequestScope({
+    listener,
+    authorization: request.headers.get('authorization'),
+    workerTokenDigest: deps.workerTokenDigest,
+  });
+
+  invariant(scope !== null, 'the door refuses a request with no scope');
+
+  return { deps, scope, request };
+}
+
+function getAccess(path: readonly string[]) {
+  const name = path.join('.');
+
+  invariant(isProcedureName(name), `the router serves only contract procedures: ${name}`);
+
+  return access[name];
+}
+
+function isProcedureName(name: string): name is ProcedureName {
+  return Object.hasOwn(access, name);
+}
+
+// The checks of the HTTP request itself: its bearer token, that no browser page sent it, then its
+// size. A refusal names nothing of the token.
+async function handleDoor(
+  deps: ServerDeps,
+  listener: Listener,
+  request: Request,
+  serve: (request: Request) => Promise<Response>,
+): Promise<Response> {
+  const scope = pickRequestScope({
+    listener,
+    authorization: request.headers.get('authorization'),
+    workerTokenDigest: deps.workerTokenDigest,
+  });
+
+  if (scope === null) {
+    return Response.json({ error: 'unauthorized' }, { status: 401 });
+  }
+
+  if (isBrowserRequest(request.headers)) {
+    return Response.json({ error: 'forbidden' }, { status: 403 });
+  }
+
+  const limited = await readLimitedRequest(request, maxRequestBytes);
+
+  return limited === null
+    ? Response.json({ error: 'request body too large' }, { status: 413 })
+    : serve(limited);
+}
+
+async function handleRPC(deps: ServerDeps, listener: Listener, request: Request) {
+  const context = buildContext(deps, listener, request);
+
+  const handled = await rpc.handle(request, { prefix: '/rpc', context });
+
+  return handled.response ?? answerNotFound();
+}
+
+function answerNotFound(): Response {
+  return Response.json({ error: 'not found' }, { status: 404 });
+}