Files
archie/internal/domain/messaging/message.go
T
sam db18d2675a feat(ratelimit): wire per-identity inbound rate limiting into the gateway
internal/ratelimit was fully built (sliding-window limiter, ticker-driven
eviction) but had no consumer, leaving multi-identity deployments with no
inbound request budget on any channel (archie-core-6wxb / GH #797).

Adds Message.SenderID (Telegram numeric user ID, SMTP from address, or
webhook route path -- the closest thing webhook has to a caller identity),
threads it into Router.Route/RouteStream via a shared checkRateLimit, and
wires an opt-in [chat.rate_limit] config section through bootstrap with the
documented EvictStale ticker.
2026-09-15 01:24:20 +10:00

116 lines
4.1 KiB
Go

// Package messaging owns canonical Messages, Conversations, branches,
// channel and source correlation, and typed tool-call/tool-result message
// variants.
//
// This package intentionally contains only the vocabulary already settled
// in docs/architecture/migration-decisions.md section 2: the composite
// Conversation identity, immutable MessageIDs, typed tool-call and
// tool-result messages, and branch lineage through ParentConversationID and
// ForkMessageID. Migrating internal/gateway/'s session, compression,
// approval, and branch logic onto these types is deliberately out of scope
// here — see that section for why, and bd for the tracked follow-up work.
package messaging
import "time"
// ConversationID is the composite identity of a Conversation: a channel and
// the channel-native thread within it. Two conversations with the same
// ChannelID but different ThreadID are distinct.
type ConversationID struct {
ChannelID string
ThreadID string
}
// MessageID is the canonical, immutable identifier for a Message. Once
// assigned it never changes, including across branch and fork operations —
// a forked transcript references the original MessageID it branched from
// rather than minting a new one for shared history.
type MessageID string
// Role identifies who or what produced a Message.
type Role string
const (
RoleUser Role = "user"
RoleAssistant Role = "assistant"
RoleTool Role = "tool"
RoleSystem Role = "system"
)
// Conversation is a single thread of Messages within a channel, optionally
// forked from another Conversation.
//
// Parent and child transcript isolation is exact: a fork sees the parent's
// history up to ForkMessageID, and appends to its own independent
// continuation. Nothing appended to the child is visible to the parent, and
// nothing appended to the parent after the fork point is visible to the
// child.
type Conversation struct {
ID ConversationID
// ParentConversationID is the Conversation this one branched from, and
// the zero value when this Conversation is not a branch.
ParentConversationID ConversationID
// ForkMessageID is the last MessageID visible to this Conversation from
// its parent's history. Empty when ParentConversationID is empty.
ForkMessageID MessageID
CreatedAt time.Time
}
// IsBranch reports whether this Conversation was forked from another.
func (c Conversation) IsBranch() bool {
return c.ParentConversationID != ConversationID{}
}
// Message is one immutable, persisted turn in a Conversation.
type Message struct {
ID MessageID
ConversationID ConversationID
// SourceID is the channel-native identifier (e.g. a Telegram
// message_id) this Message correlates to. Empty for messages with no
// upstream identity.
SourceID string
// Sender is the channel-native display attribution (e.g. a Telegram
// username) recorded when the message was written. Like SourceID it
// is external correlation metadata, never the canonical identity:
// role discrimination uses Role, never this field. It is preserved
// so history search and transcript rendering keep working.
Sender string
// SenderID is the channel-native stable identifier for the party that
// sent this message (e.g. a Telegram numeric user ID, an SMTP from
// address, or a webhook route path), distinct from Sender's
// human-readable display form. Empty when the channel has no stable
// per-sender identity to offer. Used to key per-identity inbound
// controls such as rate limiting.
SenderID string
Role Role
Text string
// ToolCall and ToolResult are populated instead of Text for their
// respective Roles; a Message carries exactly one of Text, ToolCall, or
// ToolResult content.
ToolCall *ToolCall
ToolResult *ToolResult
At time.Time
}
// ToolCall is a typed request from the assistant to invoke a tool.
type ToolCall struct {
CallID string
ToolName string
Arguments string // JSON-encoded arguments, opaque to this package
}
// ToolResult is a typed response to a prior ToolCall, correlated by CallID.
type ToolResult struct {
CallID string
Output string
Err string // non-empty when the tool call failed
}