cachedfs

README

Cached FS

A drop-in replacement for fs.FS that serves files from disk with in-memory caching and background refresh.

Features

• Pre-caches all files at startup
• Stale-while-revalidate - serves cached content immediately, refreshes in background
• SIGHUP handling - send SIGHUP to force immediate recheck of all files
• Optional fsnotify - automatically recheck files when they change on disk
• Implements fs.FS - works with http.FileServer, template.ParseFS, etc.

Installation

go get github.com/atikayda/cachedfs

Usage

package main

import (
    "log"
    "net/http"

    cachedfs "github.com/atikayda/cachedfs"
)

func main() {
    cfs, err := cachedfs.New("./static")
    if err != nil {
        log.Fatal(err)
    }
    defer cfs.Close()

    http.Handle("/", http.FileServer(http.FS(cfs)))
    http.ListenAndServe(":8080", nil)
}

With Options

cfs, err := cachedfs.New("./static",
    cachedfs.WithCacheTTL(10 * time.Minute),       // How long before marking stale (default: 5m)
    cachedfs.WithRecheckInterval(5 * time.Minute), // Background recheck interval (default: 5m)
    cachedfs.WithFSNotify(),                       // Enable filesystem notifications
    cachedfs.WithInotifyDebounce(3 * time.Second), // Debounce for fs events (default: 5s)
    cachedfs.WithoutSIGHUP(),                      // Disable SIGHUP handler
)

Subdirectories

sub, err := cfs.Sub("assets")
http.Handle("/assets/", http.StripPrefix("/assets/", http.FileServer(http.FS(sub))))

Force Refresh

cfs.ForceRecheck()

Or send SIGHUP to the process: kill -HUP <pid>

How It Works

1. On startup, walks the directory tree and caches all files in memory
2. Open() returns cached content immediately
3. If cache entry is older than TTL, schedules background recheck
4. Background recheck stats the file - if mtime/size unchanged, just updates timestamp
5. If file changed, reads new content and updates cache
6. SIGHUP triggers immediate recheck of all entries
7. With fsnotify enabled, file changes trigger debounced rechecks

License

The Unlicense

Documentation

Index

• Constants
• type CachedFS
  • func New(root string, opts ...Option) (*CachedFS, error)
  • func (c *CachedFS) Close() error
  • func (c *CachedFS) ForceRecheck()
  • func (c *CachedFS) Open(name string) (fs.File, error)
  • func (c *CachedFS) Sub(dir string) (fs.FS, error)
• type FSNotifyWatcher
  • func (w *FSNotifyWatcher) Close() error
• type Option
  • func WithCacheTTL(ttl time.Duration) Option
  • func WithFSNotify() Option
  • func WithInotifyDebounce(debounce time.Duration) Option
  • func WithRecheckInterval(interval time.Duration) Option
  • func WithoutSIGHUP() Option

Constants

const (
	DefaultCacheTTL        = 5 * time.Minute
	DefaultRecheckInterval = 5 * time.Minute
	DefaultInotifyDebounce = 5 * time.Second
)

Types

type CachedFS

type CachedFS struct {
	// contains filtered or unexported fields
}

CachedFS provides a cached view of a filesystem directory that implements fs.FS. It pre-caches all files at startup and serves them from memory, rechecking files periodically and refreshing stale entries in the background without blocking reads.

func New

func New(root string, opts ...Option) (*CachedFS, error)

New creates a new CachedFS rooted at the given directory. It pre-caches all files, starts background recheck, and sets up SIGHUP handling.

func (*CachedFS) Close

func (c *CachedFS) Close() error

Close stops all background goroutines and releases resources.

func (*CachedFS) ForceRecheck

func (c *CachedFS) ForceRecheck()

ForceRecheck triggers an immediate recheck of all cached files.

func (*CachedFS) Open

func (c *CachedFS) Open(name string) (fs.File, error)

Open implements fs.FS. It returns a cached file without blocking on refresh.

func (*CachedFS) Sub

func (c *CachedFS) Sub(dir string) (fs.FS, error)

Sub implements fs.SubFS.

type FSNotifyWatcher

type FSNotifyWatcher struct {
	// contains filtered or unexported fields
}

FSNotifyWatcher wraps fsnotify to provide filesystem change notifications.

func (*FSNotifyWatcher) Close

func (w *FSNotifyWatcher) Close() error

type Option

type Option func(*CachedFS)

Option configures a CachedFS instance.

func WithCacheTTL

func WithCacheTTL(ttl time.Duration) Option

WithCacheTTL sets how long before a cached entry is considered stale. Default is 5 minutes.

func WithFSNotify

func WithFSNotify() Option

WithFSNotify enables filesystem notifications via fsnotify. This will trigger rechecks when files change, in addition to the periodic recheck.

func WithInotifyDebounce

func WithInotifyDebounce(debounce time.Duration) Option

WithInotifyDebounce sets the delay before processing inotify events. Default is 5 seconds.

func WithRecheckInterval

func WithRecheckInterval(interval time.Duration) Option

WithRecheckInterval sets how often the background recheck runs. Default is 5 minutes.

func WithoutSIGHUP

func WithoutSIGHUP() Option

WithoutSIGHUP disables the SIGHUP handler. By default, SIGHUP triggers a full recheck of all cached files.