Documentation
¶
Overview ¶
Package caching implements a config.Interface that uses a caching layer to store its configuration values.
The Backend in this package is generic, and does not implement that actual caching interface. Instead, the user should pair it with a cache implementation by implementing its CacheGet method.
Some example caches include:
- Process in-memory cache (proccache).
- memcache, or AppEngine's memcache service.
- A local storage cache (e.g., on-disk)
- A datastore cache.
Index ¶
- Constants
- func Decode(d []byte, v interface{}) error
- func Encode(v interface{}) ([]byte, error)
- func HashParams(params ...string) []byte
- func ProcCache(b backend.B, exp time.Duration) backend.B
- type Backend
- func (b *Backend) ConfigSetURL(c context.Context, configSet string, p backend.Params) (u url.URL, err error)
- func (b *Backend) Get(c context.Context, configSet, path string, p backend.Params) (*backend.Item, error)
- func (b *Backend) GetAll(c context.Context, t backend.GetAllTarget, path string, p backend.Params) ([]*backend.Item, error)
- type Key
- type Loader
- type Operation
- type Value
- type ValueItem
Constants ¶
const ( // OpGet is the Get operation. OpGet = Operation("Get") // OpGetAll is the GetAll operation. OpGetAll = Operation("GetAll") // OpConfigSetURL is the ConfigSetURL operation. OpConfigSetURL = Operation("ConfigSetURL") )
const Schema = "v2"
Schema is the current package's cache schema.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
Decode is a convenience method for decoding a ZLIB-compressed JSON-encoded object encoded by Encode.
func Encode ¶
Encode is a convenience method for generating a ZLIB-compressed JSON-encoded object.
func HashParams ¶
HashParams is a convenience method for hashing a series of strings into a unique hash key for that series.
The output is fixed-size sha256.Size (32) bytes.
Types ¶
type Backend ¶
type Backend struct {
// Backend is the backing Backend.
backend.B
// FailOnError, if true, means that a failure to retrieve a cached item will
// be propagated to the caller immediately. If false, a cache error will
// result in a direct fall-through call to the embedded backend.B.
//
// One might set FailOnError to true if the fallback is unacceptably slow, or
// if they want to enforce caching via failure.
FailOnError bool
// CacheGet retrieves the cached value associated with key. If no such cached
// value exists, CacheGet is responsible for resolving the cache value using
// the supplied Loader.
CacheGet func(context.Context, Key, Loader) (*Value, error)
}
Backend is a backend.B implementation that caches responses.
All cached values are full-content regardless of whether or not full content was requested.
Backend caches content and no-content requests as separate cache entries. This enables one cache to do low-overhead updating against another cache implementation.
func (*Backend) ConfigSetURL ¶
func (b *Backend) ConfigSetURL(c context.Context, configSet string, p backend.Params) (u url.URL, err error)
ConfigSetURL implements backend.B.
type Key ¶
type Key struct {
// Schema is the schema for this key/value. If schema changes in a backwards-
// incompatible way, this must also change.
Schema string `json:"s,omitempty"`
// ServiceURL is the URL of the config service.
ServiceURL string `json:"u,omitempty"`
// Authority is the config authority to use.
Authority backend.Authority `json:"a,omitempty"`
// Op is the operation that is being cached.
Op Operation `json:"op,omitempty"`
// Content is true if this request asked for content.
Content bool `json:"c,omitempty"`
// Formatter is the requesting Key's Formatter parameter, expanded from its
// FormatSpec.
Formatter string `json:"f,omitempty"`
// FormatData is the requesting Key's format Data parameter, expanded from its
// FormatSpec.
FormatData string `json:"fd,omitempty"`
// ConfigSet is the config set parameter. This is valid for "OpGet".
ConfigSet string `json:"cs,omitempty"`
// Path is the path parameters. This is valid for "OpGet" and "OpGetAll".
Path string `json:"p,omitempty"`
// GetAllTarget is the "GetAll" operation type. This is valid for "OpGetAll".
GetAllTarget backend.GetAllTarget `json:"gat,omitempty"`
}
Key is a cache key.
func (*Key) ParamHash ¶
ParamHash returns a deterministic hash of all of the key parameters.
func (*Key) Params ¶
Params returns the backend.Params that are encoded in this Key.
type Loader ¶
Loader retrieves a Value by consulting the backing backend.
The input Value is the current cached Value, or nil if there is no current cached Value. The output Value is the cached Value, if one exists. It is acceptable to return mutate "v" and/or return it as the output Value.
type Operation ¶
type Operation string
Operation is a cache entry operation. Cache entries are all stored in the same object, with different parameters filled based on the operation that they represent.
type Value ¶
type Value struct {
// Items is the cached set of config response items.
//
// For Get, this will either be empty (cached miss) or have a single Item
// in it (cache hit).
Items []ValueItem `json:"i,omitempty"`
// URL is a URL string.
//
// Used with GetConfigSetURL.
URL string `json:"u,omitempty"`
}
Value is a cache value.
func CacheLoad ¶
CacheLoad loads k from backend b.
If an existing cache value is known, it should be supplied as v. Otherwise, v should be nil.
This is effectively a Loader function that is detached from a given cache instance.
func DecodeValue ¶
DecodeValue loads a Value from is encoded representation.
func (*Value) ConfigItems ¶
ConfigItems returns the backend.Item projection of v's Items slice.
func (*Value) Description ¶
Description returns a human-readable string describing the contents of this value.
func (*Value) Encode ¶
Encode encodes this Value.
This is offered for convenience, but caches aren't required to use this encoding.
The format stores the Value as compressed JSON.
func (*Value) LoadItems ¶
LoadItems loads a set of backend.Item into v's Items field. If items is nil, v.Items will be nil.
type ValueItem ¶
type ValueItem struct {
ConfigSet string `json:"cs,omitempty"`
Path string `json:"p,omitempty"`
ContentHash string `json:"ch,omitempty"`
Revision string `json:"r,omitempty"`
Content []byte `json:"c,omitempty"`
Formatter string `json:"f,omitempty"`
FormatData []byte `json:"fd,omitempty"`
}
ValueItem is a cache-optimized backend.Item projection.
This will mostly be the same as a backend.Item, with the exception of Content, which will hold the formatted value if it has been formatted.
See Formatter in github.com/luci/luci-go/luci_config/server/cfgclient and Backend in github.com/luci/luci-go/luci_config/server/cfgclient.backend/format for more information.
func MakeValueItem ¶
MakeValueItem builds a caching ValueItem from a backend.Item.
Source Files