protocol

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2026 License: MIT Imports: 13 Imported by: 0

README

Experimental binary protocol

This package implements the pinned Pi protocol-v8 envelopes, strict CBOR subset, and four-byte big-endian framing. It does not start listeners, select a gateway, or enable experimental commands in the stable CLI.

Values and validation

Use Object for ordered JavaScript own properties. It preserves insertion order and enumerates numeric index keys first. __proto__ is ordinary data. Use Undefined to represent an omitted object property. Undefined array entries and symbol properties are rejected. Go nil represents JSON null. A ResponseEnvelope uses HasResult to distinguish a missing result from an explicit null result.

Envelope parsers accept decoded values, not JSON text. Use FromJSON and ToJSON only at the Go Chord json.RawMessage boundary. This conversion preserves numeric-key ordering, last-value duplicate keys, and lone UTF-16 units. CBOR subsequently rejects non-scalar strings rather than replacing them. An absent result stays absent; callers do not convert it to JSON null. The client/server message and routing target sets are closed Go unions. Payloads remain opaque strict JSON. The protocol layer does not interpret Chord service calls. It rejects non-finite numbers, byte strings inside JSON payloads, undefined properties, and cycles. The CBOR layer independently rejects unsafe integers, malformed UTF-8, tags, indefinite lengths, unsupported floating-point widths, duplicate map keys, and trailing data.

Ownership and limits

Encoding and decoding are synchronous. Run transport work outside a TUI input or render loop. Each decoder belongs to one ordered connection reader.

The default frame and CBOR byte limit is 16 MiB. A frame decoder allocates 64 KiB payload blocks as bytes arrive instead of allocating the full declared length after reading a header. Returned frames and byte strings do not alias incoming chunks. Limit and truncation failures discard partial framing state and permanently fail the decoder. Ending an already ended decoder is an error.

The CBOR defaults permit one million container entries and depth 64. Caller options preserve explicit zero separately from an omitted value. No background tasks or timers are created by this package.

Qualification

framing_test.go, cbor_test.go, and messages_test.go retain the corresponding pinned packages/protocol/test/ cases, vectors, split points, limits, errors, and source citations. This lane runs package vet and lint only. Runtime qualification belongs to the merged test run; the package does not claim tested interoperability or performance measurements yet.

Documentation

Overview

Package protocol implements the framed experimental Pi wire contract.

Index

Constants

View Source
const (
	DefaultMaxCborByteLength      = 16 * 1024 * 1024
	DefaultMaxCborContainerLength = 1_000_000
	DefaultMaxCborDepth           = 64
)
View Source
const DefaultMaxFrameLength = 16 * 1024 * 1024

DefaultMaxFrameLength bounds one framed CBOR payload.

View Source
const ProtocolVersion = 8

ProtocolVersion is the exact pinned upstream protocol version, not a PiG-owned format version.

Variables

This section is empty.

Functions

func DecodeCbor

func DecodeCbor(data []byte, options CborOptions) (any, error)

DecodeCbor decodes exactly one strict RFC 8949 item. Map keys remain own Object properties, never prototype mutations.

func EncodeCbor

func EncodeCbor(value any, options CborOptions) ([]byte, error)

EncodeCbor encodes the strict, definite-length RFC 8949 subset with finite safe numbers, scalar Unicode strings, byte strings, arrays, and ordered Objects.

func EncodeClientMessage

func EncodeClientMessage(message ClientMessage, options FrameDecoderOptions) ([]byte, error)

EncodeClientMessage validates and encodes one complete CBOR frame.

func EncodeFrame

func EncodeFrame(payload []byte) ([]byte, error)

EncodeFrame copies payload after its four-byte unsigned big-endian length.

func EncodeServerMessage

func EncodeServerMessage(message ServerMessage, options FrameDecoderOptions) ([]byte, error)

EncodeServerMessage validates and encodes one complete CBOR frame.

func FromJSON

func FromJSON(data json.RawMessage) (any, error)

FromJSON decodes a strict JSON payload into the value representation used by the CBOR codec. It preserves lone UTF-16 units as WTF-8 so EncodeCbor rejects them instead of silently replacing them. An absent payload is not null and is rejected.

func IsServerId

func IsServerId(value string) bool

IsServerId requires a lowercase canonical UUIDv4.

func IsSupportedProtocolVersion

func IsSupportedProtocolVersion(value float64) bool

IsSupportedProtocolVersion accepts only pinned integer version 8.

func ToJSON

func ToJSON(value any) (json.RawMessage, error)

ToJSON serializes a protocol JSON value for Go service APIs. It rejects undefined, binary, cyclic, and non-finite values instead of omitting or replacing them. Omitted wire results must be handled by the caller before this conversion.

Types

type AttachmentEnvelope

type AttachmentEnvelope struct{ Attachment *SessionTarget }

type CancelEnvelope

type CancelEnvelope struct {
	Id     string
	Target RpcTarget
}

type CborError

type CborError struct{ Message string }

CborError reports a value outside the strict definite-length protocol subset.

func (*CborError) Error

func (err *CborError) Error() string

type CborOptions

type CborOptions struct {
	MaxByteLength      *float64
	MaxContainerLength *float64
	MaxDepth           *float64
}

