session

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
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

View Source 
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.

View Source 
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 added in v0.12.1 

func IsCompatible(local, remote uint32) bool

IsCompatible returns true if local and remote versions can interoperate.

func JSON 

func JSON(viewCtx view.Context) *session.S

func NewFromInitiator 

func NewFromInitiator(viewCtx view.Context, party view.Identity) (*session.S, error)

func NewFromSession 

func NewFromSession(viewCtx view.Context, s view.Session) *session.S

func NewJSON 

func NewJSON(viewCtx view.Context, caller view.View, party view.Identity) (*session.S, error)

func ReceiveTyped added in v0.12.1 

func ReceiveTyped(s *session.S, expectedType string, dst any) error

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 added in v0.12.1 

func ReceiveTypedWithTimeout(s *session.S, expectedType string, dst any, d time.Duration) error

ReceiveTypedWithTimeout is like ReceiveTyped but with an explicit timeout.

func ReceiveTypedWithTimeoutAndMetrics added in v0.12.1 

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 added in v0.12.1 

func SendTyped(s *session.S, ctx context.Context, v any, msgType string) error

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 added in v0.12.1 

func SendTypedWithMetrics(s *session.S, ctx context.Context, v any, msgType string, m *EnvelopeMetrics) error

SendTypedWithMetrics is like SendTyped but also records envelope metrics.

func UnwrapBody added in v0.12.1 

func UnwrapBody(raw []byte, expectedType string, dst any) error

UnwrapBody is a convenience that unwraps an envelope and unmarshals the body into dst in a single call.

Types

type Envelope added in v0.12.1 

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 added in v0.12.1 

func UnwrapEnvelope(raw []byte, expectedType string) (*Envelope, error)

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 added in v0.12.1 

func WrapEnvelope(v any, msgType string) (*Envelope, error)

WrapEnvelope marshals v into an Envelope with the given message type.

func (*Envelope) Validate added in v0.12.1 

func (e *Envelope) Validate(expectedType string) error

Validate checks that the envelope carries the expected message type.

type EnvelopeMetrics added in v0.12.1 

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 added in v0.12.1 

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 added in v0.12.1 

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 JSONMarshaller added in v0.11.0 

type JSONMarshaller struct{}

JSONMarshaller is the default JSON marshaller.

func (JSONMarshaller) Marshal added in v0.11.0 

func (JSONMarshaller) Marshal(v any) ([]byte, error)

func (JSONMarshaller) Unmarshal added in v0.11.0 

func (JSONMarshaller) Unmarshal(data []byte, v any) error

type TypedSession added in v0.12.1 

type TypedSession struct {
	*session.S
	// contains filtered or unexported fields
}

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 added in v0.12.1 

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 added in v0.12.1 

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 added in v0.12.1 

func NewTypedSessionFromContext(viewCtx view.Context) *TypedSession

NewTypedSessionFromContext wraps the view context's own session.

func NewTypedSessionToParty added in v0.12.1 

func NewTypedSessionToParty(viewCtx view.Context, party view.Identity) (*TypedSession, error)

NewTypedSessionToParty opens a session to party (bound to the context's initiator) and wraps it.

func (*TypedSession) ReceiveTyped added in v0.12.1 

func (t *TypedSession) ReceiveTyped(expectedType string, dst any) error

ReceiveTyped receives a versioned envelope into dst, recording metrics.

func (*TypedSession) ReceiveTypedWithTimeout added in v0.12.1 

func (t *TypedSession) ReceiveTypedWithTimeout(expectedType string, dst any, d time.Duration) error

ReceiveTypedWithTimeout receives a versioned envelope into dst with an explicit timeout, recording metrics.

func (*TypedSession) SendTyped added in v0.12.1 

func (t *TypedSession) SendTyped(ctx context.Context, v any, msgType string) error

SendTyped wraps v in a versioned envelope and sends it, recording metrics.

type VersionError added in v0.12.1 

type VersionError struct {
	Expected uint32
	Received uint32
	Message  string
}

VersionError provides structured detail about a version mismatch.

func (*VersionError) Error added in v0.12.1 

func (e *VersionError) Error() string

func (*VersionError) Is added in v0.12.1 

func (e *VersionError) Is(target error) bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.