diff --git a/docs/data/generated/contracts.json b/docs/data/generated/contracts.json index 8a359db66..e46e00278 100644 --- a/docs/data/generated/contracts.json +++ b/docs/data/generated/contracts.json @@ -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": { diff --git a/internal/app/archied/gateway.go b/internal/app/archied/gateway.go index e6faca138..cd3263582 100644 --- a/internal/app/archied/gateway.go +++ b/internal/app/archied/gateway.go @@ -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 diff --git a/internal/app/archied/gateway_test.go b/internal/app/archied/gateway_test.go index 70789df9e..e9355b269 100644 --- a/internal/app/archied/gateway_test.go +++ b/internal/app/archied/gateway_test.go @@ -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)) + } +} diff --git a/internal/channels/telegram/inboundmedia.go b/internal/channels/telegram/inboundmedia.go index f6b1b3086..dc2dab4ea 100644 --- a/internal/channels/telegram/inboundmedia.go +++ b/internal/channels/telegram/inboundmedia.go @@ -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") diff --git a/internal/contracts/gateway/v1/chat.pb.go b/internal/contracts/gateway/v1/chat.pb.go index d74b44727..81632b137 100644 --- a/internal/contracts/gateway/v1/chat.pb.go +++ b/internal/contracts/gateway/v1/chat.pb.go @@ -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" + diff --git a/internal/domain/messaging/inbound.go b/internal/domain/messaging/inbound.go index 7d32b28ba..f40972bcd 100644 --- a/internal/domain/messaging/inbound.go +++ b/internal/domain/messaging/inbound.go @@ -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 } diff --git a/internal/domain/messaging/media.go b/internal/domain/messaging/media.go index 6c7f370d1..02939e284 100644 --- a/internal/domain/messaging/media.go +++ b/internal/domain/messaging/media.go @@ -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"` } diff --git a/internal/infrastructure/gatewayrpc/values.go b/internal/infrastructure/gatewayrpc/values.go index 042a65e93..a12af125c 100644 --- a/internal/infrastructure/gatewayrpc/values.go +++ b/internal/infrastructure/gatewayrpc/values.go @@ -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 diff --git a/internal/infrastructure/gatewayrpc/values_media_test.go b/internal/infrastructure/gatewayrpc/values_media_test.go index b51a10321..905102327 100644 --- a/internal/infrastructure/gatewayrpc/values_media_test.go +++ b/internal/infrastructure/gatewayrpc/values_media_test.go @@ -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) } } diff --git a/proto/gateway/v1/chat.proto b/proto/gateway/v1/chat.proto index 2a8889f26..7d5008ff6 100644 --- a/proto/gateway/v1/chat.proto +++ b/proto/gateway/v1/chat.proto @@ -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;