fscache

Documentation

Overview

Package fscache implements a file system-based cache backend.

Entries are stored as files in a directory under the user's OS cache directory by default. The cache location and behavior are configured via DSN query parameters.

Supported DSN query parameters:

• appname (required): Subdirectory name for cache isolation.
• timeout (optional): Operation timeout (e.g., "2s", "500ms"). Default: 5m.
• connect_timeout (optional): Timeout for establishing the cache connection (e.g., "2s"). Default: 5m.
• encrypt (optional): Enable encryption for cache entries. Set to "on" or "aesgcm".
• encrypt_key (optional): The AES key, base64-encoded (URL-safe variant with/without padding as per RFC 4648 §5). Must decode to the correct length as required by crypto/aes.

Example DSNs:

fscache://?appname=myapp
fscache:///tmp/cache?appname=myapp&timeout=2s
fscache:///tmp/cache?appname=myapp&connect_timeout=2s&timeout=1m
fscache://?appname=myapp&encrypt=on&encrypt_key=6S-Ks2YYOW0xMvTzKSv6QD30gZeOi1c6Ydr-As5csWk=

Example environment variable:

export FSCACHE_ENCRYPT_KEY="6S-Ks2YYOW0xMvTzKSv6QD30gZeOi1c6Ydr-As5csWk="

To generate a suitable encryption key (32 bytes, URL-safe, with padding):

openssl rand 32 | base64 | tr '+/' '-_' | tr -d '\n'

Index

• Constants
• Variables
• func Open(appname string, opts ...Option) (*fsCache, error)
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Option
  • func WithBaseDir(base string) Option
  • func WithConnectTimeout(timeout time.Duration) Option
  • func WithEncryption(key string) Option
  • func WithTimeout(timeout time.Duration) Option

Constants

const Scheme = "fscache" // url scheme for the file system cache

Variables

var (
	ErrUserCacheDir   = errors.New("fscache: could not determine user cache dir")
	ErrMissingAppName = errors.New("fscache: appname query parameter is required")
	ErrCreateCacheDir = errors.New("fscache: could not create cache dir")
)

Functions

func Open

func Open(appname string, opts ...Option) (*fsCache, error)

Open creates a new file system cache with the specified application name and options.

See the package documentation for supported options and examples.

Types

type Error

type Error struct {
	Op  string // operation being performed (e.g., "Get", "Set")
	Key string // optional key for which the operation failed
	Err error  // underlying error
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithBaseDir

func WithBaseDir(base string) Option

WithBaseDir sets the base directory for the cache; default: user's OS cache directory.

func WithConnectTimeout

func WithConnectTimeout(timeout time.Duration) Option

WithConnectTimeout sets the timeout for establishing the cache connection; default: 5 minutes.

func WithEncryption

func WithEncryption(key string) Option

WithEncryption enables encryption for cache entries using AES-GCM.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the timeout for cache operations; default: 5 minutes.