@ismaelsoilet/synapsejs 1.4.0 → 1.9.0

package/src/runtime/queue-engine.ts

@@ -31,6 +31,7 @@ export interface JobRecord {
   run_at: number;
   created_at: number;
   updated_at: number;
+  locked_at?: number | null;
   last_error: string | null;
 }
 
@@ -38,15 +39,25 @@ export interface QueueEngineOptions {
   /** Path to SQLite database file or ':memory:' */
   dbPath?: string;
   logger?: StructuredLogger;
+  /** Inactivity window in ms before a 'running' job without heartbeat is recovered (default: 300_000ms = 5m) */
+  visibilityTimeoutMs?: number;
+  /** Inactivity window in seconds (alternative to visibilityTimeoutMs) */
+  visibilityTimeoutSeconds?: number;
 }
 
 export class QueueEngine {
   private db: Database;
   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');
+    this.visibilityTimeoutMs =
+      options.visibilityTimeoutMs ??
+      (options.visibilityTimeoutSeconds !== undefined ? options.visibilityTimeoutSeconds * 1000 : 300_000);
     const dbPath = options.dbPath || path.join(process.cwd(), '.synapse/queue.sqlite');
 
     if (dbPath !== ':memory:') {
@@ -80,11 +91,22 @@ export class QueueEngine {
         run_at INTEGER NOT NULL,
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL,
+        locked_at INTEGER,
         last_error TEXT
       );
       CREATE INDEX IF NOT EXISTS idx_synapse_jobs_pending 
       ON _synapse_jobs (status, run_at, priority DESC);
     `);
+    try {
+      this.db.run('ALTER TABLE _synapse_jobs ADD COLUMN locked_at INTEGER;');
+    } catch {
+      // Column already exists
+    }
+    try {
+      this.db.run('CREATE INDEX IF NOT EXISTS idx_synapse_jobs_stale ON _synapse_jobs (status, locked_at);');
+    } catch {
+      // Index already exists
+    }
   }
 
   /**
@@ -123,23 +145,82 @@ export class QueueEngine {
   }
 
   /**
-   * Atomically claims the next pending job eligible for execution.
+   * 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.
    */
-  claimNextJob(): JobRecord | null {
+  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;
+
+    // Fail expired zombie jobs that already exhausted max_attempts
+    this.db
+      .prepare(`
+      UPDATE _synapse_jobs
+      SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = 'Visibility timeout exceeded max attempts'
+      WHERE status = 'running' AND (locked_at IS NULL OR locked_at < ?2) AND attempts >= max_attempts
+    `)
+      .run(now, staleThreshold);
+
     const stmt = this.db.prepare(`
       UPDATE _synapse_jobs
-      SET status = 'running', updated_at = ?1
+      SET status = 'running', locked_at = ?1, updated_at = ?1, attempts = attempts + 1
       WHERE id = (
         SELECT id FROM _synapse_jobs
-        WHERE status = 'pending' AND run_at <= ?1
+        WHERE (status = 'pending' AND run_at <= ?1)
+           OR (status = 'running' AND (locked_at IS NULL OR locked_at < ?2) AND attempts < max_attempts)
         ORDER BY priority DESC, run_at ASC, created_at ASC
         LIMIT 1
       )
       RETURNING *;
     `);
 
-    const row = stmt.get(now) as JobRecord | undefined;
+    const row = stmt.get(now, staleThreshold) as JobRecord | undefined;
     return row || null;
   }
 
@@ -158,7 +239,7 @@ export class QueueEngine {
     }
 
     const jobDef = this.registry.get(job.name);
-    const attempts = job.attempts + 1;
+    const attempts = job.attempts;
     const now = Date.now();
 
     if (!jobDef) {
@@ -166,10 +247,10 @@ export class QueueEngine {
       this.logger.error(errorMsg);
       const updateStmt = this.db.prepare(`
         UPDATE _synapse_jobs
-        SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
-        WHERE id = ?4
+        SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = ?2
+        WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
       `);
-      updateStmt.run(attempts, now, errorMsg, job.id);
+      updateStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
       return true;
     }
 
@@ -180,10 +261,10 @@ export class QueueEngine {
       const errorMsg = `Falha ao desserializar payload JSON do job: ${String(parseErr)}`;
       const updateStmt = this.db.prepare(`
         UPDATE _synapse_jobs
-        SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
-        WHERE id = ?4
+        SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = ?2
+        WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
       `);
-      updateStmt.run(attempts, now, errorMsg, job.id);
+      updateStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
       return true;
     }
 
@@ -199,10 +280,10 @@ export class QueueEngine {
       await jobDef.handler(parsedPayload, actionCtx);
       const completeStmt = this.db.prepare(`
         UPDATE _synapse_jobs
-        SET status = 'completed', attempts = ?1, updated_at = ?2, last_error = NULL
-        WHERE id = ?3
+        SET status = 'completed', locked_at = NULL, updated_at = ?1, last_error = NULL
+        WHERE id = ?2 AND (locked_at = ?3 OR locked_at IS NULL)
       `);
-      completeStmt.run(attempts, now, job.id);
+      completeStmt.run(now, job.id, job.locked_at ?? null);
       return true;
     } catch (handlerErr: unknown) {
       const errorMsg = handlerErr instanceof Error ? handlerErr.message : String(handlerErr);
@@ -214,17 +295,17 @@ export class QueueEngine {
         const nextRunAt = now + backoffMs;
         const retryStmt = this.db.prepare(`
           UPDATE _synapse_jobs
-          SET status = 'pending', attempts = ?1, run_at = ?2, updated_at = ?3, last_error = ?4
-          WHERE id = ?5
+          SET status = 'pending', locked_at = NULL, run_at = ?1, updated_at = ?2, last_error = ?3
+          WHERE id = ?4 AND (locked_at = ?5 OR locked_at IS NULL)
         `);
-        retryStmt.run(attempts, nextRunAt, now, errorMsg, job.id);
+        retryStmt.run(nextRunAt, now, errorMsg, job.id, job.locked_at ?? null);
       } else {
         const failStmt = this.db.prepare(`
           UPDATE _synapse_jobs
-          SET status = 'failed', attempts = ?1, updated_at = ?2, last_error = ?3
-          WHERE id = ?4
+          SET status = 'failed', locked_at = NULL, updated_at = ?1, last_error = ?2
+          WHERE id = ?3 AND (locked_at = ?4 OR locked_at IS NULL)
         `);
-        failStmt.run(attempts, now, errorMsg, job.id);
+        failStmt.run(now, errorMsg, job.id, job.locked_at ?? null);
       }
       return true;
     }

package/src/runtime/rate-limiter.ts

@@ -18,6 +18,8 @@ export interface RateLimitOptions {
   refillRate?: number;
   /** Inactivity window in ms before bucket is evicted (default: 60,000ms = 1m) */
   idleTimeoutMs?: number;
+  /** Maximum tracked buckets in memory before LRU eviction (default: 10,000) */
+  maxBuckets?: number;
 }
 
 export interface RateLimitResult {
@@ -25,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 {
@@ -37,6 +41,7 @@ export class TokenBucketRateLimiter {
   private capacity: number;
   private refillRate: number;
   private idleTimeoutMs: number;
+  private maxBuckets: number;
   private buckets: Map<string, Bucket> = new Map();
   private cleanupTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -47,6 +52,7 @@ export class TokenBucketRateLimiter {
     this.refillRate = options.refillRate ?? (Number.isFinite(envRps) && envRps > 0 ? envRps : 100);
     this.capacity = options.capacity ?? (Number.isFinite(envBurst) && envBurst > 0 ? envBurst : 150);
     this.idleTimeoutMs = options.idleTimeoutMs ?? 60_000;
+    this.maxBuckets = options.maxBuckets ?? 10_000;
 
     // Run background prune of idle buckets every minute
     this.cleanupTimer = setInterval(() => this.pruneIdleBuckets(), this.idleTimeoutMs);
@@ -57,18 +63,36 @@ 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();
     let bucket = this.buckets.get(key);
 
     if (!bucket) {
+      if (this.buckets.size >= this.maxBuckets) {
+        return {
+          allowed: false,
+          limit: this.capacity,
+          remaining: 0,
+          resetMs: Math.max(1000, Math.ceil(this.idleTimeoutMs / 4)),
+          saturated: true
+        };
+      }
       bucket = {
         tokens: this.capacity,
         lastRefill: now,
         lastAccess: now
       };
       this.buckets.set(key, bucket);
+    } else {
+      // Move to end to track recency (LRU)
+      this.buckets.delete(key);
+      this.buckets.set(key, bucket);
     }
 
     // Refill tokens based on elapsed time