@zintrust/trace 1.2.0 → 1.5.2

package/README.md

@@ -39,6 +39,9 @@ TRACE_PROXY_PATH=/zin/trace/write
 TRACE_PROXY_KEY_ID=           # optional — falls back to APP_NAME
 TRACE_PROXY_SECRET=           # optional — falls back to APP_KEY
 TRACE_PROXY_TIMEOUT_MS=30000
+TRACE_PROXY_MIDDLEWARE=       # optional — comma-separated route middleware applied on the receiver
+TRACE_PROXY_RATE_LIMIT_MAX=0  # optional — when > 0, adds rateLimit:<max>:<window> automatically
+TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES=0
 TRACE_PRUNE_HOURS=24          # how long entries are kept (default: 24)
 TRACE_SLOW_QUERY_MS=100       # slow-query threshold in ms (default: 100)
 TRACE_LOG_LEVEL=info          # minimum log level captured (default: info)
@@ -61,6 +64,8 @@ When `TRACE_CONTENT_QUEUE_DRIVER` is set, trace writes enqueue through that regi
 
 When `TRACE_PROXY=true`, the local runtime keeps collecting the same trace payload it would normally send to storage, but it sends the write/update/stale-family operations to `TRACE_PROXY_URL + TRACE_PROXY_PATH` instead of writing directly to the local trace database. The receiver can then persist those entries with the standard `TraceStorage` flow.
 
+On the receiver, use `TRACE_PROXY_MIDDLEWARE` for any gateway middleware such as `auth,admin`. If you want a dedicated ingest rate limit without encoding `rateLimit:<max>:<window>` by hand, set `TRACE_PROXY_RATE_LIMIT_MAX` and `TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES`; the gateway appends that parameterized rate-limit middleware automatically.
+
 This currently works with any queue driver already registered in ZinTrust. First-class Cloudflare Queue support still requires a dedicated queue driver and queue-runtime registration for that transport.
 
 ### 2. Enable the plugin in `zintrust.plugins.*`

