tina4-nodejs 3.10.90 → 3.10.92

package/packages/core/src/middleware.ts

@@ -51,6 +51,30 @@ export class MiddlewareChain {
  * the chain short-circuits and runBefore returns shouldContinue = false.
  */
 export class MiddlewareRunner {
+  /** Globally registered middleware classes (parity with PHP/Ruby/Python orchestrators). */
+  private static globalMiddleware: any[] = [];
+
+  /**
+   * Register a middleware class to run on every request.
+   * Mirrors Tina4\Middleware::use (PHP), Tina4::Middleware.use (Ruby),
+   * and Middleware.use (Python).
+   */
+  static use(cls: any): void {
+    if (!MiddlewareRunner.globalMiddleware.includes(cls)) {
+      MiddlewareRunner.globalMiddleware.push(cls);
+    }
+  }
+
+  /** Return the list of globally registered middleware classes. */
+  static getGlobal(): any[] {
+    return [...MiddlewareRunner.globalMiddleware];
+  }
+
+  /** Clear all globally registered middleware (primarily for tests). */
+  static reset(): void {
+    MiddlewareRunner.globalMiddleware = [];
+  }
+
   /**
    * Execute every beforeX static method found on the supplied classes,
    * in order. Returns the (possibly mutated) request and response pair and a
@@ -244,6 +268,13 @@ export class CorsMiddleware {
 
     return [req, res];
   }
+
+  /**
+   * Check if a request is an OPTIONS preflight.
+   */
+  static isPreflight(method: string): boolean {
+    return method?.toUpperCase() === "OPTIONS";
+  }
 }
 
 /**
@@ -330,6 +361,36 @@ export class RateLimiterMiddleware {
     entry.timestamps.push(now);
     return [req, res];
   }
+
+  /**
+   * Check if an IP is within rate limits without recording a request.
+   * Returns [allowed, info] matching Python/Ruby API.
+   */
+  static check(ip: string): [boolean, { limit: number; remaining: number; reset: number; window: number }] {
+    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;
+    const now = Date.now();
+    const cutoff = now - windowMs;
+
+    let entry = RateLimiterMiddleware.store.get(ip);
+    if (!entry) {
+      entry = { timestamps: [] };
+      RateLimiterMiddleware.store.set(ip, entry);
+    }
+    entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+
+    const remaining = Math.max(0, limit - entry.timestamps.length);
+    const reset = entry.timestamps.length > 0
+      ? Math.ceil((entry.timestamps[0] + windowMs - now) / 1000)
+      : windowSeconds;
+
+    if (entry.timestamps.length >= limit) {
+      return [false, { limit, remaining: 0, reset, window: windowSeconds }];
+    }
+
+    return [true, { limit, remaining: remaining - 1, reset: windowSeconds, window: windowSeconds }];
+  }
 }
 
 /**

package/packages/core/src/queue.ts

@@ -51,6 +51,14 @@ export interface ProcessOptions {
   pollInterval?: number;
   maxJobs?: number;
   maxRetries?: number;
+  batchSize?: number;
+}
+
+export interface ConsumeOptions {
+  batchSize?: number;
+  pollInterval?: number;
+  iterations?: number;
+  id?: string;
 }
 
 export interface QueueBackendInterface {
@@ -139,11 +147,18 @@ export class Queue {
     return this.liteBackend.pop(q, this);
   }
 
+  /**
+   * Pop up to count jobs at once. Returns a partial batch if fewer available.
+   */
+  popBatch(count: number): QueueJob[] {
+    return this.liteBackend.popBatch(this.topic, this, count);
+  }
+
   /**
    * Process jobs from a queue with a handler function.
    */
   process(
-    handler: (job: QueueJob) => Promise<void> | void,
+    handler: (job: QueueJob | QueueJob[]) => Promise<void> | void,
     options?: ProcessOptions,
   ): void {
     const queue = this.topic;
@@ -151,23 +166,44 @@ export class Queue {
 
     const maxJobs = opts?.maxJobs ?? Infinity;
     const maxRetries = opts?.maxRetries ?? this._maxRetries;
+    const batchSize = opts?.batchSize;
     let processed = 0;
 
-    while (processed < maxJobs) {
-      const job = this.pop();
-      if (!job) break;
-      try {
-        const result = handler(job);
-        if (result instanceof Promise) {
-          result.catch((err: Error) => {
-            this._failJob(queue, job, err.message, maxRetries);
-          });
+    if (batchSize && batchSize > 1) {
+      while (processed < maxJobs) {
+        const remaining = maxJobs === Infinity ? batchSize : Math.min(batchSize, maxJobs - processed);
+        const jobs = this.popBatch(remaining);
+        if (jobs.length === 0) break;
+        try {
+          const result = handler(jobs);
+          if (result instanceof Promise) {
+            result.catch((err: Error) => {
+              for (const job of jobs) this._failJob(queue, job, err.message, maxRetries);
+            });
+          }
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          for (const job of jobs) this._failJob(queue, job, message, maxRetries);
+        }
+        processed += jobs.length;
+      }
+    } else {
+      while (processed < maxJobs) {
+        const job = this.pop();
+        if (!job) break;
+        try {
+          const result = handler(job);
+          if (result instanceof Promise) {
+            result.catch((err: Error) => {
+              this._failJob(queue, job, err.message, maxRetries);
+            });
+          }
+          processed++;
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          this._failJob(queue, job, message, maxRetries);
+          processed++;
         }
-        processed++;
-      } catch (err: unknown) {
-        const message = err instanceof Error ? err.message : String(err);
-        this._failJob(queue, job, message, maxRetries);
-        processed++;
       }
     }
   }
@@ -211,7 +247,12 @@ export class Queue {
    * @param delaySeconds - Optional delay before jobs become available
    * @returns true if at least one job was re-queued, false if none found
    */
-  retry(delaySeconds?: number): boolean {
+  retry(jobId?: string, delaySeconds?: number): boolean {
+    if (jobId) {
+      // Retry a specific job by ID
+      return this.liteBackend.retry(this.topic, jobId, delaySeconds);
+    }
+    // Retry all dead-letter jobs
     const deadJobs = this.deadLetters();
     if (deadJobs.length === 0) return false;
     let retried = false;
@@ -246,7 +287,7 @@ export class Queue {
   /**
    * Produce a message onto a topic. Convenience wrapper around push().
    */
-  produce(topic: string, payload: unknown, delay?: number, priority: number = 0): string {
+  produce(topic: string, payload: unknown, priority: number = 0, delay: number = 0): string {
     if (this.externalBackend) {
       return this.externalBackend.push(topic, payload, delay);
     }
@@ -279,29 +320,61 @@ export class Queue {
    *   for await (const job of queue.consume("emails")) { ... }
    *   for await (const job of queue.consume("emails", undefined, 5000)) { ... }
    */
-  async *consume(topic?: string, id?: string, pollInterval: number = 1000, iterations: number = 0): AsyncGenerator<QueueJob> {
-    const q = topic ?? this.topic;
+  async *consume(topicOrOptions?: string | ConsumeOptions, id?: string, pollInterval: number = 1000, iterations: number = 0, batchSize: number = 1): AsyncGenerator<QueueJob | QueueJob[]> {
+    // Support options-object form: consume({ batchSize, pollInterval, iterations, id })
+    let q: string;
+    let resolvedId: string | undefined;
+    let resolvedPollInterval: number;
+    let resolvedIterations: number;
+    let resolvedBatchSize: number;
+
+    if (topicOrOptions !== null && typeof topicOrOptions === "object") {
+      const opts = topicOrOptions as ConsumeOptions;
+      q = this.topic;
+      resolvedId = opts.id;
+      resolvedPollInterval = opts.pollInterval ?? 1000;
+      resolvedIterations = opts.iterations ?? 0;
+      resolvedBatchSize = opts.batchSize ?? batchSize;
+    } else {
+      q = (topicOrOptions as string | undefined) ?? this.topic;
+      resolvedId = id;
+      resolvedPollInterval = pollInterval;
+      resolvedIterations = iterations;
+      resolvedBatchSize = batchSize;
+    }
 
-    if (id !== undefined) {
-      const raw = this.popById(id);
+    if (resolvedId !== undefined) {
+      const raw = this.popById(resolvedId);
       if (raw) yield createJob(raw as any, this);
       return;
     }
 
     // pollInterval=0 → single-pass drain (returns when empty)
     // pollInterval>0 → long-running poll (sleeps when empty, never returns)
-    // iterations>0   → stop after consuming N jobs
+    // iterations>0   → stop after consuming N jobs (or N batches when batchSize>1)
     let consumed = 0;
     while (true) {
-      const raw = this.pop(q) as any;
-      if (raw === null) {
-        if (pollInterval <= 0) break;
-        await new Promise(resolve => setTimeout(resolve, pollInterval));
-        continue;
+      if (resolvedBatchSize && resolvedBatchSize > 1) {
+        const jobs = this.popBatch(resolvedBatchSize);
+        if (jobs.length === 0) {
+          if (resolvedPollInterval <= 0) break;
+          await new Promise(resolve => setTimeout(resolve, resolvedPollInterval));
+          continue;
+        }
+        yield jobs;
+        consumed++;
+        if (resolvedIterations > 0 && consumed >= resolvedIterations) break;
+      } else {
+        const raw = this.pop() as any;
+        if (raw === null) {
+          if (resolvedPollInterval <= 0) break;
+          await new Promise(resolve => setTimeout(resolve, resolvedPollInterval));
+          continue;
+        }
+        yield createJob(raw, this);
+        consumed++;
+        if (resolvedIterations > 0 && consumed >= resolvedIterations) break;
       }
-      yield createJob(raw, this);
-      consumed++;
-      if (iterations > 0 && consumed >= iterations) break;
     }
   }
 

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

@@ -90,6 +90,49 @@ export class LiteBackend {
     return null;
   }
 
+  popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
+    const dir = this.ensureDir(queue);
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
+    } catch {
+      return [];
+    }
+
+    const now = new Date().toISOString();
+    const results: QueueJob[] = [];
+
+    for (const file of files) {
+      if (results.length >= count) break;
+      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.delayUntil && job.delayUntil > now) continue;
+
+      job.status = "reserved";
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      writeFileSync(filePath, JSON.stringify(job, null, 2));
+
+      try {
+        unlinkSync(filePath);
+      } catch {
+        // Already consumed by another worker
+      }
+
+      results.push(createJob(job as any, bridge));
+    }
+
+    return results;
+  }
+
   size(queue: string, status: string = "pending"): number {
     if (status === "failed") {
       const failedDir = this.ensureFailedDir(queue);

package/packages/core/src/rateLimiter.ts

@@ -1,4 +1,4 @@
-import type { Middleware } from "./types.js";
+import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
 
 /** Per-IP sliding window entry */
 interface RateLimitEntry {
@@ -105,3 +105,90 @@ export function rateLimiter(config?: RateLimiterConfig): Middleware {
     next();
   };
 }
+
+/** 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 class RateLimiter {
+  readonly limit: number;
+  readonly window: number;
+  private store = new Map<string, number[]>();
+
+  constructor(config?: RateLimiterConfig) {
+    this.limit = config?.limit
+      ?? (process.env.TINA4_RATE_LIMIT ? parseInt(process.env.TINA4_RATE_LIMIT, 10) : 100);
+    this.window = config?.windowSeconds
+      ?? (process.env.TINA4_RATE_WINDOW ? parseInt(process.env.TINA4_RATE_WINDOW, 10) : 60);
+  }
+
+  /** Check if a request from the given IP is allowed. */
+  check(ip: string): RateLimitResult {
+    const now = Date.now();
+    const windowMs = this.window * 1000;
+    const cutoff = now - windowMs;
+
+    let timestamps = this.store.get(ip);
+    if (!timestamps) {
+      timestamps = [];
+      this.store.set(ip, timestamps);
+    }
+
+    // Prune expired
+    const filtered = timestamps.filter((t) => t > cutoff);
+    this.store.set(ip, filtered);
+
+    const resetTime = filtered.length > 0
+      ? Math.ceil((filtered[0] + windowMs) / 1000)
+      : Math.ceil((now + windowMs) / 1000);
+
+    if (filtered.length >= this.limit) {
+      const retryAfter = Math.max(1, resetTime - Math.ceil(now / 1000));
+      return { allowed: false, limit: this.limit, remaining: 0, reset: resetTime, retryAfter };
+    }
+
+    filtered.push(now);
+    return {
+      allowed: true,
+      limit: this.limit,
+      remaining: this.limit - filtered.length,
+      reset: resetTime,
+    };
+  }
+
+  /** Clear all tracked request data. */
+  reset(): void {
+    this.store.clear();
+  }
+
+  /** Apply rate limiting to a request/response pair. Sets headers and 429 if exceeded. */
+  apply(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response] {
+    const ip = (request as Record<string, unknown>).ip as string ?? "unknown";
+    const result = this.check(ip);
+
+    response.header("X-RateLimit-Limit", String(result.limit));
+    response.header("X-RateLimit-Remaining", String(result.remaining));
+    response.header("X-RateLimit-Reset", String(result.reset));
+
+    if (!result.allowed) {
+      response.header("Retry-After", String(result.retryAfter ?? 1));
+      response({ error: "Too Many Requests", retryAfter: result.retryAfter }, 429);
+    }
+
+    return [request, response];
+  }
+
+  /** Middleware hook — enforces rate limiting before the route handler. */
+  beforeRateLimit(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response] {
+    return this.apply(request, response);
+  }
+}

package/packages/core/src/request.ts

@@ -36,6 +36,29 @@ export function createRequest(req: IncomingMessage): Tina4Request {
     tReq.ip = req.socket?.remoteAddress ?? "127.0.0.1";
   }
 
+  // Add convenience methods
+  tReq.header = function (name: string): string | undefined {
+    const val = req.headers[name.toLowerCase()];
+    if (Array.isArray(val)) return val[0];
+    return val;
+  };
+
+  tReq.bearerToken = function (): string | null {
+    const auth = tReq.header("authorization") ?? "";
+    if (auth.toLowerCase().startsWith("bearer ")) {
+      return auth.slice(7);
+    }
+    return null;
+  };
+
+  tReq.param = function (key: string, defaultValue?: string): string | undefined {
+    return tReq.params[key] ?? tReq.query[key] ?? defaultValue;
+  };
+
+  tReq.parseBody = function (): Promise<void> {
+    return parseBody(tReq);
+  };
+
   return tReq;
 }
 
@@ -50,7 +73,7 @@ export class PayloadTooLargeError extends Error {
   }
 }
 
-export async function parseBody(req: Tina4Request): Promise<void> {
+async function parseBody(req: Tina4Request): Promise<void> {
   const method = req.method?.toUpperCase();
   if (method === "GET" || method === "HEAD" || method === "OPTIONS") return;
 

package/packages/core/src/response.ts

@@ -9,14 +9,67 @@ const _frondCache = new Map<string, InstanceType<any>>();
 /** Default templates directory — set via setDefaultTemplatesDir(). */
 let _defaultTemplatesDir: string | null = null;
 
+/** Global user Frond engine — set via setFrond(). */
+let _globalFrond: InstanceType<any> | null = null;
+
+/** Singleton framework Frond engine for built-in templates. */
+let _frameworkFrond: InstanceType<any> | null = null;
+
 /**
- * Set the default templates directory for render()/template().
+ * Set the default templates directory for render().
  * Called by server.ts during startup.
  */
 export function setDefaultTemplatesDir(dir: string): void {
   _defaultTemplatesDir = dir;
 }
 
+/**
+ * Return the global Frond engine, creating a default if needed.
+ */
+export async function getFrond(): Promise<InstanceType<any>> {
+  if (_globalFrond) return _globalFrond;
+  const dir = _defaultTemplatesDir ?? nodePath.resolve(process.cwd(), "src/templates");
+  let engine = _frondCache.get(dir);
+  if (!engine) {
+    const { Frond } = await import("@tina4/frond");
+    engine = new Frond(dir);
+    _frondCache.set(dir, engine);
+  }
+  _globalFrond = engine;
+  return engine;
+}
+
+/**
+ * Return the singleton Frond engine for built-in framework templates.
+ * Syncs custom filters/globals from the user engine.
+ */
+export async function getFrameworkFrond(): Promise<InstanceType<any> | null> {
+  const frameworkDir = nodePath.resolve(nodePath.dirname(import.meta.url.replace("file://", "")), "..", "templates");
+  if (!_frameworkFrond && fs.existsSync(frameworkDir)) {
+    try {
+      const { Frond } = await import("@tina4/frond");
+      _frameworkFrond = new Frond(frameworkDir);
+    } catch { return null; }
+  }
+  // Sync custom filters/globals from the user engine
+  if (_frameworkFrond && _globalFrond) {
+    if (typeof _globalFrond._filters === "object") {
+      Object.assign(_frameworkFrond._filters ??= {}, _globalFrond._filters);
+    }
+    if (typeof _globalFrond._globals === "object") {
+      Object.assign(_frameworkFrond._globals ??= {}, _globalFrond._globals);
+    }
+  }
+  return _frameworkFrond;
+}
+
+/**
+ * Register a pre-configured Frond engine for response.render().
+ */
+export function setFrond(engine: InstanceType<any>): void {
+  _globalFrond = engine;
+}
+
 /**
  * Creates a callable response object.
  *
@@ -233,15 +286,6 @@ export function createResponse(res: ServerResponse): Tina4Response {
     }
   };
 
-  response.template = async function (
-    name: string,
-    data?: Record<string, unknown>,
-    status?: number,
-    templateDir?: string,
-  ): Promise<Tina4Response> {
-    return response.render(name, data, status, templateDir);
-  };
-
   /**
    * Stream response from an async generator for Server-Sent Events (SSE).
    *

package/packages/core/src/router.ts

@@ -54,6 +54,12 @@ export class RouteRef {
     this.route.cached = true;
     return this;
   }
+
+  /** Append middleware class(es) to this route. */
+  middleware(...middlewareClasses: Middleware[]): this {
+    this.route.middlewares = [...(this.route.middlewares ?? []), ...middlewareClasses];
+    return this;
+  }
 }
 
 export interface RouteInfo {
@@ -194,7 +200,7 @@ export class Router {
   /**
    * Match a request method + pathname to a registered route.
    */
-  match(method: string, pathname: string): MatchResult | null {
+  match(method: string, path: string): MatchResult | null {
     const upperMethod = method.toUpperCase();
 
     // Try exact method first, then ANY routes are already registered under each method
@@ -202,7 +208,7 @@ export class Router {
     if (!routes) return null;
 
     for (const route of routes) {
-      const match = route.regex.exec(pathname);
+      const match = route.regex.exec(path);
       if (match) {
         const params: Record<string, string> = {};
         for (let i = 0; i < route.paramNames.length; i++) {
@@ -310,46 +316,58 @@ export class Router {
   //   Router.get("/path", handler)
   // as an alternative to importing the top-level get(), post(), etc.
 
+  /**
+   * Register a route for a specific HTTP method.
+   * Core registration method — all convenience methods delegate here.
+   */
+  static add(method: string, path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    const m = method.toUpperCase();
+    if (m === "ANY") {
+      return defaultRouter.any(path, handler, middleware, swaggerMeta);
+    }
+    return defaultRouter.addRoute({ method: m, pattern: path, handler, middlewares: middleware, meta: swaggerMeta, template });
+  }
+
   /**
    * Register a GET route on the default global router.
    */
-  static get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.get(path, handler, middlewares, meta);
+  static get(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.get(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a POST route on the default global router.
    */
-  static post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.post(path, handler, middlewares, meta);
+  static post(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.post(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PUT route on the default global router.
    */
-  static put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.put(path, handler, middlewares, meta);
+  static put(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.put(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PATCH route on the default global router.
    */
-  static patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.patch(path, handler, middlewares, meta);
+  static patch(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.patch(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a DELETE route on the default global router.
    */
-  static delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.delete(path, handler, middlewares, meta);
+  static delete(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.delete(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a route that matches ANY HTTP method on the default global router.
    */
-  static any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.any(path, handler, middlewares, meta);
+  static any(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.any(path, handler, middleware, swaggerMeta);
   }
 
   /**