@spfn/core 0.2.0-beta.67 → 0.2.0-beta.68

package/dist/middleware/index.d.ts

@@ -1,11 +1,6 @@
 import { Context, Next, MiddlewareHandler } from 'hono';
-import { b as NamedMiddlewareFactory, N as NamedMiddleware } from '../define-middleware-DuXD8Hvu.js';
-
-/**
- * Error Handler Middleware
- *
- * Handles SerializableError with automatic serialization and standard errors
- */
+import { N as NamedMiddlewareFactory, b as NamedMiddleware } from '../define-middleware-B9bFuXVU.js';
+import { Redis, Cluster } from 'ioredis';
 
 /**
  * Options for ErrorHandler middleware
@@ -27,6 +22,21 @@ interface ErrorHandlerOptions {
      * @default true
      */
     enableLogging?: boolean;
+    /**
+     * Attach the `error` envelope to every error response
+     *
+     * The envelope is `{ code, message, requestId }` sitting next to the
+     * existing `__type` and `message` fields, never replacing them: a web
+     * client restores its error class from `__type` while a generated client
+     * in another language classifies by `code` alone and cannot read a
+     * discriminator it has no registry for.
+     *
+     * Turn it off only to keep error bodies byte-identical to an older
+     * release. A route reached by a generated client needs it.
+     *
+     * @default true
+     */
+    errorEnvelope?: boolean;
     /**
      * Callback invoked when an error occurs
      *
@@ -57,6 +67,10 @@ interface OnErrorContext {
  * SerializableError instances are serialized using their toJSON() method,
  * preserving custom fields like `resource`, `fields`, etc.
  *
+ * Every response also carries an `error` envelope — `{ code, message,
+ * requestId }` — for clients that classify by a single documented field
+ * instead of restoring an error class from `__type`.
+ *
  * @param options - Configuration options
  * @returns Error handler function for Hono's onError hook
  *
@@ -76,7 +90,8 @@ interface OnErrorContext {
  * // Throw SerializableError in routes
  * app.get('/users/:id', (c) => {
  *     throw new NotFoundError({ message: 'User not found', resource: 'User' });
- *     // Response: { __type: 'NotFoundError', message: 'User not found', resource: 'User' }
+ *     // Response: { __type: 'NotFoundError', message: 'User not found', resource: 'User',
+ *     //             error: { code: 'NotFoundError', message: 'User not found', requestId: '…' } }
  * });
  * ```
  */
@@ -285,6 +300,8 @@ declare function createCacheNonceStore(cache: CacheClient, prefix?: string): Non
  */
 declare function createInMemoryNonceStore(): NonceStore;
 
+/** Test seam: forget every process-local window. */
+declare function resetMemoryRateLimitStore(): void;
 /**
  * One identity dimension to limit on. A bare string uses the top-level `limit`;
  * an object can carry its own `limit` so dimensions can differ (e.g. a loose
@@ -311,7 +328,11 @@ interface RateLimitOptions {
      * client IP only.
      */
     by?: (c: Context) => (RateLimitDimension | null | undefined)[] | Promise<(RateLimitDimension | null | undefined)[]>;
-    /** Reject with 429 instead of allowing through when the cache is unavailable. */
+    /**
+     * Refuse with 429 when the shared cache is unavailable, instead of counting
+     * in this process. For a surface where a per-process count is not an
+     * acceptable substitute for a shared one.
+     */
     failClosed?: boolean;
     /** Message for the 429 response. */
     message?: string;
