casm

Documentation

Index

• Constants
• Variables
• func MatchLz4(id protocol.ID) bool
• func MatchPacked(id protocol.ID) bool
• func NewMatcher(ns string) protoutil.MatchFunc
• func Subprotocol(ns string, ss ...string) protocol.ID
• type BasicCap
  • func (c BasicCap) Protocols() []protocol.ID
  • func (c BasicCap) Upgrade(s Stream) rpc.Transport
• type Bootstrapper
• type Capability
• type ClientProvider
• type Future
  • func (f Future) Await(ctx context.Context) error
  • func (f Future) Err() error
• type HostFactory
  • func Client(opt ...libp2p.Option) HostFactory
  • func Server(opt ...libp2p.Option) HostFactory
• type Iterator
  • func (it Iterator[T]) Err() (err error)
  • func (it Iterator[T]) Next() (t T, ok bool)
• type Lz4Stream
  • func (s *Lz4Stream) Close() error
  • func (s *Lz4Stream) Protocol() protocol.ID
  • func (s *Lz4Stream) Read(b []byte) (int, error)
  • func (s *Lz4Stream) Write(b []byte) (int, error)
• type MetricReporter
• type Stream
• type Vat
  • func New(ns string, f HostFactory) (Vat, error)
  • func (v Vat) Connect(ctx context.Context, vat peer.AddrInfo, c Capability) (*rpc.Conn, error)
  • func (v Vat) Embargo(c Capability)
  • func (v Vat) Export(c Capability, boot ClientProvider)
  • func (v Vat) Loggable() map[string]interface{}

Constants

const (
	Version             = "0.0.0"
	Proto   protocol.ID = "/casm/" + Version
)

Variables

var ErrInvalidNS = errors.New("invalid namespace")

Functions

func MatchLz4

func MatchLz4(id protocol.ID) bool

MatchLz4 returns true if the supplied protocol.ID requires a Lz4 compressed Cap'n Proto transport.

func MatchPacked

func MatchPacked(id protocol.ID) bool

MatchPacked returns true if the supplied protocol.ID requires a packed Cap'n Proto transport.

func NewMatcher

func NewMatcher(ns string) protoutil.MatchFunc

NewMatcher returns a stream matcher for a protocol.ID that matches the pattern: /casm/<version>/<ns>

func Subprotocol

func Subprotocol(ns string, ss ...string) protocol.ID

Subprotocol returns a protocol.ID that matches the pattern: /casm/<version>/<ns>/<...>

Types

type BasicCap

type BasicCap []protocol.ID

BasicCap is a basic provider of Capability. Most implementations will benefit from using this. Protocol IDs SHOULD be ordered in descending order of preference, i.e.: lower-indexed protocol IDs will be used preferrentially.

BasicCap automatically parses and recognizes two suffixes:

- /packed :: causes Upgrade to use a packed Cap'n Proto encoding. - /lz4 :: causes Upgrade to use an LZ4 compressed stream.

The '/lz4' suffix may follow '/packed', i.e.: '/packed/lz4' is supported, whereas '/lz4/packed' is not.

func (BasicCap) Protocols

func (c BasicCap) Protocols() []protocol.ID

Lists all protocol IDs that match capability c, in order of precedence.

func (BasicCap) Upgrade

func (c BasicCap) Upgrade(s Stream) rpc.Transport

Upgrade a libp2p Stream to a capnp Transport.

type Bootstrapper

type Bootstrapper interface {
	Bootstrap() capnp.Client
}

Bootstrapper is an optional interface provided by Capability types, which provides a bootstrap interface. The capability returned by Bootstrap will be made available to the remote end of a Stream.

type Capability

type Capability interface {
	// Protocols returns the IDs for the given capability.
	// Implementations SHOULD order protocol identifiers in decreasing
	// order of priority.
	Protocols() []protocol.ID

	// Upgrade a raw byte-stream to an RPC transport.  Implementations
	// MAY select a Transport impmlementation based on the protocol ID
	// returned by 'Stream.Protocol'.
	Upgrade(Stream) rpc.Transport
}

