rpc

Documentation

Overview

Package rpc implements the Cap'n Proto RPC protocol.

Index

• Variables
• func ListenAndServe(ctx context.Context, network, addr string, bootstrapClient capnp.Client) error
• func Serve(lis net.Listener, boot capnp.Client) error
• type Codec
• type Conn
  • func NewConn(t Transport, opts *Options) *Conn
  • func (c *Conn) Bootstrap(ctx context.Context) (bc capnp.Client)
  • func (c *Conn) Close() error
  • func (c *Conn) Done() <-chan struct{}
• type ErrorReporter
• type Options
• type Transport
  • func NewPackedStreamTransport(rwc io.ReadWriteCloser) Transport
  • func NewStreamTransport(rwc io.ReadWriteCloser) Transport
  • func NewTransport(codec Codec) Transport

Variables

var (

	// Base errors
	ErrConnClosed        = errors.New("connection closed")
	ErrNotACapability    = errors.New("not a capability")
	ErrCapTablePopulated = errors.New("capability table already populated")

	// RPC exceptions
	ExcClosed = rpcerr.Disconnected(ErrConnClosed)
)

Functions

func ListenAndServe

func ListenAndServe(ctx context.Context, network, addr string, bootstrapClient capnp.Client) error

ListenAndServe opens a listener on the given address and serves a Cap'n Proto RPC to incoming connections

network and address are passed to net.Listen. Use network "unix" for Unix Domain Sockets and "tcp" for regular TCP IP4 or IP6 connections.

ListenAndServe will take ownership of bootstrapClient and release it on exit.

func Serve

func Serve(lis net.Listener, boot capnp.Client) error

Serve serves a Cap'n Proto RPC to incoming connections.

Serve will take ownership of bootstrapClient and release it after the listener closes.

Serve exits with the listener error if the listener is closed by the owner.

Types

type Codec

type Codec = transport.Codec

type Conn

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

A Conn is a connection to another Cap'n Proto vat. It is safe to use from multiple goroutines.

func NewConn

func NewConn(t Transport, opts *Options) *Conn

NewConn creates a new connection that communicates on a given transport.

Closing the connection will close the transport and release the bootstrap client provided in opts.

If opts == nil, sensible defaults are used. See Options for more info.

Once a connection is created, it will immediately start receiving requests from the transport.

func (*Conn) Bootstrap

func (c *Conn) Bootstrap(ctx context.Context) (bc capnp.Client)

Bootstrap returns the remote vat's bootstrap interface. This creates a new client that the caller is responsible for releasing.

func (*Conn) Close

func (c *Conn) Close() error

Close sends an abort to the remote vat and closes the underlying transport.

func (*Conn) Done

func (c *Conn) Done() <-chan struct{}

Done returns a channel that is closed after the connection is shut down.

type ErrorReporter

type ErrorReporter interface {
	ReportError(error)
}

ErrorReporter can receive errors from a Conn. ReportError should be quick to return and should not use the Conn that it is attached to.

type Options

type Options struct {
	// BootstrapClient is the capability that will be returned to the
	// remote peer when receiving a Bootstrap message.  NewConn "steals"
	// this reference: it will release the client when the connection is
	// closed.
	BootstrapClient capnp.Client

	// ErrorReporter will be called upon when errors occur while the Conn
	// is receiving messages from the remote vat.
	ErrorReporter ErrorReporter

	// AbortTimeout specifies how long to block on sending an abort message
	// before closing the transport.  If zero, then a reasonably short
	// timeout is used.
	AbortTimeout time.Duration
}

Options specifies optional parameters for creating a Conn.

type Transport

type Transport = transport.Transport

func NewPackedStreamTransport

func NewPackedStreamTransport(rwc io.ReadWriteCloser) Transport

NewPackedStreamTransport is an alias for as transport.NewPackedStream

func NewStreamTransport

func NewStreamTransport(rwc io.ReadWriteCloser) Transport

NewStreamTransport is an alias for as transport.NewStream

func NewTransport

func NewTransport(codec Codec) Transport

NewTransport is an alias for as transport.New