github.com/outbrain/consul@v1.4.5/agent/cache/request.go (about)

     1  package cache
     2  
     3  import (
     4  	"time"
     5  )
     6  
     7  // Request is a cacheable request.
     8  //
     9  // This interface is typically implemented by request structures in
    10  // the agent/structs package.
    11  type Request interface {
    12  	// CacheInfo returns information used for caching this request.
    13  	CacheInfo() RequestInfo
    14  }
    15  
    16  // RequestInfo represents cache information for a request. The caching
    17  // framework uses this to control the behavior of caching and to determine
    18  // cacheability.
    19  type RequestInfo struct {
    20  	// Key is a unique cache key for this request. This key should
    21  	// be globally unique to identify this request, since any conflicting
    22  	// cache keys could result in invalid data being returned from the cache.
    23  	// The Key does not need to include ACL or DC information, since the
    24  	// cache already partitions by these values prior to using this key.
    25  	Key string
    26  
    27  	// Token is the ACL token associated with this request.
    28  	//
    29  	// Datacenter is the datacenter that the request is targeting.
    30  	//
    31  	// Both of these values are used to partition the cache. The cache framework
    32  	// today partitions data on these values to simplify behavior: by
    33  	// partitioning ACL tokens, the cache doesn't need to be smart about
    34  	// filtering results. By filtering datacenter results, the cache can
    35  	// service the multi-DC nature of Consul. This comes at the expense of
    36  	// working set size, but in general the effect is minimal.
    37  	Token      string
    38  	Datacenter string
    39  
    40  	// MinIndex is the minimum index being queried. This is used to
    41  	// determine if we already have data satisfying the query or if we need
    42  	// to block until new data is available. If no index is available, the
    43  	// default value (zero) is acceptable.
    44  	MinIndex uint64
    45  
    46  	// Timeout is the timeout for waiting on a blocking query. When the
    47  	// timeout is reached, the last known value is returned (or maybe nil
    48  	// if there was no prior value). This "last known value" behavior matches
    49  	// normal Consul blocking queries.
    50  	Timeout time.Duration
    51  
    52  	// MaxAge if set limits how stale a cache entry can be. If it is non-zero and
    53  	// there is an entry in cache that is older than specified, it is treated as a
    54  	// cache miss and re-fetched. It is ignored for cachetypes with Refresh =
    55  	// true.
    56  	MaxAge time.Duration
    57  
    58  	// MustRevalidate forces a new lookup of the cache even if there is an
    59  	// existing one that has not expired. It is implied by HTTP requests with
    60  	// `Cache-Control: max-age=0` but we can't distinguish that case from the
    61  	// unset case for MaxAge. Later we may support revalidating the index without
    62  	// a full re-fetch but for now the only option is to refetch. It is ignored
    63  	// for cachetypes with Refresh = true.
    64  	MustRevalidate bool
    65  }