runtime

type AdapterContext ¶ added in v0.6.0

type AdapterContext struct {
	Options          Options
	ValueEnvironment ValueEnvironment
}

AdapterContext carries runtime options used when constructing model wires.

type Backpressure ¶

type Backpressure struct {
	At       time.Time
	Queued   int
	Stalled  bool
	Deadline time.Duration
}

Backpressure is a queue that could not take a frame: Queued is its depth, Deadline the write deadline the producer then waited out where it waited, and Stalled the peer giving up on the consumer and closing the connection.

func (Backpressure) ObserverEvent()

type ConnectionClosed ¶

type ConnectionClosed struct {
	At     time.Time
	Code   int
	Reason string
	Local  bool
}

ConnectionClosed is the connection ending, once and whatever ended it. Local says this side ended it, which is every case but the one a peer can lay at the other's door: a close the remote sent, with its code and its reason.

func (ConnectionClosed) ObserverEvent()

type ConnectionOpened ¶

type ConnectionOpened struct {
	At   time.Time
	Role Role
}

ConnectionOpened is the peer taking the connection over, before it has read or written anything on it.

func (ConnectionOpened) ObserverEvent()

type DeclarationIdentity ¶ added in v0.6.0

type DeclarationIdentity struct {
	Path   string `json:"path"`
	Digest string `json:"digest,omitempty"`
}

DeclarationIdentity names a declaration and, when specified, its generated SHA-256 digest. An empty Digest is omitted from the exchange.

func CallableIdentity(binding TypeBinding) (DeclarationIdentity, error)

type DialOptions ¶

type DialOptions struct {
	Options    Options
	HTTPHeader http.Header
	HTTPClient *http.Client
	// ConnectTimeout bounds the handshake alone, as TypeScript's
	// connectTimeoutMs does, and takes the same default of 30 seconds where
	// it is zero. A dial that has not become a connection by then is refused
	// with the code connect_timeout and nothing is opened; the connection's
	// own lifetime is the context's, as it is without one.
	ConnectTimeout time.Duration
	// Subprotocols are offered to the server in order of preference; the
	// default offers none. A server that selects none leaves the connection
	// with none and the profile is spoken over it either way — but a browser
	// refuses a handshake whose offer went unselected, so a client that
	// offers must be met by a server that selects (docs/wire/profile.md).
	Subprotocols []string
}

DialOptions is what Dial opens a WebSocket with: the peer's Options, the headers and client of the HTTP upgrade, the bound on the handshake, and the subprotocols to offer.

type Dispatcher ¶ added in v0.6.0

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

Dispatcher owns one endpoint attachment and an explicit exact/longest-prefix routing policy. It captures each request's traversal on the invocation its return capability carries, through the public vocabulary alone, and refuses a request whose return capability carries none rather than routing it with weaker detach and cancellation guarantees. An opaque wrapper is therefore as good as a native endpoint: the lifecycle travels with the unchanged return capability, and nothing here recognizes a concrete type.

func NewDispatcher(root duplex.Endpoint, options ...DispatcherOptions) (*Dispatcher, error)

func (d *Dispatcher) Close(code duplex.Code, reason string) error

func (d *Dispatcher) Register(path []string, receiver duplex.Receiver) (func(), error)

func (d *Dispatcher) RegisterPrefix(path []string, receiver duplex.Receiver) (func(), error)

func (d *Dispatcher) Select(path []string) *SelectedEndpoint

func (d *Dispatcher) Send(path []string, message duplex.Message) error

type DispatcherOptions ¶ added in v0.6.0

type DispatcherOptions struct{ OwnEndpoint bool }

DispatcherOptions explicitly transfers closure authority for an endpoint the caller owns. Borrowed endpoints remain the default.

type Event ¶

type Event struct {
	Name string          `json:"event"`
	Data json.RawMessage `json:"data"`
}

Event is one event of the profile as a handler or an emitter sees it: its name and its data.

type EventDelivered ¶

type EventDelivered struct {
	At     time.Time
	Name   string
	Bytes  int
	Trace  Trace
	Family string
}

