Documentation

Overview

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

    Index

    Constants

    View Source
    const DefaultExpire = 10 * time.Minute

      DefaultExpire is a reasonable default expiration value.

      Variables

      View Source
      var ErrNotConfigured = errors.New("config service URL is not set in settings")

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

        Functions

        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 Use

            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).

            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"`
              }

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

                func DefaultSettings

                func DefaultSettings() 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) 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.