type ClientProvider

type ClientProvider interface {
	// Client returns the client capability to be exported.  It is called
	// once for each incoming Stream, so implementations may either share
	// a single global object, or instantiate a new object for each call.
	Client() capnp.Client
}

type Future

type Future struct{ *capnp.Future }

func (Future) Await

func (f Future) Await(ctx context.Context) error

func (Future) Err

func (f Future) Err() error

type HostFactory

type HostFactory func() (host.Host, error)

HostFactory constructs a libp2p host.

func Client

func Client(opt ...libp2p.Option) HostFactory

Client returns a HostFactory for a client host. A client host has no listen address, and does not accept incoming connections. Options are passed through to the underlying call to libp2p.New.

func Server

func Server(opt ...libp2p.Option) HostFactory

Client returns a HostFactory for a server host. A server host has listen addresses and accepts incoming connections from the network. Options are passed through to the underlying call to libp2p.New.

type Iterator

type Iterator[T any] struct {
	Seq interface {
		Next() (T, bool)
	}

	Future interface {
		Done() <-chan struct{}
		Err() error
	}
}

func (Iterator[T]) Err

func (it Iterator[T]) Err() (err error)

Err returns returns the first error encountered while iterating over the stream. Callers SHOULD call Err() after the iterator has become exhausted, and handle any errors.

func (Iterator[T]) Next

func (it Iterator[T]) Next() (t T, ok bool)

type Lz4Stream

type Lz4Stream struct {
	Stream
	// contains filtered or unexported fields
}

func (*Lz4Stream) Close

func (s *Lz4Stream) Close() error

func (*Lz4Stream) Protocol

func (s *Lz4Stream) Protocol() protocol.ID

func (*Lz4Stream) Read

func (s *Lz4Stream) Read(b []byte) (int, error)

func (*Lz4Stream) Write

func (s *Lz4Stream) Write(b []byte) (int, error)

type MetricReporter

type MetricReporter interface {
	Incr(key string)
	Decr(key string)
}

MetricReporter is used to track open RPC connections.

type Stream

type Stream interface {
	Protocol() protocol.ID
	Read([]byte) (int, error)
	Write([]byte) (int, error)
	Close() error
}

Stream is a full-duplex byte-stream with reliable delivery semantics.

type Vat

type Vat struct {
	NS      string
	Host    host.Host
	Metrics MetricReporter
	Logger  log.Logger
}

Vat wraps a libp2p Host and provides a high-level interface to a capability-oriented network. Host has no private fields, and can be instantiated directly. The New() function is also provided as convenient way of populating the Host field.

func New

func New(ns string, f HostFactory) (Vat, error)

New is a convenience method that constructs a libp2p host and uses it to populate the Vat's Host field. Callers MUST NOT mutate any of the returned Vat's fields after calling its methods.

func (Vat) Connect

func (v Vat) Connect(ctx context.Context, vat peer.AddrInfo, c Capability) (*rpc.Conn, error)

Connect to a capability hostend on vat. The context is used only when negotiating network connections and is safe to cancel when a call to 'Connect' returns. The RPC connection is returned without waiting for the remote capability to resolve. Users MAY refer to the 'Bootstrap' method on 'rpc.Conn' to resolve the connection.

The 'Addrs' field of 'vat' MAY be empty, in which case the network will will attempt to discover a valid address.

If 'c' satisfies the 'Bootstrapper' interface, the client returned by 'c.Bootstrap()' is provided to the RPC connection as a bootstrap capability.

func (Vat) Embargo

func (v Vat) Embargo(c Capability)

Embargo ceases to export 'c'. New calls to 'Connect' are guaranteed to fail for 'c' after 'Embargo' returns. Existing RPC connections on 'c' are unaffected.

CAUTION: Embargo is asynchronous. The capability MAY NOT be disabled when Embargo() returns. This will be fixed in the future.

func (Vat) Export

func (v Vat) Export(c Capability, boot ClientProvider)

Export a capability, making it available to other vats in the network.

func (Vat) Loggable

func (v Vat) Loggable() map[string]interface{}