cache

Documentation

Overview

Package cache provides caching features for data from a Consul server.

While this is similar in some ways to the "agent/ae" package, a key difference is that with anti-entropy, the agent is the authoritative source so it resolves differences the server may have. With caching (this package), the server is the authoritative source and we do our best to balance performance and correctness, depending on the type of data being requested.

The types of data that can be cached is configurable via the Type interface. This allows specialized behavior for certain types of data. Each type of Consul data (CA roots, leaf certs, intentions, KV, catalog, etc.) will have to be manually implemented. This usually is not much work, see the "agent/cache-types" package.

Code generated by mockery v1.0.0

Code generated by mockery v1.0.0

Index

• Constants
• func TestCacheGetCh(t testing.T, c *Cache, typ string, r Request) <-chan interface{}
• func TestCacheGetChResult(t testing.T, ch <-chan interface{}, expected interface{})
• type Cache
  • func New(*Options) *Cache
  • func TestCache(t testing.T) *Cache
  • func (c *Cache) Get(t string, r Request) (interface{}, ResultMeta, error)
  • func (c *Cache) RegisterType(n string, typ Type, opts *RegisterOptions)
• type FetchOptions
• type FetchResult
• type MockRequest
  • func TestRequest(t testing.T, info RequestInfo) *MockRequest
  • func (_m *MockRequest) CacheInfo() RequestInfo
  • func (m *MockRequest) Reset()
• type MockType
  • func TestType(t testing.T) *MockType
  • func (_m *MockType) Fetch(_a0 FetchOptions, _a1 Request) (FetchResult, error)
  • func (m *MockType) Static(r FetchResult, err error) *mock.Call
• type Options
• type RegisterOptions
• type Request
• type RequestInfo
• type ResultMeta
• type Type

Constants

const (
	CacheRefreshBackoffMin = 3               // 3 attempts before backing off
	CacheRefreshMaxWait    = 1 * time.Minute // maximum backoff wait time
)

Constants related to refresh backoff. We probably don't ever need to make these configurable knobs since they primarily exist to lower load.

Functions

func TestCacheGetCh

func TestCacheGetCh(t testing.T, c *Cache, typ string, r Request) <-chan interface{}

TestCacheGetCh returns a channel that returns the result of the Get call. This is useful for testing timing and concurrency with Get calls. Any error will be logged, so the result value should always be asserted.

func TestCacheGetChResult

func TestCacheGetChResult(t testing.T, ch <-chan interface{}, expected interface{})

TestCacheGetChResult tests that the result from TestCacheGetCh matches within a reasonable period of time (it expects it to be "immediate" but waits some milliseconds).

Types

type Cache

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a agent-local cache of Consul data. Create a Cache using the New function. A zero-value Cache is not ready for usage and will result in a panic.

The types of data to be cached must be registered via RegisterType. Then, calls to Get specify the type and a Request implementation. The implementation of Request is usually done directly on the standard RPC struct in agent/structs. This API makes cache usage a mostly drop-in replacement for non-cached RPC calls.

The cache is partitioned by ACL and datacenter. This allows the cache to be safe for multi-DC queries and for queries where the data is modified due to ACLs all without the cache having to have any clever logic, at the slight expense of a less perfect cache.

The Cache exposes various metrics via go-metrics. Please view the source searching for "metrics." to see the various metrics exposed. These can be used to explore the performance of the cache.

func New

func New(*Options) *Cache

New creates a new cache with the given RPC client and reasonable defaults. Further settings can be tweaked on the returned value.

func TestCache

func TestCache(t testing.T) *Cache

TestCache returns a Cache instance configuring for testing.

func (*Cache) Get

func (c *Cache) Get(t string, r Request) (interface{}, ResultMeta, error)

Get loads the data for the given type and request. If data satisfying the minimum index is present in the cache, it is returned immediately. Otherwise, this will block until the data is available or the request timeout is reached.

Multiple Get calls for the same Request (matching CacheKey value) will block on a single network request.

The timeout specified by the Request will be the timeout on the cache Get, and does not correspond to the timeout of any background data fetching. If the timeout is reached before data satisfying the minimum index is retrieved, the last known value (maybe nil) is returned. No error is returned on timeout. This matches the behavior of Consul blocking queries.

func (*Cache) RegisterType

func (c *Cache) RegisterType(n string, typ Type, opts *RegisterOptions)

RegisterType registers a cacheable type.

This makes the type available for Get but does not automatically perform any prefetching. In order to populate the cache, Get must be called.

type FetchOptions

type FetchOptions struct {
	// MinIndex is the minimum index to be used for blocking queries.
	// If blocking queries aren't supported for data being returned,
	// this value can be ignored.
	MinIndex uint64

	// Timeout is the maximum time for the query. This must be implemented
	// in the Fetch itself.
	Timeout time.Duration
}

FetchOptions are various settable options when a Fetch is called.

type FetchResult

type FetchResult struct {
	// Value is the result of the fetch.
	Value interface{}

	// Index is the corresponding index value for this data.
	Index uint64
}

FetchResult is the result of a Type Fetch operation and contains the data along with metadata gathered from that operation.

