tina4-nodejs 3.13.40 → 3.13.42

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.40)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.42)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -300,6 +300,15 @@ Auto-generates OpenAPI 3.0.3 docs.
 - `TINA4_SWAGGER_UI_CDN` - base URL for the Swagger UI assets (`swagger-ui.css` + `swagger-ui-bundle.js`). Defaults to the public CDN (`https://unpkg.com/swagger-ui-dist@5`); point it at a self-hosted mirror for air-gapped deployments.
 - Info block: `TINA4_SWAGGER_TITLE`, `TINA4_SWAGGER_VERSION`, `TINA4_SWAGGER_DESCRIPTION`, `TINA4_SWAGGER_CONTACT_EMAIL`, `TINA4_SWAGGER_CONTACT_TEAM`, `TINA4_SWAGGER_CONTACT_URL`, `TINA4_SWAGGER_LICENSE`.
 
+**Configurability (v3.13.42):**
+- `TINA4_SWAGGER_OPENAPI` - OpenAPI version (default `3.0.3`); `3.1`/`3.1.0` emits `3.1.0`.
+- `TINA4_SWAGGER_BEARER_FORMAT` - `bearerFormat` on the built-in `bearerAuth` scheme (default `JWT`; use `opaque` for `sk_live_` keys).
+- `TINA4_SWAGGER_API_KEY_NAME` / `TINA4_SWAGGER_API_KEY_IN` - when the name is set, emit an `apiKeyAuth` scheme; `_IN` is `header` (default) / `query` / `cookie`.
+- `TINA4_SWAGGER_DEFAULT_SCHEME` - scheme a secured route uses when its `meta` declares no `security` (default `bearerAuth`).
+- `TINA4_SWAGGER_INCLUDE` / `TINA4_SWAGGER_EXCLUDE` - comma-separated path-prefix allow-list / deny-list (`/swagger` + `/__dev` always excluded).
+
+**Per-route security + reusable schemas (v3.13.42).** A route's `meta` may carry `security` (a scheme name, a `{name: [scopes]}` map, a list of maps for OR, or the string `"public"` to force `security: []`), a sibling `scopes` array, and `requestSchema` / `responseSchemas` referencing schemas registered with `addSchema(name, schema)`. Register arbitrary schemes (including `oauth2` with scopes) via `addSecurityScheme(name, definition)`; `resetRegistry()` clears both. All three are exported from `@tina4/swagger`. Scopes are kept spec-valid: only `oauth2`/`openIdConnect` carry them, `http`/`apiKey` get `[]`.
+
 ### @tina4/frond (`packages/frond/`)
 Built-in zero-dependency Twig-compatible template engine (the only template engine; there is no `twig` npm dependency).
 
