alepha 0.15.1 → 0.15.3

package/dist/server/multipart/index.d.ts

@@ -38,10 +38,16 @@ interface HybridFile extends FileLike {
 //#endregion
 //#region ../../src/server/multipart/index.d.ts
 /**
- * This module provides support for handling multipart/form-data requests.
- * It allows to parse body data containing t.file().
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Multipart form data handling for file uploads.
+ *
+ * **Features:**
+ * - File upload parsing
+ * - Form field extraction
  *
- * @see {@link ServerMultipartProvider}
  * @module alepha.server.multipart
  */
 declare const AlephaServerMultipart: alepha1.Service<alepha1.Module>;

package/dist/server/multipart/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/multipart/providers/ServerMultipartProvider.ts","../../../src/server/multipart/index.ts"],"mappings":";;;;;;cAmCa,uBAAA;EAAA,mBACQ,MAAA,EAAM,MAAA;EAAA,mBACN,GAAA;;;;;qBACA,GAAA,EAFM,cAAA,CAEH,MAAA;EAAA,SAEN,SAAA,EAFM,OAAA,CAEG,aAAA;EAAA,SAuET,UAAA,EAvES,OAAA,CAuEC,aAAA;EAUb,0BAAA,CACX,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,OAAA,GACR,OAAA;IACD,IAAA,EAAM,MAAA;IACN,OAAA,QAAe,OAAA;EAAA;EAAA;;;;;;;EAAA,UAwHD,gBAAA,CACd,IAAA,EAAM,IAAA,EACN,SAAA,WACC,OAAA,CAAQ,UAAA;AAAA;AAAA,UAqDH,UAAA,SAAmB,QAAA;EAC3B,OAAA,IAAW,OAAA;EACX,MAAA;IACE,OAAA;IACA,IAAA;IACA,OAAA;EAAA;AAAA;;;;;;;;AAhRJ;;cClBa,qBAAA,EAAqB,OAAA,CAAA,OAAA,CAGhC,OAAA,CAHgC,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/multipart/providers/ServerMultipartProvider.ts","../../../src/server/multipart/index.ts"],"mappings":";;;;;;cAmCa,uBAAA;EAAA,mBACQ,MAAA,EAAM,MAAA;EAAA,mBACN,GAAA;;;;;qBACA,GAAA,EAFM,cAAA,CAEH,MAAA;EAAA,SAEN,SAAA,EAFM,OAAA,CAEG,aAAA;EAAA,SAuET,UAAA,EAvES,OAAA,CAuEC,aAAA;EAUb,0BAAA,CACX,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,OAAA,GACR,OAAA;IACD,IAAA,EAAM,MAAA;IACN,OAAA,QAAe,OAAA;EAAA;EAAA;;;;;;;EAAA,UAwHD,gBAAA,CACd,IAAA,EAAM,IAAA,EACN,SAAA,WACC,OAAA,CAAQ,UAAA;AAAA;AAAA,UAqDH,UAAA,SAAmB,QAAA;EAC3B,OAAA,IAAW,OAAA;EACX,MAAA;IACE,OAAA;IACA,IAAA;IACA,OAAA;EAAA;AAAA;;;;;;;;AAhRJ;;;;;;;;cCZa,qBAAA,EAAqB,OAAA,CAAA,OAAA,CAGhC,OAAA,CAHgC,MAAA"}

package/dist/server/multipart/index.js

@@ -192,10 +192,16 @@ var ServerMultipartProvider = class {
 //#endregion
 //#region ../../src/server/multipart/index.ts
 /**
-* This module provides support for handling multipart/form-data requests.
-* It allows to parse body data containing t.file().
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | standard | stable |
+*
+* Multipart form data handling for file uploads.
+*
+* **Features:**
+* - File upload parsing
+* - Form field extraction
 *
-* @see {@link ServerMultipartProvider}
 * @module alepha.server.multipart
 */
 const AlephaServerMultipart = $module({

package/dist/server/multipart/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["WebStream"],"sources":["../../../src/server/multipart/providers/ServerMultipartProvider.ts","../../../src/server/multipart/index.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { createReadStream } from \"node:fs\";\nimport { readFile, unlink, writeFile } from \"node:fs/promises\";\nimport * as os from \"node:os\";\nimport { ReadableStream as WebStream } from \"node:stream/web\";\nimport {\n  $env,\n  $hook,\n  $inject,\n  Alepha,\n  type FileLike,\n  isTypeFile,\n  t,\n} from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { HttpError, isMultipart, type ServerRoute } from \"alepha/server\";\n\nconst envSchema = t.object({\n  SERVER_MULTIPART_LIMIT: t.integer({\n    default: 10_000_000, // 10MB total\n    min: 0,\n    description: \"Maximum total size of multipart request body in bytes.\",\n  }),\n  SERVER_MULTIPART_FILE_LIMIT: t.integer({\n    default: 5_000_000, // 5MB per file\n    min: 0,\n    description: \"Maximum size of a single file in bytes.\",\n  }),\n  SERVER_MULTIPART_FILE_COUNT: t.integer({\n    default: 10,\n    min: 1,\n    description: \"Maximum number of files allowed in a single request.\",\n  }),\n});\n\nexport class ServerMultipartProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly env = $env(envSchema);\n  protected readonly log = $logger();\n\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      // already parsed (e.g. by body parser)\n      if (request.body) {\n        return;\n      }\n\n      // we do not parse body if no schema\n      if (!route.schema?.body) {\n        return;\n      }\n\n      let webRequest: Request | undefined;\n\n      if (request.raw.web?.req) {\n        webRequest = request.raw.web.req;\n      } else if (request.raw.node?.req) {\n        webRequest = new Request(request.url, {\n          method: request.method,\n          headers: request.headers,\n          body: WebStream.from(\n            request.raw.node.req,\n          ) as unknown as ReadableStream,\n          duplex: \"half\",\n        } as RequestInit & { duplex: \"half\" });\n      }\n\n      if (!webRequest) {\n        return;\n      }\n\n      const contentType = request.headers[\"content-type\"];\n\n      // Check content-length before processing to fail fast on oversized requests\n      const contentLength = request.headers[\"content-length\"];\n      if (contentLength) {\n        const size = Number.parseInt(contentLength, 10);\n        if (!Number.isNaN(size) && size > this.env.SERVER_MULTIPART_LIMIT) {\n          this.log.error(\n            `Multipart request size limit exceeded: ${size} > ${this.env.SERVER_MULTIPART_LIMIT}`,\n          );\n          throw new HttpError({\n            status: 413,\n            message: `Request body size limit exceeded. Maximum allowed: ${this.env.SERVER_MULTIPART_LIMIT} bytes`,\n          });\n        }\n      }\n\n      if (!contentType?.startsWith(\"multipart/form-data\")) {\n        if (!isMultipart(route)) {\n          return;\n        }\n\n        // route expects multipart but content-type is not correct! reject with 415\n        throw new HttpError({\n          status: 415,\n          message: `Invalid content-type: ${contentType} - only \"multipart/form-data\" is accepted`,\n        });\n      }\n\n      const { body, cleanup } = await this.handleMultipartBodyFromWeb(\n        route,\n        webRequest,\n      );\n\n      request.body = body;\n      request.metadata.multipart = { cleanup };\n    },\n  });\n\n  public readonly onResponse = $hook({\n    on: \"server:onResponse\",\n    handler: async ({ request }) => {\n      const cleanup = request.metadata.multipart?.cleanup;\n      if (typeof cleanup === \"function\") {\n        await cleanup();\n      }\n    },\n  });\n\n  public async handleMultipartBodyFromWeb(\n    route: ServerRoute,\n    request: Request,\n  ): Promise<{\n    body: Record<string, unknown>;\n    cleanup: () => Promise<void>;\n  }> {\n    let formData: FormData;\n\n    try {\n      // Parse the FormData from the request\n      formData = await request.formData();\n    } catch (error) {\n      throw new HttpError(\n        {\n          status: 400,\n          message: \"Malformed multipart/form-data\",\n        },\n        error,\n      );\n    }\n\n    const body: Record<string, any> = {};\n    const tempFiles: HybridFile[] = [];\n\n    // Helper to clean up temp files on error\n    const cleanupOnError = async () => {\n      for (const file of tempFiles) {\n        try {\n          await file.cleanup();\n        } catch {\n          // Ignore cleanup errors during error handling\n        }\n      }\n    };\n\n    try {\n      let fileCount = 0;\n      let totalSize = 0;\n\n      if (route.schema?.body && t.schema.isObject(route.schema.body)) {\n        for (const [key, value] of Object.entries(\n          route.schema.body.properties,\n        )) {\n          if (t.schema.isSchema(value)) {\n            if (isTypeFile(value)) {\n              const file = formData.get(key);\n              // Check if file is a Blob (File extends Blob in Web APIs)\n              if (file && typeof file === \"object\" && \"arrayBuffer\" in file) {\n                const blob = file as Blob;\n\n                // Validate file count\n                fileCount++;\n                if (fileCount > this.env.SERVER_MULTIPART_FILE_COUNT) {\n                  this.log.error(\n                    `Too many files in multipart request: ${fileCount} > ${this.env.SERVER_MULTIPART_FILE_COUNT}`,\n                  );\n                  throw new HttpError({\n                    status: 413,\n                    message: `Too many files. Maximum allowed: ${this.env.SERVER_MULTIPART_FILE_COUNT}`,\n                  });\n                }\n\n                // Validate individual file size\n                if (blob.size > this.env.SERVER_MULTIPART_FILE_LIMIT) {\n                  this.log.error(\n                    `File \"${key}\" exceeds size limit: ${blob.size} > ${this.env.SERVER_MULTIPART_FILE_LIMIT}`,\n                  );\n                  throw new HttpError({\n                    status: 413,\n                    message: `File \"${key}\" exceeds size limit. Maximum allowed: ${this.env.SERVER_MULTIPART_FILE_LIMIT} bytes`,\n                  });\n                }\n\n                // Validate total size\n                totalSize += blob.size;\n                if (totalSize > this.env.SERVER_MULTIPART_LIMIT) {\n                  this.log.error(\n                    `Total multipart size exceeds limit: ${totalSize} > ${this.env.SERVER_MULTIPART_LIMIT}`,\n                  );\n                  throw new HttpError({\n                    status: 413,\n                    message: `Total request size exceeds limit. Maximum allowed: ${this.env.SERVER_MULTIPART_LIMIT} bytes`,\n                  });\n                }\n\n                const hybridFile = await this.createHybridFile(blob, key);\n                body[key] = hybridFile;\n                tempFiles.push(hybridFile);\n              }\n            } else {\n              const fieldValue = formData.get(key);\n              if (fieldValue !== null) {\n                // FormData values are either string or File/Blob\n                const stringValue =\n                  typeof fieldValue === \"string\" ? fieldValue : \"\";\n                body[key] = this.alepha.codec.decode(value, stringValue);\n              }\n            }\n          }\n        }\n      }\n\n      return {\n        body,\n        cleanup: async () => {\n          for (const file of tempFiles) {\n            await file.cleanup();\n          }\n        },\n      };\n    } catch (error) {\n      // Clean up any temp files that were created before the error\n      await cleanupOnError();\n      throw error;\n    }\n  }\n\n  /**\n   * This is a legacy code, previously we used \"busboy\" to parse multipart in Node.js environment.\n   * Now we rely on Web Request's formData() method, which is supported in modern Node.js versions.\n   * However, we still need to create temporary files for uploaded files to provide a consistent File-like interface.\n   *\n   * TODO: In future, we might want to refactor this to avoid using temporary files if not necessary?\n   */\n  protected async createHybridFile(\n    file: Blob,\n    fieldName: string,\n  ): Promise<HybridFile> {\n    const tmpPath = `${os.tmpdir()}/${randomUUID()}`;\n\n    // Get file data\n    const arrayBuffer = await file.arrayBuffer();\n    const buffer = Buffer.from(arrayBuffer);\n\n    // Write to temp file\n    await writeFile(tmpPath, buffer);\n\n    // Get file name - check if it has name property (File type)\n    const fileName = (file as any).name || `${fieldName}_${Date.now()}`;\n\n    const hybridFile: HybridFile = {\n      _state: {\n        cleanup: false,\n        size: file.size,\n        tmpPath,\n      },\n      name: fileName,\n      type: file.type || \"application/octet-stream\",\n      lastModified: (file as any).lastModified || Date.now(),\n      filepath: tmpPath,\n      get size() {\n        return this._state.size;\n      },\n      stream() {\n        return createReadStream(tmpPath);\n      },\n      async arrayBuffer() {\n        const content = await readFile(tmpPath);\n        return content.buffer.slice(\n          content.byteOffset,\n          content.byteOffset + content.byteLength,\n        ) as ArrayBuffer;\n      },\n      text: async () => {\n        return await readFile(tmpPath, \"utf-8\");\n      },\n      async cleanup() {\n        if (this._state.cleanup) {\n          return;\n        }\n\n        await unlink(tmpPath); // clean up the temp file\n        this._state.cleanup = true;\n      },\n    };\n\n    return hybridFile;\n  }\n}\n\ninterface HybridFile extends FileLike {\n  cleanup(): Promise<void>;\n  _state: {\n    cleanup: boolean;\n    size: number;\n    tmpPath: string;\n  };\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { ServerMultipartProvider } from \"./providers/ServerMultipartProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/ServerMultipartProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * This module provides support for handling multipart/form-data requests.\n * It allows to parse body data containing t.file().\n *\n * @see {@link ServerMultipartProvider}\n * @module alepha.server.multipart\n */\nexport const AlephaServerMultipart = $module({\n  name: \"alepha.server.multipart\",\n  services: [AlephaServer, ServerMultipartProvider],\n});\n"],"mappings":";;;;;;;;;;AAiBA,MAAM,YAAY,EAAE,OAAO;CACzB,wBAAwB,EAAE,QAAQ;EAChC,SAAS;EACT,KAAK;EACL,aAAa;EACd,CAAC;CACF,6BAA6B,EAAE,QAAQ;EACrC,SAAS;EACT,KAAK;EACL,aAAa;EACd,CAAC;CACF,6BAA6B,EAAE,QAAQ;EACrC,SAAS;EACT,KAAK;EACL,aAAa;EACd,CAAC;CACH,CAAC;AAEF,IAAa,0BAAb,MAAqC;CACnC,AAAmB,SAAS,QAAQ,OAAO;CAC3C,AAAmB,MAAM,KAAK,UAAU;CACxC,AAAmB,MAAM,SAAS;CAElC,AAAgB,YAAY,MAAM;EAChC,IAAI;EACJ,SAAS,OAAO,EAAE,OAAO,cAAc;AAErC,OAAI,QAAQ,KACV;AAIF,OAAI,CAAC,MAAM,QAAQ,KACjB;GAGF,IAAI;AAEJ,OAAI,QAAQ,IAAI,KAAK,IACnB,cAAa,QAAQ,IAAI,IAAI;YACpB,QAAQ,IAAI,MAAM,IAC3B,cAAa,IAAI,QAAQ,QAAQ,KAAK;IACpC,QAAQ,QAAQ;IAChB,SAAS,QAAQ;IACjB,MAAMA,eAAU,KACd,QAAQ,IAAI,KAAK,IAClB;IACD,QAAQ;IACT,CAAqC;AAGxC,OAAI,CAAC,WACH;GAGF,MAAM,cAAc,QAAQ,QAAQ;GAGpC,MAAM,gBAAgB,QAAQ,QAAQ;AACtC,OAAI,eAAe;IACjB,MAAM,OAAO,OAAO,SAAS,eAAe,GAAG;AAC/C,QAAI,CAAC,OAAO,MAAM,KAAK,IAAI,OAAO,KAAK,IAAI,wBAAwB;AACjE,UAAK,IAAI,MACP,0CAA0C,KAAK,KAAK,KAAK,IAAI,yBAC9D;AACD,WAAM,IAAI,UAAU;MAClB,QAAQ;MACR,SAAS,sDAAsD,KAAK,IAAI,uBAAuB;MAChG,CAAC;;;AAIN,OAAI,CAAC,aAAa,WAAW,sBAAsB,EAAE;AACnD,QAAI,CAAC,YAAY,MAAM,CACrB;AAIF,UAAM,IAAI,UAAU;KAClB,QAAQ;KACR,SAAS,yBAAyB,YAAY;KAC/C,CAAC;;GAGJ,MAAM,EAAE,MAAM,YAAY,MAAM,KAAK,2BACnC,OACA,WACD;AAED,WAAQ,OAAO;AACf,WAAQ,SAAS,YAAY,EAAE,SAAS;;EAE3C,CAAC;CAEF,AAAgB,aAAa,MAAM;EACjC,IAAI;EACJ,SAAS,OAAO,EAAE,cAAc;GAC9B,MAAM,UAAU,QAAQ,SAAS,WAAW;AAC5C,OAAI,OAAO,YAAY,WACrB,OAAM,SAAS;;EAGpB,CAAC;CAEF,MAAa,2BACX,OACA,SAIC;EACD,IAAI;AAEJ,MAAI;AAEF,cAAW,MAAM,QAAQ,UAAU;WAC5B,OAAO;AACd,SAAM,IAAI,UACR;IACE,QAAQ;IACR,SAAS;IACV,EACD,MACD;;EAGH,MAAM,OAA4B,EAAE;EACpC,MAAM,YAA0B,EAAE;EAGlC,MAAM,iBAAiB,YAAY;AACjC,QAAK,MAAM,QAAQ,UACjB,KAAI;AACF,UAAM,KAAK,SAAS;WACd;;AAMZ,MAAI;GACF,IAAI,YAAY;GAChB,IAAI,YAAY;AAEhB,OAAI,MAAM,QAAQ,QAAQ,EAAE,OAAO,SAAS,MAAM,OAAO,KAAK,EAC5D;SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAChC,MAAM,OAAO,KAAK,WACnB,CACC,KAAI,EAAE,OAAO,SAAS,MAAM,CAC1B,KAAI,WAAW,MAAM,EAAE;KACrB,MAAM,OAAO,SAAS,IAAI,IAAI;AAE9B,SAAI,QAAQ,OAAO,SAAS,YAAY,iBAAiB,MAAM;MAC7D,MAAM,OAAO;AAGb;AACA,UAAI,YAAY,KAAK,IAAI,6BAA6B;AACpD,YAAK,IAAI,MACP,wCAAwC,UAAU,KAAK,KAAK,IAAI,8BACjE;AACD,aAAM,IAAI,UAAU;QAClB,QAAQ;QACR,SAAS,oCAAoC,KAAK,IAAI;QACvD,CAAC;;AAIJ,UAAI,KAAK,OAAO,KAAK,IAAI,6BAA6B;AACpD,YAAK,IAAI,MACP,SAAS,IAAI,wBAAwB,KAAK,KAAK,KAAK,KAAK,IAAI,8BAC9D;AACD,aAAM,IAAI,UAAU;QAClB,QAAQ;QACR,SAAS,SAAS,IAAI,yCAAyC,KAAK,IAAI,4BAA4B;QACrG,CAAC;;AAIJ,mBAAa,KAAK;AAClB,UAAI,YAAY,KAAK,IAAI,wBAAwB;AAC/C,YAAK,IAAI,MACP,uCAAuC,UAAU,KAAK,KAAK,IAAI,yBAChE;AACD,aAAM,IAAI,UAAU;QAClB,QAAQ;QACR,SAAS,sDAAsD,KAAK,IAAI,uBAAuB;QAChG,CAAC;;MAGJ,MAAM,aAAa,MAAM,KAAK,iBAAiB,MAAM,IAAI;AACzD,WAAK,OAAO;AACZ,gBAAU,KAAK,WAAW;;WAEvB;KACL,MAAM,aAAa,SAAS,IAAI,IAAI;AACpC,SAAI,eAAe,MAAM;MAEvB,MAAM,cACJ,OAAO,eAAe,WAAW,aAAa;AAChD,WAAK,OAAO,KAAK,OAAO,MAAM,OAAO,OAAO,YAAY;;;;AAOlE,UAAO;IACL;IACA,SAAS,YAAY;AACnB,UAAK,MAAM,QAAQ,UACjB,OAAM,KAAK,SAAS;;IAGzB;WACM,OAAO;AAEd,SAAM,gBAAgB;AACtB,SAAM;;;;;;;;;;CAWV,MAAgB,iBACd,MACA,WACqB;EACrB,MAAM,UAAU,GAAG,GAAG,QAAQ,CAAC,GAAG,YAAY;EAG9C,MAAM,cAAc,MAAM,KAAK,aAAa;AAI5C,QAAM,UAAU,SAHD,OAAO,KAAK,YAAY,CAGP;EAGhC,MAAM,WAAY,KAAa,QAAQ,GAAG,UAAU,GAAG,KAAK,KAAK;AAsCjE,SApC+B;GAC7B,QAAQ;IACN,SAAS;IACT,MAAM,KAAK;IACX;IACD;GACD,MAAM;GACN,MAAM,KAAK,QAAQ;GACnB,cAAe,KAAa,gBAAgB,KAAK,KAAK;GACtD,UAAU;GACV,IAAI,OAAO;AACT,WAAO,KAAK,OAAO;;GAErB,SAAS;AACP,WAAO,iBAAiB,QAAQ;;GAElC,MAAM,cAAc;IAClB,MAAM,UAAU,MAAM,SAAS,QAAQ;AACvC,WAAO,QAAQ,OAAO,MACpB,QAAQ,YACR,QAAQ,aAAa,QAAQ,WAC9B;;GAEH,MAAM,YAAY;AAChB,WAAO,MAAM,SAAS,SAAS,QAAQ;;GAEzC,MAAM,UAAU;AACd,QAAI,KAAK,OAAO,QACd;AAGF,UAAM,OAAO,QAAQ;AACrB,SAAK,OAAO,UAAU;;GAEzB;;;;;;;;;;;;;ACvRL,MAAa,wBAAwB,QAAQ;CAC3C,MAAM;CACN,UAAU,CAAC,cAAc,wBAAwB;CAClD,CAAC"}
+{"version":3,"file":"index.js","names":["WebStream"],"sources":["../../../src/server/multipart/providers/ServerMultipartProvider.ts","../../../src/server/multipart/index.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { createReadStream } from \"node:fs\";\nimport { readFile, unlink, writeFile } from \"node:fs/promises\";\nimport * as os from \"node:os\";\nimport { ReadableStream as WebStream } from \"node:stream/web\";\nimport {\n  $env,\n  $hook,\n  $inject,\n  Alepha,\n  type FileLike,\n  isTypeFile,\n  t,\n} from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { HttpError, isMultipart, type ServerRoute } from \"alepha/server\";\n\nconst envSchema = t.object({\n  SERVER_MULTIPART_LIMIT: t.integer({\n    default: 10_000_000, // 10MB total\n    min: 0,\n    description: \"Maximum total size of multipart request body in bytes.\",\n  }),\n  SERVER_MULTIPART_FILE_LIMIT: t.integer({\n    default: 5_000_000, // 5MB per file\n    min: 0,\n    description: \"Maximum size of a single file in bytes.\",\n  }),\n  SERVER_MULTIPART_FILE_COUNT: t.integer({\n    default: 10,\n    min: 1,\n    description: \"Maximum number of files allowed in a single request.\",\n  }),\n});\n\nexport class ServerMultipartProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly env = $env(envSchema);\n  protected readonly log = $logger();\n\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      // already parsed (e.g. by body parser)\n      if (request.body) {\n        return;\n      }\n\n      // we do not parse body if no schema\n      if (!route.schema?.body) {\n        return;\n      }\n\n      let webRequest: Request | undefined;\n\n      if (request.raw.web?.req) {\n        webRequest = request.raw.web.req;\n      } else if (request.raw.node?.req) {\n        webRequest = new Request(request.url, {\n          method: request.method,\n          headers: request.headers,\n          body: WebStream.from(\n            request.raw.node.req,\n          ) as unknown as ReadableStream,\n          duplex: \"half\",\n        } as RequestInit & { duplex: \"half\" });\n      }\n\n      if (!webRequest) {\n        return;\n      }\n\n      const contentType = request.headers[\"content-type\"];\n\n      // Check content-length before processing to fail fast on oversized requests\n      const contentLength = request.headers[\"content-length\"];\n      if (contentLength) {\n        const size = Number.parseInt(contentLength, 10);\n        if (!Number.isNaN(size) && size > this.env.SERVER_MULTIPART_LIMIT) {\n          this.log.error(\n            `Multipart request size limit exceeded: ${size} > ${this.env.SERVER_MULTIPART_LIMIT}`,\n          );\n          throw new HttpError({\n            status: 413,\n            message: `Request body size limit exceeded. Maximum allowed: ${this.env.SERVER_MULTIPART_LIMIT} bytes`,\n          });\n        }\n      }\n\n      if (!contentType?.startsWith(\"multipart/form-data\")) {\n        if (!isMultipart(route)) {\n          return;\n        }\n\n        // route expects multipart but content-type is not correct! reject with 415\n        throw new HttpError({\n          status: 415,\n          message: `Invalid content-type: ${contentType} - only \"multipart/form-data\" is accepted`,\n        });\n      }\n\n      const { body, cleanup } = await this.handleMultipartBodyFromWeb(\n        route,\n        webRequest,\n      );\n\n      request.body = body;\n      request.metadata.multipart = { cleanup };\n    },\n  });\n\n  public readonly onResponse = $hook({\n    on: \"server:onResponse\",\n    handler: async ({ request }) => {\n      const cleanup = request.metadata.multipart?.cleanup;\n      if (typeof cleanup === \"function\") {\n        await cleanup();\n      }\n    },\n  });\n\n  public async handleMultipartBodyFromWeb(\n    route: ServerRoute,\n    request: Request,\n  ): Promise<{\n    body: Record<string, unknown>;\n    cleanup: () => Promise<void>;\n  }> {\n    let formData: FormData;\n\n    try {\n      // Parse the FormData from the request\n      formData = await request.formData();\n    } catch (error) {\n      throw new HttpError(\n        {\n          status: 400,\n          message: \"Malformed multipart/form-data\",\n        },\n        error,\n      );\n    }\n\n    const body: Record<string, any> = {};\n    const tempFiles: HybridFile[] = [];\n\n    // Helper to clean up temp files on error\n    const cleanupOnError = async () => {\n      for (const file of tempFiles) {\n        try {\n          await file.cleanup();\n        } catch {\n          // Ignore cleanup errors during error handling\n        }\n      }\n    };\n\n    try {\n      let fileCount = 0;\n      let totalSize = 0;\n\n      if (route.schema?.body && t.schema.isObject(route.schema.body)) {\n        for (const [key, value] of Object.entries(\n          route.schema.body.properties,\n        )) {\n          if (t.schema.isSchema(value)) {\n            if (isTypeFile(value)) {\n              const file = formData.get(key);\n              // Check if file is a Blob (File extends Blob in Web APIs)\n              if (file && typeof file === \"object\" && \"arrayBuffer\" in file) {\n                const blob = file as Blob;\n\n                // Validate file count\n                fileCount++;\n                if (fileCount > this.env.SERVER_MULTIPART_FILE_COUNT) {\n                  this.log.error(\n                    `Too many files in multipart request: ${fileCount} > ${this.env.SERVER_MULTIPART_FILE_COUNT}`,\n                  );\n                  throw new HttpError({\n                    status: 413,\n                    message: `Too many files. Maximum allowed: ${this.env.SERVER_MULTIPART_FILE_COUNT}`,\n                  });\n                }\n\n                // Validate individual file size\n                if (blob.size > this.env.SERVER_MULTIPART_FILE_LIMIT) {\n                  this.log.error(\n                    `File \"${key}\" exceeds size limit: ${blob.size} > ${this.env.SERVER_MULTIPART_FILE_LIMIT}`,\n                  );\n                  throw new HttpError({\n                    status: 413,\n                    message: `File \"${key}\" exceeds size limit. Maximum allowed: ${this.env.SERVER_MULTIPART_FILE_LIMIT} bytes`,\n                  });\n                }\n\n                // Validate total size\n                totalSize += blob.size;\n                if (totalSize > this.env.SERVER_MULTIPART_LIMIT) {\n                  this.log.error(\n                    `Total multipart size exceeds limit: ${totalSize} > ${this.env.SERVER_MULTIPART_LIMIT}`,\n                  );\n                  throw new HttpError({\n                    status: 413,\n                    message: `Total request size exceeds limit. Maximum allowed: ${this.env.SERVER_MULTIPART_LIMIT} bytes`,\n                  });\n                }\n\n                const hybridFile = await this.createHybridFile(blob, key);\n                body[key] = hybridFile;\n                tempFiles.push(hybridFile);\n              }\n            } else {\n              const fieldValue = formData.get(key);\n              if (fieldValue !== null) {\n                // FormData values are either string or File/Blob\n                const stringValue =\n                  typeof fieldValue === \"string\" ? fieldValue : \"\";\n                body[key] = this.alepha.codec.decode(value, stringValue);\n              }\n            }\n          }\n        }\n      }\n\n      return {\n        body,\n        cleanup: async () => {\n          for (const file of tempFiles) {\n            await file.cleanup();\n          }\n        },\n      };\n    } catch (error) {\n      // Clean up any temp files that were created before the error\n      await cleanupOnError();\n      throw error;\n    }\n  }\n\n  /**\n   * This is a legacy code, previously we used \"busboy\" to parse multipart in Node.js environment.\n   * Now we rely on Web Request's formData() method, which is supported in modern Node.js versions.\n   * However, we still need to create temporary files for uploaded files to provide a consistent File-like interface.\n   *\n   * TODO: In future, we might want to refactor this to avoid using temporary files if not necessary?\n   */\n  protected async createHybridFile(\n    file: Blob,\n    fieldName: string,\n  ): Promise<HybridFile> {\n    const tmpPath = `${os.tmpdir()}/${randomUUID()}`;\n\n    // Get file data\n    const arrayBuffer = await file.arrayBuffer();\n    const buffer = Buffer.from(arrayBuffer);\n\n    // Write to temp file\n    await writeFile(tmpPath, buffer);\n\n    // Get file name - check if it has name property (File type)\n    const fileName = (file as any).name || `${fieldName}_${Date.now()}`;\n\n    const hybridFile: HybridFile = {\n      _state: {\n        cleanup: false,\n        size: file.size,\n        tmpPath,\n      },\n      name: fileName,\n      type: file.type || \"application/octet-stream\",\n      lastModified: (file as any).lastModified || Date.now(),\n      filepath: tmpPath,\n      get size() {\n        return this._state.size;\n      },\n      stream() {\n        return createReadStream(tmpPath);\n      },\n      async arrayBuffer() {\n        const content = await readFile(tmpPath);\n        return content.buffer.slice(\n          content.byteOffset,\n          content.byteOffset + content.byteLength,\n        ) as ArrayBuffer;\n      },\n      text: async () => {\n        return await readFile(tmpPath, \"utf-8\");\n      },\n      async cleanup() {\n        if (this._state.cleanup) {\n          return;\n        }\n\n        await unlink(tmpPath); // clean up the temp file\n        this._state.cleanup = true;\n      },\n    };\n\n    return hybridFile;\n  }\n}\n\ninterface HybridFile extends FileLike {\n  cleanup(): Promise<void>;\n  _state: {\n    cleanup: boolean;\n    size: number;\n    tmpPath: string;\n  };\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { ServerMultipartProvider } from \"./providers/ServerMultipartProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/ServerMultipartProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * | type | quality | stability |\n * |------|---------|-----------|\n * | backend | standard | stable |\n *\n * Multipart form data handling for file uploads.\n *\n * **Features:**\n * - File upload parsing\n * - Form field extraction\n *\n * @module alepha.server.multipart\n */\nexport const AlephaServerMultipart = $module({\n  name: \"alepha.server.multipart\",\n  services: [AlephaServer, ServerMultipartProvider],\n});\n"],"mappings":"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"}

package/dist/server/proxy/index.d.ts

@@ -222,9 +222,15 @@ declare class ServerProxyProvider {
 //#endregion
 //#region ../../src/server/proxy/index.d.ts
 /**
- * Plugin for Alepha that provides a proxy server functionality.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
+ *
+ * Reverse proxy routing.
+ *
+ * **Features:**
+ * - Proxy configuration and routing
  *
- * @see {@link $proxy}
  * @module alepha.server.proxy
  */
 declare const AlephaServerProxy: alepha1.Service<alepha1.Module>;

package/dist/server/proxy/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/proxy/primitives/$proxy.ts","../../../src/server/proxy/providers/ServerProxyProvider.ts","../../../src/server/proxy/index.ts"],"mappings":";;;;;;;;;;AAsFA;;;;;;;;;;;;;;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmIA;;;;;;;;AClNA;;;;;;;;;;;;;;;;;;;;;;;cD2Ea,MAAA;EAAA,UAAmB,qBAAA,GAAwB,cAAA;EAAA;;KAI5C,qBAAA;ECpCR;;;;;;;;ACpCJ;;;;EFqFE,IAAA;;;;;;;;;;;;;EAcA,MAAA;;;;;;;;;;EAWA,QAAA;;;;;;;;;;;;;;;;;;;;;;;;EAyBA,aAAA,IACE,OAAA,EAAS,aAAA,EACT,YAAA,EAAc,WAAA,KACX,KAAA;;;;;;;;;;;;;;;;;;;;;;;;EAyBL,aAAA,IACE,OAAA,EAAS,aAAA,EACT,aAAA,EAAe,QAAA,KACZ,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BL,OAAA,IAAW,GAAA,EAAK,GAAA;AAAA;AAAA,cAML,cAAA,SAAuB,SAAA,CAAU,qBAAA;;;cClNjC,mBAAA;EAAA,mBACQ,GAAA,EADW,cAAA,CACR,MAAA;EAAA,mBACH,cAAA,EAAc,oBAAA;EAAA,mBACd,MAAA,EAAM,MAAA;EAAA,mBAEN,SAAA,EAFM,OAAA,CAEG,aAAA;EASrB,WAAA,CAAY,OAAA,EAAS,qBAAA;EA2BrB,kBAAA,CACL,MAAA,UACA,OAAA,EAAS,IAAA,CAAK,qBAAA,YACb,aAAA;EAAA,QAkDK,iBAAA;AAAA;;;;;;;ADnBV;;cEpEa,iBAAA,EAAiB,OAAA,CAAA,OAAA,CAI5B,OAAA,CAJ4B,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/proxy/primitives/$proxy.ts","../../../src/server/proxy/providers/ServerProxyProvider.ts","../../../src/server/proxy/index.ts"],"mappings":";;;;;;;;;;AAsFA;;;;;;;;;;;;;;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmIA;;;;;;;;AClNA;;;;;;;;;;;;;;;;;;;;;;;cD2Ea,MAAA;EAAA,UAAmB,qBAAA,GAAwB,cAAA;EAAA;;KAI5C,qBAAA;ECpCR;;;;;;;;AC9BJ;;;;EF+EE,IAAA;;;;;;;;;;;;;EAcA,MAAA;;;;;;;;;;EAWA,QAAA;;;;;;;;;;;;;;;;;;;;;;;;EAyBA,aAAA,IACE,OAAA,EAAS,aAAA,EACT,YAAA,EAAc,WAAA,KACX,KAAA;;;;;;;;;;;;;;;;;;;;;;;;EAyBL,aAAA,IACE,OAAA,EAAS,aAAA,EACT,aAAA,EAAe,QAAA,KACZ,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BL,OAAA,IAAW,GAAA,EAAK,GAAA;AAAA;AAAA,cAML,cAAA,SAAuB,SAAA,CAAU,qBAAA;;;cClNjC,mBAAA;EAAA,mBACQ,GAAA,EADW,cAAA,CACR,MAAA;EAAA,mBACH,cAAA,EAAc,oBAAA;EAAA,mBACd,MAAA,EAAM,MAAA;EAAA,mBAEN,SAAA,EAFM,OAAA,CAEG,aAAA;EASrB,WAAA,CAAY,OAAA,EAAS,qBAAA;EA2BrB,kBAAA,CACL,MAAA,UACA,OAAA,EAAS,IAAA,CAAK,qBAAA,YACb,aAAA;EAAA,QAkDK,iBAAA;AAAA;;;;;;;ADnBV;;;;;;;;cE9Da,iBAAA,EAAiB,OAAA,CAAA,OAAA,CAI5B,OAAA,CAJ4B,MAAA"}

package/dist/server/proxy/index.js

@@ -167,9 +167,15 @@ var ServerProxyProvider = class {
 //#endregion
 //#region ../../src/server/proxy/index.ts
 /**
-* Plugin for Alepha that provides a proxy server functionality.
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | standard | stable |
+*
+* Reverse proxy routing.
+*
+* **Features:**
+* - Proxy configuration and routing
 *
-* @see {@link $proxy}
 * @module alepha.server.proxy
 */
 const AlephaServerProxy = $module({

package/dist/server/proxy/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["WebStream"],"sources":["../../../src/server/proxy/primitives/$proxy.ts","../../../src/server/proxy/providers/ServerProxyProvider.ts","../../../src/server/proxy/index.ts"],"sourcesContent":["import { type Async, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\n\n/**\n * Creates a proxy primitive to forward requests to another server.\n *\n * This primitive enables you to create reverse proxy functionality, allowing your Alepha server\n * to forward requests to other services while maintaining a unified API surface. It's particularly\n * useful for microservice architectures, API gateways, or when you need to aggregate multiple\n * services behind a single endpoint.\n *\n * **Key Features**\n *\n * - **Path-based routing**: Match specific paths or patterns to proxy\n * - **Dynamic targets**: Support both static and dynamic target resolution\n * - **Request/Response hooks**: Modify requests before forwarding and responses after receiving\n * - **URL rewriting**: Transform URLs before forwarding to the target\n * - **Conditional proxying**: Enable/disable proxies based on environment or conditions\n *\n * @example\n * **Basic proxy setup:**\n * ```ts\n * import { $proxy } from \"alepha/server/proxy\";\n *\n * class ApiGateway {\n *   // Forward all /api/* requests to external service\n *   api = $proxy({\n *     path: \"/api/*\",\n *     target: \"https://api.example.com\"\n *   });\n * }\n * ```\n *\n * @example\n * **Dynamic target with environment-based routing:**\n * ```ts\n * class ApiGateway {\n *   // Route to different environments based on configuration\n *   api = $proxy({\n *     path: \"/api/*\",\n *     target: () => process.env.NODE_ENV === \"production\"\n *       ? \"https://api.prod.example.com\"\n *       : \"https://api.dev.example.com\"\n *   });\n * }\n * ```\n *\n * @example\n * **Advanced proxy with request/response modification:**\n * ```ts\n * class SecureProxy {\n *   secure = $proxy({\n *     path: \"/secure/*\",\n *     target: \"https://secure-api.example.com\",\n *     beforeRequest: async (request, proxyRequest) => {\n *       // Add authentication headers\n *       proxyRequest.headers = {\n *         ...proxyRequest.headers,\n *         'Authorization': `Bearer ${await getServiceToken()}`,\n *         'X-Forwarded-For': request.headers['x-forwarded-for'] || request.ip\n *       };\n *     },\n *     afterResponse: async (request, proxyResponse) => {\n *       // Log response for monitoring\n *       console.log(`Proxied ${request.url} -> ${proxyResponse.status}`);\n *     },\n *     rewrite: (url) => {\n *       // Remove /secure prefix when forwarding\n *       url.pathname = url.pathname.replace('/secure', '');\n *     }\n *   });\n * }\n * ```\n *\n * @example\n * **Conditional proxy based on feature flags:**\n * ```ts\n * class FeatureProxy {\n *   newApi = $proxy({\n *     path: \"/v2/*\",\n *     target: \"https://new-api.example.com\",\n *     disabled: !process.env.ENABLE_V2_API // Disable if feature flag is off\n *   });\n * }\n * ```\n */\nexport const $proxy = (options: ProxyPrimitiveOptions): ProxyPrimitive => {\n  return createPrimitive(ProxyPrimitive, options);\n};\n\nexport type ProxyPrimitiveOptions = {\n  /**\n   * Path pattern to match for proxying requests.\n   *\n   * Supports wildcards and path parameters:\n   * - `/api/*` - Matches all paths starting with `/api/`\n   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`\n   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.\n   *\n   * @example \"/api/*\"\n   * @example \"/secure/admin/*\"\n   * @example \"/users/:id/posts\"\n   */\n  path: string;\n\n  /**\n   * Target URL to which matching requests should be forwarded.\n   *\n   * Can be either:\n   * - **Static string**: A fixed URL like `\"https://api.example.com\"`\n   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution\n   *\n   * The target URL will be combined with the remaining path from the original request.\n   *\n   * @example \"https://api.example.com\"\n   * @example () => process.env.API_URL || \"http://localhost:3001\"\n   */\n  target: string | (() => string);\n\n  /**\n   * Whether this proxy is disabled.\n   *\n   * When `true`, requests matching the path will not be proxied and will be handled\n   * by other routes or return 404. Useful for feature toggles or conditional proxying.\n   *\n   * @default false\n   * @example !process.env.ENABLE_PROXY\n   */\n  disabled?: boolean;\n\n  /**\n   * Hook called before forwarding the request to the target server.\n   *\n   * Use this to:\n   * - Add authentication headers\n   * - Modify request headers or body\n   * - Add request tracking/logging\n   * - Transform the request before forwarding\n   *\n   * @param request - The original incoming server request\n   * @param proxyRequest - The request that will be sent to the target (modifiable)\n   *\n   * @example\n   * ```ts\n   * beforeRequest: async (request, proxyRequest) => {\n   *   proxyRequest.headers = {\n   *     ...proxyRequest.headers,\n   *     'Authorization': `Bearer ${await getToken()}`,\n   *     'X-Request-ID': generateRequestId()\n   *   };\n   * }\n   * ```\n   */\n  beforeRequest?: (\n    request: ServerRequest,\n    proxyRequest: RequestInit,\n  ) => Async<void>;\n\n  /**\n   * Hook called after receiving the response from the target server.\n   *\n   * Use this to:\n   * - Log response details for monitoring\n   * - Add custom headers to the response\n   * - Transform response data\n   * - Handle error responses\n   *\n   * @param request - The original incoming server request\n   * @param proxyResponse - The response received from the target server\n   *\n   * @example\n   * ```ts\n   * afterResponse: async (request, proxyResponse) => {\n   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);\n   *\n   *   if (!proxyResponse.ok) {\n   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });\n   *   }\n   * }\n   * ```\n   */\n  afterResponse?: (\n    request: ServerRequest,\n    proxyResponse: Response,\n  ) => Async<void>;\n\n  /**\n   * Function to rewrite the URL before sending to the target server.\n   *\n   * Use this to:\n   * - Remove or add path prefixes\n   * - Transform path parameters\n   * - Modify query parameters\n   * - Change the URL structure entirely\n   *\n   * The function receives a mutable URL object and should modify it in-place.\n   *\n   * @param url - The URL object to modify (mutable)\n   *\n   * @example\n   * ```ts\n   * // Remove /api prefix when forwarding\n   * rewrite: (url) => {\n   *   url.pathname = url.pathname.replace('/api', '');\n   * }\n   * ```\n   *\n   * @example\n   * ```ts\n   * // Add version prefix\n   * rewrite: (url) => {\n   *   url.pathname = `/v2${url.pathname}`;\n   * }\n   * ```\n   */\n  rewrite?: (url: URL) => void;\n\n  // TODO: Add retry functionality\n  // retry?: RetryOptions;\n};\n\nexport class ProxyPrimitive extends Primitive<ProxyPrimitiveOptions> {}\n\n$proxy[KIND] = ProxyPrimitive;\n","import { ReadableStream as WebStream } from \"node:stream/web\";\nimport { $hook, $inject, Alepha, AlephaError } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  routeMethods,\n  type ServerHandler,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport { $proxy, type ProxyPrimitiveOptions } from \"../primitives/$proxy.ts\";\n\nexport class ServerProxyProvider {\n  protected readonly log = $logger();\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly alepha = $inject(Alepha);\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    handler: () => {\n      for (const proxy of this.alepha.primitives($proxy)) {\n        this.createProxy(proxy.options);\n      }\n    },\n  });\n\n  public createProxy(options: ProxyPrimitiveOptions): void {\n    if (options.disabled) {\n      return;\n    }\n\n    const path = options.path;\n    const target =\n      typeof options.target === \"function\" ? options.target() : options.target;\n\n    if (!path.endsWith(\"/*\")) {\n      throw new AlephaError(\"Proxy path should end with '/*'\");\n    }\n\n    // Extract base path without /*\n    const handler = this.createProxyHandler(target, options);\n\n    for (const method of routeMethods) {\n      this.routerProvider.createRoute({\n        method,\n        path,\n        handler,\n      });\n    }\n\n    this.log.info(\"Proxying\", { path, target });\n  }\n\n  public createProxyHandler(\n    target: string,\n    options: Omit<ProxyPrimitiveOptions, \"path\">,\n  ): ServerHandler {\n    return async (request) => {\n      const url = new URL(target + request.url.pathname);\n      if (request.url.search) {\n        url.search = request.url.search;\n      }\n\n      options.rewrite?.(url);\n\n      const requestInit = {\n        url: url.toString(),\n        method: request.method,\n        headers: {\n          ...request.headers,\n          \"accept-encoding\": \"identity\", // ignore compression\n        },\n        body: this.getRawRequestBody(request),\n      };\n\n      if (requestInit.body) {\n        (requestInit as any).duplex = \"half\";\n      }\n\n      if (options.beforeRequest) {\n        await options.beforeRequest(request, requestInit);\n      }\n\n      this.log.debug(\"Proxying request\", {\n        url: url.toString(),\n        method: request.method,\n        headers: request.headers,\n      });\n\n      const response = await fetch(requestInit.url, requestInit);\n\n      request.reply.status = response.status;\n      request.reply.headers = Object.fromEntries(response.headers.entries());\n      request.reply.body = response.body;\n\n      this.log.debug(\"Received response\", {\n        status: request.reply.status,\n        headers: request.reply.headers,\n      });\n\n      if (options.afterResponse) {\n        await options.afterResponse(request, response);\n      }\n    };\n  }\n\n  private getRawRequestBody(req: ServerRequest): ReadableStream | undefined {\n    const { method } = req;\n\n    if (method === \"GET\" || method === \"HEAD\" || method === \"OPTIONS\") {\n      return;\n    }\n\n    if (req.raw?.web?.req) {\n      return req.raw.web.req.body as ReadableStream;\n    }\n\n    if (req.raw?.node?.req) {\n      const nodeReq = req.raw.node.req;\n      return WebStream.from(nodeReq) as unknown as ReadableStream;\n    }\n  }\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $proxy } from \"./primitives/$proxy.ts\";\nimport { ServerProxyProvider } from \"./providers/ServerProxyProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$proxy.ts\";\nexport * from \"./providers/ServerProxyProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha that provides a proxy server functionality.\n *\n * @see {@link $proxy}\n * @module alepha.server.proxy\n */\nexport const AlephaServerProxy = $module({\n  name: \"alepha.server.proxy\",\n  primitives: [$proxy],\n  services: [AlephaServer, ServerProxyProvider],\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,MAAa,UAAU,YAAmD;AACxE,QAAO,gBAAgB,gBAAgB,QAAQ;;AAsIjD,IAAa,iBAAb,cAAoC,UAAiC;AAErE,OAAO,QAAQ;;;;ACpNf,IAAa,sBAAb,MAAiC;CAC/B,AAAmB,MAAM,SAAS;CAClC,AAAmB,iBAAiB,QAAQ,qBAAqB;CACjE,AAAmB,SAAS,QAAQ,OAAO;CAE3C,AAAmB,YAAY,MAAM;EACnC,IAAI;EACJ,eAAe;AACb,QAAK,MAAM,SAAS,KAAK,OAAO,WAAW,OAAO,CAChD,MAAK,YAAY,MAAM,QAAQ;;EAGpC,CAAC;CAEF,AAAO,YAAY,SAAsC;AACvD,MAAI,QAAQ,SACV;EAGF,MAAM,OAAO,QAAQ;EACrB,MAAM,SACJ,OAAO,QAAQ,WAAW,aAAa,QAAQ,QAAQ,GAAG,QAAQ;AAEpE,MAAI,CAAC,KAAK,SAAS,KAAK,CACtB,OAAM,IAAI,YAAY,kCAAkC;EAI1D,MAAM,UAAU,KAAK,mBAAmB,QAAQ,QAAQ;AAExD,OAAK,MAAM,UAAU,aACnB,MAAK,eAAe,YAAY;GAC9B;GACA;GACA;GACD,CAAC;AAGJ,OAAK,IAAI,KAAK,YAAY;GAAE;GAAM;GAAQ,CAAC;;CAG7C,AAAO,mBACL,QACA,SACe;AACf,SAAO,OAAO,YAAY;GACxB,MAAM,MAAM,IAAI,IAAI,SAAS,QAAQ,IAAI,SAAS;AAClD,OAAI,QAAQ,IAAI,OACd,KAAI,SAAS,QAAQ,IAAI;AAG3B,WAAQ,UAAU,IAAI;GAEtB,MAAM,cAAc;IAClB,KAAK,IAAI,UAAU;IACnB,QAAQ,QAAQ;IAChB,SAAS;KACP,GAAG,QAAQ;KACX,mBAAmB;KACpB;IACD,MAAM,KAAK,kBAAkB,QAAQ;IACtC;AAED,OAAI,YAAY,KACd,CAAC,YAAoB,SAAS;AAGhC,OAAI,QAAQ,cACV,OAAM,QAAQ,cAAc,SAAS,YAAY;AAGnD,QAAK,IAAI,MAAM,oBAAoB;IACjC,KAAK,IAAI,UAAU;IACnB,QAAQ,QAAQ;IAChB,SAAS,QAAQ;IAClB,CAAC;GAEF,MAAM,WAAW,MAAM,MAAM,YAAY,KAAK,YAAY;AAE1D,WAAQ,MAAM,SAAS,SAAS;AAChC,WAAQ,MAAM,UAAU,OAAO,YAAY,SAAS,QAAQ,SAAS,CAAC;AACtE,WAAQ,MAAM,OAAO,SAAS;AAE9B,QAAK,IAAI,MAAM,qBAAqB;IAClC,QAAQ,QAAQ,MAAM;IACtB,SAAS,QAAQ,MAAM;IACxB,CAAC;AAEF,OAAI,QAAQ,cACV,OAAM,QAAQ,cAAc,SAAS,SAAS;;;CAKpD,AAAQ,kBAAkB,KAAgD;EACxE,MAAM,EAAE,WAAW;AAEnB,MAAI,WAAW,SAAS,WAAW,UAAU,WAAW,UACtD;AAGF,MAAI,IAAI,KAAK,KAAK,IAChB,QAAO,IAAI,IAAI,IAAI,IAAI;AAGzB,MAAI,IAAI,KAAK,MAAM,KAAK;GACtB,MAAM,UAAU,IAAI,IAAI,KAAK;AAC7B,UAAOA,eAAU,KAAK,QAAQ;;;;;;;;;;;;;ACpGpC,MAAa,oBAAoB,QAAQ;CACvC,MAAM;CACN,YAAY,CAAC,OAAO;CACpB,UAAU,CAAC,cAAc,oBAAoB;CAC9C,CAAC"}
+{"version":3,"file":"index.js","names":["WebStream"],"sources":["../../../src/server/proxy/primitives/$proxy.ts","../../../src/server/proxy/providers/ServerProxyProvider.ts","../../../src/server/proxy/index.ts"],"sourcesContent":["import { type Async, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\n\n/**\n * Creates a proxy primitive to forward requests to another server.\n *\n * This primitive enables you to create reverse proxy functionality, allowing your Alepha server\n * to forward requests to other services while maintaining a unified API surface. It's particularly\n * useful for microservice architectures, API gateways, or when you need to aggregate multiple\n * services behind a single endpoint.\n *\n * **Key Features**\n *\n * - **Path-based routing**: Match specific paths or patterns to proxy\n * - **Dynamic targets**: Support both static and dynamic target resolution\n * - **Request/Response hooks**: Modify requests before forwarding and responses after receiving\n * - **URL rewriting**: Transform URLs before forwarding to the target\n * - **Conditional proxying**: Enable/disable proxies based on environment or conditions\n *\n * @example\n * **Basic proxy setup:**\n * ```ts\n * import { $proxy } from \"alepha/server/proxy\";\n *\n * class ApiGateway {\n *   // Forward all /api/* requests to external service\n *   api = $proxy({\n *     path: \"/api/*\",\n *     target: \"https://api.example.com\"\n *   });\n * }\n * ```\n *\n * @example\n * **Dynamic target with environment-based routing:**\n * ```ts\n * class ApiGateway {\n *   // Route to different environments based on configuration\n *   api = $proxy({\n *     path: \"/api/*\",\n *     target: () => process.env.NODE_ENV === \"production\"\n *       ? \"https://api.prod.example.com\"\n *       : \"https://api.dev.example.com\"\n *   });\n * }\n * ```\n *\n * @example\n * **Advanced proxy with request/response modification:**\n * ```ts\n * class SecureProxy {\n *   secure = $proxy({\n *     path: \"/secure/*\",\n *     target: \"https://secure-api.example.com\",\n *     beforeRequest: async (request, proxyRequest) => {\n *       // Add authentication headers\n *       proxyRequest.headers = {\n *         ...proxyRequest.headers,\n *         'Authorization': `Bearer ${await getServiceToken()}`,\n *         'X-Forwarded-For': request.headers['x-forwarded-for'] || request.ip\n *       };\n *     },\n *     afterResponse: async (request, proxyResponse) => {\n *       // Log response for monitoring\n *       console.log(`Proxied ${request.url} -> ${proxyResponse.status}`);\n *     },\n *     rewrite: (url) => {\n *       // Remove /secure prefix when forwarding\n *       url.pathname = url.pathname.replace('/secure', '');\n *     }\n *   });\n * }\n * ```\n *\n * @example\n * **Conditional proxy based on feature flags:**\n * ```ts\n * class FeatureProxy {\n *   newApi = $proxy({\n *     path: \"/v2/*\",\n *     target: \"https://new-api.example.com\",\n *     disabled: !process.env.ENABLE_V2_API // Disable if feature flag is off\n *   });\n * }\n * ```\n */\nexport const $proxy = (options: ProxyPrimitiveOptions): ProxyPrimitive => {\n  return createPrimitive(ProxyPrimitive, options);\n};\n\nexport type ProxyPrimitiveOptions = {\n  /**\n   * Path pattern to match for proxying requests.\n   *\n   * Supports wildcards and path parameters:\n   * - `/api/*` - Matches all paths starting with `/api/`\n   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`\n   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.\n   *\n   * @example \"/api/*\"\n   * @example \"/secure/admin/*\"\n   * @example \"/users/:id/posts\"\n   */\n  path: string;\n\n  /**\n   * Target URL to which matching requests should be forwarded.\n   *\n   * Can be either:\n   * - **Static string**: A fixed URL like `\"https://api.example.com\"`\n   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution\n   *\n   * The target URL will be combined with the remaining path from the original request.\n   *\n   * @example \"https://api.example.com\"\n   * @example () => process.env.API_URL || \"http://localhost:3001\"\n   */\n  target: string | (() => string);\n\n  /**\n   * Whether this proxy is disabled.\n   *\n   * When `true`, requests matching the path will not be proxied and will be handled\n   * by other routes or return 404. Useful for feature toggles or conditional proxying.\n   *\n   * @default false\n   * @example !process.env.ENABLE_PROXY\n   */\n  disabled?: boolean;\n\n  /**\n   * Hook called before forwarding the request to the target server.\n   *\n   * Use this to:\n   * - Add authentication headers\n   * - Modify request headers or body\n   * - Add request tracking/logging\n   * - Transform the request before forwarding\n   *\n   * @param request - The original incoming server request\n   * @param proxyRequest - The request that will be sent to the target (modifiable)\n   *\n   * @example\n   * ```ts\n   * beforeRequest: async (request, proxyRequest) => {\n   *   proxyRequest.headers = {\n   *     ...proxyRequest.headers,\n   *     'Authorization': `Bearer ${await getToken()}`,\n   *     'X-Request-ID': generateRequestId()\n   *   };\n   * }\n   * ```\n   */\n  beforeRequest?: (\n    request: ServerRequest,\n    proxyRequest: RequestInit,\n  ) => Async<void>;\n\n  /**\n   * Hook called after receiving the response from the target server.\n   *\n   * Use this to:\n   * - Log response details for monitoring\n   * - Add custom headers to the response\n   * - Transform response data\n   * - Handle error responses\n   *\n   * @param request - The original incoming server request\n   * @param proxyResponse - The response received from the target server\n   *\n   * @example\n   * ```ts\n   * afterResponse: async (request, proxyResponse) => {\n   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);\n   *\n   *   if (!proxyResponse.ok) {\n   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });\n   *   }\n   * }\n   * ```\n   */\n  afterResponse?: (\n    request: ServerRequest,\n    proxyResponse: Response,\n  ) => Async<void>;\n\n  /**\n   * Function to rewrite the URL before sending to the target server.\n   *\n   * Use this to:\n   * - Remove or add path prefixes\n   * - Transform path parameters\n   * - Modify query parameters\n   * - Change the URL structure entirely\n   *\n   * The function receives a mutable URL object and should modify it in-place.\n   *\n   * @param url - The URL object to modify (mutable)\n   *\n   * @example\n   * ```ts\n   * // Remove /api prefix when forwarding\n   * rewrite: (url) => {\n   *   url.pathname = url.pathname.replace('/api', '');\n   * }\n   * ```\n   *\n   * @example\n   * ```ts\n   * // Add version prefix\n   * rewrite: (url) => {\n   *   url.pathname = `/v2${url.pathname}`;\n   * }\n   * ```\n   */\n  rewrite?: (url: URL) => void;\n\n  // TODO: Add retry functionality\n  // retry?: RetryOptions;\n};\n\nexport class ProxyPrimitive extends Primitive<ProxyPrimitiveOptions> {}\n\n$proxy[KIND] = ProxyPrimitive;\n","import { ReadableStream as WebStream } from \"node:stream/web\";\nimport { $hook, $inject, Alepha, AlephaError } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  routeMethods,\n  type ServerHandler,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport { $proxy, type ProxyPrimitiveOptions } from \"../primitives/$proxy.ts\";\n\nexport class ServerProxyProvider {\n  protected readonly log = $logger();\n  protected readonly routerProvider = $inject(ServerRouterProvider);\n  protected readonly alepha = $inject(Alepha);\n\n  protected readonly configure = $hook({\n    on: \"configure\",\n    handler: () => {\n      for (const proxy of this.alepha.primitives($proxy)) {\n        this.createProxy(proxy.options);\n      }\n    },\n  });\n\n  public createProxy(options: ProxyPrimitiveOptions): void {\n    if (options.disabled) {\n      return;\n    }\n\n    const path = options.path;\n    const target =\n      typeof options.target === \"function\" ? options.target() : options.target;\n\n    if (!path.endsWith(\"/*\")) {\n      throw new AlephaError(\"Proxy path should end with '/*'\");\n    }\n\n    // Extract base path without /*\n    const handler = this.createProxyHandler(target, options);\n\n    for (const method of routeMethods) {\n      this.routerProvider.createRoute({\n        method,\n        path,\n        handler,\n      });\n    }\n\n    this.log.info(\"Proxying\", { path, target });\n  }\n\n  public createProxyHandler(\n    target: string,\n    options: Omit<ProxyPrimitiveOptions, \"path\">,\n  ): ServerHandler {\n    return async (request) => {\n      const url = new URL(target + request.url.pathname);\n      if (request.url.search) {\n        url.search = request.url.search;\n      }\n\n      options.rewrite?.(url);\n\n      const requestInit = {\n        url: url.toString(),\n        method: request.method,\n        headers: {\n          ...request.headers,\n          \"accept-encoding\": \"identity\", // ignore compression\n        },\n        body: this.getRawRequestBody(request),\n      };\n\n      if (requestInit.body) {\n        (requestInit as any).duplex = \"half\";\n      }\n\n      if (options.beforeRequest) {\n        await options.beforeRequest(request, requestInit);\n      }\n\n      this.log.debug(\"Proxying request\", {\n        url: url.toString(),\n        method: request.method,\n        headers: request.headers,\n      });\n\n      const response = await fetch(requestInit.url, requestInit);\n\n      request.reply.status = response.status;\n      request.reply.headers = Object.fromEntries(response.headers.entries());\n      request.reply.body = response.body;\n\n      this.log.debug(\"Received response\", {\n        status: request.reply.status,\n        headers: request.reply.headers,\n      });\n\n      if (options.afterResponse) {\n        await options.afterResponse(request, response);\n      }\n    };\n  }\n\n  private getRawRequestBody(req: ServerRequest): ReadableStream | undefined {\n    const { method } = req;\n\n    if (method === \"GET\" || method === \"HEAD\" || method === \"OPTIONS\") {\n      return;\n    }\n\n    if (req.raw?.web?.req) {\n      return req.raw.web.req.body as ReadableStream;\n    }\n\n    if (req.raw?.node?.req) {\n      const nodeReq = req.raw.node.req;\n      return WebStream.from(nodeReq) as unknown as ReadableStream;\n    }\n  }\n}\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $proxy } from \"./primitives/$proxy.ts\";\nimport { ServerProxyProvider } from \"./providers/ServerProxyProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$proxy.ts\";\nexport * from \"./providers/ServerProxyProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * | type | quality | stability |\n * |------|---------|-----------|\n * | backend | standard | stable |\n *\n * Reverse proxy routing.\n *\n * **Features:**\n * - Proxy configuration and routing\n *\n * @module alepha.server.proxy\n */\nexport const AlephaServerProxy = $module({\n  name: \"alepha.server.proxy\",\n  primitives: [$proxy],\n  services: [AlephaServer, ServerProxyProvider],\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,MAAa,UAAU,YAAmD;AACxE,QAAO,gBAAgB,gBAAgB,QAAQ;;AAsIjD,IAAa,iBAAb,cAAoC,UAAiC;AAErE,OAAO,QAAQ;;;;ACpNf,IAAa,sBAAb,MAAiC;CAC/B,AAAmB,MAAM,SAAS;CAClC,AAAmB,iBAAiB,QAAQ,qBAAqB;CACjE,AAAmB,SAAS,QAAQ,OAAO;CAE3C,AAAmB,YAAY,MAAM;EACnC,IAAI;EACJ,eAAe;AACb,QAAK,MAAM,SAAS,KAAK,OAAO,WAAW,OAAO,CAChD,MAAK,YAAY,MAAM,QAAQ;;EAGpC,CAAC;CAEF,AAAO,YAAY,SAAsC;AACvD,MAAI,QAAQ,SACV;EAGF,MAAM,OAAO,QAAQ;EACrB,MAAM,SACJ,OAAO,QAAQ,WAAW,aAAa,QAAQ,QAAQ,GAAG,QAAQ;AAEpE,MAAI,CAAC,KAAK,SAAS,KAAK,CACtB,OAAM,IAAI,YAAY,kCAAkC;EAI1D,MAAM,UAAU,KAAK,mBAAmB,QAAQ,QAAQ;AAExD,OAAK,MAAM,UAAU,aACnB,MAAK,eAAe,YAAY;GAC9B;GACA;GACA;GACD,CAAC;AAGJ,OAAK,IAAI,KAAK,YAAY;GAAE;GAAM;GAAQ,CAAC;;CAG7C,AAAO,mBACL,QACA,SACe;AACf,SAAO,OAAO,YAAY;GACxB,MAAM,MAAM,IAAI,IAAI,SAAS,QAAQ,IAAI,SAAS;AAClD,OAAI,QAAQ,IAAI,OACd,KAAI,SAAS,QAAQ,IAAI;AAG3B,WAAQ,UAAU,IAAI;GAEtB,MAAM,cAAc;IAClB,KAAK,IAAI,UAAU;IACnB,QAAQ,QAAQ;IAChB,SAAS;KACP,GAAG,QAAQ;KACX,mBAAmB;KACpB;IACD,MAAM,KAAK,kBAAkB,QAAQ;IACtC;AAED,OAAI,YAAY,KACd,CAAC,YAAoB,SAAS;AAGhC,OAAI,QAAQ,cACV,OAAM,QAAQ,cAAc,SAAS,YAAY;AAGnD,QAAK,IAAI,MAAM,oBAAoB;IACjC,KAAK,IAAI,UAAU;IACnB,QAAQ,QAAQ;IAChB,SAAS,QAAQ;IAClB,CAAC;GAEF,MAAM,WAAW,MAAM,MAAM,YAAY,KAAK,YAAY;AAE1D,WAAQ,MAAM,SAAS,SAAS;AAChC,WAAQ,MAAM,UAAU,OAAO,YAAY,SAAS,QAAQ,SAAS,CAAC;AACtE,WAAQ,MAAM,OAAO,SAAS;AAE9B,QAAK,IAAI,MAAM,qBAAqB;IAClC,QAAQ,QAAQ,MAAM;IACtB,SAAS,QAAQ,MAAM;IACxB,CAAC;AAEF,OAAI,QAAQ,cACV,OAAM,QAAQ,cAAc,SAAS,SAAS;;;CAKpD,AAAQ,kBAAkB,KAAgD;EACxE,MAAM,EAAE,WAAW;AAEnB,MAAI,WAAW,SAAS,WAAW,UAAU,WAAW,UACtD;AAGF,MAAI,IAAI,KAAK,KAAK,IAChB,QAAO,IAAI,IAAI,IAAI,IAAI;AAGzB,MAAI,IAAI,KAAK,MAAM,KAAK;GACtB,MAAM,UAAU,IAAI,IAAI,KAAK;AAC7B,UAAOA,eAAU,KAAK,QAAQ;;;;;;;;;;;;;;;;;;;AC9FpC,MAAa,oBAAoB,QAAQ;CACvC,MAAM;CACN,YAAY,CAAC,OAAO;CACpB,UAAU,CAAC,cAAc,oBAAoB;CAC9C,CAAC"}

package/dist/server/rate-limit/index.d.ts

@@ -1,7 +1,7 @@
 import * as alepha1 from "alepha";
 import { KIND, Primitive, Static } from "alepha";
 import { ServerRequest, ServerRouterProvider } from "alepha/server";
-import * as alepha_cache0 from "alepha/cache";
+import { CacheProvider } from "alepha/cache";
 import * as alepha_logger0 from "alepha/logger";
 
 //#region ../../src/server/rate-limit/providers/ServerRateLimitProvider.d.ts
@@ -34,13 +34,14 @@ declare class ServerRateLimitProvider {
     RATE_LIMIT_WINDOW_MS: number;
     RATE_LIMIT_MAX_REQUESTS: number;
   };
-  protected readonly cache: alepha_cache0.CachePrimitiveFn<RateLimitData, any[]>;
+  protected readonly cacheProvider: CacheProvider;
   protected readonly globalOptions: Readonly<{
     windowMs?: number | undefined;
     max?: number | undefined;
     skipFailedRequests?: boolean | undefined;
     skipSuccessfulRequests?: boolean | undefined;
   }>;
+  protected static readonly CACHE_NAME = "rate-limit";
   /**
    * Registered rate limit configurations with their path patterns
    */
@@ -62,12 +63,6 @@ declare class ServerRateLimitProvider {
   protected setRateLimitHeaders(request: ServerRequest, result: RateLimitResult): void;
   checkLimit(req: ServerRequest, options?: RateLimitOptions): Promise<RateLimitResult>;
   protected generateKey(req: ServerRequest): string;
-  protected getClientIP(req: ServerRequest): string;
-}
-interface RateLimitData {
-  count: number;
-  windowStart: number;
-  hits: number[];
 }
 //#endregion
 //#region ../../src/server/rate-limit/primitives/$rateLimit.d.ts
@@ -102,9 +97,13 @@ declare const $rateLimit: {
   [KIND]: typeof RateLimitPrimitive;
 };
 interface RateLimitPrimitiveOptions extends RateLimitOptions {
-  /** Name identifier for this rate limit (default: property key) */
+  /**
+   * Name identifier for this rate limit (default: property key).
+   */
   name?: string;
-  /** Path patterns to match (supports wildcards like /api/*) */
+  /**
+   * Path patterns to match (supports wildcards like /api/*).
+   */
   paths?: string[];
 }
 interface AbstractRateLimitPrimitive {
@@ -140,41 +139,37 @@ declare module "alepha/server" {
   }
 }
 interface RateLimitOptions {
-  /** Maximum number of requests per window (default: 100) */
+  /**
+   * Maximum number of requests per window (default: 100).
+   */
   max?: number;
-  /** Window duration in milliseconds (default: 15 minutes) */
+  /**
+   * Window duration in milliseconds (default: 15 minutes).
+   */
   windowMs?: number;
-  /** Custom key generator function */
+  /**
+   * Custom key generator function.
+   */
   keyGenerator?: (req: any) => string;
-  /** Skip rate limiting for failed requests */
+  /**
+   * Skip rate limiting for failed requests.
+   */
   skipFailedRequests?: boolean;
-  /** Skip rate limiting for successful requests */
+  /**
+   * Skip rate limiting for successful requests.
+   */
   skipSuccessfulRequests?: boolean;
 }
 /**
- * Provides rate limiting capabilities for server routes and actions with configurable limits and windows.
- *
- * The server-rate-limit module enables per-route and per-action rate limiting using either:
- * - The `$rateLimit` primitive with `paths` option for path-based rate limiting
- * - The `rateLimit` option in action primitives for action-specific limiting
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.
+ * Request rate limiting on actions.
  *
- * @example
- * ```ts
- * import { $rateLimit, AlephaServerRateLimit } from "alepha/server/rate-limit";
- *
- * class ApiService {
- *   // Path-specific rate limiting
- *   apiRateLimit = $rateLimit({
- *     paths: ["/api/*"],
- *     max: 100,
- *     windowMs: 15 * 60 * 1000, // 15 minutes
- *   });
- * }
- * ```
+ * **Features:**
+ * - Rate limit configuration per action
  *
- * @see {@link $rateLimit}
  * @module alepha.server.rate-limit
  */
 declare const AlephaServerRateLimit: alepha1.Service<alepha1.Module>;

package/dist/server/rate-limit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"mappings":";;;;;;;UAaiB,eAAA;EACf,OAAA;EACA,KAAA;EACA,SAAA;EACA,SAAA;EACA,UAAA;AAAA;;;;cAMW,gBAAA,EAAgB,OAAA,CAAA,IAAA,SAAA,OAAA;8BAyB3B,OAAA,CAAA,OAAA;;;;;KAEU,oBAAA,GAAuB,MAAA,QAAc,gBAAA,CAAiB,MAAA;AAAA;EAAA,UAGtD,KAAA;IAAA,CACP,gBAAA,CAAiB,GAAA,GAAM,oBAAA;EAAA;AAAA;AAAA,cAiBf,uBAAA;EAAA,mBACQ,GAAA,EADe,cAAA,CACZ,MAAA;EAAA,mBACH,oBAAA,EAAoB,oBAAA;EAAA,mBACpB,GAAA;;;;qBAEA,KAAA,EAAK,aAAA,CAAA,gBAAA,CAAA,aAAA;EAAA,mBAKL,aAAA,EAAa,QAAA;;;;;;;;;WAKhB,iBAAA,EAAmB,yBAAA;;;;EAK5B,iBAAA,CAAkB,MAAA,EAAQ,yBAAA;EAAA,mBAId,OAAA,EAJuC,OAAA,CAIhC,aAAA;EAAA,SAuBV,SAAA,EAvBU,OAAA,CAuBD,aAAA;EAAA,SAuBT,eAAA,EAvBS,OAAA,CAuBM,aAAA;;;;YA2BrB,qBAAA,CACR,MAAA,EAAQ,yBAAA,GACP,gBAAA;EAxH6D;;;EAAA,UAwItD,mBAAA,CACR,OAAA,EAAS,aAAA,EACT,MAAA,EAAQ,eAAA;EAiBG,UAAA,CACX,GAAA,EAAK,aAAA,EACL,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA;EAAA,UAiDD,WAAA,CAAY,GAAA,EAAK,aAAA;EAAA,UAMjB,WAAA,CAAY,GAAA,EAAK,aAAA;AAAA;AAAA,UAanB,aAAA;EACR,KAAA;EACA,WAAA;EACA,IAAA;AAAA;;;;;;AA3QF;;;;;;;;;;;AAWA;;;;;;;;;;;;cCUa,UAAA;EAAA,WACF,yBAAA,GACR,0BAAA;EAAA;;UAMc,yBAAA,SAAkC,gBAAA;;EAEjD,IAAA;;EAEA,KAAA;AAAA;AAAA,UAGe,0BAAA;EAAA,SACN,IAAA;EAAA,SACA,OAAA,EAAS,yBAAA;EAClB,KAAA,CACE,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;AAAA,cAGA,kBAAA,SACH,SAAA,CAAU,yBAAA,aACP,0BAAA;EAAA,mBAEQ,uBAAA,EAAuB,uBAAA;EAAA,IAE/B,IAAA,CAAA;EAAA,UAID,MAAA,CAAA;EDjBA;;;ECyBG,KAAA,CACX,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;;;;YClED,sBAAA;;;;AFAZ;IEKI,SAAA,GAAY,gBAAA;EAAA;EAAA,UAGJ,WAAA;IFPV;;;;IEYE,SAAA,GAAY,gBAAA;EAAA;AAAA;AAAA,UAMC,gBAAA;EFiBf;EEfA,GAAA;EFeA;EEbA,QAAA;;EAEA,YAAA,IAAgB,GAAA;;EAEhB,kBAAA;;EAEA,sBAAA;AAAA;;;;;;;;;;;;;;;;;;;;AFSF;;;;;;;cEoBa,qBAAA,EAAqB,OAAA,CAAA,OAAA,CAIhC,OAAA,CAJgC,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"mappings":";;;;;;;UAaiB,eAAA;EACf,OAAA;EACA,KAAA;EACA,SAAA;EACA,SAAA;EACA,UAAA;AAAA;;;;cAMW,gBAAA,EAAgB,OAAA,CAAA,IAAA,SAAA,OAAA;8BAyB3B,OAAA,CAAA,OAAA;;;;;KAEU,oBAAA,GAAuB,MAAA,QAAc,gBAAA,CAAiB,MAAA;AAAA;EAAA,UAGtD,KAAA;IAAA,CACP,gBAAA,CAAiB,GAAA,GAAM,oBAAA;EAAA;AAAA;AAAA,cAiBf,uBAAA;EAAA,mBACQ,GAAA,EADe,cAAA,CACZ,MAAA;EAAA,mBACH,oBAAA,EAAoB,oBAAA;EAAA,mBACpB,GAAA;;;;qBACA,aAAA,EAAa,aAAA;EAAA,mBACb,aAAA,EAAa,QAAA;;;;;;4BAEN,UAAA;;;;WAKV,iBAAA,EAAmB,yBAAA;;;;EAK5B,iBAAA,CAAkB,MAAA,EAAQ,yBAAA;EAAA,mBAId,OAAA,EAJuC,OAAA,CAIhC,aAAA;EAAA,SAuBV,SAAA,EAvBU,OAAA,CAuBD,aAAA;EAAA,SAuBT,eAAA,EAvBS,OAAA,CAuBM,aAAA;EAxFE;;;EAAA,UAmHvB,qBAAA,CACR,MAAA,EAAQ,yBAAA,GACP,gBAAA;EArHmE;AAAE;;EAAF,UAqI5D,mBAAA,CACR,OAAA,EAAS,aAAA,EACT,MAAA,EAAQ,eAAA;EAiBG,UAAA,CACX,GAAA,EAAK,aAAA,EACL,OAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,eAAA;EAAA,UAqCD,WAAA,CAAY,GAAA,EAAK,aAAA;AAAA;;;;;;AAtO7B;;;;;;;;;;;AAWA;;;;;;;;;;;;cCUa,UAAA;EAAA,WACF,yBAAA,GACR,0BAAA;EAAA;;UAMc,yBAAA,SAAkC,gBAAA;;;;EAIjD,IAAA;;;;EAIA,KAAA;AAAA;AAAA,UAGe,0BAAA;EAAA,SACN,IAAA;EAAA,SACA,OAAA,EAAS,yBAAA;EAClB,KAAA,CACE,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;AAAA,cAGA,kBAAA,SACH,SAAA,CAAU,yBAAA,aACP,0BAAA;EAAA,mBAEQ,uBAAA,EAAuB,uBAAA;EAAA,IAE/B,IAAA,CAAA;EAAA,UAID,MAAA,CAAA;EDrBuB;;;EC6BpB,KAAA,CACX,OAAA,EAAS,aAAA,EACT,OAAA,GAAU,gBAAA,GACT,OAAA,CAAQ,eAAA;AAAA;;;;YCtED,sBAAA;;;;AFAZ;IEKI,SAAA,GAAY,gBAAA;EAAA;EAAA,UAGJ,WAAA;IFPV;;;;IEYE,SAAA,GAAY,gBAAA;EAAA;AAAA;AAAA,UAMC,gBAAA;EFiBf;;;EEbA,GAAA;;;;EAIA,QAAA;;;;EAIA,YAAA,IAAgB,GAAA;EFpBW;;;EEwB3B,kBAAA;;;;EAIA,sBAAA;AAAA;;;;;;;;;;AFDF;;;cEgBa,qBAAA,EAAqB,OAAA,CAAA,OAAA,CAIhC,OAAA,CAJgC,MAAA"}

package/dist/server/rate-limit/index.js

@@ -1,6 +1,6 @@
 import { $atom, $env, $hook, $inject, $module, $use, KIND, Primitive, createPrimitive, t } from "alepha";
 import { AlephaServer, HttpError, ServerRouterProvider } from "alepha/server";
-import { $cache } from "alepha/cache";
+import { CacheProvider } from "alepha/cache";
 import { $logger } from "alepha/logger";
 
 //#region ../../src/server/rate-limit/providers/ServerRateLimitProvider.ts
@@ -27,15 +27,13 @@ const envSchema = t.object({
 		description: "Maximum requests per window"
 	})
 });
-var ServerRateLimitProvider = class {
+var ServerRateLimitProvider = class ServerRateLimitProvider {
 	log = $logger();
 	serverRouterProvider = $inject(ServerRouterProvider);
 	env = $env(envSchema);
-	cache = $cache({
-		name: "server-rate-limit",
-		ttl: [this.env.RATE_LIMIT_WINDOW_MS, "milliseconds"]
-	});
+	cacheProvider = $inject(CacheProvider);
 	globalOptions = $use(rateLimitOptions);
+	static CACHE_NAME = "rate-limit";
 	/**
 	* Registered rate limit configurations with their path patterns
 	*/
@@ -104,45 +102,24 @@ var ServerRateLimitProvider = class {
 	async checkLimit(req, options = {}) {
 		const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;
 		const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;
-		const key = this.generateKey(req);
+		const baseKey = this.generateKey(req);
 		const now = Date.now();
-		const windowStart = now - windowMs;
-		const currentData = await this.cache.get(key) || {
-			count: 0,
-			windowStart: now,
-			hits: []
-		};
-		const validHits = currentData.hits.filter((hit) => hit >= windowStart);
-		const allowed = validHits.length < max;
-		const remaining = Math.max(0, max - validHits.length);
-		const resetTime = Math.max(...validHits, windowStart) + windowMs;
-		if (allowed) {
-			validHits.push(now);
-			await this.cache.set(key, {
-				count: validHits.length,
-				windowStart: Math.min(currentData.windowStart, windowStart),
-				hits: validHits
-			});
-		}
+		const windowStart = Math.floor(now / windowMs) * windowMs;
+		const resetTime = windowStart + windowMs;
+		const key = `${baseKey}:${windowStart}`;
+		const count = await this.cacheProvider.incr(ServerRateLimitProvider.CACHE_NAME, key, 1);
+		const allowed = count <= max;
 		const result = {
 			allowed,
 			limit: max,
-			remaining: allowed ? remaining - 1 : remaining,
+			remaining: Math.max(0, max - count),
 			resetTime
 		};
 		if (!allowed) result.retryAfter = Math.ceil((resetTime - now) / 1e3);
 		return result;
 	}
 	generateKey(req) {
-		return `ip:${this.getClientIP(req)}`;
-	}
-	getClientIP(req) {
-		const forwarded = req.headers?.["x-forwarded-for"];
-		if (forwarded) {
-			const firstIp = forwarded.split(",")[0].trim();
-			if (firstIp) return firstIp;
-		}
-		return req.ip || "unknown";
+		return `ip:${req.ip || "unknown"}`;
 	}
 };
 
@@ -201,29 +178,15 @@ $rateLimit[KIND] = RateLimitPrimitive;
 //#endregion
 //#region ../../src/server/rate-limit/index.ts
 /**
-* Provides rate limiting capabilities for server routes and actions with configurable limits and windows.
-*
-* The server-rate-limit module enables per-route and per-action rate limiting using either:
-* - The `$rateLimit` primitive with `paths` option for path-based rate limiting
-* - The `rateLimit` option in action primitives for action-specific limiting
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | standard | stable |
 *
-* It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.
-*
-* @example
-* ```ts
-* import { $rateLimit, AlephaServerRateLimit } from "alepha/server/rate-limit";
+* Request rate limiting on actions.
 *
-* class ApiService {
-*   // Path-specific rate limiting
-*   apiRateLimit = $rateLimit({
-*     paths: ["/api/*"],
-*     max: 100,
-*     windowMs: 15 * 60 * 1000, // 15 minutes
-*   });
-* }
-* ```
+* **Features:**
+* - Rate limit configuration per action
 *
-* @see {@link $rateLimit}
 * @module alepha.server.rate-limit
 */
 const AlephaServerRateLimit = $module({

package/dist/server/rate-limit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"sourcesContent":["import { $atom, $env, $hook, $inject, $use, type Static, t } from \"alepha\";\nimport { $cache } from \"alepha/cache\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport type { RateLimitPrimitiveOptions } from \"../primitives/$rateLimit.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitResult {\n  allowed: boolean;\n  limit: number;\n  remaining: number;\n  resetTime: number;\n  retryAfter?: number;\n}\n\n/**\n * Rate limit configuration atom (global defaults)\n */\nexport const rateLimitOptions = $atom({\n  name: \"alepha.server.rate-limit.options\",\n  schema: t.object({\n    windowMs: t.optional(\n      t.number({\n        description: \"Window duration in milliseconds\",\n      }),\n    ),\n    max: t.optional(\n      t.number({\n        description: \"Maximum number of requests per window\",\n      }),\n    ),\n    skipFailedRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for failed requests\",\n      }),\n    ),\n    skipSuccessfulRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for successful requests\",\n      }),\n    ),\n  }),\n  default: {},\n});\n\nexport type RateLimitAtomOptions = Static<typeof rateLimitOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [rateLimitOptions.key]: RateLimitAtomOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nconst envSchema = t.object({\n  RATE_LIMIT_WINDOW_MS: t.number({\n    default: 15 * 60 * 1000, // 15 minutes\n    description: \"Rate limit window in milliseconds\",\n  }),\n  RATE_LIMIT_MAX_REQUESTS: t.number({\n    default: 100,\n    description: \"Maximum requests per window\",\n  }),\n});\n\nexport class ServerRateLimitProvider {\n  protected readonly log = $logger();\n  protected readonly serverRouterProvider = $inject(ServerRouterProvider);\n  protected readonly env = $env(envSchema);\n\n  protected readonly cache = $cache<RateLimitData>({\n    name: \"server-rate-limit\",\n    ttl: [this.env.RATE_LIMIT_WINDOW_MS, \"milliseconds\"],\n  });\n\n  protected readonly globalOptions = $use(rateLimitOptions);\n\n  /**\n   * Registered rate limit configurations with their path patterns\n   */\n  public readonly registeredConfigs: RateLimitPrimitiveOptions[] = [];\n\n  /**\n   * Register a rate limit configuration (called by primitives)\n   */\n  public registerRateLimit(config: RateLimitPrimitiveOptions): void {\n    this.registeredConfigs.push(config);\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      // Apply path-specific rate limit configs to routes\n      for (const config of this.registeredConfigs) {\n        if (config.paths) {\n          for (const pattern of config.paths) {\n            const matchedRoutes = this.serverRouterProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.rateLimit = this.buildRateLimitOptions(config);\n            }\n          }\n        }\n      }\n\n      if (this.registeredConfigs.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredConfigs.length} registered rate-limit configurations.`,\n        );\n      }\n    },\n  });\n\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      // Use route-specific rate limit if defined, otherwise use global options\n      const rateLimitConfig = route.rateLimit ?? this.globalOptions;\n\n      // Skip if no rate limiting configured\n      if (!rateLimitConfig.max && !rateLimitConfig.windowMs) {\n        return;\n      }\n\n      const result = await this.checkLimit(request, rateLimitConfig);\n      this.setRateLimitHeaders(request, result);\n\n      if (!result.allowed) {\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n    },\n  });\n\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      // Check if this action has rate limiting enabled\n      const rateLimit = action.options?.rateLimit;\n      if (!rateLimit) {\n        return; // No rate limiting for this action\n      }\n\n      const result = await this.checkLimit(request, rateLimit);\n\n      if (!result.allowed) {\n        // Actions are internal - don't set HTTP headers\n        // Only throw error to prevent action execution\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n\n      // Action allowed - no headers to set since actions are internal\n    },\n  });\n\n  /**\n   * Build complete rate limit options by merging with global defaults\n   */\n  protected buildRateLimitOptions(\n    config: RateLimitPrimitiveOptions,\n  ): RateLimitOptions {\n    return {\n      max: config.max ?? this.globalOptions.max,\n      windowMs: config.windowMs ?? this.globalOptions.windowMs,\n      keyGenerator: config.keyGenerator,\n      skipFailedRequests:\n        config.skipFailedRequests ?? this.globalOptions.skipFailedRequests,\n      skipSuccessfulRequests:\n        config.skipSuccessfulRequests ??\n        this.globalOptions.skipSuccessfulRequests,\n    };\n  }\n\n  /**\n   * Set rate limit headers on the response\n   */\n  protected setRateLimitHeaders(\n    request: ServerRequest,\n    result: RateLimitResult,\n  ): void {\n    request.reply.setHeader(\"X-RateLimit-Limit\", result.limit.toString());\n    request.reply.setHeader(\n      \"X-RateLimit-Remaining\",\n      result.remaining.toString(),\n    );\n    request.reply.setHeader(\n      \"X-RateLimit-Reset\",\n      Math.ceil(result.resetTime / 1000).toString(),\n    );\n\n    if (!result.allowed && result.retryAfter) {\n      request.reply.setHeader(\"Retry-After\", result.retryAfter.toString());\n    }\n  }\n\n  public async checkLimit(\n    req: ServerRequest,\n    options: RateLimitOptions = {},\n  ): Promise<RateLimitResult> {\n    const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;\n    const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;\n    const key = this.generateKey(req);\n\n    const now = Date.now();\n    const windowStart = now - windowMs;\n\n    // Get current rate limit data\n    const currentData = (await this.cache.get(key)) || {\n      count: 0,\n      windowStart: now,\n      hits: [],\n    };\n\n    // Clean old hits outside the current window\n    const validHits = currentData.hits.filter(\n      (hit: number) => hit >= windowStart,\n    );\n\n    // Check if limit exceeded\n    const allowed = validHits.length < max;\n    const remaining = Math.max(0, max - validHits.length);\n    const resetTime = Math.max(...validHits, windowStart) + windowMs;\n\n    // If allowed, record this request\n    if (allowed) {\n      validHits.push(now);\n      await this.cache.set(key, {\n        count: validHits.length,\n        windowStart: Math.min(currentData.windowStart, windowStart),\n        hits: validHits,\n      });\n    }\n\n    const result: RateLimitResult = {\n      allowed,\n      limit: max,\n      remaining: allowed ? remaining - 1 : remaining,\n      resetTime,\n    };\n\n    if (!allowed) {\n      result.retryAfter = Math.ceil((resetTime - now) / 1000);\n    }\n\n    return result;\n  }\n\n  protected generateKey(req: ServerRequest): string {\n    // Default to IP-based rate limiting\n    const ip = this.getClientIP(req);\n    return `ip:${ip}`;\n  }\n\n  protected getClientIP(req: ServerRequest): string {\n    // Check x-forwarded-for header first (for proxies/load balancers)\n    const forwarded = req.headers?.[\"x-forwarded-for\"];\n    if (forwarded) {\n      // x-forwarded-for can contain multiple IPs, get the first one (original client)\n      const firstIp = forwarded.split(\",\")[0].trim();\n      if (firstIp) return firstIp;\n    }\n\n    return req.ip || \"unknown\";\n  }\n}\n\ninterface RateLimitData {\n  count: number;\n  windowStart: number;\n  hits: number[];\n}\n","import { $inject, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport {\n  type RateLimitResult,\n  ServerRateLimitProvider,\n} from \"../providers/ServerRateLimitProvider.ts\";\n\n/**\n * Declares rate limiting for server routes or custom usage.\n * This primitive provides methods to check rate limits and configure behavior\n * within the server request/response cycle.\n *\n * @example\n * ```ts\n * class ApiService {\n *   // Apply rate limiting to specific paths\n *   apiRateLimit = $rateLimit({\n *     paths: [\"/api/*\"],\n *     max: 100,\n *     windowMs: 15 * 60 * 1000, // 15 minutes\n *   });\n *\n *   // Or use check() method for manual rate limiting\n *   customAction = $action({\n *     handler: async (req) => {\n *       const result = await this.apiRateLimit.check(req);\n *       if (!result.allowed) throw new Error(\"Rate limited\");\n *       return \"ok\";\n *     },\n *   });\n * }\n * ```\n */\nexport const $rateLimit = (\n  options: RateLimitPrimitiveOptions = {},\n): AbstractRateLimitPrimitive => {\n  return createPrimitive(RateLimitPrimitive, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitPrimitiveOptions extends RateLimitOptions {\n  /** Name identifier for this rate limit (default: property key) */\n  name?: string;\n  /** Path patterns to match (supports wildcards like /api/*) */\n  paths?: string[];\n}\n\nexport interface AbstractRateLimitPrimitive {\n  readonly name: string;\n  readonly options: RateLimitPrimitiveOptions;\n  check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult>;\n}\n\nexport class RateLimitPrimitive\n  extends Primitive<RateLimitPrimitiveOptions>\n  implements AbstractRateLimitPrimitive\n{\n  protected readonly serverRateLimitProvider = $inject(ServerRateLimitProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this rate limit configuration with the provider\n    this.serverRateLimitProvider.registerRateLimit(this.options);\n  }\n\n  /**\n   * Checks rate limit for the given request using this primitive's configuration.\n   */\n  public async check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult> {\n    const mergedOptions = { ...this.options, ...options };\n    return this.serverRateLimitProvider.checkLimit(request, mergedOptions);\n  }\n}\n\n$rateLimit[KIND] = RateLimitPrimitive;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $rateLimit } from \"./primitives/$rateLimit.ts\";\nimport { ServerRateLimitProvider } from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$rateLimit.ts\";\nexport * from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionPrimitiveOptions<TConfig> {\n    /**\n     * Rate limiting configuration for this action.\n     * When specified, the action will be rate limited according to these settings.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n\n  interface ServerRoute {\n    /**\n     * Route-specific rate limit configuration.\n     * If set, overrides the global rate limit options for this route.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitOptions {\n  /** Maximum number of requests per window (default: 100) */\n  max?: number;\n  /** Window duration in milliseconds (default: 15 minutes) */\n  windowMs?: number;\n  /** Custom key generator function */\n  keyGenerator?: (req: any) => string;\n  /** Skip rate limiting for failed requests */\n  skipFailedRequests?: boolean;\n  /** Skip rate limiting for successful requests */\n  skipSuccessfulRequests?: boolean;\n}\n\n/**\n * Provides rate limiting capabilities for server routes and actions with configurable limits and windows.\n *\n * The server-rate-limit module enables per-route and per-action rate limiting using either:\n * - The `$rateLimit` primitive with `paths` option for path-based rate limiting\n * - The `rateLimit` option in action primitives for action-specific limiting\n *\n * It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.\n *\n * @example\n * ```ts\n * import { $rateLimit, AlephaServerRateLimit } from \"alepha/server/rate-limit\";\n *\n * class ApiService {\n *   // Path-specific rate limiting\n *   apiRateLimit = $rateLimit({\n *     paths: [\"/api/*\"],\n *     max: 100,\n *     windowMs: 15 * 60 * 1000, // 15 minutes\n *   });\n * }\n * ```\n *\n * @see {@link $rateLimit}\n * @module alepha.server.rate-limit\n */\nexport const AlephaServerRateLimit = $module({\n  name: \"alepha.server.rate-limit\",\n  primitives: [$rateLimit],\n  services: [AlephaServer, ServerRateLimitProvider],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/server/rate-limit/providers/ServerRateLimitProvider.ts","../../../src/server/rate-limit/primitives/$rateLimit.ts","../../../src/server/rate-limit/index.ts"],"sourcesContent":["import { $atom, $env, $hook, $inject, $use, type Static, t } from \"alepha\";\nimport { CacheProvider } from \"alepha/cache\";\nimport { $logger } from \"alepha/logger\";\nimport {\n  HttpError,\n  type ServerRequest,\n  ServerRouterProvider,\n} from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport type { RateLimitPrimitiveOptions } from \"../primitives/$rateLimit.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitResult {\n  allowed: boolean;\n  limit: number;\n  remaining: number;\n  resetTime: number;\n  retryAfter?: number;\n}\n\n/**\n * Rate limit configuration atom (global defaults)\n */\nexport const rateLimitOptions = $atom({\n  name: \"alepha.server.rate-limit.options\",\n  schema: t.object({\n    windowMs: t.optional(\n      t.number({\n        description: \"Window duration in milliseconds\",\n      }),\n    ),\n    max: t.optional(\n      t.number({\n        description: \"Maximum number of requests per window\",\n      }),\n    ),\n    skipFailedRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for failed requests\",\n      }),\n    ),\n    skipSuccessfulRequests: t.optional(\n      t.boolean({\n        description: \"Skip rate limiting for successful requests\",\n      }),\n    ),\n  }),\n  default: {},\n});\n\nexport type RateLimitAtomOptions = Static<typeof rateLimitOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [rateLimitOptions.key]: RateLimitAtomOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nconst envSchema = t.object({\n  RATE_LIMIT_WINDOW_MS: t.number({\n    default: 15 * 60 * 1000, // 15 minutes\n    description: \"Rate limit window in milliseconds\",\n  }),\n  RATE_LIMIT_MAX_REQUESTS: t.number({\n    default: 100,\n    description: \"Maximum requests per window\",\n  }),\n});\n\nexport class ServerRateLimitProvider {\n  protected readonly log = $logger();\n  protected readonly serverRouterProvider = $inject(ServerRouterProvider);\n  protected readonly env = $env(envSchema);\n  protected readonly cacheProvider = $inject(CacheProvider);\n  protected readonly globalOptions = $use(rateLimitOptions);\n\n  protected static readonly CACHE_NAME = \"rate-limit\";\n\n  /**\n   * Registered rate limit configurations with their path patterns\n   */\n  public readonly registeredConfigs: RateLimitPrimitiveOptions[] = [];\n\n  /**\n   * Register a rate limit configuration (called by primitives)\n   */\n  public registerRateLimit(config: RateLimitPrimitiveOptions): void {\n    this.registeredConfigs.push(config);\n  }\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      // Apply path-specific rate limit configs to routes\n      for (const config of this.registeredConfigs) {\n        if (config.paths) {\n          for (const pattern of config.paths) {\n            const matchedRoutes = this.serverRouterProvider.getRoutes(pattern);\n            for (const route of matchedRoutes) {\n              route.rateLimit = this.buildRateLimitOptions(config);\n            }\n          }\n        }\n      }\n\n      if (this.registeredConfigs.length > 0) {\n        this.log.info(\n          `Initialized with ${this.registeredConfigs.length} registered rate-limit configurations.`,\n        );\n      }\n    },\n  });\n\n  public readonly onRequest = $hook({\n    on: \"server:onRequest\",\n    handler: async ({ route, request }) => {\n      // Use route-specific rate limit if defined, otherwise use global options\n      const rateLimitConfig = route.rateLimit ?? this.globalOptions;\n\n      // Skip if no rate limiting configured\n      if (!rateLimitConfig.max && !rateLimitConfig.windowMs) {\n        return;\n      }\n\n      const result = await this.checkLimit(request, rateLimitConfig);\n      this.setRateLimitHeaders(request, result);\n\n      if (!result.allowed) {\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n    },\n  });\n\n  public readonly onActionRequest = $hook({\n    on: \"action:onRequest\",\n    handler: async ({ action, request }) => {\n      // Check if this action has rate limiting enabled\n      const rateLimit = action.options?.rateLimit;\n      if (!rateLimit) {\n        return; // No rate limiting for this action\n      }\n\n      const result = await this.checkLimit(request, rateLimit);\n\n      if (!result.allowed) {\n        // Actions are internal - don't set HTTP headers\n        // Only throw error to prevent action execution\n        throw new HttpError({\n          status: 429,\n          message: \"Too Many Requests\",\n        });\n      }\n\n      // Action allowed - no headers to set since actions are internal\n    },\n  });\n\n  /**\n   * Build complete rate limit options by merging with global defaults\n   */\n  protected buildRateLimitOptions(\n    config: RateLimitPrimitiveOptions,\n  ): RateLimitOptions {\n    return {\n      max: config.max ?? this.globalOptions.max,\n      windowMs: config.windowMs ?? this.globalOptions.windowMs,\n      keyGenerator: config.keyGenerator,\n      skipFailedRequests:\n        config.skipFailedRequests ?? this.globalOptions.skipFailedRequests,\n      skipSuccessfulRequests:\n        config.skipSuccessfulRequests ??\n        this.globalOptions.skipSuccessfulRequests,\n    };\n  }\n\n  /**\n   * Set rate limit headers on the response\n   */\n  protected setRateLimitHeaders(\n    request: ServerRequest,\n    result: RateLimitResult,\n  ): void {\n    request.reply.setHeader(\"X-RateLimit-Limit\", result.limit.toString());\n    request.reply.setHeader(\n      \"X-RateLimit-Remaining\",\n      result.remaining.toString(),\n    );\n    request.reply.setHeader(\n      \"X-RateLimit-Reset\",\n      Math.ceil(result.resetTime / 1000).toString(),\n    );\n\n    if (!result.allowed && result.retryAfter) {\n      request.reply.setHeader(\"Retry-After\", result.retryAfter.toString());\n    }\n  }\n\n  public async checkLimit(\n    req: ServerRequest,\n    options: RateLimitOptions = {},\n  ): Promise<RateLimitResult> {\n    const windowMs = options.windowMs ?? this.env.RATE_LIMIT_WINDOW_MS;\n    const max = options.max ?? this.env.RATE_LIMIT_MAX_REQUESTS;\n    const baseKey = this.generateKey(req);\n\n    const now = Date.now();\n    // Fixed window: round down to nearest window boundary\n    const windowStart = Math.floor(now / windowMs) * windowMs;\n    const resetTime = windowStart + windowMs;\n\n    // Include window timestamp in key for automatic expiration of old windows\n    const key = `${baseKey}:${windowStart}`;\n\n    // Atomic increment - returns the new count after incrementing\n    const count = await this.cacheProvider.incr(\n      ServerRateLimitProvider.CACHE_NAME,\n      key,\n      1,\n    );\n\n    const allowed = count <= max;\n    const remaining = Math.max(0, max - count);\n\n    const result: RateLimitResult = {\n      allowed,\n      limit: max,\n      remaining,\n      resetTime,\n    };\n\n    if (!allowed) {\n      result.retryAfter = Math.ceil((resetTime - now) / 1000);\n    }\n\n    return result;\n  }\n\n  protected generateKey(req: ServerRequest): string {\n    // Use req.ip which is resolved by ServerRequestParser with proper trust proxy handling\n    return `ip:${req.ip || \"unknown\"}`;\n  }\n}\n","import { $inject, createPrimitive, KIND, Primitive } from \"alepha\";\nimport type { ServerRequest } from \"alepha/server\";\nimport type { RateLimitOptions } from \"../index.ts\";\nimport {\n  type RateLimitResult,\n  ServerRateLimitProvider,\n} from \"../providers/ServerRateLimitProvider.ts\";\n\n/**\n * Declares rate limiting for server routes or custom usage.\n * This primitive provides methods to check rate limits and configure behavior\n * within the server request/response cycle.\n *\n * @example\n * ```ts\n * class ApiService {\n *   // Apply rate limiting to specific paths\n *   apiRateLimit = $rateLimit({\n *     paths: [\"/api/*\"],\n *     max: 100,\n *     windowMs: 15 * 60 * 1000, // 15 minutes\n *   });\n *\n *   // Or use check() method for manual rate limiting\n *   customAction = $action({\n *     handler: async (req) => {\n *       const result = await this.apiRateLimit.check(req);\n *       if (!result.allowed) throw new Error(\"Rate limited\");\n *       return \"ok\";\n *     },\n *   });\n * }\n * ```\n */\nexport const $rateLimit = (\n  options: RateLimitPrimitiveOptions = {},\n): AbstractRateLimitPrimitive => {\n  return createPrimitive(RateLimitPrimitive, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitPrimitiveOptions extends RateLimitOptions {\n  /**\n   * Name identifier for this rate limit (default: property key).\n   */\n  name?: string;\n  /**\n   * Path patterns to match (supports wildcards like /api/*).\n   */\n  paths?: string[];\n}\n\nexport interface AbstractRateLimitPrimitive {\n  readonly name: string;\n  readonly options: RateLimitPrimitiveOptions;\n  check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult>;\n}\n\nexport class RateLimitPrimitive\n  extends Primitive<RateLimitPrimitiveOptions>\n  implements AbstractRateLimitPrimitive\n{\n  protected readonly serverRateLimitProvider = $inject(ServerRateLimitProvider);\n\n  public get name(): string {\n    return this.options.name ?? `${this.config.propertyKey}`;\n  }\n\n  protected onInit() {\n    // Register this rate limit configuration with the provider\n    this.serverRateLimitProvider.registerRateLimit(this.options);\n  }\n\n  /**\n   * Checks rate limit for the given request using this primitive's configuration.\n   */\n  public async check(\n    request: ServerRequest,\n    options?: RateLimitOptions,\n  ): Promise<RateLimitResult> {\n    const mergedOptions = { ...this.options, ...options };\n    return this.serverRateLimitProvider.checkLimit(request, mergedOptions);\n  }\n}\n\n$rateLimit[KIND] = RateLimitPrimitive;\n","import { $module } from \"alepha\";\nimport { AlephaServer } from \"alepha/server\";\nimport { $rateLimit } from \"./primitives/$rateLimit.ts\";\nimport { ServerRateLimitProvider } from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$rateLimit.ts\";\nexport * from \"./providers/ServerRateLimitProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/server\" {\n  interface ActionPrimitiveOptions<TConfig> {\n    /**\n     * Rate limiting configuration for this action.\n     * When specified, the action will be rate limited according to these settings.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n\n  interface ServerRoute {\n    /**\n     * Route-specific rate limit configuration.\n     * If set, overrides the global rate limit options for this route.\n     */\n    rateLimit?: RateLimitOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface RateLimitOptions {\n  /**\n   * Maximum number of requests per window (default: 100).\n   */\n  max?: number;\n  /**\n   * Window duration in milliseconds (default: 15 minutes).\n   */\n  windowMs?: number;\n  /**\n   * Custom key generator function.\n   */\n  keyGenerator?: (req: any) => string;\n  /**\n   * Skip rate limiting for failed requests.\n   */\n  skipFailedRequests?: boolean;\n  /**\n   * Skip rate limiting for successful requests.\n   */\n  skipSuccessfulRequests?: boolean;\n}\n\n/**\n * | type | quality | stability |\n * |------|---------|-----------|\n * | backend | standard | stable |\n *\n * Request rate limiting on actions.\n *\n * **Features:**\n * - Rate limit configuration per action\n *\n * @module alepha.server.rate-limit\n */\nexport const AlephaServerRateLimit = $module({\n  name: \"alepha.server.rate-limit\",\n  primitives: [$rateLimit],\n  services: [AlephaServer, ServerRateLimitProvider],\n});\n"],"mappings":"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"}