cabloy 5.1.239 → 5.1.240

package/.cabloy-version

@@ -1 +1 @@
-5.1.239
+5.1.240

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 5.1.240
+
+### Improvements
+
+- Enhance rate limiting.
+- Update hot module replacement (HMR) handling.
+
 ## 5.1.239
 
 ### Improvements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.239",
+  "version": "5.1.240",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/backend/rate-limit-guide.md

@@ -2,11 +2,56 @@
 
 ## Overview
 
-`a-ratelimit` limits matched Vona HTTP API actions across all application workers. It runs as the global `a-ratelimit:rateLimit` interceptor after Passport has resolved an authenticated or anonymous subject, and before request-body parsing, pipes, local middleware, and controller code. See [Controller AOP Guide](/backend/controller-aop-guide) for the general request-stage diagram and the distinction between a local aspect and a route override of an existing global onion.
+`a-ratelimit` provides two independent admission controls:
 
-It protects controller APIs. Put volumetric, static-file, unknown-route, and network-edge protection in the reverse proxy, WAF, or gateway.
+- The identity interceptor, `a-ratelimit:rateLimit`, limits matched Vona HTTP API actions across all application workers. It runs after Passport has resolved an authenticated or anonymous subject, and before request-body parsing, pipes, local middleware, and controller code.
+- The aggregate system middleware, `a-ratelimit:aggregate`, limits incoming HTTP requests across the application before the application/instance readiness middleware and routing, but after the HTTP executor's initial instance lookup. It is disabled by default and requires explicit configuration.
 
-## Enablement and rollout
+The identity interceptor protects controller APIs only; its route matching and instance isolation do not describe the aggregate middleware. Keep volumetric and network-edge protection in the reverse proxy, WAF, or gateway even when aggregate admission is enabled. See [Controller AOP Guide](/backend/controller-aop-guide) for the general request-stage diagram and the distinction between a local aspect and a route override of an existing global onion.
+
+The aggregate middleware documented here is a Cabloy Basic runtime addition. Cabloy Start is maintained separately and does not automatically receive this runtime change; shared documentation does not imply aggregate middleware availability in Start.
+
+## Aggregate application admission
+
+Enable the system middleware through application configuration, starting in observe mode:
+
+```ts
+config.onions.middlewareSystem['a-ratelimit:aggregate'] = {
+  enable: true,
+  rateLimit: {
+    mode: 'observe',
+    limit: 100,
+  },
+};
+```
+
+`100` is an example limit, not a measured application capacity or a recommended production value. An enabled aggregate middleware requires an explicit valid `limit` and a `mode` of either `'observe'` or `'enforce'`; there is no enabled default quota. Review observed traffic and Redis health before changing `mode` to `'enforce'`.
+
+### Coverage and ordering
+
+The aggregate middleware runs after `httpLog` and before health handling, the application/instance readiness middleware, routing, and authentication. The HTTP listener enters the executor first: it resolves the instance name and, when applicable, loads the instance record before dispatching system middleware. Aggregate admission does not protect that initial lookup or any instance registration it triggers, and requests that fail before middleware dispatch are not counted.
+
+By default, aggregate admission covers all requests that reach the system middleware chain, including API, SSR, static-file, preflight, health, and unknown-route requests. Standard system middleware `match` and `ignore` options can narrow this coverage; they match the incoming `ctx.path`, including the API prefix where present, before routing. Traffic served entirely by a proxy or CDN never reaches this counter. Other programs, background work, and later WebSocket messages are outside its coverage.
+
+Aggregate admission is independent of the identity interceptor. Both can be enabled, and a controller/action identity policy with `enable: false` does not bypass aggregate admission. There are no built-in aggregate path exemptions: unless explicitly excluded through system middleware matching, saturation can reject health probes and control requests before their handlers run. Account for this operational consequence before enforcing the quota.
+
+### Shared counter and fixed windows
+
+The aggregate counter uses the `limiter` Redis client and the application Redis prefix. It is shared across users, routes, instances, and workers rather than partitioned by identity or active instance. Multiple hosts using the same prefix and Redis share the quota; this is not physical-host discovery or an automatic per-host capacity limit. Keep custom application prefixes unique for applications or environments that require independent quotas.
+
+The window is fixed at `1000` ms and aligned to one-second boundaries. Attempts count toward the window, including requests already rejected for exceeding the limit. As with other fixed-window counters, traffic can burst around a window boundary; the limit is not a rolling-window guarantee.
+
+### Modes, responses, and logs
+
+In `observe` mode, requests over the limit log `rate_limit.would_reject` and still continue to the next middleware. Redis failures log `rate_limit.redis_error` and fail open, allowing the request to continue.
+
+In `enforce` mode, an over-limit request logs `rate_limit.rejected` and returns HTTP `429` with `Retry-After`. A Redis failure logs `rate_limit.redis_error` and returns HTTP `503` instead of allowing unbounded admission. Both responses are direct JSON bodies with the shape `{ code, message }`, even for requests expecting HTML; they do not enter the normal page/error rendering path.
+
+Aggregate admission does not add success `RateLimit-*` headers. The identity interceptor's response headers remain unchanged when a request reaches that interceptor.
+
+Aggregate logs use the same event names as the identity interceptor, with `scope: 'aggregate'`. Redis failures expose only a sanitized error class, not a raw error message. Do not include raw identities, routes, full URLs, or Redis keys in aggregate logs or metric labels.
+
+## Identity interceptor enablement and rollout
 
 The interceptor ships with `enable: false` to preserve compatibility. Enable the global interceptor through standard onion configuration and begin in observe mode:
 