@@ -1209,7 +1218,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **off by default — opt-in via `TINA4_AUTO_CACHING=true`** (TTL `TINA4_AUTO_CACHING_TTL=5`s) which dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes (always in-process); default OFF because a request-scoped cache defaulting on is a read-after-write footgun (cached pre-write `SELECT MAX(id)` → duplicate PKs); persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified async backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL`, so instances share one cache with global write-invalidation (full parity with Python/PHP/Ruby). `db.cacheStats()` reports `mode` (request/persistent/off) + `backend`
 - **Cache**: unified backend set — `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database` — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable. The KV API, the `responseCache` middleware, and the persistent DB query cache all route through this async backend set (native async clients, no child processes) — a network backend distributes them cross-instance, full parity with Python/PHP/Ruby; `memory` (default) keeps them in-process. `await` the async API (`cacheGet`/`cacheSet`/`clearCache`)
 - **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
-- **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
+- **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars. **Reservation/visibility timeout** (file + MongoDB): a popped job is reserved for `TINA4_QUEUE_VISIBILITY_TIMEOUT` seconds (default 300; `visibilityTimeout` Queue option; `<= 0` disables) — if the consumer dies before `complete()`/`fail()`, the next `pop()` reclaims it (incrementing `attempts`, dead-lettering past `maxRetries`), so a crashed/evicted consumer never strands a job. RabbitMQ/Kafka delegate redelivery to the broker.
 - **Cache**: memory/Redis/file backends
 - **Messenger**: .env driven SMTP/IMAP
 - **ORM relationships**: `hasMany`, `hasOne`, `belongsTo` with eager loading (`include`)

package/package.json

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

package/packages/core/src/job.ts

@@ -40,6 +40,7 @@ export type QueueJob = JobData & JobLifecycle;
 export interface JobQueueBridge {
   _failJob(topic: string, job: QueueJob, reason: string, maxRetries: number): void;
   _retryJob(topic: string, job: QueueJob, delaySeconds?: number): void;
+  _completeJob(topic: string, job: QueueJob): void;
   getMaxRetries(): number;
 }
 
@@ -48,8 +49,11 @@ export function createJob(data: JobData, queue: JobQueueBridge): QueueJob {
   const job: QueueJob = {
     ...data,
     complete() {
-      // Terminal — the job was already removed from the queue on pop().
+      // Terminal — the pending file was claimed on pop and a reservation record
+      // written; complete() drops the reservation so a dead-consumer reclaim
+      // never re-delivers an already-acked job. The job is done.
       job.status = "completed";
+      queue._completeJob(job.topic, job);
     },
     fail(reason = "") {
       // Record a failed attempt. `attempts` is incremented exactly once, inside

package/packages/core/src/queue.ts

@@ -51,6 +51,29 @@ export interface QueueConfig {
    * straight away. Parity with Python's retry_backoff.
    */
   retryBackoff?: number;
+  /**
+   * Reservation/visibility timeout (seconds). A popped job is reserved for this
+   * long; if the consumer dies before complete()/fail() (crash, OOM, k8s
+   * eviction) the next pop() reclaims it — incrementing attempts and
+   * re-enqueuing, or dead-lettering past maxRetries (at-least-once delivery).
+   * Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300 (5 min). <= 0
+   * disables the reclaim (a reservation then lasts until the consumer acks —
+   * the old at-most-once behaviour). File + MongoDB backends only;
+   * RabbitMQ/Kafka delegate visibility to the broker. Parity with Python's
+   * visibility_timeout.
+   */
+  visibilityTimeout?: number;
+}
+
+/**
+ * Reservation/visibility timeout in seconds, from env (default 300 = 5 min).
+ * Mirrors Python's _default_visibility_timeout().
+ */
+function defaultVisibilityTimeout(): number {
+  const raw = process.env.TINA4_QUEUE_VISIBILITY_TIMEOUT;
+  if (raw === undefined || raw === "") return 300;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : 300;
 }
 
 export interface ProcessOptions {
@@ -82,6 +105,7 @@ export class Queue {
   private topic: string;
   private _maxRetries: number;
   private _retryBackoff: number;
+  private _visibilityTimeout: number;
   private externalBackend: QueueBackendInterface | null = null;
   private liteBackend!: LiteBackend;
 
@@ -112,15 +136,19 @@ export class Queue {
     this.topic = resolvedConfig.topic ?? "default";
     this._maxRetries = resolvedConfig.maxRetries ?? 3;
     this._retryBackoff = resolvedConfig.retryBackoff ?? 0;
-    this.liteBackend = new LiteBackend(this.basePath);
+    this._visibilityTimeout = resolvedConfig.visibilityTimeout ?? defaultVisibilityTimeout();
+    this.liteBackend = new LiteBackend(this.basePath, this._visibilityTimeout);
 
     // Initialize external backends
     if (this.backendName === "rabbitmq") {
-      this.externalBackend = new RabbitMQBackend();
+      // Broker manages visibility/redelivery (unacked messages requeue on
+      // channel close) — the framework timeout is accepted but not used.
+      this.externalBackend = new RabbitMQBackend({ visibilityTimeout: this._visibilityTimeout });
     } else if (this.backendName === "kafka") {
-      this.externalBackend = new KafkaBackend();
+      // Consumer-group offsets manage redelivery — framework timeout N/A.
+      this.externalBackend = new KafkaBackend({ visibilityTimeout: this._visibilityTimeout });
     } else if (this.backendName === "mongodb" || this.backendName === "mongo") {
-      this.externalBackend = new MongoBackend();
+      this.externalBackend = new MongoBackend({ visibilityTimeout: this._visibilityTimeout });
     }
   }
 
@@ -410,6 +438,15 @@ export class Queue {
     return this._retryBackoff;
   }
 
+  /**
+   * Resolved reservation/visibility timeout (seconds). <= 0 means the reclaim
+   * is disabled. File + MongoDB backends honour it; RabbitMQ/Kafka delegate to
+   * the broker.
+   */
+  getVisibilityTimeout(): number {
+    return this._visibilityTimeout;
+  }
+
   /**
    * Record a failed attempt for a job. The backend increments `attempts`
    * exactly once and decides whether to re-enqueue (attempts < maxRetries,
@@ -425,4 +462,13 @@ export class Queue {
   _retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
     this.liteBackend.retryJob(queue, job, delaySeconds);
   }
+
+  /**
+   * Acknowledge a completed job — drop its reservation record so the visibility
+   * reclaim never re-delivers it. No-op for external backends (they ack their
+   * own way; lite-backend reservations are file records).
+   */
+  _completeJob(queue: string, job: QueueJob): void {
+    this.liteBackend.completeJob(queue, job);
+  }
 }

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

@@ -27,6 +27,12 @@ import type { QueueJob } from "../queue.js";
 export interface KafkaConfig {
   brokers?: string;
   groupId?: string;
+  /**
+   * Accepted for API parity with the file/MongoDB backends and IGNORED —
+   * consumer-group offsets own redelivery, so the framework-level visibility
+   * timeout does not apply here.
+   */
+  visibilityTimeout?: number;
 }
 
 /**
@@ -134,7 +140,7 @@ export class KafkaBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): Required<KafkaConfig> {
+  getConfig(): Required<Omit<KafkaConfig, "visibilityTimeout">> {
     return { brokers: this.brokers, groupId: this.groupId };
   }
 

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

@@ -24,9 +24,19 @@ import { createJob, type JobQueueBridge } from "../job.js";
 export class LiteBackend {
   private basePath: string;
   private seq: number = 0;
+  /**
+   * Reservation/visibility timeout (seconds). A popped job is held in reserved/
+   * with availableAt = now + visibilityTimeout. If the consumer dies before
+   * complete()/fail() (crash, OOM, k8s eviction) the next pop() reclaims it once
+   * the window expires — incrementing attempts and re-enqueuing, or
+   * dead-lettering past maxRetries. <= 0 disables the reclaim (a reservation
+   * then lasts until the consumer acks — the old at-most-once behaviour).
+   */
+  private visibilityTimeout: number;
 
-  constructor(basePath: string = "data/queue") {
+  constructor(basePath: string = "data/queue", visibilityTimeout: number = 300) {
     this.basePath = basePath;
+    this.visibilityTimeout = visibilityTimeout;
   }
 
   private ensureDir(queue: string): string {
@@ -41,6 +51,24 @@ export class LiteBackend {
     return dir;
   }
 
+  private ensureReservedDir(queue: string): string {
+    const dir = join(this.basePath, queue, "reserved");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  private reservedPath(queue: string, jobId: string): string {
+    return join(this.ensureReservedDir(queue), `${jobId}.queue-data`);
+  }
+
+  private nowIso(): string {
+    return new Date().toISOString();
+  }
+
+  private futureIso(seconds: number): string {
+    return new Date(Date.now() + seconds * 1000).toISOString();
+  }
+
   private nextPrefix(): string {
     this.seq++;
     return `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
