cfgclient

Documentation

Overview

Package cfgclient contains service implementations for the LUCI configuration service defined in github.com/luci/luci-go/common/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 cachable 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 retuned 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) cfgtypes.ConfigSet
• func CurrentServiceName(c context.Context) string
• func Get(c context.Context, a Authority, cs cfgtypes.ConfigSet, path string, r Resolver, ...) error
• func GetConfigSetURL(c context.Context, a Authority, cs cfgtypes.ConfigSet) (url.URL, error)
• func Projects(c context.Context, a Authority, path string, r MultiResolver, meta *[]*Meta) error
• func Refs(c context.Context, a Authority, path string, r MultiResolver, meta *[]*Meta) error
• func ServiceURL(c context.Context) url.URL
• type Authority
• type FormattingResolver
• type Meta
• 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)
)

var ErrNoConfig = config.ErrNoConfig

ErrNoConfig is a sentinel error returned by Get when the requested configuration is not found.

This is an alias of github.com/luci/luci-go/common/config.ErrNoConfig for backward compatibility.

Functions

func CurrentServiceConfigSet

func CurrentServiceConfigSet(c context.Context) cfgtypes.ConfigSet

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 cfgtypes.ConfigSet, path string, r Resolver, meta *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 GetConfigSetURL

func GetConfigSetURL(c context.Context, a Authority, cs cfgtypes.ConfigSet) (url.URL, error)

GetConfigSetURL returns the URL where the specified ConfigSet is configured. If the config set doesn't exist, ErrNoConfig will be returned.

func Projects

func Projects(c context.Context, a Authority, path string, r MultiResolver, meta *[]*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 *[]*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() backend.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 Meta

type Meta struct {
	// ConfigSet is the item's config set.
	ConfigSet cfgtypes.ConfigSet
	// Path is the item's path within its config set.
	Path string

	// ContentHash is the content hash.
	ContentHash string
	// Revision is the revision string.
	Revision string
}

Meta is metadata about a single configuration file.

This differs from backend.Meta in that it uses the ConfigSet type for the ConfigSet field.

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 *backend.Item) 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 *backend.Item) 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.