@bcts/hubert 1.0.0-alpha.17

package/src/server/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Server module for Hubert distributed storage.
+ *
+ * This module provides server-side storage implementations and the HTTP server.
+ *
+ * Port of server/mod.rs from hubert-rust.
+ *
+ * @module
+ */
+
+// Error types
+export {
+  ServerError,
+  ServerGeneralError,
+  ServerNetworkError,
+  ServerParseError,
+  SqliteError,
+} from "./error.js";
+
+// Storage backends
+export { MemoryKv } from "./memory-kv.js";
+export { SqliteKv } from "./sqlite-kv.js";
+export { type ServerKv, createMemoryKv, createSqliteKv } from "./server-kv.js";
+
+// HTTP server
+export { Server, type ServerConfig, defaultServerConfig } from "./server.js";
+
+// HTTP client
+export { ServerKvClient } from "./kv.js";

package/src/server/kv.ts

@@ -0,0 +1,211 @@
+/**
+ * Server-backed key-value store using HTTP API.
+ *
+ * Port of server/kv.rs from hubert-rust.
+ *
+ * @module
+ */
+
+import { type ARID } from "@bcts/components";
+import { Envelope } from "@bcts/envelope";
+
+import { AlreadyExistsError } from "../error.js";
+import { type KvStore } from "../kv-store.js";
+import { verboseNewline, verbosePrintDot, verbosePrintln } from "../logging.js";
+import { ServerGeneralError, ServerNetworkError, ServerParseError } from "./error.js";
+
+/**
+ * Server-backed key-value store using HTTP API.
+ *
+ * This implementation communicates with a Hubert server via HTTP POST requests.
+ *
+ * Port of `struct ServerKvClient` from server/kv.rs lines 6-37.
+ *
+ * @category Server Backend
+ *
+ * @example
+ * ```typescript
+ * const store = new ServerKvClient("http://127.0.0.1:45678");
+ * const arid = ARID.new();
+ * const envelope = Envelope.new("Hello, Server!");
+ *
+ * // Put envelope (write-once)
+ * await store.put(arid, envelope);
+ *
+ * // Get envelope with verbose logging
+ * const retrieved = await store.get(arid, undefined, true);
+ * ```
+ */
+export class ServerKvClient implements KvStore {
+  private readonly baseUrl: string;
+
+  /**
+   * Create a new server KV store client.
+   *
+   * Port of `ServerKvClient::new()` from server/kv.rs lines 39-46.
+   *
+   * @param baseUrl - Base URL of the Hubert server (e.g., "http://127.0.0.1:45678")
+   */
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Store an envelope at the given ARID.
+   *
+   * Port of `KvStore::put()` implementation from server/kv.rs lines 67-122.
+   */
+  async put(
+    arid: ARID,
+    envelope: Envelope,
+    ttlSeconds?: number,
+    verbose?: boolean,
+  ): Promise<string> {
+    if (verbose) {
+      verbosePrintln("Starting server put operation");
+    }
+
+    // Format body with optional TTL on third line
+    let body: string;
+    if (ttlSeconds !== undefined) {
+      body = `${arid.urString()}\n${envelope.urString()}\n${ttlSeconds}`;
+    } else {
+      body = `${arid.urString()}\n${envelope.urString()}`;
+    }
+
+    if (verbose) {
+      verbosePrintln("Sending PUT request to server");
+    }
+
+    try {
+      const response = await fetch(`${this.baseUrl}/put`, {
+        method: "POST",
+        body,
+        headers: {
+          "Content-Type": "text/plain",
+        },
+      });
+
+      if (response.status === 200) {
+        if (verbose) {
+          verbosePrintln("Server put operation completed");
+        }
+        return "Stored successfully";
+      } else if (response.status === 409) {
+        if (verbose) {
+          verbosePrintln("Server put operation failed");
+        }
+        throw new AlreadyExistsError(arid.urString());
+      } else {
+        if (verbose) {
+          verbosePrintln("Server put operation failed");
+        }
+        const errorMsg = await response.text();
+        throw new ServerGeneralError(errorMsg);
+      }
+    } catch (error) {
+      if (error instanceof AlreadyExistsError || error instanceof ServerGeneralError) {
+        throw error;
+      }
+      throw new ServerNetworkError(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  /**
+   * Retrieve an envelope for the given ARID.
+   *
+   * Port of `KvStore::get()` implementation from server/kv.rs lines 124-212.
+   */
+  async get(arid: ARID, timeoutSeconds?: number, verbose?: boolean): Promise<Envelope | null> {
+    let printedDot = false;
+
+    if (verbose) {
+      verbosePrintln("Starting server get operation");
+    }
+
+    const timeout = timeoutSeconds ?? 30; // Default 30 seconds
+    const deadline = Date.now() + timeout * 1000;
+    // Changed to 1000ms for verbose mode polling
+    const pollInterval = 1000;
+
+    if (verbose) {
+      verbosePrintln("Polling server for value");
+    }
+
+    while (true) {
+      const body = arid.urString();
+
+      try {
+        const response = await fetch(`${this.baseUrl}/get`, {
+          method: "POST",
+          body,
+          headers: {
+            "Content-Type": "text/plain",
+          },
+        });
+
+        if (response.status === 200) {
+          if (verbose && printedDot) {
+            verboseNewline();
+          }
+          if (verbose) {
+            verbosePrintln("Value found on server");
+          }
+
+          const envelopeStr = await response.text();
+          try {
+            const envelope = Envelope.fromUrString(envelopeStr);
+
+            if (verbose) {
+              verbosePrintln("Server get operation completed");
+            }
+
+            return envelope;
+          } catch (error) {
+            throw new ServerParseError(error instanceof Error ? error.message : String(error));
+          }
+        } else if (response.status === 404) {
+          // Not found yet - check if we should keep polling
+          if (Date.now() >= deadline) {
+            // Timeout reached
+            if (verbose && printedDot) {
+              verboseNewline();
+            }
+            if (verbose) {
+              verbosePrintln("Timeout reached, value not found");
+            }
+            return null;
+          }
+
+          // Print polling dot if verbose
+          if (verbose) {
+            verbosePrintDot();
+            printedDot = true;
+          }
+
+          // Wait before retrying (now 1000ms)
+          await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        } else {
+          const errorMsg = await response.text();
+          throw new ServerGeneralError(errorMsg);
+        }
+      } catch (error) {
+        if (error instanceof ServerGeneralError || error instanceof ServerParseError) {
+          throw error;
+        }
+        throw new ServerNetworkError(error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+
+  /**
+   * Check if an envelope exists at the given ARID.
+   *
+   * Port of `KvStore::exists()` implementation from server/kv.rs lines 214-218.
+   */
+  async exists(arid: ARID): Promise<boolean> {
+    // Use a short timeout for exists check (1 second), no verbose
+    const result = await this.get(arid, 1, false);
+    return result !== null;
+  }
+}

package/src/server/memory-kv.ts

@@ -0,0 +1,191 @@
+/**
+ * In-memory key-value store for Gordian Envelopes.
+ *
+ * Port of server/memory_kv.rs from hubert-rust.
+ *
+ * @module
+ */
+
+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";
+
+/**
+ * Storage entry with envelope data and optional expiration.
+ * @internal
+ */
+interface StorageEntry {
+  /** CBOR-encoded envelope data */
+  envelopeCbor: Uint8Array;
+  /** Expiration timestamp in milliseconds, or undefined for no expiration */
+  expiresAt?: number;
+}
+
+/**
+ * In-memory key-value store for Gordian Envelopes.
+ *
+ * Provides volatile storage with TTL support and automatic cleanup of
+ * expired entries.
+ *
+ * Port of `struct MemoryKv` from server/memory_kv.rs lines 14-21.
+ *
+ * @category Server Backend
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryKv();
+ * const arid = ARID.new();
+ * const envelope = Envelope.new("Hello, Memory!");
+ *
+ * await store.put(arid, envelope, 3600); // 1 hour TTL
+ * const result = await store.get(arid);
+ * ```
+ */
+export class MemoryKv implements KvStore {
+  private readonly storage: Map<string, StorageEntry>;
+
+  /**
+   * Create a new in-memory key-value store.
+   *
+   * Port of `MemoryKv::new()` from server/memory_kv.rs lines 29-33.
+   */
+  constructor() {
+    this.storage = new Map();
+  }
+
+  /**
+   * Check if an ARID exists and is not expired.
+   *
+   * Port of `check_exists()` from server/memory_kv.rs lines 36-53.
+   *
+   * @internal
+   */
+  private checkExists(arid: ARID): boolean {
+    const key = arid.urString();
+    const entry = this.storage.get(key);
+
+    if (entry) {
+      if (entry.expiresAt !== undefined && Date.now() >= entry.expiresAt) {
+        // Entry is expired, remove it
+        this.storage.delete(key);
+        return false;
+      }
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Store an envelope at the given ARID.
+   *
+   * Port of `KvStore::put()` implementation from server/memory_kv.rs lines 62-102.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async put(
+    arid: ARID,
+    envelope: Envelope,
+    ttlSeconds?: number,
+    verbose?: boolean,
+  ): Promise<string> {
+    const key = arid.urString();
+
+    // Check if already exists
+    if (this.storage.has(key)) {
+      if (verbose) {
+        verbosePrintln(`PUT ${key} ALREADY_EXISTS`);
+      }
+      throw new AlreadyExistsError(key);
+    }
+
+    const expiresAt = ttlSeconds !== undefined ? Date.now() + ttlSeconds * 1000 : undefined;
+    const envelopeCbor = envelope.taggedCborData();
+
+    const entry: StorageEntry = { envelopeCbor };
+    if (expiresAt !== undefined) {
+      entry.expiresAt = expiresAt;
+    }
+    this.storage.set(key, entry);
+
+    if (verbose) {
+      const ttlMsg = ttlSeconds !== undefined ? ` (TTL ${ttlSeconds}s)` : "";
+      verbosePrintln(`PUT ${key}${ttlMsg} OK (Memory)`);
+    }
+
+    return "Stored in memory";
+  }
+
+  /**
+   * Retrieve an envelope for the given ARID.
+   *
+   * Port of `KvStore::get()` implementation from server/memory_kv.rs lines 104-181.
+   */
+  async get(arid: ARID, timeoutSeconds?: number, verbose?: boolean): Promise<Envelope | null> {
+    const timeout = timeoutSeconds ?? 30;
+    const start = Date.now();
+    let firstAttempt = true;
+    const key = arid.urString();
+
+    // Dynamic import to avoid circular dependencies
+    const { EnvelopeDecoder } = await import("@bcts/envelope");
+
+    while (true) {
+      const entry = this.storage.get(key);
+
+      if (entry) {
+        // Check if expired
+        if (entry.expiresAt !== undefined && Date.now() >= entry.expiresAt) {
+          // Entry is expired, remove it
+          this.storage.delete(key);
+          if (verbose) {
+            verbosePrintln(`GET ${key} EXPIRED`);
+          }
+          return null;
+        }
+
+        // Parse CBOR bytes back to Envelope
+        try {
+          const envelope = EnvelopeDecoder.tryFromCborData(entry.envelopeCbor);
+          if (verbose) {
+            verbosePrintln(`GET ${key} OK (Memory)`);
+          }
+          return envelope;
+        } catch {
+          // If parsing fails, treat as not found
+          return null;
+        }
+      }
+
+      // Not found yet
+      const elapsed = (Date.now() - start) / 1000;
+      if (elapsed >= timeout) {
+        if (verbose) {
+          verbosePrintln(`GET ${key} NOT_FOUND (timeout after ${timeout}s)`);
+        }
+        return null;
+      }
+
+      if (firstAttempt && verbose) {
+        verbosePrintln(`Polling for ${key} (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/memory_kv.rs lines 183-186.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async exists(arid: ARID): Promise<boolean> {
+    return this.checkExists(arid);
+  }
+}

package/src/server/server-kv.ts

@@ -0,0 +1,92 @@
+/**
+ * Server-side key-value storage backend union type.
+ *
+ * Port of server/server_kv.rs from hubert-rust.
+ *
+ * @module
+ */
+
+import { type ARID } from "@bcts/components";
+import { type Envelope } from "@bcts/envelope";
+
+import { type KvStore } from "../kv-store.js";
+import { MemoryKv } from "./memory-kv.js";
+import { type SqliteKv } from "./sqlite-kv.js";
+
+/**
+ * Server-side key-value storage backend.
+ *
+ * This type allows selecting between in-memory and SQLite storage
+ * at server setup time.
+ *
+ * Port of `enum ServerKv` from server/server_kv.rs lines 7-15.
+ *
+ * @category Server Backend
+ */
+export type ServerKv = MemoryKv | SqliteKv;
+
+/**
+ * Create a new in-memory server KV store.
+ *
+ * Port of `ServerKv::memory()` from server/server_kv.rs line 19.
+ *
+ * @returns A new MemoryKv instance
+ * @category Server Backend
+ */
+export function createMemoryKv(): MemoryKv {
+  return new MemoryKv();
+}
+
+/**
+ * Create a new SQLite-backed server KV store.
+ *
+ * Port of `ServerKv::sqlite()` from server/server_kv.rs line 22.
+ *
+ * @param store - The SqliteKv instance to use
+ * @returns The same SqliteKv instance
+ * @category Server Backend
+ */
+export function createSqliteKv(store: SqliteKv): SqliteKv {
+  return store;
+}
+
+/**
+ * Synchronously put an envelope into the store.
+ *
+ * This function wraps the async KvStore trait implementation for use
+ * in synchronous HTTP handlers.
+ *
+ * Port of `put_sync()` from server/server_kv.rs lines 27-52.
+ *
+ * @param store - The KvStore to use
+ * @param arid - The ARID to store at
+ * @param envelope - The envelope to store
+ * @param ttlSeconds - TTL in seconds
+ * @returns Promise that resolves when storage is complete
+ * @internal
+ */
+export async function putSync(
+  store: KvStore,
+  arid: ARID,
+  envelope: Envelope,
+  ttlSeconds: number,
+): Promise<void> {
+  await store.put(arid, envelope, ttlSeconds, false);
+}
+
+/**
+ * Synchronously get an envelope from the store.
+ *
+ * This function wraps the async KvStore trait implementation for use
+ * in synchronous HTTP handlers.
+ *
+ * Port of `get_sync()` from server/server_kv.rs lines 58-71.
+ *
+ * @param store - The KvStore to use
+ * @param arid - The ARID to retrieve
+ * @returns The envelope if found, or null
+ * @internal
+ */
+export async function getSync(store: KvStore, arid: ARID): Promise<Envelope | null> {
+  return await store.get(arid, 0, false);
+}