docs(fscache): enhance documentation for cache configuration and usage examples

Author: bartventer

store/fscache/fscache.go

@@ -14,38 +14,70 @@
 
 // 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.
+// 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.
 //
-// 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].
-//   - update_mtime (optional): Update file modification time on cache hits.
-//     Set to "on" to enable. Default: "off".
+// 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].
 //
-// Example DSNs:
+// # Configuration Parameters
 //
-//	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=
-//	fscache://?appname=myapp&update_mtime=on
+// The following DSN query parameters are supported:
 //
-// Example environment variable:
+//   - 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="
 //
-// To generate a suitable encryption key (32 bytes, URL-safe, with padding):
+// 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
 package fscache
 
 import (