README
¶
persist/localfs
Local filesystem persistence using Go's gob encoding.
Features
- Zero dependencies beyond stdlib
- Automatic directory management
- Per-item file storage for crash safety
- Buffered I/O for performance
- Works across all platforms
Usage
import (
"github.com/codeGROOVE-dev/sfcache"
"github.com/codeGROOVE-dev/sfcache/persist/localfs"
)
// Uses OS cache directory (e.g., ~/.cache/myapp on Linux)
p, _ := localfs.New[string, User]("myapp", "")
// Or specify custom directory
p, _ := localfs.New[string, User]("myapp", "/tmp/my-cache")
cache, _ := sfcache.New[string, User](ctx,
sfcache.WithPersistence(p))
Storage Location
Files are stored in subdirectories based on key hash to avoid filesystem limits:
- Linux/macOS:
~/.cache/myapp/XX/key - Windows:
%LocalAppData%\myapp\XX\key
Where XX is the first 2 hex digits of the key's hash.
Key Constraints
- Maximum key length: 127 characters
- Keys are sanitized for filesystem safety
- No path traversal sequences allowed
Documentation
¶
Overview ¶
Package localfs provides local filesystem persistence for sfcache.
Index ¶
- type Entry
- type Store
- func (s *Store[K, V]) Cleanup(ctx context.Context, maxAge time.Duration) (int, error)
- func (*Store[K, V]) Close() error
- func (s *Store[K, V]) Delete(ctx context.Context, key K) error
- func (s *Store[K, V]) Flush(ctx context.Context) (int, error)
- func (s *Store[K, V]) Get(ctx context.Context, key K) (value V, expiry time.Time, found bool, err error)
- func (s *Store[K, V]) Len(ctx context.Context) (int, error)
- func (s *Store[K, V]) Location(key K) string
- func (s *Store[K, V]) Set(ctx context.Context, key K, value V, expiry time.Time) error
- func (*Store[K, V]) ValidateKey(key K) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store[K comparable, V any] struct { Dir string // Exported for testing - directory path // contains filtered or unexported fields }
Store implements file-based persistence using local files with JSON encoding.
func New ¶
func New[K comparable, V any](cacheID, dir string, c ...compress.Compressor) (*Store[K, V], error)
New creates a new file-based persistence layer. The cacheID is used as a subdirectory name under the OS cache directory. If dir is provided (non-empty), it's used as the base directory instead of OS cache dir. Optional compressor enables compression (default: no compression, plain JSON with .j extension).
func (*Store[K, V]) Cleanup ¶
Cleanup removes expired entries from file storage. Walks through all cache files and deletes those with expired timestamps. Returns the count of deleted entries and any errors encountered.
func (*Store[K, V]) Flush ¶
Flush removes all entries from the file-based cache. Returns the number of entries removed and any errors encountered.
func (*Store[K, V]) Get ¶
func (s *Store[K, V]) Get(ctx context.Context, key K) (value V, expiry time.Time, found bool, err error)
Get retrieves a value from a file.
func (*Store[K, V]) Location ¶
Location returns the full file path where a key is stored. Implements the Store interface Location() method.
func (*Store[K, V]) ValidateKey ¶
ValidateKey checks if a key is valid for file persistence. Since keys are hashed to SHA256, any characters are allowed. Only length is validated to prevent memory issues.
Source Files