tina4-nodejs 3.2.1 → 3.5.0

package/packages/core/src/middleware.ts

@@ -36,6 +36,76 @@ export class MiddlewareChain {
   }
 }
 
+// ── Class-based middleware runner ────────────────────────────────
+
+/**
+ * Runs class-based middleware that follows the beforeX / afterX naming convention.
+ *
+ * Static methods whose names start with "before" are executed by runBefore
+ * (prior to the route handler). Static methods starting with "after" are
+ * executed by runAfter (after the handler).
+ *
+ * Each static method receives (req, res) and returns [req, res].
+ * If a "before" method returns a response whose status code is >= 400
+ * the chain short-circuits and runBefore returns shouldContinue = false.
+ */
+export class MiddlewareRunner {
+  /**
+   * Execute every beforeX static method found on the supplied classes,
+   * in order. Returns the (possibly mutated) request and response pair and a
+   * boolean indicating whether the route handler should still run.
+   *
+   * Short-circuits when a before method sets a status >= 400.
+   */
+  static runBefore(
+    classes: any[],
+    req: Tina4Request,
+    res: Tina4Response,
+  ): [Tina4Request, Tina4Response, boolean] {
+    for (const cls of classes) {
+      const methods = Object.getOwnPropertyNames(cls).filter(
+        (name) => typeof cls[name] === "function" && name.startsWith("before"),
+      );
+      for (const method of methods) {
+        const result = cls[method](req, res);
+        if (Array.isArray(result)) {
+          [req, res] = result as [Tina4Request, Tina4Response];
+        }
+        // Short-circuit if the middleware set an error status
+        if (res.raw.statusCode >= 400 || res.raw.writableEnded) {
+          return [req, res, false];
+        }
+      }
+    }
+    return [req, res, true];
+  }
+
+  /**
+   * Execute every afterX static method found on the supplied classes,
+   * in order. Returns the (possibly mutated) request and response pair.
+   */
+  static runAfter(
+    classes: any[],
+    req: Tina4Request,
+    res: Tina4Response,
+  ): [Tina4Request, Tina4Response] {
+    for (const cls of classes) {
+      const methods = Object.getOwnPropertyNames(cls).filter(
+        (name) => typeof cls[name] === "function" && name.startsWith("after"),
+      );
+      for (const method of methods) {
+        const result = cls[method](req, res);
+        if (Array.isArray(result)) {
+          [req, res] = result as [Tina4Request, Tina4Response];
+        }
+      }
+    }
+    return [req, res];
+  }
+}
+
+// ── Built-in class-based middleware ─────────────────────────────
+
 /** Configuration for the CORS middleware */
 export interface CorsConfig {
   /** Allowed origins. Default: "*" (or TINA4_CORS_ORIGINS env, comma-separated) */
@@ -49,7 +119,7 @@ export interface CorsConfig {
 }
 
 /**
- * Built-in CORS middleware.
+ * Built-in CORS middleware (function form).
  * Reads configuration from env vars if not provided:
  *   TINA4_CORS_ORIGINS — comma-separated list of allowed origins, or "*"
  *   TINA4_CORS_METHODS — comma-separated list of allowed methods
@@ -119,7 +189,167 @@ export function cors(config?: CorsConfig): Middleware {
   };
 }
 
-// Built-in request logger middleware
+/**
+ * Class-based CORS middleware using the before/after convention.
+ * Wraps the same CORS logic as the `cors()` function middleware.
+ *
+ * Usage:
+ *   Router.use(CorsMiddleware);
+ */
+export class CorsMiddleware {
+  static beforeCors(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
+    const originsRaw = process.env.TINA4_CORS_ORIGINS ?? "*";
+    const allowedOrigins = originsRaw.split(",").map((o) => o.trim());
+
+    const allowedMethods = process.env.TINA4_CORS_METHODS
+      ?? "GET, POST, PUT, DELETE, PATCH, OPTIONS";
+
+    const allowedHeaders = process.env.TINA4_CORS_HEADERS
+      ?? "Content-Type, Authorization";
+
+    const maxAge = process.env.TINA4_CORS_MAX_AGE
+      ? parseInt(process.env.TINA4_CORS_MAX_AGE, 10)
+      : 86400;
+
+    const requestOrigin = req.headers.origin ?? "";
+
+    let originHeader: string | undefined;
+    if (allowedOrigins.includes("*")) {
+      originHeader = "*";
+    } else if (allowedOrigins.includes(requestOrigin)) {
+      originHeader = requestOrigin;
+      res.header("Vary", "Origin");
+    }
+
+    if (originHeader) {
+      res.header("Access-Control-Allow-Origin", originHeader);
+      res.header("Access-Control-Allow-Methods", allowedMethods);
+      res.header("Access-Control-Allow-Headers", allowedHeaders);
+
+      if (req.method === "OPTIONS") {
+        res.header("Access-Control-Max-Age", String(maxAge));
+        res(null, 204);
+      }
+    } else if (req.method === "OPTIONS") {
+      res(null, 204);
+    }
+
+    return [req, res];
+  }
+}
+
+/**
+ * Class-based rate limiter middleware using the before/after convention.
+ * Uses the same sliding-window algorithm as the `rateLimiter()` function.
+ *
+ * Reads configuration from env vars:
+ *   TINA4_RATE_LIMIT  — max requests per window (default 100)
+ *   TINA4_RATE_WINDOW — window duration in seconds (default 60)
+ *
+ * Usage:
+ *   Router.use(RateLimiterMiddleware);
+ */
+export class RateLimiterMiddleware {
+  private static store = new Map<string, { timestamps: number[] }>();
+  private static cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  private static ensureCleanup(windowMs: number): void {
+    if (RateLimiterMiddleware.cleanupTimer) return;
+    RateLimiterMiddleware.cleanupTimer = setInterval(() => {
+      const now = Date.now();
+      const cutoff = now - windowMs;
+      for (const [ip, entry] of RateLimiterMiddleware.store) {
+        entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+        if (entry.timestamps.length === 0) {
+          RateLimiterMiddleware.store.delete(ip);
+        }
+      }
+    }, 60_000);
+    if (RateLimiterMiddleware.cleanupTimer.unref) {
+      RateLimiterMiddleware.cleanupTimer.unref();
+    }
+  }
+
+  static beforeRateLimit(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
+    const limit = process.env.TINA4_RATE_LIMIT
+      ? parseInt(process.env.TINA4_RATE_LIMIT, 10)
+      : 100;
+    const windowSeconds = process.env.TINA4_RATE_WINDOW
+      ? parseInt(process.env.TINA4_RATE_WINDOW, 10)
+      : 60;
+    const windowMs = windowSeconds * 1000;
+
+    RateLimiterMiddleware.ensureCleanup(windowMs);
+
+    const now = Date.now();
+    const cutoff = now - windowMs;
+
+    const forwarded = req.headers["x-forwarded-for"];
+    const ip = (typeof forwarded === "string" ? forwarded.split(",")[0].trim() : undefined)
+      ?? req.socket?.remoteAddress
+      ?? "unknown";
+
+    let entry = RateLimiterMiddleware.store.get(ip);
+    if (!entry) {
+      entry = { timestamps: [] };
+      RateLimiterMiddleware.store.set(ip, entry);
+    }
+
+    entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+
+    const resetTimestamp = entry.timestamps.length > 0
+      ? Math.ceil((entry.timestamps[0] + windowMs) / 1000)
+      : Math.ceil((now + windowMs) / 1000);
+
+    const remaining = Math.max(0, limit - entry.timestamps.length);
+
+    res.header("X-RateLimit-Limit", String(limit));
+    res.header("X-RateLimit-Remaining", String(Math.max(0, remaining - 1)));
+    res.header("X-RateLimit-Reset", String(resetTimestamp));
+
+    if (entry.timestamps.length >= limit) {
+      const retryAfter = Math.max(1, resetTimestamp - Math.ceil(now / 1000));
+      res.header("Retry-After", String(retryAfter));
+      res.header("X-RateLimit-Remaining", "0");
+      res({
+        error: "Too Many Requests",
+        statusCode: 429,
+        message: `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+      }, 429);
+      return [req, res];
+    }
+
+    entry.timestamps.push(now);
+    return [req, res];
+  }
+}
+
+/**
+ * Class-based request logger middleware using the before/after convention.
+ * `beforeLog` stamps the request start time.
+ * `afterLog` prints the coloured status line.
+ *
+ * Usage:
+ *   Router.use(RequestLogger);
+ */
+export class RequestLogger {
+  static beforeLog(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
+    (req as any).startTime = Date.now();
+    return [req, res];
+  }
+
+  static afterLog(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
+    const duration = Date.now() - ((req as any).startTime ?? Date.now());
+    const status = res.raw.statusCode;
+    const method = req.method ?? "?";
+    const url = req.url ?? "/";
+    const color = status >= 400 ? "\x1b[31m" : status >= 300 ? "\x1b[33m" : "\x1b[32m";
+    console.log(`  ${color}${status}\x1b[0m ${method} ${url} \x1b[90m${duration}ms\x1b[0m`);
+    return [req, res];
+  }
+}
+
+// Built-in request logger middleware (function form — kept for backwards compat)
 export function requestLogger(): Middleware {
   return (req, res, next) => {
     const start = Date.now();

package/packages/core/src/queue.ts

@@ -7,9 +7,10 @@
  *   - 'file'     — JSON files on disk (default)
  *   - 'rabbitmq' — RabbitMQ via raw TCP (AMQP 0-9-1)
  *   - 'kafka'    — Kafka via raw TCP
+ *   - 'mongodb'  — MongoDB via `mongodb` npm package (also 'mongo')
  *
  * Environment variables:
- *   TINA4_QUEUE_BACKEND — 'file', 'rabbitmq', or 'kafka'
+ *   TINA4_QUEUE_BACKEND — 'file', 'rabbitmq', 'kafka', or 'mongodb'
  *   TINA4_QUEUE_URL     — connection URL for rabbitmq/kafka
  *   TINA4_QUEUE_PATH    — file backend storage path (default: data/queue)
  *
@@ -43,11 +44,37 @@ export interface QueueConfig {
 export interface QueueJob {
   id: string;
   payload: unknown;
-  status: "pending" | "reserved" | "failed" | "dead";
+  status: "pending" | "reserved" | "failed" | "dead" | "completed";
   createdAt: string;
   attempts: number;
   delayUntil: string | null;
   error?: string;
+  /** Mark this job as completed. */
+  complete(): void;
+  /** Mark this job as failed with a reason. */
+  fail(reason?: string): void;
+  /** Reject this job with a reason. Alias for fail(). */
+  reject(reason?: string): void;
+}
+
+/** Create a QueueJob with lifecycle methods bound to a Queue instance. */
+function createJob(data: Omit<QueueJob, "complete" | "fail" | "reject">, queue: Queue, topic: string): QueueJob {
+  const job: QueueJob = {
+    ...data,
+    complete() {
+      job.status = "completed";
+    },
+    fail(reason = "") {
+      job.status = "failed";
+      job.error = reason;
+      job.attempts = (job.attempts || 0) + 1;
+      queue._failJob(topic, job, reason, queue.getMaxRetries());
+    },
+    reject(reason = "") {
+      job.fail(reason);
+    },
+  };
+  return job;
 }
 
 export interface ProcessOptions {
@@ -69,7 +96,7 @@ export class Queue {
   private backendName: string;
   private basePath: string;
   private topic: string;
-  private maxRetries: number;
+  private _maxRetries: number;
   private seq: number = 0;
   private externalBackend: QueueBackendInterface | null = null;
 
@@ -98,7 +125,7 @@ export class Queue {
       ?? process.env.TINA4_QUEUE_PATH
       ?? "data/queue";
     this.topic = resolvedConfig.topic ?? "default";
-    this.maxRetries = resolvedConfig.maxRetries ?? 3;
+    this._maxRetries = resolvedConfig.maxRetries ?? 3;
 
     // Initialize external backends
     if (this.backendName === "rabbitmq") {
@@ -107,6 +134,9 @@ export class Queue {
     } else if (this.backendName === "kafka") {
       const { KafkaBackend } = require("./queueBackends/kafkaBackend.js");
       this.externalBackend = new KafkaBackend();
+    } else if (this.backendName === "mongodb" || this.backendName === "mongo") {
+      const { MongoBackend } = require("./queueBackends/mongoBackend.js");
+      this.externalBackend = new MongoBackend();
     }
   }
 
@@ -169,7 +199,7 @@ export class Queue {
     };
 
     const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
-    writeFileSync(join(dir, `${prefix}_${id}.json`), JSON.stringify(job, null, 2));
+    writeFileSync(join(dir, `${prefix}_${id}.queue-data`), JSON.stringify(job, null, 2));
     return id;
   }
 
@@ -190,7 +220,7 @@ export class Queue {
 
     let files: string[];
     try {
-      files = readdirSync(dir).filter(f => f.endsWith(".json")).sort();
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
     } catch {
       return null;
     }
@@ -249,7 +279,7 @@ export class Queue {
     }
 
     const maxJobs = opts?.maxJobs ?? Infinity;
-    const maxRetries = opts?.maxRetries ?? this.maxRetries;
+    const maxRetries = opts?.maxRetries ?? this._maxRetries;
     let processed = 0;
 
     while (processed < maxJobs) {
@@ -283,7 +313,7 @@ export class Queue {
     const dir = this.ensureDir(q);
     let files: string[];
     try {
-      files = readdirSync(dir).filter(f => f.endsWith(".json"));
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
     } catch {
       return 0;
     }
@@ -312,7 +342,7 @@ export class Queue {
     }
     const dir = this.ensureDir(q);
     try {
-      const files = readdirSync(dir).filter(f => f.endsWith(".json"));
+      const files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
       for (const file of files) {
         unlinkSync(join(dir, file));
       }
@@ -324,7 +354,7 @@ export class Queue {
     const failedDir = join(dir, "failed");
     try {
       if (existsSync(failedDir)) {
-        const files = readdirSync(failedDir).filter(f => f.endsWith(".json"));
+        const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
         for (const file of files) {
           unlinkSync(join(failedDir, file));
         }
@@ -343,7 +373,7 @@ export class Queue {
     const results: QueueJob[] = [];
 
     try {
-      const files = readdirSync(failedDir).filter(f => f.endsWith(".json")).sort();
+      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data")).sort();
       for (const file of files) {
         try {
           const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
@@ -367,7 +397,7 @@ export class Queue {
       const queues = readdirSync(this.basePath);
       for (const queue of queues) {
         const failedDir = join(this.basePath, queue, "failed");
-        const filePath = join(failedDir, `${jobId}.json`);
+        const filePath = join(failedDir, `${jobId}.queue-data`);
 
         if (existsSync(filePath)) {
           const job: QueueJob = JSON.parse(readFileSync(filePath, "utf-8"));
@@ -378,7 +408,7 @@ export class Queue {
           this.seq++;
           const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
           const queueDir = join(this.basePath, queue);
-          writeFileSync(join(queueDir, `${prefix}_${jobId}.json`), JSON.stringify(job, null, 2));
+          writeFileSync(join(queueDir, `${prefix}_${jobId}.queue-data`), JSON.stringify(job, null, 2));
           unlinkSync(filePath);
           return true;
         }
@@ -395,12 +425,12 @@ export class Queue {
    */
   deadLetters(queue?: string, maxRetries?: number): QueueJob[] {
     const q = queue ?? this.topic;
-    const mr = maxRetries ?? this.maxRetries;
+    const mr = maxRetries ?? this._maxRetries;
     const failedDir = this.ensureFailedDir(q);
     const results: QueueJob[] = [];
 
     try {
-      const files = readdirSync(failedDir).filter(f => f.endsWith(".json")).sort();
+      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data")).sort();
       for (const file of files) {
         try {
           const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
@@ -431,12 +461,12 @@ export class Queue {
       // Legacy: purge("queueName", "status", maxRetries?)
       queue = statusOrQueue;
       status = statusOrMaxRetries;
-      mr = maxRetries ?? this.maxRetries;
+      mr = maxRetries ?? this._maxRetries;
     } else {
       // Unified: purge("status") or purge("status", maxRetries)
       queue = this.topic;
       status = statusOrQueue;
-      mr = typeof statusOrMaxRetries === "number" ? statusOrMaxRetries : (maxRetries ?? this.maxRetries);
+      mr = typeof statusOrMaxRetries === "number" ? statusOrMaxRetries : (maxRetries ?? this._maxRetries);
     }
 
     let count = 0;
@@ -444,7 +474,7 @@ export class Queue {
     if (status === "dead") {
       const failedDir = this.ensureFailedDir(queue);
       try {
-        const files = readdirSync(failedDir).filter(f => f.endsWith(".json"));
+        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"));
@@ -462,7 +492,7 @@ export class Queue {
     } else if (status === "failed") {
       const failedDir = this.ensureFailedDir(queue);
       try {
-        const files = readdirSync(failedDir).filter(f => f.endsWith(".json"));
+        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"));
@@ -480,7 +510,7 @@ export class Queue {
     } else {
       const dir = this.ensureDir(queue);
       try {
-        const files = readdirSync(dir).filter(f => f.endsWith(".json"));
+        const files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
         for (const file of files) {
           try {
             const job: QueueJob = JSON.parse(readFileSync(join(dir, file), "utf-8"));
@@ -505,13 +535,13 @@ export class Queue {
    */
   retryFailed(queue?: string, maxRetries?: number): number {
     const q = queue ?? this.topic;
-    const mr = maxRetries ?? this.maxRetries;
+    const mr = maxRetries ?? this._maxRetries;
     const failedDir = this.ensureFailedDir(q);
     const queueDir = this.ensureDir(q);
     let count = 0;
 
     try {
-      const files = readdirSync(failedDir).filter(f => f.endsWith(".json"));
+      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
       for (const file of files) {
         try {
           const filePath = join(failedDir, file);
@@ -526,7 +556,7 @@ export class Queue {
 
           this.seq++;
           const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
-          writeFileSync(join(queueDir, `${prefix}_${job.id}.json`), JSON.stringify(job, null, 2));
+          writeFileSync(join(queueDir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
           unlinkSync(filePath);
           count++;
         } catch {
@@ -540,6 +570,74 @@ export class Queue {
     return count;
   }
 
+  /**
+   * Produce a message onto a topic. Convenience wrapper around push().
+   */
+  produce(topic: string, payload: unknown, delay?: number): string {
+    return this.push(topic, payload, delay);
+  }
+
+  /**
+   * 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);
+   *   }
+   */
+  *consume(topic?: string, id?: string): Generator<QueueJob> {
+    const q = topic ?? this.topic;
+
+    if (id !== undefined) {
+      const raw = this.popById(q, id);
+      if (raw) yield createJob(raw as any, this, q);
+      return;
+    }
+
+    let raw: any;
+    while ((raw = this.pop(q)) !== null) {
+      yield createJob(raw, this, q);
+    }
+  }
+
+  /**
+   * Pop a specific job by ID from the queue.
+   */
+  popById(queue: string, id: string): QueueJob | null {
+    const q = queue ?? this.topic;
+    const dir = this.ensureDir(q);
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+    } catch {
+      return null;
+    }
+
+    for (const file of files) {
+      const filePath = join(dir, file);
+      let job: QueueJob;
+      try {
+        job = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        continue;
+      }
+
+      if (job.status !== "pending") continue;
+      if (job.id === id) {
+        try { unlinkSync(filePath); } catch { /* already consumed */ }
+        return job;
+      }
+    }
+
+    return null;
+  }
+
   /**
    * Get the configured topic name.
    */
@@ -547,15 +645,19 @@ export class Queue {
     return this.topic;
   }
 
+  getMaxRetries(): number {
+    return this._maxRetries;
+  }
+
   /**
    * Move a job to the failed directory.
    */
-  private _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
+  _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
     const failedDir = this.ensureFailedDir(queue);
     job.status = "failed";
     job.attempts = (job.attempts || 0) + 1;
     job.error = error;
 
-    writeFileSync(join(failedDir, `${job.id}.json`), JSON.stringify(job, null, 2));
+    writeFileSync(join(failedDir, `${job.id}.queue-data`), JSON.stringify(job, null, 2));
   }
 }