@criterionx/server 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -1,6 +1,7 @@
+import * as hono from 'hono';
+import { Context, Next, Hono } from 'hono';
 import { Decision, Result, JsonSchema } from '@criterionx/core';
 export { DecisionSchema, JsonSchema, extractDecisionSchema, toJsonSchema } from '@criterionx/core';
-import { Hono } from 'hono';
 
 /**
  * Context passed to hooks
@@ -58,6 +59,74 @@ interface MetricsOptions$1 {
     /** Histogram buckets for latency in seconds */
     buckets?: number[];
 }
+/**
+ * Log entry emitted for each evaluation request
+ */
+interface LogEntry {
+    /** Unique request identifier */
+    requestId: string;
+    /** ID of the decision that was evaluated */
+    decisionId: string;
+    /** Result status or ERROR */
+    status: "OK" | "NO_MATCH" | "INVALID_INPUT" | "INVALID_OUTPUT" | "ERROR";
+    /** Duration of the evaluation in milliseconds */
+    durationMs: number;
+    /** ISO timestamp when the request completed */
+    timestamp: string;
+}
+/**
+ * Logger function type - user provides their own implementation
+ */
+type LoggerFn = (entry: LogEntry) => void;
+/**
+ * Logging configuration options
+ */
+interface LoggingOptions {
+    /** Enable request logging (default: false) */
+    enabled?: boolean;
+    /** Custom logger function - receives structured log entries */
+    logger: LoggerFn;
+}
+/**
+ * Rate limit info returned by store
+ */
+interface RateLimitInfo {
+    /** Current request count in window */
+    count: number;
+    /** Unix timestamp (ms) when window resets */
+    resetTime: number;
+}
+/**
+ * Rate limit store interface for custom implementations
+ *
+ * Implement this interface to use external stores like Redis
+ * for distributed rate limiting.
+ */
+interface RateLimitStore {
+    /** Increment counter for key and return current info */
+    increment(key: string): Promise<RateLimitInfo>;
+    /** Reset counter for key */
+    reset(key: string): Promise<void>;
+}
+/**
+ * Rate limiting configuration options
+ */
+interface RateLimitOptions {
+    /** Enable rate limiting (default: false) */
+    enabled?: boolean;
+    /** Time window in milliseconds (default: 60000 = 1 minute) */
+    windowMs?: number;
+    /** Maximum requests per window (default: 100) */
+    max?: number;
+    /** Custom key generator function (default: client IP) */
+    keyGenerator?: (c: hono.Context) => string;
+    /** Custom handler for rate limit exceeded (default: 429 JSON response) */
+    handler?: (c: hono.Context) => Response;
+    /** Skip rate limiting for certain requests (default: skip /health, /metrics) */
+    skip?: (c: hono.Context) => boolean;
+    /** Custom store for distributed rate limiting (default: in-memory) */
+    store?: RateLimitStore;
+}
 /**
  * OpenAPI info object
  */
@@ -111,6 +180,10 @@ interface ServerOptions {
     metrics?: MetricsOptions$1;
     /** OpenAPI spec generation configuration */
     openapi?: OpenAPIOptions;
+    /** Request logging configuration */
+    logging?: LoggingOptions;
+    /** Rate limiting configuration */
+    rateLimit?: RateLimitOptions;
 }
 /**
  * Request body for decision evaluation
@@ -118,8 +191,28 @@ interface ServerOptions {
 interface EvaluateRequest {
     /** Input data for the decision */
     input: unknown;
-    /** Profile to use (overrides default) */
+    /** Profile to use (overrides default and profileVersion) */
     profile?: unknown;
+    /** Profile version to use (e.g., "v1", "conservative") */
+    profileVersion?: string;
+}
+/**
+ * Profile version info for listing
+ */
+interface ProfileVersionInfo {
+    /** Version identifier (null for default) */
+    version: string | null;
+    /** Whether this is the default profile */
+    isDefault: boolean;
+}
+/**
+ * Response for listing profile versions
+ */
+interface ProfileListResponse {
+    /** Decision ID */
+    decisionId: string;
+    /** Available profile versions */
+    versions: ProfileVersionInfo[];
 }
 /**
  * Decision info for listing
@@ -133,7 +226,7 @@ interface DecisionInfo {
 /**
  * Error codes for structured error responses
  */
