fix(bluebubbles): add staleness gate and GUID dedup for inbound messages by dashhuang · Pull Request #31159 · openclaw/openclaw

dashhuang · 2026-03-02T01:58:09Z

Summary

BlueBubbles MessagePoller uses a 1-week lookback window and can re-fire old messages as webhook events after server restarts or reconnections. OpenClaw currently has no protection against this, causing duplicate message processing and confusing replies to stale messages.

This PR adds two guards at the top of processMessage() in the BlueBubbles extension:

Staleness check: drop inbound messages with timestamps older than 5 minutes
GUID dedup: track recently processed message GUIDs in a TTL'd Map (30 min TTL, 5K entry cap) and drop duplicates

Both guards run before any other processing and log dropped messages via logVerbose.

Context

Issue [bluebubbles] Add maxMessageAge filter to drop stale re-delivered webhooks #19176 requests a maxMessageAge filter for stale re-delivered webhooks
Issue BlueBubbles: no dedup/staleness protection on inbound webhooks #12053 (closed) described the same problem with a real incident: 11x duplicate intro messages sent to a contact after BlueBubbles replayed 17-hour-old webhooks
We've been running this exact patch in production on macOS 26 (Tahoe) since 2026-03-02 with no issues

Design decisions

Hardcoded 5-min threshold rather than configurable maxMessageAgeSec — simpler, and 5 minutes is generous enough for any legitimate delivery delay. A configurable option could be added later if needed.
GUID dedup is in-memory — resets on gateway restart, but that's acceptable since the staleness gate catches old replays regardless. The dedup primarily protects against rapid duplicate webhook deliveries within a session.
Guards before fromMe check — stale/duplicate fromMe messages should also be dropped to avoid unnecessary cache operations.

Test plan

Tested on macOS 26.3 (Apple Silicon) with BlueBubbles Server
Gateway starts without TypeScript errors (Node.js 25.6.1 strip mode)
Normal messages are processed correctly
Stale messages (>5 min old) are dropped with verbose log
Duplicate GUIDs are dropped with verbose log
Maintainer review

Fixes #19176
Ref #12053

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 13b5b566ed

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-02T02:01:00Z

+function _isDuplicateGuid(guid: string | undefined): boolean {
+  if (!guid) return false;
+  const now = Date.now();
+  if (_dedupGuidCache.size > DEDUP_GUID_CACHE_MAX) {


Enforce GUID cache size cap on dedup map

The dedup map is only pruned when size > DEDUP_GUID_CACHE_MAX, and that pruning removes only expired entries, so bursts of >5k unique GUIDs inside the 30-minute TTL will not evict anything and the map will keep growing past the intended cap. This makes the claimed 5k-entry bound ineffective and can cause avoidable memory/CPU growth (full-map scans on each message once over threshold) in busy BlueBubbles deployments.

Useful? React with 👍 / 👎.

greptile-apps · 2026-03-02T02:03:31Z

Greptile Summary

This PR adds two defensive guards to prevent BlueBubbles from processing stale or duplicate webhook messages that can be re-delivered after server restarts.

Key changes:

Staleness gate drops messages older than 5 minutes using timestamp comparison
GUID deduplication using an in-memory Map (30-min TTL, ~5K entry soft cap)
Both checks run before any message processing, including the fromMe filter
Dropped messages are logged via logVerbose for debugging

Implementation notes:

Timestamp is correctly normalized to milliseconds in the existing code, so the staleness check is accurate
The GUID cache uses lazy cleanup: expired entries are purged when cache exceeds 5000 entries
Cache can theoretically grow beyond 5000 if message volume exceeds ~2.7 msg/sec sustained (unlikely for personal messaging)
In-memory cache resets on gateway restart, but the staleness gate handles old replays regardless

Production validation:

Already running in production on macOS since 2026-03-02 with no reported issues
Addresses real incidents described in issues [bluebubbles] Add maxMessageAge filter to drop stale re-delivered webhooks #19176 and BlueBubbles: no dedup/staleness protection on inbound webhooks #12053

Confidence Score: 5/5

This PR is safe to merge with minimal risk
Simple, focused change that adds defensive guards against a documented problem. The implementation correctly handles edge cases (undefined timestamps/GUIDs), uses appropriate data structures, and has been validated in production. The in-memory cache design is pragmatic for the personal messaging use case where sustained high-volume message processing is unlikely.
No files require special attention

_{Last reviewed commit: 13b5b56}

openclaw-barnacle · 2026-04-06T04:29:23Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

dashhuang · 2026-04-06T06:19:42Z

Refreshed this PR onto current \ and resolved the BlueBubbles processing entrypoint drift. The patch remains the same focused behavior change: drop stale inbound messages and dedupe recently seen GUIDs before normal processing.\n\nProduction context is unchanged on our side: this is still a live local delta we carry for BlueBubbles replay/reconnect behavior.\n\nNote: I did not add a dedicated BlueBubbles test here because there still does not appear to be a direct test seam around this webhook path; this refresh is intentionally kept as the minimal one-file patch.

dashhuang · 2026-04-06T06:19:49Z

Refreshed this PR onto current main and resolved the BlueBubbles processing entrypoint drift. The patch remains the same focused behavior change: drop stale inbound messages and dedupe recently seen GUIDs before normal processing.

Production context is unchanged on our side: this is still a live local delta we carry for BlueBubbles replay/reconnect behavior.

Note: I did not add a dedicated BlueBubbles test here because there still does not appear to be a direct test seam around this webhook path; this refresh is intentionally kept as the minimal one-file patch.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3c6cf2cb1d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-06T06:23:54Z

+  return age > STALE_MESSAGE_MAX_AGE_MS;
+}
+
+function _isDuplicateGuid(guid: string | undefined): boolean {


Scope GUID dedup cache per account

The new dedup cache is module-global and keyed only by guid, so processMessage will treat the same message ID from different BlueBubbles accounts as a duplicate and drop the later one. This can silently lose legitimate inbound messages in multi-account deployments (for example when two accounts emit overlapping ID formats), because account context is available in processMessage but not part of the dedup key.

Useful? React with 👍 / 👎.

dashhuang · 2026-04-06T06:59:20Z

I pushed a follow-up test-only fix for the BlueBubbles CI failures.

Root cause: the new inbound GUID dedupe cache is module-global, while many BlueBubbles webhook tests reuse the default guid: "msg-1". After the first case, later cases were short-circuiting as duplicates, which is why the failures showed up as a wide spread of expected vi.fn() to be called / Number of calls: 0 assertions across monitor.test.ts and monitor.webhook-auth.test.ts.

Fix: add a dedicated test reset hook for the inbound dedupe cache and call it from the shared BlueBubbles monitor test reset helper. This keeps production behavior unchanged and only restores test isolation between cases.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 61acc3b630

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-06T07:03:35Z

+    }
+  }
+  if (_dedupGuidCache.has(guid)) return true;
+  _dedupGuidCache.set(guid, now);


