skyguard-js 1.2.1 → 1.2.3

package/dist/middlewares/rateLimiter.d.ts

@@ -1,9 +1,41 @@
-import { Request, Response } from "../http";
-import type { Middleware } from "../types";
+import { Context } from "../http";
+import type { Middleware, RouteHandler } from "../types";
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Mutable counter entry for a single rate-limit key.
+ */
+export interface RateLimitStoreEntry {
+    /** Requests performed in the current window. */
+    count: number;
+    /** Absolute timestamp (ms) when the current window expires. */
+    resetTime: number;
+}
+/**
+ * Pluggable store contract for rate limiting.
+ *
+ * Use a shared implementation (e.g. Redis) in multi-instance deployments.
+ */
+export interface RateLimitStore {
+    /**
+     * Increments the counter for `key` in the active window.
+     *
+     * @param key - Unique client key.
+     * @param windowMs - Active window size in milliseconds.
+     * @param now - Current unix timestamp in milliseconds.
+     * @returns Updated counter entry for the key.
+     */
+    increment(key: string, windowMs: number, now: number): MaybePromise<RateLimitStoreEntry>;
+    /**
+     * Optional cleanup hook for removing expired entries.
+     *
+     * @param now - Current unix timestamp in milliseconds.
+     */
+    cleanup?(now: number): MaybePromise<void>;
+}
 /**
  * Rate limit middleware configuration.
  */
