From f616f49165c8a816d12419e70da278bac7fbeb87 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 30 Sep 2026 07:48:56 +1000 Subject: [PATCH] feat(gateway): a TTL-bounded dedup gate for redelivered platform messages --- internal/gateway/gateway.go | 32 ++- internal/gateway/message_dedup.go | 154 ++++++++++++ internal/gateway/message_dedup_test.go | 311 +++++++++++++++++++++++++ 3 files changed, 495 insertions(+), 2 deletions(-) create mode 100644 internal/gateway/message_dedup.go create mode 100644 internal/gateway/message_dedup_test.go diff --git a/internal/gateway/gateway.go b/internal/gateway/gateway.go index c5e62b328..1746b87d3 100644 --- a/internal/gateway/gateway.go +++ b/internal/gateway/gateway.go @@ -206,7 +206,17 @@ type Router struct { // has a stable source but no person), else against Message.SenderID. // A message with neither is never limited: there is no key to charge // it against. - Limiter *ratelimit.Limiter + Limiter *ratelimit.Limiter + // Dedup declines a redelivered platform message (same platform, + // conversation and channel-native ID, delivered again inside the TTL + // window from internal/gateway/message_dedup.go) before it re-enters + // the turn pipeline. NewRouter wires the package default, so a + // production router is always guarded; set a differently configured + // gate to tune it, or nil to disable dedup entirely (test setups). + // The window is deliberately not a config knob here: the durable + // prior-reply replay in turn.go is the backstop for duplicates that + // outlive it, and no composition choice between them needs exposing. + Dedup *MessageDeduplicator sessionTracker *sessionTracker gatewayName string // titlingMu guards titling, the set of sessions with a title proposal @@ -218,7 +228,10 @@ type Router struct { // NewRouter returns a Router. llm is optional -- when nil, non-command // messages get a "not configured" response. func NewRouter(store StatusReader, llm LLMResponder, gatewayName string) *Router { - return &Router{Store: store, LLM: llm, gatewayName: gatewayName} + return &Router{ + Store: store, LLM: llm, gatewayName: gatewayName, + Dedup: NewMessageDeduplicator(0, 0, nil), + } } // InitSessions wires the session store and starts tracking sessions. @@ -277,6 +290,9 @@ func (r *Router) Route(ctx context.Context, in Inbound) (string, error) { // echoing the rate-limit prose as a successful delivery, or accepting an // event that was actually dropped (archie-core-1173). func (r *Router) RouteResult(ctx context.Context, in Inbound) (reply string, rateLimited bool, err error) { + if r.duplicateDelivery(in) { + return dedupReply, false, nil + } if r.checkRateLimit(in) { return rateLimitReply, true, nil } @@ -284,6 +300,15 @@ func (r *Router) RouteResult(ctx context.Context, in Inbound) (reply string, rat return reply, false, err } +// duplicateDelivery reports whether in is a repeat delivery inside the +// dedup window, and records the delivery so later repeats see this one. +// The check runs before the rate limit: a repeated delivery is the +// channel's doing, not the sender's, so it must not spend the sender's +// inbound budget. A nil Dedup (disabled) never blocks. +func (r *Router) duplicateDelivery(in Inbound) bool { + return r.Dedup != nil && !r.Dedup.Admit(in) +} + // route is Route's continuation once the caller has already cleared the // rate-limit check (or is deliberately skipping it, as RouteStream's // local-command fallthrough does to avoid charging one message twice). @@ -457,6 +482,9 @@ func (r *Router) RouteStream(ctx context.Context, in Inbound, stream TurnStream) if r.LLMStream == nil || stream == nil { return r.Route(ctx, in) } + if r.duplicateDelivery(in) { + return dedupReply, nil + } if r.checkRateLimit(in) { return rateLimitReply, nil } diff --git a/internal/gateway/message_dedup.go b/internal/gateway/message_dedup.go new file mode 100644 index 000000000..acffb99df --- /dev/null +++ b/internal/gateway/message_dedup.go @@ -0,0 +1,154 @@ +package gateway + +import ( + "slices" + "sync" + "time" +) + +// The deduplicator's delivery window and memory bound. A redelivery +// (webhook retry, Telegram long-poll re-fetch after a slow ack, forge +// redelivery) reaches the gateway within seconds to a few minutes of the +// first delivery, so five minutes clears the fast-path gate without ever +// colliding with the durable prior-reply replay in turn.go, which remains +// the backstop for a duplicate answered long before or long after the +// window. Each entry is one key and a timestamp, so 1024 entries stay +// comfortably under a megabyte. +const ( + defaultDedupTTL = 5 * time.Minute + defaultDedupCapacity = 1024 +) + +// dedupKey identifies one platform message delivery: the channel that +// carried it, the conversation it addressed, and its channel-native +// message ID -- the same tuple a repeat delivery is keyed on. Two +// components are not enough: Telegram message IDs are only unique per +// chat, and different platforms reuse the same numeric ID ranges. +type dedupKey struct { + Platform string + Conversation string + SourceID string +} + +// MessageDeduplicator rejects a second delivery of the same platform +// message within a TTL window, so at-least-once hand-off (webhook +// retries, Telegram long-poll re-fetch, forge redelivery) does not +// process one message twice -- a duplicate still inside the window never +// reaches the turn pipeline at all. +// +// Memory is bounded by design, not by chance: at most capacity entries +// are held. An insert brings the cache back under the bound by evicting +// expired entries first (oldest recorded delivery first, exactly the +// entries a TTL sweep would drop), then the oldest still-live delivery +// once expired entries alone no longer make room. A rejected repeat +// never extends the window: expiry is judged from the first delivery. +// +// One Router may be reached from several channel goroutines at once, so +// every method holds a mutex; Admit's test-and-record is one atomic +// step, which is what makes a concurrent duplicate see the race and +// lose it. +// +// Admit runs before the turn, so a message whose first processing fails +// stays inside the window until it expires; redeliveries of failed work +// wait out the TTL, and turn.go's prior-reply path covers anything +// that was actually completed in the meantime. +type MessageDeduplicator struct { + mu sync.Mutex + // ttl is the delivery window; cap is the live-entry bound. + ttl time.Duration + cap int + // now injects the clock, so expiry is testable without sleeping. + now func() time.Time + // entries maps each live key to when it was delivered; order is the + // FIFO eviction queue, oldest delivery first. A live entry always has + // at least one queue slot; a queue slot may outlive its entry after + // an expiry re-arm and is dropped on the next sweep. + entries map[dedupKey]time.Time + order []dedupKey +} + +// NewMessageDeduplicator returns a gate with the given TTL window and +// entry bound. Zero values select the package defaults; now injects the +// clock, so tests judge expiry without sleeping. A nil now means +// time.Now, which is the production shape. +func NewMessageDeduplicator(ttl time.Duration, capacity int, now func() time.Time) *MessageDeduplicator { + if ttl <= 0 { + ttl = defaultDedupTTL + } + if capacity <= 0 { + capacity = defaultDedupCapacity + } + if now == nil { + now = time.Now + } + return &MessageDeduplicator{ + ttl: ttl, + cap: capacity, + now: now, + entries: make(map[dedupKey]time.Time), + } +} + +// Admit records this delivery and reports whether the message may be +// processed: true for the first delivery inside the window (or the first +// after an earlier one expired), false for a repeat that is already +// inside the window. A message with no channel-native ID (its SourceID +// is empty -- gateway-local commands, most dashboard turns) has no key to +// deduplicate against and is always admitted. +func (d *MessageDeduplicator) Admit(in Inbound) bool { + if in.Message.SourceID == "" { + return true + } + key := dedupKey{ + Platform: in.Platform, + Conversation: in.Message.ConversationID.String(), + SourceID: in.Message.SourceID, + } + + d.mu.Lock() + defer d.mu.Unlock() + at := d.now() + if seen, live := d.entries[key]; live { + if at.Sub(seen) < d.ttl { + return false + } + // Expired: re-arm from the fresh delivery time by dropping the + // stale queue slots for the key, then recording anew below. + d.order = slices.DeleteFunc(d.order, func(k dedupKey) bool { return k == key }) + delete(d.entries, key) + } + d.evictLocked(at) + d.entries[key] = at + d.order = append(d.order, key) + return true +} + +// evictLocked brings the cache under its bound ahead of one insert: it +// sweeps every expired entry oldest-first, then evicts the oldest +// still-live delivery. len(order) always covers every live entry, so the +// live-entry loop below has a queue slot to evict from. +func (d *MessageDeduplicator) evictLocked(at time.Time) { + d.order = slices.DeleteFunc(d.order, func(k dedupKey) bool { + seen, live := d.entries[k] + if !live { + return true + } + if at.Sub(seen) >= d.ttl { + delete(d.entries, k) + return true + } + return false + }) + for len(d.entries) >= d.cap { + key := d.order[0] + d.order = d.order[1:] + delete(d.entries, key) + } +} + +// dedupReply is returned to a sender whose message arrived again inside +// the dedup window. Like the rate-limit reply it is prose addressed to a +// human reader of the chat; a webhook caller should treat any successful, +// non-original reply the same way it treats rate-limit prose (see +// archie-core-1173). +const dedupReply = "I already received this message, so I'm ignoring this repeat delivery." diff --git a/internal/gateway/message_dedup_test.go b/internal/gateway/message_dedup_test.go new file mode 100644 index 000000000..3e3cd7880 --- /dev/null +++ b/internal/gateway/message_dedup_test.go @@ -0,0 +1,311 @@ +package gateway + +import ( + "context" + "strconv" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/domain/messaging" +) + +// dedupInbound builds an Inbound carrying a channel-native message ID, the +// shape a duplicate delivery takes: the same source message ID +// re-presented by the channel. +func dedupInbound(platform, channelID, threadID, sourceID string) Inbound { + return Inbound{ + Platform: platform, + Message: messaging.Message{ + ConversationID: messaging.ConversationID{ChannelID: channelID, ThreadID: threadID}, + SourceID: sourceID, + Role: messaging.RoleUser, + Text: "hello", + }, + } +} + +// TestMessageDeduplicatorAdmit covers the gate's contract: the first +// delivery within the TTL window is admitted, a repeat of the same +// platform message is rejected, and expiry is judged by an injected +// clock, never a real sleep. The key is platform + channel (conversation) +// + message ID, so a second distinct channel-native ID from the same +// sender is a genuine repeat message, not a delivery duplicate. +func TestMessageDeduplicatorAdmit(t *testing.T) { + const tg = "telegram" + + tests := []struct { + name string + prepare []Inbound // deliveries recorded before the one under test + advanceBy time.Duration + admit Inbound // the delivery being tested + wantAdmit bool + wantStored int // entries the cache must hold after the tested Admit + }{ + { + name: "the first delivery is admitted", + advanceBy: 0, + admit: dedupInbound(tg, "100", "7", "42"), + wantAdmit: true, wantStored: 1, + }, + { + name: "a repeat delivery within the TTL is rejected", + prepare: []Inbound{dedupInbound(tg, "100", "7", "42")}, + advanceBy: defaultDedupTTL - time.Second, + admit: dedupInbound(tg, "100", "7", "42"), + wantAdmit: false, wantStored: 1, + }, + // The boundary is pinned exactly: TTL elapsed clears the entry, + // one second shy does not. No sleeps; the clock is injected. + { + name: "the same message after the TTL passes", + prepare: []Inbound{dedupInbound(tg, "100", "7", "42")}, + advanceBy: defaultDedupTTL, + admit: dedupInbound(tg, "100", "7", "42"), + wantAdmit: true, wantStored: 1, + }, + { + name: "a repeat in a different conversation is a distinct message", + prepare: []Inbound{dedupInbound(tg, "100", "7", "42")}, + advanceBy: 0, + admit: dedupInbound(tg, "100", "8", "42"), + wantAdmit: true, wantStored: 2, + }, + { + name: "a repeat on a different platform is a distinct message", + prepare: []Inbound{dedupInbound(tg, "100", "7", "42")}, + advanceBy: 0, + admit: dedupInbound("web", "100", "7", "42"), + wantAdmit: true, wantStored: 2, + }, + { + name: "a second message from the same sender is admitted", + prepare: []Inbound{dedupInbound(tg, "100", "7", "42")}, + advanceBy: 0, + admit: dedupInbound(tg, "100", "7", "43"), + wantAdmit: true, wantStored: 2, + }, + { + name: "a message with no source ID cannot be deduplicated", + prepare: []Inbound{dedupInbound(tg, "100", "7", "")}, + advanceBy: 0, + admit: dedupInbound(tg, "100", "7", ""), + wantAdmit: true, wantStored: 0, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + base := time.Unix(1700000000, 0) + current := base + now := func() time.Time { return current } + d := NewMessageDeduplicator(0, 0, now) + for _, in := range tt.prepare { + if !d.Admit(in) { + t.Fatalf("prepare delivery unexpectedly rejected: source %q", in.Message.SourceID) + } + } + current = base.Add(tt.advanceBy) + if got := d.Admit(tt.admit); got != tt.wantAdmit { + t.Fatalf("Admit = %v, want %v", got, tt.wantAdmit) + } + if got := len(d.entries); got != tt.wantStored { + t.Fatalf("cache holds %d entries, want %d (repeat rejections must not grow the cache)", got, tt.wantStored) + } + }) + } +} + +// TestMessageDeduplicatorCapacity proves the cache is bounded: at +// capacity, an insert evicts expired entries first, then the oldest +// still-live delivery, never growing past the bound. +func TestMessageDeduplicatorCapacity(t *testing.T) { + const tg = "telegram" + current := time.Unix(1700000000, 0) + now := func() time.Time { return current } + d := NewMessageDeduplicator(defaultDedupTTL, 2, now) + + if !d.Admit(dedupInbound(tg, "1", "", "a")) { + t.Fatal("first delivery rejected") + } + if !d.Admit(dedupInbound(tg, "1", "", "b")) { + t.Fatal("second delivery rejected") + } + // Inserting a third message at the bound evicts the oldest live + // delivery (a), which is then admitted again. + if !d.Admit(dedupInbound(tg, "1", "", "c")) { + t.Fatal("third delivery rejected") + } + if len(d.entries) != 2 { + t.Fatalf("cache holds %d entries, want the bound of 2", len(d.entries)) + } + if _, stillTracked := d.entries[dedupKey{Platform: tg, Conversation: "1", SourceID: "a"}]; stillTracked { + t.Fatal("expected a to have been evicted as the oldest entry") + } + if !d.Admit(dedupInbound(tg, "1", "", "a")) { + t.Fatal("an evicted entry must be re-admitted on its next delivery") + } + if d.Admit(dedupInbound(tg, "1", "", "c")) { + t.Fatal("c is still live inside the TTL (b, the oldest entry, was evicted to make room for a's second delivery)") + } + + // Expired eviction beats LRU: every entry is well past the TTL, so + // the next insert drops the expired tail rather than recent entries. + current = now().Add(defaultDedupTTL + time.Hour) + if !d.Admit(dedupInbound(tg, "2", "", "d")) { + t.Fatal("delivery after full expiry rejected") + } + if len(d.entries) != 1 { + t.Fatalf("cache holds %d entries after expiry sweep, want 1", len(d.entries)) + } + if !d.Admit(dedupInbound(tg, "1", "", "a")) { + t.Fatal("an expired entry must be admitted again on its next delivery") + } +} + +// TestMessageDeduplicatorConcurrent drives the gate from many goroutines +// at once, as the Router does: one telegram worker, several web sessions +// and webhook posts all dispatch through the same Router. Exactly one +// racing delivery may be admitted, and the -race run proves the guard. +func TestMessageDeduplicatorConcurrent(t *testing.T) { + current := time.Unix(1700000000, 0) + now := func() time.Time { return current } + d := NewMessageDeduplicator(0, 0, now) + + t.Run("racing repeats of one delivery", func(t *testing.T) { + in := dedupInbound("telegram", "1", "", "7") + const workers = 32 + var admitted atomic.Int64 + var wg sync.WaitGroup + wg.Add(workers) + for i := 0; i < workers; i++ { + go func() { + defer wg.Done() + if d.Admit(in) { + admitted.Add(1) + } + }() + } + wg.Wait() + if got := admitted.Load(); got != 1 { + t.Fatalf("%d goroutines raced the same delivery and %d were admitted, want exactly 1", workers, got) + } + }) + + t.Run("racing distinct deliveries stay bounded", func(t *testing.T) { + fresh := NewMessageDeduplicator(0, 16, now) + const workers = 64 + var wg sync.WaitGroup + wg.Add(workers) + for i := 0; i < workers; i++ { + go func(i int) { + defer wg.Done() + fresh.Admit(dedupInbound("telegram", "1", "", strconv.Itoa(i))) + }(i) + } + wg.Wait() + if len(fresh.entries) != 16 { + t.Fatalf("cache holds %d entries, want the bound of 16", len(fresh.entries)) + } + }) +} + +// countingLLM is an LLMResponder stub that counts invocations. +type countingLLM struct { + reply string + calls *int64 +} + +func (c *countingLLM) respond(ctx context.Context, in Inbound) (string, error) { + atomic.AddInt64(c.calls, 1) + return c.reply, nil +} + +// countingStream is a TurnStream stub satisfying the interface, so the +// streaming router path runs without a renderer. +type countingStream struct { + deltas atomic.Int64 +} + +func (s *countingStream) Delta(text string) { s.deltas.Add(1) } +func (s *countingStream) ToolCall(event messaging.ToolCallEvent) {} +func (s *countingStream) Media(event messaging.MediaEvent) {} + +// TestRouterRejectsRedeliveredMessage wires the gate where its owner +// lives: the Router declines a second delivery of the same platform +// message without reaching the LLM again, honours the TTL with an +// injected clock, and a nil Dedup disables the gate. +func TestRouterRejectsRedeliveredMessage(t *testing.T) { + t.Run("the second delivery is declined without reaching the LLM", func(t *testing.T) { + current := time.Unix(1700000000, 0) + now := func() time.Time { return current } + var calls int64 + r := NewRouter(nil, (&countingLLM{reply: "pong", calls: &calls}).respond, "web") + r.Dedup = NewMessageDeduplicator(0, 0, now) + in := dedupInbound("telegram", "100", "7", "42") + + if reply, err := r.Route(context.Background(), in); err != nil || reply != "pong" { + t.Fatalf("first delivery: reply %q, err %v, want pong", reply, err) + } + if reply, _ := r.Route(context.Background(), in); reply == "pong" { + t.Fatal("the repeat delivery was answered again instead of being declined") + } + if calls != 1 { + t.Fatalf("LLM called %d times for one accepted delivery, want 1", calls) + } + + stream := &countingStream{} + if reply, err := r.RouteStream(context.Background(), in, stream); err != nil { + t.Fatalf("streamed repeat delivery: unexpected error %v", err) + } else if reply == "pong" { + t.Fatal("the streamed repeat delivery was streamed again instead of being declined") + } + if calls != 1 || stream.deltas.Load() != 0 { + t.Fatalf("streamed repeat reached the stream (calls %d, deltas %d), want none", calls, stream.deltas.Load()) + } + }) + + t.Run("after the TTL the same message is processed again", func(t *testing.T) { + current := time.Unix(1700000000, 0) + now := func() time.Time { return current } + var calls int64 + r := NewRouter(nil, (&countingLLM{reply: "pong", calls: &calls}).respond, "web") + r.Dedup = NewMessageDeduplicator(defaultDedupTTL, 0, now) + in := dedupInbound("telegram", "100", "7", "42") + if _, err := r.Route(context.Background(), in); err != nil { + t.Fatal(err) + } + current = now().Add(defaultDedupTTL) + if reply, err := r.Route(context.Background(), in); err != nil || reply != "pong" { + t.Fatalf("post-TTL delivery: reply %q, err %v, want pong", reply, err) + } + }) + + t.Run("nil Dedup disables the gate", func(t *testing.T) { + var calls int64 + r := NewRouter(nil, (&countingLLM{reply: "pong", calls: &calls}).respond, "web") + r.Dedup = nil + in := dedupInbound("telegram", "100", "7", "42") + for i := 0; i < 2; i++ { + if _, err := r.Route(context.Background(), in); err != nil { + t.Fatal(err) + } + } + if calls != 2 { + t.Fatalf("with dedup disabled, LLM should run for both deliveries, got %d calls", calls) + } + }) +} + +// TestNewRouterWiresTheDefaultGate holds the composition root to the +// contract: the production router constructor wires the gate, so a +// deployment cannot silently process every redelivery. +func TestNewRouterWiresTheDefaultGate(t *testing.T) { + r := NewRouter(nil, nil, "web") + if r.Dedup == nil { + t.Fatal("NewRouter must wire the default deduplicator") + } + if r.Dedup.ttl != defaultDedupTTL || r.Dedup.cap != defaultDedupCapacity { + t.Fatalf("default gate configured with ttl %v cap %d, want the package defaults", r.Dedup.ttl, r.Dedup.cap) + } +}