@blamejs/core 0.4.18 → 0.4.20

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.19** (2026-04-30) — b.router: schema-validated routes + OpenAPI gen
+- **0.4.18** (2026-04-30) — cookieJar forensic-test strengthening (real crypto, replay, nonce)
 - **0.4.17** (2026-04-30) — b.httpClient.cookieJar (encrypted) + wiki catch-up sweep
 - **0.4.16** (2026-04-30) — b.httpClient: interceptors + progress events
 - **0.4.15** (2026-04-30) — b.httpClient: redirect-following + outbound multipart

package/lib/db.js

@@ -350,9 +350,13 @@ var FRAMEWORK_SCHEMA = [
       finishedAt:      "INTEGER",
       traceId:         "TEXT",
       classification:  "TEXT",
+      priority:        "INTEGER NOT NULL DEFAULT 0",
     },
     indexes: [
       { name: "idx_jobs_lease",    columns: ["queueName", "status", "availableAt"] },
+      // Priority lease index — pickers walk this when ORDER BY priority DESC,
+      // availableAt ASC, enqueuedAt ASC; matches the queue.lease ordering.
+      { name: "idx_jobs_priority", columns: ["queueName", "status", "priority", "availableAt"] },
       "leaseExpiresAt",
       "finishedAt",
     ],

package/lib/framework-schema.js

