Documentation
¶
Index ¶
- Constants
- Variables
- func IsCompatible(local, remote uint32) bool
- func JSON(viewCtx view.Context) *session.S
- func NewFromInitiator(viewCtx view.Context, party view.Identity) (*session.S, error)
- func NewFromSession(viewCtx view.Context, s view.Session) *session.S
- func NewJSON(viewCtx view.Context, caller view.View, party view.Identity) (*session.S, error)
- func ReceiveTyped(s *session.S, expectedType string, dst any) error
- func ReceiveTypedWithTimeout(s *session.S, expectedType string, dst any, d time.Duration) error
- func ReceiveTypedWithTimeoutAndMetrics(s *session.S, expectedType string, dst any, d time.Duration, ...) error
- func SendTyped(s *session.S, ctx context.Context, v any, msgType string) error
- func SendTypedWithMetrics(s *session.S, ctx context.Context, v any, msgType string, m *EnvelopeMetrics) error
- func UnwrapBody(raw []byte, expectedType string, dst any) error
- type Envelope
- type EnvelopeMetrics
- type JSONMarshaller
- type TypedSession
- func NewTypedSession(viewCtx view.Context, sess view.Session) *TypedSession
- func NewTypedSessionForCaller(viewCtx view.Context, caller view.View, party view.Identity) (*TypedSession, error)
- func NewTypedSessionFromContext(viewCtx view.Context) *TypedSession
- func NewTypedSessionToParty(viewCtx view.Context, party view.Identity) (*TypedSession, error)
- type VersionError
Constants ¶
const CurrentVersion uint32 = 1
CurrentVersion is the protocol version stamped on every outgoing envelope. Receivers reject messages whose version differs from their own CurrentVersion.
Variables ¶
var ( ErrVersionMismatch = errors.New("protocol version mismatch") ErrUnsupportedVersion = errors.New("unsupported protocol version") ErrMissingVersion = errors.New("missing protocol version") ErrInvalidEnvelope = errors.New("invalid envelope format") ErrTypeMismatch = errors.New("message type mismatch") )
Sentinel errors for envelope validation.
var VersionCompatibility = map[uint32][]uint32{
1: {1},
}
VersionCompatibility defines which protocol versions can communicate. For v1, only same-version communication is supported.
Functions ¶
func IsCompatible ¶
IsCompatible returns true if local and remote versions can interoperate.
func NewFromInitiator ¶
func ReceiveTyped ¶
ReceiveTyped receives a versioned envelope, validates its version and type, and unmarshals the body into dst. Use TypedSession.ReceiveTyped to also record metrics.
func ReceiveTypedWithTimeout ¶
ReceiveTypedWithTimeout is like ReceiveTyped but with an explicit timeout.
func ReceiveTypedWithTimeoutAndMetrics ¶
func ReceiveTypedWithTimeoutAndMetrics(s *session.S, expectedType string, dst any, d time.Duration, m *EnvelopeMetrics) error
ReceiveTypedWithTimeoutAndMetrics is like ReceiveTypedWithTimeout but also records envelope metrics.
func SendTyped ¶
SendTyped wraps v in a versioned envelope with the given message type and sends it over the session. Use TypedSession.SendTyped to also record metrics.
func SendTypedWithMetrics ¶
func SendTypedWithMetrics(s *session.S, ctx context.Context, v any, msgType string, m *EnvelopeMetrics) error
SendTypedWithMetrics is like SendTyped but also records envelope metrics.
Types ¶
type Envelope ¶
type Envelope struct {
Version uint32 `json:"v"`
Type string `json:"t"`
Body json.RawMessage `json:"b"`
}
Envelope wraps all TTX interactive protocol messages with version and type information. Wire format uses compact field names for efficiency:
- "v" = Version (uint32, monotonic)
- "t" = Type discriminator (string, mandatory)
- "b" = Body (json.RawMessage, the actual payload)
func UnwrapEnvelope ¶
UnwrapEnvelope decodes raw bytes into an Envelope and validates version and (optionally) message type. If expectedType is non-empty, the type is checked; pass "" to skip the type check.
func WrapEnvelope ¶
WrapEnvelope marshals v into an Envelope with the given message type.
type EnvelopeMetrics ¶
type EnvelopeMetrics struct {
Sent metrics.Counter
Received metrics.Counter
Errors metrics.Counter
Size metrics.Histogram
}
EnvelopeMetrics holds the counters and histograms for envelope operations. A nil *EnvelopeMetrics is safe and disables metrics (all observe* methods no-op).
func GetEnvelopeMetrics ¶
func GetEnvelopeMetrics(sp token.ServiceProvider) (*EnvelopeMetrics, error)
GetEnvelopeMetrics resolves the *EnvelopeMetrics registered in the service provider. It returns an error when no metrics are registered (e.g. in lightweight test contexts), in which case callers treat metrics as disabled.
func NewEnvelopeMetrics ¶
func NewEnvelopeMetrics(p metrics.Provider) *EnvelopeMetrics
NewEnvelopeMetrics registers and returns metrics using the given provider. It is wired into the dependency-injection container (see token/sdk/dig) so that GetEnvelopeMetrics can resolve it from a view context.
type TypedSession ¶
TypedSession wraps a JSON session together with the envelope metrics resolved from the view context, so callers send and receive versioned messages through methods (and get metrics recorded) instead of static helpers.
func NewTypedSession ¶
func NewTypedSession(viewCtx view.Context, sess view.Session) *TypedSession
NewTypedSession wraps the given view.Session, resolving the envelope metrics once from the view context. Metrics are disabled when none are registered.
func NewTypedSessionForCaller ¶
func NewTypedSessionForCaller(viewCtx view.Context, caller view.View, party view.Identity) (*TypedSession, error)
NewTypedSessionForCaller opens a session to party for the given caller view and wraps it.
func NewTypedSessionFromContext ¶
func NewTypedSessionFromContext(viewCtx view.Context) *TypedSession
NewTypedSessionFromContext wraps the view context's own session.
func NewTypedSessionToParty ¶
NewTypedSessionToParty opens a session to party (bound to the context's initiator) and wraps it.
func (*TypedSession) ReceiveTyped ¶
func (t *TypedSession) ReceiveTyped(expectedType string, dst any) error
ReceiveTyped receives a versioned envelope into dst, recording metrics.
func (*TypedSession) ReceiveTypedWithTimeout ¶
ReceiveTypedWithTimeout receives a versioned envelope into dst with an explicit timeout, recording metrics.
type VersionError ¶
VersionError provides structured detail about a version mismatch.
func (*VersionError) Error ¶
func (e *VersionError) Error() string
func (*VersionError) Is ¶
func (e *VersionError) Is(target error) bool
Source Files