meta

package
v0.5.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 27, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package meta is the unified metadata layer: record-granularity transactions over per-deployment engines (sqlite default, json legacy).

Index

Constants

View Source
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

View Source
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) Stop

func (b *Broadcaster) Stop()

Stop ends Run and closes the watcher.

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

func (c *Collection[R]) Delete(ctx context.Context, w Writer, id string, opts ...WriteOpt) error

Delete removes id; an absent id is idempotent success, never ErrNotFound.

func (*Collection[R]) Get

func (c *Collection[R]) Get(ctx context.Context, r Reader, id string) (*R, error)

Get returns a detached copy of id, or 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]) List

func (c *Collection[R]) List(ctx context.Context, r Reader) (map[string]*R, error)

List returns all records detached; intended for small namespaces.

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.

func (*Collection[R]) Scan

func (c *Collection[R]) Scan(ctx context.Context, r Reader, fn func(id string, rec *R) error) error

Scan yields detached records in the engine's stable order; fn errors abort and propagate.

func (*Collection[R]) Upsert

func (c *Collection[R]) Upsert(ctx context.Context, w Writer, id string, rec *R, opts ...WriteOpt) error

Upsert inserts or replaces id (map-assignment semantics).

type CommitMode

type CommitMode uint8

CommitMode selects a transaction's durability class.

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.

func NewLog

func NewLog[R any](ns, table string) *Log[R]

NewLog binds a Log to a (namespace, table) pair.

func (*Log[R]) Append

func (l *Log[R]) Append(ctx context.Context, w Writer, rec *R, opts ...WriteOpt) (Seq, error)

Append assigns the next Seq and writes rec under it.

func (*Log[R]) Scan

func (l *Log[R]) Scan(ctx context.Context, r Reader, after Seq, fn func(Seq, *R) error) error

Scan streams committed entries with Seq strictly after the cursor, in order.

type NamedTx

type NamedTx[R any] struct {
	*RecordTx[R]
	// contains filtered or unexported fields
}

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]) NameDel

func (x *NamedTx[R]) NameDel(name string) error

NameDel mirrors delete(names, name).

func (*NamedTx[R]) NameDelIfOwned

func (x *NamedTx[R]) NameDelIfOwned(name, id string) error

NameDelIfOwned removes name's mapping only while it still points at id; "" is a no-op.

func (*NamedTx[R]) NameGet

func (x *NamedTx[R]) NameGet(name string) (string, bool, error)

NameGet mirrors names[name] lookup.

func (*NamedTx[R]) NameSet

func (x *NamedTx[R]) NameSet(name, id string, opts ...WriteOpt) error

NameSet mirrors names[name] = id.

func (*NamedTx[R]) Resolve

func (x *NamedTx[R]) Resolve(ref string, notFound error) (string, error)

Resolve ports utils.ResolveRef: exact ID, then name, then ID prefix of at least three characters; notFound is the subsystem's sentinel.

func (*NamedTx[R]) ResolveMany

func (x *NamedTx[R]) ResolveMany(refs []string, notFound error) ([]string, error)

ResolveMany ports utils.ResolveRefs: batch resolve with dedup.

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.

func (*RecordTx[R]) All

func (x *RecordTx[R]) All() (map[string]*R, error)

All returns every record detached, keyed by id.

func (*RecordTx[R]) Del

func (x *RecordTx[R]) Del(id string) error

Del mirrors delete(items, id).

func (*RecordTx[R]) Get

func (x *RecordTx[R]) Get(id string) (*R, error)

Get mirrors items[id]: nil when absent.

func (*RecordTx[R]) Put

func (x *RecordTx[R]) Put(id string, rec *R, opts ...WriteOpt) error

Put mirrors items[id] = rec (upsert).

func (*RecordTx[R]) Reader

func (x *RecordTx[R]) Reader() Reader

Reader exposes the transaction's read handle for satellite tables.

func (*RecordTx[R]) Scan

func (x *RecordTx[R]) Scan(fn func(id string, rec *R) error) error

Scan yields detached records.

func (*RecordTx[R]) Writer

func (x *RecordTx[R]) Writer() Writer

Writer exposes the transaction's write handle for satellite tables.

type Scope

type Scope struct {
	Write string
	Read  []string
}

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.

type WriteOpt

type WriteOpt uint8

WriteOpt modifies a single write; see RelaxedOK.

type Writer

type Writer interface {
	Reader
	PutRaw(ctx context.Context, ns, table, id string, raw json.RawMessage, relaxedOK bool) error
	DeleteRaw(ctx context.Context, ns, table, id string, relaxedOK bool) error
}

Writer is the raw write SPI; relaxedOK mirrors the per-op RelaxedOK opt-in.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL