bff-store 0.1.0

package/src/server/cli.ts

@@ -0,0 +1,62 @@
+/**
+ * CLI entry point for the embedded server.
+ * This file should only be included in the CJS server bundle, NOT in the main library bundle.
+ */
+import { startServer } from './index';
+import type { ServerOptions } from './index';
+
+const args = process.argv.slice(2);
+const options: ServerOptions = {
+  backend: 'jsonl',
+  port: 3847,
+  host: 'localhost',
+  jsonlDir: './data',
+};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--backend' && args[i + 1]) {
+    options.backend = args[++i] as 'jsonl' | 'mongodb';
+  } else if (arg === '--port' && args[i + 1]) {
+    options.port = parseInt(args[++i], 10);
+  } else if (arg === '--host' && args[i + 1]) {
+    options.host = args[++i];
+  } else if (arg === '--jsonl-dir' && args[i + 1]) {
+    options.jsonlDir = args[++i];
+  } else if (arg === '--mongo-url' && args[i + 1]) {
+    options.mongoUrl = args[++i];
+  } else if (arg === '--mongo-db' && args[i + 1]) {
+    options.mongoDb = args[++i];
+  } else if (arg === '--help') {
+    console.log(`
+[bff-store] Embedded Server
+
+Usage:
+  bff-store-server [options]
+
+Options:
+  --backend <jsonl|mongodb>    Storage backend (default: jsonl)
+  --port <port>                 Server port (default: 3847)
+  --host <host>                 Server host (default: localhost)
+  --jsonl-dir <dir>             JSONL directory (default: ./data)
+  --mongo-url <url>             MongoDB URL (required for mongodb backend)
+  --mongo-db <db>               MongoDB database (default: jotai_state_store)
+  --help                        Show this help
+
+Examples:
+  bff-store-server --backend jsonl --jsonl-dir ./data
+  bff-store-server --backend mongodb --mongo-url mongodb://localhost:27017
+    `);
+    process.exit(0);
+  }
+}
+
+if (options.backend === 'mongodb' && !options.mongoUrl) {
+  console.error('[bff-store] Error: --mongo-url required for mongodb backend');
+  process.exit(1);
+}
+
+startServer(options).catch((err) => {
+  console.error('[bff-store] Failed to start:', err);
+  process.exit(1);
+});

package/src/server/entityIdCache.ts

