fix(messaging): carry an inbound attachment's bytes to the gateway turn

A Telegram photo or document was dropped between the process that receives
it and the one that runs the turn. Telegram runs in archie-messaging, which
downloads the attachment; the turn runs in archie-gateway/archied, which
never holds the bot token. gatewayrpc stripped MediaAttachment.Data on the
inbound request, so by the time the Gateway's model seam ran, the
attachment had no bytes and no URL, and mediaParts dropped it -- the model
read only the "[photo]" placeholder.

- proto/gateway/v1: Media gains a `data` field, populated only on the
  inbound request. Stored-history and outbound-event directions keep it
  empty: a persisted record still strips the bytes, and a streamed media
  event still carries metadata only.
- gatewayrpc: the inbound conversion maps Data; the stored and outbound
  conversions deliberately do not.
- archied: the Gateway server raises its gRPC receive limit from the 4 MB
  default to the messaging contract's inbound attachment ceiling plus
  framing headroom, so a maximal (20 MB) attachment is accepted rather than
  failing the RPC.
- messaging: MaxInboundAttachmentBytes is the single ceiling the Telegram
  download gate and the Gateway receive limit both derive from.

Red first: a new TestInboundMediaBytesReachTheTurn asserted the bytes crossed
the wire and failed at that assertion before the mapping changed; it was then
consolidated into TestInboundMediaRoundTrip, which now pins metadata plus bytes.
This commit is contained in:
sam committed 2026-10-02 10:18:01 +10:00
1 parent 6985be0abd
commit c70b144782
10 files changed
+212 -47

No files matched your search

