storage

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
  • func NewMemory() *Memory
  • func (s *Memory) Commit(ctx context.Context, generation catalogs.Generation, expectedGenerationID string) error
  • func (s *Memory) Current(ctx context.Context) (catalogs.Generation, error)
  • func (s *Memory) Get(ctx context.Context, id string) (catalogs.Generation, error)
• type MemoryObjectBackend
  • func NewMemoryObjectBackend() *MemoryObjectBackend
  • func (b *MemoryObjectBackend) Get(ctx context.Context, key string) (ObjectValue, error)
  • func (b *MemoryObjectBackend) Put(ctx context.Context, key string, data []byte, condition ObjectPutCondition) (ObjectValue, error)
• 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 implements Store in process for tests and simple deployments.

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 compares and swaps 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