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{}
  • func (c *Conn) RemotePeerID() PeerID
• type IntroductionInfo
• type Logger
• type Network
• type Options
• type PeerID
• type ProvisionID
• type RecipientID
• type ThirdPartyCapID
• 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.

func (*Conn) RemotePeerID

func (c *Conn) RemotePeerID() PeerID

Return the peer ID for the remote side of the connection. Returns the zero value if this connection was set up with NewConn instead of via a Network.

type IntroductionInfo

type IntroductionInfo struct {
	SendToRecipient ThirdPartyCapID
	SendToProvider  RecipientID
}

Data needed to perform a third-party handoff, returned by Newtork.Introduce.

type Logger

type Logger interface {
	Debug(message string, args ...any)
	Info(message string, args ...any)
	Warn(message string, args ...any)
	Error(message string, args ...any)
}

Logger is used for logging by the RPC system. Each method logs messages at a different level, but otherwise has the same semantics:

• Message is a human-readable description of the log event.
• Args is a sequenece of key, value pairs, where the keys must be strings and the values may be any type.
• The methods may not block for long periods of time.

This interface is designed such that it is satisfied by *slog.Logger.

type Network

type Network interface {
	// Return the identifier for caller on this network.
	LocalID() PeerID

	// Connect to another peer by ID. The supplied Options are used
	// for the connection, with the values for RemotePeerID and Network
	// overridden by the Network.
	Dial(PeerID, *Options) (*Conn, error)

	// Accept the next incoming connection on the network, using the
	// supplied Options for the connection. Generally, callers will
	// want to invoke this in a loop when launching a server.
	Accept(context.Context, *Options) (*Conn, error)

	// Introduce the two connections, in preparation for a third party
	// handoff. Afterwards, a Provide messsage should be sent to
	// provider, and a ThirdPartyCapId should be sent to recipient.
	Introduce(provider, recipient *Conn) (IntroductionInfo, error)

	// Given a ThirdPartyCapID, received from introducedBy, connect
	// to the third party. The caller should then send an Accept
	// message over the returned Connection.
	DialIntroduced(capID ThirdPartyCapID, introducedBy *Conn) (*Conn, ProvisionID, error)

	// Given a RecipientID received in a Provide message via
	// introducedBy, wait for the recipient to connect, and
	// return the connection formed. If there is already an
	// established connection to the relevant Peer, this
	// SHOULD return the existing connection immediately.
	AcceptIntroduced(recipientID RecipientID, introducedBy *Conn) (*Conn, error)
}

A Network is a reference to a multi-party (generally >= 3) network of Cap'n Proto peers. Use this instead of NewConn when establishing connections outside a point-to-point setting.

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

	// Logger is used for logging by the RPC system, including errors that
	// occur while the Conn is receiving messages from the remote vat.
	Logger Logger

	// 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

	// RemotePeerID is the PeerID of the remote side of the connection. Can
	// be left as the zero value for point to point connections. For >= 3
	// party use, this should be filled in by the Network on Accept or Dial.
	// Application code should not set this.
	RemotePeerID PeerID

	// A reference to the Network that this connection is a part of.  Can be
	// left nil for point to point connections. Otherwise, this must be set
	// by Dial or Accept on the Network itself; application code should not
	// set this.
	Network Network
}

Options specifies optional parameters for creating a Conn.

type PeerID

type PeerID struct {
	// Network specific value identifying the peer.
	Value any
}

A PeerID identifies a peer on a Cap'n Proto network. The exact format of this is network specific.

type ProvisionID

type ProvisionID capnp.Ptr

The information that must be sent in an `Accept` message to identify the object being accepted.

In a network where each vat has a public/private key pair, this could simply be the public key fingerprint of the provider vat along with a nonce matching the one in the `RecipientId` used in the `Provide` message sent from that provider.

type RecipientID

type RecipientID capnp.Ptr

The information that must be sent in a `Provide` message to identify the recipient of the capability.

In a network where each vat has a public/private key pair, this could simply be the public key fingerprint of the recipient along with a nonce matching the one in the `ProvisionId`.

As another example, when communicating between processes on the same machine over Unix sockets, RecipientId could simply refer to a file descriptor attached to the message via SCM_RIGHTS. This file descriptor would be one end of a newly-created socketpair, with the other end having been sent to the capability's recipient in ThirdPartyCapId.

type ThirdPartyCapID

type ThirdPartyCapID capnp.Ptr

The information needed to connect to a third party and accept a capability from it.

In a network where each vat has a public/private key pair, this could be a combination of the third party's public key fingerprint, hints on how to connect to the third party (e.g. an IP address), and the nonce used in the corresponding `Provide` message's `RecipientId` as sent to that third party (used to identify which capability to pick up).

As another example, when communicating between processes on the same machine over Unix sockets, ThirdPartyCapId could simply refer to a file descriptor attached to the message via SCM_RIGHTS. This file descriptor would be one end of a newly-created socketpair, with the other end having been sent to the process hosting the capability in RecipientId.

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