caching

package
v0.0.0-...-678bb0e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 8, 2017 License: Apache-2.0 Imports: 15 Imported by: 0

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

View Source
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")
)
View Source
const Schema = "v2"

Schema is the current package's cache schema.

Variables

This section is empty.

Functions

func Decode

func Decode(d []byte, v interface{}) error

Decode is a convenience method for decoding a ZLIB-compressed JSON-encoded object encoded by Encode.

func Encode

func Encode(v interface{}) ([]byte, error)

Encode is a convenience method for generating a ZLIB-compressed JSON-encoded object.

func HashParams

func HashParams(params ...string) []byte

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.

func ProcCache

func ProcCache(b backend.B, exp time.Duration) backend.B

ProcCache returns a backend.B that caches configuration service results in an in-memory proccache instance.

This will only cache results for AsService calls; any other Authority will pass through.

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.

func (*Backend) Get

func (b *Backend) Get(c context.Context, configSet, path string, p backend.Params) (*backend.Item, error)

Get implements backend.B.

func (*Backend) GetAll

func (b *Backend) GetAll(c context.Context, t backend.GetAllTarget, path string, p backend.Params) ([]*backend.Item, error)

GetAll implements config.Backend.

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

func (k *Key) ParamHash() []byte

ParamHash returns a deterministic hash of all of the key parameters.

func (*Key) Params

func (k *Key) Params() backend.Params

Params returns the backend.Params that are encoded in this Key.

func (*Key) String

func (k *Key) String() string

String prints a text representation of the key. No effort is made to ensure that this representation is consistent or deterministic, and it is not bound to the cache schema.

type Loader

type Loader func(context.Context, Key, *Value) (*Value, error)

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

func CacheLoad(c context.Context, b backend.B, k Key, v *Value) (rv *Value, err error)

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

func DecodeValue(d []byte) (*Value, error)

DecodeValue loads a Value from is encoded representation.

func (*Value) ConfigItems

func (v *Value) ConfigItems() []*backend.Item

ConfigItems returns the backend.Item projection of v's Items slice.

func (*Value) Description

func (v *Value) Description() string

Description returns a human-readable string describing the contents of this value.

func (*Value) Encode

func (v *Value) Encode() ([]byte, error)

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

func (v *Value) LoadItems(items ...*backend.Item)

LoadItems loads a set of backend.Item into v's Items field. If items is nil, v.Items will be nil.

func (*Value) SingleItem

func (v *Value) SingleItem() *backend.Item

SingleItem returns the first backend.Item in v's Items slice. If the Items slice is empty, SingleItem will return 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

func MakeValueItem(it *backend.Item) ValueItem

MakeValueItem builds a caching ValueItem from a backend.Item.

func (*ValueItem) ConfigItem

func (vi *ValueItem) ConfigItem() *backend.Item

ConfigItem returns the backend.Item equivalent of vi.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL