wire

Documentation

Overview

Package wire frames opaque payloads (JSON-RPC messages in practice) into Bison Relay private messages. Each PM carries exactly one part:

--mcp[v=1,sid=<hex>,mid=<hex>,seq=<n>/<total>,exp=<unix>]--<base64 chunk>

A part with seq=1/1 is a complete message. Bison Relay delivers PMs as discrete, ordered, acknowledged units, so the envelope only has to distinguish MCP traffic from human chat on the same DM thread, group the chunks of oversized payloads, and carry a deadline: relay delivery is store-and-forward, so a request can arrive long after the caller stopped waiting and must be droppable.

Index

• Constants
• Variables
• func Encode(sid string, payload []byte, exp time.Time, chunkSize int) ([]string, error)
• func NewID() string
• type Assembler
  • func NewAssembler(cfg AssemblerConfig) *Assembler
  • func (a *Assembler) Add(peer string, p *Part, now time.Time) ([]byte, error)
• type AssemblerConfig
• type Part
  • func Parse(text string) (p *Part, ok bool)
  • func (p *Part) Expired(now time.Time) bool

Constants

const DefaultChunkSize = 200 * 1024

DefaultChunkSize is the raw payload bytes per part before base64. Base64 expands 4/3, so parts stay far below Bison Relay's 1 MiB routed-message floor with room for the tag and JSON framing.

const MaxParts = 64

MaxParts bounds a single message's chunk count. 64 parts at the default chunk size is ~12.8 MiB raw, beyond any payload the transport should carry.

const Version = 1

Version is the envelope version emitted by Encode and accepted by Parse.

Variables

var (
	ErrExpired  = errors.New("message deadline passed")
	ErrTooLarge = errors.New("message exceeds size bounds")
	ErrOverflow = errors.New("reassembly buffer full")
)

Functions

func Encode

func Encode(sid string, payload []byte, exp time.Time, chunkSize int) ([]string, error)

Encode frames payload into one PM body per part under sid. A zero exp emits no deadline. chunkSize <= 0 selects DefaultChunkSize.

func NewID

func NewID() string

NewID returns a fresh random 16-hex identifier for sessions and messages.

Types

type Assembler

type Assembler struct {
	// contains filtered or unexported fields
}

Assembler reassembles chunked messages with hard bounds so a hostile peer cannot grow the buffers without limit.

func NewAssembler

func NewAssembler(cfg AssemblerConfig) *Assembler

func (*Assembler) Add

func (a *Assembler) Add(peer string, p *Part, now time.Time) ([]byte, error)

Add ingests one part from peer. It returns the full payload once every chunk arrived, nil while the message is still partial, and an error when the part is expired or a bound would be exceeded (the message's state is dropped on error).

type AssemblerConfig

type AssemblerConfig struct {
	// MaxPendingPerPeer caps concurrently reassembling messages per peer.
	MaxPendingPerPeer int
	// MaxMessageBytes caps one reassembled message.
	MaxMessageBytes int64
	// MaxTotalBytes caps all buffered chunks across peers.
	MaxTotalBytes int64
	// Timeout evicts partial messages that stopped arriving.
	Timeout time.Duration
}

AssemblerConfig bounds a peer's in-flight reassembly state. The zero value selects the defaults.

type Part

type Part struct {
	SID   string
	MID   string
	Seq   int
	Total int
	// Exp is the sender-set deadline in unix seconds; 0 means none.
	Exp   int64
	Chunk []byte
}

Part is one parsed envelope.

func Parse

func Parse(text string) (p *Part, ok bool)

Parse decodes one PM body. ok is false for anything that is not a well-formed part of a supported version, so plain chat text on the same thread is silently ignored by callers.

func (*Part) Expired

func (p *Part) Expired(now time.Time) bool

Expired reports whether the part's deadline has passed at now.