config

Documentation

Overview

Package config implements a generic configuration system that may be used to build YARPC Dispatchers from configurations specified in different markup formats.

Usage

To build a Dispatcher, set up a Configurator and inform it about the different transports that it needs to support. This object is re-usable and may be stored as a singleton in your application.

cfg := config.New()
cfg.MustRegisterTransport(http.TransportSpec())
cfg.MustRegisterTransport(redis.TransportSpec())

Use LoadConfigFromYAML to load a yarpc.Config from YAML and pass that to yarpc.NewDispatcher.

c, err := cfg.LoadConfigFromYAML(yamlConfig)
if err != nil {
	log.Fatal(err)
}
dispatcher := yarpc.NewDispatcher(c)

If you have already parsed your configuration from a different format, pass the parsed data to LoadConfig instead.

var m map[string]interface{} = ...
c, err := cfg.LoadConfig(m)
if err != nil {
	log.Fatal(err)
}
dispatcher := yarpc.NewDispatcher(c)

NewDispatcher or NewDispatcherFromYAML may be used to get a yarpc.Dispatcher directly instead of a yarpc.Config.

dispatcher, err := cfg.NewDispatcherFromYAML(yamlConfig)

Configuration parameters for the different transports, inbounds, and outbounds are defined in the TransportSpecs that were registered against the Configurator. A TransportSpec uses this information to build the corresponding Transport, Inbound and Outbound objects.

Configuration

The configuration may be specified in YAML or as any Go-level map[string]interface{}. The examples below use YAML for illustration purposes but other markup formats may be parsed into map[string]interface{} as long as the information provided is the same.

The configuration accepts the following top-level attributes: name, transports, inbounds, and outbounds.

name: myservice
inbounds:
  # ...
outbounds:
  # ...
transports:
  # ...

Where name specifies the name of the current service. See the following sections for details on the transports, inbounds, and outbounds keys in the configuration.

Inbound Configuration

The 'inbounds' attribute configures the different ways in which the service receives requests. It is represented as a mapping between inbound transport type and its configuration. For example, the following states that we want to receive requests over HTTP and Redis.

inbounds:
  redis:
    # ...
  http:
    # ...

(For details on the configuration parameters of individual transport types, check the documentation for the corresponding transport package.)

If you want multiple inbounds of the same type, specify a different name for it and add a 'type' attribute to its configuration:

inbounds:
  http:
    # ...
  http-deprecated:
    type: http
    # ...

Any inbound can be disabled by adding a 'disabled' attribute.

inbounds:
  http:
    # ...
  http-deprecated:
    type: http
    disabled: true
    # ...

Outbound Configuration

The 'outbounds' attribute configures how this service makes requests to other YARPC-compatible services. It is represented as mapping between service name and outbound configuration.

outbounds:
  keyvalue:
    # ..
  anotherservice:
    # ..

(For details on the configuration parameters of individual transport types, check the documentation for the corresponding transport package.)

The outbound configuration for a service has at least one of the following keys: unary, oneway. These specify the configurations for the corresponding RPC types for that service. For example, the following specifies that we make Unary requests to keyvalue service over HTTP and Oneway requests over Redis.

keyvalue:
  unary:
    http:
      # ...
  oneway:
    redis:
      # ...

For convenience, if there is only one outbound configuration for a service, it may be specified one level higher (without the 'unary' or 'oneway' attributes). In this case, all RPC types supported by that transport will be set. For example, the HTTP transport supports both, Unary and Oneway RPC types so the following states that requests for both RPC types must be made over HTTP.

keyvalue:
  http:
    # ...

Similarly, the following states that we only make Oneway requests to the "email" service and those are always made over Redis.

email:
  redis:
    # ...

When the name of the target service differs from the outbound name, it may be overridden with the 'service' key.

keyvalue:
  unary:
    # ...
  oneway:
    # ...
keyvalue-staging:
  service: keyvalue
  unary:
    # ...
  oneway:
    # ...

Transport Configuration

The 'transports' attribute configures the Transport objects that are shared between all inbounds and outbounds of that transport type. It is represented as a mapping between the transport name and its configuration.

transports:
  redis:
    # ...
  http:
    # ...

(For details on the configuration parameters of individual transport types, check the documentation for the corresponding transport package.)

Defining a Transport

To teach a Configurator about a Transport, register a TransportSpec against it.

cfg.RegisterTransport(TransportSpec{
	Name: "mytransport",
	BuildTransport: func(*myTransportConfig) (transport.Transport, error) {
		// ...
	},
	...
})

This transport will be configured under the 'mytransport' key in the parsed configuration data. See documentation for TransportSpec for details on what each field of TransportSpec means and how it behaves.

Index

• type Configurator
  • func New() *Configurator
  • func (c *Configurator) LoadConfig(data interface{}) (yarpc.Config, error)
  • func (c *Configurator) LoadConfigFromYAML(r io.Reader) (yarpc.Config, error)
  • func (c *Configurator) MustRegisterTransport(t TransportSpec)
  • func (c *Configurator) NewDispatcher(data interface{}) (*yarpc.Dispatcher, error)
  • func (c *Configurator) NewDispatcherFromYAML(r io.Reader) (*yarpc.Dispatcher, error)
  • func (c *Configurator) RegisterTransport(t TransportSpec) error
• type TransportSpec

