prepia 1.0.0

package/src/api/server.mjs

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview HTTP API server using node:http.
+ * @module api/server
+ */
+
+import http from 'node:http';
+import { parseBody, cors, RateLimitMiddleware, AuthMiddleware, errorHandler, requestLogger } from './middleware.mjs';
+import { createRoutes } from './routes.mjs';
+
+export class Server {
+  /**
+   * @param {Object} engine - Prepia engine instance
+   * @param {Object} [options]
+   * @param {number} [options.port=3000] - Server port
+   * @param {string} [options.host='0.0.0.0'] - Bind address
+   * @param {string[]} [options.apiKeys] - Valid API keys
+   * @param {boolean} [options.authRequired=false] - Require authentication
+   * @param {number} [options.rateLimit=100] - Requests per minute
+   */
+  constructor(engine, options = {}) {
+    this._engine = engine;
+    this._port = options.port ?? 3000;
+    this._host = options.host ?? '0.0.0.0';
+    this._server = null;
+    this._routes = createRoutes(engine);
+    this._rateLimiter = new RateLimitMiddleware({ maxRequests: options.rateLimit ?? 100 });
+    this._auth = new AuthMiddleware({
+      apiKeys: options.apiKeys,
+      required: options.authRequired ?? false,
+    });
+  }
+
+  /**
+   * Start the HTTP server.
+   * @returns {Promise<void>}
+   */
+  start() {
+    return new Promise((resolve) => {
+      this._server = http.createServer(async (req, res) => {
+        const logger = requestLogger(req);
+
+        try {
+          // CORS
+          cors(req, res);
+          if (req.method === 'OPTIONS') {
+            logger.end(res);
+            return;
+          }
+
+          // Auth
+          const authResult = this._auth.authenticate(req);
+          if (!authResult.authenticated) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: { message: 'Unauthorized' } }));
+            logger.end(res);
+            return;
+          }
+
+          // Rate limiting
+          const rateResult = this._rateLimiter.check(authResult.clientId);
+          res.setHeader('X-RateLimit-Remaining', rateResult.remaining);
+          if (!rateResult.allowed) {
+            res.writeHead(429, {
+              'Content-Type': 'application/json',
+              'Retry-After': Math.ceil(rateResult.retryAfter / 1000),
+            });
+            res.end(JSON.stringify({ error: { message: 'Rate limit exceeded', retryAfter: rateResult.retryAfter } }));
+            logger.end(res);
+            return;
+          }
+
+          // Parse body
+          let body = null;
+          if (req.method !== 'GET' && req.method !== 'HEAD') {
+            body = await parseBody(req);
+          }
+
+          // Route
+          await this._routes.route(req, res, body);
+        } catch (err) {
+          errorHandler(err, res);
+        }
+
+        logger.end(res);
+      });
+
+      this._server.listen(this._port, this._host, () => {
+        console.log(`Prepia API server running on http://${this._host}:${this._port}`);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Stop the HTTP server.
+   * @returns {Promise<void>}
+   */
+  stop() {
+    return new Promise((resolve, reject) => {
+      if (!this._server) {
+        resolve();
+        return;
+      }
+      this._server.close((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  /**
+   * Get the server address.
+   * @returns {Object|null}
+   */
+  address() {
+    return this._server?.address() || null;
+  }
+
+  /**
+   * Get the port the server is listening on.
+   * @returns {number}
+   */
+  get port() {
+    return this._server?.address()?.port || this._port;
+  }
+}
+
+/**
+ * Create and start a Prepia API server.
+ * @param {Object} engine - Prepia engine
+ * @param {Object} [options]
+ * @returns {Promise<Server>}
+ */
+export async function createServer(engine, options = {}) {
+  const server = new Server(engine, options);
+  await server.start();
+  return server;
+}
+
+// If run directly, start a standalone server
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const { PrepiaEngine } = await import('../core/engine.mjs');
+  const engine = new PrepiaEngine();
+  const server = await createServer(engine, {
+    port: parseInt(process.env.PREPIA_PORT || '3000'),
+  });
+  console.log(`Server running at http://localhost:${server.port}`);
+}
+
+export default { Server, createServer };

package/src/cache/disk-store.mjs

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Persistent disk cache using JSON files.
+ * @module cache/disk-store
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export class DiskStore {
+  /**
+   * Create a new DiskStore.
+   * @param {Object} [options]
+   * @param {string} [options.cacheDir='.prepia/cache'] - Cache directory path
+   * @param {number} [options.defaultTTL=3600000] - Default TTL in ms (1 hour)
+   * @param {number} [options.maxSize=10000] - Maximum number of entries
+   */
+  constructor(options = {}) {
+    this._cacheDir = options.cacheDir ?? '.prepia/cache';
+    this._defaultTTL = options.defaultTTL ?? 60 * 60 * 1000;
+    this._maxSize = options.maxSize ?? 10000;
+    this._initialized = false;
+  }
+
+  /**
+   * Initialize the cache directory.
+   */
+  async init() {
+    if (this._initialized) return;
+    await fs.mkdir(this._cacheDir, { recursive: true });
+    this._initialized = true;
+  }
+
+  /**
+   * Generate a safe filename from a cache key.
+   * @param {string} key
+   * @returns {string}
+   * @private
+   */
+  _keyToFilename(key) {
+    const hash = crypto.createHash('sha256').update(key).digest('hex');
+    return path.join(this._cacheDir, `${hash}.json`);
+  }
+
+  /**
+   * Get a value from disk cache.
+   * @param {string} key
+   * @returns {Promise<*>} The cached value or undefined
+   */
+  async get(key) {
+    await this.init();
+    const filepath = this._keyToFilename(key);
+    try {
+      const data = await fs.readFile(filepath, 'utf-8');
+      const entry = JSON.parse(data);
+      if (Date.now() > entry.expiresAt) {
+        await fs.unlink(filepath).catch(() => {});
+        return undefined;
+      }
+      entry.hits = (entry.hits || 0) + 1;
+      await fs.writeFile(filepath, JSON.stringify(entry), 'utf-8').catch(() => {});
+      return entry.value;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Set a value in disk cache.
+   * @param {string} key
+   * @param {*} value
+   * @param {number} [ttl] - TTL in ms
+   */
+  async set(key, value, ttl) {
+    await this.init();
+    const now = Date.now();
+    const entry = {
+      key,
+      value,
+      createdAt: now,
+      expiresAt: now + (ttl ?? this._defaultTTL),
+      hits: 0,
+    };
+    const filepath = this._keyToFilename(key);
+    await fs.writeFile(filepath, JSON.stringify(entry), 'utf-8');
+  }
+
+  /**
+   * Check if a key exists and is not expired.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async has(key) {
+    await this.init();
+    const filepath = this._keyToFilename(key);
+    try {
+      const data = await fs.readFile(filepath, 'utf-8');
+      const entry = JSON.parse(data);
+      if (Date.now() > entry.expiresAt) {
+        await fs.unlink(filepath).catch(() => {});
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Delete a key from disk cache.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    await this.init();
+    const filepath = this._keyToFilename(key);
+    try {
+      await fs.unlink(filepath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clear all cache entries.
+   */
+  async clear() {
+    await this.init();
+    try {
+      const files = await fs.readdir(this._cacheDir);
+      await Promise.all(
+        files
+          .filter(f => f.endsWith('.json'))
+          .map(f => fs.unlink(path.join(this._cacheDir, f)).catch(() => {}))
+      );
+    } catch {
+      // Directory may not exist yet
+    }
+  }
+
+  /**
+   * Remove expired entries.
+   * @returns {Promise<number>} Number of entries removed
+   */
+  async cleanup() {
+    await this.init();
+    let removed = 0;
+    try {
+      const files = await fs.readdir(this._cacheDir);
+      const now = Date.now();
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+        const filepath = path.join(this._cacheDir, file);
+        try {
+          const data = await fs.readFile(filepath, 'utf-8');
+          const entry = JSON.parse(data);
+          if (now > entry.expiresAt) {
+            await fs.unlink(filepath);
+            removed++;
+          }
+        } catch {
+          // Corrupted file, remove it
+          await fs.unlink(filepath).catch(() => {});
+          removed++;
+        }
+      }
+    } catch {
+      // Directory may not exist
+    }
+    return removed;
+  }
+
+  /**
+   * Get the count of cached entries.
+   * @returns {Promise<number>}
+   */
+  async size() {
+    await this.init();
+    try {
+      const files = await fs.readdir(this._cacheDir);
+      return files.filter(f => f.endsWith('.json')).length;
+    } catch {
+      return 0;
+    }
+  }
+
+  /**
+   * Generate a cache key from parameters.
+   * @param {Object} params
+   * @returns {string}
+   */
+  static generateKey(params) {
+    const str = typeof params === 'string' ? params : JSON.stringify(params, Object.keys(params).sort());
+    return crypto.createHash('sha256').update(str).digest('hex');
+  }
+}
+
+export default DiskStore;

package/src/cache/manager.mjs

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Cache orchestration - coordinates memory and disk stores.
+ * @module cache/manager
+ */
+
+import crypto from 'node:crypto';
+import { MemoryStore } from './memory-store.mjs';
+import { DiskStore } from './disk-store.mjs';
+
+export class CacheManager {
+  /**
+   * Create a new CacheManager.
+   * @param {Object} [options]
+   * @param {number} [options.memoryMaxSize=1000] - Memory cache max entries
+   * @param {number} [options.memoryTTL=300000] - Memory TTL (5 min)
+   * @param {number} [options.diskTTL=3600000] - Disk TTL (1 hour)
+   * @param {string} [options.cacheDir='.prepia/cache'] - Disk cache directory
+   * @param {boolean} [options.enableDisk=true] - Enable disk persistence
+   */
+  constructor(options = {}) {
+    this.memory = new MemoryStore({
+      maxSize: options.memoryMaxSize ?? 1000,
+      defaultTTL: options.memoryTTL ?? 5 * 60 * 1000,
+    });
+    this.disk = new DiskStore({
+      cacheDir: options.cacheDir ?? '.prepia/cache',
+      defaultTTL: options.diskTTL ?? 60 * 60 * 1000,
+    });
+    this._enableDisk = options.enableDisk ?? true;
+  }
+
+  /**
+   * Generate a cache key from task parameters.
+   * @param {Object|string} params
+   * @returns {string}
+   */
+  generateKey(params) {
+    const str = typeof params === 'string' ? params : JSON.stringify(params, Object.keys(params).sort());
+    return crypto.createHash('sha256').update(str).digest('hex');
+  }
+
+  /**
+   * Get a value - checks memory first, then disk.
+   * Populates memory from disk on disk hit.
+   * @param {string} key
+   * @returns {Promise<*>}
+   */
+  async get(key) {
+    // Try memory first
+    const memResult = this.memory.get(key);
+    if (memResult !== undefined) return memResult;
+
+    // Try disk if enabled
+    if (this._enableDisk) {
+      const diskResult = await this.disk.get(key);
+      if (diskResult !== undefined) {
+        // Promote to memory
+        this.memory.set(key, diskResult);
+        return diskResult;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Set a value in both memory and disk cache.
+   * @param {string} key
+   * @param {*} value
+   * @param {Object} [options]
+   * @param {number} [options.memoryTTL] - Memory TTL override
+   * @param {number} [options.diskTTL] - Disk TTL override
+   * @param {boolean} [options.memoryOnly=false] - Only store in memory
+   */
+  async set(key, value, options = {}) {
+    this.memory.set(key, value, options.memoryTTL);
+    if (this._enableDisk && !options.memoryOnly) {
+      await this.disk.set(key, value, options.diskTTL);
+    }
+  }
+
+  /**
+   * Check if key exists in either cache.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async has(key) {
+    if (this.memory.has(key)) return true;
+    if (this._enableDisk) return this.disk.has(key);
+    return false;
+  }
+
+  /**
+   * Delete a key from both caches.
+   * @param {string} key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    const memDeleted = this.memory.delete(key);
+    let diskDeleted = false;
+    if (this._enableDisk) {
+      diskDeleted = await this.disk.delete(key);
+    }
+    return memDeleted || diskDeleted;
+  }
+
+  /**
+   * Clear all caches.
+   */
+  async clear() {
+    this.memory.clear();
+    if (this._enableDisk) {
+      await this.disk.clear();
+    }
+  }
+
+  /**
+   * Cleanup expired entries from both caches.
+   * @returns {Promise<Object>} Cleanup stats
+   */
+  async cleanup() {
+    const memCleaned = this.memory.cleanup();
+    let diskCleaned = 0;
+    if (this._enableDisk) {
+      diskCleaned = await this.disk.cleanup();
+    }
+    return { memoryCleaned: memCleaned, diskCleaned };
+  }
+
+  /**
+   * Get combined stats.
+   * @returns {Object}
+   */
+  stats() {
+    return {
+      memory: this.memory.stats(),
+      diskEnabled: this._enableDisk,
+    };
+  }
+}
+
+export default CacheManager;

package/src/cache/memory-store.mjs

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview In-memory LRU cache with TTL support.
+ * @module cache/memory-store
+ */
+
+/**
+ * @typedef {Object} CacheEntry
+ * @property {*} value - Cached value
+ * @property {number} expiresAt - Expiration timestamp (ms)
+ * @property {number} createdAt - Creation timestamp (ms)
+ * @property {number} size - Estimated size in bytes
+ */
+
+/**
+ * @typedef {Object} CacheStats
+ * @property {number} hits - Cache hit count
+ * @property {number} misses - Cache miss count
+ * @property {number} evictions - Eviction count
+ * @property {number} sets - Set operation count
+ * @property {number} deletes - Delete operation count
+ * @property {number} size - Current entry count
+ * @property {number} maxSize - Maximum entries
+ */
+
+export class MemoryStore {
+  /**
+   * Create a new MemoryStore.
+   * @param {Object} [options]
+   * @param {number} [options.maxSize=1000] - Maximum number of entries
+   * @param {number} [options.defaultTTL=300000] - Default TTL in ms (5 min)
+   */
+  constructor(options = {}) {
+    this._maxSize = options.maxSize ?? 1000;
+    this._defaultTTL = options.defaultTTL ?? 5 * 60 * 1000;
+    /** @type {Map<string, CacheEntry>} */
+    this._store = new Map();
+    this._stats = { hits: 0, misses: 0, evictions: 0, sets: 0, deletes: 0 };
+  }
+
+  /**
+   * Get a value from cache.
+   * @param {string} key
+   * @returns {*} The cached value or undefined
+   */
+  get(key) {
+    const entry = this._store.get(key);
+    if (!entry) {
+      this._stats.misses++;
+      return undefined;
+    }
+    if (Date.now() > entry.expiresAt) {
+      this._store.delete(key);
+      this._stats.misses++;
+      return undefined;
+    }
+    // Move to end (most recently used) by re-inserting
+    this._store.delete(key);
+    this._store.set(key, entry);
+    this._stats.hits++;
+    return entry.value;
+  }
+
+  /**
+   * Set a value in cache.
+   * @param {string} key
+   * @param {*} value
+   * @param {number} [ttl] - TTL in ms, defaults to store default
+   */
+  set(key, value, ttl) {
+    const now = Date.now();
+    const effectiveTTL = ttl ?? this._defaultTTL;
+    const entry = {
+      value,
+      expiresAt: now + effectiveTTL,
+      createdAt: now,
+      size: this._estimateSize(value),
+    };
+
+    // If key exists, remove first to update position
+    if (this._store.has(key)) {
+      this._store.delete(key);
+    }
+
+    // Evict oldest if at capacity
+    while (this._store.size >= this._maxSize) {
+      const oldestKey = this._store.keys().next().value;
+      this._store.delete(oldestKey);
+      this._stats.evictions++;
+    }
+
+    this._store.set(key, entry);
+    this._stats.sets++;
+  }
+
+  /**
+   * Check if a key exists and is not expired.
+   * @param {string} key
+   * @returns {boolean}
+   */
+  has(key) {
+    const entry = this._store.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this._store.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Delete a key from cache.
+   * @param {string} key
+   * @returns {boolean} Whether the key existed
+   */
+  delete(key) {
+    const existed = this._store.delete(key);
+    if (existed) this._stats.deletes++;
+    return existed;
+  }
+
+  /**
+   * Clear all entries.
+   */
+  clear() {
+    this._store.clear();
+  }
+
+  /**
+   * Get the number of entries.
+   * @returns {number}
+   */
+  get size() {
+    return this._store.size;
+  }
+
+  /**
+   * Get cache statistics.
+   * @returns {CacheStats}
+   */
+  stats() {
+    return {
+      ...this._stats,
+      size: this._store.size,
+      maxSize: this._maxSize,
+    };
+  }
+
+  /**
+   * Reset statistics.
+   */
+  resetStats() {
+    this._stats = { hits: 0, misses: 0, evictions: 0, sets: 0, deletes: 0 };
+  }
+
+  /**
+   * Remove all expired entries.
+   * @returns {number} Number of entries removed
+   */
+  cleanup() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [key, entry] of this._store) {
+      if (now > entry.expiresAt) {
+        this._store.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  /**
+   * Get all keys (non-expired).
+   * @returns {string[]}
+   */
+  keys() {
+    const now = Date.now();
+    const result = [];
+    for (const [key, entry] of this._store) {
+      if (now <= entry.expiresAt) {
+        result.push(key);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Estimate size of a value in bytes.
+   * @param {*} value
+   * @returns {number}
+   * @private
+   */
+  _estimateSize(value) {
+    if (value === null || value === undefined) return 0;
+    if (typeof value === 'string') return value.length * 2;
+    if (typeof value === 'number') return 8;
+    if (typeof value === 'boolean') return 4;
+    try {
+      return JSON.stringify(value).length * 2;
+    } catch {
+      return 100;
+    }
+  }
+}
+
+export default MemoryStore;