cfgclient

Documentation

Overview

Package cfgclient contains glue code to use config.Interface client.

It wraps various config.Interface implementations behind a single API, implements context.Context integration and provides few high-level helper methods to simplify common tasks such as fetching and deserializing individual config files.

Index

• func Client(ctx context.Context) config.Interface
• func Get(ctx context.Context, cs config.Set, path string, dest Destination, ...) error
• func New(ctx context.Context, opts Options) (config.Interface, error)
• func ProjectsWithConfig(ctx context.Context, path string) ([]string, error)
• func Use(ctx context.Context, client config.Interface) context.Context
• type Destination
  • func Bytes(out *[]byte) Destination
  • func ProtoJSON(msg proto.Message) Destination
  • func ProtoText(msg proto.Message) Destination
  • func String(out *string) Destination
• type Options

Functions

func Client

func Client(ctx context.Context) config.Interface

Client returns a client to access the LUCI Config service.

If there's no client in the context, returns a client that fails all calls with an error.

func Get

func Get(ctx context.Context, cs config.Set, path string, dest Destination, meta *config.Meta) error

Get fetches and optionally deserializes a single config file.

It is a convenience wrapper over Client(ctx).GetConfig(...). If you need something more advanced, use the client directly.

If `dest` is given, it is used to deserialize and store the fetched config. If it is nil, the config body is ignored (but its metadata is still fetched).

If `meta` is given, it receives the metadata about the config.

Returns an error if the config can't be fetched or deserialized.

func New

func New(ctx context.Context, opts Options) (config.Interface, error)

New instantiates a LUCI Config client based on the given options.

The client fetches configs either from a LUCI Config service or from a local directory on disk (e.g. when running locally in development mode), depending on values of ServiceHost and ConfigsDir. If neither are set, returns a client that fails all calls with an error.

func ProjectsWithConfig

func ProjectsWithConfig(ctx context.Context, path string) ([]string, error)

ProjectsWithConfig returns a list of LUCI projects that have the given configuration file.

It is a convenience wrapper over Client(ctx).GetProjectConfigs(...). If you need something more advanced, use the client directly.

func Use

func Use(ctx context.Context, client config.Interface) context.Context

Use installs a client implementation into the context.

Primarily used by the framework code to setup an appropriate implementation. Can be used in unit tests to install a testing implementation.

Do not call it yourself outside of unit tests.

Types

type Destination

type Destination func(string) error

Destination receives a raw config file body, deserializes and stores it.

See Get(...).

func Bytes

func Bytes(out *[]byte) Destination

Bytes can be used to put the received config body into a byte slice.

func ProtoJSON

func ProtoJSON(msg proto.Message) Destination

ProtoJSON can be used to deserialize the received config body as a JSONPB message.

func ProtoText

func ProtoText(msg proto.Message) Destination

ProtoText can be used to deserialize the received config body as a text proto message.

func String

func String(out *string) Destination

String can be used to put the received config body into a string.

type Options

type Options struct {
	// Vars define how to substitute ${var} placeholders in config sets and paths.
	//
	// If nil, vars are not allowed. Pass &vars.Vars explicitly to use the global
	// var set.
	Vars *vars.VarSet

	// ServiceHost is a hostname of a LUCI Config service to use.
	//
	// If given, indicates configs should be fetched from the LUCI Config service.
	// Requires PerRPCCredentials to be provided as well.
	//
	// Not compatible with ConfigsDir.
	ServiceHost string

	// ConfigsDir is a file system directory to fetch configs from instead of
	// a LUCI Config service.
	//
	// See https://godoc.org/go.chromium.org/luci/config/impl/filesystem for the
	// expected layout of this directory.
	//
	// Useful when running locally in development mode. Not compatible with
	// ServiceHost.
	ConfigsDir string

	// PerRPCCredentials to use to authenticate gRPC requests.
	//
	// Must be set if ServiceHost is set, ignored otherwise.
	PerRPCCredentials credentials.PerRPCCredentials

	// UserAgent is the optional additional User-Agent fragment which will be
	// appended to gRPC calls.
	UserAgent string
}

Options describe how to configure a LUCI Config client.