Types

type Configurator

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

Configurator helps build Dispatchers using runtime configuration.

An empty Configurator does not know about any transports. Inform it about the different transports and their configuration parameters using the RegisterTransport function.

func New

func New() *Configurator

New sets up a new empty Configurator. The returned Configurator does not know about any transports. Individual TransportSpecs must be registered against it using the RegisterTransport function.

func (*Configurator) LoadConfig

func (c *Configurator) LoadConfig(data interface{}) (yarpc.Config, error)

LoadConfig loads a yarpc.Config from a map[string]interface{} or map[interface{}]interface{}.

See the module documentation for the shape the map[string]interface{} is expected to conform to.

func (*Configurator) LoadConfigFromYAML

func (c *Configurator) LoadConfigFromYAML(r io.Reader) (yarpc.Config, error)

LoadConfigFromYAML loads a yarpc.Config from YAML. Use LoadConfig if you have your own map[string]interface{} or map[interface{}]interface{} to provide.

func (*Configurator) MustRegisterTransport

func (c *Configurator) MustRegisterTransport(t TransportSpec)

MustRegisterTransport registers the given TransportSpec with the Configurator. This function panics if the TransportSpec was invalid.

func (*Configurator) NewDispatcher

func (c *Configurator) NewDispatcher(data interface{}) (*yarpc.Dispatcher, error)

NewDispatcher builds a new Dispatcher from the given configuration data.

func (*Configurator) NewDispatcherFromYAML

func (c *Configurator) NewDispatcherFromYAML(r io.Reader) (*yarpc.Dispatcher, error)

NewDispatcherFromYAML builds a Dispatcher from the given YAML configuration.

func (*Configurator) RegisterTransport

func (c *Configurator) RegisterTransport(t TransportSpec) error

RegisterTransport registers a TransportSpec with the given Configurator. An error is returned if the TransportSpec was invalid.

If a transport with the same name was already registered, it will be overwritten.

Use MustRegisterTransport if you want to panic in case of registration failure.

type TransportSpec

type TransportSpec struct {
	// Name of the transport
	Name string

	// A function in the shape,
	//
	// 	func(C) (transport.Transport, error)
	//
	// Where C is a struct or pointer to a struct defining the configuration
	// parameters accepted by this transport.
	//
	// This function will be called with the parsed configuration to build
	// Transport defined by this spec.
	BuildTransport interface{}

	// A function in the shape,
	//
	// 	func(C, transport.Transport) (transport.Inbound, error)
	//
	// Where C is a struct or pointer to a struct defining the configuration
	// parameters for the inbound.
	//
	// This may be nil if this transport does not support inbounds.
	//
	// This function will be called with the parsed configuration and the
	// transport built by BuildTransport to build the inbound for this
	// transport.
	BuildInbound interface{}

	// The following two are functions in the shapes,
	//
	// 	func(C, transport.Transport) (transport.UnaryOutbound, error)
	// 	func(C, transport.Transport) (transport.OnewayOutbound, error)
	//
	// Where C is a struct or pointer to a struct defining the configuration
	// parameters for outbounds of that RPC type.
	//
	// Either value may be nil to indicate that the transport does not support
	// unary or oneway outbounds.
	//
	// These functions will be called with the parsed configurations and the
	// transport built by BuildTransport to build the unary and oneway
	// outbounds for this transport.
	BuildUnaryOutbound  interface{}
	BuildOnewayOutbound interface{}
}

TransportSpec specifies the configuration parameters for a transport. These specifications are registered against a Configurator to teach it how to parse the configuration for that transport and build instances of it.

Every TransportSpec MUST have a BuildTransport function. BuildInbound, BuildUnaryOutbound, and BuildOnewayOutbound functions may be provided if the Transport supports that functoinality. For example, if a transport only supports incoming and outgoing Oneway requests, it will provide a BuildTransport, BuildInbound, and BuildOnewayOutbound function.

Besides BuildTransport which accepts just its configuration struct, each function mentioned above has the shape,

func(C, transport.Transport) (X, error)

Where C is a struct defining the configuration parameters of that entity and X is the result type. For example,

func(HttpOutboundConfig, transport.Transport) (transport.UnaryOutbound, error)

Is a function to build an HTTP unary outbound from its outbound configuration and the corresponding transport.

The Configurator will decode and fill the requested struct type from the input configuration. For example, given,

type HttpOutboundConfig struct {
	URL string
}

Configurator expects the outbound configuration for HTTP to have a 'url' field. In YAML, the following,

outbounds:
  myservice:
    http:
      url: http://localhost:8080

Will be decoded into,

HttpOutboundConfig{URL: "http://localhost:8080"}

A case-insensitive match is performed to map fields from configuration data to structs.

Configuration structs can use standard Go primitive types, time.Duration, maps, slices, and other similar structs. For example,

type Peer struct {
	Host string
	Port int
}

type MyOutboundConfig struct{ Peers []Peer }

Will expect the following YAML.

myoutbound:
  peers:
	- host: localhost
	  port: 8080
	- host: anotherhost
	  port: 8080

If a field name differs from the name of the field inside the configuration data, a `config` tag may be added to the struct to specify a different name.

type MyInboundConfig struct {
	Address string `config:"addr"`
}

The configuration for this struct will be in the shape,

myinbound:
  addr: foo