merge: a TTL-bounded dedup gate for repeated inbound messages (104)

This commit is contained in:
sam committed 2026-09-30 07:49:59 +10:00
commit 0b00682fac
3 files changed
+495 -2

No files matched your search

+30 -2
View File
@@ -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
}
+154
View File
@@ -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."
+311
View File
@@ -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)
}
}