+1 -1
View File
@@ -314,7 +314,7 @@
"properties": {
"data": {
"contentEncoding": "base64",
"description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It never crosses a wire or persistence\nboundary -- it is a turn-scoped value, not a stored one.",
"description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It crosses the wire in one direction only:\nthe inbound request from a channel frontend to the Gateway process\nthat runs the turn, because that process never holds the platform\ncredential. It is never persisted, and the stored-history and\noutbound-event directions strip it.",
"type": "string"
},
"duration": {
+15 -1
View File
@@ -12,6 +12,7 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/applystatus"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
@@ -189,18 +190,30 @@ func (b *boot) startGatewayRuntime(ctx context.Context, actor gateway.ChatTaskAc
return contract, nil
}
// inboundMessageHeadroomBytes leaves room for the protobuf framing and the
// rest of the request around an attachment at the messaging contract's
// ceiling, so the largest attachment a channel frontend may send is accepted
// rather than rejected as an oversized gRPC message.
const inboundMessageHeadroomBytes = 1 << 20
// gatewayServerOpts applies the transport security boundary: a loopback
// listener is served insecure with no token; any non-loopback address
// requires a Bearer [REDACTED], else the process fails closed. It mirrors
// stateStoreServerOpts, minus the State Store's task-scoped grants: the
// Gateway has one administrative token for all callers.
//
// The receive limit is raised above gRPC's 4 MB default because an inbound
// request carries a channel attachment's bytes: the channel frontend
// downloads the file, and this process -- which runs the turn -- holds no
// platform credential to fetch it again.
func gatewayServerOpts(listen, token string) (opts []grpc.ServerOption, loopback bool, err error) {
recv := grpc.MaxRecvMsgSize(messaging.MaxInboundAttachmentBytes + inboundMessageHeadroomBytes)
loopback, err = gatewayrpc.TargetIsLoopback(listen)
if err != nil {
return nil, false, err
}
if loopback {
return nil, true, nil
return []grpc.ServerOption{recv}, true, nil
}
if token == "" {
return nil, false, fmt.Errorf(
@@ -209,6 +222,7 @@ func gatewayServerOpts(listen, token string) (opts []grpc.ServerOption, loopback
)
}
return []grpc.ServerOption{
recv,
grpc.ChainUnaryInterceptor(gatewayrpc.UnaryServerInterceptor(token)),
grpc.ChainStreamInterceptor(gatewayrpc.StreamServerInterceptor(token)),
}, false, nil
+79 -4
View File
@@ -2,8 +2,11 @@ package archied
import (
"context"
"errors"
"io"
"log/slog"
"net"
"sync"
"testing"
"time"
@@ -25,8 +28,10 @@ func TestGatewayServerOptsLoopbackIsInsecure(t *testing.T) {
if !loopback {
t.Fatal("loopback listener should report loopback")
}
if len(opts) != 0 {
t.Fatalf("loopback listener should have no server opts, got %d", len(opts))
// Only the inbound size limit; a loopback listener installs no auth
// interceptors (the count is the only handle on opaque ServerOptions).
if len(opts) != 1 {
t.Fatalf("loopback listener should install only the inbound size limit, got %d options", len(opts))
}
}
@@ -41,8 +46,8 @@ func TestGatewayServerOptsNonLoopbackRequiresToken(t *testing.T) {
if loopback {
t.Fatal("non-loopback listener should not report loopback")
}
if len(opts) != 2 {
t.Fatalf("non-loopback listener should install two server options (unary and stream auth interceptors), got %d", len(opts))
if len(opts) != 3 {
t.Fatalf("non-loopback listener should install three server options (inbound size limit plus unary and stream auth interceptors), got %d", len(opts))
}
}
@@ -135,3 +140,73 @@ func TestGatewayServingAnnouncesReady(t *testing.T) {
t.Fatalf("serveGatewayListener returned: %v", err)
}
}
// recordingGatewayContract captures the inbound a Stream call reached the
// Gateway with, so a test can prove the request's payload survived the wire.
type recordingGatewayContract struct {
stubGatewayContract
mu sync.Mutex
last messaging.Inbound
}
func (c *recordingGatewayContract) Stream(_ context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) {
c.mu.Lock()
c.last = in
c.mu.Unlock()
events := make(chan messaging.ChatEvent)
close(events)
return events, nil
}
// TestGatewayAcceptsAnInboundAttachmentOverTheDefaultGRPCLimit: the inbound
// request now carries a channel attachment's bytes, and gRPC's default receive
// limit is 4 MB -- well under the messaging contract's ceiling. A maximal
// attachment must reach the turn, not fail the RPC with ResourceExhausted.
func TestGatewayAcceptsAnInboundAttachmentOverTheDefaultGRPCLimit(t *testing.T) {
rec := &recordingGatewayContract{}
ln, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("listen: %v", err)
}
opts, _, err := gatewayServerOpts(ln.Addr().String(), "")
if err != nil {
t.Fatalf("gatewayServerOpts: %v", err)
}
ctx, cancel := context.WithCancel(t.Context())
defer cancel()
serveCh := make(chan error, 1)
go func() { serveCh <- serveGateway(ctx, ln, rec, nil, opts) }()
defer func() {
cancel()
if err := <-serveCh; err != nil {
t.Errorf("serveGateway: %v", err)
}
}()
conn, err := grpc.NewClient("passthrough:///"+ln.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatalf("dial: %v", err)
}
defer conn.Close()
raw := make([]byte, 5<<20) // larger than gRPC's 4 MB default receive limit
stream, err := pb.NewChatServiceClient(conn).Stream(t.Context(), &pb.StreamRequest{
Message: &pb.Message{Media: []*pb.Media{{Type: "image", MimeType: "image/jpeg", Data: raw}}},
})
if err != nil {
t.Fatalf("Stream with a %d-byte attachment: %v", len(raw), err)
}
if _, err := stream.Recv(); !errors.Is(err, io.EOF) {
t.Fatalf("Recv after an empty stream: %v, want EOF", err)
}
rec.mu.Lock()
got := rec.last
rec.mu.Unlock()
if len(got.Media) != 1 {
t.Fatalf("turn received %d attachments, want 1", len(got.Media))
}
if len(got.Media[0].Data) != len(raw) {
t.Fatalf("turn received %d attachment bytes, want %d", len(got.Media[0].Data), len(raw))
}
}
+3 -2
View File
@@ -117,8 +117,9 @@ func nilIfZero(v int64) *int64 {
// maxInboundDownloadBytes is the Bot API download ceiling: bots cannot
// fetch files larger than 20 MB through getFile, so a larger attachment
// must be refused with a clear notice rather than met with a Bot API 400
// nobody reads.
var maxInboundDownloadBytes int64 = 20 * 1024 * 1024
// nobody reads. It is the messaging contract's inbound attachment ceiling,
// so the value the Gateway must be able to receive stays in one place.
var maxInboundDownloadBytes int64 = messaging.MaxInboundAttachmentBytes
var errInboundMediaTooLarge = errors.New("file exceeds the bot download limit")
+32 -17
View File
@@ -163,9 +163,9 @@ type Message struct {
// constant. Transport-only, never persisted: the session record keeps it.
Platform string `protobuf:"bytes,10,opt,name=platform,proto3" json:"platform,omitempty"`
// media carries attachment metadata for a message that arrived with a
// file. The attachment's bytes never cross this wire: a stored Media
// with tool_name empty is a sender attachment, and the tool_name on
// tool-produced events stays a stream-only field.
// file. The bytes ride only on the inbound request (see Media.data); a
// stored Media with tool_name empty is a sender attachment, and the
// tool_name on tool-produced events stays a stream-only field.
Media []*Media `protobuf:"bytes,11,rep,name=media,proto3" json:"media,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
@@ -355,18 +355,25 @@ func (x *ToolCall) GetError() string {
}
type Media struct {
state protoimpl.MessageState `protogen:"open.v1"`
ToolName string `protobuf:"bytes,1,opt,name=tool_name,json=toolName,proto3" json:"tool_name,omitempty"`
Type string `protobuf:"bytes,2,opt,name=type,proto3" json:"type,omitempty"`
FileId string `protobuf:"bytes,3,opt,name=file_id,json=fileId,proto3" json:"file_id,omitempty"`
Url string `protobuf:"bytes,4,opt,name=url,proto3" json:"url,omitempty"`
Path string `protobuf:"bytes,5,opt,name=path,proto3" json:"path,omitempty"`
MimeType string `protobuf:"bytes,6,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"`
FileName string `protobuf:"bytes,7,opt,name=file_name,json=fileName,proto3" json:"file_name,omitempty"`
FileSize *int64 `protobuf:"varint,8,opt,name=file_size,json=fileSize,proto3,oneof" json:"file_size,omitempty"`
Width *int64 `protobuf:"varint,9,opt,name=width,proto3,oneof" json:"width,omitempty"`
Height *int64 `protobuf:"varint,10,opt,name=height,proto3,oneof" json:"height,omitempty"`
Duration *int64 `protobuf:"varint,11,opt,name=duration,proto3,oneof" json:"duration,omitempty"`
state protoimpl.MessageState `protogen:"open.v1"`
ToolName string `protobuf:"bytes,1,opt,name=tool_name,json=toolName,proto3" json:"tool_name,omitempty"`
Type string `protobuf:"bytes,2,opt,name=type,proto3" json:"type,omitempty"`
FileId string `protobuf:"bytes,3,opt,name=file_id,json=fileId,proto3" json:"file_id,omitempty"`
Url string `protobuf:"bytes,4,opt,name=url,proto3" json:"url,omitempty"`
Path string `protobuf:"bytes,5,opt,name=path,proto3" json:"path,omitempty"`
MimeType string `protobuf:"bytes,6,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"`
FileName string `protobuf:"bytes,7,opt,name=file_name,json=fileName,proto3" json:"file_name,omitempty"`
FileSize *int64 `protobuf:"varint,8,opt,name=file_size,json=fileSize,proto3,oneof" json:"file_size,omitempty"`
Width *int64 `protobuf:"varint,9,opt,name=width,proto3,oneof" json:"width,omitempty"`
Height *int64 `protobuf:"varint,10,opt,name=height,proto3,oneof" json:"height,omitempty"`
Duration *int64 `protobuf:"varint,11,opt,name=duration,proto3,oneof" json:"duration,omitempty"`
// data carries a sender attachment's bytes on an inbound request. The
// channel frontend downloads the file, but the Gateway process that runs
// the turn never holds the platform credential, so this is the only way
// the model can read a photo or document. It is empty on every other
// direction: stored history and outbound media events carry metadata
// only, and a persisted record strips the bytes.
Data []byte `protobuf:"bytes,12,opt,name=data,proto3" json:"data,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -478,6 +485,13 @@ func (x *Media) GetDuration() int64 {
return 0
}
func (x *Media) GetData() []byte {
if x != nil {
return x.Data
}
return nil
}
type Turn struct {
state protoimpl.MessageState `protogen:"open.v1"`
TurnId string `protobuf:"bytes,1,opt,name=turn_id,json=turnId,proto3" json:"turn_id,omitempty"`
@@ -2890,7 +2904,7 @@ const file_gateway_v1_chat_proto_rawDesc = "" +
"parameters\x18\x03 \x01(\tR\n" +
"parameters\x12\x16\n" +
"\x06output\x18\x04 \x01(\tR\x06output\x12\x14\n" +
"\x05error\x18\x05 \x01(\tR\x05error\"\xdc\x02\n" +
"\x05error\x18\x05 \x01(\tR\x05error\"\xf0\x02\n" +
"\x05Media\x12\x1b\n" +
"\ttool_name\x18\x01 \x01(\tR\btoolName\x12\x12\n" +
"\x04type\x18\x02 \x01(\tR\x04type\x12\x17\n" +
@@ -2903,7 +2917,8 @@ const file_gateway_v1_chat_proto_rawDesc = "" +
"\x05width\x18\t \x01(\x03H\x01R\x05width\x88\x01\x01\x12\x1b\n" +
"\x06height\x18\n" +
" \x01(\x03H\x02R\x06height\x88\x01\x01\x12\x1f\n" +
"\bduration\x18\v \x01(\x03H\x03R\bduration\x88\x01\x01B\f\n" +
"\bduration\x18\v \x01(\x03H\x03R\bduration\x88\x01\x01\x12\x12\n" +
"\x04data\x18\f \x01(\fR\x04dataB\f\n" +
"\n" +
"_file_sizeB\b\n" +
"\x06_widthB\t\n" +
+7 -4
View File
@@ -50,10 +50,13 @@ type Inbound struct {
// Media carries files the sender attached to this message (photos,
// documents, voice, video) with their in-process bytes already
// downloaded. Like Page and BudgetKey it is transport-only: it never
// crosses a gRPC or persistence boundary, and the stored Message
// records the attachment as a short textual note in its Text instead,
// because download URLs expire and raw media bytes must not silently
// inflate the transcript store. nil for a text-only message.
// crosses a persistence boundary, and the stored Message records the
// attachment as a short textual note in its Text instead, because
// download URLs expire and raw media bytes must not silently inflate
// the transcript store. It does cross the inbound request to the
// Gateway process that runs the turn -- that process has no platform
// credential, so the bytes have no other way to reach the model. nil
// for a text-only message.
Media []MediaAttachment
}
+14 -2
View File
@@ -1,5 +1,14 @@
package messaging
// MaxInboundAttachmentBytes is the transport ceiling for an attachment a
// channel frontend carries across the inbound wire to the process that runs
// the turn. It is a ceiling, not a policy: a frontend may refuse earlier
// (Telegram's Bot API caps getFile at 20 MB), and anything larger must
// degrade to a notice instead of failing the request that carries it.
// The Gateway's gRPC receive limit is sized from this value, so a maximal
// attachment is accepted rather than rejected as an oversized message.
const MaxInboundAttachmentBytes = 20 << 20
// MediaAttachment describes a file attached to a message. Platform-agnostic;
// platform-specific fields live in Raw.
//
@@ -53,7 +62,10 @@ type MediaAttachment struct {
// Data carries the attachment bytes in-process. An inbound path sets
// it after downloading the file; outbound senders never set it and
// read Path or URL instead. It never crosses a wire or persistence
// boundary -- it is a turn-scoped value, not a stored one.
// read Path or URL instead. It crosses the wire in one direction only:
// the inbound request from a channel frontend to the Gateway process
// that runs the turn, because that process never holds the platform
// credential. It is never persisted, and the stored-history and
// outbound-event directions strip it.
Data []byte `json:"data,omitempty"`
}
+41 -8
View File
@@ -64,7 +64,7 @@ func inboundProto(v messaging.Inbound) *pb.Message {
m.Page = v.Page
m.BudgetKey = v.BudgetKey
m.Platform = v.Platform
m.Media = attachmentProtoList(v.Media)
m.Media = inboundAttachmentProtoList(v.Media)
return m
}
@@ -78,7 +78,9 @@ func inboundValue(v *pb.Message) messaging.Inbound {
}
msg := storedValue(v)
msg.Role = messaging.RoleUser
return messaging.Inbound{Message: msg, Page: v.Page, BudgetKey: v.BudgetKey, Platform: v.Platform, Media: attachmentValueList(v.GetMedia())}
// The record keeps the metadata the store persists; the transport media
// carries the bytes the turn model reads, which the record must not hold.
return messaging.Inbound{Message: msg, Page: v.Page, BudgetKey: v.BudgetKey, Platform: v.Platform, Media: inboundAttachmentValueList(v.GetMedia())}
}
func toolProto(v messaging.ToolCallEvent) *pb.ToolCall {
@@ -175,12 +177,12 @@ func intPointer(v *int64) *int {
return &n
}
// attachmentProtoList renders a message's attachments in wire shape. Data
// is deliberately unmapped: it is a turn-scoped in-process value and must
// never cross the wire, matching the persisted record which strips it too.
// An attachment with no fields beyond Data would produce an empty wire
// message, which is still the honest encoding of "metadata was stripped",
// and never happens for a real attachment.
// attachmentProtoList renders a message's attachments in wire shape for the
// stored-history and outbound-event directions. Data is deliberately
// unmapped: those directions must not carry a turn's bytes, and a persisted
// record strips them too. An attachment with no fields beyond Data would
// produce an empty wire message, which is still the honest encoding of
// "metadata was stripped", and never happens for a real attachment.
func attachmentProtoList(media []messaging.MediaAttachment) []*pb.Media {
if len(media) == 0 {
return nil
@@ -195,6 +197,25 @@ func attachmentValueList(list []*pb.Media) []messaging.MediaAttachment {
return mapValues(list, attachmentValue)
}
// inboundAttachmentProtoList renders a turn's attachments for the inbound
// request. Unlike the stored direction, Data rides along: the channel
// frontend downloads the file, but the Gateway process that runs the turn
// never holds the platform credential, so the bytes have no other way to
// reach the model.
func inboundAttachmentProtoList(media []messaging.MediaAttachment) []*pb.Media {
if len(media) == 0 {
return nil
}
return mapValues(media, inboundAttachmentProto)
}
func inboundAttachmentValueList(list []*pb.Media) []messaging.MediaAttachment {
if len(list) == 0 {
return nil
}
return mapValues(list, inboundAttachmentValue)
}
func attachmentProto(a messaging.MediaAttachment) *pb.Media {
return &pb.Media{Type: a.Type, FileId: a.FileID, Url: a.URL, Path: a.Path, MimeType: a.MIMEType, FileName: a.FileName, FileSize: a.FileSize, Width: int64Pointer(a.Width), Height: int64Pointer(a.Height), Duration: int64Pointer(a.Duration)}
}
@@ -206,6 +227,18 @@ func attachmentValue(v *pb.Media) messaging.MediaAttachment {
return messaging.MediaAttachment{Type: v.Type, FileID: v.FileId, URL: v.Url, Path: v.Path, MIMEType: v.MimeType, FileName: v.FileName, FileSize: v.FileSize, Width: intPointer(v.Width), Height: intPointer(v.Height), Duration: intPointer(v.Duration)}
}
func inboundAttachmentProto(a messaging.MediaAttachment) *pb.Media {
pm := attachmentProto(a)
pm.Data = a.Data
return pm
}
func inboundAttachmentValue(v *pb.Media) messaging.MediaAttachment {
a := attachmentValue(v)
a.Data = v.GetData()
return a
}
func mediaProto(v messaging.MediaEvent) *pb.Media {
pm := attachmentProto(v.Attachment)
pm.ToolName = v.ToolName
@@ -1,6 +1,7 @@
package gatewayrpc
import (
"bytes"
"testing"
"github.com/samcharles93/archie-core/internal/domain/messaging"
@@ -43,20 +44,24 @@ func TestStoredMediaRoundTrip(t *testing.T) {
}
// TestInboundMediaRoundTrip mirrors the stored direction for the inbound
// transport context: a frontend that names attachments on Route gets them
// back on the daemon side, minus the bytes which it must carry itself.
// transport context, except that the bytes ride along. The channel frontend
// (archie-messaging) downloads an inbound attachment, but the process that
// runs the turn is archie-gateway/archied, which never holds the Telegram
// token -- so the bytes have to cross this request or the model never sees
// the photo or document it was sent.
func TestInboundMediaRoundTrip(t *testing.T) {
raw := []byte("jpeg bytes")
in := messaging.Inbound{
Message: messaging.Message{Text: "hi", Sender: "sam"},
Media: []messaging.MediaAttachment{
{Type: "image", FileID: "f1", MIMEType: "image/jpeg", Data: []byte("jpeg")},
{Type: "image", FileID: "f1", MIMEType: "image/jpeg", Data: raw},
},
}
out := inboundValue(inboundProto(in))
if len(out.Media) != 1 || out.Media[0].FileID != "f1" || out.Media[0].Type != "image" {
t.Fatalf("round-tripped inbound media = %#v, want the sender attachment", out.Media)
}
if len(out.Media[0].Data) != 0 {
t.Errorf("inbound attachment bytes crossed the wire, want them stripped")
if !bytes.Equal(out.Media[0].Data, raw) {
t.Errorf("inbound attachment bytes = %q, want %q carried to the turn", out.Media[0].Data, raw)
}
}
+10 -3
View File
@@ -64,9 +64,9 @@ message Message {
// constant. Transport-only, never persisted: the session record keeps it.
string platform = 10;
// media carries attachment metadata for a message that arrived with a
// file. The attachment's bytes never cross this wire: a stored Media
// with tool_name empty is a sender attachment, and the tool_name on
// tool-produced events stays a stream-only field.
// file. The bytes ride only on the inbound request (see Media.data); a
// stored Media with tool_name empty is a sender attachment, and the
// tool_name on tool-produced events stays a stream-only field.
repeated Media media = 11;
}
message ToolCall {
@@ -88,6 +88,13 @@ message Media {
optional int64 width = 9;
optional int64 height = 10;
optional int64 duration = 11;
// data carries a sender attachment's bytes on an inbound request. The
// channel frontend downloads the file, but the Gateway process that runs
// the turn never holds the platform credential, so this is the only way
// the model can read a photo or document. It is empty on every other
// direction: stored history and outbound media events carry metadata
// only, and a persisted record strips the bytes.
bytes data = 12;
}
message Turn {
string turn_id = 1;