@@ -111,22 +139,112 @@ export class LiteBackend {
     return candidates;
   }
 
+  /**
+   * Persist a reservation record so a dead consumer's job is reclaimable.
+   *
+   * Stores reservedAt + availableAt = now + visibilityTimeout. The next pop()
+   * reclaims this job once availableAt has passed (see reclaimExpired).
+   * complete()/fail()/retry() delete the record.
+   */
+  private writeReserved(queue: string, job: any): void {
+    const now = this.nowIso();
+    const vt = this.visibilityTimeout || 0;
+    const record = {
+      id: job.id,
+      payload: job.payload,
+      status: "reserved" as const,
+      priority: job.priority ?? 0,
+      attempts: job.attempts ?? 0,
+      error: job.error,
+      reservedAt: now,
+      availableAt: vt > 0 ? this.futureIso(vt) : now,
+      createdAt: job.createdAt ?? now,
+      topic: job.topic ?? queue,
+    };
+    writeFileSync(this.reservedPath(queue, record.id), JSON.stringify(record, null, 2));
+  }
+
+  /**
+   * Return expired reservations to the queue (at-least-once delivery).
+   *
+   * A reserved job whose availableAt <= now means its consumer never
+   * acknowledged in time (crash / OOM / pod eviction). Atomically claim it
+   * (delete the reservation file), increment attempts, and either re-enqueue it
+   * (so the next pop picks it up) or dead-letter it once it has hit maxRetries.
+   * Disabled when visibilityTimeout <= 0.
+   */
+  private reclaimExpired(queue: string, maxRetries: number, now: string): void {
+    if (!this.visibilityTimeout || this.visibilityTimeout <= 0) return;
+    const reservedDir = this.ensureReservedDir(queue);
+
+    let filenames: string[];
+    try {
+      filenames = readdirSync(reservedDir).filter(f => f.endsWith(".queue-data"));
+    } catch {
+      return;
+    }
+
+    for (const filename of filenames) {
+      const filePath = join(reservedDir, filename);
+      let record: any;
+      try {
+        record = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        continue;
+      }
+      if (record.availableAt && record.availableAt > now) continue; // still valid
+      // Atomically claim the expired reservation by deleting its file.
+      try {
+        unlinkSync(filePath);
+      } catch {
+        continue; // another worker reclaimed it first
+      }
+
+      const attempts = (record.attempts ?? 0) + 1;
+      const error = "reservation timed out — consumer did not acknowledge within the visibility timeout";
+      const job: QueueJob = {
+        id: record.id,
+        payload: record.payload,
+        status: "reserved",
+        createdAt: record.createdAt ?? now,
+        attempts,
+        delayUntil: null,
+        priority: record.priority ?? 0,
+        topic: record.topic ?? queue,
+        error,
+      } as QueueJob;
+
+      if (attempts >= maxRetries) {
+        this.deadLetter(queue, job, error);
+      } else {
+        this.requeue(queue, job, 0, error);
+      }
+    }
+  }
+
   pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
     const dir = this.ensureDir(queue);
-    const now = new Date().toISOString();
+    // First return any reservations whose consumer died mid-flight.
+    this.reclaimExpired(queue, bridge.getMaxRetries(), this.nowIso());
+    const now = this.nowIso();
 
     for (const [filename, job] of this.availableCandidates(queue, now)) {
       const filePath = join(dir, filename);
-      // Claim the job by deleting the file.
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      // Write the reservation BEFORE claiming the pending file, so a crash
+      // between claim and reserve can never strand the job. Only the worker
+      // that wins the unlink owns — and returns — it.
+      this.writeReserved(queue, job);
       try {
         unlinkSync(filePath);
       } catch {
-        continue; // Already consumed by another worker
+        // Already consumed by another worker — drop the speculative reservation.
+        try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
+        continue;
       }
 
       job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
       return createJob(job as any, bridge);
     }
 
