@open-mercato/shared 0.6.8-develop.6963.1.04a6d320e9 → 0.6.8-develop.6964.1.36b364cfd8

package/dist/lib/ratelimit/helpers.js

@@ -3,11 +3,19 @@ import { z } from "zod";
 const RATE_LIMIT_ERROR_KEY = "api.errors.rateLimit";
 const RATE_LIMIT_ERROR_FALLBACK = "Too many requests. Please try again later.";
 const RATE_LIMIT_FALLBACK_KEY = "global";
+const RATE_LIMIT_UNAVAILABLE_KEY = "api.errors.rateLimitUnavailable";
+const RATE_LIMIT_UNAVAILABLE_FALLBACK = "Service temporarily unavailable. Please try again later.";
 const rateLimitErrorSchema = z.object({
   error: z.string().describe("Rate limit exceeded message")
 });
-async function checkRateLimit(rateLimiterService, config, key, errorMessage) {
+async function checkRateLimit(rateLimiterService, config, key, errorMessage, options = {}) {
   const result = await rateLimiterService.consume(key, config);
+  if (result.degraded && options.failClosed) {
+    return NextResponse.json(
+      { error: options.unavailableMessage ?? RATE_LIMIT_UNAVAILABLE_FALLBACK },
+      { status: 503 }
+    );
+  }
   if (!result.allowed) {
     const retryAfterSec = Math.ceil(result.msBeforeNext / 1e3);
     return NextResponse.json(
@@ -41,6 +49,8 @@ export {
   RATE_LIMIT_ERROR_FALLBACK,
   RATE_LIMIT_ERROR_KEY,
   RATE_LIMIT_FALLBACK_KEY,
+  RATE_LIMIT_UNAVAILABLE_FALLBACK,
+  RATE_LIMIT_UNAVAILABLE_KEY,
   checkRateLimit,
   getClientIp,
   rateLimitErrorSchema

package/dist/lib/ratelimit/helpers.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/ratelimit/helpers.ts"],
-  "sourcesContent": ["import { NextResponse } from 'next/server'\nimport { z } from 'zod'\nimport type { RateLimitConfig } from './types'\nimport type { RateLimiterService } from './service'\n\nexport const RATE_LIMIT_ERROR_KEY = 'api.errors.rateLimit'\nexport const RATE_LIMIT_ERROR_FALLBACK = 'Too many requests. Please try again later.'\nexport const RATE_LIMIT_FALLBACK_KEY = 'global'\n\nexport const rateLimitErrorSchema = z.object({\n  error: z.string().describe('Rate limit exceeded message'),\n})\n\n/**\n * Check rate limit for a request. Returns a 429 NextResponse if rate limited, or null if allowed.\n * Rate limit headers (X-RateLimit-*, Retry-After) are only included on 429 responses.\n */\nexport async function checkRateLimit(\n  rateLimiterService: RateLimiterService,\n  config: RateLimitConfig,\n  key: string,\n  errorMessage: string,\n): Promise<NextResponse | null> {\n  const result = await rateLimiterService.consume(key, config)\n\n  if (!result.allowed) {\n    const retryAfterSec = Math.ceil(result.msBeforeNext / 1000)\n    return NextResponse.json(\n      { error: errorMessage },\n      {\n        status: 429,\n        headers: {\n          'Retry-After': String(retryAfterSec),\n          'X-RateLimit-Limit': String(config.points),\n          'X-RateLimit-Remaining': String(result.remainingPoints),\n          'X-RateLimit-Reset': String(retryAfterSec),\n        },\n      },\n    )\n  }\n\n  return null\n}\n\n/**\n * Extract client IP from a request, respecting reverse proxy trust depth.\n *\n * @param trustProxyDepth Number of trusted reverse proxies between the client and the app.\n *   - 0 (default): Do not trust proxy-provided IP headers; return null.\n *   - 1: One trusted proxy (e.g. nginx) \u2014 the last entry in X-Forwarded-For is the client IP;\n *     X-Real-IP is accepted only as a single-proxy fallback when X-Forwarded-For is absent.\n *   - N: N trusted proxies \u2014 the Nth-from-last entry is the client IP. If the\n *     forwarded chain is shorter than N, return null rather than trusting an\n *     attacker-controlled entry.\n *\n * With depth=0, X-Forwarded-For and X-Real-IP are ignored entirely to prevent spoofing.\n */\nexport function getClientIp(req: Request, trustProxyDepth: number = 0): string | null {\n  const forwarded = req.headers.get('x-forwarded-for')\n  if (!Number.isInteger(trustProxyDepth) || trustProxyDepth <= 0) {\n    return null\n  }\n\n  if (forwarded) {\n    const ips = forwarded.split(',').map((ip) => ip.trim())\n    const clientIndex = ips.length - trustProxyDepth\n    return clientIndex >= 0 ? ips[clientIndex] || null : null\n  }\n  return trustProxyDepth === 1 ? req.headers.get('x-real-ip')?.trim() || null : null\n}\n"],
-  "mappings": "AAAA,SAAS,oBAAoB;AAC7B,SAAS,SAAS;AAIX,MAAM,uBAAuB;AAC7B,MAAM,4BAA4B;AAClC,MAAM,0BAA0B;AAEhC,MAAM,uBAAuB,EAAE,OAAO;AAAA,EAC3C,OAAO,EAAE,OAAO,EAAE,SAAS,6BAA6B;AAC1D,CAAC;AAMD,eAAsB,eACpB,oBACA,QACA,KACA,cAC8B;AAC9B,QAAM,SAAS,MAAM,mBAAmB,QAAQ,KAAK,MAAM;AAE3D,MAAI,CAAC,OAAO,SAAS;AACnB,UAAM,gBAAgB,KAAK,KAAK,OAAO,eAAe,GAAI;AAC1D,WAAO,aAAa;AAAA,MAClB,EAAE,OAAO,aAAa;AAAA,MACtB;AAAA,QACE,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,OAAO,aAAa;AAAA,UACnC,qBAAqB,OAAO,OAAO,MAAM;AAAA,UACzC,yBAAyB,OAAO,OAAO,eAAe;AAAA,UACtD,qBAAqB,OAAO,aAAa;AAAA,QAC3C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAeO,SAAS,YAAY,KAAc,kBAA0B,GAAkB;AACpF,QAAM,YAAY,IAAI,QAAQ,IAAI,iBAAiB;AACnD,MAAI,CAAC,OAAO,UAAU,eAAe,KAAK,mBAAmB,GAAG;AAC9D,WAAO;AAAA,EACT;AAEA,MAAI,WAAW;AACb,UAAM,MAAM,UAAU,MAAM,GAAG,EAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;AACtD,UAAM,cAAc,IAAI,SAAS;AACjC,WAAO,eAAe,IAAI,IAAI,WAAW,KAAK,OAAO;AAAA,EACvD;AACA,SAAO,oBAAoB,IAAI,IAAI,QAAQ,IAAI,WAAW,GAAG,KAAK,KAAK,OAAO;AAChF;",
+  "sourcesContent": ["import { NextResponse } from 'next/server'\nimport { z } from 'zod'\nimport type { RateLimitConfig } from './types'\nimport type { RateLimiterService } from './service'\n\nexport const RATE_LIMIT_ERROR_KEY = 'api.errors.rateLimit'\nexport const RATE_LIMIT_ERROR_FALLBACK = 'Too many requests. Please try again later.'\nexport const RATE_LIMIT_FALLBACK_KEY = 'global'\nexport const RATE_LIMIT_UNAVAILABLE_KEY = 'api.errors.rateLimitUnavailable'\nexport const RATE_LIMIT_UNAVAILABLE_FALLBACK = 'Service temporarily unavailable. Please try again later.'\n\nexport const rateLimitErrorSchema = z.object({\n  error: z.string().describe('Rate limit exceeded message'),\n})\n\nexport type CheckRateLimitOptions = {\n  /**\n   * Reject with 503 when the limiter could not reach its backing store, instead of\n   * letting the request through uncounted. Use on state-mutating endpoints, where an\n   * unenforced limit is worse than a rejected request.\n   */\n  failClosed?: boolean\n  /** Body message for the 503 emitted by `failClosed`. */\n  unavailableMessage?: string\n}\n\n/**\n * Check rate limit for a request. Returns a 429 NextResponse if rate limited, or null if allowed.\n * Rate limit headers (X-RateLimit-*, Retry-After) are only included on 429 responses.\n *\n * With `options.failClosed`, a degraded limiter (backing store unreachable) yields a 503\n * instead of an allowed request. Without it the call behaves exactly as before and fails open.\n */\nexport async function checkRateLimit(\n  rateLimiterService: RateLimiterService,\n  config: RateLimitConfig,\n  key: string,\n  errorMessage: string,\n  options: CheckRateLimitOptions = {},\n): Promise<NextResponse | null> {\n  const result = await rateLimiterService.consume(key, config)\n\n  if (result.degraded && options.failClosed) {\n    return NextResponse.json(\n      { error: options.unavailableMessage ?? RATE_LIMIT_UNAVAILABLE_FALLBACK },\n      { status: 503 },\n    )\n  }\n\n  if (!result.allowed) {\n    const retryAfterSec = Math.ceil(result.msBeforeNext / 1000)\n    return NextResponse.json(\n      { error: errorMessage },\n      {\n        status: 429,\n        headers: {\n          'Retry-After': String(retryAfterSec),\n          'X-RateLimit-Limit': String(config.points),\n          'X-RateLimit-Remaining': String(result.remainingPoints),\n          'X-RateLimit-Reset': String(retryAfterSec),\n        },\n      },\n    )\n  }\n\n  return null\n}\n\n/**\n * Extract client IP from a request, respecting reverse proxy trust depth.\n *\n * @param trustProxyDepth Number of trusted reverse proxies between the client and the app.\n *   - 0 (default): Do not trust proxy-provided IP headers; return null.\n *   - 1: One trusted proxy (e.g. nginx) \u2014 the last entry in X-Forwarded-For is the client IP;\n *     X-Real-IP is accepted only as a single-proxy fallback when X-Forwarded-For is absent.\n *   - N: N trusted proxies \u2014 the Nth-from-last entry is the client IP. If the\n *     forwarded chain is shorter than N, return null rather than trusting an\n *     attacker-controlled entry.\n *\n * With depth=0, X-Forwarded-For and X-Real-IP are ignored entirely to prevent spoofing.\n */\nexport function getClientIp(req: Request, trustProxyDepth: number = 0): string | null {\n  const forwarded = req.headers.get('x-forwarded-for')\n  if (!Number.isInteger(trustProxyDepth) || trustProxyDepth <= 0) {\n    return null\n  }\n\n  if (forwarded) {\n    const ips = forwarded.split(',').map((ip) => ip.trim())\n    const clientIndex = ips.length - trustProxyDepth\n    return clientIndex >= 0 ? ips[clientIndex] || null : null\n  }\n  return trustProxyDepth === 1 ? req.headers.get('x-real-ip')?.trim() || null : null\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAC7B,SAAS,SAAS;AAIX,MAAM,uBAAuB;AAC7B,MAAM,4BAA4B;AAClC,MAAM,0BAA0B;AAChC,MAAM,6BAA6B;AACnC,MAAM,kCAAkC;AAExC,MAAM,uBAAuB,EAAE,OAAO;AAAA,EAC3C,OAAO,EAAE,OAAO,EAAE,SAAS,6BAA6B;AAC1D,CAAC;AAoBD,eAAsB,eACpB,oBACA,QACA,KACA,cACA,UAAiC,CAAC,GACJ;AAC9B,QAAM,SAAS,MAAM,mBAAmB,QAAQ,KAAK,MAAM;AAE3D,MAAI,OAAO,YAAY,QAAQ,YAAY;AACzC,WAAO,aAAa;AAAA,MAClB,EAAE,OAAO,QAAQ,sBAAsB,gCAAgC;AAAA,MACvE,EAAE,QAAQ,IAAI;AAAA,IAChB;AAAA,EACF;AAEA,MAAI,CAAC,OAAO,SAAS;AACnB,UAAM,gBAAgB,KAAK,KAAK,OAAO,eAAe,GAAI;AAC1D,WAAO,aAAa;AAAA,MAClB,EAAE,OAAO,aAAa;AAAA,MACtB;AAAA,QACE,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,OAAO,aAAa;AAAA,UACnC,qBAAqB,OAAO,OAAO,MAAM;AAAA,UACzC,yBAAyB,OAAO,OAAO,eAAe;AAAA,UACtD,qBAAqB,OAAO,aAAa;AAAA,QAC3C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;AAeO,SAAS,YAAY,KAAc,kBAA0B,GAAkB;AACpF,QAAM,YAAY,IAAI,QAAQ,IAAI,iBAAiB;AACnD,MAAI,CAAC,OAAO,UAAU,eAAe,KAAK,mBAAmB,GAAG;AAC9D,WAAO;AAAA,EACT;AAEA,MAAI,WAAW;AACb,UAAM,MAAM,UAAU,MAAM,GAAG,EAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;AACtD,UAAM,cAAc,IAAI,SAAS;AACjC,WAAO,eAAe,IAAI,IAAI,WAAW,KAAK,OAAO;AAAA,EACvD;AACA,SAAO,oBAAoB,IAAI,IAAI,QAAQ,IAAI,WAAW,GAAG,KAAK,KAAK,OAAO;AAChF;",
   "names": []
 }

package/dist/lib/ratelimit/index.js

@@ -1,10 +1,12 @@
 import { RateLimiterService } from "./service.js";
 import { readRateLimitConfig, readEndpointRateLimitConfig } from "./config.js";
-import { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_FALLBACK_KEY, rateLimitErrorSchema } from "./helpers.js";
+import { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_FALLBACK_KEY, RATE_LIMIT_UNAVAILABLE_KEY, RATE_LIMIT_UNAVAILABLE_FALLBACK, rateLimitErrorSchema } from "./helpers.js";
 export {
   RATE_LIMIT_ERROR_FALLBACK,
   RATE_LIMIT_ERROR_KEY,
   RATE_LIMIT_FALLBACK_KEY,
+  RATE_LIMIT_UNAVAILABLE_FALLBACK,
+  RATE_LIMIT_UNAVAILABLE_KEY,
   RateLimiterService,
   checkRateLimit,
   getClientIp,

package/dist/lib/ratelimit/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/ratelimit/index.ts"],
-  "sourcesContent": ["export { RateLimiterService } from './service'\nexport { readRateLimitConfig, readEndpointRateLimitConfig } from './config'\nexport { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_FALLBACK_KEY, rateLimitErrorSchema } from './helpers'\nexport type { RateLimitConfig, RateLimitResult, RateLimitStrategy, RateLimitGlobalConfig } from './types'\n"],
-  "mappings": "AAAA,SAAS,0BAA0B;AACnC,SAAS,qBAAqB,mCAAmC;AACjE,SAAS,gBAAgB,aAAa,sBAAsB,2BAA2B,yBAAyB,4BAA4B;",
+  "sourcesContent": ["export { RateLimiterService } from './service'\nexport { readRateLimitConfig, readEndpointRateLimitConfig } from './config'\nexport { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_FALLBACK_KEY, RATE_LIMIT_UNAVAILABLE_KEY, RATE_LIMIT_UNAVAILABLE_FALLBACK, rateLimitErrorSchema } from './helpers'\nexport type { CheckRateLimitOptions } from './helpers'\nexport type { RateLimitConfig, RateLimitResult, RateLimitStrategy, RateLimitGlobalConfig } from './types'\n"],
+  "mappings": "AAAA,SAAS,0BAA0B;AACnC,SAAS,qBAAqB,mCAAmC;AACjE,SAAS,gBAAgB,aAAa,sBAAsB,2BAA2B,yBAAyB,4BAA4B,iCAAiC,4BAA4B;",
   "names": []
 }

package/dist/lib/ratelimit/service.js

@@ -1,5 +1,7 @@
 import { RateLimiterMemory, RateLimiterRedis, RateLimiterRes } from "rate-limiter-flexible";
+import { createLogger } from "../logger/index.js";
 import { parseRedisUrl } from "../redis/connection.js";
+const logger = createLogger("ratelimit");
 class RateLimiterService {
   constructor(globalConfig) {
     this.limiters = /* @__PURE__ */ new Map();
@@ -29,7 +31,12 @@ class RateLimiterService {
       if (error instanceof RateLimiterRes) {
         return this.toResult(error, false);
       }
-      return this.disabledResult(config);
+      logger.error("Rate limiter unavailable, request was not counted", {
+        err: error,
+        keyPrefix: config.keyPrefix,
+        strategy: this.globalConfig.strategy
+      });
+      return this.degradedResult(config);
     }
   }
   async get(key, config) {
@@ -73,6 +80,9 @@ class RateLimiterService {
   disabledResult(config) {
     return { allowed: true, remainingPoints: config.points, msBeforeNext: 0, consumedPoints: 0 };
   }
+  degradedResult(config) {
+    return { ...this.disabledResult(config), degraded: true };
+  }
   getOrCreateLimiter(config) {
     const cacheKey = `${config.keyPrefix ?? "default"}:${config.points}:${config.duration}:${config.blockDuration ?? 0}`;
     let limiter = this.limiters.get(cacheKey);

package/dist/lib/ratelimit/service.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/lib/ratelimit/service.ts"],
-  "sourcesContent": ["import { RateLimiterMemory, RateLimiterRedis, RateLimiterRes } from 'rate-limiter-flexible'\nimport { parseRedisUrl } from '../redis/connection'\nimport type { RateLimitConfig, RateLimitResult, RateLimitGlobalConfig } from './types'\n\n/** Narrow interface for the ioredis client \u2014 only the methods we actually use. */\ninterface RedisClient {\n  disconnect(): void\n}\n\nexport class RateLimiterService {\n  private globalConfig: RateLimitGlobalConfig\n  private limiters = new Map<string, RateLimiterMemory | RateLimiterRedis>()\n  private redisClient: RedisClient | null = null\n\n  readonly trustProxyDepth: number\n\n  constructor(globalConfig: RateLimitGlobalConfig) {\n    this.globalConfig = globalConfig\n    this.trustProxyDepth = globalConfig.trustProxyDepth ?? 0\n  }\n\n  async initialize(): Promise<void> {\n    if (this.globalConfig.strategy === 'redis' && this.globalConfig.redisUrl) {\n      const { default: Redis } = await import('ioredis')\n      this.redisClient = new Redis({\n        ...parseRedisUrl(this.globalConfig.redisUrl),\n        enableOfflineQueue: false,\n        maxRetriesPerRequest: 1,\n      })\n    }\n  }\n\n  async consume(key: string, config: RateLimitConfig): Promise<RateLimitResult> {\n    if (!this.globalConfig.enabled) {\n      return this.disabledResult(config)\n    }\n\n    const limiter = this.getOrCreateLimiter(config)\n\n    try {\n      const res = await limiter.consume(key, 1)\n      return this.toResult(res, true)\n    } catch (error) {\n      if (error instanceof RateLimiterRes) {\n        return this.toResult(error, false)\n      }\n      return this.disabledResult(config)\n    }\n  }\n\n  async get(key: string, config: RateLimitConfig): Promise<RateLimitResult | null> {\n    if (!this.globalConfig.enabled) return null\n\n    const limiter = this.getOrCreateLimiter(config)\n    const res = await limiter.get(key)\n    return res ? this.toResult(res, res.remainingPoints > 0) : null\n  }\n\n  async delete(key: string, config: RateLimitConfig): Promise<void> {\n    if (!this.globalConfig.enabled) return\n    const limiter = this.getOrCreateLimiter(config)\n    await limiter.delete(key)\n  }\n\n  async penalty(key: string, points: number, config: RateLimitConfig): Promise<RateLimitResult> {\n    if (!this.globalConfig.enabled) {\n      return this.disabledResult(config)\n    }\n    const limiter = this.getOrCreateLimiter(config)\n    const res = await limiter.penalty(key, points)\n    return this.toResult(res, res.remainingPoints > 0)\n  }\n\n  async reward(key: string, points: number, config: RateLimitConfig): Promise<RateLimitResult> {\n    if (!this.globalConfig.enabled) {\n      return this.disabledResult(config)\n    }\n    const limiter = this.getOrCreateLimiter(config)\n    const res = await limiter.reward(key, points)\n    return this.toResult(res, true)\n  }\n\n  async block(key: string, durationSec: number, config: RateLimitConfig): Promise<void> {\n    if (!this.globalConfig.enabled) return\n    const limiter = this.getOrCreateLimiter(config)\n    await limiter.block(key, durationSec)\n  }\n\n  async destroy(): Promise<void> {\n    if (this.redisClient) {\n      this.redisClient.disconnect()\n    }\n    this.limiters.clear()\n  }\n\n  private disabledResult(config: RateLimitConfig): RateLimitResult {\n    return { allowed: true, remainingPoints: config.points, msBeforeNext: 0, consumedPoints: 0 }\n  }\n\n  private getOrCreateLimiter(config: RateLimitConfig): RateLimiterMemory | RateLimiterRedis {\n    const cacheKey = `${config.keyPrefix ?? 'default'}:${config.points}:${config.duration}:${config.blockDuration ?? 0}`\n\n    let limiter = this.limiters.get(cacheKey)\n    if (limiter) return limiter\n\n    const prefix = [this.globalConfig.keyPrefix, config.keyPrefix].filter(Boolean).join(':')\n\n    const baseOpts = {\n      keyPrefix: prefix,\n      points: config.points,\n      duration: config.duration,\n      blockDuration: config.blockDuration ?? 0,\n    }\n\n    if (this.globalConfig.strategy === 'redis' && this.redisClient) {\n      const insuranceLimiter = new RateLimiterMemory(baseOpts)\n      limiter = new RateLimiterRedis({\n        ...baseOpts,\n        storeClient: this.redisClient,\n        insuranceLimiter,\n        rejectIfRedisNotReady: false,\n      })\n    } else {\n      limiter = new RateLimiterMemory(baseOpts)\n    }\n\n    this.limiters.set(cacheKey, limiter)\n    return limiter\n  }\n\n  private toResult(res: RateLimiterRes, allowed: boolean): RateLimitResult {\n    return {\n      allowed,\n      remainingPoints: Math.max(res.remainingPoints, 0),\n      msBeforeNext: res.msBeforeNext,\n      consumedPoints: res.consumedPoints,\n    }\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { RateLimiterMemory, RateLimiterRedis, RateLimiterRes } from 'rate-limiter-flexible'\nimport { createLogger } from '../logger'\nimport { parseRedisUrl } from '../redis/connection'\nimport type { RateLimitConfig, RateLimitResult, RateLimitGlobalConfig } from './types'\n\nconst logger = createLogger('ratelimit')\n\n/** Narrow interface for the ioredis client \u2014 only the methods we actually use. */\ninterface RedisClient {\n  disconnect(): void\n}\n\nexport class RateLimiterService {\n  private globalConfig: RateLimitGlobalConfig\n  private limiters = new Map<string, RateLimiterMemory | RateLimiterRedis>()\n  private redisClient: RedisClient | null = null\n\n  readonly trustProxyDepth: number\n\n  constructor(globalConfig: RateLimitGlobalConfig) {\n    this.globalConfig = globalConfig\n    this.trustProxyDepth = globalConfig.trustProxyDepth ?? 0\n  }\n\n  async initialize(): Promise<void> {\n    if (this.globalConfig.strategy === 'redis' && this.globalConfig.redisUrl) {\n      const { default: Redis } = await import('ioredis')\n      this.redisClient = new Redis({\n        ...parseRedisUrl(this.globalConfig.redisUrl),\n        enableOfflineQueue: false,\n        maxRetriesPerRequest: 1,\n      })\n    }\n  }\n\n  async consume(key: string, config: RateLimitConfig): Promise<RateLimitResult> {\n    if (!this.globalConfig.enabled) {\n      return this.disabledResult(config)\n    }\n\n    const limiter = this.getOrCreateLimiter(config)\n\n    try {\n      const res = await limiter.consume(key, 1)\n      return this.toResult(res, true)\n    } catch (error) {\n      if (error instanceof RateLimiterRes) {\n        return this.toResult(error, false)\n      }\n      logger.error('Rate limiter unavailable, request was not counted', {\n        err: error,\n        keyPrefix: config.keyPrefix,\n        strategy: this.globalConfig.strategy,\n      })\n      return this.degradedResult(config)\n    }\n  }\n\n  async get(key: string, config: RateLimitConfig): Promise<RateLimitResult | null> {\n    if (!this.globalConfig.enabled) return null\n\n    const limiter = this.getOrCreateLimiter(config)\n    const res = await limiter.get(key)\n    return res ? this.toResult(res, res.remainingPoints > 0) : null\n  }\n\n  async delete(key: string, config: RateLimitConfig): Promise<void> {\n    if (!this.globalConfig.enabled) return\n    const limiter = this.getOrCreateLimiter(config)\n    await limiter.delete(key)\n  }\n\n  async penalty(key: string, points: number, config: RateLimitConfig): Promise<RateLimitResult> {\n    if (!this.globalConfig.enabled) {\n      return this.disabledResult(config)\n    }\n    const limiter = this.getOrCreateLimiter(config)\n    const res = await limiter.penalty(key, points)\n    return this.toResult(res, res.remainingPoints > 0)\n  }\n\n  async reward(key: string, points: number, config: RateLimitConfig): Promise<RateLimitResult> {\n    if (!this.globalConfig.enabled) {\n      return this.disabledResult(config)\n    }\n    const limiter = this.getOrCreateLimiter(config)\n    const res = await limiter.reward(key, points)\n    return this.toResult(res, true)\n  }\n\n  async block(key: string, durationSec: number, config: RateLimitConfig): Promise<void> {\n    if (!this.globalConfig.enabled) return\n    const limiter = this.getOrCreateLimiter(config)\n    await limiter.block(key, durationSec)\n  }\n\n  async destroy(): Promise<void> {\n    if (this.redisClient) {\n      this.redisClient.disconnect()\n    }\n    this.limiters.clear()\n  }\n\n  private disabledResult(config: RateLimitConfig): RateLimitResult {\n    return { allowed: true, remainingPoints: config.points, msBeforeNext: 0, consumedPoints: 0 }\n  }\n\n  private degradedResult(config: RateLimitConfig): RateLimitResult {\n    return { ...this.disabledResult(config), degraded: true }\n  }\n\n  private getOrCreateLimiter(config: RateLimitConfig): RateLimiterMemory | RateLimiterRedis {\n    const cacheKey = `${config.keyPrefix ?? 'default'}:${config.points}:${config.duration}:${config.blockDuration ?? 0}`\n\n    let limiter = this.limiters.get(cacheKey)\n    if (limiter) return limiter\n\n    const prefix = [this.globalConfig.keyPrefix, config.keyPrefix].filter(Boolean).join(':')\n\n    const baseOpts = {\n      keyPrefix: prefix,\n      points: config.points,\n      duration: config.duration,\n      blockDuration: config.blockDuration ?? 0,\n    }\n\n    if (this.globalConfig.strategy === 'redis' && this.redisClient) {\n      const insuranceLimiter = new RateLimiterMemory(baseOpts)\n      limiter = new RateLimiterRedis({\n        ...baseOpts,\n        storeClient: this.redisClient,\n        insuranceLimiter,\n        rejectIfRedisNotReady: false,\n      })\n    } else {\n      limiter = new RateLimiterMemory(baseOpts)\n    }\n\n    this.limiters.set(cacheKey, limiter)\n    return limiter\n  }\n\n  private toResult(res: RateLimiterRes, allowed: boolean): RateLimitResult {\n    return {\n      allowed,\n      remainingPoints: Math.max(res.remainingPoints, 0),\n      msBeforeNext: res.msBeforeNext,\n      consumedPoints: res.consumedPoints,\n    }\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.8-develop.6963.1.04a6d320e9";
+const APP_VERSION = "0.6.8-develop.6964.1.36b364cfd8";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6963.1.04a6d320e9';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.8-develop.6964.1.36b364cfd8';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.8-develop.6963.1.04a6d320e9",
+  "version": "0.6.8-develop.6964.1.36b364cfd8",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -105,7 +105,7 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.6.8-develop.6963.1.04a6d320e9",
+    "@open-mercato/cache": "0.6.8-develop.6964.1.36b364cfd8",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",

package/src/lib/ratelimit/__tests__/helpers.test.ts

@@ -1,5 +1,11 @@
 import { RateLimiterService } from '../service'
-import { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK } from '../helpers'
+import {
+  checkRateLimit,
+  getClientIp,
+  RATE_LIMIT_ERROR_KEY,
+  RATE_LIMIT_ERROR_FALLBACK,
+  RATE_LIMIT_UNAVAILABLE_FALLBACK,
+} from '../helpers'
 import { readEndpointRateLimitConfig } from '../config'
 import type { RateLimitConfig, RateLimitGlobalConfig } from '../types'
 
@@ -84,6 +90,45 @@ describe('checkRateLimit', () => {
       expect(result).toBeNull()
     }
   })
+
+  describe('degraded limiter', () => {
+    function createDegradedService(): RateLimiterService {
+      const degraded = createService()
+      jest.spyOn(degraded, 'consume').mockResolvedValue({
+        allowed: true,
+        remainingPoints: limitConfig.points,
+        msBeforeNext: 0,
+        consumedPoints: 0,
+        degraded: true,
+      })
+      return degraded
+    }
+
+    it('returns 503 when failClosed is set', async () => {
+      service = createDegradedService()
+      const response = await checkRateLimit(service, limitConfig, 'ip7', 'Rate limited', {
+        failClosed: true,
+      })
+      expect(response).not.toBeNull()
+      expect(response!.status).toBe(503)
+      expect(await response!.json()).toEqual({ error: RATE_LIMIT_UNAVAILABLE_FALLBACK })
+    })
+
+    it('uses the supplied unavailableMessage in the 503 body', async () => {
+      service = createDegradedService()
+      const response = await checkRateLimit(service, limitConfig, 'ip8', 'Rate limited', {
+        failClosed: true,
+        unavailableMessage: 'Payments are briefly unavailable.',
+      })
+      expect(await response!.json()).toEqual({ error: 'Payments are briefly unavailable.' })
+    })
+
+    it('keeps failing open when failClosed is not set', async () => {
+      service = createDegradedService()
+      const response = await checkRateLimit(service, limitConfig, 'ip9', 'Rate limited')
+      expect(response).toBeNull()
+    })
+  })
 })
 
 describe('getClientIp', () => {

package/src/lib/ratelimit/__tests__/service.test.ts

@@ -1,6 +1,17 @@
+import { RateLimiterMemory, RateLimiterRedis, RateLimiterRes } from 'rate-limiter-flexible'
+import {
+  registerLoggerExtension,
+  resetLoggerExtension,
+  type LoggerExtensionRecord,
+} from '../../logger'
 import { RateLimiterService } from '../service'
 import type { RateLimitConfig, RateLimitGlobalConfig } from '../types'
 
+jest.mock('ioredis', () => ({
+  __esModule: true,
+  default: jest.fn().mockImplementation(() => ({ disconnect: jest.fn() })),
+}))
+
 function createConfig(overrides: Partial<RateLimitGlobalConfig> = {}): RateLimitGlobalConfig {
   return {
     enabled: true,
@@ -148,6 +159,108 @@ describe('RateLimiterService', () => {
     })
   })
 
+  describe('degraded limiter', () => {
+    const logRecords: LoggerExtensionRecord[] = []
+
+    beforeEach(() => {
+      logRecords.length = 0
+      registerLoggerExtension({ emit: (record) => logRecords.push(record) })
+      jest.spyOn(console, 'error').mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+      resetLoggerExtension()
+      jest.restoreAllMocks()
+    })
+
+    it('flags the result as degraded when the backing store fails', async () => {
+      jest.spyOn(RateLimiterMemory.prototype, 'consume').mockRejectedValue(new Error('store unreachable'))
+      service = new RateLimiterService(createConfig())
+
+      const result = await service.consume('key1', defaultLimitConfig)
+      expect(result.degraded).toBe(true)
+      expect(result.allowed).toBe(true)
+      expect(logRecords).toEqual([
+        expect.objectContaining({
+          level: 'error',
+          namespace: 'ratelimit',
+          message: 'Rate limiter unavailable, request was not counted',
+        }),
+      ])
+    })
+
+    it('does not flag a real rejection as degraded', async () => {
+      service = new RateLimiterService(createConfig())
+      for (let i = 0; i < defaultLimitConfig.points; i++) {
+        await service.consume('key2', defaultLimitConfig)
+      }
+
+      const result = await service.consume('key2', defaultLimitConfig)
+      expect(result.allowed).toBe(false)
+      expect(result.degraded).toBeFalsy()
+    })
+
+    it('does not flag a config-disabled result as degraded', async () => {
+      service = new RateLimiterService(createConfig({ enabled: false }))
+
+      const result = await service.consume('key3', defaultLimitConfig)
+      expect(result.allowed).toBe(true)
+      expect(result.degraded).toBeFalsy()
+    })
+
+    // Which failure modes actually reach `degraded` under the redis strategy: the store
+    // abstraction absorbs a plain outage through the in-memory insurance limiter, so only
+    // an error it re-throws gets there.
+    describe('redis strategy', () => {
+      async function createRedisService(): Promise<RateLimiterService> {
+        const redisService = new RateLimiterService(createConfig({
+          strategy: 'redis',
+          redisUrl: 'redis://localhost:6379',
+        }))
+        await redisService.initialize()
+        return redisService
+      }
+
+      function buildLimiter(redisService: RateLimiterService): unknown {
+        const internals = redisService as unknown as {
+          getOrCreateLimiter: (config: RateLimitConfig) => unknown
+        }
+        return internals.getOrCreateLimiter(defaultLimitConfig)
+      }
+
+      it('flags an error the redis limiter re-throws as degraded', async () => {
+        service = await createRedisService()
+        expect(buildLimiter(service)).toBeInstanceOf(RateLimiterRedis)
+        jest.spyOn(RateLimiterRedis.prototype, 'consume').mockRejectedValue(new Error('redis down'))
+
+        const result = await service.consume('redis-key', defaultLimitConfig)
+
+        expect(result.degraded).toBe(true)
+        expect(result.allowed).toBe(true)
+        expect(logRecords).toEqual([
+          expect.objectContaining({
+            level: 'error',
+            namespace: 'ratelimit',
+            message: 'Rate limiter unavailable, request was not counted',
+          }),
+        ])
+      })
+
+      it('does not flag a resolved redis decision as degraded, including one the insurance limiter produced', async () => {
+        service = await createRedisService()
+        expect(buildLimiter(service)).toBeInstanceOf(RateLimiterRedis)
+        jest.spyOn(RateLimiterRedis.prototype, 'consume')
+          .mockResolvedValue(new RateLimiterRes(2, 0, 1, undefined))
+
+        const result = await service.consume('redis-key', defaultLimitConfig)
+
+        expect(result.allowed).toBe(true)
+        expect(result.degraded).toBeFalsy()
+        expect(logRecords).toEqual([])
+      })
+    })
+  })
+
   describe('limiter caching', () => {
     it('reuses the same limiter for the same config', async () => {
       service = new RateLimiterService(createConfig())

package/src/lib/ratelimit/helpers.ts

@@ -6,23 +6,47 @@ import type { RateLimiterService } from './service'
 export const RATE_LIMIT_ERROR_KEY = 'api.errors.rateLimit'
 export const RATE_LIMIT_ERROR_FALLBACK = 'Too many requests. Please try again later.'
 export const RATE_LIMIT_FALLBACK_KEY = 'global'
+export const RATE_LIMIT_UNAVAILABLE_KEY = 'api.errors.rateLimitUnavailable'
+export const RATE_LIMIT_UNAVAILABLE_FALLBACK = 'Service temporarily unavailable. Please try again later.'
 
 export const rateLimitErrorSchema = z.object({
   error: z.string().describe('Rate limit exceeded message'),
 })
 
+export type CheckRateLimitOptions = {
+  /**
+   * Reject with 503 when the limiter could not reach its backing store, instead of
+   * letting the request through uncounted. Use on state-mutating endpoints, where an
+   * unenforced limit is worse than a rejected request.
+   */
+  failClosed?: boolean
+  /** Body message for the 503 emitted by `failClosed`. */
+  unavailableMessage?: string
+}
+
 /**
  * Check rate limit for a request. Returns a 429 NextResponse if rate limited, or null if allowed.
  * Rate limit headers (X-RateLimit-*, Retry-After) are only included on 429 responses.
+ *
+ * With `options.failClosed`, a degraded limiter (backing store unreachable) yields a 503
+ * instead of an allowed request. Without it the call behaves exactly as before and fails open.
  */
 export async function checkRateLimit(
   rateLimiterService: RateLimiterService,
   config: RateLimitConfig,
   key: string,
   errorMessage: string,
+  options: CheckRateLimitOptions = {},
 ): Promise<NextResponse | null> {
   const result = await rateLimiterService.consume(key, config)
 
+  if (result.degraded && options.failClosed) {
+    return NextResponse.json(
+      { error: options.unavailableMessage ?? RATE_LIMIT_UNAVAILABLE_FALLBACK },
+      { status: 503 },
+    )
+  }
+
   if (!result.allowed) {
     const retryAfterSec = Math.ceil(result.msBeforeNext / 1000)
     return NextResponse.json(

package/src/lib/ratelimit/index.ts

@@ -1,4 +1,5 @@
 export { RateLimiterService } from './service'
 export { readRateLimitConfig, readEndpointRateLimitConfig } from './config'
-export { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_FALLBACK_KEY, rateLimitErrorSchema } from './helpers'
+export { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FALLBACK, RATE_LIMIT_FALLBACK_KEY, RATE_LIMIT_UNAVAILABLE_KEY, RATE_LIMIT_UNAVAILABLE_FALLBACK, rateLimitErrorSchema } from './helpers'
+export type { CheckRateLimitOptions } from './helpers'
 export type { RateLimitConfig, RateLimitResult, RateLimitStrategy, RateLimitGlobalConfig } from './types'

package/src/lib/ratelimit/service.ts

@@ -1,7 +1,10 @@
 import { RateLimiterMemory, RateLimiterRedis, RateLimiterRes } from 'rate-limiter-flexible'
+import { createLogger } from '../logger'
 import { parseRedisUrl } from '../redis/connection'
 import type { RateLimitConfig, RateLimitResult, RateLimitGlobalConfig } from './types'
 
+const logger = createLogger('ratelimit')
+
 /** Narrow interface for the ioredis client — only the methods we actually use. */
 interface RedisClient {
   disconnect(): void
@@ -44,7 +47,12 @@ export class RateLimiterService {
       if (error instanceof RateLimiterRes) {
         return this.toResult(error, false)
       }
-      return this.disabledResult(config)
+      logger.error('Rate limiter unavailable, request was not counted', {
+        err: error,
+        keyPrefix: config.keyPrefix,
+        strategy: this.globalConfig.strategy,
+      })
+      return this.degradedResult(config)
     }
   }
 
@@ -97,6 +105,10 @@ export class RateLimiterService {
     return { allowed: true, remainingPoints: config.points, msBeforeNext: 0, consumedPoints: 0 }
   }
 
+  private degradedResult(config: RateLimitConfig): RateLimitResult {
+    return { ...this.disabledResult(config), degraded: true }
+  }
+
   private getOrCreateLimiter(config: RateLimitConfig): RateLimiterMemory | RateLimiterRedis {
     const cacheKey = `${config.keyPrefix ?? 'default'}:${config.points}:${config.duration}:${config.blockDuration ?? 0}`
 

package/src/lib/ratelimit/types.ts

@@ -18,6 +18,20 @@ export interface RateLimitResult {
   msBeforeNext: number
   /** Total points consumed in the current window */
   consumedPoints: number
+  /**
+   * True when the limiter could not produce a real decision, so `allowed` is a
+   * fallback. Callers guarding state-mutating endpoints SHOULD fail closed on this
+   * instead of letting the request through. Absent (falsy) when rate limiting is
+   * switched off by configuration.
+   *
+   * Set for every error that escapes the limiter itself: building the limiter fails,
+   * or `consume()` rejects with anything other than a `RateLimiterRes` quota
+   * rejection. With the `redis` strategy an unreachable store is normally absorbed
+   * one level lower by the in-memory insurance limiter — requests stay counted
+   * per process and the result is a real decision, so `degraded` stays falsy; it is
+   * set when that fallback layer fails too.
+   */
+  degraded?: boolean
 }
 
 export type RateLimitStrategy = 'memory' | 'redis'