Documentation
¶
Overview ¶
Package wire defines the framing and message types used between the intercom shim and broker over a Unix domain socket.
Frames are 4-byte big-endian length-prefixed UTF-8 JSON. Each JSON object carries a "kind" discriminator. The Go API uses one concrete type per kind (see Hello, Welcome, Send, SendAck, ListPeers, ListPeersReply, Deliver, Goodbye, Error), all satisfying the Frame interface. See docs/BROKER_PROTOCOL.md for the protocol contract.
Index ¶
Constants ¶
const MaxFrameSize = 256 * 1024
MaxFrameSize bounds a single frame's JSON payload. Frames larger than this are refused by both shim and broker.
const MaxNameLen = 64
MaxNameLen caps peer name length to keep error messages and meta values bounded.
Variables ¶
var ErrOversize = errors.New("wire: frame exceeds max size")
ErrOversize is returned when a frame exceeds MaxFrameSize. An oversize inbound length makes the connection unusable because the payload remains on the stream. An outbound oversize frame is rejected before any bytes are written, so the connection remains usable.
var ErrShortRead = errors.New("wire: short read")
ErrShortRead is returned when the underlying reader returns EOF mid-frame.
Functions ¶
func EncodedFrameSize ¶
EncodedFrameSize returns the number of JSON payload bytes a frame occupies, excluding the four-byte length prefix. Callers that accept user-controlled strings can use this to reject JSON-escaping expansion before a write.
Types ¶
type Code ¶
type Code string
Code enumerates wire-level error codes carried on Error and SendAck frames.
const ( CodeBadHello Code = "bad_hello" CodeBadName Code = "bad_name" CodeNameTaken Code = "name_taken" CodeHelloTimeout Code = "hello_timeout" CodeNoSuchPeer Code = "no_such_peer" CodeNoSelfSend Code = "no_self_send" CodeDeliverFailed Code = "deliver_failed" CodeOversize Code = "oversize" CodeBadFrame Code = "bad_frame" )
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is a length-prefixed JSON frame channel over an io.ReadWriter.
Write is goroutine-safe (a per-Conn gate serializes writes). Read is not; drive a single read goroutine per connection.
func NewConn ¶
func NewConn(rw io.ReadWriter) *Conn
NewConn wraps rw in a length-prefixed JSON frame channel.
func (*Conn) Read ¶
Read consumes one frame from the connection. It returns:
- (frame, nil) on success;
- (nil, io.EOF) at clean stream end (no bytes read);
- (nil, ErrShortRead) on EOF mid-frame;
- (nil, ErrOversize) when the announced length exceeds MaxFrameSize. The connection is unusable and the caller should close it after writing any final error frame;
- (nil, other error) on any other I/O or decode error.
func (*Conn) Write ¶
Write encodes f and sends it as a single length-prefixed JSON frame. If the encoded payload exceeds MaxFrameSize, Write returns ErrOversize and nothing is written.
func (*Conn) WriteWithTimeout ¶
WriteWithTimeout is like Conn.Write, with timeout as one total budget for encoding, waiting behind another writer, and writing this frame. timeout <= 0 means no deadline.
The socket deadline is applied while holding the per-Conn write gate, so concurrent callers don't clobber each other's deadlines. A caller whose budget expires while queued returns without touching the stream.
If the underlying io.ReadWriter doesn't support SetWriteDeadline (e.g. a bytes.Buffer in tests), the queue wait is still bounded but an in-progress underlying Write cannot be interrupted.
type Deliver ¶
type Deliver struct {
ID string `json:"id,omitempty"`
From string `json:"from"`
Message string `json:"message"`
Timestamp string `json:"timestamp"`
}
Deliver: the broker pushes a message to a peer. ID is copied from the originating Send when available; it is optional for compatibility with older brokers. From is the sender's registered (and validated) name.
type Error ¶
type Error struct {
ID string `json:"id,omitempty"`
Code Code `json:"code"`
Message string `json:"message"`
}
Error: a wire-level error. ID is set when responding to a request that carried one; omitted for unsolicited errors (oversize, bad_frame on a frame that couldn't be parsed, hello_timeout).
type Frame ¶
type Frame interface {
Kind() Kind
// contains filtered or unexported methods
}
Frame is the sealed sum type implemented by every concrete frame.
type Goodbye ¶
type Goodbye struct {
Reason string `json:"reason"`
}
Goodbye: the broker is closing this connection (shutdown or idle exit).
type ListPeers ¶
type ListPeers struct {
ID string `json:"id"`
}
ListPeers: the shim asks for the names of currently-connected peers.
type ListPeersReply ¶
ListPeersReply: response to ListPeers. Peers excludes the requester and is sorted lexicographically.
func (ListPeersReply) Kind ¶
func (ListPeersReply) Kind() Kind
type SendAck ¶
type SendAck struct {
ID string `json:"id"`
OK bool `json:"ok"`
Code Code `json:"code,omitempty"`
Message string `json:"message,omitempty"`
}
SendAck: the broker's reply to a Send. OK=true on success; on failure, Code and Message describe the reason.
func SendAckErr ¶
SendAckErr builds a failure send_ack with the given code and message.
Source Files