@@ -135,34 +253,61 @@ export class LiteBackend {
 
   popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
     const dir = this.ensureDir(queue);
-    const now = new Date().toISOString();
+    this.reclaimExpired(queue, bridge.getMaxRetries(), this.nowIso());
+    const now = this.nowIso();
     const results: QueueJob[] = [];
 
     for (const [filename, job] of this.availableCandidates(queue, now)) {
       if (results.length >= count) break;
       const filePath = join(dir, filename);
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      this.writeReserved(queue, job);
       try {
         unlinkSync(filePath);
       } catch {
+        try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
         continue; // Already consumed by another worker
       }
 
       job.status = "reserved";
-      job.topic = queue;
-      job.priority = job.priority ?? 0;
       results.push(createJob(job as any, bridge));
     }
 
     return results;
   }
 
+  /**
+   * Delete a job's reservation record (best-effort).
+   */
+  private clearReservation(queue: string, jobId: string): void {
+    try {
+      unlinkSync(this.reservedPath(queue, jobId));
+    } catch {
+      // no reservation record — nothing to clear
+    }
+  }
+
+  /**
+   * Acknowledge a completed job — drop its reservation record so the visibility
+   * reclaim never re-delivers an already-acked job.
+   */
+  completeJob(queue: string, job: QueueJob): void {
+    this.clearReservation(queue, job.id);
+  }
+
   // 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 {
     const isDead = LiteBackend.DEAD_STATES.includes(status);
