wire

Documentation

Overview

Package wire defines the peerbus message envelope, control messages, and the newline-delimited JSON codec, plus the load-bearing canonical-form HMAC byte representation (see Canonical in codec.go for the fixed, load-bearing field order).

Index

• Constants
• Variables
• func Canonical(env Envelope) ([]byte, error)
• func CheckVersion(v string) error
• type Ack
• type ControlType
  • func ControlTypeOf(b []byte) (ControlType, error)
• type Deliver
• type Envelope
• type Kind
• type Peers
• type Register

Constants

const MaxFrameBytes = 1 << 20

MaxFrameBytes is the per-WebSocket-frame read budget applied by both the broker (server side) and the adapter client. Envelopes carry opaque application JSON, so the budget is generous (1 MiB) but bounded so a hostile peer cannot exhaust memory with an unbounded frame.

const ProtocolVersion = "v1"

ProtocolVersion is the single supported wire protocol version. Policy is exact-match-or-reject (see CheckVersion): the field exists so future negotiation is additive, but v1 implements no negotiation engine.

Variables

var ErrUnsupportedVersion = errors.New("wire: unsupported protocol version")

ErrUnsupportedVersion is returned by CheckVersion for any non-matching value.

Functions

func Canonical

func Canonical(env Envelope) ([]byte, error)

Canonical returns the deterministic byte representation of env that is fed to HMAC-SHA256. The sender signs Canonical(env); a recipient reconstructs it from the received wire bytes (marshal→unmarshal→Canonical→verify). Both must agree across machines and across protocol_version values. body is spliced in verbatim — it is never re-marshalled.

func CheckVersion

func CheckVersion(v string) error

CheckVersion enforces the v1 exact-match-or-reject policy. Any value other than the single supported ProtocolVersion constant is rejected; there is no negotiation.

Types

type Ack

type Ack struct {
	ProtocolVersion string      `json:"protocol_version"`
	Type            ControlType `json:"type"`
	ID              string      `json:"id"`
}

Ack acknowledges that the recipient has consumed the message with ID.

type ControlType

type ControlType string

ControlType discriminates a control frame.

const (
	// ControlRegister is sent by an adapter to bind a peer name under a token.
	ControlRegister ControlType = "register"
	// ControlAck acknowledges consumption of a delivered message id.
	ControlAck ControlType = "ack"
	// ControlPeers requests / returns the current peer registry.
	ControlPeers ControlType = "peers"
	// ControlDeliver carries an Envelope from the broker to a recipient.
	ControlDeliver ControlType = "deliver"
)

func ControlTypeOf

func ControlTypeOf(b []byte) (ControlType, error)

ControlTypeOf returns the ControlType discriminator of a raw control frame.

type Deliver

type Deliver struct {
	ProtocolVersion string      `json:"protocol_version"`
	Type            ControlType `json:"type"`
	DeliveryKey     string      `json:"delivery_key"`
	Envelope        Envelope    `json:"envelope"`
}

Deliver wraps an Envelope pushed from the broker to a recipient.

DeliveryKey is the broker's per-recipient durable row key (the store Message.ID). It is carried OUTSIDE the signed Envelope deliberately: the Envelope is byte-identical to what the sender signed (so the recipient's end-to-end HMAC verifies, including for broadcast — to:"*", original id), while the routing/ack identity lives on this control frame, which is NOT covered by the HMAC. The recipient acks by DeliveryKey, not Envelope.ID, so each per-recipient broadcast copy is independently ackable without mutating (and thus invalidating) the signed envelope. For a direct message DeliveryKey equals Envelope.ID.

type Envelope

type Envelope struct {
	ProtocolVersion string          `json:"protocol_version"`
	ID              string          `json:"id"`
	From            string          `json:"from"`
	To              string          `json:"to"`
	TS              string          `json:"ts"`
	Source          string          `json:"source"`
	Kind            Kind            `json:"kind"`
	Body            json.RawMessage `json:"body"`
	HMAC            string          `json:"hmac"`
}

Envelope is the end-to-end peerbus message carried over the WS data channel as one newline-delimited JSON object. body is opaque application JSON: it is hashed verbatim and MUST NOT be re-encoded (re-marshalling opaque JSON is not byte-stable). hmac is the hex-encoded HMAC-SHA256 over Canonical(env).

type Kind

type Kind string

Kind enumerates the envelope delivery semantics.

const (
	// KindMsg is a direct (to:<name>) message.
	KindMsg Kind = "msg"
	// KindBroadcast is a fan-out (to:*) message.
	KindBroadcast Kind = "broadcast"
)

type Peers

type Peers struct {
	ProtocolVersion string      `json:"protocol_version"`
	Type            ControlType `json:"type"`
	Names           []string    `json:"names"`
}

Peers is the registry request/response. When sent by an adapter Names is empty; the broker replies with the currently-registered peer names.

type Register

type Register struct {
	ProtocolVersion string      `json:"protocol_version"`
	Type            ControlType `json:"type"`
	Token           string      `json:"token"`
	Name            string      `json:"name"`
}

Register binds a unique peer name under a bearer token. The HMAC secret is shared out-of-band, never sent on the wire.