cfgclient

Documentation

Overview

Package cfgclient contains service implementations for the LUCI configuration service defined in go.chromium.org/luci/config.

This defines an interface to the LUCI configuration service properties and files. The interface is designed to be used by services which handle user data, and has the ability to operate on behalf of authorities, either the service itself (privileged), on behalf of the user (delegation), or anonymously.

This package also offers the concept of resolution, where a configuration value is transformed into a more versatile application format prior to being cached and/or returned. Resolution allows configuration data consumers to handle configuration data as native Go types instead of raw configuration service data.

Configuration requests pass through the following layers:

1. A Backend, which is the configured configuration authority.
2. Cache resolution, which optionally transforms the data into an application-specific cacheable format.
3. A cache layer, which caches the data.
4. Value resolution, which transforms the cached data format from (2) into a Go value.
5. The Go value is returned to the user.

Layers (2) and (4) are managed by the Resolver type, which is associated by the application with the underlying configuration data.

Index

• Constants
• Variables
• func CurrentServiceConfigSet(c context.Context) config.Set
• func CurrentServiceName(c context.Context) string
• func Get(c context.Context, a Authority, cs config.Set, path string, r Resolver, ...) error
• func Projects(c context.Context, a Authority, path string, r MultiResolver, ...) error
• func Refs(c context.Context, a Authority, path string, r MultiResolver, ...) error
• func ServiceURL(c context.Context) url.URL
• type Authority
• type FormattingResolver
• type MultiResolver
  • func BytesSlice(out *[][]byte) MultiResolver
  • func StringSlice(out *[]string) MultiResolver
• type Resolver
  • func Bytes(out *[]byte) Resolver
  • func String(out *string) Resolver

Constants

const ProjectConfigPath = "project.cfg"

ProjectConfigPath is the path of a project's project-wide configuration file.

Variables

var (
	// AsAnonymous requests config data as an anonymous user.
	//
	// Corresponds to auth.NoAuth.
	AsAnonymous = Authority(backend.AsAnonymous)

	// AsService requests config data as the currently-running service.
	//
	// Corresponds to auth.AsSelf.
	AsService = Authority(backend.AsService)

	// AsUser requests config data as the currently logged-in user.
	//
	// Corresponds to auth.AsUser.
	AsUser = Authority(backend.AsUser)
)

Functions

func CurrentServiceConfigSet

func CurrentServiceConfigSet(c context.Context) config.Set

CurrentServiceConfigSet returns the config set for the current AppEngine service, based on its current service name.

func CurrentServiceName

func CurrentServiceName(c context.Context) string

CurrentServiceName returns the current service name, as used to identify it in configurations. This is based on the current App ID.

func Get

func Get(c context.Context, a Authority, cs config.Set, path string, r Resolver, meta *config.Meta) error

Get retrieves a single configuration file.

r, if not nil, is a Resolver that will load the configuration data. If nil, the configuration data will be discarded (useful if you only care about metas).

meta, if not nil, will have the configuration's Meta loaded into it on success.

func Projects

func Projects(c context.Context, a Authority, path string, r MultiResolver, meta *[]*config.Meta) error

Projects retrieves all named project configurations.

r, if not nil, is a MultiResolver that will load the configuration data. If nil, the configuration data will be discarded (useful if you only care about metas). If the MultiResolver operates on a slice (which it probably will), each meta and/or error index will correspond to its slice index.

If meta is not nil, it will be populated with a slice of *Meta entries for each loaded configuration, in the same order that r receives them. If r resolves to a slice, the indexes for each resolved slice entry and meta entry should align unless r is doing something funky.

Two types of failure may happen here. A systemic failure fails to load the set of project configurations. This will be returned directly.

A resolver failure happens when the configuratiokns load, but could not be resolved. In this case, any successful resolutions and "meta" will be populated and an errors.MultiError will be returned containing non-nil errors at indices whose configs failed to resolve.

func Refs

func Refs(c context.Context, a Authority, path string, r MultiResolver, meta *[]*config.Meta) error

Refs retrieves all named ref configurations.

See Projects for individual argument descriptions.

func ServiceURL

func ServiceURL(c context.Context) url.URL

ServiceURL returns the URL of the config service.

Types

type Authority

type Authority backend.Authority

Authority is the authority on whose behalf a request is operating.

type FormattingResolver

type FormattingResolver interface {
	// Format returns the FormatterRegistry key and associated data for this
	// Resolver.
	//
	// An empty format represents no Formatter, meaning that this Resolver only
	// supports the raw config service result.
	Format() config.FormatSpec
}

FormattingResolver is a Resolver that changes the format of its contents. If a Resolver does this, it self-describes the new format so that it can be associated with the format later.

type MultiResolver

type MultiResolver interface {
	// PrepareMulti indicates that items are about to be loaded, as well as the
	// number of resolved values. The MultiResolver should allocate and export its
	// output value.
	//
	// The value's contents will be populated in a series of successive
	// ResolveItemAt calls for indexes between zero and (size-1).
	PrepareMulti(size int)

	// ResolveItemAt resolves an individual item at the specified index.
	// PrepareMulti with a size greater than i must be called prior to using
	// ResolveItemAt.
	ResolveItemAt(i int, it *config.Config) error
}

MultiResolver resolves a slice of Item.

If it resolves into a slice (which it should), it must preserve Item ordering such that resolved Item "n" appears in the slice at index "n".

Any individual resolution failures should be

func BytesSlice

func BytesSlice(out *[][]byte) MultiResolver

BytesSlice is a MultiResolver that resolves condig data into a slice of byte slices.

func StringSlice

func StringSlice(out *[]string) MultiResolver

StringSlice is a MultiResolver that resolves config data into a slice of strings.

type Resolver

type Resolver interface {
	// Resolve resolves a single Item.
	Resolve(it *config.Config) error
}

Resolver resolves configuration data into a native type.

func Bytes

func Bytes(out *[]byte) Resolver

Bytes is a Resolver that resolves config data into a byte slice.

func String

func String(out *string) Resolver

String is a Resolver that resolves config data into a string.