bazis 0.98.8 → 0.98.9

package/core/http/Errors/HttpError.ts

@@ -61,7 +61,11 @@ export class PayloadTooLargeError extends HttpError {
 }
 
 export class TooManyRequestsError extends HttpError {
-  constructor(readonly retryAfterSeconds: number) {
+  constructor(
+    readonly retryAfterSeconds: number,
+    /** Extra response headers, for example `RateLimit-*` from {@link rateLimit}. */
+    readonly headers?: Readonly<Record<string, string>>,
+  ) {
     super(429, "Too Many Requests");
   }
 }

package/core/http/Middleware/errorHandler.ts

@@ -112,6 +112,10 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         if (challenge !== undefined) {
           extra.push(["www-authenticate", challenge]);
         }
+        const headers = (error as { headers?: Readonly<Record<string, string>> }).headers;
+        if (headers !== undefined) {
+          extra.push(...Object.entries(headers));
+        }
         ctx.response = safeJsonResponse(
           error.status,
           error.details === undefined ? { error: error.message } : { error: error.message, details: error.details },

package/core/http/Middleware/rateLimit.ts

@@ -13,12 +13,19 @@ export interface RateLimitOptions {
    * bucket when unavailable). Plug your own: user id, API key, etc.
    */
   keyOf?: (ctx: HttpContext) => string;
-  /** Trust the first `X-Forwarded-For` hop. Off by default. */
-  trustProxy?: boolean;
-  /** Forwarded client-address header used when `trustProxy` is true. */
+  /**
+   * Read the client address from `X-Forwarded-For` behind trusted proxies.
+   * `true` — one proxy: the last address, the one the proxy saw; a number —
+   * that many proxies: the address that many hops from the end. Earlier
+   * addresses are written by the client and are never used. Off by default.
+   */
+  trustProxy?: boolean | number;
+  /** Forwarded client-address header used when `trustProxy` is set. */
   proxyHeader?: string;
   /** Hard cap for in-process buckets. New keys receive 429 when full. Default: 10,000. */
   maxBuckets?: number;
+  /** Add `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` to responses. Default: true. */
+  headers?: boolean;
 }
 
 interface Bucket {
@@ -30,7 +37,8 @@ interface Bucket {
  * Fixed-window in-memory rate limiter. Per-process state (no external
  * store) — suitable for a single binary; swap `keyOf` or wrap your own
  * middleware for distributed setups. Exceeding the limit throws 429 with
- * Retry-After. At capacity, new keys are rejected until a bucket expires;
+ * Retry-After; every response carries `RateLimit-Limit`, `RateLimit-Remaining`
+ * and `RateLimit-Reset` unless `headers: false`. At capacity, new keys are rejected until a bucket expires;
  * existing keys retain their quota and live buckets are never evicted.
  */
 export function rateLimit(options: RateLimitOptions): HttpMiddleware {
@@ -39,15 +47,22 @@ export function rateLimit(options: RateLimitOptions): HttpMiddleware {
   const maxBuckets = Math.floor(options.maxBuckets ?? 10_000);
   let nextExpiry = Number.POSITIVE_INFINITY;
   const proxyHeader = options.proxyHeader ?? "x-forwarded-for";
+  const trustedHops = options.trustProxy === true ? 1 : options.trustProxy || 0;
+  const withHeaders = options.headers !== false;
   const keyOf = options.keyOf ?? ((ctx: HttpContext) => {
-    if (options.trustProxy) {
-      const forwarded = ctx.header(proxyHeader)?.split(",", 1)[0]?.trim();
+    if (trustedHops > 0) {
+      const forwarded = forwardedClient(ctx.header(proxyHeader), trustedHops);
       if (forwarded) {
         return forwarded;
       }
     }
     return ctx.clientIp ?? "*";
   });
+  const limitHeaders = (remaining: number, resetSeconds: number): Record<string, string> => ({
+    "ratelimit-limit": String(options.max),
+    "ratelimit-remaining": String(remaining),
+    "ratelimit-reset": String(resetSeconds),
+  });
 
   return async (ctx, next) => {
     const now = Date.now();
@@ -65,20 +80,45 @@ export function rateLimit(options: RateLimitOptions): HttpMiddleware {
         nextExpiry = purgeExpired(buckets, now);
       }
       if (buckets.size >= maxBuckets) {
-        throw new TooManyRequestsError(Math.ceil((nextExpiry - now) / 1000));
+        const retryAfter = Math.ceil((nextExpiry - now) / 1000);
+        throw new TooManyRequestsError(retryAfter, withHeaders ? limitHeaders(0, retryAfter) : undefined);
       }
       bucket = { count: 0, resetAt: now + options.windowMs };
       buckets.set(key, bucket);
       nextExpiry = Math.min(nextExpiry, bucket.resetAt);
     }
+    const resetSeconds = Math.ceil((bucket.resetAt - now) / 1000);
     if (bucket.count >= options.max) {
-      throw new TooManyRequestsError(Math.ceil((bucket.resetAt - now) / 1000));
+      throw new TooManyRequestsError(resetSeconds, withHeaders ? limitHeaders(0, resetSeconds) : undefined);
     }
     bucket.count += 1;
     await next();
+    if (withHeaders && ctx.response) {
+      setIfAbsent(ctx.response, limitHeaders(options.max - bucket.count, resetSeconds));
+    }
   };
 }
 
+/**
+ * The client address `hops` entries from the end of `X-Forwarded-For`: each
+ * trusted proxy appends the address it saw, so entries before them are
+ * whatever the client sent.
+ */
+function forwardedClient(header: string | undefined, hops: number): string | undefined {
+  const addresses = header?.split(",").map((address) => address.trim()).filter((address) => address.length > 0) ?? [];
+  return addresses[Math.max(0, addresses.length - hops)];
+}
+
+function setIfAbsent(response: Response, headers: Record<string, string>): void {
+  try {
+    for (const [name, value] of Object.entries(headers)) {
+      if (!response.headers.has(name)) response.headers.set(name, value);
+    }
+  } catch {
+    // A raw Response may have immutable headers; the limit itself still applies.
+  }
+}
+
 function assertRateLimitOptions(options: RateLimitOptions): void {
   if (!Number.isFinite(options.windowMs) || options.windowMs <= 0) {
     throw new HttpSetupError("rateLimit windowMs must be a positive finite number.");
@@ -89,6 +129,9 @@ function assertRateLimitOptions(options: RateLimitOptions): void {
   if (options.maxBuckets !== undefined && (!Number.isSafeInteger(options.maxBuckets) || options.maxBuckets <= 0)) {
     throw new HttpSetupError("rateLimit maxBuckets must be a positive integer.");
   }
+  if (typeof options.trustProxy === "number" && (!Number.isSafeInteger(options.trustProxy) || options.trustProxy <= 0)) {
+    throw new HttpSetupError("rateLimit trustProxy must be true, false or the number of trusted proxies (a positive integer).");
+  }
 }
 
 function purgeExpired(buckets: Map<string, Bucket>, now: number): number {

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.8" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.9" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.8",
+  "version": "0.98.9",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",