feat: add persistent cache with auto-refresh support (#3)

Implement generic persistent cache using Otter pkg
with the following features:

* Cache SSLBL records to
  "~/.cache/sebel/records.gob".
* Embed `otter.Cache` directly for full API
  access.
* Add `DataRefreshInterval` option for background
  refresh.
* Best-effort persistence (graceful fallback in
  containers).

The cache package is generic (`Cache[K, V]`) and
low-level, exposing `otter.Options` for full
configurability.

Add `Close()` method to `Sebel` for stopping
background goroutine.

Signed-off-by: Dwi Siswanto <git@dw1.io>

Author: dwisiswant0

README.md

@@ -16,10 +16,11 @@ import "github.com/teler-sh/sebel"
 // ...
 
 s := sebel.New(Options{/* ... */})
+defer s.Close() // Stop background refresh if enabled
 ```
 
 > [!NOTE]
-> The `Options` parameter is optional. Currently, the only supported option is disabling the SSL blacklist. See [TODO](#TODO).
+> The `Options` parameter is optional. See [Options](#options) for available configuration.
 
 ### Examples
 
@@ -28,6 +29,7 @@ Next, set the transport for the HTTP client you are using:
 ```go
 // initialize Sebel (fetch SSLBL data)
 s := sebel.New()
+defer s.Close()
 
 client := &http.Client{
     Transport: s.RoundTripper(http.DefaultTransport),
@@ -79,11 +81,27 @@ if err != nil && sebel.IsBlacklist(err) {
 }
 ```
 
+#### Background Refresh
+
+To keep the SSLBL data up-to-date automatically:
+
+```go
+s := sebel.New(sebel.Options{
+    DataRefreshInterval: 5 * time.Minute,
+})
+defer s.Close() // Important: stop the background goroutine
+
+client := &http.Client{
+    Transport: s.RoundTripper(http.DefaultTransport),
+}
+```
+
 These examples demonstrate various ways to set up Sebel and integrate it with HTTP clients for SSL/TLS certificate checks.
 
 ## TODO
 
-* [ ] Caching SSLBL data under user-specific cache directory.
+* [x] Caching SSLBL data under user-specific cache directory.
+* [x] Background refresh to keep data up-to-date.
 * [x] Add `io.Writer` option.
 * [ ] ~Add `CheckIP` method.~ Not planned, instead:
 * [x] Add `CheckHost` method.

go.mod

@@ -2,6 +2,12 @@ module github.com/teler-sh/sebel
 
 go 1.24.0
 
-require github.com/samber/lo v1.52.0
+require (
+	github.com/maypok86/otter/v2 v2.2.1
+	github.com/samber/lo v1.52.0
+)
 
-require golang.org/x/text v0.32.0 // indirect
+require (
+	golang.org/x/sys v0.34.0 // indirect
+	golang.org/x/text v0.22.0 // indirect
+)

go.sum

@@ -1,4 +1,16 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/maypok86/otter/v2 v2.2.1 h1:hnGssisMFkdisYcvQ8L019zpYQcdtPse+g0ps2i7cfI=
+github.com/maypok86/otter/v2 v2.2.1/go.mod h1:1NKY9bY+kB5jwCXBJfE59u+zAwOt6C7ni1FTlFFMqVs=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/samber/lo v1.52.0 h1:Rvi+3BFHES3A8meP33VPAxiBZX/Aws5RxrschYGjomw=
 github.com/samber/lo v1.52.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
-golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
-golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
+golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM=
+golang.org/x/text v0.22.0/go.mod h1:YRoo4H8PVmsu+E3Ou7cqLVH8oXWIHVoX0jqUWALQhfY=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/cache/cache.go

@@ -0,0 +1,126 @@
+// Package cache provides a generic persistent cache using Otter.
+package cache
+
+import (
+	"os"
+	"sync"
+	"time"
+
+	"github.com/maypok86/otter/v2"
+)
+
+// Options configures a Cache instance.
+// It embeds otter.Options and adds persistence support.
+type Options[K comparable, V any] struct {
+	otter.Options[K, V]
+
+	// Filepath is the path for persisting the cache.
+	// If empty, persistence is disabled.
+	Filepath string
+}
+
+// Cache is a generic persistent cache that embeds [otter.Cache].
+// It adds persistence and background refresh capabilities.
+type Cache[K comparable, V any] struct {
+	*otter.Cache[K, V]
+
+	cacheFilepath string
+
+	refreshStop chan struct{}
+	refreshOnce sync.Once
+	refreshMu   sync.Mutex
+}
+
+// New creates a new [Cache] instance with the given options.
+func New[K comparable, V any](opts *Options[K, V]) (*Cache[K, V], error) {
+	otterCache, err := otter.New(&opts.Options)
+	if err != nil {
+		return nil, err
+	}
+
+	c := &Cache[K, V]{
+		Cache:         otterCache,
+		cacheFilepath: opts.Filepath,
+	}
+
+	if c.cacheFilepath != "" {
+		if _, err := os.Stat(c.cacheFilepath); err == nil {
+			_ = otter.LoadCacheFromFile(c.Cache, c.cacheFilepath)
+		}
+	}
+
+	return c, nil
+}
+
+// Must is like [New] but panics on error.
+func Must[K comparable, V any](opts *Options[K, V]) *Cache[K, V] {
+	c, err := New(opts)
+	if err != nil {
+		panic(err)
+	}
+
+	return c
+}
+
+// Save persists the cache to disk.
+// Returns nil if persistence is not configured.
+func (c *Cache[K, V]) Save() error {
+	if c.cacheFilepath == "" {
+		return nil
+	}
+
+	return otter.SaveCacheToFile(c.Cache, c.cacheFilepath)
+}
+
+// Load loads the cache from disk.
+// Returns nil if persistence is not configured.
+func (c *Cache[K, V]) Load() error {
+	if c.cacheFilepath == "" {
+		return nil
+	}
+
+	return otter.LoadCacheFromFile(c.Cache, c.cacheFilepath)
+}
+
+// FetchFunc is a function that fetches fresh data and populates the cache.
+type FetchFunc func() error
+
+// StartBackgroundRefresh starts a goroutine that periodically calls fetchFn.
+// Call StopBackgroundRefresh to stop.
+func (c *Cache[K, V]) StartBackgroundRefresh(interval time.Duration, fetchFn FetchFunc) {
+	if interval <= 0 || fetchFn == nil {
+		return
+	}
+
+	c.refreshOnce.Do(func() {
+		c.refreshStop = make(chan struct{})
+		go c.backgroundRefresh(interval, fetchFn)
+	})
+}
+
+// StopBackgroundRefresh stops the background refresh goroutine.
+func (c *Cache[K, V]) StopBackgroundRefresh() {
+	c.refreshMu.Lock()
+	defer c.refreshMu.Unlock()
+
+	if c.refreshStop != nil {
+		close(c.refreshStop)
+		c.refreshStop = nil
+		c.refreshOnce = sync.Once{}
+	}
+}
+
+// backgroundRefresh periodically calls fetchFn.
+func (c *Cache[K, V]) backgroundRefresh(interval time.Duration, fetchFn FetchFunc) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			_ = fetchFn()
+		case <-c.refreshStop:
+			return
+		}
+	}
+}

internal/cache/cache_test.go

@@ -0,0 +1,152 @@
+package cache
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/maypok86/otter/v2"
+)
+
+func TestCacheSetAndGet(t *testing.T) {
+	c := newTestCache[string, string](t)
+
+	c.Set("key1", "value1")
+
+	got, ok := c.GetIfPresent("key1")
+	if !ok {
+		t.Fatal("key not found in cache")
+	}
+
+	if got != "value1" {
+		t.Errorf("value mismatch: got %s, want %s", got, "value1")
+	}
+}
+
+func TestCacheSize(t *testing.T) {
+	c := newTestCache[string, int](t)
+
+	c.Set("a", 1)
+	c.Set("b", 2)
+	c.Set("c", 3)
+
+	if c.EstimatedSize() != 3 {
+		t.Errorf("expected size 3, got %d", c.EstimatedSize())
+	}
+}
+
+func TestCacheInvalidate(t *testing.T) {
+	c := newTestCache[string, string](t)
+
+	c.Set("key1", "value1")
+	c.Set("key2", "value2")
+
+	if c.EstimatedSize() == 0 {
+		t.Fatal("cache should have entries before invalidate")
+	}
+
+	c.InvalidateAll()
+
+	if c.EstimatedSize() != 0 {
+		t.Errorf("cache should be empty after invalidate, got size %d", c.EstimatedSize())
+	}
+}
+
+func TestCachePersistence(t *testing.T) {
+	tmpDir := t.TempDir()
+	tmpFile := filepath.Join(tmpDir, "test.gob")
+
+	// Create and populate cache
+	c1, err := New(&Options[string, string]{Filepath: tmpFile})
+	if err != nil {
+		t.Fatalf("New failed: %v", err)
+	}
+
+	c1.Set("persist1", "value1")
+	c1.Set("persist2", "value2")
+
+	if err := c1.Save(); err != nil {
+		t.Fatalf("Save failed: %v", err)
+	}
+
+	// Verify file was created
+	if _, err := os.Stat(tmpFile); os.IsNotExist(err) {
+		t.Fatal("cache file was not created")
+	}
+
+	// Create new cache and load
+	c2, err := New(&Options[string, string]{Filepath: tmpFile})
+	if err != nil {
+		t.Fatalf("New failed: %v", err)
+	}
+
+	if err := c2.Load(); err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	// Verify data was loaded
+	if got, ok := c2.GetIfPresent("persist1"); !ok || got != "value1" {
+		t.Errorf("persist1: got %q, want %q", got, "value1")
+	}
+	if got, ok := c2.GetIfPresent("persist2"); !ok || got != "value2" {
+		t.Errorf("persist2: got %q, want %q", got, "value2")
+	}
+}
+
+func TestCacheAll(t *testing.T) {
+	c := newTestCache[string, int](t)
+
+	c.Set("a", 1)
+	c.Set("b", 2)
+	c.Set("c", 3)
+
+	count := 0
+	sum := 0
+	for _, v := range c.All() {
+		count++
+		sum += v
+	}
+
+	if count != 3 {
+		t.Errorf("expected 3 iterations, got %d", count)
+	}
+	if sum != 6 {
+		t.Errorf("expected sum 6, got %d", sum)
+	}
+}
+
+func TestCacheWithOtterOptions(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	c, err := New(&Options[string, string]{
+		Options: otter.Options[string, string]{
+			InitialCapacity: 1000,
+		},
+		Filepath: filepath.Join(tmpDir, "test.gob"),
+	})
+	if err != nil {
+		t.Fatalf("New failed: %v", err)
+	}
+
+	c.Set("key", "value")
+
+	got, ok := c.GetIfPresent("key")
+	if !ok || got != "value" {
+		t.Errorf("got %q, want %q", got, "value")
+	}
+}
+
+// newTestCache creates a cache with a temp directory for testing.
+func newTestCache[K comparable, V any](t *testing.T) *Cache[K, V] {
+	t.Helper()
+
+	tmpDir := t.TempDir()
+	c, err := New(&Options[K, V]{
+		Filepath: filepath.Join(tmpDir, "test.gob"),
+	})
+	if err != nil {
+		t.Fatalf("failed to create test cache: %v", err)
+	}
+
+	return c
+}

internal/cache/utils.go

@@ -0,0 +1,27 @@
+package cache
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// BuildCacheFilepath constructs a cache filepath in the user's cache directory.
+//
+// Returns empty string if the path cannot be created.
+func BuildCacheFilepath(dir, file string) string {
+	if dir == "" || file == "" {
+		return ""
+	}
+
+	userCacheDir, err := os.UserCacheDir()
+	if err != nil {
+		return ""
+	}
+
+	fullDir := filepath.Join(userCacheDir, dir)
+	if err := os.MkdirAll(fullDir, 0o755); err != nil {
+		return ""
+	}
+
+	return filepath.Join(fullDir, file)
+}