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

    Constants

    This section is empty.

    Variables

    This section is empty.

    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(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 ClientFactory 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
                        
                        	// ClientFactory initializes an authenticating HTTP client on demand.
                        	//
                        	// It will be used to call LUCI Config service. Must be set if ServiceHost is
                        	// set, ignored otherwise.
                        	ClientFactory func(context.Context) (*http.Client, error)
                        }

                          Options describe how to configure a LUCI Config client.