fscache

Overview ¶

Package fscache implements a file system-based cache backend.

Entries are stored as files in a structured directory hierarchy. Cache entries are stored under the user's OS cache directory by default, with support for custom base directories via the WithBaseDir option or DSN path specification.

The cache supports advanced features including AES-GCM encryption, configurable timeouts, and optional modification time tracking for LRU cleanup strategies. All configuration can be specified through DSN query parameters or programmatic [Option]s passed to Open.

Configuration Parameters ¶

The following DSN query parameters are supported:

• appname (required): Application subdirectory name for cache isolation
• timeout (optional): Operation timeout duration (default: 5m)
• connect_timeout (optional): Cache initialization timeout (default: 5m)
• encrypt (optional): Enable AES-GCM encryption ("on" or "aesgcm")
• encrypt_key (optional): Base64-encoded AES key (URL-safe, RFC 4648 §5)
• update_mtime (optional): Update file mtime on cache hits ("on" to enable)

Usage Examples ¶

The DSN and equavalent programmatic usage are shown below.

 Basic usage:

	fscache://?appname=myapp
	fscache.Open("myapp")

 Custom directory with timeouts:

	fscache:///tmp/cache?appname=myapp&timeout=2s&connect_timeout=10s
	fscache.Open("myapp", fscache.WithBaseDir("/tmp/cache"), fscache.WithTimeout(2*time.Second), fscache.WithConnectTimeout(10*time.Second))

 Encrypted cache:

	fscache://?appname=myapp&encrypt=on&encrypt_key=6S-Ks2YYOW0xMvTzKSv6QD30gZeOi1c6Ydr-As5csWk=
	fscache.Open("myapp", fscache.WithEncryption("6S-Ks2YYOW0xMvTzKSv6QD30gZeOi1c6Ydr-As5csWk="))

 Update modification time on cache hits:

	fscache://?appname=myapp&update_mtime=on
	fscache.Open("myapp", fscache.WithUpdateMTime(true))

Encryption Key Management ¶

Encryption keys can be provided via DSN parameter or environment variable:

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

Generate a secure 256-bit encryption key:

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

LRU Cleanup Integration ¶

When update_mtime is enabled, cache hits update file modification times, enabling efficient LRU cleanup using standard Unix tools:

# Remove files older than 7 days
find /cache/dir -type f -mtime +7 -delete

# Keep only the 1000 most recently used files
find /cache/dir -type f -printf '%T@ %p\n' | sort -rn | tail -n +1001 | cut -d' ' -f2- | xargs rm