package/dist/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.2.0",
-  "buildDate": "2026-04-24T08:48:22.033Z",
+  "version": "1.5.2",
+  "buildDate": "2026-04-25T12:38:43.860Z",
   "buildEnvironment": {
     "node": "v20.20.2",
     "platform": "linux",
     "arch": "x64"
   },
   "git": {
-    "commit": "a179ffe4",
+    "commit": "616b0d5d",
     "branch": "master"
   },
   "package": {
@@ -83,15 +83,15 @@
     },
     "index.js": {
       "size": 3421,
-      "sha256": "def9be169e22b131447ecfd522a255f5800a7407e0ab58aad9efa1150c5e2a0e"
+      "sha256": "199bd3c4a0618b7b336e3b866169656a0b49c8f527b083be87d44fe092518ad6"
     },
     "ingest/TraceIngestGateway.d.ts": {
       "size": 786,
       "sha256": "3a0a46fa5bbf5367047214533ec0ee92a171ee35a60d25c197eea1eed1ff0f65"
     },
     "ingest/TraceIngestGateway.js": {
-      "size": 9413,
-      "sha256": "84d0d2d0bd648d9734b2c19881d953f6ebd9d55e4d96a3d3e5d500ffd332c5ac"
+      "size": 10936,
+      "sha256": "c95f0e42f1294d8ae2e406a5910f8e74044c2b586e82e726876d75ddfafef27e"
     },
     "migrations/20260331000001_create_zin_trace_entries_table.d.ts": {
       "size": 304,

package/dist/ingest/TraceIngestGateway.js

@@ -13,6 +13,9 @@ const parseMiddleware = (value) => value
     .split(',')
     .map((entry) => entry.trim())
     .filter((entry) => entry.length > 0);
+const isParameterizedRateLimitMiddleware = (value) => {
+    return /^rateLimit:\d+:\d+(?:\.\d+)?$/.test(value.trim());
+};
 const trimTrailingSlashes = (value) => {
     let trimmed = value;
     while (trimmed.endsWith('/')) {
@@ -210,8 +213,46 @@ const resolveSigningWindowMs = (overrides) => {
 const resolveNonceTtlMs = (overrides) => {
     return overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000);
 };
+const resolveRateLimitMax = () => {
+    return Env.getInt('TRACE_PROXY_RATE_LIMIT_MAX', 0);
+};
+const resolveRateLimitWindowMinutes = () => {
+    const windowMinutes = Env.getFloat('TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES', 0);
+    return Math.max(windowMinutes, 0);
+};
+const createRateLimitMiddleware = () => {
+    const max = resolveRateLimitMax();
+    const windowMinutes = resolveRateLimitWindowMinutes();
+    if (!Number.isFinite(max) || !Number.isInteger(max)) {
+        throw ErrorFactory.createConfigError('TRACE_PROXY_RATE_LIMIT_MAX must be a valid integer', {
+            value: max,
+            envKey: 'TRACE_PROXY_RATE_LIMIT_MAX',
+        });
+    }
+    if (!Number.isFinite(windowMinutes)) {
+        throw ErrorFactory.createConfigError('TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES must be a valid number', {
+            value: windowMinutes,
+            envKey: 'TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES',
+        });
+    }
+    if (max <= 0 || windowMinutes <= 0) {
+        return undefined;
+    }
+    return `rateLimit:${max}:${windowMinutes}`;
+};
 const resolveMiddleware = (overrides) => {
-    return overrides?.middleware ?? parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+    if (overrides?.middleware !== undefined) {
+        return overrides.middleware;
+    }
+    const configured = parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+    const rateLimitMiddleware = createRateLimitMiddleware();
+    if (rateLimitMiddleware === undefined) {
+        return configured;
+    }
+    return [
+        ...configured.filter((entry) => !isParameterizedRateLimitMiddleware(entry)),
+        rateLimitMiddleware,
+    ];
 };
 const readSettings = (overrides) => {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "1.2.0",
+  "version": "1.5.2",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.9.6"
+    "@zintrust/core": "*"
   },
   "publishConfig": {
     "access": "public"

package/src/ingest/TraceIngestGateway.ts

@@ -56,6 +56,10 @@ const parseMiddleware = (value: string): ReadonlyArray<string> =>
     .map((entry) => entry.trim())
     .filter((entry) => entry.length > 0);
 
+const isParameterizedRateLimitMiddleware = (value: string): boolean => {
+  return /^rateLimit:\d+:\d+(?:\.\d+)?$/.test(value.trim());
+};
+
 const trimTrailingSlashes = (value: string): string => {
   let trimmed = value;
   while (trimmed.endsWith('/')) {
@@ -295,8 +299,58 @@ const resolveNonceTtlMs = (overrides?: TraceIngestGatewayOverrides): number => {
   return overrides?.nonceTtlMs ?? Env.getInt('TRACE_PROXY_NONCE_TTL_MS', 120000);
 };
 
+const resolveRateLimitMax = (): number => {
+  return Env.getInt('TRACE_PROXY_RATE_LIMIT_MAX', 0);
+};
+
+const resolveRateLimitWindowMinutes = (): number => {
+  const windowMinutes = Env.getFloat('TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES', 0);
+  return Math.max(windowMinutes, 0);
+};
+
+const createRateLimitMiddleware = (): string | undefined => {
+  const max = resolveRateLimitMax();
+  const windowMinutes = resolveRateLimitWindowMinutes();
+
+  if (!Number.isFinite(max) || !Number.isInteger(max)) {
+    throw ErrorFactory.createConfigError('TRACE_PROXY_RATE_LIMIT_MAX must be a valid integer', {
+      value: max,
+      envKey: 'TRACE_PROXY_RATE_LIMIT_MAX',
+    });
+  }
+
+  if (!Number.isFinite(windowMinutes)) {
+    throw ErrorFactory.createConfigError(
+      'TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES must be a valid number',
+      {
+        value: windowMinutes,
+        envKey: 'TRACE_PROXY_RATE_LIMIT_WINDOW_MINUTES',
+      }
+    );
+  }
+
+  if (max <= 0 || windowMinutes <= 0) {
+    return undefined;
+  }
+
+  return `rateLimit:${max}:${windowMinutes}`;
+};
+
 const resolveMiddleware = (overrides?: TraceIngestGatewayOverrides): ReadonlyArray<string> => {
-  return overrides?.middleware ?? parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+  if (overrides?.middleware !== undefined) {
+    return overrides.middleware;
+  }
+
+  const configured = parseMiddleware(Env.get('TRACE_PROXY_MIDDLEWARE', ''));
+  const rateLimitMiddleware = createRateLimitMiddleware();
+  if (rateLimitMiddleware === undefined) {
+    return configured;
+  }
+
+  return [
+    ...configured.filter((entry) => !isParameterizedRateLimitMiddleware(entry)),
+    rateLimitMiddleware,
+  ];
 };
 
 const readSettings = (overrides?: TraceIngestGatewayOverrides): TraceIngestGatewaySettings => {