Record GUID only after successful processing

_isDuplicateGuid stores every GUID before any downstream work runs, so a transient failure later in processMessage (for example during dispatch/model calls) still burns that GUID. When BlueBubbles re-delivers the same webhook, this guard drops it as a duplicate, turning retryable failures into permanent message loss; this is especially impactful because webhook processing errors are only logged and not retried in the current monitor flow.

Useful? React with 👍 / 👎.

openclaw-barnacle · 2026-04-12T04:25:27Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

omarshahine · 2026-04-13T20:32:38Z

Taking a look at this — going to run it on macOS 26.3 / OpenClaw 2026.4.12 against a BlueBubbles 1.9.x server. The post-restart new-message replay symptom is biting me on every openclaw gateway restart (the agent replies to the most recent inbound message in the BB cache), so the staleness gate is exactly what I need. Will report back with results from a few days of runtime.

omarshahine · 2026-04-14T00:19:14Z

Thanks for the original patch @dashhuang — the behavioral goal is exactly right, and this one sat in the queue for too long.

I've re-created and improved the fix over in #66230. The key change vs. this one is that the dedupe is now persistent on disk (via createPersistentDedupe, same pattern used by the Feishu plugin), so it survives the gateway-restart case that's actually the driver for the bug — plus it avoids the module-global mutable state that required test-reset plumbing here. You're credited in both the PR body and the CHANGELOG entry.

Closing in favor of #66230.

openclaw-barnacle Bot added the channel: bluebubbles Channel integration: bluebubbles label Mar 2, 2026

dashhuang mentioned this pull request Mar 2, 2026

[bluebubbles] Add maxMessageAge filter to drop stale re-delivered webhooks #19176

Closed

openclaw-barnacle Bot added the size: XS label Mar 2, 2026

chatgpt-codex-connector Bot reviewed Mar 2, 2026

View reviewed changes

openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Apr 6, 2026

fix(bluebubbles): add staleness gate and GUID dedup for inbound messages

3c6cf2c

dashhuang force-pushed the fix/bluebubbles-message-dedup branch from 13b5b56 to 3c6cf2c Compare April 6, 2026 06:19

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

test(bluebubbles): reset inbound dedup state between cases

61acc3b

openclaw-barnacle Bot added size: S and removed size: XS labels Apr 6, 2026

chatgpt-codex-connector Bot reviewed Apr 6, 2026

View reviewed changes

openclaw-barnacle Bot removed the stale Marked as stale due to inactivity label Apr 7, 2026

openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Apr 12, 2026

omarshahine mentioned this pull request Apr 14, 2026

fix(bluebubbles): dedupe inbound webhooks across restarts (#19176, #12053) #66230

Closed

5 tasks

omarshahine closed this Apr 14, 2026

Uh oh!

Conversation

dashhuang commented Mar 2, 2026

Summary

Context

Design decisions

Test plan

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Mar 2, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

openclaw-barnacle Bot commented Apr 6, 2026

Uh oh!

dashhuang commented Apr 6, 2026

Uh oh!

dashhuang commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

dashhuang commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

openclaw-barnacle Bot commented Apr 12, 2026

Uh oh!

omarshahine commented Apr 13, 2026

Uh oh!

omarshahine commented Apr 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants