@blamejs/core 0.4.19 → 0.4.20

package/CHANGELOG.md

@@ -8,6 +8,7 @@ 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

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/package.json

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