README
¶
storage
import "github.com/agentstation/starmap/pkg/catalogs/storage"
Package storage provides durable generation-oriented catalog storage.
Index
- type Filesystem
- func NewFilesystem(path string) (*Filesystem, error)
- func (s *Filesystem) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
- func (s *Filesystem) Current(ctx context.Context) (catalogs.Generation, error)
- func (s *Filesystem) Get(ctx context.Context, id string) (catalogs.Generation, error)
- func (s *Filesystem) Root() string
- type Memory
- type MemoryObjectBackend
- type Object
- func NewObject(backend ObjectBackend, prefix string) (*Object, error)
- func (s *Object) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
- func (s *Object) Current(ctx context.Context) (catalogs.Generation, error)
- func (s *Object) Get(ctx context.Context, id string) (catalogs.Generation, error)
- type ObjectBackend
- type ObjectPutCondition
- type ObjectValue
- type Store
type Filesystem
Filesystem stores immutable generation directories and an atomically replaced current pointer beneath one root directory.
type Filesystem struct {
// contains filtered or unexported fields
}
func NewFilesystem
func NewFilesystem(path string) (*Filesystem, error)
NewFilesystem creates a filesystem catalog store rooted at path.
func (*Filesystem) Commit
func (s *Filesystem) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
Commit writes an immutable generation before atomically replacing current.
func (*Filesystem) Current
func (s *Filesystem) Current(ctx context.Context) (catalogs.Generation, error)
Current returns the currently active generation.
func (*Filesystem) Get
func (s *Filesystem) Get(ctx context.Context, id string) (catalogs.Generation, error)
Get returns an immutable generation by ID.
func (*Filesystem) Root
func (s *Filesystem) Root() string
Root returns the configured filesystem root without creating it.
type Memory
Memory is an in-process reference implementation of Store.
type Memory struct {
// contains filtered or unexported fields
}
func NewMemory
func NewMemory() *Memory
NewMemory creates an empty in-memory catalog store.
func (*Memory) Commit
func (s *Memory) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
Commit validates and atomically activates generation when current matches expectedGenerationID.
func (*Memory) Current
func (s *Memory) Current(ctx context.Context) (catalogs.Generation, error)
Current returns the currently active generation.
func (*Memory) Get
func (s *Memory) Get(ctx context.Context, id string) (catalogs.Generation, error)
Get returns an immutable generation by ID.
type MemoryObjectBackend
MemoryObjectBackend is a deterministic reference object backend.
type MemoryObjectBackend struct {
// contains filtered or unexported fields
}
func NewMemoryObjectBackend
func NewMemoryObjectBackend() *MemoryObjectBackend
NewMemoryObjectBackend creates an empty reference object backend.
func (*MemoryObjectBackend) Get
func (b *MemoryObjectBackend) Get(ctx context.Context, key string) (ObjectValue, error)
Get returns a defensive copy of key.
func (*MemoryObjectBackend) Put
func (b *MemoryObjectBackend) Put(ctx context.Context, key string, data []byte, condition ObjectPutCondition) (ObjectValue, error)
Put atomically writes key when condition matches.
type Object
Object stores immutable generations in an object namespace and promotes a versioned current pointer with a conditional write.
type Object struct {
// contains filtered or unexported fields
}
func NewObject
func NewObject(backend ObjectBackend, prefix string) (*Object, error)
NewObject creates an object-backed catalog store.
func (*Object) Commit
func (s *Object) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
Commit uploads immutable generation objects before conditionally promoting the current pointer.
func (*Object) Current
func (s *Object) Current(ctx context.Context) (catalogs.Generation, error)
Current returns the currently active generation.
func (*Object) Get
func (s *Object) Get(ctx context.Context, id string) (catalogs.Generation, error)
Get returns an immutable generation by ID.
type ObjectBackend
ObjectBackend is the minimum immutable-object and conditional-pointer API required by Object.
Version must be a non-empty opaque token that identifies the exact returned object version. Put must atomically honor IfAbsent or IfVersion and return a typed conflict when its condition does not hold. Production adapters must never weaken either condition to an unconditional last-writer-wins write. Cloud adapters should translate ETags or object generations to Version.
type ObjectBackend interface {
Get(context.Context, string) (ObjectValue, error)
Put(context.Context, string, []byte, ObjectPutCondition) (ObjectValue, error)
}
type ObjectPutCondition
ObjectPutCondition configures an atomic conditional object write.
type ObjectPutCondition struct {
IfAbsent bool
IfVersion string
}
type ObjectValue
ObjectValue is one versioned object returned by an ObjectBackend.
type ObjectValue struct {
Data []byte
Version string
}
type Store
Store commits and reads immutable catalog generations.
Commit always performs compare-and-swap against expectedGenerationID. An empty expected ID means that no current generation may exist. Implementations must validate and persist the complete generation before changing Current. Repeating an already-successful identical commit is idempotent.
Starmap provides memory, filesystem, and conditional object-storage implementations. Embedding applications own and inject any database-backed implementation, including its driver, schema, migrations, credentials, connection pool, backups, and lifecycle.
type Store interface {
Current(context.Context) (catalogs.Generation, error)
Get(context.Context, string) (catalogs.Generation, error)
Commit(context.Context, catalogs.Generation, string) error
}
Generated by gomarkdoc
Documentation
¶
Overview ¶
Package storage provides durable generation-oriented catalog storage.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Filesystem ¶
type Filesystem struct {
// contains filtered or unexported fields
}
Filesystem stores immutable generation directories and an atomically replaced current pointer beneath one root directory.
func NewFilesystem ¶
func NewFilesystem(path string) (*Filesystem, error)
NewFilesystem creates a filesystem catalog store rooted at path.
func (*Filesystem) Commit ¶
func (s *Filesystem) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
Commit writes an immutable generation before atomically replacing current.
func (*Filesystem) Current ¶
func (s *Filesystem) Current(ctx context.Context) (catalogs.Generation, error)
Current returns the currently active generation.
func (*Filesystem) Get ¶
func (s *Filesystem) Get(ctx context.Context, id string) (catalogs.Generation, error)
Get returns an immutable generation by ID.
func (*Filesystem) Root ¶
func (s *Filesystem) Root() string
Root returns the configured filesystem root without creating it.
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory is an in-process reference implementation of Store.
func (*Memory) Commit ¶
func (s *Memory) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
Commit validates and atomically activates generation when current matches expectedGenerationID.
type MemoryObjectBackend ¶
type MemoryObjectBackend struct {
// contains filtered or unexported fields
}
MemoryObjectBackend is a deterministic reference object backend.
func NewMemoryObjectBackend ¶
func NewMemoryObjectBackend() *MemoryObjectBackend
NewMemoryObjectBackend creates an empty reference object backend.
func (*MemoryObjectBackend) Get ¶
func (b *MemoryObjectBackend) Get(ctx context.Context, key string) (ObjectValue, error)
Get returns a defensive copy of key.
func (*MemoryObjectBackend) Put ¶
func (b *MemoryObjectBackend) Put(ctx context.Context, key string, data []byte, condition ObjectPutCondition) (ObjectValue, error)
Put atomically writes key when condition matches.
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
Object stores immutable generations in an object namespace and promotes a versioned current pointer with a conditional write.
func NewObject ¶
func NewObject(backend ObjectBackend, prefix string) (*Object, error)
NewObject creates an object-backed catalog store.
func (*Object) Commit ¶
func (s *Object) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
Commit uploads immutable generation objects before conditionally promoting the current pointer.
type ObjectBackend ¶
type ObjectBackend interface {
Get(context.Context, string) (ObjectValue, error)
Put(context.Context, string, []byte, ObjectPutCondition) (ObjectValue, error)
}
ObjectBackend is the minimum immutable-object and conditional-pointer API required by Object.
Version must be a non-empty opaque token that identifies the exact returned object version. Put must atomically honor IfAbsent or IfVersion and return a typed conflict when its condition does not hold. Production adapters must never weaken either condition to an unconditional last-writer-wins write. Cloud adapters should translate ETags or object generations to Version.
type ObjectPutCondition ¶
ObjectPutCondition configures an atomic conditional object write.
type ObjectValue ¶
ObjectValue is one versioned object returned by an ObjectBackend.
type Store ¶
type Store interface {
Current(context.Context) (catalogs.Generation, error)
Get(context.Context, string) (catalogs.Generation, error)
Commit(context.Context, catalogs.Generation, string) error
}
Store commits and reads immutable catalog generations.
Commit always performs compare-and-swap against expectedGenerationID. An empty expected ID means that no current generation may exist. Implementations must validate and persist the complete generation before changing Current. Repeating an already-successful identical commit is idempotent.
Starmap provides memory, filesystem, and conditional object-storage implementations. Embedding applications own and inject any database-backed implementation, including its driver, schema, migrations, credentials, connection pool, backups, and lifecycle.
Source Files
Directories