tina4-nodejs 3.13.92 → 3.13.94

package/types/core/src/queue.d.ts

@@ -0,0 +1,219 @@
+import { type QueueJob } from "./job.js";
+export { LiteBackend } from "./queueBackends/liteBackend.js";
+export { type QueueJob } from "./job.js";
+export interface QueueConfig {
+    backend?: string;
+    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;
+    /**
+     * 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;
+}
+export interface ProcessOptions {
+    pollInterval?: number;
+    maxJobs?: number;
+    maxRetries?: number;
+    batchSize?: number;
+    /**
+     * Override the queue's topic for this drain (parity with Python's
+     * process(handler, topic=...)). When set, process() retargets the queue so
+     * pop() reads the requested topic instead of the construction-time one.
+     */
+    topic?: string;
+}
+export interface ConsumeOptions {
+    /** Topic to consume (defaults to the constructor topic). */
+    topic?: string;
+    batchSize?: number;
+    pollInterval?: number;
+    iterations?: number;
+    id?: string;
+}
+export interface QueueBackendInterface {
+    push(queue: string, payload: unknown, delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+    complete?(queue: string, id: string): void;
+    fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
+    retry?(queue: string, id: string, delaySeconds?: number): void;
+    deadLetters?(queue: string, maxRetries?: number): QueueJob[];
+    failed?(queue: string, maxRetries?: number): QueueJob[];
+    retryFailed?(queue: string, maxRetries?: number): number;
+    purge?(queue: string, status?: string): number;
+}
+export declare class Queue {
+    private backendName;
+    private basePath;
+    private topic;
+    private _maxRetries;
+    private _retryBackoff;
+    private _visibilityTimeout;
+    private externalBackend;
+    private liteBackend;
+    /**
+     * Unified Queue constructor.
+     *
+     * Accepts either:
+     *   - new Queue({ topic: "tasks", backend: "rabbitmq" })
+     *   - new Queue("rabbitmq", { path: "data/queue" })  // legacy
+     *   - new Queue()  // file backend, default topic
+     */
+    constructor(backendOrConfig?: string | QueueConfig, config?: QueueConfig);
+    /**
+     * Point this queue at ``topic`` in place.
+     *
+     * produce()/consume()/process() call this so a topic argument actually
+     * changes which topic is read or written. Without it the argument was
+     * accepted but ignored on the read path — pop() always used the
+     * construction-time topic, so consume("other") silently drained the wrong
+     * queue. The lite + external backends are topic-per-call (every push/pop/size
+     * takes the queue name), so changing this.topic retargets all of them; the
+     * job lifecycle (complete()/fail()/retry()) routes by the job's own .topic, so
+     * it is unaffected. Mirrors Python's Queue._retarget().
+     */
+    private retarget;
+    /**
+     * Add a job to the queue. Returns job ID.
+     *
+     * Can be called as:
+     *   queue.push(payload)                — uses constructor topic
+     *   queue.push(payload, delay)         — uses constructor topic with delay
+     *   queue.push(payload, delay, priority) — with delay and priority
+     *
+     * @param priority — Higher value = higher priority. Default 0.
+     */
+    push(payload: unknown, delay?: number, priority?: number): string;
+    /**
+     * Atomically claim the next available job from this queue's topic. Returns null if empty.
+     */
+    pop(): QueueJob | null;
+    /**
+     * Pop up to count jobs at once. Returns a partial batch if fewer available.
+     */
+    popBatch(count: number): QueueJob[];
+    /**
+     * Process jobs from a queue with a handler function.
+     */
+    process(handler: (job: QueueJob | QueueJob[]) => Promise<void> | void, options?: ProcessOptions): void;
+    /**
+     * Count jobs filtered by status. Defaults to "pending".
+     */
+    size(status?: string): number;
+    /**
+     * Remove all jobs from this queue's topic. Returns the number cleared.
+     */
+    clear(): number;
+    /**
+     * 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[];
+    /**
+     * Retry all dead letter jobs for this queue's topic.
+     * Moves failed jobs that exceeded max retries back to pending.
+     *
+     * @param delaySeconds - Optional delay before jobs become available
+     * @returns true if at least one job was re-queued, false if none found
+     */
+    retry(jobId?: string, delaySeconds?: number): boolean;
+    /**
+     * Get dead letter jobs — failed jobs that exceeded max retries.
+     */
+    deadLetters(maxRetries?: number): QueueJob[];
+    /**
+     * Delete messages by status (e.g. "completed", "failed", "dead").
+     */
+    purge(status: string, maxRetries?: number): number;
+    /**
+     * Re-queue failed jobs that haven't exceeded max retries back to pending.
+     */
+    retryFailed(maxRetries?: number): number;
+    /**
+     * Produce a message onto a topic. Convenience wrapper around push().
+     *
+     * Retargets to the requested topic (restoring the prior one afterwards) so it
+     * shares the same retarget path consume()/process() use — keeping produce and
+     * consume symmetric on the same topic argument.
+     */
+    produce(topic: string, payload: unknown, priority?: number, delay?: number): string;
+    /**
+     * Consume jobs from a topic using a generator (yield pattern).
+     *
+     * Usage:
+     *   for (const job of queue.consume("emails")) {
+     *       processEmail(job);
+     *   }
+     *
+     *   // Consume a specific job by ID:
+     *   for (const job of queue.consume("emails", "job-id-123")) {
+     *       processEmail(job);
+     *   }
+     */
+    /**
+     * Long-running async generator that polls the queue continuously.
+     * When empty, sleeps for pollInterval ms before polling again.
+     * No external while-loop or sleep needed.
+     *
+     * @param topic Queue topic (defaults to constructor topic)
+     * @param id Optional job ID — single yield, no polling
+     * @param pollInterval Milliseconds to sleep when queue is empty (default 1000)
+     *
+     * Usage:
+     *   for await (const job of queue.consume("emails")) { ... }
+     *   for await (const job of queue.consume("emails", undefined, 5000)) { ... }
+     */
+    consume(topicOrOptions?: string | ConsumeOptions, id?: string, pollInterval?: number, iterations?: number, batchSize?: number): AsyncGenerator<QueueJob | QueueJob[]>;
+    /**
+     * Pop a specific job by ID from this queue's topic.
+     */
+    popById(id: string): QueueJob | null;
+    /**
+     * Get the configured topic name.
+     */
+    getTopic(): string;
+    getMaxRetries(): number;
+    getRetryBackoff(): number;
+    /**
+     * Resolved reservation/visibility timeout (seconds). <= 0 means the reclaim
+     * is disabled. File + MongoDB backends honour it; RabbitMQ/Kafka delegate to
+     * the broker.
+     */
+    getVisibilityTimeout(): number;
+    /**
+     * 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;
+    /**
+     * Re-queue a job back to the main queue directory with incremented attempts.
+     */
+    _retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
+    /**
+     * Acknowledge a completed job — drop its reservation so the visibility reclaim
+     * never re-delivers it. Routes to the active backend: a reservation-based
+     * external backend (MongoDB) acks there (without this its reserved doc would
+     * be re-delivered after the visibility window); RabbitMQ (no-ack on get) and
+     * Kafka (offset-based) expose no complete(), so the lite path is used and is a
+     * harmless no-op for them since they already acked/own redelivery.
+     */
+    _completeJob(queue: string, job: QueueJob): void;
+}

package/types/core/src/queueBackends/kafkaBackend.d.ts

@@ -0,0 +1,117 @@
+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;
+}
+/**
+ * librdkafka-style SSL/SASL client config (a TLS broker/proxy). Mirrors the
+ * keys produced by Python's `KafkaConnector._security_config`. Every key is
+ * optional — an unset env var leaves the key OUT (librdkafka defaults to the
+ * PLAINTEXT protocol with no SASL).
+ */
+export interface KafkaSecurityConfig {
+    "security.protocol"?: string;
+    "ssl.ca.location"?: string;
+    "sasl.mechanism"?: string;
+    "sasl.username"?: string;
+    "sasl.password"?: string;
+}
+/** Resolved producer/consumer config — brokers, client id, and security keys. */
+export interface KafkaClientConfig extends KafkaSecurityConfig {
+    "bootstrap.servers": string;
+    "client.id": string;
+    "group.id"?: string;
+    "auto.offset.reset"?: string;
+    "enable.auto.commit"?: boolean;
+}
+/**
+ * Build the SSL/SASL client config from the environment (for a TLS broker or
+ * proxy in front of Kafka). Each setting is read from the Tina4-namespaced env
+ * var FIRST (`TINA4_KAFKA_SECURITY_PROTOCOL` …) and falls back to the bare
+ * librdkafka-convention name (`KAFKA_SECURITY_PROTOCOL` …) that many Kafka
+ * deployments already set. Honours security.protocol (e.g. SSL, SASL_SSL),
+ * ssl.ca.location, and optional SASL (mechanism / username / password). Unset
+ * keys are omitted so librdkafka keeps its PLAINTEXT defaults.
+ *
+ * Exported for testing/introspection — and exact parity with Python's
+ * `_security_config` (same key set, same precedence, same omit-when-unset).
+ */
+export declare function kafkaSecurityConfig(env?: NodeJS.ProcessEnv): KafkaSecurityConfig;
+export interface QueueBackend {
+    push(queue: string, payload: unknown, delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}
+/**
+ * Kafka queue backend using raw Kafka protocol over TCP.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the Redis session handler pattern.
+ */
+export declare class KafkaBackend implements QueueBackend {
+    private brokers;
+    private groupId;
+    constructor(config?: KafkaConfig);
+    /**
+     * Resolved connection config — exposed for testing/introspection.
+     */
+    getConfig(): Required<Omit<KafkaConfig, "visibilityTimeout">>;
+    /**
+     * Resolved SSL/SASL client config from the environment (PLAINTEXT default).
+     * Mirrors Python's `KafkaConnector._security_config`.
+     */
+    securityConfig(): KafkaSecurityConfig;
+    /**
+     * Full producer config — brokers + client id + the resolved security block.
+     * The security keys are applied to BOTH producer and consumer (matching
+     * Python's `_connect_confluent`).
+     */
+    producerConfig(): KafkaClientConfig;
+    /**
+     * Full consumer config — brokers + client id + group id + the SAME resolved
+     * security block applied to the producer.
+     */
+    consumerConfig(): KafkaClientConfig;
+    /**
+     * Parse broker string into host:port.
+     */
+    private parseBroker;
+    /**
+     * Execute a Kafka operation synchronously via a child process.
+     *
+     * The wire protocol is hand-rolled (Tina4 is zero-dependency — no npm Kafka
+     * library). Produce uses Produce **v3** carrying a Kafka **v2 RecordBatch**
+     * (magic byte 2) with a **CRC-32C** (Castagnoli) checksum; Fetch uses Fetch
+     * **v4** and parses the v2 RecordBatch out of the response. Both formats are
+     * what a modern KRaft broker (apache/kafka 3.7.0) requires — the old
+     * Produce-v0 / message-format-v0 / CRC=0 batch is rejected by such brokers.
+     */
+    private execSync;
+    /**
+     * Sleep synchronously between produce retries.
+     *
+     * `push()` is synchronous (the whole backend drives its socket through a child
+     * process), so there is no event loop to await on. `Atomics.wait` on a
+     * SharedArrayBuffer is the stdlib way to block a thread for a fixed time --
+     * no dependency, no busy-wait burning CPU.
+     */
+    private static sleepSync;
+    /**
+     * Turn a sentinel from the protocol child into a thrown error, or return.
+     *
+     * The wording matches the Python and PHP backends exactly -- the parity rule
+     * covers user-visible error messages, not just behaviour.
+     */
+    private static assertNoError;
+    push(queue: string, payload: unknown, _delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(_queue: string): number;
+    clear(_queue: string): void;
+}

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -0,0 +1,119 @@
+import { type QueueJob } from "../job.js";
+import { type JobQueueBridge } from "../job.js";
+export declare class LiteBackend {
+    private basePath;
+    private seq;
+    /**
+     * 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;
+    constructor(basePath?: string, visibilityTimeout?: number);
+    private ensureDir;
+    private ensureFailedDir;
+    private ensureReservedDir;
+    private reservedPath;
+    private nowIso;
+    private futureIso;
+    private nextPrefix;
+    push(queue: string, payload: unknown, delay?: number, priority?: number): string;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    pop(queue: string, bridge: JobQueueBridge): QueueJob | null;
+    popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[];
+    /**
+     * Delete a job's reservation record (best-effort).
+     */
+    private clearReservation;
+    /**
+     * 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;
+    private static readonly DEAD_STATES;
+    size(queue: string, status?: string): number;
+    clear(queue: string): number;
+    /**
+     * 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): QueueJob[];
+    /**
+     * 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;
+    deadLetters(queue: string, maxRetries?: number): QueueJob[];
+    purge(queue: string, status: string, maxRetries?: number): number;
+    /**
+     * 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): number;
+    popById(queue: string, id: string): QueueJob | null;
+    /**
+     * 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;
+    /**
+     * Move the job to the dead-letter (failed/) directory. Terminal until a
+     * manual retryFailed()/retry() revives it.
+     */
+    private deadLetter;
+    /**
+     * 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): void;
+    /**
+     * 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;
+}

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -0,0 +1,97 @@
+import type { QueueJob } from "../queue.js";
+export interface MongoConfig {
+    host?: string;
+    port?: number;
+    uri?: string;
+    username?: string;
+    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 {
+    push(queue: string, payload: unknown, delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}
+/**
+ * MongoDB queue backend using the `mongodb` npm package.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the RabbitMQ and Redis patterns.
+ * This keeps the interface synchronous as required by the Queue class.
+ */
+export declare class MongoBackend implements QueueBackend {
+    private host;
+    private port;
+    private uri;
+    private username;
+    private password;
+    private database;
+    private collection;
+    private visibilityTimeout;
+    private maxRetries;
+    constructor(config?: MongoConfig);
+    /**
+     * Resolved connection config — exposed for testing/introspection.
+     */
+    getConfig(): {
+        uri: string;
+        database: string;
+        collection: string;
+        visibilityTimeout: number;
+    };
+    /**
+     * Resolved reservation/visibility timeout (seconds). <= 0 disables the
+     * reclaim. Exposed for testing/introspection.
+     */
+    getVisibilityTimeout(): number;
+    /**
+     * 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;
+    /**
+     * Execute a MongoDB operation synchronously via a child process.
+     */
+    private execSync;
+    push(queue: string, payload: unknown, delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+    /**
+     * Acknowledge a completed job — drop its reservation so the reclaim never
+     * re-delivers it. Without this a Mongo-popped job stayed reserved and was
+     * re-delivered after the visibility window (the redelivery bug).
+     */
+    complete(queue: string, id: string): void;
+    /**
+     * Record a failed attempt: requeue (reset availableAt, ++attempts) while
+     * retries remain, else dead-letter. Mirrors the file/lite backend.
+     */
+    fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff?: number): void;
+    /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+    retry(queue: string, id: string, delaySeconds?: number): void;
+    /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
+    deadLetters(queue: string, maxRetries?: number): QueueJob[];
+    /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */
+    failed(queue: string, maxRetries?: number): QueueJob[];
+    /** Revive dead-lettered jobs under the (possibly raised) limit. Returns count revived. */
+    retryFailed(queue: string, maxRetries?: number): number;
+    /** Remove jobs by status (default: every doc for the topic). Returns count removed. */
+    purge(queue: string, status?: string): number;
+}

package/types/core/src/queueBackends/rabbitmqBackend.d.ts

@@ -0,0 +1,55 @@
+import type { QueueJob } from "../queue.js";
+export interface RabbitMQConfig {
+    host?: string;
+    port?: number;
+    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;
+}
+/**
+ * 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 declare function parseAmqpUrl(url: string): RabbitMQConfig;
+export interface QueueBackend {
+    push(queue: string, payload: unknown, delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}
+/**
+ * RabbitMQ queue backend using raw AMQP 0-9-1 protocol.
+ *
+ * Uses synchronous-style communication by spawning a child process
+ * for each operation, similar to the Redis session handler pattern.
+ * This keeps the interface synchronous as required by the Queue class.
+ */
+export declare class RabbitMQBackend implements QueueBackend {
+    private host;
+    private port;
+    private username;
+    private password;
+    private vhost;
+    constructor(config?: RabbitMQConfig);
+    /**
+     * Resolved connection config — exposed for testing/introspection.
+     */
+    getConfig(): Required<Omit<RabbitMQConfig, "visibilityTimeout">>;
+    /**
+     * Execute an AMQP operation synchronously via a child process.
+     */
+    private execSync;
+    push(queue: string, payload: unknown, _delay?: number): string;
+    pop(queue: string): QueueJob | null;
+    size(queue: string): number;
+    clear(queue: string): void;
+}

package/types/core/src/rateLimiter.d.ts

@@ -0,0 +1,49 @@
+import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
+/** Configuration for the rate limiter */
+export interface RateLimiterConfig {
+    /** Maximum number of requests per window. Default: 100 (or TINA4_RATE_LIMIT env) */
+    limit?: number;
+    /** Window duration in seconds. Default: 60 (or TINA4_RATE_WINDOW env) */
+    windowSeconds?: number;
+    /** Cleanup interval in milliseconds. Default: 60000 (1 minute) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Create a rate limiter middleware using a sliding window algorithm.
+ * Tracks requests per IP in an in-memory Map.
+ *
+ * Response headers:
+ *   X-RateLimit-Limit     — Maximum requests per window
+ *   X-RateLimit-Remaining — Requests remaining in the current window
+ *   X-RateLimit-Reset     — Unix timestamp (seconds) when the window resets
+ *   Retry-After           — Seconds to wait (only when rate limited)
+ *
+ * Returns 429 Too Many Requests when the limit is exceeded.
+ */
+export declare function rateLimiter(config?: RateLimiterConfig): Middleware;
+/** Rate limit check result */
+export interface RateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    reset: number;
+    retryAfter?: number;
+}
+/**
+ * Class-based rate limiter with check/reset/apply methods.
+ * Matches the Python/PHP/Ruby API surface.
+ */
+export declare class RateLimiter {
+    readonly limit: number;
+    readonly window: number;
+    private store;
+    constructor(config?: RateLimiterConfig);
+    /** Check if a request from the given IP is allowed. */
+    check(ip: string): RateLimitResult;
+    /** Clear all tracked request data. */
+    reset(): void;
+    /** Apply rate limiting to a request/response pair. Sets headers and 429 if exceeded. */
+    apply(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response];
+    /** Middleware hook — enforces rate limiting before the route handler. */
+    beforeRateLimit(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response];
+}

package/types/core/src/request.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage, IncomingHttpHeaders } from "node:http";
+import type { Tina4Request, UploadedFile } from "./types.js";
+/**
+ * Wrap Node's `IncomingHttpHeaders` in a Proxy so mixed-case lookups
+ * (`req.headers["Content-Type"]`) work alongside the canonical lowercase
+ * form Node already provides. Parity with PY-10-03 (Python ships a
+ * `CaseInsensitiveDict` for the same reason).
+ *
+ * The raw object is returned as-is by `Object.keys` / iteration — only
+ * string property reads/`in` checks are normalised.
+ */
+export declare function makeCaseInsensitiveHeaders(raw: IncomingHttpHeaders): IncomingHttpHeaders;
+export declare function createRequest(req: IncomingMessage): Tina4Request;
+export declare class PayloadTooLargeError extends Error {
+    statusCode: number;
+    constructor(actual: number, limit: number);
+}
+/**
+ * Parse multipart/form-data body into fields and files.
+ * Zero-dependency implementation.
+ */
+export declare function parseMultipart(body: Buffer, boundary: string): {
+    fields: Record<string, string>;
+    files: Record<string, UploadedFile | UploadedFile[]>;
+};