5225c99cd7
Update module path to dappco.re/go/core/store, require dappco.re/go/core/log v0.1.0, and update all Go import paths and documentation references. Co-Authored-By: Virgil <virgil@lethean.io>
134 lines
5.3 KiB
Markdown
134 lines
5.3 KiB
Markdown
---
|
|
title: go-store
|
|
description: Group-namespaced SQLite key-value store with TTL expiry, namespace isolation, quota enforcement, and reactive event hooks.
|
|
---
|
|
|
|
# go-store
|
|
|
|
`go-store` is a group-namespaced key-value store backed by SQLite. It provides persistent or in-memory storage with optional TTL expiry, namespace isolation for multi-tenant use, quota enforcement, and a reactive event system for observing mutations.
|
|
|
|
The package has a single runtime dependency -- a pure-Go SQLite driver (`modernc.org/sqlite`). No CGO is required. It compiles and runs on all platforms that Go supports.
|
|
|
|
**Module path:** `dappco.re/go/core/store`
|
|
**Go version:** 1.26+
|
|
**Licence:** EUPL-1.2
|
|
|
|
## Quick Start
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
"time"
|
|
|
|
"dappco.re/go/core/store"
|
|
)
|
|
|
|
func main() {
|
|
// Open a store. Use ":memory:" for ephemeral data or a file path for persistence.
|
|
st, err := store.New("/tmp/app.db")
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
defer st.Close()
|
|
|
|
// Basic CRUD
|
|
st.Set("config", "theme", "dark")
|
|
val, _ := st.Get("config", "theme")
|
|
fmt.Println(val) // "dark"
|
|
|
|
// TTL expiry -- key disappears after the duration elapses
|
|
st.SetWithTTL("session", "token", "abc123", 24*time.Hour)
|
|
|
|
// Fetch all keys in a group
|
|
all, _ := st.GetAll("config")
|
|
fmt.Println(all) // map[theme:dark]
|
|
|
|
// Template rendering from stored values
|
|
st.Set("mail", "host", "smtp.example.com")
|
|
st.Set("mail", "port", "587")
|
|
out, _ := st.Render(`{{ .host }}:{{ .port }}`, "mail")
|
|
fmt.Println(out) // "smtp.example.com:587"
|
|
|
|
// Namespace isolation for multi-tenant use
|
|
sc, _ := store.NewScoped(st, "tenant-42")
|
|
sc.Set("prefs", "locale", "en-GB")
|
|
// Stored internally as group "tenant-42:prefs", key "locale"
|
|
|
|
// Quota enforcement
|
|
quota := store.QuotaConfig{MaxKeys: 100, MaxGroups: 5}
|
|
sq, _ := store.NewScopedWithQuota(st, "tenant-99", quota)
|
|
err = sq.Set("g", "k", "v") // returns store.ErrQuotaExceeded if limits are hit
|
|
|
|
// Watch for mutations via a buffered channel
|
|
w := st.Watch("config", "*")
|
|
defer st.Unwatch(w)
|
|
go func() {
|
|
for e := range w.Ch {
|
|
fmt.Printf("event: %s %s/%s\n", e.Type, e.Group, e.Key)
|
|
}
|
|
}()
|
|
|
|
// Or register a synchronous callback
|
|
unreg := st.OnChange(func(e store.Event) {
|
|
fmt.Printf("changed: %s\n", e.Key)
|
|
})
|
|
defer unreg()
|
|
}
|
|
```
|
|
|
|
## Package Layout
|
|
|
|
The entire package lives in a single Go package (`package store`) with three source files:
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `store.go` | Core `Store` type, CRUD operations (`Get`, `Set`, `SetWithTTL`, `Delete`, `DeleteGroup`), bulk queries (`GetAll`, `All`, `Count`, `CountAll`, `Groups`, `GroupsSeq`), string splitting helpers (`GetSplit`, `GetFields`), template rendering (`Render`), TTL expiry, background purge goroutine |
|
|
| `events.go` | `EventType` constants, `Event` struct, `Watcher` type, `Watch`/`Unwatch` subscription management, `OnChange` callback registration, internal `notify` dispatch |
|
|
| `scope.go` | `ScopedStore` wrapper for namespace isolation, `QuotaConfig` struct, `NewScoped`/`NewScopedWithQuota` constructors, quota enforcement logic |
|
|
|
|
Tests are organised in corresponding files:
|
|
|
|
| File | Covers |
|
|
|------|--------|
|
|
| `store_test.go` | CRUD, TTL, concurrency, edge cases, persistence, WAL verification |
|
|
| `events_test.go` | Watch/Unwatch, OnChange, event dispatch, wildcard matching, buffer overflow |
|
|
| `scope_test.go` | Namespace isolation, quota enforcement, cross-namespace behaviour |
|
|
| `coverage_test.go` | Defensive error paths (scan errors, schema conflicts, database corruption) |
|
|
| `bench_test.go` | Performance benchmarks for all major operations |
|
|
|
|
## Dependencies
|
|
|
|
**Runtime:**
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `modernc.org/sqlite` | Pure-Go SQLite driver (no CGO). Registered as a `database/sql` driver. |
|
|
|
|
**Test only:**
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `github.com/stretchr/testify` | Assertion helpers (`assert`, `require`) for tests. |
|
|
|
|
There are no other direct dependencies. The package uses only the Go standard library (`database/sql`, `context`, `sync`, `time`, `text/template`, `iter`, `errors`, `fmt`, `strings`, `regexp`, `slices`, `sync/atomic`) beyond the SQLite driver.
|
|
|
|
## Key Types
|
|
|
|
- **`Store`** -- the central type. Holds a `*sql.DB`, manages the background purge goroutine, and maintains the watcher/callback registry.
|
|
- **`ScopedStore`** -- wraps a `*Store` with an auto-prefixed namespace. Provides the same API surface with group names transparently prefixed.
|
|
- **`QuotaConfig`** -- configures per-namespace limits on total keys and distinct groups.
|
|
- **`Event`** -- describes a single store mutation (type, group, key, value, timestamp).
|
|
- **`Watcher`** -- a channel-based subscription to store events, created by `Watch`.
|
|
- **`KV`** -- a simple key-value pair struct, used by the `All` iterator.
|
|
|
|
## Sentinel Errors
|
|
|
|
- **`ErrNotFound`** -- returned by `Get` when the requested key does not exist or has expired.
|
|
- **`ErrQuotaExceeded`** -- returned by `ScopedStore.Set`/`SetWithTTL` when a namespace quota limit is reached.
|
|
|
|
## Further Reading
|
|
|
|
- [Architecture](architecture.md) -- storage layer internals, TTL model, event system, concurrency design
|
|
- [Development Guide](development.md) -- building, testing, benchmarks, contribution workflow
|