@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-node/src/coordinator/logStore.ts

@@ -0,0 +1,335 @@
+import { createWriteStream, mkdirSync, statSync, WriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+
+import { LogEntry } from "../types";
+
+/**
+ * Where a board's log lives on disk.
+ *
+ * One file per board, holding entries from every runtime it spans — that
+ * stitching is the whole reason the log is kept by the coordinator rather than
+ * by each runtime, which could only ever answer for its own slice.
+ *
+ * JSONL, one entry per line: it appends without rewriting what is already
+ * there, a crash mid-write costs the last line rather than the file, and it
+ * reads back a line at a time so serving a query never loads a long-running
+ * board's whole history into memory. A pretty-printed array would fail all
+ * three.
+ *
+ * Entries carry board data, so the files inherit the board store's posture:
+ * per-user directories, `0o700` on the directory and `0o600` on the file —
+ * the owner's to read, and nobody else's.
+ *
+ * Bounded by size rather than by age: what fills a disk is bytes, and a board
+ * ticking once a second and one that runs twice a day would need wildly
+ * different day counts to mean the same thing. When the live file passes the
+ * limit it is rolled aside and a new one started; past the kept count the
+ * oldest is deleted.
+ */
+export type LogStore = {
+  append(userId: string, boardName: string, entry: LogEntry): void;
+  /**
+   * Entries for one board, newest last, optionally narrowed.
+   *
+   * `fields` exists so a caller can ask for entries *without* their `data`:
+   * filtering after the fact would mean the payload had already crossed the
+   * wire, which is the thing the default-off `data` setting exists to prevent.
+   */
+  read(
+    userId: string,
+    boardName: string,
+    query?: {
+      runId?: string;
+      level?: LogEntry["level"];
+      since?: string;
+      limit?: number;
+      withData?: boolean;
+    },
+  ): Promise<LogEntry[]>;
+  remove(userId: string, boardName: string): Promise<void>;
+  close(): Promise<void>;
+};
+
+const LEVELS: Record<LogEntry["level"], number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/** Keeps a file name from escaping its directory or colliding across boards. */
+function safeName(value: string): string {
+  return encodeURIComponent(value);
+}
+
+export type LogStoreOptions = {
+  /** Roll the live file once it passes this many bytes. */
+  maxBytes?: number;
+  /** How many rolled files to keep beside the live one. */
+  keepFiles?: number;
+};
+
+/** 32 MB × 4 rolled ≈ 160 MB per board before the oldest entries are dropped. */
+const DEFAULT_MAX_BYTES = 32 * 1024 * 1024;
+const DEFAULT_KEEP_FILES = 4;
+
+/**
+ * How many entries a read returns when the caller does not say.
+ *
+ * A log is read from its end, and an unbounded default makes the whole file the
+ * easy answer — which is fine on a board that has just started and ruinous on
+ * one that has been running for a week.
+ */
+const DEFAULT_LIMIT = 500;
+/** Lines read per entry wanted, to absorb the ones a filter discards. */
+const OVER_READ = 4;
+
+/**
+ * The newest entries in a file, read backwards from its end.
+ *
+ * A limited read must not have to walk a long file to answer, and the newest
+ * entries are the ones a log is asked for — so this reads chunks from the end
+ * until it has enough lines, rather than reading forward and discarding almost
+ * all of it.
+ */
+async function tailLines(
+  handle: fs.FileHandle,
+  wanted: number,
+): Promise<string[]> {
+  const { size } = await handle.stat();
+  const chunk = 64 * 1024;
+  let position = size;
+  let carry = "";
+  const lines: string[] = [];
+
+  while (position > 0 && lines.length <= wanted) {
+    const length = Math.min(chunk, position);
+    position -= length;
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, position);
+    const text = buffer.toString("utf8") + carry;
+    const split = text.split("\n");
+    // The first piece may be half a line whose start is in the chunk before
+    // this one; carry it until that chunk is read (or the file begins).
+    carry = position > 0 ? (split.shift() ?? "") : "";
+    lines.unshift(...split);
+  }
+  if (carry) {
+    lines.unshift(carry);
+  }
+  return lines;
+}
+
+export function createFileLogStore(
+  root: string,
+  options: LogStoreOptions = {},
+): LogStore {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const keepFiles = options.keepFiles ?? DEFAULT_KEEP_FILES;
+  // One open stream per board, because a board writes entries continuously and
+  // reopening per entry would cost a syscall per line.
+  const streams = new Map<string, WriteStream>();
+  // Bytes in the live file, so a roll does not need a stat per entry.
+  const writtenBytes = new Map<string, number>();
+  // Rolls still running, kept as their promises rather than as a flag: a roll
+  // takes its stream out of `streams` before it starts renaming, so anything
+  // waiting for writes to settle would otherwise see nothing to wait for and
+  // return while the file was still being moved.
+  const rotations = new Map<string, Promise<void>>();
+
+  const dirFor = (userId: string) => path.join(root, safeName(userId));
+  const fileFor = (userId: string, boardName: string) =>
+    path.join(dirFor(userId), `${safeName(boardName)}.log.jsonl`);
+
+  function streamFor(userId: string, boardName: string): WriteStream {
+    const file = fileFor(userId, boardName);
+    const existing = streams.get(file);
+    if (existing) {
+      return existing;
+    }
+    // Synchronously, because the stream opens the file immediately: an awaited
+    // mkdir would still be pending when it did, the open would fail with
+    // ENOENT, and the entries written before the directory appeared would be
+    // lost with only a console error to show for it. This costs one syscall the
+    // first time a board logs, not one per entry.
+    mkdirSync(dirFor(userId), { recursive: true, mode: 0o700 });
+    // Seeded from what is already there: the stream appends, so a restart that
+    // started counting from zero would let the file grow past the limit by
+    // whatever it held before.
+    try {
+      writtenBytes.set(file, statSync(file).size);
+    } catch {
+      writtenBytes.set(file, 0);
+    }
+    const stream = createWriteStream(file, { flags: "a", mode: 0o600 });
+    stream.on("error", (err) => {
+      console.error(`[coordinator] Log write failed for "${boardName}":`, err);
+      streams.delete(file);
+    });
+    streams.set(file, stream);
+    return stream;
+  }
+
+  /**
+   * Rolls the live file aside once it is too big, dropping the oldest.
+   *
+   * `.1` is the most recent roll, so every kept file shifts up by one and
+   * whatever was at `keepFiles` falls off. Renames rather than copies, so a
+   * roll costs the same whatever the file holds.
+   */
+  async function rotate(userId: string, boardName: string): Promise<void> {
+    const file = fileFor(userId, boardName);
+    const stream = streams.get(file);
+    streams.delete(file);
+    await new Promise<void>((resolve) => {
+      if (!stream) {
+        resolve();
+        return;
+      }
+      stream.end(() => resolve());
+    });
+
+    await fs.rm(`${file}.${keepFiles}`, { force: true });
+    for (let index = keepFiles - 1; index >= 1; index -= 1) {
+      await fs
+        .rename(`${file}.${index}`, `${file}.${index + 1}`)
+        .catch(() => {});
+    }
+    await fs.rename(file, `${file}.1`).catch(() => {});
+  }
+
+  return {
+    append(userId, boardName, entry) {
+      const line = `${JSON.stringify(entry)}\n`;
+      const file = fileFor(userId, boardName);
+      // Opened first: opening is what seeds the count from a file that already
+      // exists, and reading the count before that would discard the seed.
+      const stream = streamFor(userId, boardName);
+      const written = (writtenBytes.get(file) ?? 0) + Buffer.byteLength(line);
+
+      stream.write(line);
+      writtenBytes.set(file, written);
+
+      if (written >= maxBytes && !rotations.has(file)) {
+        // One roll at a time per board: append is synchronous for the caller,
+        // so a second one arriving mid-roll must not start another.
+        const running = rotate(userId, boardName)
+          .catch((err) =>
+            console.error(
+              `[coordinator] Log rotation failed for "${boardName}":`,
+              err,
+            ),
+          )
+          .finally(() => {
+            writtenBytes.set(file, 0);
+            rotations.delete(file);
+          });
+        rotations.set(file, running);
+      }
+    },
+
+    async read(userId, boardName, query = {}) {
+      // Defaults to info: the flow is recorded at debug, and a caller who did
+      // not ask for it is asking what happened, not what ran. `level=debug`
+      // opens it up.
+      const minLevel = LEVELS[query.level ?? "info"];
+      const limit = query.limit && query.limit > 0 ? query.limit : DEFAULT_LIMIT;
+      // Over-read a little: a line may be filtered out, so the newest `limit`
+      // lines are not always the newest `limit` entries. Bounded either way,
+      // which is the point.
+      const wanted = limit * OVER_READ;
+
+      // Newest first — the live file, then the rolled ones behind it. A read
+      // has to span them: right after a roll the live file is empty (it is not
+      // even created until the next entry), and the entries somebody is asking
+      // for are all in `.1`.
+      const base = fileFor(userId, boardName);
+      const candidates = [
+        base,
+        ...Array.from({ length: keepFiles }, (_, index) => `${base}.${index + 1}`),
+      ];
+
+      const lines: string[] = [];
+      for (const candidate of candidates) {
+        if (lines.length >= wanted) {
+          break;
+        }
+        let handle;
+        try {
+          handle = await fs.open(candidate, "r");
+        } catch {
+          // A board that has not logged this far back has no such file, which
+          // is an empty stretch rather than an error.
+          continue;
+        }
+        try {
+          // Each file read is older than what is already collected, so it goes
+          // in front of it.
+          lines.unshift(...(await tailLines(handle, wanted - lines.length)));
+        } finally {
+          await handle.close();
+        }
+      }
+
+      const found: LogEntry[] = [];
+      for (const line of lines) {
+        if (!line) {
+          continue;
+        }
+        let entry: LogEntry;
+        try {
+          entry = JSON.parse(line) as LogEntry;
+        } catch {
+          // A torn line — the last one after a crash mid-write, or the first
+          // one when a read started mid-file. Either way the rest is still
+          // readable, which is why entries are one per line.
+          continue;
+        }
+        if (query.runId && entry.runId !== query.runId) {
+          continue;
+        }
+        if (LEVELS[entry.level] < minLevel) {
+          continue;
+        }
+        if (query.since && entry.ts <= query.since) {
+          continue;
+        }
+        if (!query.withData && entry.data !== undefined) {
+          const { data: _dropped, ...rest } = entry;
+          found.push(rest);
+        } else {
+          found.push(entry);
+        }
+      }
+
+      // Newest last is how the files read, so the newest `limit` are the tail.
+      return found.slice(-limit);
+    },
+
+    async remove(userId, boardName) {
+      const file = fileFor(userId, boardName);
+      // A roll in flight is about to rename this file into place behind it;
+      // deleting first would leave that rename to recreate what was removed.
+      await rotations.get(file);
+      streams.get(file)?.end();
+      streams.delete(file);
+      await fs.rm(file, { force: true });
+    },
+
+    async close() {
+      // Rolls first: each one ends its own stream and then renames, so a close
+      // that only ended the streams it can see would return with a file half
+      // moved — the state a coordinator would come back up on.
+      await Promise.all([...rotations.values()]);
+      await Promise.all(
+        [...streams.values()].map(
+          (stream) =>
+            new Promise<void>((resolve) => stream.end(() => resolve())),
+        ),
+      );
+      streams.clear();
+    },
+  };
+}

package/bundle/hkp-node/src/coordinator/members.ts

@@ -0,0 +1,133 @@
+import { normalizeEmail } from "../auth";
+import { Caller } from "../types";
+
+/**
+ * The people a deployed board is shared with.
+ *
+ * A board has one owner — the person who deployed it, in whose tenant its
+ * runtimes run and its data lives — and a list of members. Whoever is on the
+ * list may attach to the board and use its facade, and nothing else; the list
+ * *is* the membership.
+ *
+ * It is kept by the coordinator, beside the board and never in the board
+ * document: who a board is shared with is not part of what the board is, and a
+ * board that carried its own list would hand it to everyone it was exported
+ * to.
+ */
+
+export type BoardMember = {
+  /** A verified address, as `normalizeEmail` keeps one. The key of the list. */
+  email: string;
+  /**
+   * What the other members see this person called. The owner's to set: a name
+   * taken from the person's own token would let them appear as someone else.
+   */
+  name: string;
+};
+
+/** A board somebody else owns, as a member is told about it. */
+export type SharedBoardInfo = {
+  /** The owner's id: what a member names, with the board, to attach. */
+  owner: string;
+  boardName: string;
+  status: string;
+  /** What the board's list calls the person asking. */
+  name: string;
+};
+
+/** What a coordinator's operator allows of membership. */
+export type MemberLimits = {
+  /** How many people one board may be shared with. */
+  maxMembersPerBoard?: number;
+  /** How many bridges one member may hold on one board at once. */
+  maxBridgesPerMember?: number;
+  /** How many process calls a member may make on one board per minute. */
+  maxMemberProcessPerMinute?: number;
+  /** Longest a run may retain a person actor's authority. */
+  maxPersonRunAgeMs?: number;
+};
+
+export const DEFAULT_MEMBER_LIMITS: Required<MemberLimits> = {
+  maxMembersPerBoard: 200,
+  maxBridgesPerMember: 4,
+  maxMemberProcessPerMinute: 120,
+  maxPersonRunAgeMs: 15 * 60 * 1000,
+};
+
+/** Refused for being over a limit; carries what to tell the owner. */
+export class MemberLimitError extends Error {}
+
+const MAX_EMAIL_LENGTH = 254;
+const MAX_NAME_LENGTH = 80;
+
+/**
+ * A list entry from what a client sent, or null when it is not one.
+ *
+ * The address only has to look like one — it is compared with what an identity
+ * provider verified, so one that belongs to nobody simply admits nobody.
+ */
+export function readMember(value: unknown): BoardMember | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const { email, name } = value as Record<string, unknown>;
+  if (typeof email !== "string" || typeof name !== "string") {
+    return null;
+  }
+  const address = normalizeEmail(email);
+  const label = name.trim();
+  if (
+    !address ||
+    address.length > MAX_EMAIL_LENGTH ||
+    !/^[^\s@]+@[^\s@]+$/.test(address) ||
+    !label ||
+    label.length > MAX_NAME_LENGTH
+  ) {
+    return null;
+  }
+  return { email: address, name: label };
+}
+
+/** The entries of a stored list that are still well formed, one per email. */
+export function readMembers(value: unknown): BoardMember[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const byEmail = new Map<string, BoardMember>();
+  for (const entry of value) {
+    const member = readMember(entry);
+    if (member) {
+      byEmail.set(member.email, member);
+    }
+  }
+  return [...byEmail.values()];
+}
+
+/** The entry for an email, when the list has one. */
+export function findMember(
+  members: BoardMember[],
+  email: string | undefined,
+): BoardMember | undefined {
+  if (!email) {
+    return undefined;
+  }
+  const address = normalizeEmail(email);
+  return members.find((member) => member.email === address);
+}
+
+/**
+ * Whether a person's authority on a board is still live: they are its owner,
+ * or a current member who does not claim to be its owner. A run is checked
+ * again at every hop, and a role that changed hands in between would let a
+ * member's run set up what only the owner may.
+ */
+export function mayActOn(
+  owner: string,
+  members: BoardMember[],
+  caller: Caller,
+): boolean {
+  if (caller.sub === owner) {
+    return true;
+  }
+  return caller.role !== "owner" && !!findMember(members, caller.email);
+}