@@ -36,9 +81,9 @@ config.onions.interceptor['a-ratelimit:rateLimit'] = {
 };
 ```
 
-Use instance configuration when tenants require different policy values. Each limiter key always includes the active instance, so one instance never consumes another instance’s quota.
+Use instance configuration when tenants require different identity policy values. Each identity interceptor key includes the active instance, so one instance never consumes another instance’s identity quota. The aggregate middleware instead shares one application-prefix quota across instances.
 
-## Route policies
+## Identity route policies
 
 Use `Core.rateLimit(...)` on a controller for its baseline policy, or on an action for a stricter policy, an intentional shared bucket, or an explicit exemption:
 
@@ -64,7 +109,7 @@ async requestReset() {}
 health() {}
 ```
 
-`enable`, matching, and ordering remain outer interceptor options. The nested `rateLimit` object contains the quota policy, so partial controller/action overrides inherit the remaining policy fields through normal Vona onion merging. Interceptor options use normal Vona precedence: application config, active-instance config, controller/action decorators, then controlled dynamic onion overrides used by tests. A controller/action can enable a narrower policy while the global interceptor is disabled, or set `enable: false` as a reviewed exemption after global activation. Do not put this policy in another middleware’s options: only `a-ratelimit:rateLimit` consumes the `rateLimit` object at the post-Passport interceptor stage.
+`enable`, matching, and ordering remain outer interceptor options. The nested `rateLimit` object contains the quota policy, so partial controller/action overrides inherit the remaining policy fields through normal Vona onion merging. Interceptor options use normal Vona precedence: application config, active-instance config, controller/action decorators, then controlled dynamic onion overrides used by tests. A controller/action can enable a narrower policy while the global interceptor is disabled, or set `enable: false` as a reviewed exemption after global activation. These identity policy fields belong to `a-ratelimit:rateLimit` at the post-Passport interceptor stage, not to another middleware. The aggregate system middleware has its own independent `rateLimit` configuration described above.
 
 ## Identity and Redis storage
 
@@ -72,11 +117,11 @@ The default `key: 'identity'` combines the proxy-trusted `ctx.ip` with the authe
 
 Do not parse `X-Forwarded-For` in application code. Vona resolves `ctx.ip` according to its configured proxy trust settings. The trusted reverse proxy must replace client-supplied forwarding headers before forwarding a request.
 