@@ -476,10 +476,12 @@ function _jobsDDL(dialect) {
       "  lastError        TEXT," +
       "  finishedAt       " + t.INT + "," +
       "  traceId          TEXT," +
-      "  classification   TEXT" +
+      "  classification   TEXT," +
+      "  priority         " + t.INT + " NOT NULL DEFAULT 0" +
       ")",
     indexes: [
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_lease ON " + name + " (queueName, status, availableAt)",
+      "CREATE INDEX IF NOT EXISTS idx_" + name + "_priority ON " + name + " (queueName, status, priority, availableAt)",
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_leaseExpiresAt ON " + name + " (leaseExpiresAt)",
       "CREATE INDEX IF NOT EXISTS idx_" + name + "_finishedAt ON " + name + " (finishedAt)",
     ],

package/lib/queue-local.js

@@ -50,7 +50,7 @@ var JOB_COLS = [
   "_id", "queueName", "payload", "status",
   "enqueuedAt", "availableAt", "leasedAt", "leaseExpiresAt",
   "attempts", "maxAttempts", "lastError", "finishedAt",
-  "traceId", "classification",
+  "traceId", "classification", "priority",
 ];
 
 // Columns returned by lease() / used by RETURNING. Subset of JOB_COLS
@@ -97,6 +97,8 @@ function create(_config) {
     var nowMs = Date.now();
     var availableAt = nowMs + (opts.delaySeconds ? opts.delaySeconds * 1000 : 0);
 
+    var priority = (typeof opts.priority === "number" && isFinite(opts.priority))
+      ? Math.floor(opts.priority) : 0;
     var row = {
       _id:             generateToken(16),
       queueName:       queueName,
@@ -112,6 +114,7 @@ function create(_config) {
       finishedAt:      null,
       traceId:         opts.traceId || null,
       classification:  opts.classification || null,
+      priority:        priority,
     };
     var sealed = cryptoField.sealRow("_blamejs_jobs", row);
     var values = JOB_COLS.map(function (c) { return c in sealed ? sealed[c] : null; });
@@ -148,7 +151,7 @@ function create(_config) {
       "WHERE _id IN (" +
       "  SELECT _id FROM _blamejs_jobs " +
       "  WHERE queueName = ? AND status = 'pending' AND availableAt <= ? " +
-      "  ORDER BY availableAt ASC, enqueuedAt ASC " +
+      "  ORDER BY priority DESC, availableAt ASC, enqueuedAt ASC " +
       "  LIMIT ?" +
       ") " +
       "RETURNING " + _quotedList(LEASE_RETURN_COLS);

package/lib/queue.js

@@ -177,6 +177,42 @@ function consume(queueName, handler, opts) {
   var pollIntervalMs   = opts.pollIntervalMs   || 1000;
   var fastPollMs       = opts.fastPollMs       || 50;
 
+  // Rate-limit: { max, perSeconds } caps how many handler INVOCATIONS
+  // start within any rolling perSeconds window. Token-bucket-style
+  // accounting keeps it cheap (just a sliding deque of timestamps).
+  var rateLimit = null;
+  if (opts.rateLimit) {
+    if (!opts.rateLimit.max || !opts.rateLimit.perSeconds ||
+        typeof opts.rateLimit.max !== "number" ||
+        typeof opts.rateLimit.perSeconds !== "number") {
+      throw _err("BAD_RATE_LIMIT",
+        "consume({ rateLimit }): expected { max: number, perSeconds: number }, got " +
+        JSON.stringify(opts.rateLimit), true);
+    }
+    rateLimit = {
+      max:        opts.rateLimit.max,
+      windowMs:   opts.rateLimit.perSeconds * 1000,
+      timestamps: [],
+    };
+  }
+  function _rateLimitWaitMs() {
+    if (!rateLimit) return 0;
+    var now = Date.now();
+    var cutoff = now - rateLimit.windowMs;
+    while (rateLimit.timestamps.length > 0 && rateLimit.timestamps[0] <= cutoff) {
+      rateLimit.timestamps.shift();
+    }
+    if (rateLimit.timestamps.length < rateLimit.max) return 0;
+    return rateLimit.timestamps[0] + rateLimit.windowMs - now + 1;
+  }
+  function _rateLimitConsume() {
+    if (rateLimit) rateLimit.timestamps.push(Date.now());
+  }
+
+  // Progress audit-emit rate-limit — protect the audit chain from a
+  // chatty handler that calls progress() every loop iteration.
+  var PROGRESS_MIN_INTERVAL_MS = 250;
+
   // Each consumer has its own AbortController so cancel() unblocks any
   // in-flight poll-sleep immediately rather than waiting up to
   // pollIntervalMs (default 1s) for the next while-loop iteration.
@@ -209,6 +245,18 @@ function consume(queueName, handler, opts) {
         await _pollSleep(fastPollMs);
         continue;
       }
+      // If rate-limited and we'd exceed the budget, sleep until the
+      // next slot opens. We lease at most `max - currentTokens` jobs to
+      // stay under the cap.
+      if (rateLimit) {
+        var wait = _rateLimitWaitMs();
+        if (wait > 0) {
+          await _pollSleep(Math.min(wait, pollIntervalMs));
+          continue;
+        }
+        var remainingTokens = rateLimit.max - rateLimit.timestamps.length;
+        if (remainingTokens < slots) slots = Math.max(1, remainingTokens);
+      }
       var jobs;
       try { jobs = await b.lease(queueName, leaseDurationMs, slots); }
       catch {
@@ -227,9 +275,17 @@ function consume(queueName, handler, opts) {
           _emit("system.queue.consume.start", {
             metadata: { queue: queueName, backend: b.name, jobId: job.jobId, attempt: job.attempts, traceId: job.traceId },
           });
+          // Consume a rate-limit slot at handler-start so the budget
+          // tracks invocation rate, not lease rate (a single lease that
+          // splits work across many sub-units doesn't double-count).
+          _rateLimitConsume();
+
           // Handler context — second arg to handler. Carries
-          // ctx.extendLease(ms) for long-running handlers that need to
-          // bump their own lease before the sweeper reclaims the job.
+          // ctx.extendLease(ms) for long-running handlers and
+          // ctx.progress(0..100) for surfacing job progress to the
+          // audit chain (rate-limited so chatty handlers don't drown it).
+          var lastProgressEmitAt = 0;
+          var lastProgressValue = -1;
           var ctx = {
             extendLease: function (additionalMs) {
               if (typeof b.extendLease !== "function") {
@@ -246,6 +302,25 @@ function consume(queueName, handler, opts) {
                 return ok;
               });
             },
+            progress: function (pct) {
+              if (typeof pct !== "number" || !isFinite(pct)) return;
+              var clamped = Math.max(0, Math.min(100, Math.floor(pct)));
+              var now = Date.now();
+              // Always emit 0 and 100 (start/done markers); throttle the rest.
+              var isMarker = clamped === 0 || clamped === 100;
+              if (!isMarker && (now - lastProgressEmitAt) < PROGRESS_MIN_INTERVAL_MS) return;
+              if (clamped === lastProgressValue && !isMarker) return;
+              lastProgressEmitAt = now;
+              lastProgressValue = clamped;
+              observability.event("queue.progress", clamped, { queueName: queueName });
+              _emit("system.queue.progress", {
+                metadata: {
+                  queue: queueName, backend: b.name, jobId: job.jobId,
+                  attempt: job.attempts, traceId: job.traceId,
+                  percent: clamped,
+                },
+              });
+            },
           };
           observability.tap("queue.consume",
             { queueName: queueName, backend: b.name, jobId: job.jobId, attempt: job.attempts },

package/lib/router.js

@@ -30,6 +30,114 @@ var { boot } = require("./log");
 
 var log = boot("router");
 
+// ---- Schema-spec helpers (route-level body/query/params validation) ----
+
+var ALLOWED_SPEC_KEYS = [
+  "body", "query", "params", "response",
+  "bodyJsonSchema", "queryJsonSchema", "paramsJsonSchema", "responseJsonSchema",
+  "description", "summary", "tags", "validateResponse",
+];
+
+function _validateRouteSpec(spec, method, pattern) {
+  var keys = Object.keys(spec);
+  for (var i = 0; i < keys.length; i++) {
+    if (ALLOWED_SPEC_KEYS.indexOf(keys[i]) === -1) {
+      throw new Error("router." + method.toLowerCase() + "(" + pattern +
+        "): unknown spec key '" + keys[i] + "'. Allowed: " +
+        ALLOWED_SPEC_KEYS.slice().sort().join(", "));
+    }
+  }
+  function _checkSchema(name) {
+    var s = spec[name];
+    if (s === undefined) return;
+    if (!s || typeof s !== "object" || typeof s.safeParse !== "function") {
+      throw new Error("router." + method.toLowerCase() + "(" + pattern +
+        "): spec." + name + " must be a b.safeSchema-shaped schema (with safeParse)");
+    }
+  }
+  _checkSchema("body");
+  _checkSchema("query");
+  _checkSchema("params");
+  _checkSchema("response");
+  if (spec.tags !== undefined) {
+    if (!Array.isArray(spec.tags) || !spec.tags.every(function (t) { return typeof t === "string"; })) {
+      throw new Error("router." + method.toLowerCase() + "(" + pattern +
+        "): spec.tags must be an array of strings");
+    }
+  }
+}
+
+function _writeValidationError(res, where, errors) {
+  if (res.writableEnded || res.headersSent) return;
+  var body = JSON.stringify({
+    error: "validation",
+    where: where,
+    issues: errors,
+  });
+  res.writeHead(400, {
+    "Content-Type":   "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+function _makeSchemaValidator(spec) {
+  // 3-arg signature → router treats as middleware, chains via next().
+  return function schemaValidator(req, res, next) {
+    if (spec.params && req.params !== undefined) {
+      var pp = spec.params.safeParse(req.params);
+      if (!pp.ok) return _writeValidationError(res, "params", pp.errors);
+      req.params = pp.value;
+    }
+    if (spec.query && req.query !== undefined) {
+      var qq = spec.query.safeParse(req.query);
+      if (!qq.ok) return _writeValidationError(res, "query", qq.errors);
+      req.query = qq.value;
+    }
+    if (spec.body && req.body !== undefined) {
+      var bb = spec.body.safeParse(req.body);
+      if (!bb.ok) return _writeValidationError(res, "body", bb.errors);
+      req.body = bb.value;
+    }
+    next();
+  };
+}
+
+function _makeResponseValidator(spec) {
+  // Wraps res.json (and res.end when called with a JSON-shaped buffer)
+  // to validate the response body against spec.response. Mode:
+  //   - BLAMEJS_VALIDATE_RESPONSES=throw (or per-route validateResponse: "throw")
+  //     → throw a SafeSchemaError-shaped error; route handler's caller sees a 500.
+  //   - BLAMEJS_VALIDATE_RESPONSES=warn (or per-route validateResponse: "warn")
+  //     → log a warning; ship the response as-is (prod-safe).
+  var perRoute = spec.validateResponse;
+  var globalMode = process.env.BLAMEJS_VALIDATE_RESPONSES;
+  var mode = (perRoute === "throw" || perRoute === "warn") ? perRoute :
+             (globalMode === "throw" || globalMode === "warn") ? globalMode : null;
+  if (!mode) return function passthrough(_req, _res, next) { next(); };
+
+  return function responseValidator(req, res, next) {
+    var origJson = typeof res.json === "function" ? res.json.bind(res) : null;
+    if (origJson) {
+      res.json = function (value) {
+        var rr = spec.response.safeParse(value);
+        if (!rr.ok) {
+          if (mode === "throw") {
+            throw new Error("router response-validation failed for " +
+              (req.method + " " + req.routePattern) + ": " +
+              JSON.stringify(rr.errors));
+          }
+          // warn mode
+          log.warn("response-validation drift on " + req.method + " " + req.routePattern +
+                   ": " + JSON.stringify(rr.errors).slice(0, 500));
+        }
+        return origJson(value);
+      };
+    }
+    next();
+  };
+}
+
 function compilePattern(pattern) {
   var keys = [];
   var regexStr = pattern
@@ -128,24 +236,154 @@ class Router {
     this.middleware.push(fn);
   }
 
-  get(pattern, ...handlers) {
-    this.routes.push({ method: "GET", ...compilePattern(pattern), handlers });
+  // Internal: split a route registration's args into { spec, handlers }.
+  // The first non-pattern arg is the schema spec when it's a plain object
+  // (not a function); subsequent args are handler middlewares. Operators
+  // who never pass a spec keep the existing two-arg shape working.
+  _splitArgs(args) {
+    if (args.length > 0 && args[0] && typeof args[0] === "object" &&
+        !Array.isArray(args[0]) && typeof args[0] !== "function") {
+      return { spec: args[0], handlers: args.slice(1) };
+    }
+    return { spec: null, handlers: args };
+  }
+
+  _registerRoute(method, pattern, args) {
+    var split = this._splitArgs(args);
+    if (split.spec) _validateRouteSpec(split.spec, method, pattern);
+    var handlers = split.handlers;
+    if (split.spec) {
+      // Pre-handler validates body / query / params. Runs after the
+      // global middleware chain (bodyParser populates req.body before
+      // route dispatch) but before any route-specific handler.
+      handlers = [_makeSchemaValidator(split.spec)].concat(handlers);
+      // Response validation (dev/opt-in via env or per-route opt).
+      if (split.spec.response &&
+          (process.env.BLAMEJS_VALIDATE_RESPONSES === "throw" ||
+           process.env.BLAMEJS_VALIDATE_RESPONSES === "warn" ||
+           split.spec.validateResponse)) {
+        handlers = [_makeResponseValidator(split.spec)].concat(handlers);
+      }
+    }
+    this.routes.push(Object.assign(
+      { method: method, handlers: handlers, spec: split.spec || null },
+      compilePattern(pattern)
+    ));
+  }
+
+  get(pattern, ...args) {
+    this._registerRoute("GET", pattern, args);
+  }
+
+  post(pattern, ...args) {
+    this._registerRoute("POST", pattern, args);
+  }
+
+  put(pattern, ...args) {
+    this._registerRoute("PUT", pattern, args);
   }
 
-  post(pattern, ...handlers) {
-    this.routes.push({ method: "POST", ...compilePattern(pattern), handlers });
+  patch(pattern, ...args) {
+    this._registerRoute("PATCH", pattern, args);
   }
 
-  put(pattern, ...handlers) {
-    this.routes.push({ method: "PUT", ...compilePattern(pattern), handlers });
+  delete(pattern, ...args) {
+    this._registerRoute("DELETE", pattern, args);
   }
 
-  patch(pattern, ...handlers) {
-    this.routes.push({ method: "PATCH", ...compilePattern(pattern), handlers });
+  // Operator-facing introspection — returns a copy of the route table
+  // with each entry's method, pattern, description, and (when provided)
+  // operator-supplied jsonSchema bodies for OpenAPI publication.
+  inspectRoutes() {
+    return this.routes
+      .filter(function (r) { return typeof r.method === "string"; })
+      .map(function (r) {
+        return {
+          method:      r.method,
+          pattern:     r.pattern,
+          description: r.spec ? r.spec.description || null : null,
+          spec:        r.spec ? {
+            hasBodySchema:   !!r.spec.body,
+            hasQuerySchema:  !!r.spec.query,
+            hasParamsSchema: !!r.spec.params,
+            hasResponseSchema: !!r.spec.response,
+            bodyJsonSchema:     r.spec.bodyJsonSchema     || null,
+            queryJsonSchema:    r.spec.queryJsonSchema    || null,
+            paramsJsonSchema:   r.spec.paramsJsonSchema   || null,
+            responseJsonSchema: r.spec.responseJsonSchema || null,
+            tags:        Array.isArray(r.spec.tags) ? r.spec.tags.slice() : [],
+            summary:     r.spec.summary || null,
+          } : null,
+        };
+      });
   }
 
-  delete(pattern, ...handlers) {
-    this.routes.push({ method: "DELETE", ...compilePattern(pattern), handlers });
+  // openapi(opts?) → minimal Swagger 3.0 document covering every
+  // schema-spec'd route. Body / query / params show up as parameter
+  // entries when the operator supplies bodyJsonSchema / etc. (a
+  // safeSchema → JSON Schema converter is its own primitive — operators
+  // who want full schema bodies in the OpenAPI doc supply the JSON
+  // Schema alongside the safeSchema today).
+  openapi(opts) {
+    opts = opts || {};
+    var info = opts.info || { title: "blamejs app", version: "0.0.0" };
+    var paths = {};
+    var routes = this.inspectRoutes();
+    for (var i = 0; i < routes.length; i++) {
+      var r = routes[i];
+      var openapiPath = r.pattern.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
+      if (!paths[openapiPath]) paths[openapiPath] = {};
+      var op = {
+        summary:     r.spec ? r.spec.summary || r.description || (r.method + " " + r.pattern) :
+                              (r.method + " " + r.pattern),
+        description: r.description || null,
+      };
+      if (r.spec) {
+        op.tags = r.spec.tags;
+        var params = [];
+        // Path params from pattern
+        var pathParams = (r.pattern.match(/:[a-zA-Z0-9_]+/g) || [])
+          .map(function (s) { return s.slice(1); });
+        for (var pp = 0; pp < pathParams.length; pp++) {
+          params.push({ name: pathParams[pp], in: "path", required: true,
+                        schema: { type: "string" } });
+        }
+        if (r.spec.queryJsonSchema && r.spec.queryJsonSchema.properties) {
+          var qprops = r.spec.queryJsonSchema.properties;
+          var qreq   = r.spec.queryJsonSchema.required || [];
+          var qkeys  = Object.keys(qprops);
+          for (var qi = 0; qi < qkeys.length; qi++) {
+            params.push({ name: qkeys[qi], in: "query",
+                          required: qreq.indexOf(qkeys[qi]) !== -1,
+                          schema: qprops[qkeys[qi]] });
+          }
+        }
+        if (params.length > 0) op.parameters = params;
+        if (r.spec.bodyJsonSchema) {
+          op.requestBody = {
+            required: true,
+            content: { "application/json": { schema: r.spec.bodyJsonSchema } },
+          };
+        } else if (r.spec.hasBodySchema) {
+          // Operator validates via safeSchema but didn't supply JSON Schema.
+          op["x-blamejs-body-validation"] = "safe-schema (json schema not provided)";
+        }
+        if (r.spec.responseJsonSchema) {
+          op.responses = {
+            "200": {
+              description: "OK",
+              content: { "application/json": { schema: r.spec.responseJsonSchema } },
+            },
+          };
+        }
+      }
+      paths[openapiPath][r.method.toLowerCase()] = op;
+    }
+    return {
+      openapi: "3.0.3",
+      info:    info,
+      paths:   paths,
+    };
   }
 
   // ---- WebSocket route registration ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",