Documentation
¶
Overview ¶
Package meta is the unified metadata layer: record-granularity transactions over per-deployment engines (sqlite default, json legacy).
Index ¶
- Constants
- Variables
- func CheckWriteScope(ns, write string, mode CommitMode, relaxedOK bool) error
- type Broadcaster
- type Collection
- func (c *Collection[R]) Delete(ctx context.Context, w Writer, id string, opts ...WriteOpt) error
- func (c *Collection[R]) Get(ctx context.Context, r Reader, id string) (*R, error)
- func (c *Collection[R]) Insert(ctx context.Context, w Writer, id string, rec *R, opts ...WriteOpt) error
- func (c *Collection[R]) List(ctx context.Context, r Reader) (map[string]*R, error)
- func (c *Collection[R]) Replace(ctx context.Context, w Writer, id string, rec *R, opts ...WriteOpt) error
- func (c *Collection[R]) Scan(ctx context.Context, r Reader, fn func(id string, rec *R) error) error
- func (c *Collection[R]) Upsert(ctx context.Context, w Writer, id string, rec *R, opts ...WriteOpt) error
- type CommitMode
- type Log
- type NamedTx
- func (x *NamedTx[R]) NameDel(name string) error
- func (x *NamedTx[R]) NameDelIfOwned(name, id string) error
- func (x *NamedTx[R]) NameGet(name string) (string, bool, error)
- func (x *NamedTx[R]) NameSet(name, id string, opts ...WriteOpt) error
- func (x *NamedTx[R]) Resolve(ref string, notFound error) (string, error)
- func (x *NamedTx[R]) ResolveMany(refs []string, notFound error) ([]string, error)
- type Reader
- type RecordTx
- func (x *RecordTx[R]) All() (map[string]*R, error)
- func (x *RecordTx[R]) Del(id string) error
- func (x *RecordTx[R]) Get(id string) (*R, error)
- func (x *RecordTx[R]) Put(id string, rec *R, opts ...WriteOpt) error
- func (x *RecordTx[R]) Reader() Reader
- func (x *RecordTx[R]) Scan(fn func(id string, rec *R) error) error
- func (x *RecordTx[R]) Writer() Writer
- type Scope
- type Seq
- type Store
- type WriteOpt
- type Writer
Constants ¶
const ( // CommitDurable fsyncs on commit; the default durability class. CommitDurable CommitMode = iota // CommitRelaxed may lose the un-checkpointed tail on power loss; the store stays consistent. CommitRelaxed // RelaxedOK marks one write as acceptable to lose, permitting it inside a CommitRelaxed transaction. RelaxedOK WriteOpt = 1 )
Variables ¶
var ( ErrNotFound = errors.New("record not found") ErrConflict = errors.New("record conflict") ErrBusy = errors.New("store busy") ErrCorrupt = errors.New("store corrupt") ErrNoSpace = errors.New("no space left on store") ErrIO = errors.New("store io error") // ErrDurabilityContract reports a durable-default write inside a CommitRelaxed transaction (clause 5). ErrDurabilityContract = errors.New("durable-default write in relaxed transaction") // ErrScope reports access to a namespace the transaction did not declare (clause 2). ErrScope = errors.New("namespace not in transaction scope") )
Functions ¶
func CheckWriteScope ¶ added in v0.5.5
func CheckWriteScope(ns, write string, mode CommitMode, relaxedOK bool) error
CheckWriteScope enforces write scope (clause 2) and durability (clause 5) for one write.
Types ¶
type Broadcaster ¶
type Broadcaster struct {
// contains filtered or unexported fields
}
Broadcaster is the engine-shared half of an Events notifier: it owns the subscriber set and the debounce/poll loop, funneling every trigger into the engine's check func — which calls Broadcast only when state moved.
func NewBroadcaster ¶
func NewBroadcaster(watcher *fsnotify.Watcher) *Broadcaster
NewBroadcaster wraps an fsnotify watcher the engine has already populated.
func (*Broadcaster) Broadcast ¶
func (b *Broadcaster) Broadcast()
Broadcast signals every subscriber without blocking.
func (*Broadcaster) Run ¶
func (b *Broadcaster) Run(check func(), extra <-chan struct{})
Run is the notifier goroutine body: watcher events are debounced, watcher errors, the optional extra trigger and a safety poll check immediately.
func (*Broadcaster) Subscribe ¶
func (b *Broadcaster) Subscribe() (chan struct{}, func())
Subscribe registers a coalescing signal channel; release is idempotent.
type Collection ¶
type Collection[R any] struct { // contains filtered or unexported fields }
Collection is a typed record set inside one namespace table; reads hand back detached values, persisting a change requires Replace.
func NewCollection ¶
func NewCollection[R any](s Store, ns, table string) *Collection[R]
NewCollection binds a Collection to a (namespace, table) pair on s.
func (*Collection[R]) Delete ¶
Delete removes id; an absent id is idempotent success, never ErrNotFound.
func (*Collection[R]) Insert ¶
func (c *Collection[R]) Insert(ctx context.Context, w Writer, id string, rec *R, opts ...WriteOpt) error
Insert adds a new record; an existing id is ErrConflict.
func (*Collection[R]) Replace ¶
func (c *Collection[R]) Replace(ctx context.Context, w Writer, id string, rec *R, opts ...WriteOpt) error
Replace overwrites an existing record; an absent id is ErrNotFound.
type Log ¶
type Log[R any] struct { // contains filtered or unexported fields }
Log is an append-only typed sequence over one namespace table; the cursor shares the table under a reserved id, so a rollback releases its number.
type NamedTx ¶
NamedTx is RecordTx plus an explicit name→id index shared by cocoon subsystems; name entries are claimed and released explicitly.
func NewNamedTx ¶
func NewNamedTx[R any](ctx context.Context, s Store, ns, recordsTable, namesTable string, r Reader, w Writer) *NamedTx[R]
NewNamedTx binds the pattern to (ns, recordsTable, namesTable); w is nil in read-only transactions.
func (*NamedTx[R]) NameDelIfOwned ¶
NameDelIfOwned removes name's mapping only while it still points at id; "" is a no-op.
type Reader ¶
type Reader interface {
GetRaw(ctx context.Context, ns, table, id string) (json.RawMessage, bool, error)
// ScanRaw yields records in the engine's stable order (json: insertion).
ScanRaw(ctx context.Context, ns, table string, fn func(id string, raw json.RawMessage) error) error
}
Reader is the raw read SPI transactions hand to Collection; values returned are detached from engine state.
type RecordTx ¶
type RecordTx[R any] struct { // contains filtered or unexported fields }
RecordTx is the id→record map view of one table inside a transaction: Get mirrors map lookup (nil when absent), Put is an upsert.
func NewRecordTx ¶
func NewRecordTx[R any](ctx context.Context, s Store, ns, table string, r Reader, w Writer) *RecordTx[R]
NewRecordTx binds the view to (ns, table); w is nil in read-only transactions.
type Scope ¶
Scope declares, before the closure runs, every namespace a transaction touches: Write is the single namespace it may modify, Read the others it may read. Engines acquire all of them in one fixed global order before invoking the closure.
type Seq ¶
type Seq uint64
Seq numbers committed log entries: unique and strictly increasing. Rolled-back numbers may be reused, and engines may leave gaps.
type Store ¶
type Store interface {
// View runs fn over a consistent snapshot of the given namespaces.
View(ctx context.Context, nss []string, fn func(Reader) error) error
// Update runs fn in a serializable transaction writing sc.Write; commit follows mode.
Update(ctx context.Context, sc Scope, mode CommitMode, fn func(Writer) error) error
// Events returns a coalesced change signal; release unsubscribes.
Events(ctx context.Context) (<-chan struct{}, func(), error)
Close() error
}
Store is the engine-neutral transaction boundary. Closures must be pure and retryable: they may run more than once, all effects go through the handle, and results are published only after the transaction returns nil.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contracttest is the engine-agnostic meta contract suite: every engine must pass it unmodified.
|
Package contracttest is the engine-agnostic meta contract suite: every engine must pass it unmodified. |
|
Package json is the meta engine over today's per-namespace JSON files: same formats, same .prev crash story, same flocks (design §8).
|
Package json is the meta engine over today's per-namespace JSON files: same formats, same .prev crash story, same flocks (design §8). |
|
Package sqlite is the meta scale engine: one WAL database, namespace = table group, generic (id, data) rows per root-declared table (§2-§4, v2.28).
|
Package sqlite is the meta scale engine: one WAL database, namespace = table group, generic (id, data) rows per root-declared table (§2-§4, v2.28). |
|
Package tombstone is the §5 phase protocol: leased rolls back, deleting rolls forward, every mutation fenced by the holder's lease id.
|
Package tombstone is the §5 phase protocol: leased rolls back, deleting rolls forward, every mutation fenced by the holder's lease id. |