@dunx/http 2.1.1 → 2.2.1

package/dist/index.js

@@ -340,13 +340,15 @@ import { AppError as AppError3, ConsoleLogger } from "@dunx/core";
 class HttpError extends AppError3 {
   status;
   name = "HttpError";
+  headers;
   constructor(status, message, options) {
     super(message, options);
     this.status = status;
+    this.headers = options?.headers;
   }
 }
 Object.defineProperty(HttpError, Symbol.for("dunx.deps"), {
-  value: () => [{ unresolved: "readonly status: number" }, { unresolved: "message: string" }, ErrorOptions]
+  value: () => [{ unresolved: "readonly status: number" }, { unresolved: "message: string" }, { unresolved: "options?: HttpErrorOptions" }]
 });
 
 class ValidationError extends HttpError {
@@ -369,10 +371,16 @@ var isErrorFilter = (handler) => typeof handler === "function" && typeof handler
 var toErrorMapper = (handler, resolve) => isErrorFilter(handler) ? (error, req) => resolve(handler).catch(error, req) : handler;
 var errorMapper = (logger) => (error) => {
   if (error instanceof ValidationError) {
-    return Response.json({ error: error.message, status: error.status, issues: error.issues }, { status: error.status });
+    return Response.json({ error: error.message, status: error.status, issues: error.issues }, {
+      status: error.status,
+      ...error.headers && { headers: error.headers }
+    });
   }
   if (error instanceof HttpError) {
-    return Response.json({ error: error.message, status: error.status }, { status: error.status });
+    return Response.json({ error: error.message, status: error.status }, {
+      status: error.status,
+      ...error.headers && { headers: error.headers }
+    });
   }
   logger.error("Unhandled error", error);
   return Response.json({
@@ -386,10 +394,10 @@ import {
   collectModules as collectModules2,
   AppError as AppError8,
   AppFactory,
-  Logger as Logger3,
+  Logger as Logger4,
   provide,
   readControllers as readControllers2,
-  RequestContext as RequestContext2
+  RequestContext as RequestContext3
 } from "@dunx/core";
 
 // src/ws/envelope.ts
@@ -409,6 +417,29 @@ var decode = (message) => {
   return typeof event === "string" ? { event, data } : undefined;
 };
 
+// src/ws/middleware.ts
+var composeSocket = (middleware, ctx) => middleware.reduceRight((next, current) => (frame, run) => current.handle(frame, ctx, () => next(frame, run)), (_frame, run) => run());
+var observe = (next, done) => {
+  let result;
+  try {
+    result = next();
+  } catch (error) {
+    done(error, undefined);
+    throw error;
+  }
+  if (result instanceof Promise) {
+    return result.then((value) => {
+      done(undefined, value);
+      return value;
+    }, (error) => {
+      done(error, undefined);
+      throw error;
+    });
+  }
+  done(undefined, result);
+  return result;
+};
+
 // src/ws/runtime.ts
 import { AppError as AppError4 } from "@dunx/core";
 var slotOf = (handler) => handler.kind === HandlerKind.MESSAGE && handler.event !== undefined ? `message ${JSON.stringify(handler.event)}` : handler.kind;
@@ -463,9 +494,14 @@ var someHandler = (gateways, pick) => {
 
 // src/ws/adapter.ts
 var RUNTIME = Symbol.for("dunx.ws.runtime");
+var UNCLAIMED = Symbol.for("dunx.ws.unclaimed");
 var defaultOnError = (error, socket) => {
   console.error(`[dunx/http] ${socket.data.path} handler failed:`, error);
 };
+var reportedByMiddleware = () => {
+  return;
+};
+var unreported = (middleware) => "Socket middleware is installed and none of it sets reportsErrors, so a " + "throwing gateway handler is reported nowhere: the console fallback is off " + "whenever middleware wraps the handler. Set reportsErrors on the one that " + "records a failure, or pass websocket.onError. Installed: " + `${middleware.map((entry) => entry.constructor.name).join(", ")}.`;
 var runtimeOf = (socket) => socket.data[RUNTIME];
 var isBinary = (value) => value instanceof ArrayBuffer || ArrayBuffer.isView(value);
 var replyRaw = (socket, value) => {
@@ -489,10 +525,67 @@ var settle = (result, socket, onError, then) => {
   if (then)
     then(result);
 };
-var buildWebSocket = (discovered, options = {}) => {
+var framing = (kind) => {
+  if (kind === HandlerKind.CLOSE) {
+    return (args) => ({
+      socket: args[0],
+      data: { code: args[1], reason: args[2] }
+    });
+  }
+  if (kind === HandlerKind.OPEN || kind === HandlerKind.DRAIN) {
+    return (args) => ({ socket: args[0], data: undefined });
+  }
+  return (args) => ({ socket: args[1], data: args[0] });
+};
+var NOTHING = () => {
+  return;
+};
+var through = (gateway, middleware, kind, event, invoke) => {
+  const ctx = {
+    gateway: gateway.name,
+    path: gateway.path,
+    kind,
+    event
+  };
+  const dispatch = composeSocket(middleware, ctx);
+  const frameOf = framing(kind);
+  const run = invoke ?? NOTHING;
+  return (...args) => dispatch(frameOf(args), () => run(...args));
+};
+var withMiddleware = (gateway, middleware) => {
+  const wrap = (kind, event, invoke) => through(gateway, middleware, kind, event, invoke);
+  const optional = (kind, invoke) => invoke === undefined ? undefined : wrap(kind, undefined, invoke);
+  return {
+    ...gateway,
+    open: wrap(HandlerKind.OPEN, undefined, gateway.open),
+    close: wrap(HandlerKind.CLOSE, undefined, gateway.close),
+    drain: optional(HandlerKind.DRAIN, gateway.drain),
+    ping: optional(HandlerKind.PING, gateway.ping),
+    pong: optional(HandlerKind.PONG, gateway.pong),
+    raw: optional(HandlerKind.MESSAGE, gateway.raw),
+    events: new Map([...gateway.events].map(([event, invoke]) => [
+      event,
+      wrap(HandlerKind.MESSAGE, event, invoke)
+    ]))
+  };
+};
+var unclaimedDispatch = (gateway, middleware) => (frame, event) => composeSocket(middleware, {
+  gateway: gateway.name,
+  path: gateway.path,
+  kind: HandlerKind.MESSAGE,
+  event
+})(frame, () => {
+  return;
+});
+var buildWebSocket = (discovered, options = {}, middleware = []) => {
   const byPath = buildGateways(discovered);
-  const gateways = [...byPath.values()];
-  const onError = options.onError ?? defaultOnError;
+  const wrapped = middleware.length === 0 ? byPath : new Map([...byPath].map(([path, gateway]) => [
+    path,
+    withMiddleware(gateway, middleware)
+  ]));
+  const gateways = [...wrapped.values()];
+  const onError = options.onError ?? (middleware.length === 0 ? defaultOnError : reportedByMiddleware);
+  const reports = options.onError !== undefined || middleware.some((entry) => entry.reportsErrors === true);
   const { onError: _onError, ...socketOptions } = options;
   const run = (invoke, args, ws, then) => {
     try {
@@ -505,6 +598,7 @@ var buildWebSocket = (discovered, options = {}) => {
     ...socketOptions,
     message(ws, message) {
       const gateway = runtimeOf(ws);
+      let event;
       if (gateway.events.size > 0) {
         const envelope = decode(message);
         const handler = envelope && gateway.events.get(envelope.event);
@@ -515,9 +609,19 @@ var buildWebSocket = (discovered, options = {}) => {
           });
           return;
         }
+        event = envelope?.event;
       }
       if (gateway.raw) {
         run(gateway.raw, [message, ws], ws, (value) => replyRaw(ws, value));
+        return;
+      }
+      const unclaimed2 = ws.data[UNCLAIMED];
+      if (!unclaimed2)
+        return;
+      try {
+        settle(unclaimed2({ socket: ws, data: message }, event), ws, onError, undefined);
+      } catch (error) {
+        onError(error, ws);
       }
     },
     ...someHandler(gateways, (g) => g.open) && {
@@ -556,8 +660,19 @@ var buildWebSocket = (discovered, options = {}) => {
       }
     }
   };
+  const unclaimed = new Map(middleware.length === 0 ? [] : gateways.map((gateway) => [
+    gateway,
+    unclaimedDispatch(gateway, middleware)
+  ]));
   const accept = (req, server, gateway, context) => {
-    const data = { path: gateway.path, context, [RUNTIME]: gateway };
+    const fallback = unclaimed.get(gateway);
+    const data = {
+      path: gateway.path,
+      context,
+      id: crypto.randomUUID(),
+      [RUNTIME]: gateway,
+      ...fallback === undefined ? {} : { [UNCLAIMED]: fallback }
+    };
     return server.upgrade(req, { data }) ? undefined : new Response("Expected a WebSocket upgrade", { status: 426 });
   };
   const upgradeHandler = (gateway) => (req, server) => {
@@ -573,6 +688,7 @@ var buildWebSocket = (discovered, options = {}) => {
     websocket,
     routes: new Map(gateways.map((gateway) => [gateway.path, upgradeHandler(gateway)])),
     paths: [...byPath.keys()],
+    warnings: middleware.length > 0 && !reports ? [unreported(middleware)] : [],
     gateways: gateways.map((gateway) => ({
       name: gateway.name,
       path: gateway.path,
@@ -581,6 +697,105 @@ var buildWebSocket = (discovered, options = {}) => {
   };
 };
 
+// src/ws/logging.ts
+import { Logger, LogLevel, RequestContext } from "@dunx/core";
+var LIFECYCLE_LABEL = {
+  [HandlerKind.OPEN]: "connect",
+  [HandlerKind.CLOSE]: "disconnect"
+};
+var elapsedMs = (started) => Math.round((Bun.nanoseconds() - started) / 1e6);
+
+class SocketLoggingMiddleware {
+  logger;
+  context;
+  reportsErrors = true;
+  #level;
+  #errorLevel;
+  #events;
+  #lifecycle;
+  #payload;
+  #limit;
+  #correlate;
+  constructor(logger, context, options = {}) {
+    this.logger = logger;
+    this.context = context;
+    this.#level = options.level ?? LogLevel.DEBUG;
+    this.#errorLevel = options.errorLevel ?? LogLevel.ERROR;
+    this.#events = options.events ?? {};
+    this.#lifecycle = options.lifecycle ?? this.#level;
+    this.#payload = options.payload ?? false;
+    this.#limit = options.maxPayloadLength ?? 512;
+    this.#correlate = options.correlate ?? true;
+  }
+  #levelFor(ctx) {
+    if (ctx.kind !== HandlerKind.MESSAGE)
+      return this.#lifecycle;
+    if (ctx.event === undefined)
+      return this.#level;
+    return this.#events[ctx.event] ?? this.#level;
+  }
+  handle(frame, ctx, next) {
+    const level = this.#levelFor(ctx);
+    if (level === false)
+      return next();
+    const label = ctx.event ?? LIFECYCLE_LABEL[ctx.kind] ?? ctx.kind;
+    const connectionId = frame.socket.data.id;
+    const started = Bun.nanoseconds();
+    const write2 = (error, value) => {
+      const entry = {
+        gateway: ctx.gateway,
+        path: ctx.path,
+        event: label,
+        connectionId,
+        elapsedMs: elapsedMs(started),
+        ...this.#payload ? { payload: this.#brief(frame.data) } : {},
+        ...error === undefined ? { replied: value !== undefined } : { err: error }
+      };
+      const line = `${ctx.path} ${label}`;
+      this.#emit(error === undefined ? level : this.#errorLevel, line, entry);
+    };
+    if (!this.#correlate)
+      return observe(next, write2);
+    return this.context.runWithContext({ connectionId, event: label, flow: "ws", context: ctx.gateway }, () => observe(next, write2));
+  }
+  #emit(level, line, entry) {
+    switch (level) {
+      case LogLevel.VERBOSE:
+        this.logger.verbose(line, entry);
+        return;
+      case LogLevel.DEBUG:
+        this.logger.debug(line, entry);
+        return;
+      case LogLevel.INFO:
+        this.logger.info(line, entry);
+        return;
+      case LogLevel.WARN:
+        this.logger.warn(line, entry);
+        return;
+      case LogLevel.ERROR:
+        this.logger.error(line, entry);
+        return;
+      default:
+        this.logger.fatal(line, entry);
+    }
+  }
+  #brief(data) {
+    if (data === undefined || this.#limit === 0)
+      return;
+    if (typeof data === "string") {
+      return data.length > this.#limit ? `[${data.length} chars]` : data;
+    }
+    if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+      return `[${data.byteLength} bytes]`;
+    }
+    const text = JSON.stringify(data) ?? "";
+    return text.length > this.#limit ? `[${text.length} chars]` : data;
+  }
+}
+Object.defineProperty(SocketLoggingMiddleware, Symbol.for("dunx.deps"), {
+  value: () => [Logger, RequestContext, { unresolved: "options: SocketLoggingOptions = {}" }]
+});
+
 // src/ws/pubsub.ts
 import { AppError as AppError5 } from "@dunx/core";
 
@@ -742,19 +957,40 @@ class PubSub {
 // src/server/application.ts
 import {
   AppError as AppError7,
-  Logger as Logger2,
+  Logger as Logger3,
   runtimeInfo,
-  ShutdownHooks
+  ShutdownHooks,
+  teardownError,
+  teardownFailures as toFailures
 } from "@dunx/core";
 
 // src/server/request-logging.ts
 import {
-  Logger,
-  RequestContext
+  Logger as Logger2,
+  RequestContext as RequestContext2
 } from "@dunx/core";
+
+// src/server/request-id.ts
 var REQUEST_ID_HEADER = "x-request-id";
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var traceId = (inbound) => inbound !== null && inbound.length === 36 && UUID.test(inbound) ? inbound : crypto.randomUUID();
+var ID = Symbol.for("dunx.http.requestId");
+
+class RequestIds {
+  static assign(req) {
+    const id = traceId(req.headers.get(REQUEST_ID_HEADER));
+    req[ID] = id;
+    return id;
+  }
+  static stamp(response, req) {
+    const id = req[ID];
+    if (id !== undefined)
+      response.headers.set(REQUEST_ID_HEADER, id);
+    return response;
+  }
+}
+
+// src/server/request-logging.ts
 var parse = (text, limit) => {
   if (limit === 0)
     return;
@@ -768,7 +1004,7 @@ var parse = (text, limit) => {
     return text;
   }
 };
-var elapsedMs = (started) => Math.round((Bun.nanoseconds() - started) / 1e6);
+var elapsedMs2 = (started) => Math.round((Bun.nanoseconds() - started) / 1e6);
 
 class RequestLoggingMiddleware {
   logger;
@@ -807,7 +1043,7 @@ class RequestLoggingMiddleware {
       return this.#correlateIgnored ? this.#correlated(req, ctx, path, next) : next();
     }
     const started = Bun.nanoseconds();
-    const requestId = traceId(req.headers.get(REQUEST_ID_HEADER));
+    const requestId = RequestIds.assign(req);
     const scope = {
       requestId,
       method: ctx.method,
@@ -835,7 +1071,7 @@ class RequestLoggingMiddleware {
     });
   }
   #correlated(req, ctx, path, next) {
-    const requestId = traceId(req.headers.get(REQUEST_ID_HEADER));
+    const requestId = RequestIds.assign(req);
     const stamp = (response) => {
       response.headers.set(REQUEST_ID_HEADER, requestId);
       return response;
@@ -870,7 +1106,7 @@ class RequestLoggingMiddleware {
       request,
       err: error,
       statusCode: status,
-      elapsedMs: elapsedMs(started)
+      elapsedMs: elapsedMs2(started)
     };
     const line = `${req.method} ${path} ${status}`;
     if (status < HttpStatusCode.INTERNAL_SERVER_ERROR) {
@@ -886,7 +1122,7 @@ class RequestLoggingMiddleware {
         ...scope,
         request,
         statusCode: response.status,
-        elapsedMs: elapsedMs(started)
+        elapsedMs: elapsedMs2(started)
       });
       response.headers.set(REQUEST_ID_HEADER, requestId);
       return response;
@@ -897,7 +1133,7 @@ class RequestLoggingMiddleware {
         request,
         statusCode: response.status,
         ...value === undefined ? {} : { responseBody: value },
-        elapsedMs: elapsedMs(started)
+        elapsedMs: elapsedMs2(started)
       });
       response.headers.set(REQUEST_ID_HEADER, requestId);
       return response;
@@ -923,7 +1159,7 @@ class RequestLoggingMiddleware {
   }
 }
 Object.defineProperty(RequestLoggingMiddleware, Symbol.for("dunx.deps"), {
-  value: () => [Logger, RequestContext, { unresolved: "options: RequestLoggingOptions = {}" }]
+  value: () => [Logger2, RequestContext2, { unresolved: "options: RequestLoggingOptions = {}" }]
 });
 
 // src/server/routes.ts
@@ -1089,7 +1325,7 @@ var buildFallback = (middleware = [], onError = defaultErrorMapper, cors, notFou
     try {
       return await compose(middleware, unmatchedContext(req, notFound === "public"), miss)(req);
     } catch (error) {
-      return onError(error, req);
+      return RequestIds.stamp(onError(error, req), req);
     }
   };
   return cors ? withCors(cors, run) : run;
@@ -1146,7 +1382,7 @@ var buildRoutes = (discovered, middleware = [], onError = defaultErrorMapper, co
       try {
         return await chained(req);
       } catch (error) {
-        return onError(error, req);
+        return RequestIds.stamp(onError(error, req), req);
       }
     };
     const byMethod = routes[route.path] ??= {};
@@ -1197,7 +1433,7 @@ class HttpApplication {
       ...options.requestLogging === false ? [] : [RequestLoggingMiddleware],
       ...options.middleware ?? []
     ];
-    this.#onError = options.onError === undefined ? errorMapper(app.get(Logger2)) : toErrorMapper(options.onError, (token) => app.get(token, root));
+    this.#onError = options.onError === undefined ? errorMapper(app.get(Logger3)) : toErrorMapper(options.onError, (token) => app.get(token, root));
     this.#port = options.port ?? 3000;
     this.#websocket = websocket;
     this.#relay = options.relay;
@@ -1263,7 +1499,7 @@ class HttpApplication {
     const pubsub = this.#app.get(PubSub);
     pubsub.attach(this.#server);
     if (this.#relay) {
-      const logger = this.#app.get(Logger2);
+      const logger = this.#app.get(Logger3);
       await pubsub.relayThrough(this.#relay, {
         ...this.#relayChannel !== undefined && {
           channel: this.#relayChannel
@@ -1287,7 +1523,7 @@ class HttpApplication {
       `${routes.length} route(s)`,
       ...gateways.length === 0 ? [] : [`${gateways.length} gateway(s)`]
     ].join(" and ");
-    this.#app.get(Logger2).info(`Serving ${subject}`, {
+    this.#app.get(Logger3).info(`Serving ${subject}`, {
       ...runtimeInfo(),
       routes: routes.map((route) => `${route.method} ${route.path}`),
       ...gateways.length === 0 ? {} : {
@@ -1304,12 +1540,25 @@ class HttpApplication {
   }
   async shutdown() {
     this.#shuttingDown ??= (async () => {
-      await this.#app.drain();
-      await this.#server?.stop(this.#websocket !== undefined);
+      const failures = [];
+      const step = async (run) => {
+        try {
+          await run();
+        } catch (error) {
+          failures.push(...toFailures(error));
+        }
+      };
+      await step(() => this.#app.drain());
+      await step(async () => this.#server?.stop(this.#websocket !== undefined));
       this.#server = undefined;
-      await this.#app.get(PubSub).close();
-      await this.#app.shutdown();
-      this.#resolveClosed?.();
+      await step(() => this.#app.get(PubSub).close());
+      try {
+        await step(() => this.#app.shutdown());
+      } finally {
+        this.#resolveClosed?.();
+      }
+      if (failures.length > 0)
+        throw teardownError(failures);
     })();
     return this.#shuttingDown;
   }
@@ -1343,10 +1592,18 @@ class HttpFactory {
   static async create(root, options = {}) {
     const logging = provide(RequestLoggingMiddleware, {
       useFactory: (logger, context) => new RequestLoggingMiddleware(logger, context, typeof options.requestLogging === "object" ? options.requestLogging : {}),
-      inject: [Logger3, RequestContext2]
+      inject: [Logger4, RequestContext3]
+    });
+    const socketLogging = provide(SocketLoggingMiddleware, {
+      useFactory: (logger, context) => new SocketLoggingMiddleware(logger, context, typeof options.socketLogging === "object" ? options.socketLogging : {}),
+      inject: [Logger4, RequestContext3]
     });
     const services = [PubSub, ClientAddress];
-    const providers = options.requestLogging === false ? services : [...services, logging];
+    const providers = [
+      ...services,
+      ...options.requestLogging === false ? [] : [logging],
+      ...options.socketLogging === false ? [] : [socketLogging]
+    ];
     const scope = {
       module: HttpModule,
       global: true,
@@ -1375,9 +1632,17 @@ class HttpFactory {
     }
     assertNoCollisions(discovered);
     const gateways = discoverGateways(modules, (token) => app.get(token));
-    const websocket = gateways.length > 0 ? buildWebSocket(gateways, options.websocket) : undefined;
+    const websocket = gateways.length > 0 ? buildWebSocket(gateways, options.websocket, HttpFactory.#socketMiddleware(app, root, options)) : undefined;
+    for (const warning of websocket?.warnings ?? []) {
+      app.get(Logger4).warn(warning);
+    }
     return new HttpApplication(app, discovered, options, root, websocket);
   }
+  static #socketMiddleware(app, root, options) {
+    const declared = options.socketMiddleware ?? [];
+    const entries = options.socketLogging === false ? declared : [SocketLoggingMiddleware, ...declared];
+    return entries.map((entry) => app.get(entry, root));
+  }
 }
 // src/static/files.ts
 import { join, normalize, resolve } from "path";
@@ -1502,6 +1767,242 @@ StaticModule = __decorateElement(_init, 0, "StaticModule", _dec, StaticModule);
 __runInitializers(_init, 1, StaticModule);
 __decoratorMetadata(_init, StaticModule);
 let _StaticModule = StaticModule;
+// src/throttle/decorators.ts
+var THROTTLE = metaKey("throttle");
+var SKIP_THROTTLE = metaKey("skip-throttle");
+var Throttle = (limit) => meta(THROTTLE, limit);
+var SkipThrottle = () => meta(SKIP_THROTTLE, true);
+// src/throttle/guard.ts
+import { Logger as Logger5 } from "@dunx/core";
+
+// src/throttle/options.ts
+import { AppError as AppError9 } from "@dunx/core";
+
+class ThrottleOptions {
+  limit;
+  windowSeconds;
+  prefix;
+  headers;
+  subject;
+  store;
+  constructor(init) {
+    if (init.prefix.trim() === "") {
+      throw new AppError9("ThrottleModule needs a prefix naming this application, and it has no " + "default: two apps sharing one Redis with one throttle namespace each " + "spend the other's budget. Pass something like { prefix: 'orders-api' }.");
+    }
+    if (!Number.isInteger(init.limit) || init.limit < 1) {
+      throw new AppError9(`ThrottleModule needs a limit of at least 1; got ${init.limit}.`);
+    }
+    if (!Number.isInteger(init.windowSeconds) || init.windowSeconds < 1) {
+      throw new AppError9("ThrottleModule needs a windowSeconds of at least 1; got " + `${init.windowSeconds}.`);
+    }
+    this.limit = init.limit;
+    this.windowSeconds = init.windowSeconds;
+    this.prefix = init.prefix;
+    this.headers = init.headers ?? true;
+    this.subject = init.subject;
+    this.store = init.store;
+  }
+}
+Object.defineProperty(ThrottleOptions, Symbol.for("dunx.deps"), {
+  value: () => [{ unresolved: "init: ThrottleOptionsInit" }]
+});
+
+// src/throttle/store.ts
+import { AppError as AppError10 } from "@dunx/core";
+
+class ThrottleStore {
+  constructor() {
+    if (new.target === ThrottleStore) {
+      throw new AppError10("ThrottleStore is a contract, not an implementation. Bind one with " + "ThrottleModule.forRoot({ store: new RedisThrottleStore(redis) }), or " + "leave it out for the in-process MemoryThrottleStore.");
+    }
+  }
+}
+
+class RedisThrottleStore extends ThrottleStore {
+  redis;
+  constructor(redis) {
+    super();
+    this.redis = redis;
+  }
+  async hit(key, windowSeconds) {
+    const used = await this.redis.incr(key);
+    if (used === 1)
+      await this.redis.expire(key, windowSeconds);
+    return used;
+  }
+  async ttl(key) {
+    const left = await this.redis.ttl(key);
+    return left > 0 ? left : undefined;
+  }
+}
+Object.defineProperty(RedisThrottleStore, Symbol.for("dunx.deps"), {
+  value: () => [{ unresolved: "private readonly redis: ThrottleRedis" }]
+});
+
+class MemoryThrottleStore extends ThrottleStore {
+  #windows = new Map;
+  #maxKeys;
+  constructor(maxKeys = 1e4) {
+    super();
+    this.#maxKeys = maxKeys;
+  }
+  hit(key, windowSeconds) {
+    const now = Date.now();
+    const existing = this.#windows.get(key);
+    if (existing !== undefined && existing.expiresAt > now) {
+      existing.count += 1;
+      return Promise.resolve(existing.count);
+    }
+    if (this.#windows.size >= this.#maxKeys)
+      this.#sweep(now);
+    this.#windows.set(key, { count: 1, expiresAt: now + windowSeconds * 1000 });
+    return Promise.resolve(1);
+  }
+  ttl(key) {
+    const window = this.#windows.get(key);
+    if (window === undefined)
+      return Promise.resolve(undefined);
+    const left = Math.ceil((window.expiresAt - Date.now()) / 1000);
+    return Promise.resolve(left > 0 ? left : undefined);
+  }
+  #sweep(now) {
+    for (const [key, window] of this.#windows) {
+      if (window.expiresAt <= now)
+        this.#windows.delete(key);
+    }
+    if (this.#windows.size >= this.#maxKeys)
+      this.#windows.clear();
+  }
+}
+Object.defineProperty(MemoryThrottleStore, Symbol.for("dunx.deps"), {
+  value: () => [{ unresolved: "maxKeys = 10_000" }]
+});
+
+// src/throttle/guard.ts
+class ThrottleGuard {
+  options;
+  store;
+  address;
+  logger;
+  #warned = false;
+  constructor(options, store, address, logger) {
+    this.options = options;
+    this.store = store;
+    this.address = address;
+    this.logger = logger;
+  }
+  async handle(req, ctx, next) {
+    if (ctx.get(UNMATCHED) === true)
+      return next();
+    if (ctx.get(SKIP_THROTTLE) === true)
+      return next();
+    const limit = ctx.get(THROTTLE) ?? this.options;
+    const key = this.#key(req, ctx);
+    const used = await this.#hit(key, limit.windowSeconds);
+    if (used === undefined)
+      return next();
+    if (used > limit.limit) {
+      const after = await this.#ttl(key) ?? limit.windowSeconds;
+      throw new HttpError(HttpStatusCode.TOO_MANY_REQUESTS, `Rate limit exceeded: ${limit.limit} requests per ` + `${limit.windowSeconds}s`, this.options.headers ? {
+        headers: {
+          "retry-after": String(after),
+          "ratelimit-limit": String(limit.limit),
+          "ratelimit-remaining": "0",
+          "ratelimit-reset": String(after)
+        }
+      } : undefined);
+    }
+    const response = await next();
+    if (this.options.headers) {
+      response.headers.set("ratelimit-limit", String(limit.limit));
+      response.headers.set("ratelimit-remaining", String(Math.max(0, limit.limit - used)));
+    }
+    return response;
+  }
+  #key(req, ctx) {
+    const subject = (this.options.subject ?? ((request) => this.address.of(request)))(req, ctx) ?? "anonymous";
+    return `${this.options.prefix}:throttle:${ctx.controller}:${ctx.handler}:${subject}`;
+  }
+  async#hit(key, windowSeconds) {
+    try {
+      return await this.store.hit(key, windowSeconds);
+    } catch (error) {
+      this.#degraded(error);
+      return;
+    }
+  }
+  async#ttl(key) {
+    try {
+      return await this.store.ttl(key);
+    } catch (error) {
+      this.#degraded(error);
+      return;
+    }
+  }
+  #degraded(error) {
+    if (this.#warned)
+      return;
+    this.#warned = true;
+    this.logger.warn("The rate limiter is unreachable, so requests are not being counted.", { reason: error.message });
+  }
+}
+Object.defineProperty(ThrottleGuard, Symbol.for("dunx.deps"), {
+  value: () => [ThrottleOptions, ThrottleStore, ClientAddress, Logger5]
+});
+// src/throttle/module.ts
+import {
+  Logger as Logger6,
+  Module as Module2,
+  provide as provide3
+} from "@dunx/core";
+var EXPORTS = [ThrottleOptions, ThrottleStore, ThrottleGuard];
+var guard = () => provide3(ThrottleGuard, {
+  useFactory: (options, store, address, logger) => new ThrottleGuard(options, store, address, logger),
+  inject: [ThrottleOptions, ThrottleStore, ClientAddress, Logger6]
+});
+var store = () => provide3(ThrottleStore, {
+  useFactory: (options) => options.store ?? new MemoryThrottleStore,
+  inject: [ThrottleOptions]
+});
+var _dec = [
+  Module2({})
+];
+var _init = __decoratorStart(undefined);
+
+class ThrottleModule {
+  static forRoot(init) {
+    return {
+      module: ThrottleModule,
+      global: true,
+      exports: EXPORTS,
+      providers: [
+        provide3(ThrottleOptions, { useValue: new ThrottleOptions(init) }),
+        store(),
+        guard()
+      ]
+    };
+  }
+  static forRootAsync(config) {
+    return {
+      module: ThrottleModule,
+      global: true,
+      ...config.imports && { imports: config.imports },
+      exports: EXPORTS,
+      providers: [
+        provide3(ThrottleOptions, {
+          useFactory: async (...deps) => new ThrottleOptions(await config.useFactory(...deps)),
+          inject: config.inject ?? []
+        }),
+        store(),
+        guard()
+      ]
+    };
+  }
+}
+ThrottleModule = __decorateElement(_init, 0, "ThrottleModule", _dec, ThrottleModule);
+__runInitializers(_init, 1, ThrottleModule);
+__decoratorMetadata(_init, ThrottleModule);
+let _ThrottleModule = ThrottleModule;
 // src/ws/decorators.ts
 var Gateway = (path = "/") => (target) => {
   markGateway(target, path);
@@ -1522,7 +2023,7 @@ var OnMessage = (event) => (value) => {
   return value;
 };
 // src/ws/redis-relay.ts
-import { AppError as AppError9 } from "@dunx/core";
+import { AppError as AppError11 } from "@dunx/core";
 var PROTOCOLS = [
   "redis:",
   "rediss:",
@@ -1538,10 +2039,10 @@ var assertUrl = (url) => {
   try {
     parsed = new URL(url);
   } catch {
-    throw new AppError9(`${JSON.stringify(url)} is not a valid URL for the websocket relay. ` + "Expected something like redis://localhost:6379.");
+    throw new AppError11(`${JSON.stringify(url)} is not a valid URL for the websocket relay. ` + "Expected something like redis://localhost:6379.");
   }
   if (!PROTOCOLS.includes(parsed.protocol)) {
-    throw new AppError9(`Unsupported protocol ${JSON.stringify(parsed.protocol)} in ` + `${JSON.stringify(url)}. Expected one of ${PROTOCOLS.join(", ")}.`);
+    throw new AppError11(`Unsupported protocol ${JSON.stringify(parsed.protocol)} in ` + `${JSON.stringify(url)}. Expected one of ${PROTOCOLS.join(", ")}.`);
   }
   return url;
 };
@@ -1677,7 +2178,7 @@ Object.defineProperty(HealthOptions, Symbol.for("dunx.deps"), {
 class HealthRegistry {
   options;
   readiness_;
-  #startedAt = Date.now();
+  #startedAt = performance.now();
   constructor(options, readiness_) {
     this.options = options;
     this.readiness_ = readiness_;
@@ -1697,7 +2198,7 @@ class HealthRegistry {
     return {
       status: worst(checks),
       draining: this.readiness_.draining,
-      uptimeMs: Date.now() - this.#startedAt,
+      uptimeMs: Math.round(performance.now() - this.#startedAt),
       checks
     };
   }
@@ -1867,8 +2368,8 @@ Object.defineProperty(DiskIndicator, Symbol.for("dunx.deps"), {
 });
 // src/health/module.ts
 import {
-  Module as Module2,
-  provide as provide3
+  Module as Module3,
+  provide as provide4
 } from "@dunx/core";
 
 // src/health/readiness.ts
@@ -1915,22 +2416,22 @@ Object.defineProperty(Readiness, Symbol.for("dunx.deps"), {
 // src/health/module.ts
 var wiring = (options) => [
   ...options,
-  provide3(ReadinessOptions, {
+  provide4(ReadinessOptions, {
     useFactory: (opts) => new ReadinessOptions({ drainDelayMs: opts.drainDelayMs }),
     inject: [HealthOptions]
   }),
-  provide3(Readiness, {
+  provide4(Readiness, {
     useFactory: (opts) => new Readiness(opts),
     inject: [ReadinessOptions]
   }),
-  provide3(HealthRegistry, {
+  provide4(HealthRegistry, {
     useFactory: (opts, readiness) => new HealthRegistry(opts, readiness),
     inject: [HealthOptions, Readiness]
   })
 ];
 var surface = [HealthOptions, HealthRegistry, Readiness];
 var _dec = [
-  Module2({})
+  Module3({})
 ];
 var _init = __decoratorStart(undefined);
 
@@ -1941,7 +2442,7 @@ class HealthModule {
       module: HealthModule,
       ...options.routes ? { controllers: [HealthController] } : {},
       exports: surface,
-      providers: wiring([provide3(HealthOptions, { useValue: options })])
+      providers: wiring([provide4(HealthOptions, { useValue: options })])
     };
   }
   static forRootAsync(config) {
@@ -1951,7 +2452,7 @@ class HealthModule {
       ...config.routes ?? true ? { controllers: [HealthController] } : {},
       exports: surface,
       providers: wiring([
-        provide3(HealthOptions, {
+        provide4(HealthOptions, {
           useFactory: async (...deps) => new HealthOptions(await config.useFactory(...deps)),
           inject: config.inject ?? []
         })
@@ -1969,6 +2470,7 @@ export {
   toErrorMapper,
   routesOf,
   preflight,
+  observe,
   normalizePrefix,
   normalizePath,
   metaOf,
@@ -1990,6 +2492,7 @@ export {
   defaultErrorMapper,
   decodeRelay,
   decode,
+  composeSocket,
   compose,
   buildWebSocket,
   buildRuntime,
@@ -2001,11 +2504,21 @@ export {
   ValidationError,
   UseGuards,
   UNMATCHED,
+  ThrottleStore,
+  ThrottleOptions,
+  ThrottleModule,
+  ThrottleGuard,
+  Throttle,
+  THROTTLE,
   StaticOptions,
   StaticModule,
   StaticFiles,
+  SocketLoggingMiddleware,
+  SkipThrottle,
+  SKIP_THROTTLE,
   Roles,
   RequestLoggingMiddleware,
+  RedisThrottleStore,
   RedisRelay,
   RedisIndicator,
   ReadinessOptions,
@@ -2027,6 +2540,7 @@ export {
   OnMessage,
   OnDrain,
   OnClose,
+  MemoryThrottleStore,
   MemoryOptions,
   MemoryIndicator,
   HttpStatusCode,
@@ -2052,5 +2566,5 @@ export {
   ApiHidden
 };
 
-//# debugId=0B19A1EE11424A5864756E2164756E21
+//# debugId=C7EBB73765DCC48764756E2164756E21
 //# sourceMappingURL=index.js.map