Documentation
¶
Overview ¶
Package protocol implements the framed experimental Pi wire contract.
Index ¶
- Constants
- func DecodeCbor(data []byte, options CborOptions) (any, error)
- func EncodeCbor(value any, options CborOptions) ([]byte, error)
- func EncodeClientMessage(message ClientMessage, options FrameDecoderOptions) ([]byte, error)
- func EncodeFrame(payload []byte) ([]byte, error)
- func EncodeServerMessage(message ServerMessage, options FrameDecoderOptions) ([]byte, error)
- func FromJSON(data json.RawMessage) (any, error)
- func IsServerId(value string) bool
- func IsSupportedProtocolVersion(value float64) bool
- func ToJSON(value any) (json.RawMessage, error)
- type AttachmentEnvelope
- type CancelEnvelope
- type CborError
- type CborOptions
- type ClientHello
- type ClientMessage
- type ClientMessageDecoder
- type FrameDecoder
- type FrameDecoderOptions
- type FrameError
- type Object
- type Property
- type ProtocolError
- type ProtocolErrorCode
- type ProtocolValidationError
- type RangeError
- type RequestEnvelope
- type ResponseEnvelope
- type RpcTarget
- type ServerHello
- type ServerHelloError
- type ServerId
- type ServerMessage
- type ServerMessageDecoder
- type ServerTarget
- type ServiceEventEnvelope
- type SessionTarget
- type Symbol
- type Undefined
Constants ¶
const ( DefaultMaxCborByteLength = 16 * 1024 * 1024 DefaultMaxCborContainerLength = 1_000_000 DefaultMaxCborDepth = 64 )
const DefaultMaxFrameLength = 16 * 1024 * 1024
DefaultMaxFrameLength bounds one framed CBOR payload.
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 ¶
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 ¶
IsServerId requires a lowercase canonical UUIDv4.
func IsSupportedProtocolVersion ¶
IsSupportedProtocolVersion accepts only pinned integer version 8.
Types ¶
type AttachmentEnvelope ¶
type AttachmentEnvelope struct{ Attachment *SessionTarget }
type CancelEnvelope ¶
type CborError ¶
type CborError struct{ Message string }
CborError reports a value outside the strict definite-length protocol subset.
type CborOptions ¶
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.
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.
type Property ¶
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 ProtocolErrorCode ¶
type ProtocolErrorCode = string
ProtocolErrorCode is the opaque routing error code; any non-empty string is valid.
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 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 ServerHelloError ¶
type ServerHelloError struct{ Error ProtocolError }
type ServerId ¶
type ServerId = string
ServerId is a logical server identity: a lowercase canonical UUIDv4 (IsServerId).
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 SessionTarget ¶
type SessionTarget struct{ ServerId, SessionId, AttachmentId string }