package/bundle/hkp-node/src/coordinator/mount.ts

@@ -0,0 +1,124 @@
+/**
+ * Mount vocabulary, for the coordinator side.
+ *
+ * A service that needs to be reachable from outside is assigned a path on its
+ * runtime's server and publishes the resulting address in its own state, in
+ * `__hkpMount`.
+ *
+ * A service that *consumes* a mount names the owner with a
+ * `hkp-mount://<runtimeId>/<serviceUuid>` reference, written in whatever field
+ * that service calls its target. References are found by their scheme, wherever
+ * they appear: a bare `<runtimeId>/<serviceUuid>` is not accepted, because it is
+ * indistinguishable from a relative URL.
+ *
+ * The coordinator resolves a reference and configures the consumer's
+ * `__hkpMount` with the address — never the field the reference was found in.
+ * One job each: the reference is what a person wrote and what the board keeps,
+ * the address is only true of this run.
+ *
+ * Resolving one form into the other needs a view of the whole board, which is
+ * the coordinator's job — see `session.ts`. This module is only the vocabulary,
+ * and mirrors `hkp-frontend/src/runtime/board/mount.ts`; the two must agree,
+ * since they read and write the same board.
+ */
+
+/** State field holding a mount address, on both the owner and the consumer. */
+export const MOUNT_FIELD = "__hkpMount";
+
+/** Scheme marking a value as a reference to a mount-owning service. */
+export const MOUNT_SCHEME = "hkp-mount://";
+
+export type MountRef = {
+  runtimeId: string;
+  serviceUuid: string;
+};
+
+/**
+ * Parses a `hkp-mount://<runtimeId>/<serviceUuid>` reference. Returns null for
+ * anything that is not one — an address, a blank, a legacy value — so callers
+ * can treat "not a reference" as "nothing to resolve".
+ *
+ * Split by hand rather than through `URL`, which would subject the runtime id
+ * to host syntax; both parts here are opaque board identifiers.
+ */
+export function parseMountRef(
+  value: string | null | undefined,
+): MountRef | null {
+  if (!value || !value.startsWith(MOUNT_SCHEME)) {
+    return null;
+  }
+  const target = value.slice(MOUNT_SCHEME.length);
+  const slash = target.indexOf("/");
+  if (slash <= 0 || slash === target.length - 1) {
+    return null;
+  }
+  return {
+    runtimeId: target.slice(0, slash),
+    serviceUuid: target.slice(slash + 1),
+  };
+}
+
+export function formatMountRef(ref: MountRef): string {
+  return `${MOUNT_SCHEME}${ref.runtimeId}/${ref.serviceUuid}`;
+}
+
+/**
+ * Every mount reference in a value, replaced by the address `resolve` returns
+ * for it — in whatever field held it. References that resolve to null are left
+ * untouched rather than blanked, so a service still describes what it wanted and
+ * can be resolved later, once its owner publishes.
+ *
+ * Used where a board is being handed somewhere that has no coordinator to ask
+ * (an export). Configuring a running consumer does *not* go through this: that
+ * writes the address to `__hkpMount` and leaves what the board says alone.
+ *
+ * Walks the whole value because services nest: a sub-service pipeline carries
+ * its own services, each with their own state.
+ */
+export function substituteMounts<T>(
+  value: T,
+  resolve: (ref: string) => string | null,
+): T {
+  if (typeof value === "string") {
+    return (parseMountRef(value) ? (resolve(value) ?? value) : value) as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteMounts(item, resolve)) as T;
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = substituteMounts(item, resolve);
+  }
+  return out as T;
+}
+
+/**
+ * Every mount reference in a value, as the references themselves, found by
+ * scheme wherever they appear. Used to find out which services a board wants
+ * pointed at a mount before any of them have been provisioned.
+ */
+export function collectMountRefs(value: unknown, into = new Set<string>()): Set<string> {
+  if (typeof value === "string") {
+    if (parseMountRef(value)) {
+      into.add(value);
+    }
+    return into;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectMountRefs(item, into);
+    }
+    return into;
+  }
+  if (!value || typeof value !== "object") {
+    return into;
+  }
+  for (const item of Object.values(value as Record<string, unknown>)) {
+    collectMountRefs(item, into);
+  }
+  return into;
+}