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 ¶ added in v1.3.0
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 gob encoding.
func New ¶
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. This is useful for testing with temporary directories.
func (*Store[K, V]) Cleanup ¶ added in v1.3.0
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 ¶ added in v1.3.0
Flush removes all entries from the file-based cache. Returns the number of entries removed and any errors encountered.
func (*Store[K, V]) Get ¶ added in v1.3.0
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]) Len ¶ added in v1.3.0
Len returns the number of entries in the file-based cache.
func (*Store[K, V]) Location ¶ added in v1.3.0
Location returns the full file path where a key is stored. Implements the Store interface Location() method.
func (*Store[K, V]) ValidateKey ¶ added in v1.3.0
ValidateKey checks if a key is valid for file persistence. Keys must be alphanumeric, dash, underscore, period, or colon, and max 127 characters.
Source Files