transport.go RawHistoryFolder

1package wire
2
3import "context"
4
5// Envelope is the unit of exchange over a Transport: one complete
6// serialized Protobuf envelope (client, server, or preamble), without any
7// legacy type byte. The payload is owned by the caller on Send and by the
8// receiver on Recv; Transports copy across queue boundaries so either side
9// may retain it.
10type Envelope struct {
11	Payload []byte
12}
13
14// Transport is an envelope channel over a single connection. Close must be
15// safe to call concurrently with Send and Recv, and must unblock active
16// Send and Recv calls.
17type Transport interface {
18	Send(Envelope) error
19	Recv() (Envelope, error) // blocking; io.EOF on close
20	Close() error
21}
22
23// DatagramTransport marks transports backed by a datagram link. Typed session
24// adapters translate this carriage detail into semantic capabilities.
25type DatagramTransport interface {
26	Transport
27	DatagramTransport()
28}
29
30// AsyncTransport accepts envelopes for ordered background transmission.
31// SendAsync returns once the adapter owns the envelope; Send retains its
32// synchronous wire-attempt contract. Daemon paint output may use this
33// capability to pipeline.
34type AsyncTransport interface {
35	SendAsync(Envelope) error
36}
37
38// OwnedSynchronousTransport owns the complete bounded synchronous operation,
39// including adapter queues, pacing, write deadlines, and close cancellation.
40type OwnedSynchronousTransport interface {
41	SendSynchronous(Envelope) error
42}
43
44// BoundedTransport is a Transport whose receive path accepts a caller-supplied
45// ceiling: RecvBounded validates the framed length prefix against limit before
46// allocating or reading the body, so a peer cannot force a large allocation by
47// advertising a huge frame. The effective bound is the smaller of limit and the
48// transport's own framed ceiling, so it can only narrow a carriage that already
49// enforces one. Every vev stream carriage (IPC, QUIC, SSH stdio) implements it;
50// callers that need a bounded read assert this optional capability, leaving the
51// base Transport contract unchanged.
52type BoundedTransport interface {
53	Transport
54	RecvBounded(limit uint64) (Envelope, error)
55}
56
57// Dialer establishes outbound raw carriage connections.
58type Dialer interface {
59	Dial(context.Context) (Transport, error)
60}
61
62// Listener accepts incoming raw carriage connections.
63type Listener interface {
64	Accept() (Transport, error)
65	Close() error
66	Addr() string
67}