-interface RateLimitOptions {
+export interface RateLimitOptions {
     /**
      * Time window in milliseconds where requests are counted.
      * @default 60000
@@ -26,11 +58,31 @@ interface RateLimitOptions {
     /**
      * Resolves the identity key used for counting requests.
      */
-    keyGenerator?: (request: Request) => string;
+    keyGenerator?: (context: Context) => string;
+    /**
+     * Trusts proxy-provided IP headers (`x-forwarded-for`, `x-real-ip`,
+     * `cf-connecting-ip`) in the default key generator.
+     * @default false
+     */
+    trustProxy?: boolean;
+    /**
+     * Custom store implementation. Defaults to in-memory store.
+     */
+    store?: RateLimitStore;
+    /**
+     * Periodic cleanup interval for stores that support `cleanup`.
+     * @default windowMs
+     */
+    cleanupIntervalMs?: number;
+    /**
+     * Max number of keys retained by the built-in in-memory store.
+     * @default 50000
+     */
+    maxKeys?: number;
     /**
      * Optional predicate to skip rate limiting for selected requests.
      */
-    skip?: (request: Request) => boolean | Promise<boolean>;
+    skip?: (context: Context) => boolean | Promise<boolean>;
     /**
      * Includes `RateLimit-*` response headers.
      * @default true
@@ -44,7 +96,7 @@ interface RateLimitOptions {
     /**
      * Optional custom handler executed when the limit is exceeded.
      */
-    handler?: (request: Request) => Response | Promise<Response>;
+    handler?: RouteHandler;
 }
 /**
  * Creates a configurable request rate-limiting middleware.

package/dist/middlewares/rateLimiter.js

@@ -3,35 +3,146 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rateLimit = void 0;
 const http_1 = require("../http");
 const httpExceptions_1 = require("../exceptions/httpExceptions");
+const node_net_1 = require("node:net");
 /**
- * Default key generator used by the rate limiter to uniquely identify a client.
+ * Default in-memory implementation of {@link RateLimitStore}.
  *
- * The function attempts to extract the client IP address from common proxy
- * headers in order of priority:
- *
- * 1. `x-forwarded-for` → typically used by reverse proxies and load balancers.
- *    If multiple IPs are present, the first one is assumed to be the client IP.
- * 2. `x-real-ip` → used by some proxies (e.g., Nginx).
- * 3. `cf-connecting-ip` → used by Cloudflare to forward the original client IP.
+ * Use a shared external store (e.g. Redis) for distributed environments.
+ */
+class MemoryRateLimitStore {
+    maxKeys;
+    store = new Map();
+    /**
+     * @param maxKeys - Maximum number of retained keys in memory.
+     */
+    constructor(maxKeys) {
+        this.maxKeys = maxKeys;
+    }
+    /**
+     * Increments an in-memory counter for the provided key.
+     *
+     * If the window is expired (or absent), a new window starts at `now`.
+     */
+    increment(key, windowMs, now) {
+        let entry = this.store.get(key);
+        if (!entry || now > entry.resetTime) {
+            entry = { count: 1, resetTime: now + windowMs };
+            this.store.set(key, entry);
+            this.trimIfNeeded(now);
+            return entry;
+        }
+        entry.count += 1;
+        return entry;
+    }
+    /**
+     * Removes expired entries from the internal map.
+     */
+    cleanup(now) {
+        for (const [key, value] of this.store.entries()) {
+            if (now > value.resetTime)
+                this.store.delete(key);
+        }
+    }
+    /**
+     * Enforces `maxKeys` and avoids unbounded memory growth.
+     */
+    trimIfNeeded(now) {
+        if (this.store.size <= this.maxKeys)
+            return;
+        this.cleanup(now);
+        while (this.store.size > this.maxKeys) {
+            const oldestKey = this.store.keys().next().value;
+            if (!oldestKey)
+                break;
+            this.store.delete(oldestKey);
+        }
+    }
+}
+/**
+ * Normalizes a candidate IP address into a canonical value.
  *
- * If none of these headers are available, the request `Host` header is used as
- * a fallback identifier. If that is also missing, `"anonymous"` is returned.
+ * Supported inputs:
+ * - Plain IPv4/IPv6
+ * - IPv4-mapped IPv6 (`::ffff:x.x.x.x`)
+ * - Bracketed IPv6 (`[2001:db8::1]`)
+ * - IPv4 with port (`x.x.x.x:port`)
  *
- * @param request - Incoming HTTP request.
- * @returns A string key used to track request counts per client.
+ * @param value - Raw address candidate.
+ * @returns Normalized IP, or `null` when the input is not a valid IP.
  */
-const defaultKeyGenerator = (request) => {
-    const forwardedFor = request.headers["x-forwarded-for"];
-    const realIp = request.headers["x-real-ip"];
-    const cfIp = request.headers["cf-connecting-ip"];
-    if (typeof forwardedFor === "string") {
-        return forwardedFor.split(",")[0]?.trim() ?? "anonymous";
+const normalizeAddress = (value) => {
+    if (!value)
+        return null;
+    const candidate = value.trim();
+    if (!candidate)
+        return null;
+    if ((0, node_net_1.isIP)(candidate))
+        return candidate;
+    if (candidate.startsWith("::ffff:")) {
+        const mapped = candidate.slice("::ffff:".length);
+        if ((0, node_net_1.isIP)(mapped))
+            return mapped;
     }
-    if (typeof realIp === "string")
-        return realIp;
-    if (typeof cfIp === "string")
+    const withoutBrackets = candidate.startsWith("[") && candidate.endsWith("]")
+        ? candidate.slice(1, -1)
+        : candidate;
+    if ((0, node_net_1.isIP)(withoutBrackets))
+        return withoutBrackets;
+    const ipv4WithPort = withoutBrackets.match(/^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/);
+    if (ipv4WithPort && (0, node_net_1.isIP)(ipv4WithPort[1]))
+        return ipv4WithPort[1];
+    return null;
+};
+/**
+ * Returns the first value when a header can be `string | string[]`.
+ */
+const pickFirstHeaderValue = (value) => Array.isArray(value) ? value[0] : value;
+/**
+ * Parses `x-forwarded-for` into an ordered list of candidates.
+ *
+ * @param value - Raw `x-forwarded-for` header value.
+ * @returns A trimmed list of forwarded addresses.
+ */
+const parseForwardedFor = (value) => {
+    const firstValue = pickFirstHeaderValue(value);
+    if (!firstValue)
+        return [];
+    return firstValue
+        .split(",")
+        .map(item => item.trim())
+        .filter(Boolean);
+};
+/**
+ * Builds the default key generator used by the rate limiter.
+ *
+ * Behavior:
+ * - `trustProxy: false` -> uses only socket `remoteAddress` (plus host fallback).
+ * - `trustProxy: true` -> allows proxy headers in this priority:
+ *   1) `cf-connecting-ip`
+ *   2) `x-real-ip`
+ *   3) first valid item in `x-forwarded-for`
+ *   4) socket `remoteAddress` fallback
+ *
+ * @param trustProxy - Whether proxy headers are trusted.
+ * @returns A key generator function for rate-limit identity.
+ */
+const buildDefaultKeyGenerator = (trustProxy) => (context) => {
+    const remoteAddress = normalizeAddress(context.remoteAddress);
+    if (!trustProxy)
+        return remoteAddress ?? context.headers.host ?? "anonymous";
+    const cfIp = normalizeAddress(pickFirstHeaderValue(context.headers["cf-connecting-ip"]));
+    if (cfIp)
         return cfIp;
-    return request.headers.host ?? "anonymous";
+    const realIp = normalizeAddress(pickFirstHeaderValue(context.headers["x-real-ip"]));
+    if (realIp)
+        return realIp;
+    const forwardedCandidates = parseForwardedFor(context.headers["x-forwarded-for"]);
+    for (const candidate of forwardedCandidates) {
+        const trustedIp = normalizeAddress(candidate);
+        if (trustedIp)
+            return trustedIp;
+    }
+    return remoteAddress ?? context.headers.host ?? "anonymous";
 };
 /**
  * Generates HTTP headers describing the current rate limit state.
@@ -112,46 +223,44 @@ const getRateLimitHeaders = (limit, current, resetTime, now, includeStandardHead
  * ]);
  */
 const rateLimit = (options = {}) => {
+    const trustProxy = options.trustProxy ?? false;
+    const memoryStoreMaxKeys = Math.max(options.maxKeys ?? 50_000, 1);
+    const store = options.store ?? new MemoryRateLimitStore(memoryStoreMaxKeys);
     const config = {
         windowMs: options.windowMs ?? 60_000,
         max: options.max ?? 5,
         message: options.message ?? "Too many requests, please try again later.",
         statusCode: options.statusCode ?? 429,
-        keyGenerator: options.keyGenerator ?? defaultKeyGenerator,
+        keyGenerator: options.keyGenerator ?? buildDefaultKeyGenerator(trustProxy),
         skip: options.skip,
         standardHeaders: options.standardHeaders ?? true,
         legacyHeaders: options.legacyHeaders ?? false,
         handler: options.handler,
     };
-    const store = new Map();
-    return async (request, next) => {
-        if (config.skip && (await config.skip(request))) {
-            return next(request);
+    const cleanupIntervalMs = Math.max(options.cleanupIntervalMs ?? config.windowMs, 1000);
+    let nextCleanupAt = Date.now() + cleanupIntervalMs;
+    return async (context, next) => {
+        if (config.skip && (await config.skip(context))) {
+            return next(context);
         }
         const now = Date.now();
-        const key = config.keyGenerator(request);
-        const current = store.get(key);
-        if (!current || now > current.resetTime) {
-            store.set(key, {
-                count: 1,
-                resetTime: now + config.windowMs,
-            });
-        }
-        else {
-            current.count += 1;
+        if (now >= nextCleanupAt && store.cleanup) {
+            await store.cleanup(now);
+            nextCleanupAt = now + cleanupIntervalMs;
         }
-        const entry = store.get(key);
+        const key = config.keyGenerator(context) || "anonymous";
+        const entry = await store.increment(key, config.windowMs, now);
         const headers = getRateLimitHeaders(config.max, entry.count, entry.resetTime, now, config.standardHeaders, config.legacyHeaders);
         if (entry.count > config.max) {
             const retryAfter = Math.max(Math.ceil((entry.resetTime - now) / 1000), 0);
             headers["Retry-After"] = String(retryAfter);
             const blockedResponse = config.handler
-                ? await config.handler(request)
+                ? await config.handler(context)
                 : http_1.Response.json(new httpExceptions_1.TooManyRequestsError(config.message).toJSON()).setStatusCode(config.statusCode);
             blockedResponse.setHeaders(headers);
             return blockedResponse;
         }
-        const response = await next(request);
+        const response = await next(context);
         response.setHeaders(headers);
         return response;
     };

package/dist/middlewares/session.js

@@ -68,17 +68,17 @@ const sessions = (StorageClass, options = {}) => {
             path: options.cookie?.path ?? "/",
         },
     };
-    return async (request, next) => {
-        const cookies = (0, cookies_1.parseCookies)(request.headers.cookie);
+    return async (context, next) => {
+        const cookies = (0, cookies_1.parseCookies)(context.headers.cookie);
         const sessionIdFromCookie = cookies[config.name];
         const storage = new StorageClass(config.cookie.maxAge);
         await loadSessionFromCookie(storage, sessionIdFromCookie);
         const session = new sessions_1.Session(storage);
-        request.setSession(session);
+        context.req.setSession(session);
         const sessionIdBefore = storage.id();
         if (!sessionIdBefore && config.saveUninitialized)
             await storage.start();
-        const response = await next(request);
+        const response = await next(context);
         const sessionIdAfter = storage.id();
         if (sessionIdAfter && config.rolling)
             await storage.touch();

package/dist/parsers/contentParserManager.d.ts

@@ -26,14 +26,16 @@ export declare class ContentParserManager {
      * @param req - Native incoming HTTP request
      * @returns Parsed body content or raw body
      */
-    parse(req: IncomingMessage): Promise<unknown>;
+    parse(req: IncomingMessage | globalThis.Request): Promise<unknown>;
     /**
      * Reads the raw request body.
      *
      * @param req - Native incoming HTTP request
      * @returns A promise that resolves to the full body buffer
      */
-    private readBody;
+    private readNodeBody;
+    private readWebBody;
+    private isWebRequest;
     /**
      * Finds a parser capable of handling the given content type.
      *

package/dist/parsers/contentParserManager.js

@@ -43,10 +43,15 @@ class ContentParserManager {
      * @returns Parsed body content or raw body
      */
     async parse(req) {
-        const body = await this.readBody(req);
+        const isWebRequest = this.isWebRequest(req);
+        const body = isWebRequest
+            ? await this.readWebBody(req)
+            : await this.readNodeBody(req);
         if (body.length <= 0)
             return {};
-        const contentType = req.headers["content-type"] || "text/plain";
+        const contentType = isWebRequest
+            ? req.headers.get("content-type") || "text/plain"
+            : req.headers["content-type"] || "text/plain";
         const parser = this.findParser(contentType);
         if (!parser)
             return Buffer.isBuffer(body) ? body : Buffer.from(body);
@@ -58,7 +63,7 @@ class ContentParserManager {
      * @param req - Native incoming HTTP request
      * @returns A promise that resolves to the full body buffer
      */
-    readBody(req) {
+    readNodeBody(req) {
         return new Promise((resolve, reject) => {
             const chunks = [];
             req.on("data", (chunk) => {
@@ -72,6 +77,20 @@ class ContentParserManager {
             });
         });
     }
+    async readWebBody(req) {
+        try {
+            const arrayBuffer = await req.arrayBuffer();
+            return Buffer.from(arrayBuffer);
+        }
+        catch {
+            throw new httpExceptions_1.UnprocessableContentError("Failed to read request body");
+        }
+    }
+    isWebRequest(req) {
+        const candidate = req;
+        return (typeof candidate.arrayBuffer === "function" &&
+            typeof candidate.headers?.get === "function");
+    }
     /**
      * Finds a parser capable of handling the given content type.
      *

package/dist/routing/routeResolveFunc.d.ts

@@ -0,0 +1,10 @@
+import type { HandlerOrMiddlewares, RouteHandler, Middleware } from "../types";
+/**
+ * Normalizes route registration args to support both signatures:
+ * - (path, action, middlewares?)
+ * - (path, middlewares, action)
+ */
+export declare const normalizeRouteArgs: (handlerOrMiddlewares: HandlerOrMiddlewares, handler?: RouteHandler) => {
+    action: RouteHandler;
+    middlewares: Middleware[];
+};

package/dist/routing/routeResolveFunc.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRouteArgs = void 0;
+/**
+ * Normalizes route registration args to support both signatures:
+ * - (path, action, middlewares?)
+ * - (path, middlewares, action)
+ */
+const normalizeRouteArgs = (handlerOrMiddlewares, handler) => {
+    if (Array.isArray(handlerOrMiddlewares)) {
+        return {
+            action: handler,
+            middlewares: handlerOrMiddlewares,
+        };
+    }
+    return {
+        action: handlerOrMiddlewares,
+        middlewares: Array.isArray(handler) ? handler : [],
+    };
+};
+exports.normalizeRouteArgs = normalizeRouteArgs;

package/dist/routing/router.d.ts

@@ -1,5 +1,5 @@
 import type { Middleware, RouteHandler } from "../types";
-import { Request, Response } from "../http";
+import { Context, Response } from "../http";
 import { Layer } from "./layer";
 import { RouterGroup } from "./routerGroup";
 /**
@@ -26,7 +26,7 @@ export declare class Router {
      * @returns The matching {@link Layer}
      * @throws {HttpNotFoundException} If no route matches
      */
-    resolveLayer(request: Request): Layer;
+    resolveLayer(context: Context): Layer;
     /**
      * Resolves and executes a request.
      *
@@ -39,14 +39,15 @@ export declare class Router {
      * @param request - Request to process
      * @returns The handler/middleware response (sync or async)
      */
-    resolve(request: Request): Promise<Response> | Response;
+    resolve(request: Context): Promise<Response> | Response;
+    private ensureContext;
     /**
      * Runs a middleware chain using the onion model.
      *
-     * Each middleware receives `(request, next)` and can run code
+     * Each middleware receives `(context, next)` and can run code
      * before/after calling `next()`.
      *
-     * @param request - Incoming request
+     * @param context - Incoming context
      * @param middlewares - Remaining middlewares to execute
      * @param target - Final route handler
      * @returns The response returned by a middleware or the final handler
@@ -87,13 +88,18 @@ export declare class Router {
      */
     middlewares(middlewares: Middleware[]): this;
     /** Registers a GET route. */
-    get(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    get(path: string, action: RouteHandler): Layer;
+    get(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a POST route. */
-    post(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    post(path: string, action: RouteHandler): Layer;
+    post(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a PATCH route. */
-    patch(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    patch(path: string, action: RouteHandler): Layer;
+    patch(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a PUT route. */
-    put(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    put(path: string, action: RouteHandler): Layer;
+    put(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a DELETE route. */
-    delete(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    delete(path: string, action: RouteHandler): Layer;
+    delete(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
 }

package/dist/routing/router.js

@@ -6,6 +6,7 @@ const httpExceptions_1 = require("../exceptions/httpExceptions");
 const layer_1 = require("./layer");
 const routerGroup_1 = require("./routerGroup");
 const buildFullPath_1 = require("./buildFullPath");
+const routeResolveFunc_1 = require("./routeResolveFunc");
 /**
  * Central routing system of the framework.
  *
@@ -34,10 +35,10 @@ class Router {
      * @returns The matching {@link Layer}
      * @throws {HttpNotFoundException} If no route matches
      */
-    resolveLayer(request) {
-        const routes = this.routes[request.method];
+    resolveLayer(context) {
+        const routes = this.routes[context.req.method];
         for (const route of routes) {
-            if (route.matches(request.url))
+            if (route.matches(context.req.url))
                 return route;
         }
         throw new httpExceptions_1.NotFoundError("Route not found");
@@ -55,38 +56,44 @@ class Router {
      * @returns The handler/middleware response (sync or async)
      */
     resolve(request) {
-        const executeLayer = (req) => {
-            const layer = this.resolveLayer(req);
+        const context = this.ensureContext(request);
+        const executeLayer = (ctx) => {
+            const layer = this.resolveLayer(ctx);
             if (layer.hasParameters()) {
-                req.setParams(layer.parseParameters(req.url));
+                ctx.req.setParams(layer.parseParameters(ctx.req.url));
             }
             const action = layer.getAction;
             const routeMiddlewares = layer.getMiddlewares;
             if (routeMiddlewares.length > 0) {
-                return this.runMiddlewares(req, routeMiddlewares, action);
+                return this.runMiddlewares(ctx, routeMiddlewares, action);
             }
-            return action(req);
+            return action(ctx);
         };
         if (this.globalMiddlewares.length > 0) {
-            return this.runMiddlewares(request, this.globalMiddlewares, executeLayer);
+            return this.runMiddlewares(context, this.globalMiddlewares, executeLayer);
         }
-        return executeLayer(request);
+        return executeLayer(context);
+    }
+    ensureContext(request) {
+        if (request instanceof http_1.Context)
+            return request;
+        return new http_1.Context(request);
     }
     /**
      * Runs a middleware chain using the onion model.
      *
-     * Each middleware receives `(request, next)` and can run code
+     * Each middleware receives `(context, next)` and can run code
      * before/after calling `next()`.
      *
-     * @param request - Incoming request
+     * @param context - Incoming context
      * @param middlewares - Remaining middlewares to execute
      * @param target - Final route handler
      * @returns The response returned by a middleware or the final handler
      */
-    runMiddlewares(request, middlewares, target) {
+    runMiddlewares(context, middlewares, target) {
         if (middlewares.length === 0)
-            return target(request);
-        return middlewares[0](request, request => this.runMiddlewares(request, middlewares.slice(1), target));
+            return target(context);
+        return middlewares[0](context, nextContext => this.runMiddlewares(this.ensureContext(nextContext), middlewares.slice(1), target));
     }
     /**
      * Registers a route and returns the created {@link Layer}.
@@ -138,24 +145,24 @@ class Router {
         this.globalMiddlewares.push(...middlewares);
         return this;
     }
-    /** Registers a GET route. */
-    get(path, action, middlewares) {
+    get(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.get, path, action, middlewares);
     }
-    /** Registers a POST route. */
-    post(path, action, middlewares) {
+    post(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.post, path, action, middlewares);
     }
-    /** Registers a PATCH route. */
-    patch(path, action, middlewares) {
+    patch(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.patch, path, action, middlewares);
     }
-    /** Registers a PUT route. */
-    put(path, action, middlewares) {
+    put(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.put, path, action, middlewares);
     }
-    /** Registers a DELETE route. */
-    delete(path, action, middlewares) {
+    delete(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.delete, path, action, middlewares);
     }
 }

package/dist/routing/routerGroup.d.ts

@@ -51,13 +51,18 @@ export declare class RouterGroup {
      */
     private addRoute;
     /** Registers a GET route within the group. */
-    get(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    get(path: string, action: RouteHandler): void;
+    get(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a POST route within the group. */
-    post(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    post(path: string, action: RouteHandler): void;
+    post(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a PUT route within the group. */
-    put(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    put(path: string, action: RouteHandler): void;
+    put(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a PATCH route within the group. */
-    patch(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    patch(path: string, action: RouteHandler): void;
+    patch(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a DELETE route within the group. */
-    delete(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    delete(path: string, action: RouteHandler): void;
+    delete(path: string, middlewares: Middleware[], action: RouteHandler): void;
 }