EventDelivered is an event reaching the application, before its handler and the listeners run.

func (EventDelivered) ObserverEvent()

type EventEmitted ¶

type EventEmitted struct {
	At     time.Time
	Name   string
	Bytes  int
	Trace  Trace
	Family string
}

EventEmitted is the application emitting an event, before the frame carrying it is queued. Bytes is the size of the event's data, as EventDelivered's is.

func (EventEmitted) ObserverEvent()

type EventHandler ¶

type EventHandler func(context.Context, *Peer, json.RawMessage)

EventHandler takes one event's data; events have no answer. Handlers run one at a time in the order the events arrived.

type FrameReceived ¶

type FrameReceived struct {
	At     time.Time
	Kind   string
	Name   string
	Bytes  int
	ID     string
	Trace  Trace
	Family string
}

FrameReceived is one frame the decoder accepted, before anything routed it. A frame the decoder refused closes the connection and is no frame at all.

func (FrameReceived) ObserverEvent()

type FrameSent ¶

type FrameSent struct {
	At     time.Time
	Kind   string
	Name   string
	Bytes  int
	ID     string
	Trace  Trace
	Family string
}

FrameSent is one frame handed to the transport, which is as far as this peer carries it: told by the writer immediately before the bytes leave, so that a frame is observed sent before anything it draws can be received. Name is what the frame names — the method of a request, the name of an event — and a response and a cancel name nothing, a response's method being no member of the wire.

func (FrameSent) ObserverEvent()

type Handler ¶

type Handler func(context.Context, *Peer, json.RawMessage) (any, error)

Handler answers one request: it takes the params as they arrived and returns the result, or an error — a *PublicError crosses the wire with its code; any other error reaches the caller as internal. The context is cancelled when the caller withdraws the request or its deadline passes, and carries the trace and the meta the frame brought.

func IdentityHandler(expected DeclarationIdentity) (Handler, error)

type HandlerPanic ¶

type HandlerPanic struct {
	At     time.Time
	Method string
	Value  string
	Trace  Trace
	Family string
}

HandlerPanic is a method handler that gave up. Value is the panic value as %v renders it and nothing else: what the handler was given is the handler's, and reaches no observer here.

func (HandlerPanic) ObserverEvent()

type HandlerRegistry ¶ added in v0.6.0

type HandlerRegistry interface {
	duplex.Wire
	Register([]string, duplex.Receiver) (func(), error)
	Close(duplex.Code, string) error
}

HandlerRegistry is the explicit registration capability used by generated bindings. Closing it releases its registrations, not its borrowed carrier.

type IdentityPreparation ¶ added in v0.6.0

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

IdentityPreparation installs model receivers before a carrier starts reading, checks its declaration after attachment, and releases dispatch after binding. It owns its registrations, never the source carrier or another receive queue.

func PrepareIdentity(wire duplex.Endpoint, expected DeclarationIdentity, options Options) (*IdentityPreparation, error)

func (p *IdentityPreparation) Check(ctx context.Context) error

func (p *IdentityPreparation) Close()

func (p *IdentityPreparation) Ready() error

func (p *IdentityPreparation) Wire() HandlerRegistry

type Invocation ¶ added in v0.6.0

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

Invocation is the lifecycle an admitting runtime keeps for one admitted request, and the answer its return capability gives to the vocabulary above. A runtime that is not Nightseam's composes it — or answers the same paths itself — and the same participants work against either.

func NewInvocation(limits InvocationLimits, onRetired func()) *Invocation

func (v *Invocation) Deliver(path []string, message duplex.Message) error

func (v *Invocation) DispatchDone()

func (v *Invocation) Retired() bool

func (v *Invocation) Settle()

type InvocationBodyHandle ¶ added in v0.6.0

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

InvocationBodyHandle is one execution lease of one admitted invocation.

func BeginInvocationBody(message duplex.Message) (*InvocationBodyHandle, error)

func (b *InvocationBodyHandle) Done()

type InvocationCaptureHandle ¶ added in v0.6.0

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

InvocationCaptureHandle is one immutable routing decision a participant took for one traversal of one admitted invocation. Repeated traversal of the same dispatcher takes a fresh handle, so no two traversals share a slot.

func CaptureInvocation(message duplex.Message, control func(duplex.Message)) (*InvocationCaptureHandle, error)

func (c *InvocationCaptureHandle) Ready()

func (c *InvocationCaptureHandle) Release()

type InvocationLimits ¶ added in v0.6.0

type InvocationLimits struct{ Captures, Bodies int }

InvocationLimits bounds the total captures and execution leases of one admitted invocation. Both are totals, so neither depth nor fan-out can grow the state an invocation retains.

func DefaultInvocationLimits() InvocationLimits

type Meta ¶

type Meta = map[string]string

Meta is what a frame carries about a call rather than of it: a flat map of strings — a tenant, an idempotency key, a credential that is per request — which the profile carries verbatim and reads nothing into.

func MetaFrom(ctx context.Context) Meta

type Nullable ¶

type Nullable[T any] struct {
	Value T
	Null  bool
}

Nullable distinguishes JSON null from a non-null value. Use Optional[Nullable[T]] for an optional nullable field.

func NonNull[T any](value T) Nullable[T]

func Null[T any]() Nullable[T]

func (v Nullable[T]) MarshalJSON() ([]byte, error)

func (v *Nullable[T]) UnmarshalJSON(data []byte) error

type Observer ¶

type Observer interface{ Observe(event ObserverEvent) }

Observer is what a peer tells about the traffic it carries. It emits and never aggregates, and it chooses no backend: an observer sees names, ids, sizes, durations, outcomes and close codes — never a payload. A params object reaches no observer by any path, and diagnostic logging is one observer among others; the runtime writes to no logger of its own.

Observe is called on whichever goroutine the event happened on — the reader, a handler, a caller — and so from several at once: an observer that keeps anything keeps it under a lock of its own, and one that blocks holds up the connection it is watching. One that panics panics alone: the peer recovers it, loses that event and carries on, a diagnostic being no reason for a connection to end on a goroutine the consumer does not own.

type ObserverEvent ¶

type ObserverEvent interface{ ObserverEvent() }

ObserverEvent is one thing a peer did, or one thing a layer running over a peer did: it is implemented by the events of this package, by those of the tunnel and of the live layer, which reach an observer through the peer they run over, and by nothing else. A type switch is the consumer's dispatch, and a later profile or a later layer may add a case to it. It is not named Event because an Event of this package is one event of the profile, which an observer only ever hears about.

type Of ¶

type Of[T any] interface{ Of() T }

Of is what an entry point of a package generic in a family holds its type arguments to. Every record and enum a family's protocol package declares returns the package's Tag from Of, and an entry point that takes a parameter S drawn at several types constrains each to Of[STag]: they are then types of one family, or the call does not compile, whether the caller spells them or the compiler infers them from the handler. Go has no associated types; this is the pairing they would have given.

type Opaque ¶

type Opaque struct{}

Opaque is the tag of Raw: no family at all.

type Optional ¶

type Optional[T any] struct {
	Value   T
	Present bool
}

Optional distinguishes an absent member from a present value. Generated Go fields use the omitzero JSON option; a standalone absent value encodes as null.

func Some[T any](value T) Optional[T]

func (v Optional[T]) IsZero() bool

func (v Optional[T]) MarshalJSON() ([]byte, error)

func (v *Optional[T]) UnmarshalJSON(data []byte) error

type Options ¶

type Options struct {
	Handlers map[string]Handler
	Events   map[string]EventHandler
	// Prepare runs on the peer once it is built and before it reads its
	// first frame: what it installs — Handle, HandleEvent, a tunnel over the
	// peer — is there before anything can arrive, so the other side's first
	// request cannot be refused method_not_found by a peer whose handlers
	// are still on their way. Install in Prepare, use in OnConnect, which
	// runs on a peer that is already live. An error fails the construction:
	// the peer never runs and the constructor answers with it.
	Prepare               func(*Peer) error
	MaxConcurrentHandlers int
	// MaxPendingRequests bounds the calls this peer may have outstanding at
	// once; the one past it is refused busy without reaching the wire. It is
	// the caller's own bound, as MaxConcurrentHandlers is the receiver's.
	MaxPendingRequests int
	QueueCapacity      int
	MaxFrameBytes      int64
	RequestTimeout     time.Duration
	WriteTimeout       time.Duration
	Propagator         Propagator
	// Observer is told what the peer does with the traffic it carries; nil
	// observes nothing and costs nothing. Families labels a method or event
	// name with the family it belongs to, which the generated install fills:
	// an unlabelled name has no family, and the runtime parses none.
	Observer Observer
	Families map[string]string
}

Options limits are per connection. Zero values select the documented defaults. Handlers may run concurrently; event callbacks run serially in receive order.

type Outcome ¶

type Outcome int

Outcome is how a request ended.

const (
	// OutcomeOK is a request answered with a result.
	OutcomeOK Outcome = iota
	// OutcomeErrored is a request answered with an error.
	OutcomeErrored
	// OutcomeCancelled is a request the caller withdrew before it was answered.
	OutcomeCancelled
	// OutcomeTimedOut is a request that outlived its deadline.
	OutcomeTimedOut
)

func (o Outcome) String() string

type Peer ¶

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

Peer owns a frames duplex connection until Close or transport failure. Never send on or receive from the connection after handing it to NewPeer. The connection's receive limit is its maker's to set to MaxFrameBytes; the peer refuses a larger frame it is nonetheless handed.

func Accept(w http.ResponseWriter, r *http.Request, options ServerOptions) (*Peer, error)

func Dial(ctx context.Context, url string, options DialOptions) (*Peer, *http.Response, error)

func NewPeer(ctx context.Context, conn duplex.Conn, role Role, options Options) (*Peer, error)

func (p *Peer) Call(ctx context.Context, method string, params, result any) error

func (p *Peer) Close() error

func (p *Peer) Context() context.Context

func (p *Peer) Done() <-chan struct{}

func (p *Peer) Emit(ctx context.Context, event string, data any) error

func (p *Peer) Err() error

func (p *Peer) Handle(method string, handler Handler) error

func (p *Peer) HandleEvent(name string, handler EventHandler) error

func (p *Peer) MaxFrameBytes() int64

func (p *Peer) Observe(event ObserverEvent)

func (p *Peer) Observer() Observer

func (p *Peer) OnEvent(listener func(context.Context, Event)) func()

func (p *Peer) Role() Role

func (p *Peer) Subprotocol() string

func (p *Peer) Wire() duplex.Endpoint

type Propagator ¶

type Propagator interface {
	Extract(ctx context.Context, trace Trace) context.Context
	Inject(ctx context.Context) Trace
}

Propagator moves a trace between a context and a frame. Extract places an incoming frame's trace in the context its handler runs under; Inject says what an outgoing frame carries — a child of the trace the context holds, or a new trace where it holds none. Both members reach it verbatim, and a peer sends what it returns as it returns it.

var DefaultPropagator Propagator = w3cPropagator{}

type PublicError ¶

