transport

Documentation

Overview

Package transport defines an interface for sending and receiving rpc messages.

In addition to the implementations defined here, one of the developers maintains a websocket-backed implementation as a separate module:

https://pkg.go.dev/zenhack.net/go/websocket-capnp

Index

• type Codec
  • func NewPipe(bufSz int) (c1, c2 Codec)
• type IncomingMessage
• type OutgoingMessage
• type Transport
  • func New(c Codec) Transport
  • func NewPackedStream(rwc io.ReadWriteCloser) Transport
  • func NewStream(rwc io.ReadWriteCloser) Transport

Types

type Codec

type Codec interface {
	Encode(*capnp.Message) error
	Decode() (*capnp.Message, error)
	Close() error
}

A Codec is responsible for encoding and decoding messages from a single logical stream.

func NewPipe

func NewPipe(bufSz int) (c1, c2 Codec)

NewPipe returns a pair of codecs which communicate over channels, copying messages at the channel boundary. bufSz is the size of the channel buffers.

type IncomingMessage

type IncomingMessage interface {
	Message() rpccp.Message
	Release()
}

IncomingMessage is a message that has arrived over a transport. Release() MUST be called when the IncomingMessage is no longer in use.

Implementations SHOULD release the underlying *capnp.Message when the Release() method is called. Release() MUST be idempotent.

type OutgoingMessage

type OutgoingMessage interface {
	Send() error
	Message() rpccp.Message
	Release()
}

OutgoingMessage is a message that can be sent at a later time. Release() MUST be called when the OutgoingMessage is no longer in use. Before releasing an ougoing message, Send() MAY be called at most once to send the message over the transport that produced it.

Implementations SHOULD release the underlying *capnp.Message when the Release() method is called.

Release() MUST be idempotent, and calls to Send() after a call to Release MUST panic.

type Transport

type Transport interface {
	// NewMessage allocates a new message to be sent over the transport.
	// The caller must call OutgoingMessage.Release() when it no longer
	// needs to reference the message. Calling Release() more than once
	// has no effect.  Before releasing the message, Send() MAY be called
	// at most once to send the mssage.
	//
	// When Release() is called, the underlying *capnp.Message SHOULD be
	// released.  This will also release any clients in the CapTable and
	// release its Arena.
	//
	// The Arena in the returned message should be fast at allocating new
	// segments.  The returned ReleaseFunc MUST be safe to call concurrently
	// with subsequent calls to NewMessage.
	NewMessage() (OutgoingMessage, error)

	// RecvMessage receives the next message sent from the remote vat.
	// The returned message is only valid until the release method is
	// called.  The IncomingMessage.Release() method may be called
	// concurrently with RecvMessage or with any other release function
	// returned by RecvMessage.
	//
	// When Release() is called, the underlying *capnp.Message SHOULD be
	// released.  This will also release any clients in the CapTable and
	// release its Arena.
	//
	// The Arena in the returned message should not fetch segments lazily;
	// the Arena should be fast to access other segments.
	RecvMessage() (IncomingMessage, error)

	// Close releases any resources associated with the transport. If there
	// are any outstanding calls to NewMessage, a returned send function,
	// or RecvMessage, they will be interrupted and return errors.
	Close() error
}

A Transport sends and receives Cap'n Proto RPC messages to and from another vat.

It is safe to call NewMessage and its returned functions concurrently with RecvMessage.

func New

func New(c Codec) Transport

New creates a new transport that uses the supplied codec to read and write messages across the wire.

func NewPackedStream

func NewPackedStream(rwc io.ReadWriteCloser) Transport

NewPackedStream creates a new transport that uses a packed encoding.

See: NewStream.

func NewStream

func NewStream(rwc io.ReadWriteCloser) Transport

NewStream creates a new transport that reads and writes to rwc. Closing the transport will close rwc.

rwc's Close method must interrupt any outstanding IO, and it must be safe to call rwc.Read and rwc.Write concurrently.