-type ErrorCode = "DECISION_NOT_FOUND" | "INVALID_JSON" | "MISSING_INPUT" | "MISSING_PROFILE" | "VALIDATION_ERROR" | "EVALUATION_ERROR" | "INTERNAL_ERROR";
+type ErrorCode = "DECISION_NOT_FOUND" | "INVALID_JSON" | "MISSING_INPUT" | "MISSING_PROFILE" | "VALIDATION_ERROR" | "EVALUATION_ERROR" | "INTERNAL_ERROR" | "RATE_LIMIT_EXCEEDED";
 /**
  * Structured error response
  */
@@ -266,9 +359,9 @@ interface Operation {
             };
         };
     };
-    responses: Record<string, Response>;
+    responses: Record<string, Response$1>;
 }
-interface Response {
+interface Response$1 {
     description: string;
     content?: {
         "application/json": {
@@ -287,6 +380,40 @@ declare function generateOpenAPISpec(decisions: Decision<any, any, any>[], info?
  */
 declare function generateSwaggerUIHtml(specUrl: string): string;
 
+/**
+ * Default in-memory rate limit store
+ *
+ * Simple implementation for single-instance deployments.
+ * For distributed deployments, use a custom store (e.g., Redis).
+ */
+declare class InMemoryRateLimitStore implements RateLimitStore {
+    private hits;
+    private windowMs;
+    constructor(windowMs: number);
+    increment(key: string): Promise<RateLimitInfo>;
+    reset(key: string): Promise<void>;
+    /**
+     * Get current info for a key (for testing/debugging)
+     */
+    getInfo(key: string): RateLimitInfo | undefined;
+    /**
+     * Clear all entries (for testing)
+     */
+    clear(): void;
+}
+/**
+ * Create rate limiting middleware for Hono
+ *
+ * @example
+ * ```typescript
+ * app.use("*", createRateLimitMiddleware({
+ *   windowMs: 60000,  // 1 minute
+ *   max: 100,         // 100 requests per window
+ * }));
+ * ```
+ */
+declare function createRateLimitMiddleware(options: RateLimitOptions): (c: Context, next: Next) => Promise<void | Response>;
+
 /**
  * Criterion Server
  *
@@ -302,9 +429,14 @@ declare class CriterionServer {
     private metricsOptions;
     private openApiOptions;
     private openApiSpec;
+    private loggingOptions;
     private startTime;
     constructor(options: ServerOptions);
     private setupRoutes;
+    /**
+     * Get available profile versions for a decision
+     */
+    private getProfileVersions;
     private generateDocsHtml;
     /**
      * Get the Hono app instance (for custom middleware)
@@ -324,4 +456,4 @@ declare class CriterionServer {
  */
 declare function createServer(options: ServerOptions): CriterionServer;
 
-export { type AfterEvaluateHook, type BeforeEvaluateHook, CriterionServer, type DecisionInfo, type ErrorCode, type ErrorResponse, type EvaluateRequest, type HealthResponse, type HealthStatus, type HookContext, type Hooks, METRIC_EVALUATIONS_TOTAL, METRIC_EVALUATION_DURATION_SECONDS, METRIC_RULE_MATCHES_TOTAL, MetricsCollector, type MetricsOptions$1 as MetricsOptions, type OnErrorHook, type OpenAPIInfo, type OpenAPIOptions, type OpenAPISpec, type ServerOptions, createServer, generateEndpointSchema, generateOpenAPISpec, generateSwaggerUIHtml };
+export { type AfterEvaluateHook, type BeforeEvaluateHook, CriterionServer, type DecisionInfo, type ErrorCode, type ErrorResponse, type EvaluateRequest, type HealthResponse, type HealthStatus, type HookContext, type Hooks, InMemoryRateLimitStore, type LogEntry, type LoggerFn, type LoggingOptions, METRIC_EVALUATIONS_TOTAL, METRIC_EVALUATION_DURATION_SECONDS, METRIC_RULE_MATCHES_TOTAL, MetricsCollector, type MetricsOptions$1 as MetricsOptions, type OnErrorHook, type OpenAPIInfo, type OpenAPIOptions, type OpenAPISpec, type ProfileListResponse, type ProfileVersionInfo, type RateLimitInfo, type RateLimitOptions, type RateLimitStore, type ServerOptions, createRateLimitMiddleware, createServer, generateEndpointSchema, generateOpenAPISpec, generateSwaggerUIHtml };

package/dist/index.js

@@ -452,6 +452,84 @@ function generateSwaggerUIHtml(specUrl) {
 </html>`;
 }
 
+// src/rate-limit.ts
+var InMemoryRateLimitStore = class {
+  hits = /* @__PURE__ */ new Map();
+  windowMs;
+  constructor(windowMs) {
+    this.windowMs = windowMs;
+  }
+  async increment(key) {
+    const now = Date.now();
+    const record = this.hits.get(key);
+    if (!record || now >= record.resetTime) {
+      const resetTime = now + this.windowMs;
+      this.hits.set(key, { count: 1, resetTime });
+      return { count: 1, resetTime };
+    }
+    record.count++;
+    return { count: record.count, resetTime: record.resetTime };
+  }
+  async reset(key) {
+    this.hits.delete(key);
+  }
+  /**
+   * Get current info for a key (for testing/debugging)
+   */
+  getInfo(key) {
+    return this.hits.get(key);
+  }
+  /**
+   * Clear all entries (for testing)
+   */
+  clear() {
+    this.hits.clear();
+  }
+};
+function defaultKeyGenerator(c) {
+  return c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";
+}
+function defaultSkip(c) {
+  const path = c.req.path;
+  return path === "/health" || path === "/metrics";
+}
+function createRateLimitMiddleware(options) {
+  const windowMs = options.windowMs ?? 6e4;
+  const max = options.max ?? 100;
+  const store = options.store ?? new InMemoryRateLimitStore(windowMs);
+  const keyGenerator = options.keyGenerator ?? defaultKeyGenerator;
+  const skip = options.skip ?? defaultSkip;
+  return async (c, next) => {
+    if (skip(c)) {
+      return next();
+    }
+    const key = keyGenerator(c);
+    const info = await store.increment(key);
+    c.header("X-RateLimit-Limit", String(max));
+    c.header("X-RateLimit-Remaining", String(Math.max(0, max - info.count)));
+    c.header("X-RateLimit-Reset", String(Math.floor(info.resetTime / 1e3)));
+    if (info.count > max) {
+      const retryAfter = Math.max(1, Math.ceil((info.resetTime - Date.now()) / 1e3));
+      c.header("Retry-After", String(retryAfter));
+      if (options.handler) {
+        return options.handler(c);
+      }
+      return c.json(
+        {
+          error: {
+            code: "RATE_LIMIT_EXCEEDED",
+            message: "Too many requests, please try again later"
+          },
+          retryAfter,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        429
+      );
+    }
+    return next();
+  };
+}
+
 // src/server.ts
 import { Hono } from "hono";
 import { cors } from "hono/cors";
@@ -483,6 +561,7 @@ var CriterionServer = class {
   metricsOptions;
   openApiOptions;
   openApiSpec = null;
+  loggingOptions = null;
   startTime;
   constructor(options) {
     this.app = new Hono();
@@ -496,6 +575,9 @@ var CriterionServer = class {
     if (this.metricsOptions.enabled) {
       this.metricsCollector = new MetricsCollector(this.metricsOptions);
     }
+    if (options.logging?.enabled) {
+      this.loggingOptions = options.logging;
+    }
     for (const decision of options.decisions) {
       this.decisions.set(decision.id, decision);
     }
@@ -513,6 +595,9 @@ var CriterionServer = class {
     if (options.cors !== false) {
       this.app.use("*", cors());
     }
+    if (options.rateLimit?.enabled) {
+      this.app.use("*", createRateLimitMiddleware(options.rateLimit));
+    }
     this.setupRoutes();
   }
   setupRoutes() {
@@ -628,16 +713,31 @@ var CriterionServer = class {
       }
       let profile = body.profile;
       if (!profile) {
-        profile = this.profiles.get(id);
-        if (!profile) {
-          return c.json(
-            createErrorResponse(
-              "MISSING_PROFILE",
-              `No profile provided and no default profile for decision: ${id}`,
-              requestId
-            ),
-            400
-          );
+        if (body.profileVersion) {
+          const versionedKey = `${id}:${body.profileVersion}`;
+          profile = this.profiles.get(versionedKey);
+          if (!profile) {
+            return c.json(
+              createErrorResponse(
+                "MISSING_PROFILE",
+                `Profile version not found: ${body.profileVersion} for decision: ${id}`,
+                requestId
+              ),
+              400
+            );
+          }
+        } else {
+          profile = this.profiles.get(id);
+          if (!profile) {
+            return c.json(
+              createErrorResponse(
+                "MISSING_PROFILE",
+                `No profile provided and no default profile for decision: ${id}`,
+                requestId
+              ),
+              400
+            );
+          }
         }
       }
       let ctx = {
@@ -679,6 +779,16 @@ var CriterionServer = class {
         if (this.hooks.afterEvaluate) {
           await this.hooks.afterEvaluate(ctx, result);
         }
+        if (this.loggingOptions) {
+          const entry = {
+            requestId,
+            decisionId: id,
+            status: result.status,
+            durationMs: performance.now() - startTime,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          this.loggingOptions.logger(entry);
+        }
         const statusCode = result.status === "OK" ? 200 : 400;
         return c.json(result, statusCode);
       } catch (error) {
@@ -692,6 +802,16 @@ var CriterionServer = class {
         if (this.hooks.onError) {
           await this.hooks.onError(ctx, err);
         }
+        if (this.loggingOptions) {
+          const entry = {
+            requestId,
+            decisionId: id,
+            status: "ERROR",
+            durationMs: performance.now() - startTime,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          this.loggingOptions.logger(entry);
+        }
         return c.json(
           createErrorResponse(
             "EVALUATION_ERROR",
@@ -703,6 +823,18 @@ var CriterionServer = class {
         );
       }
     });
+    this.app.get("/decisions/:id/profiles", (c) => {
+      const id = c.req.param("id");
+      const decision = this.decisions.get(id);
+      if (!decision) {
+        return c.json(
+          createErrorResponse("DECISION_NOT_FOUND", `Decision not found: ${id}`),
+          404
+        );
+      }
+      const versions = this.getProfileVersions(id);
+      return c.json({ decisionId: id, versions });
+    });
     this.app.get("/docs", (c) => {
       const decisions = Array.from(this.decisions.values()).map((d) => ({
         id: d.id,
@@ -713,6 +845,23 @@ var CriterionServer = class {
       return c.html(html);
     });
   }
+  /**
+   * Get available profile versions for a decision
+   */
+  getProfileVersions(decisionId) {
+    const versions = [];
+    const prefix = `${decisionId}:`;
+    if (this.profiles.has(decisionId)) {
+      versions.push({ version: null, isDefault: true });
+    }
+    for (const key of this.profiles.keys()) {
+      if (key.startsWith(prefix)) {
+        const version = key.slice(prefix.length);
+        versions.push({ version, isDefault: false });
+      }
+    }
+    return versions;
+  }
   generateDocsHtml(decisions) {
     return `<!DOCTYPE html>
 <html lang="en">
@@ -956,10 +1105,12 @@ function createServer(options) {
 }
 export {
   CriterionServer,
+  InMemoryRateLimitStore,
   METRIC_EVALUATIONS_TOTAL,
   METRIC_EVALUATION_DURATION_SECONDS,
   METRIC_RULE_MATCHES_TOTAL,
   MetricsCollector,
+  createRateLimitMiddleware,
   createServer,
   extractDecisionSchema,
   generateEndpointSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@criterionx/server",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "HTTP server for Criterion decisions with auto-generated docs",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,7 @@
     "@hono/node-server": "^1.13.0",
     "hono": "^4.6.0",
     "zod-to-json-schema": "^3.24.0",
-    "@criterionx/core": "0.3.2"
+    "@criterionx/core": "0.3.4"
   },
   "peerDependencies": {
     "zod": "^3.22.0"