CborOptions preserves omitted limits separately from zero and validates JavaScript numeric option semantics.

type ClientHello

type ClientHello struct{ Version float64 }

type ClientMessage

type ClientMessage interface {
	// contains filtered or unexported methods
}

ClientMessage is the closed set of client wire envelopes.

func ParseClientMessage

func ParseClientMessage(value any) (ClientMessage, error)

ParseClientMessage validates an ordered Object without parsing JSON strings or interpreting the call payload.

type ClientMessageDecoder

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

ClientMessageDecoder incrementally validates framed client messages and permanently fails after a malformed frame.

func NewClientMessageDecoder

func NewClientMessageDecoder(options FrameDecoderOptions) (*ClientMessageDecoder, error)

func (*ClientMessageDecoder) End

func (decoder *ClientMessageDecoder) End() error

func (*ClientMessageDecoder) Push

func (decoder *ClientMessageDecoder) Push(chunk []byte) ([]ClientMessage, error)

type FrameDecoder

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

FrameDecoder assembles arbitrary chunks without allocating a whole declared payload before its bytes arrive. Push copies every input; completed frames do not alias input chunks or later frames.

func NewFrameDecoder

func NewFrameDecoder(options FrameDecoderOptions) (*FrameDecoder, error)

NewFrameDecoder creates an open decoder. An omitted limit selects DefaultMaxFrameLength.

func (*FrameDecoder) End

func (decoder *FrameDecoder) End() error

End closes a clean stream or fails a truncated one. End is not idempotent.

func (*FrameDecoder) Push

func (decoder *FrameDecoder) Push(chunk []byte) ([][]byte, error)

Push emits complete frames in order. A framing error permanently fails the decoder and discards its retained partial frame.

type FrameDecoderOptions

type FrameDecoderOptions struct {
	MaxFrameLength *float64
}

FrameDecoderOptions preserves omitted limits separately from zero. Limits use JavaScript number semantics and are checked before conversion.

type FrameError

type FrameError struct{ Message string }

FrameError reports a malformed frame or an invalid decoder transition.

func (*FrameError) Error

func (err *FrameError) Error() string

type Object

type Object []Property

Object preserves JavaScript object insertion order without Go map iteration. Numeric index keys encode first; repeated keys retain their first position and last value.

func (Object) Get

func (object Object) Get(key string) (any, bool)

Get returns an own property, including __proto__, without prototype lookup.

type Property

type Property struct {
	Key   any
	Value any
}

Property is one enumerable own property of an Object. Non-string keys are rejected by the encoder, like enumerable JavaScript symbol keys.

type ProtocolError

type ProtocolError struct{ Code, Message string }

ProtocolError is the bounded routing error exposed on the wire.

type ProtocolValidationError

type ProtocolValidationError struct{ Message string }

ProtocolValidationError reports an invalid envelope or framed message.

func (*ProtocolValidationError) Error

func (err *ProtocolValidationError) Error() string

type RangeError

type RangeError struct{ Message string }

RangeError reports a numeric framing option outside Pi's accepted range.

func (*RangeError) Error

func (err *RangeError) Error() string

type RequestEnvelope

type RequestEnvelope struct {
	Id     string
	Target RpcTarget
	Call   any
}

type ResponseEnvelope

type ResponseEnvelope struct {
	Id        string
	Ok        bool
	HasResult bool
	Result    any
	Error     *ProtocolError
}

ResponseEnvelope distinguishes omitted results from explicit null. Failed responses carry Error and cannot carry a result.

type RpcTarget

type RpcTarget interface {
	// contains filtered or unexported methods
}

RpcTarget fences a call to a logical server or a live Session attachment.

type ServerHello

type ServerHello struct {
	Version  float64
	ServerId string
}

type ServerHelloError

type ServerHelloError struct{ Error ProtocolError }

type ServerMessage

type ServerMessage interface {
	// contains filtered or unexported methods
}

ServerMessage is the closed set of server wire envelopes.

func ParseServerMessage

func ParseServerMessage(value any) (ServerMessage, error)

ParseServerMessage validates a server envelope while preserving absent/null result and attachment states.

type ServerMessageDecoder

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

ServerMessageDecoder incrementally validates framed server messages and permanently fails after a malformed frame.

func NewServerMessageDecoder

func NewServerMessageDecoder(options FrameDecoderOptions) (*ServerMessageDecoder, error)

func (*ServerMessageDecoder) End

func (decoder *ServerMessageDecoder) End() error

func (*ServerMessageDecoder) Push

func (decoder *ServerMessageDecoder) Push(chunk []byte) ([]ServerMessage, error)

type ServerTarget

type ServerTarget struct{ ServerId string }

type ServiceEventEnvelope

type ServiceEventEnvelope struct {
	SubscriptionId string
	Update         any
}

type SessionTarget

type SessionTarget struct{ ServerId, SessionId, AttachmentId string }

type Symbol

type Symbol struct{ Description string }

Symbol represents a JavaScript symbol at the validation boundary. Symbols are never accepted as CBOR values or enumerable object keys.

type Undefined

type Undefined struct{}

Undefined distinguishes an omitted JavaScript property from null. It is not a CBOR value; object properties with this value are omitted.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL