Documentation
¶
Overview ¶
Package metadatadb provides an eventually consistent metadata store for coordinating state across cachew replicas. Mutations are applied to local state immediately and synced periodically to a shared backend. Last flush wins — the lock serialises all writes.
Index ¶
- Variables
- func Register[Config any, B Backend](r *Registry, id, description string, factory Factory[Config, B])
- func RegisterMemory(r *Registry)
- func RegisterS3(r *Registry, clientProvider s3client.ClientProvider)
- type Backend
- type Factory
- type Int
- type IntAdd
- type IntDiv
- type IntGet
- type IntMap
- func (m *IntMap[K]) Add(key K, delta int64)
- func (m *IntMap[K]) Delete(key K)
- func (m *IntMap[K]) Div(key K, divisor int64)
- func (m *IntMap[K]) Entries() map[K]int64
- func (m *IntMap[K]) Get(key K) int64
- func (m *IntMap[K]) Keys() []K
- func (m *IntMap[K]) Mul(key K, factor int64)
- func (m *IntMap[K]) Set(key K, value int64)
- type IntMapAdd
- type IntMapDelete
- type IntMapDiv
- type IntMapEntries
- type IntMapGet
- type IntMapKeys
- type IntMapMul
- type IntMapSet
- type IntMul
- type IntSet
- type List
- type ListAppend
- type ListEntries
- type ListLen
- type Map
- type MapDelete
- type MapEntries
- type MapGet
- type MapKeys
- type MapSet
- type MemoryBackend
- type MemoryConfig
- type Namespace
- type Op
- type ReadOp
- type Registry
- type S3Backend
- type S3BackendConfig
- type Scalar
- type ScalarDelete
- type ScalarGet
- type ScalarSet
- type Set
- type SetAdd
- type SetContains
- type SetMembers
- type SetRemove
- type Store
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("metadata backend not found")
ErrNotFound is returned when a metadata backend is not found.
Functions ¶
func Register ¶
func Register[Config any, B Backend](r *Registry, id, description string, factory Factory[Config, B])
Register a metadata backend factory function.
func RegisterMemory ¶
func RegisterMemory(r *Registry)
RegisterMemory registers the in-memory metadata backend.
func RegisterS3 ¶
func RegisterS3(r *Registry, clientProvider s3client.ClientProvider)
RegisterS3 registers the S3 metadata backend. The clientProvider supplies the shared minio client constructed from the global s3 config block.
Types ¶
type Backend ¶
type Backend interface {
// Apply applies one or more write operations to the given namespace.
Apply(ctx context.Context, namespace string, ops ...Op) error
// Query executes a read query and unmarshals the result into target.
// Target must be a pointer to the expected result type.
Query(ctx context.Context, namespace string, q ReadOp, target any) error
// Flush forces pending state to be persisted for the given namespace.
Flush(ctx context.Context, namespace string) error
// Close shuts down the backend, flushing any pending state.
Close(ctx context.Context) error
}
Backend is the pluggable storage layer for the metadata store. Implementations handle write operations (Apply), read queries (Query), and persistence (Flush).
type Factory ¶
Factory is a function that creates a new Backend from the given hcl-tagged configuration struct.
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int is an integer with arithmetic operations.
type IntGet ¶
type IntGet struct{ Key string }
IntGet reads an integer value. Returns int64 (zero if absent).
type IntMap ¶
type IntMap[K comparable] struct { // contains filtered or unexported fields }
IntMap is a keyed collection of integer values supporting atomic increment.
type IntMapDelete ¶
IntMapDelete removes a key from an integer map.
type IntMapEntries ¶
type IntMapEntries struct{ Key string }
IntMapEntries returns all entries in an integer map.
type IntMapKeys ¶
type IntMapKeys struct{ Key string }
IntMapKeys returns all keys in an integer map.
type List ¶
type List[V any] struct { // contains filtered or unexported fields }
List is an append-only ordered collection.
type ListAppend ¶
ListAppend appends a value to a list.
type ListEntries ¶
type ListEntries struct{ Key string }
ListEntries returns all list entries as []any.
type Map ¶
type Map[K comparable, V any] struct { // contains filtered or unexported fields }
Map is a keyed collection of values. Last write per key wins.
type MemoryBackend ¶
type MemoryBackend struct {
// contains filtered or unexported fields
}
MemoryBackend is an in-memory Backend for testing and single-instance deployments. Ops are applied directly — there is no sync or persistence.
func NewMemoryBackend ¶
func NewMemoryBackend() *MemoryBackend
type MemoryConfig ¶
type MemoryConfig struct{}
MemoryConfig is the configuration for the in-memory metadata backend.
type Namespace ¶
type Namespace struct {
// contains filtered or unexported fields
}
Namespace is a scoped collection of named data structures.
type Op ¶
type Op interface {
// contains filtered or unexported methods
}
Op is a write operation applied to the metadata store. Concrete types form a closed set (sum type) — backends handle each variant via exhaustive type switch.
type ReadOp ¶
type ReadOp interface {
// contains filtered or unexported methods
}
ReadOp is a read query against the metadata store. Like Op, concrete types form a closed set dispatched by the backend.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds registered metadata backend factories.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates a new metadata backend registry.
func (*Registry) Create ¶
func (r *Registry) Create(ctx context.Context, name string, config *hcl.Block, vars map[string]string) (Backend, error)
Create a new Backend from the given name and configuration.
Returns ErrNotFound if the backend is not found.
type S3Backend ¶
type S3Backend struct {
// contains filtered or unexported fields
}
S3Backend stores metadata state as JSON objects in S3 with periodic sync. Writes are applied to local state immediately and queued for the next flush. Locking uses a separate lock object with TTL-based expiry for stale lock recovery. The idempotence token maps to the S3 object ETag.
func NewS3Backend ¶
func NewS3Backend(ctx context.Context, clientProvider s3client.ClientProvider, config S3BackendConfig) (*S3Backend, error)
type S3BackendConfig ¶
type S3BackendConfig struct {
Bucket string `hcl:"bucket" help:"S3 bucket name."`
LockTTL time.Duration `hcl:"lock-ttl,optional" help:"TTL for namespace locks." default:"30s"`
SyncInterval time.Duration `hcl:"sync-interval,optional" help:"Interval between periodic syncs." default:"30s"`
}
S3BackendConfig configures the S3 metadata backend.
type Scalar ¶
type Scalar[V any] struct { // contains filtered or unexported fields }
Scalar is a single value. Last write wins.
type ScalarGet ¶
type ScalarGet struct{ Key string }
ScalarGet reads a scalar value. Returns (value, true) or (nil, false).
type Set ¶
type Set[V comparable] struct { // contains filtered or unexported fields }
Set is an unordered collection of unique members.
type SetContains ¶
SetContains checks whether a member exists in a set. Returns bool.