-The limiter always uses the dedicated `limiter` Redis client; this infrastructure choice is not a route-policy field. It registers one atomic Lua fixed-window counter command during module startup and invokes that command for each request. Redis keys contain the instance, policy, normalized route, window start, and a SHA-256 digest of the identity; raw IP addresses and subject IDs are not stored in key text.
+The identity interceptor always uses the dedicated `limiter` Redis client; this infrastructure choice is not a route-policy field. It registers one atomic Lua fixed-window counter command during module startup and invokes that command for each evaluated request. Identity Redis keys contain the instance, policy, normalized route, window start, and a SHA-256 digest of the identity; raw IP addresses and subject IDs are not stored in key text.
 
 Fixed windows provide one low-cost atomic operation per request. A limit can burst around a window boundary; choose lower limits or shorter windows for especially sensitive actions.
 
-## HTTP response contract
+## Identity HTTP response contract
 
 In enforce mode, evaluated requests expose RFC 9333 fields when `headers` is enabled:
 
@@ -90,7 +135,7 @@ If the limiter Redis operation fails during enforce mode, Cabloy returns `503`,
 
 ## Operations
 
-The primary structured events are `rate_limit.would_reject`, `rate_limit.rejected`, and `rate_limit.redis_error`. They contain only route/policy/instance and error-class information; do not add raw identities, full URLs, or Redis keys to logs or metric labels.
+The primary structured events are `rate_limit.would_reject`, `rate_limit.rejected`, and `rate_limit.redis_error`. Identity interceptor events contain only route/policy/instance and error-class information. Aggregate events carry `scope: 'aggregate'` and omit route/identity detail, with only a sanitized error class for Redis failures. Do not add raw identities, full URLs, or Redis keys to logs or metric labels.
 
 The `limiter` client may initially use the same Redis deployment as other Vona clients, but it is separately configured so production can isolate its endpoint, timeout, and capacity. Ensure Redis remains available before globally setting `enable: true` with `rateLimit.mode: 'enforce'`.
 

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.118",
+  "version": "5.1.119",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/src/suite-vendor/a-vona/modules/a-hmr/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-hmr",
-  "version": "5.1.15",
+  "version": "5.1.16",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "keywords": [

package/vona/src/suite-vendor/a-vona/modules/a-hmr/src/service/hmr.ts

@@ -34,7 +34,7 @@ export class ServiceHmr extends BeanBase {
       if (sceneName === '_error') {
         await this._reloadError(moduleName!, fileModule.errors);
       } else if (sceneName === '_locale') {
-        await this._reloadLocale(moduleName!, fileModule.default, file);
+        await this._reloadLocale();
       } else if (sceneName === '_config') {
         await this._reloadConfig(moduleName!, fileModule.config);
       } else if (sceneName === '_constant') {
@@ -50,17 +50,10 @@ export class ServiceHmr extends BeanBase {
     deepExtend(this.app.meta.error.ebErrors[moduleName], errors);
   }
 
-  private async _reloadLocale(moduleName: string, moduleLocales: {}, file: string) {
-    const locale = path.basename(file, '.ts');
-    // localeModules
-    if (!this.app.meta.localeModules[moduleName]) this.app.meta.localeModules[moduleName] = {};
-    this.app.meta.localeModules[moduleName][locale] = Object.assign(
-      {},
-      moduleLocales,
-      this.app.meta.hmrCacheLocaleModules[moduleName]?.[locale],
-    );
-    // openapi
-    await this.bean.openapi.clearAllCaches();
+  private async _reloadLocale() {
+    // Ordinary dictionaries also contribute to the ordered global fallback map.
+    // Restart to remove stale values and restore project/provider precedence in both maps.
+    this.app.bean.worker.reload();
   }
 
   private async _reloadConfig(moduleName: string, config: TypeModuleResourceConfig) {

package/vona/src/suite-vendor/a-vona/modules/a-ratelimit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-module-a-ratelimit",
-  "version": "5.1.3",
+  "version": "5.1.4",
   "description": "",
   "keywords": [
     "Vona Module"

package/vona/src/suite-vendor/a-vona/modules/a-ratelimit/src/.metadata/index.ts

@@ -25,6 +25,32 @@ declare module 'vona-module-a-ratelimit' {
           }
 }
 /** interceptor: end */
+/** middlewareSystem: begin */
+export * from '../bean/middlewareSystem.aggregate.ts';
+import type { IMiddlewareSystemOptionsAggregate } from '../bean/middlewareSystem.aggregate.ts';
+import 'vona-module-a-aspect';
+declare module 'vona-module-a-aspect' {
+
+    export interface IMiddlewareSystemRecord {
+      'a-ratelimit:aggregate': IMiddlewareSystemOptionsAggregate;
+    }
+
+
+}
+declare module 'vona-module-a-ratelimit' {
+
+        export interface MiddlewareSystemAggregate {
+          /** @internal */
+          get scope(): ScopeModuleARatelimit;
+        }
+
+          export interface MiddlewareSystemAggregate {
+            get $beanFullName(): 'a-ratelimit.middlewareSystem.aggregate';
+            get $onionName(): 'a-ratelimit:aggregate';
+            get $onionOptions(): IMiddlewareSystemOptionsAggregate;
+          }
+}
+/** middlewareSystem: end */
 /** service: begin */
 export * from '../service/rateLimit.ts';
 

package/vona/src/suite-vendor/a-vona/modules/a-ratelimit/src/bean/middlewareSystem.aggregate.ts

@@ -0,0 +1,58 @@
+import type { Next } from 'vona';
+import type {
+  IDecoratorMiddlewareSystemOptions,
+  IMiddlewareSystemExecute,
+} from 'vona-module-a-aspect';
+
+import { BeanBase } from 'vona';
+import { MiddlewareSystem } from 'vona-module-a-aspect';
+
+import type { IRateLimitAggregatePolicy, IRateLimitResult } from '../types/rateLimit.ts';
+
+export interface IMiddlewareSystemOptionsAggregate extends IDecoratorMiddlewareSystemOptions {
+  rateLimit?: IRateLimitAggregatePolicy;
+}
+
+@MiddlewareSystem<IMiddlewareSystemOptionsAggregate>({
+  enable: false,
+  dependencies: 'a-logger:httpLog',
+  dependents: ['a-metrics:health', 'a-instance:app'],
+})
+export class MiddlewareSystemAggregate extends BeanBase implements IMiddlewareSystemExecute {
+  async execute(options: IMiddlewareSystemOptionsAggregate, next: Next) {
+    const policy = options.rateLimit;
+    if (!policy) throw new Error('rate-limit aggregate policy is required when enabled');
+    // Validation is synchronous; only Redis admission failures enter the catch below.
+    const admission = this.scope.service.rateLimit.admitAggregate(policy);
+    let result: IRateLimitResult;
+    try {
+      result = await admission;
+    } catch (error) {
+      this.$logger.warn({
+        event: 'rate_limit.redis_error',
+        scope: 'aggregate',
+        mode: policy.mode,
+        error: error instanceof Error ? error.name : 'Error',
+      });
+      if (policy.mode === 'observe') return next();
+      this._reject(503, 'Service Unavailable');
+      return;
+    }
+    if (result.allowed) return next();
+    this.$logger.warn({
+      event: policy.mode === 'observe' ? 'rate_limit.would_reject' : 'rate_limit.rejected',
+      scope: 'aggregate',
+      mode: policy.mode,
+      limit: policy.limit,
+    });
+    if (policy.mode === 'observe') return next();
+    this.ctx.set('Retry-After', String(result.retryAfterSeconds));
+    this._reject(429, 'Too Many Requests');
+  }
+
+  private _reject(status: number, message: string) {
+    this.ctx.status = status;
+    this.ctx.type = 'application/json';
+    this.ctx.body = { code: status, message };
+  }
+}

package/vona/src/suite-vendor/a-vona/modules/a-ratelimit/src/service/rateLimit.ts

@@ -2,7 +2,11 @@ import { createHash } from 'node:crypto';
 import { BeanBase, cast } from 'vona';
 import { Service } from 'vona-module-a-bean';
 
-import type { IRateLimitPolicy, IRateLimitResult } from '../types/rateLimit.ts';
+import type {
+  IRateLimitAggregatePolicy,
+  IRateLimitPolicy,
+  IRateLimitResult,
+} from '../types/rateLimit.ts';
 
 @Service()
 export class ServiceRateLimit extends BeanBase {
@@ -14,16 +18,32 @@ export class ServiceRateLimit extends BeanBase {
     this._validatePolicy(policy);
     const now = Date.now();
     const key = this._createKey(policy, now);
-    const result = (await cast(this.clientRedis).rateLimitAdmit(key, String(policy.windowMs))) as [
+    return this._admit(key, policy.limit, policy.windowMs);
+  }
+
+  admitAggregate(policy: IRateLimitAggregatePolicy): Promise<IRateLimitResult> {
+    if (!['observe', 'enforce'].includes(policy.mode)) {
+      throw new Error('rate-limit aggregate mode must be observe or enforce');
+    }
+    if (!Number.isSafeInteger(policy.limit) || policy.limit < 1) {
+      throw new Error('rate-limit aggregate limit must be a positive safe integer');
+    }
+    const windowMs = 1_000;
+    const windowStart = Math.floor(Date.now() / windowMs) * windowMs;
+    return this._admit(`rate-limit:aggregate:v1:${windowStart}`, policy.limit, windowMs);
+  }
+
+  private async _admit(key: string, limit: number, windowMs: number): Promise<IRateLimitResult> {
+    const result = (await cast(this.clientRedis).rateLimitAdmit(key, String(windowMs))) as [
       number | string,
       number | string,
     ];
     const current = Number(result[0]);
     const resetAfterMs = Math.max(0, Number(result[1]));
     return {
-      allowed: current <= policy.limit,
-      limit: policy.limit,
-      remaining: Math.max(0, policy.limit - current),
+      allowed: current <= limit,
+      limit,
+      remaining: Math.max(0, limit - current),
       resetAfterMs,
       retryAfterSeconds: Math.max(1, Math.ceil(resetAfterMs / 1000)),
     };

package/vona/src/suite-vendor/a-vona/modules/a-ratelimit/src/types/rateLimit.ts

@@ -14,6 +14,11 @@ export interface IRateLimitPolicy {
   headers: boolean;
 }
 
+export interface IRateLimitAggregatePolicy {
+  mode: RateLimitMode;
+  limit: number;
+}
+
 export interface IRateLimitResult {
   allowed: boolean;
   limit: number;

package/vona/src/suite-vendor/a-vona/modules/a-ratelimit/test/aggregate.test.ts

@@ -0,0 +1,247 @@
+import type { IMiddlewareSystemOptionsAggregate, RateLimitMode } from 'vona-module-a-ratelimit';
+
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { once } from 'node:events';
+import { createServer } from 'node:http';
+import { describe, it } from 'node:test';
+import { setTimeout } from 'node:timers/promises';
+import { cast, compose } from 'vona';
+import { app } from 'vona-mock';
+import { MiddlewareSystemAggregate, ServiceRateLimit } from 'vona-module-a-ratelimit';
+
+const exemptPath = '/api/test/vona/performAction/rateLimitExempt';
+const limitedPath = '/api/test/vona/performAction/rateLimit';
+
+type AdmitCommand = (key: string, windowMs: string) => Promise<[number, number]>;
+
+function createService(command: AdmitCommand) {
+  const service = app.bean._newBean(ServiceRateLimit);
+  Object.defineProperty(service, 'bean', {
+    value: { redis: { get: () => ({ rateLimitAdmit: command }) } },
+  });
+  return service;
+}
+
+type Request = (path: string, options?: RequestInit) => Promise<Response>;
+
+async function withGate(
+  mode: RateLimitMode,
+  limit: number,
+  command: AdmitCommand,
+  fn: (request: Request) => Promise<void>,
+) {
+  await app.bean.executor.mockCtx(async () => {
+    const middleware = app.bean._newBean(MiddlewareSystemAggregate);
+    Object.defineProperty(middleware, 'scope', {
+      value: { service: { rateLimit: createService(command) } },
+    });
+    const policyName = `test-aggregate-${randomUUID()}`;
+    // Keep admission and its listener local; never patch the shared application chain.
+    const chain = compose([
+      (_ctx, next) => middleware.execute({ rateLimit: { mode, limit } }, next),
+      ...app.middleware,
+    ]);
+    const server = createServer((req, res) => {
+      void app.bean.executor
+        .newCtx(
+          () => {
+            app.ctx.onionsDynamic = {
+              interceptor: { 'a-ratelimit:rateLimit': { rateLimit: { name: policyName } } },
+            };
+            return cast(app).handleRequest(app.ctx, chain);
+          },
+          { dbInfo: { level: 0 }, innerAccess: false, req, res },
+        )
+        .catch(error => res.destroy(error));
+    });
+    try {
+      server.listen(0, '127.0.0.1');
+      await once(server, 'listening');
+      const address = server.address();
+      assert.ok(address && typeof address !== 'string');
+      await fn((path, options) =>
+        fetch(`http://127.0.0.1:${address.port}${path}`, {
+          ...options,
+          headers: { accept: 'application/json', ...options?.headers },
+          signal: AbortSignal.timeout(10_000),
+        }),
+      );
+    } finally {
+      await new Promise<void>((resolve, reject) => {
+        server.close(error => (error ? reject(error) : resolve()));
+        server.closeAllConnections();
+      });
+      const redis = app.bean.redis.get('limiter');
+      const prefix = redis.options.keyPrefix ?? '';
+      const keys = await redis.keys(`${prefix}rate-limit:v1:*:${encodeURIComponent(policyName)}:*`);
+      if (keys.length) await redis.del(...keys.map(key => key.slice(prefix.length)));
+    }
+  });
+}
+
+function counter(): AdmitCommand {
+  let current = 0;
+  return async () => [++current, 1_000];
+}
+
+describe('aggregate.test.ts', { concurrency: false }, () => {
+  it('shares an atomic Redis budget across request contexts and expires its counter', async () => {
+    const key = `test:aggregate:${randomUUID()}`;
+    const redis = cast(app.bean.redis.get('limiter'));
+    const keys: string[] = [];
+    // Isolate this test's bucket without changing the production key dimensions or TTL.
+    const service = createService((actualKey, windowMs) => {
+      keys.push(actualKey);
+      return redis.rateLimitAdmit(key, windowMs);
+    });
+    try {
+      const results = await Promise.all(
+        [0, 1, 2, 3].map(index =>
+          app.bean.executor.mockCtx(async () => {
+            app.ctx.req.url = `/aggregate-${index}`;
+            return service.admitAggregate({
+              mode: 'enforce',
+              limit: 2,
+            });
+          }),
+        ),
+      );
+      assert.equal(results.filter(result => result.allowed).length, 2);
+      assert.ok(keys.every(actualKey => /^rate-limit:aggregate:v1:\d+$/.test(actualKey)));
+      assert.equal(await redis.get(key), '4');
+      const ttl = await redis.pttl(key);
+      assert.ok(ttl > 0 && ttl <= 1_000);
+      await setTimeout(ttl + 20);
+      assert.equal(await redis.get(key), null);
+      await app.bean.executor.mockCtx(async () => {
+        const result = await service.admitAggregate({
+          mode: 'enforce',
+          limit: 2,
+        });
+        assert.equal(result.allowed, true);
+        assert.equal(result.remaining, 1);
+      });
+    } finally {
+      await redis.del(key);
+    }
+  });
+
+  it('counts health, preflight, unknown paths and identity-exempt actions in one HTTP budget', async () => {
+    await withGate('enforce', 3, counter(), async request => {
+      const health = await request('/health/live');
+      assert.equal(health.status, 200);
+      await health.text();
+      const preflight = await request('/aggregate-unknown', {
+        method: 'OPTIONS',
+        headers: { 'origin': 'https://example.test', 'access-control-request-method': 'GET' },
+      });
+      assert.notEqual(preflight.status, 429);
+      await preflight.text();
+      const unknown = await request(`/aggregate-unknown-${randomUUID()}`);
+      assert.equal(unknown.status, 404);
+      await unknown.text();
+      const rejected = await request(exemptPath);
+      assert.equal(rejected.status, 429);
+      assert.equal(rejected.headers.get('retry-after'), '1');
+      assert.equal(rejected.headers.get('ratelimit-limit'), null);
+      assert.deepEqual(await rejected.json(), { code: 429, message: 'Too Many Requests' });
+    });
+  });
+
+  it('observes excess requests without rejecting or replacing identity headers', async () => {
+    await withGate('observe', 1, counter(), async request => {
+      for (let index = 0; index < 2; index++) {
+        const response = await request(exemptPath);
+        assert.equal(response.status, 200);
+        assert.equal(response.headers.get('ratelimit-limit'), null);
+        assert.equal(response.headers.get('retry-after'), null);
+        await response.text();
+      }
+    });
+    await withGate('enforce', 100, counter(), async request => {
+      for (let index = 0; index < 2; index++) {
+        const response = await request(limitedPath);
+        assert.equal(response.status, 200);
+        assert.equal(response.headers.get('ratelimit-limit'), '2');
+        await response.text();
+      }
+      const response = await request(limitedPath);
+      assert.equal(response.status, 429);
+      assert.equal(response.headers.get('ratelimit-limit'), '2');
+      await response.text();
+    });
+  });
+
+  it('fails open only in observe mode and preserves HTTP 503 for HTML callers', async () => {
+    const unavailable: AdmitCommand = async () => {
+      throw new Error('redis unavailable');
+    };
+    await withGate('observe', 1, unavailable, async request => {
+      const response = await request('/health/live');
+      assert.equal(response.status, 200);
+      await response.text();
+    });
+    await withGate('enforce', 1, unavailable, async request => {
+      const response = await request(exemptPath, { headers: { accept: 'text/html' } });
+      assert.equal(response.status, 503);
+      assert.match(response.headers.get('content-type')!, /application\/json/);
+      assert.equal(response.headers.get('retry-after'), null);
+      assert.deepEqual(await response.json(), { code: 503, message: 'Service Unavailable' });
+    });
+  });
+
+  it('keeps competing gates and the shared application listener independent', async () => {
+    await Promise.all([
+      withGate(
+        'enforce',
+        1,
+        async () => [2, 1_000],
+        async request => {
+          const response = await request('/health/live');
+          assert.equal(response.status, 429);
+          await response.text();
+          const address = app.server.address();
+          assert.ok(address && typeof address !== 'string');
+          const shared = await fetch(`http://127.0.0.1:${address.port}/health/live`, {
+            signal: AbortSignal.timeout(10_000),
+          });
+          assert.equal(shared.status, 200);
+          await shared.text();
+        },
+      ),
+      withGate(
+        'enforce',
+        1,
+        async () => [1, 1_000],
+        async request => {
+          const response = await request('/health/live');
+          assert.equal(response.status, 200);
+          await response.text();
+        },
+      ),
+    ]);
+  });
+
+  it('requires valid explicit configuration even in observe mode', async () => {
+    await app.bean.executor.mockCtx(async () => {
+      const middleware = app.bean._newBean(MiddlewareSystemAggregate);
+      let downstream = false;
+      const next = async () => {
+        downstream = true;
+      };
+      for (const options of [
+        {},
+        { rateLimit: { mode: 'observe', limit: 0 } },
+        { rateLimit: { mode: 'observe', limit: 1.5 } },
+        { rateLimit: { mode: 'invalid', limit: 1 } },
+      ]) {
+        await assert.rejects(
+          middleware.execute(options as IMiddlewareSystemOptionsAggregate, next),
+          /rate-limit aggregate/,
+        );
+      }
+      assert.equal(downstream, false);
+    });
+  });
+});

package/vona/src/suite-vendor/a-vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-suite-a-vona",
-  "version": "5.1.109",
+  "version": "5.1.110",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "",
   "author": "",