type MockRequest

type MockRequest struct {
	mock.Mock
}

MockRequest is an autogenerated mock type for the Request type

func TestRequest

func TestRequest(t testing.T, info RequestInfo) *MockRequest

TestRequest returns a Request that returns the given cache key and index. The Reset method can be called to reset it for custom usage.

func (*MockRequest) CacheInfo

func (_m *MockRequest) CacheInfo() RequestInfo

CacheInfo provides a mock function with given fields:

func (*MockRequest) Reset

func (m *MockRequest) Reset()

type MockType

type MockType struct {
	mock.Mock
}

MockType is an autogenerated mock type for the Type type

func TestType

func TestType(t testing.T) *MockType

TestType returns a MockType that can be used to setup expectations on data fetching.

func (*MockType) Fetch

func (_m *MockType) Fetch(_a0 FetchOptions, _a1 Request) (FetchResult, error)

Fetch provides a mock function with given fields: _a0, _a1

func (*MockType) Static

func (m *MockType) Static(r FetchResult, err error) *mock.Call

Static sets a static value to return for a call to Fetch.

type Options

type Options struct {
}

Options are options for the Cache.

type RegisterOptions

type RegisterOptions struct {
	// LastGetTTL is the time that the values returned by this type remain
	// in the cache after the last get operation. If a value isn't accessed
	// within this duration, the value is purged from the cache and
	// background refreshing will cease.
	LastGetTTL time.Duration

	// Refresh configures whether the data is actively refreshed or if
	// the data is only refreshed on an explicit Get. The default (false)
	// is to only request data on explicit Get.
	Refresh bool

	// RefreshTimer is the time between attempting to refresh data.
	// If this is zero, then data is refreshed immediately when a fetch
	// is returned.
	//
	// RefreshTimeout determines the maximum query time for a refresh
	// operation. This is specified as part of the query options and is
	// expected to be implemented by the Type itself.
	//
	// Using these values, various "refresh" mechanisms can be implemented:
	//
	//   * With a high timer duration and a low timeout, a timer-based
	//     refresh can be set that minimizes load on the Consul servers.
	//
	//   * With a low timer and high timeout duration, a blocking-query-based
	//     refresh can be set so that changes in server data are recognized
	//     within the cache very quickly.
	//
	RefreshTimer   time.Duration
	RefreshTimeout time.Duration
}

RegisterOptions are options that can be associated with a type being registered for the cache. This changes the behavior of the cache for this type.

type Request

type Request interface {
	// CacheInfo returns information used for caching this request.
	CacheInfo() RequestInfo
}

Request is a cacheable request.

This interface is typically implemented by request structures in the agent/structs package.

type RequestInfo

type RequestInfo struct {
	// Key is a unique cache key for this request. This key should
	// be globally unique to identify this request, since any conflicting
	// cache keys could result in invalid data being returned from the cache.
	// The Key does not need to include ACL or DC information, since the
	// cache already partitions by these values prior to using this key.
	Key string

	// Token is the ACL token associated with this request.
	//
	// Datacenter is the datacenter that the request is targeting.
	//
	// Both of these values are used to partition the cache. The cache framework
	// today partitions data on these values to simplify behavior: by
	// partitioning ACL tokens, the cache doesn't need to be smart about
	// filtering results. By filtering datacenter results, the cache can
	// service the multi-DC nature of Consul. This comes at the expense of
	// working set size, but in general the effect is minimal.
	Token      string
	Datacenter string

	// MinIndex is the minimum index being queried. This is used to
	// determine if we already have data satisfying the query or if we need
	// to block until new data is available. If no index is available, the
	// default value (zero) is acceptable.
	MinIndex uint64

	// Timeout is the timeout for waiting on a blocking query. When the
	// timeout is reached, the last known value is returned (or maybe nil
	// if there was no prior value). This "last known value" behavior matches
	// normal Consul blocking queries.
	Timeout time.Duration
}

RequestInfo represents cache information for a request. The caching framework uses this to control the behavior of caching and to determine cacheability.

type ResultMeta

type ResultMeta struct {
	// Return whether or not the request was a cache hit
	Hit bool
}

ResultMeta is returned from Get calls along with the value and can be used to expose information about the cache status for debugging or testing.

type Type

type Type interface {
	// Fetch fetches a single unique item.
	//
	// The FetchOptions contain the index and timeouts for blocking queries.
	// The MinIndex value on the Request itself should NOT be used
	// as the blocking index since a request may be reused multiple times
	// as part of Refresh behavior.
	//
	// The return value is a FetchResult which contains information about
	// the fetch. If an error is given, the FetchResult is ignored. The
	// cache does not support backends that return partial values.
	//
	// On timeout, FetchResult can behave one of two ways. First, it can
	// return the last known value. This is the default behavior of blocking
	// RPC calls in Consul so this allows cache types to be implemented with
	// no extra logic. Second, FetchResult can return an unset value and index.
	// In this case, the cache will reuse the last value automatically.
	Fetch(FetchOptions, Request) (FetchResult, error)
}

Type implements the logic to fetch certain types of data.