cfgcache

Documentation

Overview

Package cfgcache provides a datastore-based cache of individual config files.

It is intended to be used to cache a small number (usually 1) service configuration files fetched from the service's config set and used in every request.

Configuration files are assumed to be stored in text protobuf encoding.

Index

• type Entry
  • func Register(e *Entry) *Entry
  • func (e *Entry) Fetch(ctx context.Context, meta *config.Meta) (proto.Message, error)
  • func (e *Entry) Get(ctx context.Context, meta *config.Meta) (proto.Message, error)
  • func (e *Entry) Set(ctx context.Context, cfg proto.Message, meta *config.Meta) error
  • func (e *Entry) Update(ctx context.Context, meta *config.Meta) (proto.Message, error)

Types

type Entry

type Entry struct {
	// Path is a path within the service config set to fetch.
	Path string

	// ConfigSet allows to provider custom config set.
	//
	// If empty, defaults to this service's config set.
	ConfigSet string

	// Type identifies proto message type with the config file schema.
	//
	// The actual value will never be used, only its type. All methods will
	// return proto.Message of the exact same type.
	Type proto.Message

	// Validator is called to validate the config correctness.
	//
	// If nil, Update will just validate the config file matches the protobuf
	// message kind identified by Type.
	//
	// If not nil, the Validator will be called with a deserialized message to
	// continue its validation.
	//
	// See go.chromium.org/luci/config/validation for more details.
	Validator func(c *validation.Context, msg proto.Message) error

	// Rules is a config validation ruleset to register the validator in.
	//
	// If nil, the default validation.Rules will be used. This is usually what you
	// want outside of unit tests.
	Rules *validation.RuleSet
	// contains filtered or unexported fields
}

Entry describes what service configuration file to fetch and how to deserialize and validate it.

Must be defined as a global variable and registered via Register(...) to enable the process cache and the config validation hook.

You **must** setup periodical calls to Update to use Get or Fetch. They will be returning stale data if Update is not called periodically.

func Register

func Register(e *Entry) *Entry

Register registers the process cache slot and the validation hook.

Must be called during the init time i.e. when initializing a global variable or in a package init() function. Get() will panic if used with an unregistered entry.

Panics if called twice. Returns `e` itself.

func (*Entry) Fetch

func (e *Entry) Fetch(ctx context.Context, meta *config.Meta) (proto.Message, error)

Fetch fetches the config from the datastore cache.

Note: you **must** setup periodical calls to Update to use Get or Fetch. They will be returning stale data if Update is not called periodically.

Strongly consistent with Update: calling Fetch right after Update will always return the most recent config.

Prefer to use Get if possible.

To simplify deploying code that uses new configs, Fetch will call Update itself if it notices there's no cached config in the datastore. To avoid overloading LUCI Config, it will do it under the lock and exactly once. If this attempt fails, for whatever reason, it will not be retried. Callers of Fetch will have to wait until the cache is explicitly updated by Update. If you can't risk this situation, deploy code that calls Update before deploying code that uses Get or Fetch.

If `meta` is non-nil, it will receive the config metadata.

func (*Entry) Get

func (e *Entry) Get(ctx context.Context, meta *config.Meta) (proto.Message, error)

Get returns the cached config.

Note: you **must** setup periodical calls to Update to use Get or Fetch. They will be returning stale data if Update is not called periodically.

Uses in-memory cache to avoid hitting datastore all the time. As a result it may keep returning a stale config up to 1 min after the Update call. Uses Fetch to fetch the config if the in-memory cache is stale, see Fetch doc to learn its caveats, they apply to Get as well.

If there's no in-memory cache available in the context, falls back to Fetch. This happens in tests that don't call caching.WithEmptyProcessCache to setup the cache.

Panics if the entry wasn't registered in the process cache via Register.

If `meta` is non-nil, it will receive the config metadata.

func (*Entry) Set

func (e *Entry) Set(ctx context.Context, cfg proto.Message, meta *config.Meta) error

Set overrides the cached config in the datastore.

Primarily intended for tests to mock the cached config in the datastore.

func (*Entry) Update

func (e *Entry) Update(ctx context.Context, meta *config.Meta) (proto.Message, error)

Update fetches the freshest config and caches it in the datastore.

**Must** be called periodically and asynchronously (e.g. from a GAE cron job) to keep the cache fresh. Get and Fetch will return stale data if Update isn't called periodically.

This is a slow operation. Do not put it on hot code paths.

Performs validation before storing the fetched config.

If `meta` is non-nil, it will receive the config metadata.