tina4-nodejs 3.13.31 → 3.13.33

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.31)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.33)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.31",
+  "version": "3.13.33",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/cache.ts

@@ -1269,6 +1269,9 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
     if (cached && typeof cached === "object" && typeof cached.body === "string") {
       // Cache HIT — serve from the (possibly distributed) backend.
       res.header("X-Cache", "HIT");
+      // X-Cache-TTL advertises the configured cache lifetime in seconds
+      // (parity with Python/PHP/Ruby, which set it alongside X-Cache).
+      res.header("X-Cache-TTL", String(ttl));
       res.header("Content-Type", cached.contentType);
       res(cached.body, cached.statusCode, cached.contentType);
       return;
@@ -1297,6 +1300,7 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
       }
 
       res.header("X-Cache", "MISS");
+      res.header("X-Cache-TTL", String(ttl));
       return originalEnd(chunk, ...args);
     } as any;
 

package/packages/core/src/index.ts

@@ -6,6 +6,7 @@ export type {
   RouteMeta,
   Tina4Config,
   Middleware,
+  MiddlewareSpec,
   UploadedFile,
   CookieOptions,
   WebSocketRouteHandler,
@@ -14,7 +15,7 @@ export type {
 
 export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
-export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares, isTrailingSlashRedirectEnabled } from "./router.js";
+export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
 export { discoverRoutes } from "./routeDiscovery.js";
@@ -95,7 +96,7 @@ export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateC
 export type { AiTool } from "./ai.js";
 export type { ImapMessage, ImapFullMessage } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
-export { RabbitMQBackend } from "./queueBackends/rabbitmqBackend.js";
+export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";
 export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";
 export { KafkaBackend } from "./queueBackends/kafkaBackend.js";
 export type { KafkaConfig } from "./queueBackends/kafkaBackend.js";

package/packages/core/src/job.ts

@@ -48,12 +48,17 @@ export function createJob(data: JobData, queue: JobQueueBridge): QueueJob {
   const job: QueueJob = {
     ...data,
     complete() {
+      // Terminal — the job was already removed from the queue on pop().
       job.status = "completed";
     },
     fail(reason = "") {
+      // Record a failed attempt. `attempts` is incremented exactly once, inside
+      // the backend's failJob() — NOT here — so a persistently-failing job runs
+      // exactly maxRetries times before it is dead-lettered. The backend decides
+      // whether to re-enqueue (attempts < maxRetries) or dead-letter
+      // (attempts >= maxRetries).
       job.status = "failed";
       job.error = reason;
-      job.attempts = (job.attempts || 0) + 1;
       queue._failJob(job.topic, job, reason, queue.getMaxRetries());
     },
     reject(reason = "") {

package/packages/core/src/queue.ts

@@ -45,6 +45,12 @@ export interface QueueConfig {
   path?: string;
   topic?: string;
   maxRetries?: number;
+  /**
+   * Seconds to delay a failed job's automatic re-enqueue. 0 (the default)
+   * means retry immediately — the next pop()/consume() iteration picks it up
+   * straight away. Parity with Python's retry_backoff.
+   */
+  retryBackoff?: number;
 }
 
 export interface ProcessOptions {
@@ -75,6 +81,7 @@ export class Queue {
   private basePath: string;
   private topic: string;
   private _maxRetries: number;
+  private _retryBackoff: number;
   private externalBackend: QueueBackendInterface | null = null;
   private liteBackend!: LiteBackend;
 
@@ -104,6 +111,7 @@ export class Queue {
       ?? "data/queue";
     this.topic = resolvedConfig.topic ?? "default";
     this._maxRetries = resolvedConfig.maxRetries ?? 3;
+    this._retryBackoff = resolvedConfig.retryBackoff ?? 0;
     this.liteBackend = new LiteBackend(this.basePath);
 
     // Initialize external backends
@@ -234,10 +242,12 @@ export class Queue {
   }
 
   /**
-   * Get all failed jobs for this queue's topic.
+   * Get jobs that failed at least once but are still being retried
+   * (0 < attempts < maxRetries). These live in the pending queue under the
+   * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
    */
   failed(): QueueJob[] {
-    return this.liteBackend.failed(this.topic);
+    return this.liteBackend.failed(this.topic, this._maxRetries);
   }
 
   /**
@@ -396,11 +406,17 @@ export class Queue {
     return this._maxRetries;
   }
 
+  getRetryBackoff(): number {
+    return this._retryBackoff;
+  }
+
   /**
-   * Move a job to the failed directory.
+   * Record a failed attempt for a job. The backend increments `attempts`
+   * exactly once and decides whether to re-enqueue (attempts < maxRetries,
+   * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
    */
   _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
-    this.liteBackend.failJob(queue, job, error, maxRetries);
+    this.liteBackend.failJob(queue, job, error, maxRetries, this._retryBackoff);
   }
 
   /**

package/packages/core/src/queueBackends/kafkaBackend.ts

@@ -5,8 +5,12 @@
  * for message storage and delivery.
  *
  * Configure via environment variables:
- *   TINA4_KAFKA_BROKERS   (default: "localhost:9092")
+ *   TINA4_QUEUE_URL       — broker list (strips a leading kafka:// if present)
+ *   TINA4_KAFKA_BROKERS   (override; default: "localhost:9092")
  *   TINA4_KAFKA_GROUP_ID  (default: "tina4_consumer_group")
+ *
+ * Precedence for brokers: specific TINA4_KAFKA_BROKERS var (if set)
+ *   > value derived from TINA4_QUEUE_URL > existing default.
  */
 import net from "node:net";
 import { execFileSync } from "node:child_process";
@@ -54,10 +58,25 @@ export class KafkaBackend implements QueueBackend {
   private groupId: string;
 
   constructor(config?: KafkaConfig) {
-    this.brokers = config?.brokers ?? process.env.TINA4_KAFKA_BROKERS ?? "localhost:9092";
+    // Base layer: brokers derived from TINA4_QUEUE_URL (strip a leading
+    // kafka:// scheme if present; otherwise use the value as-is, e.g.
+    // "localhost:9092").
+    const url = process.env.TINA4_QUEUE_URL;
+    const fromUrl = url ? url.replace(/^kafka:\/\//, "") : undefined;
+
+    // Precedence: explicit config arg > specific TINA4_KAFKA_BROKERS var
+    // > value from TINA4_QUEUE_URL > existing default.
+    this.brokers = config?.brokers ?? process.env.TINA4_KAFKA_BROKERS ?? fromUrl ?? "localhost:9092";
     this.groupId = config?.groupId ?? process.env.TINA4_KAFKA_GROUP_ID ?? "tina4_consumer_group";
   }
 
+  /**
+   * Resolved connection config — exposed for testing/introspection.
+   */
+  getConfig(): Required<KafkaConfig> {
+    return { brokers: this.brokers, groupId: this.groupId };
+  }
+
   /**
    * Parse broker string into host:port.
    */

package/packages/core/src/queueBackends/liteBackend.ts

@@ -1,6 +1,19 @@
 /**
  * LiteBackend — file-based queue backend for Tina4 Queue.
  * Stores jobs as JSON files on disk. Zero dependencies.
+ *
+ * Dequeue policy (parity with Python master): the highest-priority AVAILABLE
+ * job is returned first; ties are broken oldest-first by createdAt. The file
+ * *name* is no longer the ordering key — the stored `priority` and `createdAt`
+ * fields are. Delayed jobs (delayUntil in the future) are skipped until due.
+ *
+ * Failure lifecycle (parity with Python master): job.fail() records one failed
+ * attempt — `attempts` is incremented exactly once, here in failJob(). If the
+ * job still has retries left (attempts < maxRetries) it is automatically
+ * re-enqueued to the pending queue (immediately, or after retryBackoff seconds
+ * if configured) so the next pop()/consume() picks it up again. Once it has
+ * been attempted maxRetries times (attempts >= maxRetries) it is moved to the
+ * dead-letter (failed/) directory, where deadLetters() returns it.
  */
 import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -28,11 +41,15 @@ export class LiteBackend {
     return dir;
   }
 
+  private nextPrefix(): string {
+    this.seq++;
+    return `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+  }
+
   push(queue: string, payload: unknown, delay?: number, priority?: number): string {
     const dir = this.ensureDir(queue);
     const id = randomUUID();
     const now = new Date().toISOString();
-    this.seq++;
 
     const job = {
       id,
@@ -42,48 +59,74 @@ export class LiteBackend {
       attempts: 0,
       delayUntil: delay ? new Date(Date.now() + delay * 1000).toISOString() : null,
       priority: priority ?? 0,
+      topic: queue,
+      error: undefined as string | undefined,
     };
 
-    const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+    const prefix = this.nextPrefix();
     writeFileSync(join(dir, `${prefix}_${id}.queue-data`), JSON.stringify(job, null, 2));
     return id;
   }
 
-  pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
+  /**
+   * Return [filename, jobData] for every pending, non-delayed job, ordered by
+   * the dequeue policy: highest priority first, ties broken oldest-first by
+   * createdAt. createdAt is an ISO-8601 string, so lexicographic comparison ==
+   * chronological order.
+   */
+  private availableCandidates(queue: string, now: string): Array<[string, any]> {
     const dir = this.ensureDir(queue);
 
-    let files: string[];
+    let filenames: string[];
     try {
-      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
+      filenames = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
     } catch {
-      return null;
+      return [];
     }
 
-    const now = new Date().toISOString();
-
-    for (const file of files) {
-      const filePath = join(dir, file);
-      let job: QueueJob;
+    const candidates: Array<[string, any]> = [];
+    for (const filename of filenames) {
+      const filePath = join(dir, filename);
+      let job: any;
       try {
         job = JSON.parse(readFileSync(filePath, "utf-8"));
       } catch {
         continue;
       }
-
       if (job.status !== "pending") continue;
-      if (job.delayUntil && job.delayUntil > now) continue;
+      if (job.delayUntil && job.delayUntil > now) continue; // still delayed
+      candidates.push([filename, job]);
+    }
 
-      job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
-      writeFileSync(filePath, JSON.stringify(job, null, 2));
+    // priority DESC, then createdAt ASC (oldest first).
+    candidates.sort((a, b) => {
+      const pa = Number(a[1].priority ?? 0) || 0;
+      const pb = Number(b[1].priority ?? 0) || 0;
+      if (pb !== pa) return pb - pa;
+      const ca = (a[1].createdAt ?? "") as string;
+      const cb = (b[1].createdAt ?? "") as string;
+      return ca < cb ? -1 : ca > cb ? 1 : 0;
+    });
+
+    return candidates;
+  }
+
+  pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
+    const dir = this.ensureDir(queue);
+    const now = new Date().toISOString();
 
+    for (const [filename, job] of this.availableCandidates(queue, now)) {
+      const filePath = join(dir, filename);
+      // Claim the job by deleting the file.
       try {
         unlinkSync(filePath);
       } catch {
-        // Already consumed by another worker
+        continue; // Already consumed by another worker
       }
 
+      job.status = "reserved";
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
       return createJob(job as any, bridge);
     }
 
@@ -92,71 +135,52 @@ export class LiteBackend {
 
   popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
     const dir = this.ensureDir(queue);
-
-    let files: string[];
-    try {
-      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
-    } catch {
-      return [];
-    }
-
     const now = new Date().toISOString();
     const results: QueueJob[] = [];
 
-    for (const file of files) {
+    for (const [filename, job] of this.availableCandidates(queue, now)) {
       if (results.length >= count) break;
-      const filePath = join(dir, file);
-      let job: QueueJob;
+      const filePath = join(dir, filename);
       try {
-        job = JSON.parse(readFileSync(filePath, "utf-8"));
+        unlinkSync(filePath);
       } catch {
-        continue;
+        continue; // Already consumed by another worker
       }
 
-      if (job.status !== "pending") continue;
-      if (job.delayUntil && job.delayUntil > now) continue;
-
       job.status = "reserved";
       job.topic = queue;
       job.priority = job.priority ?? 0;
-      writeFileSync(filePath, JSON.stringify(job, null, 2));
-
-      try {
-        unlinkSync(filePath);
-      } catch {
-        // Already consumed by another worker
-      }
-
       results.push(createJob(job as any, bridge));
     }
 
     return results;
   }
 
+  // Status aliases that live in the failed/ directory (dead-lettered jobs)
+  // rather than as pending files in the queue directory.
+  private static readonly DEAD_STATES = ["failed", "dead", "dead_letter"];
+
   size(queue: string, status: string = "pending"): number {
-    if (status === "failed") {
-      const failedDir = this.ensureFailedDir(queue);
-      let files: string[];
-      try {
-        files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
-      } catch {
-        return 0;
-      }
-      return files.length;
-    }
+    const isDead = LiteBackend.DEAD_STATES.includes(status);
+    const scanDir = isDead ? this.ensureFailedDir(queue) : this.ensureDir(queue);
 
-    const dir = this.ensureDir(queue);
     let files: string[];
     try {
-      files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+      files = readdirSync(scanDir).filter(f => f.endsWith(".queue-data"));
     } catch {
       return 0;
     }
 
+    if (isDead) {
+      // Every file in failed/ is a dead-letter; count them all regardless of
+      // the exact stored status string.
+      return files.length;
+    }
+
     let count = 0;
     for (const file of files) {
       try {
-        const job = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+        const job = JSON.parse(readFileSync(join(scanDir, file), "utf-8"));
         if (job.status === status) count++;
       } catch {
         // skip corrupt files
@@ -178,7 +202,7 @@ export class LiteBackend {
       // directory might not exist
     }
 
-    // Also clear failed jobs
+    // Also clear dead-letter jobs.
     const failedDir = join(dir, "failed");
     try {
       if (existsSync(failedDir)) {
@@ -194,16 +218,27 @@ export class LiteBackend {
     return count;
   }
 
-  failed(queue: string): QueueJob[] {
-    const failedDir = this.ensureFailedDir(queue);
+  /**
+   * Jobs that have failed at least once but are still being retried.
+   *
+   * Under the auto-retry lifecycle a failed-but-retryable job lives in the
+   * pending queue (not the dead-letter dir), so this scans the queue dir for
+   * pending jobs with attempts > 0 that have not yet exhausted their retries.
+   * Dead-lettered jobs are returned by deadLetters().
+   */
+  failed(queue: string, maxRetries: number = 3): QueueJob[] {
+    const dir = this.ensureDir(queue);
     const results: QueueJob[] = [];
 
     try {
-      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data")).sort();
+      const files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
       for (const file of files) {
         try {
-          const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
-          results.push(job);
+          const job: QueueJob = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+          const attempts = job.attempts || 0;
+          if (attempts > 0 && attempts < maxRetries) {
+            results.push(job);
+          }
         } catch {
           // skip corrupt files
         }
@@ -215,6 +250,13 @@ export class LiteBackend {
     return results;
   }
 
+  /**
+   * Revive a specific dead-letter job by id back to the pending queue.
+   *
+   * Manual override (Queue.retry(jobId) / job.retry()) — always revives a
+   * dead-letter regardless of attempt count. Returns false only if no
+   * dead-letter with that id exists.
+   */
   retry(queue: string, jobId: string, delaySeconds?: number): boolean {
     try {
       const queues = readdirSync(this.basePath);
@@ -227,10 +269,10 @@ export class LiteBackend {
           job.status = "pending";
           job.attempts = (job.attempts || 0) + 1;
           job.error = undefined;
+          job.createdAt = new Date().toISOString();
           job.delayUntil = delaySeconds ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null;
 
-          this.seq++;
-          const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+          const prefix = this.nextPrefix();
           const queueDir = join(this.basePath, q);
           writeFileSync(join(queueDir, `${prefix}_${jobId}.queue-data`), JSON.stringify(job, null, 2));
           unlinkSync(filePath);
@@ -270,38 +312,19 @@ export class LiteBackend {
 
   purge(queue: string, status: string, maxRetries: number = 3): number {
     let count = 0;
+    const isDead = LiteBackend.DEAD_STATES.includes(status);
 
-    if (status === "dead") {
-      const failedDir = this.ensureFailedDir(queue);
-      try {
-        const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
-        for (const file of files) {
-          try {
-            const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
-            if ((job.attempts || 0) >= maxRetries) {
-              unlinkSync(join(failedDir, file));
-              count++;
-            }
-          } catch {
-            // skip corrupt files
-          }
-        }
-      } catch {
-        // directory might not exist
-      }
-    } else if (status === "failed") {
+    if (isDead) {
+      // Every file in failed/ is a dead-letter — purge them all.
       const failedDir = this.ensureFailedDir(queue);
       try {
         const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
         for (const file of files) {
           try {
-            const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
-            if ((job.attempts || 0) < maxRetries) {
-              unlinkSync(join(failedDir, file));
-              count++;
-            }
+            unlinkSync(join(failedDir, file));
+            count++;
           } catch {
-            // skip corrupt files
+            // already removed
           }
         }
       } catch {
@@ -330,6 +353,11 @@ export class LiteBackend {
     return count;
   }
 
+  /**
+   * Re-queue dead-letter jobs that are under the (possibly raised) limit back
+   * to pending. Mirrors Python retry_failed(): a job dead-lettered at the
+   * original maxRetries needs a raised limit to qualify again.
+   */
   retryFailed(queue: string, maxRetries: number = 3): number {
     const failedDir = this.ensureFailedDir(queue);
     const queueDir = this.ensureDir(queue);
@@ -348,9 +376,10 @@ export class LiteBackend {
 
           job.status = "pending";
           job.error = undefined;
+          job.createdAt = new Date().toISOString();
+          job.delayUntil = null;
 
-          this.seq++;
-          const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+          const prefix = this.nextPrefix();
           writeFileSync(join(queueDir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
           unlinkSync(filePath);
           count++;
@@ -376,6 +405,7 @@ export class LiteBackend {
     }
 
     for (const file of files) {
+      if (!file.includes(id)) continue;
       const filePath = join(dir, file);
       let job: QueueJob;
       try {
@@ -394,24 +424,79 @@ export class LiteBackend {
     return null;
   }
 
-  failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
+  /**
+   * Write the job back to the pending queue (queue dir).
+   *
+   * Re-enqueued jobs get a fresh createdAt so that within a priority tier they
+   * sort behind jobs that have not yet been attempted. `attempts` already
+   * reflects the latest failure count. The job carries its prior error.
+   */
+  private requeue(queue: string, job: QueueJob, delaySeconds: number = 0, error?: string): void {
+    const dir = this.ensureDir(queue);
+    const jobData = {
+      id: job.id,
+      payload: job.payload,
+      status: "pending" as const,
+      createdAt: new Date().toISOString(),
+      attempts: job.attempts ?? 0,
+      delayUntil: delaySeconds > 0 ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null,
+      priority: job.priority ?? 0,
+      topic: job.topic,
+      error,
+    };
+    const prefix = this.nextPrefix();
+    writeFileSync(join(dir, `${prefix}_${job.id}.queue-data`), JSON.stringify(jobData, null, 2));
+  }
+
+  /**
+   * Move the job to the dead-letter (failed/) directory. Terminal until a
+   * manual retryFailed()/retry() revives it.
+   */
+  private deadLetter(queue: string, job: QueueJob, error?: string): void {
     const failedDir = this.ensureFailedDir(queue);
-    job.status = "failed";
+    const jobData = {
+      id: job.id,
+      payload: job.payload,
+      status: "dead" as const,
+      createdAt: job.createdAt,
+      attempts: job.attempts ?? 0,
+      delayUntil: null,
+      priority: job.priority ?? 0,
+      topic: job.topic,
+      error,
+      failedAt: new Date().toISOString(),
+    };
+    writeFileSync(join(failedDir, `${job.id}.queue-data`), JSON.stringify(jobData, null, 2));
+  }
+
+  /**
+   * Record a failed attempt.
+   *
+   * Increments `attempts` exactly once (the increment lives here, NOT in
+   * job.ts — see the double-increment fix). If the job still has retries left
+   * (attempts < maxRetries) it is automatically re-enqueued to pending, after
+   * an optional retryBackoff delay. Once it has been attempted maxRetries times
+   * (attempts >= maxRetries) it is moved to the dead-letter store.
+   */
+  failJob(queue: string, job: QueueJob, error: string, maxRetries: number, retryBackoff: number = 0): void {
     job.attempts = (job.attempts || 0) + 1;
     job.error = error;
-
-    writeFileSync(join(failedDir, `${job.id}.queue-data`), JSON.stringify(job, null, 2));
+    if (job.attempts < maxRetries) {
+      this.requeue(queue, job, retryBackoff, error);
+    } else {
+      this.deadLetter(queue, job, error);
+    }
   }
 
+  /**
+   * Explicit re-queue requested by the caller (job.retry()).
+   *
+   * Always re-enqueues regardless of the retry limit — manual override,
+   * distinct from the automatic failJob() path.
+   */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
-    const dir = this.ensureDir(queue);
-    job.status = "pending";
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
-    job.delayUntil = delaySeconds ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null;
-
-    this.seq++;
-    const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
-    writeFileSync(join(dir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
+    this.requeue(queue, job, delaySeconds ?? 0, undefined);
   }
 }

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -5,13 +5,18 @@
  * for message storage and delivery. Atomic pop via findOneAndUpdate.
  *
  * Configure via environment variables:
+ *   TINA4_QUEUE_URL        — connection URI (mongodb://...)
+ *   TINA4_MONGO_URI        (override; wins over TINA4_QUEUE_URL)
  *   TINA4_MONGO_HOST       (default: "localhost")
  *   TINA4_MONGO_PORT       (default: 27017)
- *   TINA4_MONGO_URI        (overrides host/port/username/password)
  *   TINA4_MONGO_USERNAME   (optional)
  *   TINA4_MONGO_PASSWORD   (optional)
  *   TINA4_MONGO_DB         (default: "tina4")
  *   TINA4_MONGO_COLLECTION (default: "tina4_queue")
+ *
+ * Precedence for the connection URI: explicit config.uri
+ *   > TINA4_MONGO_URI > TINA4_QUEUE_URL > a URI built from the
+ *   TINA4_MONGO_HOST/PORT/USERNAME/PASSWORD field vars (existing defaults).
  */
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
@@ -63,9 +68,11 @@ export class MongoBackend implements QueueBackend {
     this.database = config?.database ?? process.env.TINA4_MONGO_DB ?? "tina4";
     this.collection = config?.collection ?? process.env.TINA4_MONGO_COLLECTION ?? "tina4_queue";
 
-    // URI overrides individual host/port/auth settings
-    if (config?.uri ?? process.env.TINA4_MONGO_URI) {
-      this.uri = config?.uri ?? process.env.TINA4_MONGO_URI!;
+    // Connection URI precedence: explicit config.uri > TINA4_MONGO_URI
+    // > TINA4_QUEUE_URL > a URI built from the host/port/auth field vars.
+    const explicitUri = config?.uri ?? process.env.TINA4_MONGO_URI ?? process.env.TINA4_QUEUE_URL;
+    if (explicitUri) {
+      this.uri = explicitUri;
     } else {
       const auth = this.username
         ? `${encodeURIComponent(this.username)}:${encodeURIComponent(this.password)}@`
@@ -74,6 +81,13 @@ export class MongoBackend implements QueueBackend {
     }
   }
 
+  /**
+   * Resolved connection config — exposed for testing/introspection.
+   */
+  getConfig(): { uri: string; database: string; collection: string } {
+    return { uri: this.uri, database: this.database, collection: this.collection };
+  }
+
   /**
    * Execute a MongoDB operation synchronously via a child process.
    */

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -5,11 +5,15 @@
  * for message storage and delivery.
  *
  * Configure via environment variables:
- *   TINA4_RABBITMQ_HOST     (default: "localhost")
- *   TINA4_RABBITMQ_PORT     (default: 5672)
- *   TINA4_RABBITMQ_USERNAME (default: "guest")
- *   TINA4_RABBITMQ_PASSWORD (default: "guest")
- *   TINA4_RABBITMQ_VHOST    (default: "/")
+ *   TINA4_QUEUE_URL         — AMQP URL (amqp://[user:pass@]host:port[/vhost])
+ *   TINA4_RABBITMQ_HOST     (override; default: "localhost")
+ *   TINA4_RABBITMQ_PORT     (override; default: 5672)
+ *   TINA4_RABBITMQ_USERNAME (override; default: "guest")
+ *   TINA4_RABBITMQ_PASSWORD (override; default: "guest")
+ *   TINA4_RABBITMQ_VHOST    (override; default: "/")
+ *
+ * Precedence per field: specific TINA4_RABBITMQ_* var (if set)
+ *   > value derived from TINA4_QUEUE_URL > existing default.
  */
 import net from "node:net";
 import { execFileSync } from "node:child_process";
@@ -26,6 +30,51 @@ export interface RabbitMQConfig {
   vhost?: string;
 }
 
+/**
+ * Parse an AMQP URL (amqp://[user:pass@]host[:port][/vhost]) into a partial
+ * RabbitMQConfig. Mirrors the Python/PHP/Ruby `parse_amqp_url` semantics:
+ * strips a leading amqp:// or amqps:// scheme, splits optional credentials,
+ * and prepends a leading "/" to the vhost when missing. Only fields present
+ * in the URL are populated.
+ */
+export function parseAmqpUrl(url: string): RabbitMQConfig {
+  const config: RabbitMQConfig = {};
+  let rest = url.replace(/^amqps:\/\//, "").replace(/^amqp:\/\//, "");
+
+  const atIndex = rest.indexOf("@");
+  if (atIndex !== -1) {
+    const creds = rest.slice(0, atIndex);
+    rest = rest.slice(atIndex + 1);
+    const colonIndex = creds.indexOf(":");
+    if (colonIndex !== -1) {
+      config.username = creds.slice(0, colonIndex);
+      config.password = creds.slice(colonIndex + 1);
+    } else {
+      config.username = creds;
+    }
+  }
+
+  let hostport = rest;
+  const slashIndex = rest.indexOf("/");
+  if (slashIndex !== -1) {
+    hostport = rest.slice(0, slashIndex);
+    const vhost = rest.slice(slashIndex + 1);
+    if (vhost) {
+      config.vhost = vhost.startsWith("/") ? vhost : "/" + vhost;
+    }
+  }
+
+  const portColon = hostport.indexOf(":");
+  if (portColon !== -1) {
+    config.host = hostport.slice(0, portColon);
+    config.port = parseInt(hostport.slice(portColon + 1), 10);
+  } else if (hostport) {
+    config.host = hostport;
+  }
+
+  return config;
+}
+
 export interface QueueBackend {
   push(queue: string, payload: unknown, delay?: number): string;
   pop(queue: string): QueueJob | null;
@@ -133,12 +182,32 @@ export class RabbitMQBackend implements QueueBackend {
   private vhost: string;
 
   constructor(config?: RabbitMQConfig) {
-    this.host = config?.host ?? process.env.TINA4_RABBITMQ_HOST ?? "localhost";
+    // Base layer: values derived from TINA4_QUEUE_URL (parsed as an AMQP URL).
+    const url = process.env.TINA4_QUEUE_URL;
+    const fromUrl = url ? parseAmqpUrl(url) : {};
+
+    // Precedence per field: explicit config arg > specific TINA4_RABBITMQ_* var
+    // > value from TINA4_QUEUE_URL > existing default.
+    this.host = config?.host ?? process.env.TINA4_RABBITMQ_HOST ?? fromUrl.host ?? "localhost";
     this.port = config?.port
-      ?? (process.env.TINA4_RABBITMQ_PORT ? parseInt(process.env.TINA4_RABBITMQ_PORT, 10) : 5672);
-    this.username = config?.username ?? process.env.TINA4_RABBITMQ_USERNAME ?? "guest";
-    this.password = config?.password ?? process.env.TINA4_RABBITMQ_PASSWORD ?? "guest";
-    this.vhost = config?.vhost ?? process.env.TINA4_RABBITMQ_VHOST ?? "/";
+      ?? (process.env.TINA4_RABBITMQ_PORT ? parseInt(process.env.TINA4_RABBITMQ_PORT, 10) : undefined)
+      ?? fromUrl.port ?? 5672;
+    this.username = config?.username ?? process.env.TINA4_RABBITMQ_USERNAME ?? fromUrl.username ?? "guest";
+    this.password = config?.password ?? process.env.TINA4_RABBITMQ_PASSWORD ?? fromUrl.password ?? "guest";
+    this.vhost = config?.vhost ?? process.env.TINA4_RABBITMQ_VHOST ?? fromUrl.vhost ?? "/";
+  }
+
+  /**
+   * Resolved connection config — exposed for testing/introspection.
+   */
+  getConfig(): Required<RabbitMQConfig> {
+    return {
+      host: this.host,
+      port: this.port,
+      username: this.username,
+      password: this.password,
+      vhost: this.vhost,
+    };
   }
 
   /**

package/packages/core/src/router.ts

@@ -1,4 +1,4 @@
-import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
+import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, MiddlewareSpec, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
 import { isTruthy } from "./dotenv.js";
 
 /**
@@ -43,7 +43,7 @@ interface MatchResult {
   params: Record<string, string | number>;
   pattern: string;
   meta?: RouteMeta;
-  middlewares?: Middleware[];
+  middlewares?: MiddlewareSpec[];
   template?: string;
   secure?: boolean;
   cached?: boolean;
@@ -58,7 +58,7 @@ interface CompiledRoute {
   handler: RouteHandler;
   meta?: RouteMeta;
   filePath?: string;
-  middlewares?: Middleware[];
+  middlewares?: MiddlewareSpec[];
   secure?: boolean;
   cached?: boolean;
   noAuth?: boolean;
@@ -94,8 +94,11 @@ export class RouteRef {
     return this;
   }
 
-  /** Append middleware class(es) to this route. */
-  middleware(...middlewareClasses: Middleware[]): this {
+  /**
+   * Append middleware to this route. Accepts middleware functions and/or
+   * string specs (e.g. `"ResponseCache:300"`), resolved when the route runs.
+   */
+  middleware(...middlewareClasses: MiddlewareSpec[]): this {
     this.route.middlewares = [...(this.route.middlewares ?? []), ...middlewareClasses];
     return this;
   }
@@ -187,35 +190,35 @@ export class Router {
   /**
    * Register a GET route programmatically.
    */
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "GET", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a POST route programmatically.
    */
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "POST", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PUT route programmatically.
    */
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "PUT", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PATCH route programmatically.
    */
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "PATCH", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a DELETE route programmatically.
    */
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
   }
 
@@ -227,7 +230,7 @@ export class Router {
    * logic, custom validator headers without the cost of building the body.
    * The framework still strips the response body for you on the way out.
    */
-  head(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  head(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "HEAD", pattern: path, handler, middlewares, meta });
   }
 
@@ -237,14 +240,14 @@ export class Router {
    * registered for the path and returning 204 (RFC 9110 §9.3.7). Use
    * this to take over that behaviour.
    */
-  options(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  options(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "OPTIONS", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a route that matches ANY HTTP method.
    */
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
       lastRef = this.addRoute({ method, pattern: path, handler, middlewares, meta });
@@ -255,7 +258,7 @@ export class Router {
   /**
    * Create a route group with a shared prefix and optional middlewares.
    */
-  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: Middleware[]): void {
+  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void {
     const group = new RouteGroup(this, prefix, middlewares);
     callback(group);
   }
@@ -447,7 +450,7 @@ export class Router {
    * Register a route for a specific HTTP method.
    * Core registration method — all convenience methods delegate here.
    */
-  static add(method: string, path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static add(method: string, path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     const m = method.toUpperCase();
     if (m === "ANY") {
       return defaultRouter.any(path, handler, middleware, swaggerMeta);
@@ -458,42 +461,42 @@ export class Router {
   /**
    * Register a GET route on the default global router.
    */
-  static get(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static get(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.get(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a POST route on the default global router.
    */
-  static post(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static post(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.post(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PUT route on the default global router.
    */
-  static put(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static put(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.put(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PATCH route on the default global router.
    */
-  static patch(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static patch(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.patch(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a DELETE route on the default global router.
    */
-  static delete(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static delete(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.delete(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a route that matches ANY HTTP method on the default global router.
    */
-  static any(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static any(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.any(path, handler, middleware, swaggerMeta);
   }
 
@@ -507,7 +510,7 @@ export class Router {
   /**
    * Create a route group on the default global router.
    */
-  static group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: Middleware[]): void {
+  static group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void {
     defaultRouter.group(prefix, callback, middlewares);
   }
 
@@ -622,7 +625,7 @@ export class RouteGroup {
     return merged.length > 0 ? merged : undefined;
   }
 
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "GET",
       pattern: this.prefix + path,
@@ -632,7 +635,7 @@ export class RouteGroup {
     });
   }
 
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "POST",
       pattern: this.prefix + path,
@@ -642,7 +645,7 @@ export class RouteGroup {
     });
   }
 
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "PUT",
       pattern: this.prefix + path,
@@ -652,7 +655,7 @@ export class RouteGroup {
     });
   }
 
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "PATCH",
       pattern: this.prefix + path,
@@ -662,7 +665,7 @@ export class RouteGroup {
     });
   }
 
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "DELETE",
       pattern: this.prefix + path,
@@ -672,7 +675,7 @@ export class RouteGroup {
     });
   }
 
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
       lastRef = this.router.addRoute({
@@ -689,7 +692,7 @@ export class RouteGroup {
   /**
    * Nested groups.
    */
-  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: Middleware[]): void {
+  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void {
     const nestedGroup = new RouteGroup(
       this.router,
       this.prefix + prefix,
@@ -699,15 +702,64 @@ export class RouteGroup {
   }
 }
 
+/**
+ * Resolve a string-form middleware spec to a middleware function.
+ *
+ * Forms (parity with Python/PHP/Ruby):
+ *   "ResponseCache"      → responseCache() with the default/env TTL
+ *   "ResponseCache:300"  → responseCache({ ttl: 300 })
+ *
+ * The head before the first ":" names the middleware; any trailing
+ * colon-separated parts are its arguments (numeric parts are parsed as
+ * integers). Unknown names throw so a typo surfaces instead of silently
+ * dropping the middleware. `responseCache` is loaded via a dynamic import so
+ * the router carries no import-time dependency on the cache module.
+ *
+ * Exported so route dispatch (and tests) can turn a spec into a runnable
+ * middleware.
+ */
+export async function resolveStringMiddleware(spec: string): Promise<Middleware> {
+  const colon = spec.indexOf(":");
+  const name = colon >= 0 ? spec.slice(0, colon) : spec;
+  const rawArgs = colon >= 0 ? spec.slice(colon + 1).split(":") : [];
+
+  switch (name) {
+    case "ResponseCache": {
+      const { responseCache } = await import("./cache.js");
+      // First arg (if any) is the TTL in seconds.
+      const ttlArg = rawArgs[0];
+      const ttl = ttlArg !== undefined && /^\d+$/.test(ttlArg) ? parseInt(ttlArg, 10) : undefined;
+      return responseCache(ttl !== undefined ? { ttl } : undefined);
+    }
+    default:
+      throw new Error(
+        `Unknown middleware "${name}". Known string middleware: ResponseCache. ` +
+        `For custom middleware, pass the function directly to .middleware(fn).`,
+      );
+  }
+}
+
+/**
+ * Resolve a single route-middleware spec to a middleware function. Functions
+ * pass through unchanged; strings are resolved via resolveStringMiddleware.
+ */
+async function resolveMiddlewareSpec(spec: MiddlewareSpec): Promise<Middleware> {
+  return typeof spec === "string" ? resolveStringMiddleware(spec) : spec;
+}
+
 /**
  * Run per-route middleware chain, then call the handler.
+ *
+ * Accepts middleware functions and/or string specs (e.g. "ResponseCache:300").
+ * Each spec is resolved to a middleware function just before it runs.
  */
 export async function runRouteMiddlewares(
-  middlewares: Middleware[],
+  middlewares: MiddlewareSpec[],
   req: Tina4Request,
   res: Tina4Response,
 ): Promise<boolean> {
-  for (const mw of middlewares) {
+  for (const spec of middlewares) {
+    const mw = await resolveMiddlewareSpec(spec);
     let nextCalled = false;
     await mw(req, res, () => {
       nextCalled = true;
@@ -739,28 +791,28 @@ export const defaultRouter = new Router();
  *     res.json({ id: req.params.id }, 201);
  *   });
  */
-export function get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.get(path, handler, middlewares, meta);
 }
 
-export function post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.post(path, handler, middlewares, meta);
 }
 
-export function put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.put(path, handler, middlewares, meta);
 }
 
-export function patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.patch(path, handler, middlewares, meta);
 }
 
 // Named "del" to avoid conflict with the "delete" keyword; also exported as "delete" alias below.
-export function del(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function del(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.delete(path, handler, middlewares, meta);
 }
 
-export function any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.any(path, handler, middlewares, meta);
 }
 

package/packages/core/src/types.ts

@@ -117,7 +117,8 @@ export interface RouteDefinition {
   handler: RouteHandler;
   filePath?: string;
   meta?: RouteMeta;
-  middlewares?: Middleware[];
+  /** Middleware functions and/or string specs (e.g. "ResponseCache:300"). */
+  middlewares?: MiddlewareSpec[];
   /** Template file to render when handler returns a plain object */
   template?: string;
   /** Whether this route requires bearer-token authentication */
@@ -158,6 +159,20 @@ export type Middleware = (
   next: () => void
 ) => void | Promise<void>;
 
+/**
+ * A route middleware entry: either a middleware function, or a string spec
+ * resolved by the router to a built-in middleware.
+ *
+ * String forms (parity with Python/PHP/Ruby):
+ *   "ResponseCache"      → responseCache() with the default/env TTL
+ *   "ResponseCache:300"  → responseCache({ ttl: 300 })
+ *
+ * The router resolves string specs to middleware functions when the route
+ * runs, so callers can register a response-cache middleware without importing
+ * `responseCache`.
+ */
+export type MiddlewareSpec = Middleware | string;
+
 /**
  * Handler for WebSocket routes.
  * connection — object with send/broadcast/close methods and route params.

package/packages/orm/src/cachedDatabase.ts

@@ -317,8 +317,12 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.query(sql, params);
   }
 
-  fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
-    if (this.enabled) {
+  fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): T[] {
+    // `noCache` bypasses the query cache for this one call — no lookup, no
+    // store, run straight against the underlying adapter (mirrors the Python
+    // master's `no_cache`). Counters are left untouched so a bypass read isn't
+    // misreported as a hit or a miss.
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
@@ -333,8 +337,8 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.fetch(sql, params, limit, skip);
   }
 
-  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
-    if (this.enabled) {
+  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): T | null {
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
       const cached = this.cache.get<T | null>(key);
       if (cached !== undefined) {
@@ -417,11 +421,13 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   // ORM read/write path prefer those when present. We mirror them here so the
   // cache sits in front of the async path too. Reads cache; writes flush.
 
-  async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]> {
+  async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): Promise<T[]> {
     const run = async (): Promise<T[]> => (this.adapter as any).fetchAsync
       ? await (this.adapter as any).fetchAsync(sql, params, limit, skip)
       : this.adapter.fetch<T>(sql, params, limit, skip);
-    if (this.enabled) {
+    // `noCache` bypasses both cache layers for this one call — no lookup, no
+    // store, run directly (mirrors the Python master's `no_cache`).
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
       // Persistent distributed backend is AUTHORITATIVE (mirrors Python, where a
       // configured _cache_backend bypasses the in-process dict). This keeps
@@ -448,11 +454,12 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return run();
   }
 
-  async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+  async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): Promise<T | null> {
     const run = async (): Promise<T | null> => (this.adapter as any).fetchOneAsync
       ? await (this.adapter as any).fetchOneAsync(sql, params)
       : this.adapter.fetchOne<T>(sql, params);
-    if (this.enabled) {
+    // `noCache` bypasses both cache layers for this one call (see fetchAsync).
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
       if (this.usesPersistentBackend()) {
         const shared = await this.backendGetOne<T>(key);

package/packages/orm/src/database.ts

@@ -38,11 +38,13 @@ export function stripTrailingSemicolons(sql: string): string {
  * the single chokepoint every public read/write flows through.
  */
 export async function adapterFetch<T = Record<string, unknown>>(
-  adapter: DatabaseAdapter, sql: string, params?: unknown[], limit?: number, skip?: number,
+  adapter: DatabaseAdapter, sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean,
 ): Promise<T[]> {
+  // `noCache` is forwarded to the CachedDatabaseAdapter so a single read can
+  // bypass the query cache; raw adapters ignore the extra trailing arg.
   return (adapter as any).fetchAsync
-    ? await (adapter as any).fetchAsync(sql, params, limit, skip)
-    : adapter.fetch<T>(sql, params, limit, skip);
+    ? await (adapter as any).fetchAsync(sql, params, limit, skip, noCache)
+    : adapter.fetch<T>(sql, params, limit, skip, noCache);
 }
 
 export async function adapterQuery<T = Record<string, unknown>>(
@@ -633,14 +635,16 @@ export class Database {
    * the fallback resolves instantly). This is the breaking change that makes
    * the wrapper work uniformly across every engine.
    */
-  async fetch(sql: string, params?: unknown[], limit?: number, offset?: number): Promise<DatabaseResult> {
+  async fetch(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<DatabaseResult> {
     // v3.13.12: strip trailing `;` before the adapter wraps with COUNT(*)
     // or appends LIMIT/OFFSET. Without this, `"SELECT * FROM t;"` becomes
     // `"SELECT * FROM t; LIMIT 100 OFFSET 0"` — a syntax error.
     sql = stripTrailingSemicolons(sql);
     const adapter = this.getNextAdapter();
     try {
-      const rows = await adapterFetch(adapter, sql, params, limit, offset);
+      // `opts.noCache` bypasses the query cache for this one call — no lookup,
+      // no store, run directly (mirrors the Python master's `no_cache`).
+      const rows = await adapterFetch(adapter, sql, params, limit, offset, opts?.noCache);
       this.lastError = null;
       return new DatabaseResult(rows, undefined, undefined, limit, offset, adapter, sql);
     } catch (e: any) {
@@ -650,13 +654,19 @@ export class Database {
     }
   }
 
-  /** Fetch a single row or null. */
-  async fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+  /**
+   * Fetch a single row or null.
+   *
+   * Pass `{ noCache: true }` as the trailing options object to bypass the
+   * query cache for this one call — no lookup, no store, run directly
+   * (mirrors the Python master's `no_cache`). Default preserves caching.
+   */
+  async fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], opts?: { noCache?: boolean }): Promise<T | null> {
     sql = stripTrailingSemicolons(sql);
     const adapter = this.getNextAdapter();
     return (adapter as any).fetchOneAsync
-      ? await (adapter as any).fetchOneAsync<T>(sql, params)
-      : adapter.fetchOne<T>(sql, params);
+      ? await (adapter as any).fetchOneAsync<T>(sql, params, opts?.noCache)
+      : adapter.fetchOne<T>(sql, params, opts?.noCache);
   }
 
   /**
@@ -671,9 +681,14 @@ export class Database {
    *
    * Returns `[]` (not `null`) when no rows match. Cross-framework parity
    * with Python `db.fetch_all()`, PHP `$db->fetchAll()`, and Ruby `db.fetch_all`.
+   *
+   * Pass `{ noCache: true }` as the trailing options object to bypass the
+   * query cache for this one call — no lookup, no store, run directly
+   * (mirrors the Python master's `no_cache`). The options object is a
+   * SEPARATE trailing argument, never the params array.
    */
-  async fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]> {
-    return (await this.fetch(sql, params, limit, offset)).records as T[];
+  async fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<T[]> {
+    return (await this.fetch(sql, params, limit, offset, opts)).records as T[];
   }
 
   /**