gaeconfig

Documentation

Overview

Package gaeconfig implements LUCI-config service bindings backed by AppEngine storage and caching.

Importing this module registers ${appid} variable in config validation rules.

Index

• Constants
• Variables
• func GetConfigServiceAppID(c context.Context) (string, error)
• func InstallCacheCronHandler(r *router.Router, base router.MiddlewareChain)
• func InstallValidationHandlers(r *router.Router, base router.MiddlewareChain, rules *validation.RuleSet)
• func RegisterValidationVars(rules *validation.RuleSet)
• func Use(c context.Context) context.Context
• func UseFlex(c context.Context) context.Context
• type DSCacheMode
• type Settings
  • func DefaultSettings(c context.Context) Settings
  • func FetchCachedSettings(c context.Context) (Settings, error)
  • func (s *Settings) CacheExpiration() time.Duration
  • func (s *Settings) SetIfChanged(c context.Context, who, why string) error

Constants

const DefaultExpire = 10 * time.Minute

DefaultExpire is a reasonable default expiration value to use on prod GAE.

Variables

var ErrNotConfigured = errors.New("config service URL is not set in settings; please visit /admin/portal")

ErrNotConfigured is returned by cfgclient methods if the config service URL is not set. Usually happens for new apps.

Functions

func GetConfigServiceAppID

func GetConfigServiceAppID(c context.Context) (string, error)

GetConfigServiceAppID looks up the app ID of the LUCI Config service, as set in the app's settings.

Returns an empty string if the LUCI Config integration is not configured for the app.

func InstallCacheCronHandler

func InstallCacheCronHandler(r *router.Router, base router.MiddlewareChain)

InstallCacheCronHandler installs the configuration service datastore caching cron handler. This must be installed, and an associated cron must be set up, if datastore caching is enabled.

The cron should be configured to hit the handler at: /admin/config/cache/manager

func InstallValidationHandlers

func InstallValidationHandlers(r *router.Router, base router.MiddlewareChain, rules *validation.RuleSet)

InstallValidationHandlers installs handlers for config validation.

It ensures that caller is either the config service itself or a member of a trusted group, both of which are configurable in the appengine app settings. It requires that the hostname, the email of config service and the name of the trusted group have been defined in the appengine app settings page before the installed endpoints are called.

func RegisterValidationVars

func RegisterValidationVars(rules *validation.RuleSet)

RegisterValidationVars registers placeholders that can be used in validation rules patterns.

Registers:

${appid} - expands into a GAE app ID of the running service.
${config_service_appid} - expands into a GAE app ID of a LUCI Config
    service that the running service is using (or empty string if
    unconfigured).

This function is called during init() time for default rule set.

func Use

func Use(c context.Context) context.Context

Use installs the default luci-config client.

The client is configured to use luci-config URL specified in the settings, using GAE app service account for authentication.

If running in prod, and the settings don't specify luci-config URL, produces an implementation of backend.B that returns ErrNotConfigured from all methods.

If running on devserver, and the settings don't specify luci-config URL, returns a filesystem-based implementation that reads configs from a directory (or a symlink) named 'devcfg' located in the GAE module directory (where app.yaml is) or its immediate parent directory.

If such directory can not be located, produces an implementation of cfgclient that returns errors from all methods.

Panics if it can't load the settings (should not happen since they are in the local memory cache usually).

func UseFlex

func UseFlex(c context.Context) context.Context

UseFlex installs the default luci-config client for an AppEngine Flex environment.

UseFlex has the same effect as Use, except that the backing cache is a process-local cache instead of the AppEngine memcache service.

Types

type DSCacheMode

type DSCacheMode string

DSCacheMode is the datastore cache mode.

const (
	// DSCacheDisabled means that the datastore cache is disabled.
	DSCacheDisabled DSCacheMode = ""
	// DSCacheEnabled means that the datastore cache is enabled.
	//
	// When enabled, all requests that have cached entries will hit the cache,
	// regardless of whether the cache is stale or not. If the cache is stale,
	// a warning will be printed during fetch.
	DSCacheEnabled DSCacheMode = "Enabled"
)

type Settings

type Settings struct {
	// ConfigServiceHost is host name (and port) of the luci-config service to
	// fetch configs from.
	//
	// For legacy reasons, the JSON value is "config_service_url".
	ConfigServiceHost string `json:"config_service_url"`

	// CacheExpirationSec is how long to hold configs in local cache.
	CacheExpirationSec int `json:"cache_expiration_sec"`

	// DatastoreCacheMode is the datastore caching mode.
	DatastoreCacheMode DSCacheMode `json:"datastore_enabled"`

	// Administrators is the auth group of users that can call the validation
	// endpoint.
	AdministratorsGroup string `json:"administrators_group"`
}

Settings are stored in the datastore via appengine/gaesettings package.

func DefaultSettings

func DefaultSettings(c context.Context) Settings

DefaultSettings returns Settings to use if setting store is empty.

func FetchCachedSettings

func FetchCachedSettings(c context.Context) (Settings, error)

FetchCachedSettings fetches Settings from the settings store.

Uses in-process global cache to avoid hitting datastore often. The cache expiration time is 1 min (see gaesettings.expirationTime), meaning the instance will refetch settings once a minute (blocking only one unlucky request to do so).

Returns errors only if there's no cached value (i.e. it is the first call to this function in this process ever) and datastore operation fails.

func (*Settings) CacheExpiration

func (s *Settings) CacheExpiration() time.Duration

CacheExpiration returns a Duration representing the configured cache expiration. If the cache expiration is not configured, CacheExpiration will return 0.

func (*Settings) SetIfChanged

func (s *Settings) SetIfChanged(c context.Context, who, why string) error

SetIfChanged sets "s" to be the new Settings if it differs from the current settings value.