@bcts/hubert 1.0.0-alpha.17

package/src/server/server.ts

@@ -0,0 +1,369 @@
+/**
+ * Hubert HTTP server implementation.
+ *
+ * Port of server/server.rs from hubert-rust.
+ *
+ * @module
+ */
+
+import Fastify, { type FastifyInstance, type FastifyRequest, type FastifyReply } from "fastify";
+
+import { ARID } from "@bcts/components";
+import { Envelope } from "@bcts/envelope";
+
+import { verbosePrintln } from "../logging.js";
+import { MemoryKv } from "./memory-kv.js";
+import { type ServerKv, getSync, putSync } from "./server-kv.js";
+import { type SqliteKv } from "./sqlite-kv.js";
+
+/**
+ * Package version for health endpoint.
+ */
+const VERSION = "1.0.0-alpha.1";
+
+/**
+ * Configuration for the Hubert server.
+ *
+ * Port of `struct ServerConfig` from server/server.rs lines 19-30.
+ *
+ * @category Server
+ */
+export interface ServerConfig {
+  /** Port to listen on */
+  port: number;
+  /**
+   * Maximum TTL in seconds allowed.
+   * If a put() specifies a TTL higher than this, it will be clamped.
+   * If put() specifies None, this value will be used.
+   * Hubert is intended for coordination, not long-term storage.
+   */
+  maxTtl: number;
+  /** Enable verbose logging with timestamps */
+  verbose: boolean;
+}
+
+/**
+ * Default server configuration.
+ *
+ * Port of `impl Default for ServerConfig` from server/server.rs lines 32-40.
+ */
+export const defaultServerConfig: ServerConfig = {
+  port: 45678,
+  maxTtl: 86400, // 24 hours max (and default)
+  verbose: false,
+};
+
+/**
+ * Shared server state.
+ *
+ * Port of `struct ServerState` from server/server.rs lines 43-47.
+ *
+ * @internal
+ */
+class ServerState {
+  storage: ServerKv;
+  config: ServerConfig;
+
+  constructor(config: ServerConfig, storage: ServerKv) {
+    this.storage = storage;
+    this.config = config;
+  }
+
+  /**
+   * Put an envelope into storage.
+   *
+   * Port of `ServerState::put()` from server/server.rs lines 54-101.
+   */
+  async put(
+    arid: ARID,
+    envelope: Envelope,
+    requestedTtl: number | undefined,
+    clientIp: string | undefined,
+  ): Promise<void> {
+    // Determine effective TTL:
+    // - If requested, use it (clamped to maxTtl)
+    // - If undefined requested, use maxTtl
+    // All entries expire (hubert is for coordination, not long-term storage)
+    const maxTtl = this.config.maxTtl;
+    let ttl: number;
+    if (requestedTtl !== undefined) {
+      ttl = requestedTtl > maxTtl ? maxTtl : requestedTtl;
+    } else {
+      ttl = maxTtl;
+    }
+
+    try {
+      await putSync(this.storage, arid, envelope, ttl);
+
+      if (this.config.verbose) {
+        const ipStr = clientIp ? `${clientIp}: ` : "";
+        verbosePrintln(`${ipStr}PUT ${arid.urString()} (TTL ${ttl}s) OK`);
+      }
+    } catch (error) {
+      if (this.config.verbose) {
+        const ipStr = clientIp ? `${clientIp}: ` : "";
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        verbosePrintln(`${ipStr}PUT ${arid.urString()} (TTL ${ttl}s) ERROR: ${errorMsg}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get an envelope from storage.
+   *
+   * Port of `ServerState::get()` from server/server.rs lines 103-126.
+   */
+  async get(arid: ARID, clientIp: string | undefined): Promise<Envelope | null> {
+    const result = await getSync(this.storage, arid);
+
+    if (this.config.verbose) {
+      const ipStr = clientIp ? `${clientIp}: ` : "";
+      const status = result ? "OK" : "NOT_FOUND";
+      verbosePrintln(`${ipStr}GET ${arid.urString()} ${status}`);
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Hubert HTTP server.
+ *
+ * Port of `struct Server` from server/server.rs lines 128-133.
+ *
+ * @category Server
+ *
+ * @example
+ * ```typescript
+ * const server = Server.newMemory({ port: 8080, maxTtl: 3600, verbose: true });
+ * await server.run();
+ * ```
+ */
+export class Server {
+  private readonly config: ServerConfig;
+  private readonly state: ServerState;
+  private readonly fastify: FastifyInstance;
+
+  /**
+   * Create a new server with the given configuration and storage backend.
+   *
+   * Port of `Server::new()` from server/server.rs lines 135-139.
+   */
+  constructor(config: ServerConfig, storage: ServerKv) {
+    this.config = config;
+    this.state = new ServerState(config, storage);
+    this.fastify = Fastify({ logger: false });
+    this.setupRoutes();
+  }
+
+  /**
+   * Create a new server with in-memory storage.
+   *
+   * Port of `Server::new_memory()` from server/server.rs lines 142-144.
+   */
+  static newMemory(config: Partial<ServerConfig> = {}): Server {
+    const fullConfig = { ...defaultServerConfig, ...config };
+    return new Server(fullConfig, new MemoryKv());
+  }
+
+  /**
+   * Create a new server with SQLite storage.
+   *
+   * Port of `Server::new_sqlite()` from server/server.rs lines 147-149.
+   */
+  static newSqlite(config: Partial<ServerConfig> = {}, storage: SqliteKv): Server {
+    const fullConfig = { ...defaultServerConfig, ...config };
+    return new Server(fullConfig, storage);
+  }
+
+  /**
+   * Setup HTTP routes.
+   * @internal
+   */
+  private setupRoutes(): void {
+    // Health check endpoint
+    this.fastify.get("/health", this.handleHealth.bind(this));
+
+    // PUT endpoint
+    this.fastify.post("/put", this.handlePut.bind(this));
+
+    // GET endpoint
+    this.fastify.post("/get", this.handleGet.bind(this));
+  }
+
+  /**
+   * Handle health check requests.
+   *
+   * Port of `handle_health()` from server/server.rs lines 179-187.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  private async handleHealth(_request: FastifyRequest, reply: FastifyReply): Promise<void> {
+    reply.send({
+      server: "hubert",
+      version: VERSION,
+      status: "ok",
+    });
+  }
+
+  /**
+   * Handle PUT requests.
+   *
+   * Port of `handle_put()` from server/server.rs lines 195-238.
+   */
+  private async handlePut(
+    request: FastifyRequest<{ Body: string }>,
+    reply: FastifyReply,
+  ): Promise<void> {
+    try {
+      const bodyStr = request.body;
+      if (typeof bodyStr !== "string") {
+        reply.status(400).send("Expected text body");
+        return;
+      }
+
+      const lines = bodyStr.split("\n");
+      if (lines.length < 2) {
+        reply.status(400).send("Expected at least 2 lines: ur:arid and ur:envelope");
+        return;
+      }
+
+      // Parse ARID
+      let arid: ARID;
+      try {
+        arid = ARID.fromUrString(lines[0]);
+      } catch {
+        reply.status(400).send("Invalid ur:arid");
+        return;
+      }
+
+      // Parse Envelope
+      let envelope: Envelope;
+      try {
+        envelope = Envelope.fromUrString(lines[1]);
+      } catch {
+        reply.status(400).send("Invalid ur:envelope");
+        return;
+      }
+
+      // Parse optional TTL
+      let ttl: number | undefined;
+      if (lines.length > 2 && lines[2].trim() !== "") {
+        const parsed = parseInt(lines[2], 10);
+        if (isNaN(parsed)) {
+          reply.status(400).send("Invalid TTL");
+          return;
+        }
+        ttl = parsed;
+      }
+
+      // Get client IP
+      const clientIp = request.ip;
+
+      // Store the envelope
+      await this.state.put(arid, envelope, ttl, clientIp);
+
+      reply.status(200).send("OK");
+    } catch (error) {
+      // Check if it's an AlreadyExists error
+      if (error instanceof Error && error.name === "AlreadyExistsError") {
+        reply.status(409).send(error.message);
+      } else {
+        reply.status(500).send(error instanceof Error ? error.message : "Internal server error");
+      }
+    }
+  }
+
+  /**
+   * Handle GET requests.
+   *
+   * Port of `handle_get()` from server/server.rs lines 244-269.
+   */
+  private async handleGet(
+    request: FastifyRequest<{ Body: string }>,
+    reply: FastifyReply,
+  ): Promise<void> {
+    try {
+      const bodyStr = request.body;
+      if (typeof bodyStr !== "string") {
+        reply.status(400).send("Expected text body");
+        return;
+      }
+
+      const aridStr = bodyStr.trim();
+      if (aridStr === "") {
+        reply.status(400).send("Expected ur:arid");
+        return;
+      }
+
+      // Parse ARID
+      let arid: ARID;
+      try {
+        arid = ARID.fromUrString(aridStr);
+      } catch {
+        reply.status(400).send("Invalid ur:arid");
+        return;
+      }
+
+      // Get client IP
+      const clientIp = request.ip;
+
+      // Retrieve the envelope
+      const envelope = await this.state.get(arid, clientIp);
+
+      if (envelope) {
+        reply.status(200).send(envelope.urString());
+      } else {
+        reply.status(404).send("Not found");
+      }
+    } catch (error) {
+      reply.status(500).send(error instanceof Error ? error.message : "Internal server error");
+    }
+  }
+
+  /**
+   * Run the server.
+   *
+   * Port of `Server::run()` from server/server.rs lines 152-170.
+   */
+  async run(): Promise<void> {
+    const addr = `127.0.0.1:${this.config.port}`;
+
+    // Configure Fastify to parse plain text bodies
+    this.fastify.addContentTypeParser(
+      "text/plain",
+      { parseAs: "string" },
+      (_request, payload, done) => {
+        done(null, payload);
+      },
+    );
+
+    // Also handle application/octet-stream and no content-type
+    this.fastify.addContentTypeParser(
+      "application/octet-stream",
+      { parseAs: "string" },
+      (_request, payload, done) => {
+        done(null, payload);
+      },
+    );
+
+    await this.fastify.listen({ port: this.config.port, host: "127.0.0.1" });
+    console.log(`✓ Hubert server listening on ${addr}`);
+  }
+
+  /**
+   * Get the port the server is configured to listen on.
+   *
+   * Port of `Server::port()` from server/server.rs line 173.
+   */
+  port(): number {
+    return this.config.port;
+  }
+
+  /**
+   * Stop the server.
+   */
+  async close(): Promise<void> {
+    await this.fastify.close();
+  }
+}

package/src/server/sqlite-kv.ts

@@ -0,0 +1,295 @@
+/**
+ * SQLite-backed key-value store for Gordian Envelopes.
+ *
+ * Port of server/sqlite_kv.rs from hubert-rust.
+ *
+ * @module
+ */
+
+import Database from "better-sqlite3";
+import * as fs from "fs";
+import * as path from "path";
+
+import { type ARID } from "@bcts/components";
+import { type Envelope } from "@bcts/envelope";
+
+import { AlreadyExistsError } from "../error.js";
+import { type KvStore } from "../kv-store.js";
+import { verbosePrintln } from "../logging.js";
+import { SqliteError } from "./error.js";
+
+/**
+ * SQLite-backed key-value store for Gordian Envelopes.
+ *
+ * Provides persistent storage with TTL support and automatic cleanup of
+ * expired entries.
+ *
+ * Port of `struct SqliteKv` from server/sqlite_kv.rs lines 16-24.
+ *
+ * @category Server Backend
+ *
+ * @example
+ * ```typescript
+ * const store = new SqliteKv("./hubert.db");
+ * const arid = ARID.new();
+ * const envelope = Envelope.new("Hello, SQLite!");
+ *
+ * await store.put(arid, envelope, 3600); // 1 hour TTL
+ * const result = await store.get(arid);
+ *
+ * // Cleanup when done
+ * store.close();
+ * ```
+ */
+export class SqliteKv implements KvStore {
+  private readonly db: Database.Database;
+  private readonly dbPath: string;
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  /**
+   * Create a new SQLite-backed key-value store.
+   *
+   * Port of `SqliteKv::new()` from server/sqlite_kv.rs lines 26-67.
+   *
+   * @param dbPath - Path to the SQLite database file. Will be created if it doesn't exist.
+   * @throws {SqliteError} If database initialization fails
+   */
+  constructor(dbPath: string) {
+    this.dbPath = dbPath;
+
+    // Create parent directory if it doesn't exist
+    const parentDir = path.dirname(dbPath);
+    if (parentDir && parentDir !== "." && !fs.existsSync(parentDir)) {
+      fs.mkdirSync(parentDir, { recursive: true });
+    }
+
+    try {
+      this.db = new Database(dbPath);
+
+      // Create table if it doesn't exist
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS hubert_store (
+          arid TEXT PRIMARY KEY,
+          envelope TEXT NOT NULL,
+          expires_at INTEGER
+        );
+        CREATE INDEX IF NOT EXISTS idx_expires_at ON hubert_store(expires_at);
+      `);
+    } catch (error) {
+      throw new SqliteError(
+        `Failed to initialize database: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined,
+      );
+    }
+
+    // Start background cleanup task
+    this.startCleanupTask();
+  }
+
+  /**
+   * Start a background task that prunes expired entries every minute.
+   *
+   * Port of `start_cleanup_task()` from server/sqlite_kv.rs lines 70-126.
+   *
+   * @internal
+   */
+  private startCleanupTask(): void {
+    this.cleanupInterval = setInterval(() => {
+      const now = Math.floor(Date.now() / 1000);
+
+      try {
+        // First collect the ARIDs that will be deleted
+        const selectStmt = this.db.prepare(
+          "SELECT arid FROM hubert_store WHERE expires_at IS NOT NULL AND expires_at <= ?",
+        );
+        const rows = selectStmt.all(now) as { arid: string }[];
+        const arids = rows.map((row) => row.arid);
+
+        if (arids.length > 0) {
+          // Now delete them
+          const deleteStmt = this.db.prepare(
+            "DELETE FROM hubert_store WHERE expires_at IS NOT NULL AND expires_at <= ?",
+          );
+          deleteStmt.run(now);
+
+          const count = arids.length;
+          const aridList = arids.join(" ");
+          verbosePrintln(
+            `Pruned ${count} expired ${count === 1 ? "entry" : "entries"}: ${aridList}`,
+          );
+        }
+      } catch {
+        // Silently ignore cleanup errors
+      }
+    }, 60 * 1000); // Every 60 seconds
+  }
+
+  /**
+   * Check if an ARID exists and is not expired.
+   *
+   * Port of `check_exists()` from server/sqlite_kv.rs lines 129-170.
+   *
+   * @internal
+   */
+  private checkExists(arid: ARID): boolean {
+    const aridStr = arid.urString();
+    const now = Math.floor(Date.now() / 1000);
+
+    try {
+      const stmt = this.db.prepare("SELECT expires_at FROM hubert_store WHERE arid = ?");
+      const row = stmt.get(aridStr) as { expires_at: number | null } | undefined;
+
+      if (row) {
+        // Check if expired
+        if (row.expires_at !== null && now >= row.expires_at) {
+          // Entry is expired, remove it
+          const deleteStmt = this.db.prepare("DELETE FROM hubert_store WHERE arid = ?");
+          deleteStmt.run(aridStr);
+          return false;
+        }
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Store an envelope at the given ARID.
+   *
+   * Port of `KvStore::put()` implementation from server/sqlite_kv.rs lines 175-236.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async put(
+    arid: ARID,
+    envelope: Envelope,
+    ttlSeconds?: number,
+    verbose?: boolean,
+  ): Promise<string> {
+    // Check if already exists
+    if (this.checkExists(arid)) {
+      if (verbose) {
+        verbosePrintln(`PUT ${arid.urString()} ALREADY_EXISTS`);
+      }
+      throw new AlreadyExistsError(arid.urString());
+    }
+
+    const aridStr = arid.urString();
+    const envelopeStr = envelope.urString();
+
+    const expiresAt = ttlSeconds !== undefined ? Math.floor(Date.now() / 1000) + ttlSeconds : null;
+
+    try {
+      const stmt = this.db.prepare(
+        "INSERT INTO hubert_store (arid, envelope, expires_at) VALUES (?, ?, ?)",
+      );
+      stmt.run(aridStr, envelopeStr, expiresAt);
+
+      if (verbose) {
+        const ttlMsg = ttlSeconds !== undefined ? ` (TTL ${ttlSeconds}s)` : "";
+        verbosePrintln(`PUT ${aridStr}${ttlMsg} OK (SQLite: ${this.dbPath})`);
+      }
+
+      return `Stored in SQLite: ${this.dbPath}`;
+    } catch (error) {
+      throw new SqliteError(
+        `Failed to insert: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined,
+      );
+    }
+  }
+
+  /**
+   * Retrieve an envelope for the given ARID.
+   *
+   * Port of `KvStore::get()` implementation from server/sqlite_kv.rs lines 238-354.
+   */
+  async get(arid: ARID, timeoutSeconds?: number, verbose?: boolean): Promise<Envelope | null> {
+    const timeout = timeoutSeconds ?? 30;
+    const start = Date.now();
+    let firstAttempt = true;
+    const aridStr = arid.urString();
+
+    // Dynamic import to avoid circular dependencies
+    const { Envelope } = await import("@bcts/envelope");
+
+    while (true) {
+      const now = Math.floor(Date.now() / 1000);
+
+      try {
+        const stmt = this.db.prepare(
+          "SELECT envelope, expires_at FROM hubert_store WHERE arid = ?",
+        );
+        const row = stmt.get(aridStr) as
+          | { envelope: string; expires_at: number | null }
+          | undefined;
+
+        if (row) {
+          // Check if expired
+          if (row.expires_at !== null && now >= row.expires_at) {
+            // Entry is expired, remove it
+            const deleteStmt = this.db.prepare("DELETE FROM hubert_store WHERE arid = ?");
+            deleteStmt.run(aridStr);
+
+            if (verbose) {
+              verbosePrintln(`GET ${aridStr} EXPIRED`);
+            }
+            return null;
+          }
+
+          // Entry found and not expired
+          const envelope = Envelope.fromUrString(row.envelope);
+
+          if (verbose) {
+            verbosePrintln(`GET ${aridStr} OK (SQLite: ${this.dbPath})`);
+          }
+
+          return envelope;
+        }
+      } catch {
+        // Query failed, treat as not found
+      }
+
+      // Not found yet
+      const elapsed = (Date.now() - start) / 1000;
+      if (elapsed >= timeout) {
+        if (verbose) {
+          verbosePrintln(`GET ${aridStr} NOT_FOUND (timeout after ${timeout}s)`);
+        }
+        return null;
+      }
+
+      if (firstAttempt && verbose) {
+        verbosePrintln(`Polling for ${aridStr} (timeout: ${timeout}s)`);
+        firstAttempt = false;
+      } else if (verbose) {
+        process.stdout.write(".");
+      }
+
+      // Wait 500ms before polling again
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+
+  /**
+   * Check if an envelope exists at the given ARID.
+   *
+   * Port of `KvStore::exists()` implementation from server/sqlite_kv.rs lines 356-359.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async exists(arid: ARID): Promise<boolean> {
+    return this.checkExists(arid);
+  }
+
+  /**
+   * Close the database connection and stop the cleanup task.
+   */
+  close(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.db.close();
+  }
+}