@@ -0,0 +1,57 @@
+/**
+ * EntityId Cache for Multi-Tenant Storage
+ *
+ * Caches storage instances per entityId to avoid recreating them.
+ */
+
+import type { Storage } from '../storage/base';
+import { jsonlStorage } from '../storage/jsonl';
+
+export interface EntityIdCacheOptions {
+  dir: string;
+}
+
+export class EntityIdCache {
+  private cache = new Map<string, Storage>();
+  private defaultStorage: Storage;
+  private dir: string;
+
+  constructor(options: EntityIdCacheOptions) {
+    this.dir = options.dir;
+    // Create default storage
+    const adapter = jsonlStorage({ dir: options.dir });
+    adapter.setEntityId('default');
+    this.defaultStorage = adapter.storage;
+  }
+
+  getStorage(entityId?: string): Storage {
+    if (!entityId || entityId === 'default') {
+      return this.defaultStorage;
+    }
+
+    let storage = this.cache.get(entityId);
+    if (storage) {
+      return storage;
+    }
+
+    // Create new storage for this entityId
+    const adapter = jsonlStorage({ dir: this.dir });
+    adapter.setEntityId(entityId);
+    storage = adapter.storage;
+    this.cache.set(entityId, storage);
+
+    return storage;
+  }
+
+  getEntityIds(): string[] {
+    return Array.from(this.cache.keys());
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+}

package/src/server/entry.ts

@@ -0,0 +1,12 @@
+/**
+ * Embedded Server entry point
+ * Import from 'bff-store/server' instead of 'bff-store'
+ *
+ * @example
+ * import { startServer } from 'bff-store/server';
+ */
+export { startServer } from './index';
+export type { ServerOptions } from './index';
+export { Router } from './router';
+export { EntityIdCache } from './entityIdCache';
+export { createStorageHandlers } from './handlers';

package/src/server/handlers.ts

@@ -0,0 +1,271 @@
+/**
+ * Storage Handlers
+ *
+ * Request handlers for storage operations with caching for dynamic storage adapters.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { Storage, StorageAdapter } from '../storage/base';
+import type { BackendConfig } from '../types';
+import { jsonlStorage } from '../storage/jsonl';
+import { mongodbStorage } from '../storage/mongodb';
+
+export interface StorageHandlersOptions {
+  getStorage: (entityId?: string) => Storage;
+}
+
+interface CacheEntry {
+  adapter: StorageAdapter;
+  lastUsed: number;
+}
+
+// Storage adapter cache - keyed by backend+mongoUrl or backend+jsonlDir
+const storageCache = new Map<string, CacheEntry>();
+const MAX_CACHE_SIZE = 10;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function getCacheKey(config: BackendConfig): string {
+  if (config.backend === 'mongodb') {
+    return `mongodb:${config.mongoUrl}:${config.mongoDb ?? 'default'}`;
+  }
+  if (config.backend === 'jsonl') {
+    return `jsonl:${config.jsonlDir ?? './data'}`;
+  }
+  return 'default';
+}
+
+function getBackendConfig(req: IncomingMessage): BackendConfig {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  return {
+    backend: (url.searchParams.get('backend') as 'mongodb' | 'jsonl') ?? undefined,
+    mongoUrl: url.searchParams.get('mongoUrl') ?? undefined,
+    mongoDb: url.searchParams.get('mongoDb') ?? undefined,
+    jsonlDir: url.searchParams.get('jsonlDir') ?? undefined,
+  };
+}
+
+function getEntityId(req: IncomingMessage): string | undefined {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  return url.searchParams.get('entityId') ?? undefined;
+}
+
+async function parseBody<T>(req: IncomingMessage): Promise<T> {
+  let body = '';
+  for await (const chunk of req) {
+    body += chunk;
+  }
+  return JSON.parse(body);
+}
+
+function cleanExpiredCache(): void {
+  const now = Date.now();
+  for (const [key, entry] of storageCache.entries()) {
+    if (now - entry.lastUsed > CACHE_TTL_MS) {
+      storageCache.delete(key);
+    }
+  }
+}
+
+async function getCachedStorage(config: BackendConfig, entityId?: string): Promise<Storage> {
+  const key = getCacheKey(config);
+
+  // Check cache
+  if (storageCache.has(key)) {
+    const entry = storageCache.get(key)!;
+    entry.lastUsed = Date.now();
+
+    // Set entityId if provided
+    if (entityId && 'setEntityId' in entry.adapter && typeof entry.adapter.setEntityId === 'function') {
+      entry.adapter.setEntityId(entityId);
+    }
+    return entry.adapter.storage;
+  }
+
+  // Evict oldest if cache is full
+  if (storageCache.size >= MAX_CACHE_SIZE) {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+    for (const [k, entry] of storageCache.entries()) {
+      if (entry.lastUsed < oldestTime) {
+        oldestTime = entry.lastUsed;
+        oldestKey = k;
+      }
+    }
+    if (oldestKey) {
+      storageCache.delete(oldestKey);
+    }
+  }
+
+  // Create new adapter
+  let adapter: StorageAdapter;
+  if (config.backend === 'mongodb') {
+    if (!config.mongoUrl) {
+      throw new Error('mongoUrl is required for mongodb backend');
+    }
+    adapter = await mongodbStorage({
+      url: config.mongoUrl,
+      database: config.mongoDb ?? 'jotai_state_store',
+    });
+  } else if (config.backend === 'jsonl') {
+    adapter = jsonlStorage({ dir: config.jsonlDir ?? './data' });
+  } else {
+    throw new Error('Unknown backend type');
+  }
+
+  // Set entityId if provided
+  if (entityId && 'setEntityId' in adapter && typeof adapter.setEntityId === 'function') {
+    adapter.setEntityId(entityId);
+  }
+
+  // Cache it
+  storageCache.set(key, { adapter, lastUsed: Date.now() });
+
+  return adapter.storage;
+}
+
+async function getStorageForRequest(
+  req: IncomingMessage,
+  entityId?: string
+): Promise<Storage> {
+  const urlConfig = getBackendConfig(req);
+  const body = await parseBody<BackendConfig>(req);
+
+  const config: BackendConfig = {
+    backend: body.backend ?? urlConfig.backend,
+    mongoUrl: body.mongoUrl ?? urlConfig.mongoUrl,
+    mongoDb: body.mongoDb ?? urlConfig.mongoDb,
+    jsonlDir: body.jsonlDir ?? urlConfig.jsonlDir,
+  };
+
+  // Periodic cleanup of expired cache entries
+  cleanExpiredCache();
+
+  return getCachedStorage(config, entityId);
+}
+
+export function createStorageHandlers(options: StorageHandlersOptions) {
+  const { getStorage } = options;
+
+  // Resolve storage based on request - parses body only once for POST/PATCH methods
+  async function resolveStorage(req: IncomingMessage): Promise<{ storage: Storage; body: Record<string, unknown> | null }> {
+    const entityId = getEntityId(req);
+    const urlConfig = getBackendConfig(req);
+    let body: Record<string, unknown> | null = null;
+
+    // For POST/PUT/PATCH methods, parse body to get backend config
+    if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+      try {
+        body = await parseBody<Record<string, unknown>>(req);
+      } catch {
+        // Ignore parse errors
+      }
+    }
+
+    const config: BackendConfig = body
+      ? {
+          backend: (body.backend as 'mongodb' | 'jsonl') ?? urlConfig.backend,
+          mongoUrl: (body.mongoUrl as string) ?? urlConfig.mongoUrl,
+          mongoDb: (body.mongoDb as string) ?? urlConfig.mongoDb,
+          jsonlDir: (body.jsonlDir as string) ?? urlConfig.jsonlDir,
+        }
+      : urlConfig;
+
+    // If backend is specified, use dynamic storage
+    if (config.backend) {
+      cleanExpiredCache();
+      const storage = await getCachedStorage(config, entityId);
+      return { storage, body };
+    }
+
+    // Otherwise use default storage
+    return { storage: getStorage(entityId), body };
+  }
+
+  async function handleGet(req: IncomingMessage, res: ServerResponse, params?: Record<string, string>): Promise<void> {
+    const { storage } = await resolveStorage(req);
+    const value = await storage.get(params?.key ?? '');
+
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(200);
+    res.end(JSON.stringify({ value }));
+  }
+
+  async function handleSet(req: IncomingMessage, res: ServerResponse, params?: Record<string, string>): Promise<void> {
+    const { storage, body } = await resolveStorage(req);
+    const value = body?.value as unknown;
+    await storage.set(params?.key ?? '', value);
+
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(200);
+    res.end(JSON.stringify({ success: true }));
+  }
+
+  async function handleDelete(req: IncomingMessage, res: ServerResponse, params?: Record<string, string>): Promise<void> {
+    const { storage } = await resolveStorage(req);
+    await storage.remove(params?.key ?? '');
+
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(200);
+    res.end(JSON.stringify({ success: true }));
+  }
+
+  async function handleBatchGet(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const { storage, body } = await resolveStorage(req);
+    const keys = (body?.keys as string[]) ?? [];
+
+    let result: Map<string, unknown>;
+    if (storage.getMultiple) {
+      result = await storage.getMultiple(keys);
+    } else {
+      result = new Map();
+      for (const key of keys) {
+        const value = await storage.get(key);
+        if (value !== null) {
+          result.set(key, value);
+        }
+      }
+    }
+
+    const entries: Record<string, unknown> = {};
+    result.forEach((value, key) => {
+      entries[key] = value;
+    });
+
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(200);
+    res.end(JSON.stringify({ entries }));
+  }
+
+  async function handleBatchSet(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const { storage, body } = await resolveStorage(req);
+    const entries = (body?.entries as Record<string, unknown>) ?? {};
+
+    if (storage.setMultiple) {
+      const map = new Map(Object.entries(entries));
+      await storage.setMultiple(map);
+    } else {
+      for (const [key, value] of Object.entries(entries)) {
+        await storage.set(key, value);
+      }
+    }
+
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(200);
+    res.end(JSON.stringify({ success: true }));
+  }
+
+  async function handleHealth(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    res.setHeader('Content-Type', 'application/json');
+    res.writeHead(200);
+    res.end(JSON.stringify({ status: 'ok' }));
+  }
+
+  return {
+    handleGet,
+    handleSet,
+    handleDelete,
+    handleBatchGet,
+    handleBatchSet,
+    handleHealth,
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,182 @@
+/**
+ * Embedded Sidecar API Server
+ *
+ * Lightweight HTTP server that proxies storage operations to JSONL or MongoDB.
+ * Auto-shuts down when parent process exits.
+ *
+ * Supports singleton mode: call startServer() multiple times, only one server starts.
+ */
+
+import * as http from 'http';
+import { mongodbStorage } from '../storage/mongodb';
+import type { Storage } from '../storage/base';
+import { Router } from './router';
+import { EntityIdCache } from './entityIdCache';
+import { createStorageHandlers } from './handlers';
+
+export { Router } from './router';
+export { EntityIdCache } from './entityIdCache';
+export { createStorageHandlers } from './handlers';
+
+export interface ServerOptions {
+  port?: number;
+  host?: string;
+  backend: 'jsonl' | 'mongodb';
+  jsonlDir?: string;
+  mongoUrl?: string;
+  mongoDb?: string;
+}
+
+// Singleton state
+let serverInstance: http.Server | null = null;
+let serverPromise: Promise<http.Server> | null = null;
+
+const defaultOptions: ServerOptions = {
+  backend: 'jsonl',
+  port: 3847,
+  host: 'localhost',
+  jsonlDir: './data',
+};
+
+function isServerRunning(): boolean {
+  return serverInstance !== null;
+}
+
+/**
+ * Start the embedded API server (singleton).
+ *
+ * First call starts the server. Subsequent calls return the existing instance.
+ * If the existing server has been closed externally, a new one will be started.
+ * Use options to customize on first call only.
+ */
+export async function startServer(options?: Partial<ServerOptions>): Promise<http.Server> {
+  // Return existing instance if it's still running
+  if (serverInstance && serverInstance.listening) {
+    return serverInstance;
+  }
+
+  // If a start is already in progress, wait for it
+  if (serverPromise) {
+    return serverPromise;
+  }
+
+  // Server was closed externally, reset the reference
+  if (serverInstance) {
+    serverInstance = null;
+  }
+
+  // Merge options with defaults
+  const opts: ServerOptions = {
+    backend: options?.mongoUrl ? 'mongodb' : (options?.backend ?? defaultOptions.backend),
+    port: options?.port ?? defaultOptions.port,
+    host: options?.host ?? defaultOptions.host,
+    jsonlDir: options?.jsonlDir ?? defaultOptions.jsonlDir,
+    mongoUrl: options?.mongoUrl,
+    mongoDb: options?.mongoDb,
+  };
+
+  serverPromise = _startServer(opts);
+
+  try {
+    serverInstance = await serverPromise;
+    return serverInstance;
+  } finally {
+    serverPromise = null;
+  }
+}
+
+/**
+ * Internal start that does the actual server creation (no singleton check)
+ */
+async function _startServer(options: ServerOptions): Promise<http.Server> {
+  const port = options.port ?? 3847;
+  const host = options.host ?? 'localhost';
+
+  // Initialize storage backend
+  let storage: Storage;
+  let entityIdCache: EntityIdCache | undefined;
+
+  if (options.backend === 'jsonl') {
+    // Create entityId cache for JSONL
+    entityIdCache = new EntityIdCache({ dir: options.jsonlDir ?? './data' });
+    storage = entityIdCache.getStorage();
+  } else if (options.backend === 'mongodb') {
+    const adapter = await mongodbStorage({
+      url: options.mongoUrl!,
+      database: options.mongoDb ?? 'jotai_state_store',
+    });
+    storage = adapter.storage;
+  } else {
+    throw new Error(`Unsupported backend: ${options.backend}`);
+  }
+
+  // Create storage handlers
+  const handlers = createStorageHandlers({
+    getStorage: (entityId?: string) => entityIdCache
+      ? entityIdCache.getStorage(entityId)
+      : storage,
+  });
+
+  // Setup router
+  const router = new Router();
+  router.get('/storage/get/:key', handlers.handleGet);
+  router.post('/storage/set/:key', handlers.handleSet);
+  router.delete('/storage/delete/:key', handlers.handleDelete);
+  router.post('/storage/batch-get', handlers.handleBatchGet);
+  router.post('/storage/batch-set', handlers.handleBatchSet);
+  router.get('/health', handlers.handleHealth);
+
+  const server = http.createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    res.setHeader('Content-Type', 'application/json');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    try {
+      const matched = await router.handle(req, res);
+      if (!matched) {
+        res.writeHead(404);
+        res.end(JSON.stringify({ error: 'Not found' }));
+      }
+    } catch (err) {
+      console.error('[bff-store] Error:', err);
+      res.writeHead(500);
+      res.end(JSON.stringify({ error: String(err) }));
+    }
+  });
+
+  return new Promise<http.Server>((resolve, reject) => {
+    server.on('error', reject);
+
+    server.listen(port, host, () => {
+      console.log(`[bff-store] Server running on http://${host}:${port}`);
+      console.log(`[bff-store] Backend: ${options.backend}`);
+      resolve(server);
+    });
+
+    // Graceful shutdown
+    const shutdown = (signal: string) => {
+      console.log(`\n[bff-store] Received ${signal}, shutting down...`);
+      server.close(() => {
+        console.log('[bff-store] Server closed');
+        process.exit(0);
+      });
+
+      // Force close after 5s
+      setTimeout(() => {
+        console.error('[bff-store] Forced shutdown');
+        process.exit(1);
+      }, 5000);
+    };
+
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+  });
+}

