s3db.js 13.6.0 → 14.0.2

package/src/plugins/s3-queue.plugin.js

@@ -1,6 +1,8 @@
 import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 import { idGenerator } from "../concerns/id.js";
+import { resolveResourceName } from "./concerns/resource-names.js";
+import { QueueError } from "./queue.errors.js";
 
 /**
  * S3QueuePlugin - Distributed Queue System with ETag-based Atomicity
@@ -64,24 +66,58 @@ export class S3QueuePlugin extends Plugin {
   constructor(options = {}) {
     super(options);
 
+    const resourceNamesOption = options.resourceNames || {};
     if (!options.resource) {
-      throw new Error('S3QueuePlugin requires "resource" option');
+      throw new QueueError('S3QueuePlugin requires "resource" option', {
+        pluginName: 'S3QueuePlugin',
+        operation: 'constructor',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide the target resource name: new S3QueuePlugin({ resource: "orders", ... }).'
+      });
     }
 
     this.config = {
+      ...options,
       resource: options.resource,
-      visibilityTimeout: options.visibilityTimeout || 30000,     // 30 seconds
-      pollInterval: options.pollInterval || 1000,                 // 1 second
-      maxAttempts: options.maxAttempts || 3,
-      concurrency: options.concurrency || 1,
-      deadLetterResource: options.deadLetterResource || null,
+      visibilityTimeout: options.visibilityTimeout ?? 30000,     // 30 seconds
+      pollInterval: options.pollInterval ?? 1000,                 // 1 second
+      maxAttempts: options.maxAttempts ?? 3,
+      concurrency: options.concurrency ?? 1,
+      deadLetterResource: options.deadLetterResource ?? null,
       autoStart: options.autoStart !== false,
       onMessage: options.onMessage,
       onError: options.onError,
       onComplete: options.onComplete,
-      verbose: options.verbose || false,
-      ...options
+      verbose: options.verbose ?? false
+    };
+    this.config.pollBatchSize = options.pollBatchSize ?? Math.max((this.config.concurrency || 1) * 4, 16);
+    this.config.recoveryInterval = options.recoveryInterval ?? 5000;
+    this.config.recoveryBatchSize = options.recoveryBatchSize ?? Math.max((this.config.concurrency || 1) * 2, 10);
+    this.config.processedCacheTTL = options.processedCacheTTL ?? 30000;
+    this.config.maxPollInterval = options.maxPollInterval ?? this.config.pollInterval;
+
+    this._queueResourceDescriptor = {
+      defaultName: `plg_s3queue_${this.config.resource}_queue`,
+      override: resourceNamesOption.queue || options.queueResource
     };
+    this.queueResourceName = this._resolveQueueResourceName();
+    this.config.queueResourceName = this.queueResourceName;
+
+    if (this.config.deadLetterResource) {
+      this._deadLetterDescriptor = {
+        defaultName: `plg_s3queue_${this.config.resource}_dead`,
+        override: resourceNamesOption.deadLetter || this.config.deadLetterResource
+      };
+    } else {
+      this._deadLetterDescriptor = null;
+    }
+
+    this.deadLetterResourceName = this._resolveDeadLetterResourceName();
+    this.config.deadLetterResource = this.deadLetterResourceName;
+
+    this.queueResourceAlias = options.queueResource || `${this.config.resource}_queue`;
+    this.deadLetterResourceAlias = options.deadLetterResource || null;
 
     this.queueResource = null;       // Resource: <resource>_queue
     this.targetResource = null;      // Resource original do usuário
@@ -92,20 +128,63 @@ export class S3QueuePlugin extends Plugin {
 
     // Deduplication cache to prevent S3 eventual consistency issues
     // Tracks recently processed messages to avoid reprocessing
-    this.processedCache = new Map(); // queueId -> timestamp
+    this.processedCache = new Map(); // queueId -> expiresAt
     this.cacheCleanupInterval = null;
     this.lockCleanupInterval = null;
+    this.messageLocks = new Map();
+    this._lastRecovery = 0;
+    this._recoveryInFlight = false;
+  }
+
+  _resolveQueueResourceName() {
+    return resolveResourceName('s3queue', this._queueResourceDescriptor, {
+      namespace: this.namespace
+    });
+  }
+
+  _resolveDeadLetterResourceName() {
+    if (!this._deadLetterDescriptor) return null;
+    const { override, defaultName } = this._deadLetterDescriptor;
+    if (override) {
+      // Honor explicit overrides verbatim unless user opted into plg_* naming.
+      if (override.startsWith('plg_')) {
+        return resolveResourceName('s3queue', { override }, {
+          namespace: this.namespace,
+          applyNamespaceToOverrides: true
+        });
+      }
+      return override;
+    }
+    return resolveResourceName('s3queue', { defaultName }, {
+      namespace: this.namespace
+    });
+  }
+
+  onNamespaceChanged() {
+    if (!this._queueResourceDescriptor) return;
+    this.queueResourceName = this._resolveQueueResourceName();
+    this.config.queueResourceName = this.queueResourceName;
+    this.deadLetterResourceName = this._resolveDeadLetterResourceName();
+    this.config.deadLetterResource = this.deadLetterResourceName;
   }
 
   async onInstall() {
     // Get target resource
     this.targetResource = this.database.resources[this.config.resource];
     if (!this.targetResource) {
-      throw new Error(`S3QueuePlugin: resource '${this.config.resource}' not found`);
+      throw new QueueError(`Resource '${this.config.resource}' not found`, {
+        pluginName: 'S3QueuePlugin',
+        operation: 'onInstall',
+        resourceName: this.config.resource,
+        statusCode: 404,
+        retriable: false,
+        suggestion: 'Create the resource before installing S3QueuePlugin or update the plugin configuration.',
+        availableResources: Object.keys(this.database.resources || {})
+      });
     }
 
     // Create queue metadata resource
-    const queueName = `${this.config.resource}_queue`;
+    const queueName = this.queueResourceName;
     const [ok, err] = await tryFn(() =>
       this.database.createResource({
         name: queueName,
@@ -133,11 +212,30 @@ export class S3QueuePlugin extends Plugin {
       })
     );
 
-    if (!ok && !this.database.resources[queueName]) {
-      throw new Error(`Failed to create queue resource: ${err?.message}`);
+    if (ok) {
+      this.queueResource = this.database.resources[queueName];
+    } else {
+      this.queueResource = this.database.resources[queueName];
+      if (!this.queueResource) {
+        throw new QueueError(`Failed to create queue resource: ${err?.message}`, {
+          pluginName: 'S3QueuePlugin',
+          operation: 'createQueueResource',
+          queueName,
+          statusCode: 500,
+          retriable: false,
+          suggestion: 'Check database permissions and ensure createResource() was successful.',
+          original: err
+        });
+      }
     }
+    this.queueResourceName = this.queueResource.name;
 
-    this.queueResource = this.database.resources[queueName];
+    if (this.queueResourceAlias) {
+      const existing = this.database.resources[this.queueResourceAlias];
+      if (!existing || existing === this.queueResource) {
+        this.database.resources[this.queueResourceAlias] = this.queueResource;
+      }
+    }
 
     // Locks are now managed by PluginStorage with TTL - no Resource needed
     // Lock acquisition is handled via storage.acquireLock() with automatic expiration
@@ -220,6 +318,17 @@ export class S3QueuePlugin extends Plugin {
     resource.stopProcessing = async function() {
       return await plugin.stopProcessing();
     };
+
+    /**
+     * Extend visibility timeout for a specific queue entry
+     */
+    resource.extendQueueVisibility = async function(queueId, extraMilliseconds) {
+      return await plugin.extendVisibility(queueId, extraMilliseconds);
+    };
+
+    resource.clearQueueCache = async function() {
+      plugin.clearProcessedCache();
+    };
   }
 
   async startProcessing(handler = null, options = {}) {
@@ -232,7 +341,14 @@ export class S3QueuePlugin extends Plugin {
 
     const messageHandler = handler || this.config.onMessage;
     if (!messageHandler) {
-      throw new Error('S3QueuePlugin: onMessage handler required');
+      throw new QueueError('onMessage handler required', {
+        pluginName: 'S3QueuePlugin',
+        operation: 'startProcessing',
+        queueName: this.queueResourceName,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Pass a handler: resource.startProcessing(async msg => {...}) or configure onMessage in plugin options.'
+      });
     }
 
     this.isRunning = true;
@@ -241,16 +357,17 @@ export class S3QueuePlugin extends Plugin {
     // Start cache cleanup (every 5 seconds, remove entries older than 30 seconds)
     this.cacheCleanupInterval = setInterval(() => {
       const now = Date.now();
-      const maxAge = 30000; // 30 seconds
+      const ttl = this.config.processedCacheTTL;
 
-      for (const [queueId, timestamp] of this.processedCache.entries()) {
-        if (now - timestamp > maxAge) {
+      for (const [queueId, expiresAt] of this.processedCache.entries()) {
+        if (expiresAt <= now || expiresAt - now > ttl * 4) {
           this.processedCache.delete(queueId);
         }
       }
     }, 5000);
 
     // Lock cleanup no longer needed - TTL handles expiration automatically
+    this._lastRecovery = 0;
 
     // Start N workers
     for (let i = 0; i < concurrency; i++) {
@@ -294,24 +411,28 @@ export class S3QueuePlugin extends Plugin {
 
   createWorker(handler, workerIndex) {
     return (async () => {
+      let idleStreak = 0;
       while (this.isRunning) {
         try {
           // Try to claim a message
           const message = await this.claimMessage();
 
           if (message) {
+            idleStreak = 0;
             // Process the claimed message
             await this.processMessage(message, handler);
           } else {
             // No messages available, wait before polling again
-            await new Promise(resolve => setTimeout(resolve, this.config.pollInterval));
+            idleStreak = Math.min(idleStreak + 1, 10);
+            const delay = this._computeIdleDelay(idleStreak);
+            await this._sleep(delay);
           }
         } catch (error) {
           if (this.config.verbose) {
             console.error(`[Worker ${workerIndex}] Error:`, error.message);
           }
           // Wait a bit before retrying on error
-          await new Promise(resolve => setTimeout(resolve, 1000));
+          await this._sleep(1000);
         }
       }
     })();
@@ -320,10 +441,15 @@ export class S3QueuePlugin extends Plugin {
   async claimMessage() {
     const now = Date.now();
 
+    await this.recoverStalledMessages(now);
+
     // Query for available messages
     const [ok, err, messages] = await tryFn(() =>
       this.queueResource.query({
-        status: 'pending'
+        status: 'pending',
+        visibleAt: { '<=': now }
+      }, {
+        limit: this.config.pollBatchSize
       })
     );
 
@@ -352,40 +478,63 @@ export class S3QueuePlugin extends Plugin {
    * Acquire a distributed lock using PluginStorage TTL
    * This ensures only one worker can claim a message at a time
    */
+  _lockNameForMessage(messageId) {
+    return `msg-${messageId}`;
+  }
+
   async acquireLock(messageId) {
     const storage = this.getStorage();
-    const lockKey = `msg-${messageId}`;
+    const lockName = this._lockNameForMessage(messageId);
 
     try {
-      const lock = await storage.acquireLock(lockKey, {
+      const lock = await storage.acquireLock(lockName, {
         ttl: 5, // 5 seconds
         timeout: 0, // Don't wait if locked
         workerId: this.workerId
       });
 
-      return lock !== null;
+      if (lock) {
+        this.messageLocks.set(lock.name, lock);
+      }
+
+      return lock;
     } catch (error) {
       // On any error, skip this message
       if (this.config.verbose) {
         console.log(`[acquireLock] Error: ${error.message}`);
       }
-      return false;
+      return null;
     }
   }
 
   /**
    * Release a distributed lock via PluginStorage
    */
-  async releaseLock(messageId) {
+  async releaseLock(lockOrMessageId) {
     const storage = this.getStorage();
-    const lockKey = `msg-${messageId}`;
+    let lock = null;
+
+    if (lockOrMessageId && typeof lockOrMessageId === 'object') {
+      lock = lockOrMessageId;
+    } else {
+      const lockName = this._lockNameForMessage(lockOrMessageId);
+      lock = this.messageLocks.get(lockName) || null;
+    }
+
+    if (!lock) {
+      return;
+    }
 
     try {
-      await storage.releaseLock(lockKey);
+      await storage.releaseLock(lock);
     } catch (error) {
       // Ignore errors on release (lock may have expired or been cleaned up)
       if (this.config.verbose) {
-        console.log(`[releaseLock] Failed to release lock for ${messageId}: ${error.message}`);
+        console.log(`[releaseLock] Failed to release lock '${lock.name}': ${error.message}`);
+      }
+    } finally {
+      if (lock?.name) {
+        this.messageLocks.delete(lock.name);
       }
     }
   }
@@ -404,28 +553,29 @@ export class S3QueuePlugin extends Plugin {
 
     // Try to acquire distributed lock for cache check
     // This prevents race condition where multiple workers check cache simultaneously
-    const lockAcquired = await this.acquireLock(msg.id);
+    const lock = await this.acquireLock(msg.id);
 
-    if (!lockAcquired) {
+    if (!lock) {
       // Another worker is checking/claiming this message, skip it
       return null;
     }
 
-    // Check deduplication cache (protected by lock)
-    if (this.processedCache.has(msg.id)) {
-      await this.releaseLock(msg.id);
-      if (this.config.verbose) {
-        console.log(`[attemptClaim] Message ${msg.id} already processed (in cache)`);
+    try {
+      // Check deduplication cache (protected by lock)
+      const alreadyProcessed = await this._isRecentlyProcessed(msg.id);
+      if (alreadyProcessed) {
+        if (this.config.verbose) {
+          console.log(`[attemptClaim] Message ${msg.id} already processed (in cache)`);
+        }
+        return null;
       }
-      return null;
-    }
 
-    // Add to cache immediately (while still holding lock)
-    // This prevents other workers from claiming this message
-    this.processedCache.set(msg.id, Date.now());
-
-    // Release lock now that cache is updated
-    await this.releaseLock(msg.id);
+      // Add to cache immediately (while still holding lock)
+      // This prevents other workers from claiming this message
+      await this._markMessageProcessed(msg.id);
+    } finally {
+      await this.releaseLock(lock);
+    }
 
     // Fetch the message with ETag (query doesn't return _etag)
     const [okGet, errGet, msgWithETag] = await tryFn(() =>
@@ -434,7 +584,7 @@ export class S3QueuePlugin extends Plugin {
 
     if (!okGet || !msgWithETag) {
       // Message was deleted or not found - remove from cache
-      this.processedCache.delete(msg.id);
+      await this._clearProcessedMarker(msg.id);
       if (this.config.verbose) {
         console.log(`[attemptClaim] Message ${msg.id} not found or error: ${errGet?.message}`);
       }
@@ -575,6 +725,7 @@ export class S3QueuePlugin extends Plugin {
       status: 'failed',
       error
     });
+    await this._clearProcessedMarker(queueId);
   }
 
   async retryMessage(queueId, attempts, error) {
@@ -588,7 +739,7 @@ export class S3QueuePlugin extends Plugin {
     });
 
     // Remove from cache so it can be retried
-    this.processedCache.delete(queueId);
+    await this._clearProcessedMarker(queueId);
   }
 
   async moveToDeadLetter(queueId, record, error) {
@@ -614,22 +765,13 @@ export class S3QueuePlugin extends Plugin {
     });
 
     // Note: message already in cache from attemptClaim()
+    await this._clearProcessedMarker(queueId);
   }
 
   async getStats() {
-    const [ok, err, allMessages] = await tryFn(() =>
-      this.queueResource.list()
-    );
-
-    if (!ok) {
-      if (this.config.verbose) {
-        console.warn('[S3QueuePlugin] Failed to get stats:', err.message);
-      }
-      return null;
-    }
-
+    const statusKeys = ['pending', 'processing', 'completed', 'failed', 'dead'];
     const stats = {
-      total: allMessages.length,
+      total: 0,
       pending: 0,
       processing: 0,
       completed: 0,
@@ -637,9 +779,29 @@ export class S3QueuePlugin extends Plugin {
       dead: 0
     };
 
-    for (const msg of allMessages) {
-      if (stats[msg.status] !== undefined) {
-        stats[msg.status]++;
+    const counts = await Promise.all(
+      statusKeys.map(status => tryFn(() => this.queueResource.count({ status })))
+    );
+
+    let derivedTotal = 0;
+
+    counts.forEach(([ok, err, count], index) => {
+      const status = statusKeys[index];
+      if (ok) {
+        stats[status] = count || 0;
+        derivedTotal += count || 0;
+      } else if (this.config.verbose) {
+        console.warn(`[S3QueuePlugin] Failed to count status '${status}':`, err?.message);
+      }
+    });
+
+    const [totalOk, totalErr, totalCount] = await tryFn(() => this.queueResource.count());
+    if (totalOk) {
+      stats.total = totalCount || 0;
+    } else {
+      stats.total = derivedTotal;
+      if (this.config.verbose) {
+        console.warn('[S3QueuePlugin] Failed to count total messages:', totalErr?.message);
       }
     }
 
@@ -647,9 +809,12 @@ export class S3QueuePlugin extends Plugin {
   }
 
   async createDeadLetterResource() {
+    if (!this.config.deadLetterResource) return;
+
+    const resourceName = this.config.deadLetterResource;
     const [ok, err] = await tryFn(() =>
       this.database.createResource({
-        name: this.config.deadLetterResource,
+        name: resourceName,
         attributes: {
           id: 'string|required',
           originalId: 'string|required',
@@ -664,12 +829,246 @@ export class S3QueuePlugin extends Plugin {
       })
     );
 
-    if (ok || this.database.resources[this.config.deadLetterResource]) {
-      this.deadLetterResourceObj = this.database.resources[this.config.deadLetterResource];
+    if (ok) {
+      this.deadLetterResourceObj = this.database.resources[resourceName];
+    } else {
+      this.deadLetterResourceObj = this.database.resources[resourceName];
+      if (!this.deadLetterResourceObj) {
+        throw err;
+      }
+    }
+
+    this.deadLetterResourceName = this.deadLetterResourceObj.name;
+
+    if (this.deadLetterResourceAlias) {
+      const existing = this.database.resources[this.deadLetterResourceAlias];
+      if (!existing || existing === this.deadLetterResourceObj) {
+        this.database.resources[this.deadLetterResourceAlias] = this.deadLetterResourceObj;
+      }
+    }
+
+    if (this.config.verbose) {
+      console.log(`[S3QueuePlugin] Dead letter queue ready: ${this.deadLetterResourceName}`);
+    }
+  }
+
+  async extendVisibility(queueId, extraMilliseconds) {
+    if (!queueId || !extraMilliseconds || extraMilliseconds <= 0) {
+      return false;
+    }
 
+    const [okGet, errGet, entry] = await tryFn(() => this.queueResource.get(queueId));
+    if (!okGet || !entry) {
       if (this.config.verbose) {
-        console.log(`[S3QueuePlugin] Dead letter queue created: ${this.config.deadLetterResource}`);
+        console.warn('[S3QueuePlugin] extendVisibility failed to load entry:', errGet?.message);
       }
+      return false;
+    }
+
+    const baseTime = Math.max(entry.visibleAt || 0, Date.now());
+    const newVisibleAt = baseTime + extraMilliseconds;
+
+    const [okUpdate, errUpdate, result] = await tryFn(() =>
+      this.queueResource.updateConditional(queueId, {
+        visibleAt: newVisibleAt,
+        claimedAt: entry.claimedAt || Date.now()
+      }, {
+        ifMatch: entry._etag
+      })
+    );
+
+    if (!okUpdate || !result?.success) {
+      if (this.config.verbose) {
+        console.warn('[S3QueuePlugin] extendVisibility conditional update failed:', errUpdate?.message || result?.error);
+      }
+      return false;
+    }
+
+    return true;
+  }
+
+  async recoverStalledMessages(now) {
+    if (this.config.recoveryInterval <= 0) return;
+    if (this._recoveryInFlight) return;
+    if (this._lastRecovery && now - this._lastRecovery < this.config.recoveryInterval) {
+      return;
+    }
+
+    this._recoveryInFlight = true;
+    this._lastRecovery = now;
+
+    try {
+      const [ok, err, candidates] = await tryFn(() =>
+        this.queueResource.query({
+          status: 'processing',
+          visibleAt: { '<=': now }
+        }, {
+          limit: this.config.recoveryBatchSize
+        })
+      );
+
+      if (!ok) {
+        if (this.config.verbose) {
+          console.warn('[S3QueuePlugin] Failed to query stalled messages:', err?.message);
+        }
+        return;
+      }
+
+      if (!candidates || candidates.length === 0) {
+        return;
+      }
+
+      for (const candidate of candidates) {
+        await this._recoverSingleMessage(candidate, now);
+      }
+    } finally {
+      this._recoveryInFlight = false;
+    }
+  }
+
+  async _recoverSingleMessage(candidate, now) {
+    const [okGet, errGet, queueEntry] = await tryFn(() => this.queueResource.get(candidate.id));
+    if (!okGet || !queueEntry) {
+      if (this.config.verbose) {
+        console.warn('[S3QueuePlugin] Failed to load stalled message:', errGet?.message);
+      }
+      return;
+    }
+
+    if (queueEntry.status !== 'processing' || queueEntry.visibleAt > now) {
+      return;
+    }
+
+    // If max attempts reached, move to dead letter
+    if (queueEntry.maxAttempts !== undefined && queueEntry.attempts >= queueEntry.maxAttempts) {
+      let record = null;
+      const [okRecord, , original] = await tryFn(() => this.targetResource.get(queueEntry.originalId));
+      if (okRecord && original) {
+        record = original;
+      } else {
+        record = { id: queueEntry.originalId, _missing: true };
+      }
+
+      await this.moveToDeadLetter(queueEntry.id, record, 'visibility-timeout exceeded max attempts');
+      this.emit('plg:s3-queue:message-dead', {
+        queueId: queueEntry.id,
+        originalId: queueEntry.originalId,
+        error: 'visibility-timeout exceeded max attempts'
+      });
+      return;
+    }
+
+    const [okUpdate, errUpdate, result] = await tryFn(() =>
+      this.queueResource.updateConditional(queueEntry.id, {
+        status: 'pending',
+        visibleAt: now,
+        claimedBy: null,
+        claimedAt: null,
+        error: 'Recovered after visibility timeout'
+      }, {
+        ifMatch: queueEntry._etag
+      })
+    );
+
+    if (!okUpdate || !result?.success) {
+      if (this.config.verbose) {
+        console.warn('[S3QueuePlugin] Failed to recover message:', errUpdate?.message || result?.error);
+      }
+      return;
+    }
+
+    await this._clearProcessedMarker(queueEntry.id);
+    this.emit('plg:s3-queue:message-recovered', {
+      queueId: queueEntry.id,
+      originalId: queueEntry.originalId
+    });
+  }
+
+  _computeIdleDelay(idleStreak) {
+    const base = this.config.pollInterval;
+    const maxInterval = Math.max(base, this.config.maxPollInterval || base);
+    if (maxInterval <= base) {
+      return base;
+    }
+    const factor = Math.pow(2, Math.max(0, idleStreak - 1));
+    const delay = base * factor;
+    return Math.min(delay, maxInterval);
+  }
+
+  async _sleep(ms) {
+    if (!ms || ms <= 0) return;
+    await new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  clearProcessedCache() {
+    this.processedCache.clear();
+  }
+
+  async _markMessageProcessed(messageId) {
+    const ttl = Math.max(1000, this.config.processedCacheTTL);
+    const expiresAt = Date.now() + ttl;
+    this.processedCache.set(messageId, expiresAt);
+
+    const storage = this.getStorage();
+    const key = storage.getPluginKey(null, 'cache', 'processed', messageId);
+    const ttlSeconds = Math.max(1, Math.ceil(ttl / 1000));
+
+    const payload = {
+      workerId: this.workerId,
+      markedAt: Date.now()
+    };
+
+    const [ok, err] = await tryFn(() =>
+      storage.set(key, payload, {
+        ttl: ttlSeconds,
+        behavior: 'body-only'
+      })
+    );
+
+    if (!ok && this.config.verbose) {
+      console.warn('[S3QueuePlugin] Failed to persist processed marker:', err?.message);
+    }
+  }
+
+  async _isRecentlyProcessed(messageId) {
+    const now = Date.now();
+    const localExpiresAt = this.processedCache.get(messageId);
+    if (localExpiresAt && localExpiresAt > now) {
+      return true;
+    }
+    if (localExpiresAt && localExpiresAt <= now) {
+      this.processedCache.delete(messageId);
+    }
+
+    const storage = this.getStorage();
+    const key = storage.getPluginKey(null, 'cache', 'processed', messageId);
+    const [ok, err, data] = await tryFn(() => storage.get(key));
+
+    if (!ok) {
+      if (err && err.code !== 'NoSuchKey' && err.code !== 'NotFound' && this.config.verbose) {
+        console.warn('[S3QueuePlugin] Failed to read processed marker:', err.message || err);
+      }
+      return false;
+    }
+
+    if (!data) {
+      return false;
+    }
+
+    const ttl = Math.max(1000, this.config.processedCacheTTL);
+    this.processedCache.set(messageId, now + ttl);
+    return true;
+  }
+
+  async _clearProcessedMarker(messageId) {
+    this.processedCache.delete(messageId);
+
+    const storage = this.getStorage();
+    const key = storage.getPluginKey(null, 'cache', 'processed', messageId);
+
+    const [ok, err] = await tryFn(() => storage.delete(key));
+    if (!ok && err && err.code !== 'NoSuchKey' && err.code !== 'NotFound' && this.config.verbose) {
+      console.warn('[S3QueuePlugin] Failed to delete processed marker:', err.message || err);
     }
   }
 }