Documentation
¶
Overview ¶
Package cache provides a framework for implementing and registering different cache backends.
Index ¶
- Variables
- func Fetch(client *http.Client, r *http.Request, c Cache) (*http.Response, error)
- func FetchDirect(client *http.Client, r *http.Request, c Cache, key Key) (*http.Response, error)
- func NewHTTPClient(headerFunc HeaderFunc) *http.Client
- func Register[Config any, C Cache](r *Registry, id, description string, factory Factory[Config, C])
- func RegisterDisk(r *Registry)
- func RegisterMemory(r *Registry)
- func RegisterS3(r *Registry, clientProvider s3client.ClientProvider)
- func ValidateNamespace(name string) error
- type Cache
- type Disk
- func (d *Disk) Close() error
- func (d *Disk) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
- func (d *Disk) Delete(_ context.Context, key Key) error
- func (d *Disk) ListNamespaces(_ context.Context) ([]string, error)
- func (d *Disk) Namespace(namespace Namespace) Cache
- func (d *Disk) Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error)
- func (d *Disk) Size() int64
- func (d *Disk) Stat(ctx context.Context, key Key) (http.Header, error)
- func (d *Disk) Stats(_ context.Context) (Stats, error)
- func (d *Disk) String() string
- type DiskConfig
- type Factory
- type HeaderFunc
- type Key
- type Memory
- func (m *Memory) Close() error
- func (m *Memory) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
- func (m *Memory) Delete(_ context.Context, key Key) error
- func (m *Memory) ListNamespaces(_ context.Context) ([]string, error)
- func (m *Memory) Namespace(namespace Namespace) Cache
- func (m *Memory) Open(_ context.Context, key Key) (io.ReadCloser, http.Header, error)
- func (m *Memory) Stat(_ context.Context, key Key) (http.Header, error)
- func (m *Memory) Stats(_ context.Context) (Stats, error)
- func (m *Memory) String() string
- type MemoryConfig
- type Namespace
- type Registry
- type Remote
- func (c *Remote) Close() error
- func (c *Remote) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
- func (c *Remote) Delete(ctx context.Context, key Key) error
- func (c *Remote) ListNamespaces(ctx context.Context) ([]string, error)
- func (c *Remote) Namespace(namespace Namespace) Cache
- func (c *Remote) Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error)
- func (c *Remote) Stat(ctx context.Context, key Key) (http.Header, error)
- func (c *Remote) Stats(ctx context.Context) (Stats, error)
- func (c *Remote) String() string
- type S3
- func (s *S3) Close() error
- func (s *S3) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
- func (s *S3) Delete(ctx context.Context, key Key) error
- func (s *S3) ListNamespaces(_ context.Context) ([]string, error)
- func (s *S3) Namespace(namespace Namespace) Cache
- func (s *S3) Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error)
- func (s *S3) Stat(ctx context.Context, key Key) (http.Header, error)
- func (s *S3) Stats(_ context.Context) (Stats, error)
- func (s *S3) String() string
- type S3Config
- type Stats
- type Tiered
- func (t Tiered) Close() error
- func (t Tiered) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
- func (t Tiered) Delete(ctx context.Context, key Key) error
- func (t Tiered) ListNamespaces(ctx context.Context) ([]string, error)
- func (t Tiered) Namespace(namespace Namespace) Cache
- func (t Tiered) Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error)
- func (t Tiered) Stat(ctx context.Context, key Key) (http.Header, error)
- func (t Tiered) Stats(ctx context.Context) (Stats, error)
- func (t Tiered) String() string
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("cache backend not found")
ErrNotFound is returned when a cache backend is not found.
ErrStatsUnavailable is returned when a cache backend cannot provide statistics.
Functions ¶
func Fetch ¶
Fetch retrieves a response from cache or fetches from the request URL and caches it. The response is streamed without buffering. Returns HTTPError for semantic errors. The caller must close the response body.
func FetchDirect ¶
FetchDirect fetches and caches the given URL without checking the cache first. The response is streamed without buffering. Returns HTTPError for semantic errors. The caller must close the response body.
func NewHTTPClient ¶
func NewHTTPClient(headerFunc HeaderFunc) *http.Client
NewHTTPClient creates an *http.Client that attaches headerFunc headers to every outgoing request. Useful for callers that need to talk to non-API endpoints (e.g. /git/) with the same auth as the cache client.
func RegisterMemory ¶
func RegisterMemory(r *Registry)
func RegisterS3 ¶
func RegisterS3(r *Registry, clientProvider s3client.ClientProvider)
RegisterS3 registers the S3 cache backend. The clientProvider supplies the shared minio client constructed from the global s3 config block.
func ValidateNamespace ¶
ValidateNamespace checks that a namespace name is valid.
Types ¶
type Cache ¶
type Cache interface {
// String describes the Cache implementation.
String() string
// Namespace creates a namespaced view of this cache.
// All operations on the returned cache will use the given namespace prefix.
Namespace(namespace Namespace) Cache
// Stat returns the headers of an existing object in the cache.
//
// Expired files MUST not be returned.
// Must return os.ErrNotExist if the file does not exist.
Stat(ctx context.Context, key Key) (http.Header, error)
// Open an existing file in the cache.
//
// Expired files MUST NOT be returned.
// The returned headers MUST include a Last-Modified header.
// Must return os.ErrNotExist if the file does not exist.
Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error)
// Create a new file in the cache.
//
// If "ttl" is zero, a maximum TTL MUST be used by the implementation.
//
// The file MUST NOT be available for read until completely written and closed.
//
// If the context is cancelled the object MUST NOT be made available in the cache.
Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
// Delete a file from the cache.
//
// MUST be atomic.
Delete(ctx context.Context, key Key) error
// Stats returns health and usage statistics for the cache.
Stats(ctx context.Context) (Stats, error)
// ListNamespaces returns all unique namespaces in the cache in order.
ListNamespaces(ctx context.Context) ([]string, error)
// Close the Cache.
Close() error
}
A Cache knows how to retrieve, create and delete objects from a cache.
Objects in the cache are not guaranteed to persist and implementations may delete them at any time.
func MaybeNewTiered ¶
MaybeNewTiered creates a Tiered cache if multiple are provided, or if there is only one it will return that cache.
If no caches are passed it will panic.
type Disk ¶
type Disk struct {
// contains filtered or unexported fields
}
func NewDisk ¶
func NewDisk(ctx context.Context, config DiskConfig) (*Disk, error)
NewDisk creates a new disk-based cache instance.
config.Root MUST be set.
This Cache implementation stores cache entries under a directory. If total usage exceeds the limit, entries are evicted based on their last access time. TTLs are stored in a bbolt database. If an entry exceeds its TTL or the default, it is evicted. The implementation is safe for concurrent use within a single Go process.
func (*Disk) ListNamespaces ¶
ListNamespaces returns all unique namespaces in the disk cache.
type DiskConfig ¶
type DiskConfig struct {
Root string `hcl:"root,optional" help:"Root directory for the disk storage." default:"${CACHEW_STATE}/cache"`
LimitMB int `hcl:"limit-mb,optional" help:"Maximum size of the disk cache in megabytes (defaults to 10GB)." default:"10240"`
MaxTTL time.Duration `hcl:"max-ttl,optional" help:"Maximum time-to-live for entries in the disk cache (defaults to 1 hour)." default:"1h"`
EvictInterval time.Duration `hcl:"evict-interval,optional" help:"Interval at which to check files for eviction (defaults to 1 minute)." default:"1m"`
}
type Factory ¶
Factory is a function that creates a new cache instance from the given hcl-tagged configuration struct.
type HeaderFunc ¶
HeaderFunc returns headers to attach to each outgoing request.
type Key ¶
type Key [32]byte
Key represents a unique identifier for a cached object.
func (*Key) MarshalText ¶
func (*Key) UnmarshalText ¶
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
func (*Memory) ListNamespaces ¶
ListNamespaces returns all unique namespaces in the memory cache.
type MemoryConfig ¶
type Namespace ¶
type Namespace string
Namespace identifies a logical partition within a cache or metadata store. Valid names start with an alphanumeric character and contain only alphanumerics, hyphens, and underscores.
func ParseNamespace ¶
ParseNamespace validates and returns a Namespace from a plain string.
func (*Namespace) UnmarshalText ¶
UnmarshalText implements encoding.TextUnmarshaler with validation.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
func NewRegistry ¶
func NewRegistry() *Registry
type Remote ¶
type Remote struct {
// contains filtered or unexported fields
}
Remote implements Cache as a client for the remote cache server.
func NewRemote ¶
func NewRemote(baseURL string, headerFunc HeaderFunc) *Remote
NewRemote creates a new remote cache client. If headerFunc is non-nil, its returned headers are added to every outgoing request.
func (*Remote) Create ¶
func (c *Remote) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
Create stores a new object in the remote.
func (*Remote) ListNamespaces ¶
ListNamespaces requests namespace list from the remote server.
type S3 ¶
type S3 struct {
// contains filtered or unexported fields
}
func NewS3 ¶
func NewS3(ctx context.Context, config S3Config, clientProvider s3client.ClientProvider) (*S3, error)
NewS3 creates a new S3-based cache instance.
The minio client is obtained from the shared clientProvider, which is constructed once from the global s3 configuration block. Cache-specific settings (bucket, TTL, upload tuning) come from the per-instance S3Config.
This Cache implementation stores cache entries in an S3-compatible object storage service. Metadata (headers and expiration time) are stored as object user metadata. The implementation uses the lightweight minio-go SDK to reduce overhead compared to the AWS SDK.
func (*S3) ListNamespaces ¶
ListNamespaces returns all unique namespaces in the S3 cache. Not implemented for S3 - would require listing all objects.
type S3Config ¶
type S3Config struct {
Bucket string `hcl:"bucket" help:"S3 bucket name."`
MaxTTL time.Duration `hcl:"max-ttl,optional" help:"Maximum time-to-live for entries in the S3 cache (defaults to 1 hour)." default:"1h"`
UploadConcurrency uint `` /* 144-byte string literal not displayed */
UploadPartSizeMB uint `` /* 141-byte string literal not displayed */
}
S3Config contains cache-specific S3 settings. Connection parameters (endpoint, region, SSL, credentials) are provided by the global s3client.Config block and shared via the s3client.ClientProvider.
type Stats ¶
type Stats struct {
// Objects is the number of objects currently in the cache.
Objects int64 `json:"objects"`
// Size is the total size of all objects in the cache in bytes.
Size int64 `json:"size"`
// Capacity is the maximum size of the cache in bytes (0 if unlimited).
Capacity int64 `json:"capacity"`
}
Stats contains health and usage statistics for a cache.
type Tiered ¶
type Tiered struct {
// contains filtered or unexported fields
}
The Tiered cache combines multiple caches.
It is not directly selectable from configuration, but instead is automatically used if multiple caches are configured.
func (Tiered) Create ¶
func (t Tiered) Create(ctx context.Context, key Key, headers http.Header, ttl time.Duration) (io.WriteCloser, error)
Create a new object. All underlying caches will be written to in sequence.
func (Tiered) ListNamespaces ¶
ListNamespaces returns unique namespaces from all underlying caches.
func (Tiered) Namespace ¶
Namespace creates a namespaced view of the tiered cache. All underlying caches are also namespaced.
func (Tiered) Open ¶
Open returns a reader from the first cache that succeeds. When a higher tier hits but lower tiers missed, the returned reader transparently backfills the lowest tier as the caller reads, so that subsequent Opens are served locally.
If all caches fail, all errors are returned.
Source Files
Directories