-    const scanDir = isDead ? this.ensureFailedDir(queue) : this.ensureDir(queue);
+    const isReserved = status === "reserved";
+    const scanDir = isDead
+      ? this.ensureFailedDir(queue)
+      : isReserved
+        ? this.ensureReservedDir(queue)
+        : this.ensureDir(queue);
 
     let files: string[];
     try {
@@ -171,9 +316,9 @@ export class LiteBackend {
       return 0;
     }
 
-    if (isDead) {
-      // Every file in failed/ is a dead-letter; count them all regardless of
-      // the exact stored status string.
+    if (isDead || isReserved) {
+      // Every file in failed/ (or reserved/) matches the requested status;
+      // count them all regardless of the exact stored status string.
       return files.length;
     }
 
@@ -215,6 +360,20 @@ export class LiteBackend {
     } catch {
       // ignore
     }
+
+    // Also clear reservation records.
+    const reservedDir = join(dir, "reserved");
+    try {
+      if (existsSync(reservedDir)) {
+        const files = readdirSync(reservedDir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          unlinkSync(join(reservedDir, file));
+          count++;
+        }
+      }
+    } catch {
+      // ignore
+    }
     return count;
   }
 
@@ -416,7 +575,18 @@ export class LiteBackend {
 
       if (job.status !== "pending") continue;
       if (job.id === id) {
-        try { unlinkSync(filePath); } catch { /* already consumed */ }
+        job.topic = queue;
+        job.priority = job.priority ?? 0;
+        // Reserve (so a dead consumer's job is reclaimable) then claim the
+        // pending file — mirrors pop().
+        this.writeReserved(queue, job);
+        try {
+          unlinkSync(filePath);
+        } catch {
+          try { unlinkSync(this.reservedPath(queue, job.id)); } catch { /* ignore */ }
+          continue; // already consumed
+        }
+        job.status = "reserved";
         return job;
       }
     }
@@ -479,6 +649,8 @@ export class LiteBackend {
    * (attempts >= maxRetries) it is moved to the dead-letter store.
    */
   failJob(queue: string, job: QueueJob, error: string, maxRetries: number, retryBackoff: number = 0): void {
+    // Clear the reservation — the consumer acknowledged (with a failure).
+    this.clearReservation(queue, job.id);
     job.attempts = (job.attempts || 0) + 1;
     job.error = error;
     if (job.attempts < maxRetries) {
@@ -495,6 +667,8 @@ export class LiteBackend {
    * distinct from the automatic failJob() path.
    */
   retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
+    // Clear the reservation — the consumer acknowledged (with an explicit retry).
+    this.clearReservation(queue, job.id);
     job.attempts = (job.attempts || 0) + 1;
     job.error = undefined;
     this.requeue(queue, job, delaySeconds ?? 0, undefined);

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

@@ -32,6 +32,15 @@ export interface MongoConfig {
   password?: string;
   database?: string;
   collection?: string;
+  /**
+   * Reservation/visibility timeout (seconds). A dequeued message is held
+   * reserved with availableAt = now + timeout; reclaim returns it once that
+   * passes (consumer died mid-flight, before complete()/fail()). <= 0 disables
+   * the reclaim. Falls back to TINA4_QUEUE_VISIBILITY_TIMEOUT, else 300.
+   */
+  visibilityTimeout?: number;
+  /** Max attempts before the reclaim dead-letters a job instead of re-delivering. */
+  maxRetries?: number;
 }
 
 export interface QueueBackend {
@@ -58,6 +67,8 @@ export class MongoBackend implements QueueBackend {
   private password: string;
   private database: string;
   private collection: string;
+  private visibilityTimeout: number;
+  private maxRetries: number;
 
   constructor(config?: MongoConfig) {
     this.host = config?.host ?? process.env.TINA4_MONGO_HOST ?? "localhost";
@@ -68,6 +79,16 @@ 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";
 
+    // Reservation/visibility timeout (seconds): config wins, else env, else 300.
+    if (config?.visibilityTimeout !== undefined) {
+      this.visibilityTimeout = config.visibilityTimeout;
+    } else {
+      const raw = process.env.TINA4_QUEUE_VISIBILITY_TIMEOUT;
+      const parsed = raw === undefined || raw === "" ? 300 : Number(raw);
+      this.visibilityTimeout = Number.isFinite(parsed) ? parsed : 300;
+    }
+    this.maxRetries = config?.maxRetries ?? 3;
+
     // 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;
@@ -84,15 +105,34 @@ 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 };
+  getConfig(): { uri: string; database: string; collection: string; visibilityTimeout: number } {
+    return {
+      uri: this.uri,
+      database: this.database,
+      collection: this.collection,
+      visibilityTimeout: this.visibilityTimeout,
+    };
   }
 
   /**
-   * Execute a MongoDB operation synchronously via a child process.
+   * Resolved reservation/visibility timeout (seconds). <= 0 disables the
+   * reclaim. Exposed for testing/introspection.
    */
-  private execSync(operation: string, queue: string, data?: string): string {
-    const script = `
+  getVisibilityTimeout(): number {
+    return this.visibilityTimeout;
+  }
+
+  /**
+   * Build the Node script that performs one MongoDB queue operation in a child
+   * process. Exposed (not private) so tests can assert the visibility-timeout
+   * behaviour without a live MongoDB — the script's pop branch advances
+   * availableAt = now + visibilityTimeout and stamps reservedAt (the core fix),
+   * and the reclaim branch flips an expired { status: reserved } back to
+   * pending with attempts incremented (dead-lettering past maxRetries),
+   * disabled when visibilityTimeout <= 0.
+   */
+  buildScript(operation: string, queue: string, data?: string): string {
+    return `
       async function main() {
         let mongodb;
         try {
@@ -109,6 +149,8 @@ export class MongoBackend implements QueueBackend {
         const operation = ${JSON.stringify(operation)};
         const queueName = ${JSON.stringify(queue)};
         const data = ${JSON.stringify(data ?? "")};
+        const visibilityTimeout = ${JSON.stringify(this.visibilityTimeout)};
+        const maxRetries = ${JSON.stringify(this.maxRetries)};
 
         const client = new MongoClient(uri, {
           connectTimeoutMS: 5000,
@@ -121,7 +163,7 @@ export class MongoBackend implements QueueBackend {
           const col = db.collection(collName);
 
           // Ensure indexes on first use
-          await col.createIndex({ queue: 1, status: 1, delayUntil: 1 });
+          await col.createIndex({ queue: 1, status: 1, availableAt: 1 });
           await col.createIndex({ queue: 1, createdAt: 1 });
 
           if (operation === "push") {
@@ -129,19 +171,59 @@ export class MongoBackend implements QueueBackend {
             await col.insertOne({ ...job, queue: queueName });
             process.stdout.write("__PUSHED__");
           }
+          else if (operation === "reclaim") {
+            // Return reservations whose visibility window expired (at-least-once
+            // delivery). A doc left { status: reserved, availableAt <= now } had
+            // its consumer die before acknowledging — flip it back to pending
+            // with attempts incremented, or dead-letter once attempts hit the
+            // limit. Disabled when visibilityTimeout <= 0.
+            let reclaimed = 0;
+            if (visibilityTimeout > 0) {
+              while (true) {
+                const now = new Date().toISOString();
+                const doc = await col.findOneAndUpdate(
+                  { queue: queueName, status: "reserved", availableAt: { $lte: now } },
+                  { $set: { status: "pending", availableAt: now, reservedAt: null }, $inc: { attempts: 1 } },
+                  { sort: { availableAt: 1 }, returnDocument: "after" },
+                );
+                const updated = doc && doc.value ? doc.value : (doc && doc._id ? doc : null);
+                if (!updated) break;
+                reclaimed++;
+                if ((updated.attempts || 0) >= maxRetries) {
+                  await col.insertOne({
+                    ...updated,
+                    _id: undefined,
+                    status: "dead",
+                    queue: queueName + ".dead_letter",
+                    error: "reservation timed out — consumer did not acknowledge within the visibility timeout",
+                  });
+                  await col.deleteOne({ _id: updated._id, queue: queueName });
+                }
+              }
+            }
+            process.stdout.write(String(reclaimed));
+          }
           else if (operation === "pop") {
             const now = new Date().toISOString();
+            // The claim advances availableAt = now + visibilityTimeout and
+            // stamps reservedAt so reclaim can return the job if the consumer
+            // dies before complete()/fail() — this is the fix for the "reserved
+            // forever" bug (previously availableAt was left unchanged).
+            const future = new Date(Date.now() + visibilityTimeout * 1000).toISOString();
             const result = await col.findOneAndUpdate(
               {
                 queue: queueName,
                 status: "pending",
                 $or: [
+                  { availableAt: null },
+                  { availableAt: { $exists: false } },
+                  { availableAt: { $lte: now } },
                   { delayUntil: null },
                   { delayUntil: { $lte: now } },
                 ],
               },
-              { $set: { status: "reserved" } },
-              { sort: { createdAt: 1 }, returnDocument: "before" },
+              { $set: { status: "reserved", reservedAt: now, availableAt: future } },
+              { sort: { priority: -1, createdAt: 1 }, returnDocument: "before" },
             );
 
             if (result && result.value) {
@@ -181,6 +263,13 @@ export class MongoBackend implements QueueBackend {
 
       main();
     `;
+  }
+
+  /**
+   * Execute a MongoDB operation synchronously via a child process.
+   */
+  private execSync(operation: string, queue: string, data?: string): string {
+    const script = this.buildScript(operation, queue, data);
 
     try {
       const result = execFileSync(process.execPath, ["-e", script], {
@@ -215,6 +304,11 @@ export class MongoBackend implements QueueBackend {
   }
 
   pop(queue: string): QueueJob | null {
+    // Reclaim any reservations whose consumer died before acking, then take the
+    // next available message (at-least-once delivery). Disabled at timeout <= 0.
+    if (this.visibilityTimeout > 0) {
+      this.execSync("reclaim", queue);
+    }
     const result = this.execSync("pop", queue);
     if (!result || result === "__EMPTY__") return null;
 

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

@@ -28,6 +28,12 @@ export interface RabbitMQConfig {
   username?: string;
   password?: string;
   vhost?: string;
+  /**
+   * Accepted for API parity with the file/MongoDB backends and IGNORED — the
+   * broker owns redelivery (unacked messages requeue on channel close), so the
+   * framework-level visibility timeout does not apply here.
+   */
+  visibilityTimeout?: number;
 }
 
 /**
@@ -200,7 +206,7 @@ export class RabbitMQBackend implements QueueBackend {
   /**
    * Resolved connection config — exposed for testing/introspection.
    */
-  getConfig(): Required<RabbitMQConfig> {
+  getConfig(): Required<Omit<RabbitMQConfig, "visibilityTimeout">> {
     return {
       host: this.host,
       port: this.port,

package/packages/core/src/types.ts

@@ -138,6 +138,28 @@ export interface RouteMeta {
   example?: unknown;
   /** Marks the operation deprecated in the spec. */
   deprecated?: boolean;
+  /**
+   * Per-route security requirement (v3.13.42). Overrides the default scheme.
+   * Accepted forms (normalized by the generator into a security-requirement list):
+   *   "bearerAuth"                          -> [{ bearerAuth: [] }]
+   *   "public" | "none" | []                -> [] (explicitly no auth)
+   *   { apiKeyAuth: [] }                    -> [{ apiKeyAuth: [] }]   (AND within one map)
+   *   [{ oauth2: ["read"] }, { bearerAuth: [] }]  -> verbatim (OR across maps)
+   */
+  security?: string | string[] | Record<string, string[]> | Array<Record<string, string[]>>;
+  /** Scopes for a single named scheme passed as `security: "oauth2"` + `scopes: [...]`. */
+  scopes?: string[];
+  /**
+   * Reference a registered component schema as the request body (v3.13.42):
+   *   requestSchema: "CreateUser"  OR  { name: "CreateUser", contentType: "application/json" }
+   * Emits `$ref: #/components/schemas/CreateUser` and lands the schema in components.schemas.
+   */
+  requestSchema?: string | { name: string; contentType?: string };
+  /**
+   * Reference registered component schemas as response bodies, keyed by status (v3.13.42):
+   *   responseSchemas: { 200: "User", 201: { name: "User", isList: true } }
+   */
+  responseSchemas?: Record<string, string | { name: string; isList?: boolean }>;
 }
 
 export interface Tina4Config {

package/packages/swagger/src/generator.ts

@@ -20,6 +20,120 @@ interface OpenAPISpec {
 
 const WRITE_METHODS = new Set(["post", "put", "patch", "delete"]);
 
+// ── Configuration registries (v3.13.42) ───────────────────────────
+// Process-wide registries for security schemes and reusable component schemas
+// declared programmatically (addSecurityScheme / addSchema). Kept module-level so
+// app bootstrap can register before any generate() call; resetRegistry() clears
+// them (tests). Parity with Python's Swagger.add_security_scheme/add_schema/reset_registry.
+const registeredSchemes: Record<string, Record<string, unknown>> = {};
+const registeredSchemas: Record<string, Record<string, unknown>> = {};
+
+/**
+ * Register a named OpenAPI security scheme (e.g. an oauth2 scheme with scopes,
+ * or a custom apiKey). Call at app bootstrap, before generate(). A registered
+ * scheme may override the built-in bearerAuth.
+ */
+export function addSecurityScheme(name: string, definition: Record<string, unknown>): void {
+  registeredSchemes[name] = definition;
+}
+
+/**
+ * Register a reusable component schema, referenceable via meta.requestSchema /
+ * meta.responseSchemas or a raw $ref.
+ */
+export function addSchema(name: string, schema: Record<string, unknown>): void {
+  registeredSchemas[name] = schema;
+}
+
+/** Clear the security-scheme and schema registries (test helper). */
+export function resetRegistry(): void {
+  for (const k of Object.keys(registeredSchemes)) delete registeredSchemes[k];
+  for (const k of Object.keys(registeredSchemas)) delete registeredSchemas[k];
+}
+
+/** Resolve TINA4_SWAGGER_OPENAPI to a concrete version. Default 3.0.3; "3.1"/"3.1.0" -> "3.1.0". */
+function resolveOpenApiVersion(): string {
+  const v = (process.env.TINA4_SWAGGER_OPENAPI ?? "").trim();
+  if (!v) return "3.0.3";
+  if (v === "3.1" || v === "3.1.0") return "3.1.0";
+  if (v === "3.0" || v === "3.0.3") return "3.0.3";
+  return v; // honour an explicit full version verbatim
+}
+
+/** Comma-separated env value -> clean list. */
+function csv(val: string | undefined): string[] {
+  return (val ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+/** Resolve components.securitySchemes from defaults + env + registry. */
+function resolveSecuritySchemes(): Record<string, Record<string, unknown>> {
+  const bearerFormat = process.env.TINA4_SWAGGER_BEARER_FORMAT ?? "JWT";
+  const schemes: Record<string, Record<string, unknown>> = {
+    bearerAuth: { type: "http", scheme: "bearer", bearerFormat },
+  };
+  const apiKeyName = (process.env.TINA4_SWAGGER_API_KEY_NAME ?? "").trim();
+  if (apiKeyName.length > 0) {
+    const rawIn = process.env.TINA4_SWAGGER_API_KEY_IN ?? "header";
+    const apiKeyIn = ["header", "query", "cookie"].includes(rawIn) ? rawIn : "header";
+    schemes.apiKeyAuth = { type: "apiKey", name: apiKeyName, in: apiKeyIn };
+  }
+  // Registered schemes win (let an app override bearerAuth or add oauth2).
+  for (const [name, def] of Object.entries(registeredSchemes)) {
+    schemes[name] = def;
+  }
+  return schemes;
+}
+
+/**
+ * Normalize a meta.security value (+ optional scopes) into an OpenAPI
+ * security-requirement list. Mirrors Python's _normalize_security.
+ */
+function normalizeSecurity(
+  value: NonNullable<unknown> | undefined,
+  scopes: string[] | undefined
+): Array<Record<string, string[]>> {
+  if ((value === "public" || value === "none" || value === undefined || value === null) && (!scopes || scopes.length === 0)) {
+    return [];
+  }
+  if (typeof value === "string") {
+    return [{ [value]: [...(scopes ?? [])] }];
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [];
+    return value.map((req) => normalizeRequirementMap(req as Record<string, string[]>));
+  }
+  if (value !== null && typeof value === "object") {
+    return [normalizeRequirementMap(value as Record<string, string[]>)];
+  }
+  return [];
+}
+
+function normalizeRequirementMap(req: Record<string, string[]>): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [k, v] of Object.entries(req)) out[k] = [...(v ?? [])];
+  return out;
+}
+
+/**
+ * Keep a security-requirement list spec-valid: scopes are allowed only on
+ * oauth2/openIdConnect schemes; everything else gets an empty array (OpenAPI
+ * requires it). Mirrors Python's _sanitize_security.
+ */
+function sanitizeSecurity(
+  reqs: Array<Record<string, string[]>>,
+  schemes: Record<string, Record<string, unknown>>
+): Array<Record<string, string[]>> {
+  const scopeOk = new Set(["oauth2", "openIdConnect"]);
+  return reqs.map((req) => {
+    const clean: Record<string, string[]> = {};
+    for (const [name, scopes] of Object.entries(req)) {
+      const stype = (schemes[name] as Record<string, unknown> | undefined)?.type;
+      clean[name] = scopeOk.has(stype as string) ? [...scopes] : [];
+    }
+    return clean;
+  });
+}
+
 export function generate(
   routes: RouteDefinition[],
   models: ModelDefinition[] = []
@@ -49,21 +163,31 @@ export function generate(
     info.license = url ? { name, url } : { name };
   }
 
+  const schemes = resolveSecuritySchemes();
   const spec: OpenAPISpec = {
-    openapi: "3.0.3",
+    openapi: resolveOpenApiVersion(),
     info,
     servers: resolveServers(),
     paths: {},
     components: {
       schemas: {},
-      // bearerAuth was never defined before — secured routes were documented
-      // identically to public ones (audit P1). Define it once and reference it.
-      securitySchemes: {
-        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
-      },
+      // Configurable security schemes (v3.13.42): bearerFormat via env, optional
+      // apiKey scheme, plus any programmatically-registered schemes (which may
+      // override bearerAuth — e.g. an oauth2 scheme with scopes).
+      securitySchemes: schemes,
     },
   };
 
+  // Default scheme secured routes use when no explicit meta.security is set.
+  const defaultScheme = process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth";
+
+  // Path filters (comma-separated raw-path prefixes).
+  const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
+  const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
+
+  // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
+  const refSchemas = new Set<string>();
+
   // Generate schemas from models
   for (const model of models) {
     const schema = modelToSchema(model);
@@ -75,6 +199,7 @@ export function generate(
 
   // Generate paths from routes
   for (const route of routes) {
+    if (!isIncludedPath(route.pattern, includePrefixes, excludePrefixes)) continue;
     const openApiPath = patternToOpenAPI(route.pattern);
     const method = route.method.toLowerCase();
 
@@ -123,8 +248,20 @@ export function generate(
       }
     }
 
-    // Add request body for POST/PUT
-    if (method === "post" || method === "put") {
+    // Request body — a registered custom schema $ref (meta.requestSchema) wins,
+    // else the inferred-from-model body (POST/PUT to a resource), else an
+    // example-only body.
+    const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
+    if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
+      refSchemas.add(reqSchemaRef.name);
+      const media: Record<string, unknown> = {
+        schema: { $ref: `#/components/schemas/${reqSchemaRef.name}` },
+      };
+      if (route.meta?.example !== undefined) media.example = route.meta.example;
+      operation.requestBody = {
+        content: { [reqSchemaRef.contentType]: media },
+      };
+    } else if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
       if (modelName && models.some((m) => m.tableName === modelName)) {
         const media: Record<string, unknown> = {
@@ -151,11 +288,35 @@ export function generate(
       }
     }
 
-    // Security — a secured route emits operation.security + 401. Mirrors the
-    // router's enforcement (writes secure by default unless noAuth; GET secure
-    // only when marked). Before, no route ever got a security requirement.
-    if (routeRequiresAuth(route, method)) {
-      operation.security = [{ bearerAuth: [] }];
+    // Registered response schemas ($ref) — explicit and authoritative, keyed by status.
+    const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
+    if (respSchemas.length > 0) {
+      const responses = operation.responses as Record<string, unknown>;
+      for (const { status, name, isList } of respSchemas) {
+        refSchemas.add(name);
+        const sref = `#/components/schemas/${name}`;
+        const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
+        responses[status] = {
+          description: status.startsWith("2") ? "Successful response" : "Response",
+          content: { "application/json": { schema } },
+        };
+      }
+    }
+
+    // Security (v3.13.42) — explicit meta.security wins (empty list = explicitly
+    // public); otherwise a secured route gets the default scheme. Scopes are kept
+    // valid (only oauth2/openIdConnect carry them).
+    const hasExplicitSecurity =
+      route.meta?.security !== undefined || (route.meta?.scopes !== undefined && route.meta.scopes.length > 0);
+    if (hasExplicitSecurity) {
+      const normalized = normalizeSecurity(route.meta?.security, route.meta?.scopes);
+      operation.security = normalized.length > 0 ? sanitizeSecurity(normalized, schemes) : [];
+      if (normalized.length > 0) {
+        const responses = operation.responses as Record<string, unknown>;
+        if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
+      }
+    } else if (routeRequiresAuth(route, method)) {
+      operation.security = sanitizeSecurity([{ [defaultScheme]: [] }], schemes);
       const responses = operation.responses as Record<string, unknown>;
       if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
     }
@@ -163,6 +324,16 @@ export function generate(
     spec.paths[openApiPath][method] = operation;
   }
 
+  // Registered component schemas referenced via meta.requestSchema/responseSchemas.
+  if (refSchemas.size > 0) {
+    const schemas = spec.components!.schemas!;
+    for (const name of refSchemas) {
+      if (name in registeredSchemas && !(name in schemas)) {
+        schemas[name] = registeredSchemas[name];
+      }
+    }
+  }
+
   if (usedTags.length > 0) {
     spec.tags = usedTags.map((name) => ({ name }));
   }
@@ -176,6 +347,45 @@ function routeRequiresAuth(route: RouteDefinition, method: string): boolean {
   return route.secure === true;
 }
 
+/**
+ * Path-filter a raw route pattern. Framework internals (/swagger, /__dev) are
+ * ALWAYS excluded; then TINA4_SWAGGER_INCLUDE (allow-list) / _EXCLUDE apply.
+ * Mirrors Python's _included.
+ */
+function isIncludedPath(rawPath: string, include: string[], exclude: string[]): boolean {
+  for (const internal of ["/swagger", "/__dev"]) {
+    if (rawPath === internal || rawPath.startsWith(internal + "/")) return false;
+  }
+  if (include.length > 0 && !include.some((p) => rawPath === p || rawPath.startsWith(p))) {
+    return false;
+  }
+  if (exclude.some((p) => rawPath === p || rawPath.startsWith(p))) return false;
+  return true;
+}
+
+function parseRequestSchema(
+  spec: string | { name: string; contentType?: string } | undefined
+): { name: string; contentType: string } | null {
+  if (spec === undefined) return null;
+  if (typeof spec === "string") return { name: spec, contentType: "application/json" };
+  return { name: spec.name, contentType: spec.contentType ?? "application/json" };
+}
+
+function parseResponseSchemas(
+  spec: Record<string, string | { name: string; isList?: boolean }> | undefined
+): Array<{ status: string; name: string; isList: boolean }> {
+  if (!spec) return [];
+  const out: Array<{ status: string; name: string; isList: boolean }> = [];
+  for (const [status, value] of Object.entries(spec)) {
+    if (typeof value === "string") {
+      out.push({ status, name: value, isList: false });
+    } else {
+      out.push({ status, name: value.name, isList: value.isList === true });
+    }
+  }
+  return out;
+}
+
 function resolveServers(): { url: string }[] {
   const raw = (process.env.TINA4_SWAGGER_SERVERS ?? "").trim();
   const urls = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);

package/packages/swagger/src/index.ts

@@ -1,2 +1,2 @@
-export { generate } from "./generator.js";
+export { generate, addSecurityScheme, addSchema, resetRegistry } from "./generator.js";
 export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";