@@ -333,7 +354,8 @@ interface RateLimitOptions {
  */
 declare function getClientIp(c: Context): string;
 /**
- * Redis-backed fixed-window rate limiter.
+ * Fixed-window rate limiter — counters in the shared cache when there is one,
+ * in this process otherwise.
  *
  * @example
  * ```typescript
@@ -380,4 +402,79 @@ declare function getRateLimitPolicy(name: string): RateLimitOptions | undefined;
  */
 declare function rateLimitPolicy(name: string, fallback: RateLimitOptions): NamedMiddleware<string>;
 
-export { type ClientType, ErrorHandler, type ErrorHandlerOptions, type NonceStore, type OnErrorContext, type ProxyGuardConfig, type ProxyGuardMode, type RateLimitDimension, type RateLimitOptions, RequestLogger, type RequestLoggerConfig, type RequestLoggerOptions, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, getRateLimitPolicy, maskSensitiveData, rateLimit, rateLimitPolicy, setRateLimitFailClosedDefault, setRateLimitPolicies };
+/**
+ * The rate limiter's fixed-window counter as a pluggable store — the same
+ * pattern the clientProofV1 replay ledger and the SSE token manager already
+ * use: an in-memory default, a Redis/Valkey store on top of `getCache()`, and
+ * the cache's presence deciding which one a request gets.
+ *
+ * Why the memory default exists: without it, "no cache configured" and "cache
+ * down" both meant the limiter had nowhere to count, so the only choices were
+ * letting every request through or refusing every request. Neither is what a
+ * limiter is for. Counting in the process is worse than counting in Redis and
+ * far better than not counting.
+ *
+ * What the memory store cannot do is span processes. Behind N instances each
+ * keeps its own counters, so the effective limit is N times the configured one.
+ * That is the cost of the fallback and the reason a real deployment still
+ * points `CACHE_URL` at Redis.
+ *
+ * @module middleware/rate-limit-store
+ */
+
+/** One window's state for a key: how many hits, and how long the window has left. */
+interface RateLimitHit {
+    count: number;
+    /** Milliseconds until the window resets. */
+    pttl: number;
+}
+/** What the limiter needs from wherever the counters live. */
+interface RateLimitStore {
+    /** Records one hit against `key` and answers the window's state after it. */
+    hit(key: string, windowMs: number): Promise<RateLimitHit>;
+}
+/**
+ * Counters in Redis — shared by every instance, so the configured limit is the
+ * limit no matter how many processes serve the traffic.
+ */
+declare class CacheRateLimitStore implements RateLimitStore {
+    private readonly cache;
+    constructor(cache: Redis | Cluster);
+    hit(key: string, windowMs: number): Promise<RateLimitHit>;
+}
+/**
+ * Counters in this process.
+ *
+ * Entries are pruned lazily — a key past its window resets on its next hit, so
+ * the common path stays O(1). Keys nobody touches again would otherwise sit
+ * there forever, so a full sweep runs once the map crosses `maxKeys`; that
+ * bound is what keeps a limiter keyed by client IP from growing without end.
+ */
+declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly maxKeys;
+    private readonly windows;
+    /** How many live windows were dropped to stay under `maxKeys`. */
+    private evicted;
+    constructor(maxKeys?: number);
+    hit(key: string, windowMs: number): Promise<RateLimitHit>;
+    /** Drops every window that has already reset. */
+    prune(nowMillis: number): void;
+    /**
+     * Frees a slot for a new key.
+     *
+     * Expired windows go first. If every window is still live the oldest one is
+     * dropped, because a hard bound is the only thing standing between a
+     * per-IP limiter and unbounded memory. A dropped window loses its count,
+     * so a caller who can mint `maxKeys` distinct identities can push another
+     * one out — which is why `evictionCount` is worth watching: it says this
+     * process is past what an in-memory limiter should be asked to hold, and
+     * the deployment wants a real cache.
+     */
+    private makeRoom;
+    get size(): number;
+    /** Live windows dropped for capacity — nonzero means the bound is binding. */
+    get evictionCount(): number;
+    clear(): void;
+}
+
+export { CacheRateLimitStore, type ClientType, ErrorHandler, type ErrorHandlerOptions, MemoryRateLimitStore, type NonceStore, type OnErrorContext, type ProxyGuardConfig, type ProxyGuardMode, type RateLimitDimension, type RateLimitHit, type RateLimitOptions, type RateLimitStore, RequestLogger, type RequestLoggerConfig, type RequestLoggerOptions, createCacheNonceStore, createInMemoryNonceStore, createProxyGuard, getClientIp, getRateLimitPolicy, maskSensitiveData, rateLimit, rateLimitPolicy, resetMemoryRateLimitStore, setRateLimitFailClosedDefault, setRateLimitPolicies };