type PublicError struct {
	Code    string          `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

PublicError is safe to send to the remote caller. Other handler errors are replaced by a generic internal error; their messages are not disclosed.

func (e *PublicError) Error() string

type Raw ¶

type Raw []byte

Raw fills a slot with JSON passed through unexamined, which is what a relay wants: it carries the bytes and satisfies Of, so a generic package instantiated with it compiles, and validates nothing of what it carries.

func (r Raw) MarshalJSON() ([]byte, error)

func (Raw) Of() Opaque

func (r *Raw) UnmarshalJSON(data []byte) error

type RequestEnded ¶

type RequestEnded struct {
	At        time.Time
	ID        string
	Method    string
	Incoming  bool
	Duration  time.Duration
	Outcome   Outcome
	ErrorCode string
	Trace     Trace
	Family    string
}

RequestEnded pairs with every RequestStarted. Duration is the span between the two, and ErrorCode names the local cause: request_timeout for a deadline, cancelled for a cancellation, or the public error's code for a refusal. These codes hold for incoming and outgoing requests; success names no code.

func (RequestEnded) ObserverEvent()

type RequestStarted ¶

type RequestStarted struct {
	At       time.Time
	ID       string
	Method   string
	Incoming bool
	Trace    Trace
	Family   string
}

RequestStarted is a request beginning, whichever side raised it: Incoming is one this peer serves, and a request it refuses for want of a method or of a slot begins and ends like any other.

func (RequestStarted) ObserverEvent()

type Role ¶

type Role string

Role is the side of a connection a peer takes. It decides the prefix of the request ids the peer mints — c: for a client, s: for a server — so the two sides never mint the same id, and a tunnel over the peer chooses its channel ids by it.

const (
	// ClientRole dials and mints request ids under the c: prefix.
	ClientRole Role = "client"
	// ServerRole accepts and mints request ids under the s: prefix.
	ServerRole Role = "server"
)

type Schema ¶

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

Schema validates a family's descriptor: {"types": {...}, "parameters": [...]}. Its imports retain their own descriptors, so an application can fill type and family parameters without losing the caller's scope.

Expressions include primitives, named and imported types, family draws, arrays, maps, entity references, applications, literals, nullable values, inline shapes and the empty object. Records and adjacently tagged unions inherit their fields or variants. Field presence is separate from nullness.

Bind supplies parameters to raw validation. An explicitly applied argument is always validated. A generated Go generic codec may instead leave a family parameter unbound: the schema checks the enclosing shape and the instantiated Go codec checks that slot during marshal or unmarshal.

A refusal gives the location and the fact about it. Both runtimes read conformance/tables/validator.json, including the same refusal strings.

func MustSchema(wire string, digest string, imported map[string]*Schema) *Schema

func NewSchema(wire []byte, digest string, imported map[string]*Schema) (*Schema, error)

func (s *Schema) Bind(types map[string]any, families map[string]*Schema) *Schema

func (s *Schema) BoundDeclaration() (string, error)

func (s *Schema) DeclarationDigest() (string, error)

func (s *Schema) Fields(name string) []string

func (s *Schema) MustWithDeclaration(document string) *Schema

func (s *Schema) ValidateExpressionRaw(expression any, data []byte, at ...string) error

func (s *Schema) ValidateRaw(name string, data []byte, at ...string) error

func (s *Schema) ValidateValue(expression any, value any) error

func (s *Schema) WithDeclaration(document string) (*Schema, error)

type SelectedEndpoint ¶ added in v0.6.0

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

func (s *SelectedEndpoint) Close(code duplex.Code, reason string) error

func (s *SelectedEndpoint) Receive(receiver duplex.Receiver) (func(), error)

func (s *SelectedEndpoint) Select(path []string) *SelectedEndpoint

func (s *SelectedEndpoint) Send(path []string, message duplex.Message) error

type ServerOptions ¶

type ServerOptions struct {
	Options      Options
	Authenticate func(*http.Request) (context.Context, error)
	CheckOrigin  func(*http.Request) bool
	// OnConnect is called with a peer that is already live: it has read
	// frames and may have answered them. It is where a server uses the peer
	// — calls it, keeps it, waits on it. What a peer must serve is installed
	// in Options.Prepare, which runs before it reads anything; a handler
	// installed here can be too late for the other side's first request.
	OnConnect func(*Peer)
	// Subprotocols are what the server will select, in its own order of
	// preference, from what a client offers; empty selects none, which is
	// the default and what every consumer that sets nothing keeps. The
	// profile names itself here nowhere and refuses nothing on this ground
	// (docs/wire/profile.md).
	Subprotocols []string
	// SelectSubprotocol answers with the one subprotocol to select out of
	// what this request offered, "" for none. It is the selection, not a
	// filter over Subprotocols: a browser's ticket travels in the offer and
	// is accepted only if it is selected back unchanged, which no fixed
	// list can do. Nil selects the first offered that Subprotocols names.
	SelectSubprotocol func(r *http.Request, offered []string) string
}

ServerOptions requires an explicit authentication and origin policy. The authenticated context is the base context for every incoming invocation.

type Trace ¶

type Trace struct{ Parent, State string }

Trace is the W3C Trace Context a frame carries: the two members verbatim, neither of them read by the runtime beyond the form the decoder holds a traceparent to. The runtime imports no tracing library; one binds to it as a Propagator and nowhere else.

func TraceOf(ctx context.Context) (Trace, bool)

type TypeBinding ¶ added in v0.5.0

type TypeBinding struct {
	Schema *Schema
	Type   any
}

TypeBinding retains the schema where a supplied type expression belongs. Generated WireType methods return it so aliases, literals and constraints survive use as Go type arguments, including inside another family.

func TypeArgument[T any]() TypeBinding

func (b TypeBinding) Declaration() (string, error)

type UnpublishedError ¶ added in v0.5.0

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

UnpublishedError reports a local refusal before a frame entered the peer's outbound queue or a local implementation dispatched. Its underlying cause retains the ordinary public error or cancellation identity. A queued write failure or a remote response never supplies this proof, even if it has the same error code or message.

The proof belongs to this send attempt. A handler must not treat a nested call's refusal as proof that its own already-dispatched request was unsent.

func (e *UnpublishedError) Error() string

func (e *UnpublishedError) Unwrap() error

type ValueAdapter ¶ added in v0.6.0

type ValueAdapter[T any] struct {
	Binding      TypeBinding
	NeedsContext bool
	Export       func(context.Context, T) (json.RawMessage, error)
	Import       func(context.Context, json.RawMessage) (T, error)
}

ValueAdapter pairs a declaration with its two primitive conversions. A reusable adapter retains no operation context or lifetime. When NeedsContext is true, conversion runs inside the supplied ValueEnvironment's matching Export, Import or Publish boundary, using the active context it provides.

func JSONAdapter[T any]() ValueAdapter[T]

type ValueEnvironment ¶ added in v0.6.0

type ValueEnvironment interface {
	Select(context.Context) (context.Context, error)
	Child(context.Context) (context.Context, error)
	Export(context.Context, func(context.Context) (json.RawMessage, error)) (json.RawMessage, error)
	Import(context.Context, func(context.Context) error) error
	Publish(context.Context, func(context.Context) (json.RawMessage, error), func(json.RawMessage) (json.RawMessage, error)) (json.RawMessage, error)
}

ValueEnvironment supplies operation-local conversion effects. It belongs to the consumer's chosen component; the runtime never interprets its context. Select chooses an outgoing context, and Child derives an incoming lifetime. Build callbacks are synchronous and must pass their active context through every nested conversion. Publish completes the build before attempting send.

type WireCallOptions ¶ added in v0.6.0

type WireCallOptions struct {
	Propagator     Propagator
	RequestTimeout time.Duration
	Observer       Observer
	Family         string
}

WireCallOptions configures one model call, independently of its carrier. A zero RequestTimeout uses the runtime default; Propagator nil uses DefaultPropagator.

type WireEmitOptions ¶ added in v0.6.0

type WireEmitOptions struct {
	Propagator Propagator
	Observer   Observer
	Family     string
}

WireEmitOptions configures one model event emission, independently of its carrier.

type WireEventHandler ¶ added in v0.6.0

type WireEventHandler func(context.Context, json.RawMessage) error

WireEventHandler receives an event body beside its carried context.

type WireHandler ¶ added in v0.6.0

type WireHandler func(context.Context, json.RawMessage) (any, error)

WireHandler is a typed adapter's decoded request body, independent of the concrete carrier. The runtime supplies cancellation and response routing.

type WireHandlers ¶ added in v0.6.0

type WireHandlers struct {
	Request  WireHandler
	Event    WireEventHandler
	Observer Observer
	Family   string
}

WireHandlers groups a method and event that share one declared name.