storage

package
v2.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 29, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package storage defines the transactional persistence boundary used by Floret. Backends store opaque namespaced bytes; Floret owns every domain schema and index encoded into those bytes.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound reports that a key does not exist in a namespace.
	ErrNotFound = errors.New("storage record not found")
	// ErrClosed reports an operation attempted on a closed backend.
	ErrClosed = errors.New("storage backend closed")
	// ErrConflict reports that a transaction could not commit because another
	// transaction committed after its snapshot was taken.
	ErrConflict = errors.New("storage transaction conflict")
	// ErrInvalidArgument reports a request outside the storage contract.
	ErrInvalidArgument = errors.New("invalid storage argument")
	// ErrTransactionClosed reports use of a transaction outside its callback.
	ErrTransactionClosed = errors.New("storage transaction closed")
	// ErrMigrationRequired reports an exact legacy storage schema that must be
	// migrated explicitly before it can be opened as a Backend.
	ErrMigrationRequired = errors.New("storage migration required")
)
View Source
var (
	// ErrMigrationConflict reports that a v2 store was produced by a different
	// migration operation.
	ErrMigrationConflict = errors.New("floret v2 migration operation conflict")
)

Functions

This section is empty.

Types

type Backend

type Backend interface {
	View(context.Context, func(ReadTx) error) error
	Update(context.Context, func(WriteTx) error) error
	Close() error
}

Backend provides snapshot reads and serializable writes over opaque records. Implementations must invoke an Update callback exactly once and must never retry it implicitly.

type MigrateV2Request

type MigrateV2Request struct {
	Path        string
	OperationID string
}

MigrateV2Request identifies one exact SQLite migration operation.

type MigrateV2Result

type MigrateV2Result struct {
	OperationID string `json:"operation_id"`
	Replayed    bool   `json:"replayed"`
	Threads     int    `json:"threads"`
	Entries     int    `json:"entries"`
	ContentHash string `json:"content_hash"`
}

MigrateV2Result reports the committed operation and whether it was replayed.

func MigrateV2

func MigrateV2(ctx context.Context, request MigrateV2Request) (result MigrateV2Result, resultErr error)

MigrateV2 atomically converts one exact schema-v16 SQLite store into the v2 backend format. It never opens, repairs, or upgrades any other schema.

type MigrationSchemaError

type MigrationSchemaError struct {
	Version     string
	Fingerprint string
	Reason      string
}

MigrationSchemaError reports a database outside the one exact v16 source schema or exact v2 migration receipt accepted by MigrateV2.

func (*MigrationSchemaError) Error

func (failure *MigrationSchemaError) Error() string

Error describes the rejected migration schema.

type ReadTx

type ReadTx interface {
	Get(namespace string, key []byte) ([]byte, error)
	Scan(ScanRequest) (ScanPage, error)
}

ReadTx is a snapshot that is valid only for the duration of its callback.

type Record

type Record struct {
	Key   []byte
	Value []byte
}

Record is one key and value returned by Scan. Both byte slices are owned by the caller.

type ScanPage

type ScanPage struct {
	Records []Record
	HasMore bool
	Next    []byte
}

ScanPage is one ordered page. Next is the exclusive After cursor for the following request and is present only when HasMore is true.

type ScanRequest

type ScanRequest struct {
	Namespace string
	Start     []byte
	End       []byte
	After     []byte
	Limit     int
}

ScanRequest selects a bounded lexicographic page from one namespace. Start is inclusive, End is exclusive, and After is exclusive. Limit must be positive.

type Source

type Source interface {
	Open(context.Context) (Backend, error)
}

Source opens a fresh Backend. A Source may be retained and opened more than once; each returned Backend has an independent lifecycle.

func Memory

func Memory() Source

Memory returns an in-memory Source suitable for production ephemeral use and deterministic tests.

func SQLite

func SQLite(path string) Source

SQLite returns a Source backed by the SQLite file at path. The physical database contains only backend metadata and opaque namespaced records.

type WriteTx

type WriteTx interface {
	ReadTx
	Put(namespace string, key, value []byte) error
	Delete(namespace string, key []byte) error
}

WriteTx is a serializable transaction that is valid only for the duration of its callback.

Jump to

Keyboard shortcuts

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