@ismaelsoilet/synapsejs 1.8.0 → 1.11.1

package/src/runtime/queue-engine.ts

@@ -15,9 +15,12 @@ import {
   type DatabaseClient,
   type JobDefinition,
   type JobEnqueueOptions,
+  JobScheduleError,
+  jobPayloadMatchesSchema,
   type SessionContext,
   type StructuredLogger
 } from '../core';
+import { parseNextCronOccurrence } from '../core/cron-parser';
 
 export interface JobRecord {
   id: string;
@@ -28,6 +31,7 @@ export interface JobRecord {
   attempts: number;
   max_attempts: number;
   backoff_seconds: number;
+  cron?: string | null;
   run_at: number;
   created_at: number;
   updated_at: number;
@@ -50,6 +54,8 @@ export class QueueEngine {
   private registry: Map<string, JobDefinition<unknown>> = new Map();
   private logger: StructuredLogger;
   private visibilityTimeoutMs: number;
+  /** Set at the start of shutdown: no new claim is taken from that moment on. */
+  private claimingStopped = false;
 
   constructor(options: QueueEngineOptions = {}) {
     this.logger = options.logger || createDefaultLogger('QueueEngine');
@@ -86,6 +92,7 @@ export class QueueEngine {
         attempts INTEGER NOT NULL DEFAULT 0,
         max_attempts INTEGER NOT NULL DEFAULT 3,
         backoff_seconds INTEGER NOT NULL DEFAULT 5,
+        cron TEXT,
         run_at INTEGER NOT NULL,
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL,
@@ -100,6 +107,11 @@ export class QueueEngine {
     } catch {
       // Column already exists
     }
+    try {
+      this.db.run('ALTER TABLE _synapse_jobs ADD COLUMN cron TEXT;');
+    } catch {
+      // Column already exists
+    }
     try {
       this.db.run('CREATE INDEX IF NOT EXISTS idx_synapse_jobs_stale ON _synapse_jobs (status, locked_at);');
     } catch {
@@ -112,13 +124,57 @@ export class QueueEngine {
    */
   registerJob<T>(job: JobDefinition<T>): void {
     this.registry.set(job.name, job as JobDefinition<unknown>);
+
+    if (job.cron && job.runAt !== undefined) {
+      throw new JobScheduleError(
+        'CONFLICTING_SCHEDULE',
+        `Job "${job.name}" declares both cron and runAt; choose one schedule.`
+      );
+    }
+
+    const initialPayload = job.cronPayload ? job.cronPayload() : ({} as T);
+
+    if (!jobPayloadMatchesSchema(job.schema, initialPayload)) {
+      throw new JobScheduleError(
+        'INVALID_CRON_PAYLOAD',
+        `Job "${job.name}" has a schema that rejects its initial cron payload.`
+      );
+    }
+
+    if (job.cron) {
+      const existing = this.db
+        .prepare(`SELECT id FROM _synapse_jobs WHERE name = ?1 AND status IN ('pending', 'running') LIMIT 1`)
+        .get(job.name);
+
+      if (!existing) {
+        try {
+          const nextDate = parseNextCronOccurrence(job.cron, new Date());
+          const delaySeconds = Math.max(0, Math.floor((nextDate.getTime() - Date.now()) / 1000));
+          void this.enqueue(job, initialPayload, { delaySeconds }).catch((err) => {
+            this.logger.error(`Falha ao registrar agendamento cron inicial para ${job.name}: ${err}`);
+          });
+        } catch (err) {
+          this.logger.error(`Falha ao registrar agendamento cron inicial para ${job.name}: ${err}`);
+        }
+      }
+    } else if (job.runAt !== undefined) {
+      const existing = this.db
+        .prepare(`SELECT id FROM _synapse_jobs WHERE name = ?1 AND status IN ('pending', 'running') LIMIT 1`)
+        .get(job.name);
+
+      if (!existing) {
+        void this.enqueue(job, initialPayload, { runAt: job.runAt }).catch((err) => {
+          this.logger.error(`Falha ao registrar agendamento runAt para ${job.name}: ${err}`);
+        });
+      }
+    }
   }
 
   /**
    * Enqueues a job for background processing.
    */
   async enqueue<TPayload>(
-    jobOrName: { name: string; retryLimit?: number; backoffSeconds?: number } | string,
+    jobOrName: { name: string; retryLimit?: number; backoffSeconds?: number; cron?: string } | string,
     payload: TPayload,
     options?: JobEnqueueOptions
   ): Promise<string> {
@@ -126,27 +182,78 @@ export class QueueEngine {
     const name = typeof jobOrName === 'string' ? jobOrName : jobOrName.name;
     const maxAttempts = typeof jobOrName === 'object' && jobOrName.retryLimit ? jobOrName.retryLimit : 3;
     const backoffSeconds = typeof jobOrName === 'object' && jobOrName.backoffSeconds ? jobOrName.backoffSeconds : 5;
+    const cron = typeof jobOrName === 'object' && jobOrName.cron ? jobOrName.cron : null;
+
+    if (options?.runAt !== undefined && options?.delaySeconds !== undefined) {
+      throw new JobScheduleError('CONFLICTING_SCHEDULE', `Job "${name}" cannot declare both runAt and delaySeconds.`);
+    }
+
     const priority = options?.priority ?? 0;
     const delaySeconds = options?.delaySeconds ?? 0;
     const now = Date.now();
-    const runAt = now + delaySeconds * 1000;
+    const runAt = options?.runAt ?? now + delaySeconds * 1000;
     const payloadStr = JSON.stringify(payload);
 
     const stmt = this.db.prepare(`
       INSERT INTO _synapse_jobs (
-        id, name, payload, status, priority, attempts, max_attempts, backoff_seconds, run_at, created_at, updated_at
-      ) VALUES (?1, ?2, ?3, 'pending', ?4, 0, ?5, ?6, ?7, ?8, ?8)
+        id, name, payload, status, priority, attempts, max_attempts, backoff_seconds, cron, run_at, created_at, updated_at
+      ) VALUES (?1, ?2, ?3, 'pending', ?4, 0, ?5, ?6, ?7, ?8, ?9, ?9)
     `);
 
-    stmt.run(id, name, payloadStr, priority, maxAttempts, backoffSeconds, runAt, now);
+    stmt.run(id, name, payloadStr, priority, maxAttempts, backoffSeconds, cron, runAt, now);
     return id;
   }
 
+  /**
+   * Stops the engine from claiming any new work. Jobs enqueued by a request that
+   * was in flight remain pending for the next process, instead of being claimed
+   * during a shutdown that is about to close the database.
+   */
+  stopClaiming(): void {
+    this.claimingStopped = true;
+  }
+
+  get isClaimingStopped(): boolean {
+    return this.claimingStopped;
+  }
+
+  /**
+   * Returns every job that is still marked running to the queue. The attempt
+   * counter is left exactly as the interrupted claim left it — releasing must not
+   * consume a second attempt for one claim — and a job that already reached its
+   * maximum is marked failed instead of being handed back for another run.
+   */
+  interruptRunningJobs(): { requeued: number; failed: number } {
+    const now = Date.now();
+
+    const failed = this.db
+      .prepare(`
+        UPDATE _synapse_jobs
+        SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = 'Interrompido pelo encerramento do processo'
+        WHERE status = 'running' AND attempts >= max_attempts
+      `)
+      .run(now);
+
+    const requeued = this.db
+      .prepare(`
+        UPDATE _synapse_jobs
+        SET status = 'pending', locked_at = NULL, updated_at = ?1, last_error = 'Interrompido pelo encerramento do processo'
+        WHERE status = 'running' AND attempts < max_attempts
+      `)
+      .run(now);
+
+    return { requeued: Number(requeued.changes ?? 0), failed: Number(failed.changes ?? 0) };
+  }
+
   /**
    * Atomically claims the next pending job eligible for execution, or recovers
    * any stale 'running' job whose worker has died (visibility timeout exceeded).
    */
   claimNextJob(visibilityTimeoutMs?: number): JobRecord | null {
+    if (this.claimingStopped) {
+      return null;
+    }
+
     const now = Date.now();
     const timeout = visibilityTimeoutMs ?? this.visibilityTimeoutMs;
     const staleThreshold = now - timeout;
@@ -237,6 +344,10 @@ export class QueueEngine {
         WHERE id = ?2 AND (locked_at = ?3 OR locked_at IS NULL)
       `);
       completeStmt.run(now, job.id, job.locked_at ?? null);
+
+      // Reschedule recurring cron job if defined
+      await this.rescheduleCronIfConfigured(jobDef, parsedPayload, now);
+
       return true;
     } catch (handlerErr: unknown) {
       const errorMsg = handlerErr instanceof Error ? handlerErr.message : String(handlerErr);
@@ -259,11 +370,62 @@ export class QueueEngine {
           WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
         `);
         failStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
+
+        // Recurring cron jobs must not be permanently halted when an individual run exhausts retries
+        await this.rescheduleCronIfConfigured(jobDef, parsedPayload, now);
       }
       return true;
     }
   }
 
+  /**
+   * Reschedules the next occurrence of a recurring cron job.
+   */
+  private async rescheduleCronIfConfigured(
+    jobDef: JobDefinition,
+    fallbackPayload: unknown,
+    now: number
+  ): Promise<void> {
+    if (!jobDef.cron) {
+      return;
+    }
+    try {
+      const nextDate = parseNextCronOccurrence(jobDef.cron, new Date(now));
+      const delaySeconds = Math.max(1, Math.floor((nextDate.getTime() - now) / 1000));
+      const nextPayload = jobDef.cronPayload ? jobDef.cronPayload() : fallbackPayload;
+
+      if (!jobPayloadMatchesSchema(jobDef.schema, nextPayload)) {
+        this.logger.error(`Payload da recorrência de ${jobDef.name} não satisfaz o schema; recorrência não agendada.`);
+      } else {
+        await this.enqueue(jobDef, nextPayload, { delaySeconds });
+      }
+    } catch (cronErr) {
+      this.logger.error(`Falha ao reagendar job cron ${jobDef.name}: ${cronErr}`);
+    }
+  }
+
+  /**
+   * Retrieves failed jobs from Dead Letter Queue for inspection.
+   */
+  getDeadLetterJobs(limit = 50): JobRecord[] {
+    return this.db
+      .prepare(`SELECT * FROM _synapse_jobs WHERE status = 'failed' ORDER BY updated_at DESC LIMIT ?1`)
+      .all(limit) as JobRecord[];
+  }
+
+  /**
+   * Resets a failed dead-letter job to pending for re-execution.
+   */
+  retryJob(id: string): boolean {
+    const stmt = this.db.prepare(`
+      UPDATE _synapse_jobs
+      SET status = 'pending', attempts = 0, locked_at = NULL, run_at = ?1, updated_at = ?1
+      WHERE id = ?2 AND status = 'failed'
+    `);
+    const res = stmt.run(Date.now(), id);
+    return Number(res.changes ?? 0) > 0;
+  }
+
   /**
    * Returns a snapshot of job counts by status.
    */

package/src/runtime/rate-limiter.ts

@@ -27,6 +27,8 @@ export interface RateLimitResult {
   limit: number;
   remaining: number;
   resetMs: number;
+  /** True when the refusal is due to a saturated registry rather than an exhausted bucket. */
+  saturated?: boolean;
 }
 
 interface Bucket {
@@ -61,6 +63,11 @@ export class TokenBucketRateLimiter {
 
   /**
    * Consumes `cost` tokens from the bucket for `key`.
+   *
+   * When the registry is saturated with distinct identities the excess is refused
+   * instead of evicting a live bucket: eviction would hand a client that is over its
+   * allowance a fresh one, which is precisely the bypass a spoofed identity stream
+   * is looking for.
    */
   consume(key: string, cost = 1): RateLimitResult {
     const now = Date.now();
@@ -68,10 +75,13 @@ export class TokenBucketRateLimiter {
 
     if (!bucket) {
       if (this.buckets.size >= this.maxBuckets) {
-        const oldest = this.buckets.keys().next().value;
-        if (oldest !== undefined) {
-          this.buckets.delete(oldest);
-        }
+        return {
+          allowed: false,
+          limit: this.capacity,
+          remaining: 0,
+          resetMs: Math.max(1000, Math.ceil(this.idleTimeoutMs / 4)),
+          saturated: true
+        };
       }
       bucket = {
         tokens: this.capacity,

package/src/runtime/security-headers.ts

@@ -0,0 +1,35 @@
+/**
+ * SynapseJS - HTTP Security Headers & Status Mapping Utilities
+ */
+
+export const ERROR_STATUS: Array<{ pattern: RegExp; status: number }> = [
+  { pattern: /^UNAUTHORIZED$/, status: 401 },
+  { pattern: /^FORBIDDEN$/, status: 403 },
+  { pattern: /_NOT_FOUND$/, status: 404 },
+  { pattern: /^(DUPLICATE_|ALREADY_|CONFLICT)/, status: 409 },
+  { pattern: /^(INVALID_|MALFORMED)/, status: 422 },
+  { pattern: /^(NO_DATABASE|PERSISTENCE_FAILED)/, status: 500 },
+  { pattern: /_FAILED$/, status: 500 }
+];
+
+export function httpStatusForError(error: unknown): number {
+  const code = typeof error === 'string' ? error : '';
+
+  for (const entry of ERROR_STATUS) {
+    if (entry.pattern.test(code)) {
+      return entry.status;
+    }
+  }
+
+  return 400;
+}
+
+/** Escapes special HTML characters to prevent Reflected/Stored XSS. */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}