@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/fleet/rooms/room-lock.js

@@ -0,0 +1,180 @@
+/**
+ * Fleet rooms — exclusive single-writer lock for one ledger directory.
+ *
+ * Two `buddy server` processes commonly share one HOME. Without a lock both
+ * would hand out the same `seq` and one compaction would erase the other's
+ * appends. The lock is a `writer.lock` file created with `O_CREAT|O_EXCL`
+ * holding `{ pid, hostname, token }`.
+ *
+ * Recovery is deliberately narrow: a lock is reclaimed only when it names THIS
+ * host and a pid that no longer exists (`ESRCH`). A live pid (even a reused
+ * one), another host, `EPERM` or an unreadable/corrupt lock file all fail
+ * closed with {@link RoomLockError}; the operator removes the file by hand.
+ *
+ * @module fleet/rooms/room-lock
+ */
+import { randomBytes } from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const LOCK_FILE = 'writer.lock';
+const RECOVERY_LOCK_FILE = 'writer.lock.recovery';
+export class RoomLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RoomLockError';
+    }
+}
+function readLock(lockPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        if (parsed.version === 1 && Number.isSafeInteger(parsed.pid) && parsed.pid > 0 &&
+            typeof parsed.hostname === 'string' && typeof parsed.token === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // unreadable or corrupt: caller fails closed
+    }
+    return undefined;
+}
+function pidIsGone(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+export class RoomDirectoryLock {
+    lockPath;
+    recoveryLockPath;
+    token = randomBytes(16).toString('hex');
+    released = false;
+    constructor(directory) {
+        this.lockPath = path.join(directory, LOCK_FILE);
+        this.recoveryLockPath = path.join(directory, RECOVERY_LOCK_FILE);
+    }
+    /** Acquire the lock or throw {@link RoomLockError}. */
+    static acquire(directory) {
+        const lock = new RoomDirectoryLock(directory);
+        if (fs.existsSync(lock.recoveryLockPath)) {
+            throw new RoomLockError(`room ledger recovery lock ${lock.recoveryLockPath} remains; refusing automatic recovery (remove it manually only if no server uses this directory)`);
+        }
+        if (lock.tryCreate())
+            return lock;
+        if (!lock.tryCreateRecoveryMutex()) {
+            throw new RoomLockError(`room ledger recovery lock ${lock.recoveryLockPath} is already held; refusing concurrent recovery`);
+        }
+        try {
+            // Re-read only after winning the recovery mutex. Another contender may
+            // have replaced the stale writer between our first O_EXCL failure and
+            // this point; that replacement must never be renamed.
+            const holder = readLock(lock.lockPath);
+            if (!holder) {
+                throw new RoomLockError(`room ledger lock ${lock.lockPath} is unreadable; refusing to share the ledger (remove it only if no server uses this directory)`);
+            }
+            if (holder.hostname !== os.hostname() || holder.pid === process.pid || !pidIsGone(holder.pid)) {
+                throw new RoomLockError(`room ledger ${directory} is already owned by pid ${holder.pid} on ${holder.hostname}`);
+            }
+            const stale = `${lock.lockPath}.stale-${holder.pid}-${Date.now()}`;
+            try {
+                fs.renameSync(lock.lockPath, stale);
+            }
+            catch (error) {
+                throw new RoomLockError(`could not reclaim stale room ledger lock: ${error.message}`);
+            }
+            if (!lock.tryCreate()) {
+                throw new RoomLockError(`room ledger ${directory} was claimed by another process during recovery`);
+            }
+            return lock;
+        }
+        finally {
+            lock.releaseRecoveryMutex();
+        }
+    }
+    tryCreateRecoveryMutex() {
+        let fd;
+        try {
+            fd = fs.openSync(this.recoveryLockPath, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw new RoomLockError(`could not create room ledger recovery lock: ${error.message}`);
+        }
+        try {
+            fs.writeSync(fd, JSON.stringify({
+                version: 1,
+                pid: process.pid,
+                hostname: os.hostname(),
+                token: this.token,
+                acquiredAt: new Date().toISOString(),
+            }));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return true;
+    }
+    releaseRecoveryMutex() {
+        if (readLock(this.recoveryLockPath)?.token !== this.token)
+            return;
+        try {
+            fs.unlinkSync(this.recoveryLockPath);
+        }
+        catch {
+            // A residue deliberately fails future recovery closed and requires an
+            // operator to confirm that no server is active before removing it.
+        }
+    }
+    tryCreate() {
+        let fd;
+        try {
+            fd = fs.openSync(this.lockPath, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw new RoomLockError(`could not create room ledger lock: ${error.message}`);
+        }
+        try {
+            const content = {
+                version: 1,
+                pid: process.pid,
+                hostname: os.hostname(),
+                token: this.token,
+                acquiredAt: new Date().toISOString(),
+            };
+            fs.writeSync(fd, JSON.stringify(content));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return true;
+    }
+    /** True while the lock file on disk still carries this holder's token. */
+    isHeld() {
+        if (this.released)
+            return false;
+        return readLock(this.lockPath)?.token === this.token;
+    }
+    /** Release once; never removes a lock that another holder now owns. */
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        if (readLock(this.lockPath)?.token === this.token) {
+            try {
+                fs.unlinkSync(this.lockPath);
+            }
+            catch {
+                // already gone
+            }
+        }
+    }
+}
+//# sourceMappingURL=room-lock.js.map

package/dist/fleet/rooms/room-observations.d.ts

@@ -0,0 +1,7 @@
+import { type SensoryMissionBus } from '../sensory-mission-bridge.js';
+import type { RoomHub } from './room-hub.js';
+export declare const ROOM_OBSERVATION_PRINCIPAL = "local:fleet-room-observations";
+export declare function startRoomObservations(hub: RoomHub, options?: {
+    env?: NodeJS.ProcessEnv;
+    bus?: SensoryMissionBus;
+}): () => void;

package/dist/fleet/rooms/room-observations.js

@@ -0,0 +1,61 @@
+/** Publishes local status snapshots through the same membership checks as peers. */
+import { getGlobalEventBus } from '../../events/event-bus.js';
+import { createMissionObservationRoomPublisher, wireSensoryMissionBridge, } from '../sensory-mission-bridge.js';
+import { buildRoomAuth, buildRoomMessage, isValidRoomId, signRoomEvent } from './room-event.js';
+import { loadRoomIdentity } from './room-identity.js';
+export const ROOM_OBSERVATION_PRINCIPAL = 'local:fleet-room-observations';
+export function startRoomObservations(hub, options = {}) {
+    const env = options.env ?? process.env;
+    if (env.CODEBUDDY_FLEET_ROOMS_OBSERVATIONS !== 'true')
+        return () => { };
+    const room = env.CODEBUDDY_FLEET_ROOMS_ROOM;
+    const missionId = env.CODEBUDDY_FLEET_ROOMS_MISSION;
+    if (typeof room !== 'string' || !isValidRoomId(room) || !missionId || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(missionId)) {
+        throw new Error('Room observations require a valid CODEBUDDY_FLEET_ROOMS_ROOM and CODEBUDDY_FLEET_ROOMS_MISSION');
+    }
+    const identity = loadRoomIdentity(env.CODEBUDDY_FLEET_ROOMS_IDENTITY);
+    const audience = hub.audiences[0];
+    if (!audience)
+        throw new Error('Room observations require a configured hub audience');
+    const session = hub.open({
+        connectionId: ROOM_OBSERVATION_PRINCIPAL,
+        principalId: ROOM_OBSERVATION_PRINCIPAL,
+        send: () => false,
+        isBackpressured: () => false,
+    });
+    try {
+        const challenge = session.hello();
+        const auth = session.authenticate(signRoomEvent(buildRoomAuth(challenge.challenge, audience, Math.floor(hub.now() / 1000)), identity.secretKey));
+        if (!auth.ok || !hub.access.canWrite(identity.publicKey, room)) {
+            throw new Error('Room observation identity is not allowed to publish to the configured room');
+        }
+        const stop = wireSensoryMissionBridge({
+            enabled: true,
+            missionId,
+            bus: options.bus ?? getGlobalEventBus(),
+            now: hub.now,
+            ...(env.CODEBUDDY_FLEET_ROOMS_OBSERVATION_INTERVAL_MS !== undefined
+                ? { intervalMs: Number(env.CODEBUDDY_FLEET_ROOMS_OBSERVATION_INTERVAL_MS) }
+                : {}),
+            publish: createMissionObservationRoomPublisher(room, async (target, content, createdAt, signal) => {
+                signal.throwIfAborted();
+                const result = session.publish(signRoomEvent(buildRoomMessage({ room: target, content, createdAt }, identity.publicKey), identity.secretKey));
+                if (!result.accepted)
+                    throw new Error(result.message);
+            }),
+        });
+        let stopped = false;
+        return () => {
+            if (stopped)
+                return;
+            stopped = true;
+            stop();
+            session.dispose();
+        };
+    }
+    catch (error) {
+        session.dispose();
+        throw error;
+    }
+}
+//# sourceMappingURL=room-observations.js.map

package/dist/fleet/rooms/room-server.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fleet rooms — opt-in startup for `buddy server`.
+ *
+ * `CODEBUDDY_FLEET_ROOMS=true` opens the ledger (exclusive lock), loads the room
+ * policy and registers the `fleet.rooms.*` WebSocket messages. Unset, nothing is
+ * opened or registered: `/ws` answers `UNKNOWN_TYPE` exactly as before.
+ *
+ * Accepted auth audiences: the loopback URLs of the listening port, plus the
+ * canonical URLs listed in `CODEBUDDY_FLEET_ROOMS_AUDIENCE` (csv) — the address
+ * remote members dial (e.g. `ws://codebuddy-hub.example:3000/ws`). A hub never accepts
+ * a proof addressed to a URL it was not told is its own.
+ *
+ * @module fleet/rooms/room-server
+ */
+import { RoomHub } from './room-hub.js';
+import { RoomStore } from './room-store.js';
+export interface FleetRoomsHandle {
+    readonly hub: RoomHub;
+    readonly store: RoomStore;
+    readonly audiences: readonly string[];
+    stop(): void;
+}
+export declare function fleetRoomsEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function resolveFleetRoomsAudiences(port: number, env?: NodeJS.ProcessEnv): string[];
+export declare function startFleetRooms(options: {
+    port: number;
+    env?: NodeJS.ProcessEnv;
+}): FleetRoomsHandle;

package/dist/fleet/rooms/room-server.js

@@ -0,0 +1,75 @@
+/**
+ * Fleet rooms — opt-in startup for `buddy server`.
+ *
+ * `CODEBUDDY_FLEET_ROOMS=true` opens the ledger (exclusive lock), loads the room
+ * policy and registers the `fleet.rooms.*` WebSocket messages. Unset, nothing is
+ * opened or registered: `/ws` answers `UNKNOWN_TYPE` exactly as before.
+ *
+ * Accepted auth audiences: the loopback URLs of the listening port, plus the
+ * canonical URLs listed in `CODEBUDDY_FLEET_ROOMS_AUDIENCE` (csv) — the address
+ * remote members dial (e.g. `ws://codebuddy-hub.example:3000/ws`). A hub never accepts
+ * a proof addressed to a URL it was not told is its own.
+ *
+ * @module fleet/rooms/room-server
+ */
+import { logger } from '../../utils/logger.js';
+import { RoomAccessPolicy } from './room-access.js';
+import { canonicalRoomAudience } from './room-event.js';
+import { RoomHub } from './room-hub.js';
+import { startRoomObservations } from './room-observations.js';
+import { RoomStore } from './room-store.js';
+import { wireFleetRoomsBridge } from './room-ws-bridge.js';
+export function fleetRoomsEnabled(env = process.env) {
+    return env.CODEBUDDY_FLEET_ROOMS === 'true';
+}
+export function resolveFleetRoomsAudiences(port, env = process.env) {
+    if (!Number.isSafeInteger(port) || port <= 0 || port > 65_535) {
+        throw new RangeError('port must be an integer between 1 and 65535');
+    }
+    const audiences = [`ws://127.0.0.1:${port}/ws`, `ws://localhost:${port}/ws`, `ws://[::1]:${port}/ws`];
+    for (const entry of (env.CODEBUDDY_FLEET_ROOMS_AUDIENCE ?? '').split(',')) {
+        const trimmed = entry.trim();
+        if (trimmed)
+            audiences.push(canonicalRoomAudience(trimmed));
+    }
+    return [...new Set(audiences.map((audience) => canonicalRoomAudience(audience)))];
+}
+export function startFleetRooms(options) {
+    const env = options.env ?? process.env;
+    const audiences = resolveFleetRoomsAudiences(options.port, env);
+    const store = new RoomStore({ directory: env.CODEBUDDY_FLEET_ROOMS_DIR });
+    let unwire;
+    let stopObservations;
+    let hub;
+    try {
+        hub = new RoomHub({ store, access: new RoomAccessPolicy({ path: env.CODEBUDDY_FLEET_ROOMS_CONFIG }), audiences });
+        unwire = wireFleetRoomsBridge(hub);
+    }
+    catch (error) {
+        store.close();
+        throw error;
+    }
+    try {
+        stopObservations = startRoomObservations(hub, { env });
+    }
+    catch {
+        logger.warn('[fleet-rooms] observations disabled: check the configured mission, identity and room permissions');
+    }
+    logger.info('[fleet-rooms] enabled on /ws', { storeId: store.storeId, audiences: audiences.length });
+    let stopped = false;
+    return {
+        hub,
+        store,
+        audiences,
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            stopObservations?.();
+            unwire?.();
+            hub.close();
+            store.close();
+        },
+    };
+}
+//# sourceMappingURL=room-server.js.map

package/dist/fleet/rooms/room-store.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Fleet rooms — durable append-only message ledger.
+ *
+ * Buzz stores events in Postgres and replays by `created_at` (`since`), which
+ * trusts every author's clock (`crates/buzz-acp/src/relay.rs::channel_since`).
+ * A fleet mixes machines whose clocks drift, so the hub also stamps each
+ * accepted event with a strictly increasing `seq`: reconnection resumes from
+ * the last `seq` a member saw, and a message signed with a late clock cannot
+ * fall behind the cursor. `storeId` names the ledger generation so a cursor
+ * from a wiped ledger is never trusted (same role as the cognition bus epoch).
+ *
+ * Guarantees, each covered by tests:
+ * - single writer: an exclusive directory lock ({@link RoomDirectoryLock}),
+ *   re-checked with the ledger inode and size before every write or compaction;
+ * - durability: an append is `fsync`ed before `append()` returns, so the hub
+ *   only acknowledges what survives a crash;
+ * - crash tail: bytes after the last newline (torn OR complete-but-unterminated)
+ *   are copied to `ledger.jsonl.tail-*` and truncated BEFORE `seq` is reused;
+ * - strict order and integrity: every complete record must be valid, authentic
+ *   and strictly increasing or the store fails closed;
+ * - compaction: eviction watermarks are persisted before the ledger rewrite,
+ *   so a crash in between can only over-report a gap, never hide one;
+ * - duplicate detection: ids are remembered for the retained window only;
+ * - immutability: stored records are deep-frozen copies of the input.
+ *
+ * @module fleet/rooms/room-store
+ */
+import { type ReadonlyRoomEvent } from './room-event.js';
+import { type RoomFilter } from './room-filter.js';
+export declare const DEFAULT_MAX_EVENTS_PER_ROOM = 2000;
+export declare const DEFAULT_MAX_ROOMS = 1024;
+export declare const DEFAULT_MAX_LEDGER_BYTES: number;
+export interface RoomRecord {
+    readonly seq: number;
+    readonly receivedAt: number;
+    readonly event: ReadonlyRoomEvent;
+}
+export interface RoomStoreOptions {
+    /** Defaults to `$CODEBUDDY_FLEET_ROOMS_DIR` or `<CODEBUDDY_HOME>/fleet/rooms`. */
+    directory?: string;
+    maxEventsPerRoom?: number;
+    maxRooms?: number;
+    /** Refuse to load, and to grow, a ledger beyond this size. */
+    maxLedgerBytes?: number;
+    compactAfterEvictions?: number;
+}
+export type RoomAppendResult = {
+    status: 'stored';
+    record: RoomRecord;
+} | {
+    status: 'duplicate';
+    record: RoomRecord;
+};
+export interface RoomQueryResult {
+    records: RoomRecord[];
+    /** Replay only: more matching records exist after the last one returned. */
+    truncated: boolean;
+}
+export declare class RoomStoreError extends Error {
+    readonly code: 'FULL' | 'CONFLICT' | 'CLOSED' | 'INVALID' | 'CORRUPT';
+    constructor(message: string, code: 'FULL' | 'CONFLICT' | 'CLOSED' | 'INVALID' | 'CORRUPT');
+}
+export declare function defaultRoomStoreDirectory(): string;
+export declare class RoomStore {
+    readonly directory: string;
+    readonly storeId: string;
+    private readonly ledgerPath;
+    private readonly metaPath;
+    private readonly maxEventsPerRoom;
+    private readonly maxRooms;
+    private readonly maxLedgerBytes;
+    private readonly compactAfterEvictions;
+    private readonly lock;
+    private readonly byRoom;
+    private readonly byId;
+    private readonly evicted;
+    private fd;
+    private expectedSize;
+    private lastSeq;
+    private evictionsSinceCompaction;
+    private closed;
+    private failure;
+    constructor(options?: RoomStoreOptions);
+    get latestSeq(): number;
+    private readMeta;
+    private load;
+    /** Move the bytes after the last newline aside and cut them from the ledger. */
+    private quarantineTail;
+    private parseRecord;
+    private insert;
+    private assertWritable;
+    /** Stop at the first sign that another process touched the ledger. */
+    private assertExclusive;
+    get(id: string): RoomRecord | undefined;
+    /**
+     * Durably persist an authentic room message. Idempotency is guaranteed for
+     * ids still in the retained window; an evicted id may be stored again. The
+     * input is copied and the returned record is deep-frozen.
+     */
+    append(input: unknown, receivedAt?: number): RoomAppendResult;
+    /** Rewrite the ledger with retained records; watermarks are persisted first. */
+    compact(): void;
+    /**
+     * True when records of these rooms with `seq > afterSeq` were evicted, i.e.
+     * a replay from `afterSeq` cannot be complete.
+     */
+    hasGapAfter(rooms: readonly string[], afterSeq: number): boolean;
+    /**
+     * Replay (`afterSeq` set): every match after the cursor, oldest first, capped.
+     * History (no cursor): the newest `limit` matches of each filter, NIP-01
+     * style, returned oldest first.
+     */
+    query(filters: readonly RoomFilter[], options?: {
+        afterSeq?: number;
+        maxRecords?: number;
+    }): RoomQueryResult;
+    /** Close the append descriptor and release the directory lock. Idempotent. */
+    close(): void;
+}