@archlast/server 0.0.1

package/dist/startup/processes.mjs

@@ -0,0 +1,162 @@
+import { logger } from "../logging/logger.js";
+import { IpcClient } from "../ipc/socket-bridge.js";
+import { CacheClient } from "../cache/client.js";
+import { waitForSocket } from "../cache/utils.js";
+import { join } from "path";
+import { existsSync } from "fs";
+import { ProcessManager } from "./process-manager.js";
+// Constants
+const BUN_PATH = process.execPath || "bun";
+const PROCESS_STARTUP_WAIT_MS = 500;
+const PROCESS_VERIFY_WAIT_MS = 1000;
+const SOCKET_WAIT_TIMEOUT_MS = 10000;
+// Command Paths
+const getCommandPath = (scriptParams) => [BUN_PATH, join(import.meta.dir, scriptParams)];
+const WORKER_CMD = getCommandPath("../jobs/run-worker.ts");
+const SCHEDULER_CMD = getCommandPath("../jobs/run-scheduler.ts");
+const IPC_SIDECAR_CMD = getCommandPath("../ipc/run-sidecar.ts");
+const CACHE_SIDECAR_CMD = getCommandPath("../cache/run-sidecar.ts");
+/**
+ * Spawns background processes (IPC sidecar, Cache sidecar, Worker, Scheduler)
+ * and establishes connections to the sidecar services.
+ */
+export async function spawnBackgroundProcesses(config) {
+    const processManager = new ProcessManager();
+    const ipcSocketPath = join(process.cwd(), config.paths.root, "ipc.sock");
+    const cacheSocketPath = join(process.cwd(), config.paths.root, "cache.sock");
+    logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        kind: "system",
+        message: "Starting background processes...",
+    });
+    // 1. Start Sidecars
+    await startSidecar(processManager, "IPC Sidecar", IPC_SIDECAR_CMD, {
+        IPC_SOCKET_PATH: ipcSocketPath,
+    });
+    await startSidecar(processManager, "Cache Sidecar", CACHE_SIDECAR_CMD, {
+        CACHE_SOCKET_PATH: cacheSocketPath,
+    });
+    // 2. Wait for Sockets & Connect Clients
+    await waitForStartup(PROCESS_STARTUP_WAIT_MS);
+    // 2. Wait for Sockets & Connect Clients
+    await waitForStartup(PROCESS_STARTUP_WAIT_MS);
+    // Re-implementing connection logic with specific handling for CacheClient wrapping
+    const clients = await establishConnections(ipcSocketPath, cacheSocketPath);
+    // 3. Start Workers
+    await startWorkerProcesses(processManager);
+    return {
+        ipcClient: clients.ipcClient,
+        cacheClient: clients.cacheClient,
+        processManager
+    };
+}
+/**
+ * Helper to start a sidecar process
+ */
+async function startSidecar(manager, name, command, env) {
+    try {
+        const scriptPath = command[1];
+        if (!existsSync(scriptPath)) {
+            throw new Error(`Script not found: ${scriptPath}`);
+        }
+        await manager.start(name, command, env);
+    }
+    catch (err) {
+        logError(`Failed to start ${name}`, err);
+    }
+}
+/**
+ * Helper to start worker and scheduler
+ */
+async function startWorkerProcesses(manager) {
+    try {
+        await manager.start("Worker", WORKER_CMD);
+        await manager.start("Scheduler", SCHEDULER_CMD);
+        await waitForStartup(PROCESS_VERIFY_WAIT_MS);
+        verifyProcessesRunning(manager);
+        logger.log({
+            timestamp: Date.now(),
+            level: "info",
+            kind: "system",
+            message: "Worker and Scheduler spawned and verified running",
+        });
+    }
+    catch (err) {
+        logError("Failed to spawn Worker/Scheduler", err);
+        process.exit(1);
+    }
+}
+/**
+ * Helper to verify all managed processes are running
+ */
+function verifyProcessesRunning(manager) {
+    const status = manager.getStatus();
+    const allRunning = status.every((s) => s.pid !== undefined);
+    if (!allRunning) {
+        throw new Error("One or more background processes failed to start or crashed immediately.");
+    }
+}
+/**
+ * Orchestrates connection to sidecar sockets
+ */
+async function establishConnections(ipcPath, cachePath) {
+    let ipcClient = null;
+    let cacheClient = null;
+    try {
+        await Promise.all([
+            waitForSocket(ipcPath, SOCKET_WAIT_TIMEOUT_MS),
+            waitForSocket(cachePath, SOCKET_WAIT_TIMEOUT_MS),
+        ]);
+        // Connect IPC
+        try {
+            ipcClient = new IpcClient(ipcPath);
+            await ipcClient.connect();
+            logger.setIpcClient(ipcClient);
+            logInfo("system", "IPC Sidecar connected");
+        }
+        catch (err) {
+            logError("Failed to connect to IPC Sidecar", err);
+        }
+        // Connect Cache
+        try {
+            // Need a base IPC connection for CacheClient
+            const cacheIpc = new IpcClient(cachePath);
+            await cacheIpc.connect();
+            cacheClient = new CacheClient(cacheIpc);
+            await cacheClient.connect();
+            logInfo("cache", "Cache Sidecar connected");
+        }
+        catch (err) {
+            logError("Failed to connect to Cache Sidecar", err);
+        }
+    }
+    catch (err) {
+        logError("Error waiting for sidecar sockets", err);
+    }
+    return { ipcClient, cacheClient };
+}
+/**
+ * Common logging helpers
+ */
+function logInfo(kind, message) {
+    logger.log({
+        timestamp: Date.now(),
+        level: "info",
+        kind,
+        message,
+    });
+}
+function logError(message, err) {
+    logger.log({
+        timestamp: Date.now(),
+        level: "error",
+        kind: "system",
+        message,
+        context: { error: err instanceof Error ? err.message : String(err) },
+    });
+}
+function waitForStartup(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=processes.mjs.map

package/dist/startup/processes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processes.mjs","sourceRoot":"","sources":["../../src/startup/processes.mts"],"names":[],"mappings":"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"}

package/dist/startup.js

@@ -0,0 +1,42 @@
+// startup.ts
+var server = Bun.spawn(["bun", "src/index.mts"], {
+  stdio: ["inherit", "inherit", "inherit"],
+  cwd: process.cwd()
+});
+console.log("[Supervisor] Server started with PID:", server.pid);
+function spawnServer() {
+  const child = Bun.spawn(["bun", "src/index.mts"], {
+    stdio: ["inherit", "inherit", "inherit"],
+    cwd: process.cwd()
+  });
+  console.log("[Supervisor] Server started with PID:", child.pid);
+  child.exited.then((code) => {
+    if (code === 0) {
+      console.log("[Supervisor] Restarting server...");
+      spawnServer();
+    } else {
+      console.error(`[Supervisor] Server exited with code ${code}, not restarting`);
+      process.exit(code);
+    }
+  });
+  return child;
+}
+server.exited.then((code) => {
+  if (code === 0) {
+    console.log("[Supervisor] Restarting server...");
+    spawnServer();
+  } else {
+    console.error(`[Supervisor] Server exited with code ${code}, not restarting`);
+    process.exit(code);
+  }
+});
+process.on("SIGINT", () => {
+  console.log("[Supervisor] Received SIGINT, shutting down...");
+  server.kill();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  console.log("[Supervisor] Received SIGTERM, shutting down...");
+  server.kill();
+  process.exit(0);
+});

package/dist/storage/fs-backend.d.ts

@@ -0,0 +1,38 @@
+import type { StorageBackend, StorageId, StorageMeta } from "./types.js";
+/**
+ * Filesystem-backed storage backend.
+ *
+ * Layout:
+ *   root/
+ *     objects/
+ *       ab/
+ *         abcd1234... (full hex storage id)
+ *
+ * Supports streaming writes/reads and optional signed URL generation.
+ */
+export declare class FsStorageBackend implements StorageBackend {
+    private readonly root;
+    private readonly publicUrl;
+    private readonly signingSecret;
+    constructor(options?: {
+        root?: string;
+        publicUrl?: string;
+        signingSecret?: string;
+    });
+    put(id: StorageId, stream: ReadableStream, _meta: StorageMeta): Promise<void>;
+    get(id: StorageId): Promise<ReadableStream>;
+    delete(id: StorageId): Promise<void>;
+    exists(id: StorageId): Promise<boolean>;
+    /**
+     * Generate a signed, time-limited URL for this storage object.
+     * The verifier should recompute HMAC(secret, `${id}:${exp}`) to validate.
+     */
+    signUrl(id: StorageId, expiresInSeconds: number): Promise<string>;
+    private pathFor;
+    private ensureDir;
+    private throwIfMissing;
+    verifySignature(id: StorageId, exp: number, sig: string): boolean;
+    private sign;
+}
+export default FsStorageBackend;
+//# sourceMappingURL=fs-backend.d.ts.map

package/dist/storage/fs-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-backend.d.ts","sourceRoot":"","sources":["../../src/storage/fs-backend.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACnD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;IAO7E,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC7E,GAAG,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAM3C,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpC,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAS7C;;;OAGG;IACG,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUvE,OAAO,CAAC,OAAO;YAKD,SAAS;YAKT,cAAc;IAO5B,eAAe,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAcjE,OAAO,CAAC,IAAI;CAGf;AAED,eAAe,gBAAgB,CAAC"}

package/dist/storage/fs-backend.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsStorageBackend = void 0;
+const promises_1 = require("fs/promises");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const logger_js_1 = require("../logging/logger.js");
+/**
+ * Filesystem-backed storage backend.
+ *
+ * Layout:
+ *   root/
+ *     objects/
+ *       ab/
+ *         abcd1234... (full hex storage id)
+ *
+ * Supports streaming writes/reads and optional signed URL generation.
+ */
+class FsStorageBackend {
+    root;
+    publicUrl;
+    signingSecret;
+    constructor(options) {
+        this.root = options?.root ?? "./storage";
+        this.publicUrl = options?.publicUrl ?? "/_storage";
+        this.signingSecret =
+            options?.signingSecret ?? process.env.STORAGE_SIGNING_SECRET ?? "dev-secret";
+    }
+    async put(id, stream, _meta) {
+        const filePath = this.pathFor(id);
+        await this.ensureDir(id);
+        try {
+            const arrayBuffer = stream instanceof Uint8Array
+                ? stream.buffer.slice(stream.byteOffset, stream.byteOffset + stream.byteLength)
+                : stream instanceof Blob
+                    ? await stream.arrayBuffer()
+                    : await new Response(stream).arrayBuffer();
+            await Bun.write(filePath, arrayBuffer);
+            logger_js_1.logger.log({
+                timestamp: Date.now(),
+                level: "info",
+                kind: "system",
+                message: "FS backend stored object",
+                context: { id, size: arrayBuffer.byteLength, path: filePath },
+            });
+        }
+        catch (err) {
+            logger_js_1.logger.log({
+                timestamp: Date.now(),
+                level: "error",
+                kind: "system",
+                message: "FS backend put failed",
+                context: {
+                    id,
+                    path: filePath,
+                    error: err instanceof Error ? err.message : String(err),
+                },
+            });
+            throw err;
+        }
+    }
+    async get(id) {
+        const filePath = this.pathFor(id);
+        await this.throwIfMissing(id);
+        return Bun.file(filePath).stream();
+    }
+    async delete(id) {
+        const filePath = this.pathFor(id);
+        await (0, promises_1.rm)(filePath, { force: true });
+    }
+    async exists(id) {
+        try {
+            await (0, promises_1.access)(this.pathFor(id), fs_1.constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Generate a signed, time-limited URL for this storage object.
+     * The verifier should recompute HMAC(secret, `${id}:${exp}`) to validate.
+     */
+    async signUrl(id, expiresInSeconds) {
+        const exp = Math.floor(Date.now() / 1000) + expiresInSeconds;
+        const sig = this.sign(`${id}:${exp}`);
+        const base = this.publicUrl;
+        const separator = base.includes("?") ? "&" : "?";
+        return `${base}${separator}id=${encodeURIComponent(id)}&exp=${exp}&sig=${sig}`;
+    }
+    // Helpers
+    pathFor(id) {
+        const prefix = id.slice(0, 2);
+        return (0, path_1.join)(this.root, "objects", prefix, id);
+    }
+    async ensureDir(id) {
+        const prefix = id.slice(0, 2);
+        await (0, promises_1.mkdir)((0, path_1.join)(this.root, "objects", prefix), { recursive: true });
+    }
+    async throwIfMissing(id) {
+        const exists = await this.exists(id);
+        if (!exists) {
+            throw new Error(`Storage object not found: ${id}`);
+        }
+    }
+    verifySignature(id, exp, sig) {
+        try {
+            const now = Math.floor(Date.now() / 1000);
+            if (!Number.isFinite(exp) || exp < now)
+                return false;
+            const expected = this.sign(`${id}:${exp}`);
+            const a = Buffer.from(expected, "hex");
+            const b = Buffer.from(sig, "hex");
+            if (a.length !== b.length)
+                return false;
+            return (0, crypto_1.timingSafeEqual)(a, b);
+        }
+        catch {
+            return false;
+        }
+    }
+    sign(payload) {
+        return (0, crypto_1.createHmac)("sha256", this.signingSecret).update(payload).digest("hex");
+    }
+}
+exports.FsStorageBackend = FsStorageBackend;
+exports.default = FsStorageBackend;
+//# sourceMappingURL=fs-backend.js.map

package/dist/storage/fs-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-backend.js","sourceRoot":"","sources":["../../src/storage/fs-backend.ts"],"names":[],"mappings":"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"}

package/dist/storage/manager.d.ts

@@ -0,0 +1,88 @@
+import type { IDatabaseClient } from "../db/interfaces.js";
+import { LogService } from "../logging/logger.js";
+import type { Storage, StorageBackend, StorageId, StorageMeta, StoreOptions, StoreWithNameOptions, GetUrlOptions } from "./types.js";
+export declare const STORAGE_OBJECTS_COLLECTION = "_storage_objects";
+export declare const STORAGE_NAMES_COLLECTION = "_storage_names";
+export declare const STORAGE_STAGING_COLLECTION = "_storage_staging";
+export type StorageListItem = {
+    id: StorageId;
+    fileName: string | null;
+    size: number;
+    contentType: string | null;
+    hash: string;
+    refCount: number;
+};
+/**
+ * StorageManager
+ *
+ * - Content-addressed (SHA-256) immutable objects
+ * - Staging with transactional commit/rollback
+ * - Document Store-backed metadata (_storage_objects, _storage_staging, _storage_names)
+ * - Pluggable backend (FS or S3 for actual blob storage)
+ *
+ * Dashboard support:
+ * - Persist an optional human-friendly `file_name` for each object
+ * - Provide listing APIs (cursor/pagination can be added later)
+ */
+export declare class StorageManager implements Storage {
+    private readonly backend;
+    private readonly stagingDir;
+    private readonly db;
+    private readonly logger;
+    private readonly txScope;
+    constructor(options: {
+        backend: StorageBackend;
+        db: IDatabaseClient;
+        stagingDir?: string;
+        logger: LogService;
+    });
+    /**
+     * Run storage operations within a transactional scope.
+     * Staged blobs are committed only if `fn` resolves; rolled back on rejection.
+     */
+    withTransaction<T>(txId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Store a stream/blob/uint8array. Content-addressed by SHA-256.
+     * If called inside withTransaction, it stages and defers commit;
+     * otherwise it finalizes immediately.
+     */
+    store(stream: ReadableStream | Blob | Uint8Array, options?: StoreOptions): Promise<StorageId>;
+    /**
+     * Store an object while preserving a human-friendly filename for dashboards.
+     *
+     * Note: Storage is still content-addressed; filename is metadata only.
+     */
+    storeWithName(stream: ReadableStream | Blob | Uint8Array, options?: StoreWithNameOptions): Promise<StorageId>;
+    getUrl(id: StorageId, options?: GetUrlOptions): Promise<string>;
+    open(id: StorageId): Promise<ReadableStream>;
+    delete(id: StorageId): Promise<void>;
+    getMetadata(id: StorageId): Promise<StorageMeta | null>;
+    /**
+     * Dashboard/admin helper to retrieve an optional human-friendly filename.
+     */
+    getFileName(id: StorageId): Promise<string | null>;
+    exists(id: StorageId): Promise<boolean>;
+    /**
+     * List storage objects for dashboards/admin tools.
+     * Returns the id (content hash), optional file_name, and basic meta.
+     */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StorageListItem[]>;
+    /**
+     * Garbage collect objects whose ref_count == 0 (safety: run after ref cleanup).
+     */
+    deleteUnreferenced(): Promise<number>;
+    /**
+     * Remove staging entries for a transaction id (and delete temp files).
+     * Useful for cleanup of abandoned tx.
+     */
+    cleanupStaging(txId?: string): Promise<number>;
+    private commit;
+    private rollback;
+    private finalizeOne;
+    private safeDeleteTemp;
+    private tempPathFor;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/storage/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/storage/manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EACR,OAAO,EACP,cAAc,EACd,SAAS,EACT,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,aAAa,EAChB,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAC7D,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AACzD,eAAO,MAAM,0BAA0B,qBAAqB,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC1B,EAAE,EAAE,SAAS,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,YAAW,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAkB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;gBAEhD,OAAO,EAAE;QACjB,OAAO,EAAE,cAAc,CAAC;QACxB,EAAE,EAAE,eAAe,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,UAAU,CAAC;KACtB;IAOD;;;OAGG;IACG,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAaxE;;;;OAIG;IACG,KAAK,CACP,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,YAAY,GACvB,OAAO,CAAC,SAAS,CAAC;IAIrB;;;;OAIG;IACG,aAAa,CACf,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,UAAU,EAC1C,OAAO,CAAC,EAAE,oBAAoB,GAC/B,OAAO,CAAC,SAAS,CAAC;IAwHf,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAO/D,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;IAQ5C,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BpC,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAS7D;;OAEG;IACG,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASlD,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAO7C;;;OAGG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IA4BrF;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;IAoB3C;;;OAGG;IACG,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAiBtC,MAAM;YA4CN,QAAQ;YAkBR,WAAW;YAiEX,cAAc;IAI5B,OAAO,CAAC,WAAW;CAItB"}