package/src/server/router.ts

@@ -0,0 +1,74 @@
+/**
+ * HTTP Router for Storage Server
+ *
+ * Simple pattern-based router for HTTP requests.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'http';
+
+export type RequestHandler = (req: IncomingMessage, res: ServerResponse, params?: Record<string, string>) => Promise<void>;
+
+export interface Route {
+  method: string;
+  pattern: RegExp;
+  paramNames: string[];
+  handler: RequestHandler;
+}
+
+export class Router {
+  private routes: Route[] = [];
+
+  addRoute(method: string, path: string, handler: RequestHandler): void {
+    // Convert path pattern like /storage/get/:key to regex
+    // :param becomes a named capture group
+    const paramNames: string[] = [];
+    const regexPattern = path.replace(/:([^/]+)/g, (_, name) => {
+      paramNames.push(name);
+      return '([^/]+)';
+    });
+
+    const pattern = new RegExp(`^${regexPattern}$`);
+
+    this.routes.push({
+      method: method.toUpperCase(),
+      pattern,
+      paramNames,
+      handler: (req, res, params) => handler(req, res, params as Record<string, string>),
+    });
+  }
+
+  get(path: string, handler: RequestHandler): void {
+    this.addRoute('GET', path, handler);
+  }
+
+  post(path: string, handler: RequestHandler): void {
+    this.addRoute('POST', path, handler);
+  }
+
+  delete(path: string, handler: RequestHandler): void {
+    this.addRoute('DELETE', path, handler);
+  }
+
+  async handle(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+    const method = req.method?.toUpperCase() ?? 'GET';
+    const url = new URL(req.url ?? '/', 'http://localhost');
+
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+
+      const match = url.pathname.match(route.pattern);
+      if (match) {
+        // Extract named params using stored paramNames
+        const params: Record<string, string> = {};
+        route.paramNames.forEach((name, index) => {
+          params[name] = decodeURIComponent(match[index + 1]);
+        });
+
+        await route.handler(req, res, params);
+        return true;
+      }
+    }
+
+    return false; // No route matched
+  }
+}

package/src/server.ts

@@ -0,0 +1,5 @@
+/**
+ * @deprecated Use './server/index' instead
+ */
+export { startServer } from './server/index';
+export type { ServerOptions } from './server/index';