runtime

Documentation

Overview

Package runtime provides a high-level API for constructing Wetware clients and servers using dependency injection.

The runtime package is intended to be used with go.uber.org/fx. As such, it provides constructors for the fx.Option type, which can be consumed by fx.New to create a client or server node. Refer to the Fx documentation for information about how to consume fx.Options.

The runtime package exports three basic types:

1. runtime.Env is a configuration struct containing top-level types required by the runtime. These types are effectful, interacting with the host environment: loggers, metrics, contexts, configs, etc. The Options() method exports these types to Fx.

2. runtime.Config contains options for the libp2p, CASM and Wetware constructors required to build a node. These are passed to their constructors lazily, via the fx.Options returned by the Client() and Server() methods. The Options returned by either Client() or Server() MUST be passed to fx.New() along with those returned by runtime.Env.Options().

3. runtime.Option allows callers to pass options to libp2p, CASM or Wetware. These are initially staged in runtime.Config, whereupon they are passed into the fx.Options produced by the Client() and Server() methods.

The runtime API also exports two high-level constructors for building client and server nodes: NewClient() and NewServer(). Callers SHOULD prefer these over manual invocation of Env.Options(), Config.Client() and Config().Server(), as they apply sensible defaults and are easier to use overall. The lower-level API is provided for advanced users.

Index

• func NewClient(ctx context.Context, fs Flags, opt ...Option) fx.Option
• func NewServer(ctx context.Context, fs Flags, opt ...Option) fx.Option
• type Config
  • func (c Config) Client() fx.Option
  • func (c Config) ClientBootstrap() fx.Option
  • func (c *Config) PubSub() fx.Option
  • func (c Config) Routing() fx.Option
  • func (c Config) Server() fx.Option
  • func (c Config) ServerBootstrap() fx.Option
  • func (c Config) System() fx.Option
  • func (c Config) Vat() fx.Option
  • func (c Config) With(opt []Option) Config
• type Env
  • func (env Env) Options() fx.Option
• type Flags
• type HostConfig
• type Option
  • func HostOpt(opt ...libp2p.Option) Option
  • func WithHostConfig(f HostConfig) Option
  • func WithPeXDisabled() Option
  • func WithPeXOpt(opt ...pex.Option) Option

Functions

func NewClient

func NewClient(ctx context.Context, fs Flags, opt ...Option) fx.Option

NewClient returns Fx options for a client runtime. Options are passed directly to Client().

func NewServer

func NewServer(ctx context.Context, fs Flags, opt ...Option) fx.Option

NewClient returns Fx options for a server runtime. Options are passed directly to Server().

Types

type Config

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

Config is used to parametrize the Fx runtime. It contains a set of unexported type-constructors that are set by the Option type, and then provided to Fx. This allows callers to override defaults, while keeping interacton with Fx to a minimum.

func (Config) Client

func (c Config) Client() fx.Option

func (Config) ClientBootstrap

func (c Config) ClientBootstrap() fx.Option

func (*Config) PubSub

func (c *Config) PubSub() fx.Option

func (Config) Routing

func (c Config) Routing() fx.Option

func (Config) Server

func (c Config) Server() fx.Option

func (Config) ServerBootstrap

func (c Config) ServerBootstrap() fx.Option

func (Config) System

func (c Config) System() fx.Option

func (Config) Vat

func (c Config) Vat() fx.Option

func (Config) With

func (c Config) With(opt []Option) Config

With returns a new Config populated by the supplied options.

type Env

type Env struct {
	fx.In

	Ctx     context.Context `optional:"true"`
	Log     log.Logger      `optional:"true"`
	Metrics metrics.Client  `optional:"true"`
	Flags   Flags
}

Env is a context object that exposes environmental data and effectful operations to the runtime.

func (Env) Options

func (env Env) Options() fx.Option

Options for the Wetware runtime. These MUST be passed to the top-level call to fx.New, along with either options provided by either Config.Client() or Config.Server().

type Flags

type Flags interface {
	Bool(string) bool
	IsSet(string) bool
	Path(string) string
	String(string) string
	StringSlice(string) []string
	Duration(string) time.Duration
	Float64(string) float64
}

Flags are used to query configuration parameters.

type HostConfig

type HostConfig func(...libp2p.Option) casm.HostFactory

HostConfig specifies how to construct a libp2p Host, in a parametrizable way. Implementations MUST pass the options provided to libp2p.New. They MAY prepend default options.

type Option

type Option func(*Config)

Option can modify the state of Config. It is used to set type constructors that will be consumed by Fx.

func HostOpt

func HostOpt(opt ...libp2p.Option) Option

HostOpt declares a set of libp2p options to be passed into the HostConifg. If len(opt) == nil, no options are passed.

func WithHostConfig

func WithHostConfig(f HostConfig) Option

WithHostConfig sets the host configuration for the Fx app. Panics if f == nil.

func WithPeXDisabled

func WithPeXDisabled() Option

WithPeXDisabled disables PeX entirely.

func WithPeXOpt

func WithPeXOpt(opt ...pex.Option) Option

WithPeXOpt sets the options for the boot cache. The PeX cache is disabled by default. Calling without arguments uses the default configuration.