storage

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Mar 24, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package storage manages global and local storage layers with caching and version tracking.

Index

Constants

View Source
const MaxStaleness = time.Duration(math.MaxInt64)

MaxStaleness is the maximum duration a cached value can be stale, effectively meaning that any cached value is acceptable regardless of age.

Variables

View Source
var ErrKeyNotFound = errors.New("key not found in committed transaction")

ErrKeyNotFound is returned when a key is not found in a committed transaction log.

Functions

This section is empty.

Types

type Global

type Global struct {
	// contains filtered or unexported fields
}

Global wraps a backend with a local cache, performing read-through and write-through caching of storage objects and metadata.

func NewGlobal

func NewGlobal(b backend.Backend, l Local, clock clockwork.Clock) Global

NewGlobal returns a Global that reads and writes through the given backend, using l as a local cache.

func (Global) Delete

func (s Global) Delete(ctx context.Context, key string) error

Delete removes the object from the backend and the local cache.

func (Global) DeleteIf

func (s Global) DeleteIf(ctx context.Context, key string, expected backend.Version) error

DeleteIf conditionally deletes the object if its version matches expected, and removes it from the local cache on success.

func (Global) GetMetadata

func (s Global) GetMetadata(ctx context.Context, key string) (backend.Metadata, error)

GetMetadata fetches the object metadata from the backend and updates the local cache.

func (Global) Read

func (s Global) Read(ctx context.Context, key string) (GlobalRead, error)

func (Global) SetTagsIf

func (s Global) SetTagsIf(
	ctx context.Context,
	key string,
	expected backend.Version,
	t backend.Tags,
) (backend.Metadata, error)

SetTagsIf conditionally sets tags on the object if its current version matches expected, and updates the local metadata cache.

func (Global) Write

func (s Global) Write(
	ctx context.Context,
	key string,
	value []byte,
	t backend.Tags,
) (backend.Metadata, error)

func (Global) WriteIf

func (s Global) WriteIf(
	ctx context.Context,
	key string,
	value []byte,
	expected backend.Version,
	t backend.Tags,
) (backend.Metadata, error)

WriteIf conditionally writes the value if the current version matches expected, and updates the local cache.

func (Global) WriteIfNotExists

func (s Global) WriteIfNotExists(
	ctx context.Context,
	key string,
	value []byte,
	t backend.Tags,
) (backend.Metadata, error)

WriteIfNotExists writes the value only if the object does not already exist, and updates the local cache on success.

type GlobalRead

type GlobalRead struct {
	Value   []byte
	Version int64
}

GlobalRead holds the result of reading a value from global storage.

type Local

type Local struct {
	// contains filtered or unexported fields
}

Local provides a local in-memory cache for storage objects, including both values and metadata with staleness tracking.

func NewLocal

func NewLocal(c *cache.Cache, clock clockwork.Clock) Local

NewLocal returns a Local backed by the given cache and clock.

func (Local) Delete

func (c Local) Delete(key string)

Delete removes the given key entirely from the cache.

func (Local) GetMeta

func (c Local) GetMeta(key string, maxStale time.Duration) (LocalMetadata, bool)

GetMeta returns the cached metadata for the given key, if it exists and is not staler than maxStale.

func (Local) MarkDeleted

func (c Local) MarkDeleted(key string, v Version)

MarkDeleted marks the given key as deleted in the cache with the given version.

func (Local) MarkValueOutated

func (c Local) MarkValueOutated(key string, v Version)

MarkValueOutated annotates the given key value as outdated, only if it's currently set at the given version.

func (Local) Read

func (c Local) Read(key string, maxStale time.Duration) (LocalRead, bool)

func (Local) SetMeta

func (c Local) SetMeta(key string, meta backend.Metadata)

SetMeta updates only the cached metadata for the given key.

func (Local) Write

func (c Local) Write(key string, value []byte, v Version)

func (Local) WriteWithMeta

func (c Local) WriteWithMeta(key string, value []byte, meta backend.Metadata)

WriteWithMeta stores both the value and its metadata in the cache atomically.

type LocalMetadata

type LocalMetadata struct {
	M backend.Metadata
	// Outdated is true if the metadata is certainly outdated.
	Outdated bool
}

LocalMetadata holds cached metadata along with its freshness status.

type LocalRead

type LocalRead struct {
	Value   []byte
	Version Version
	Deleted bool
	// Outdated is true if the value read is certainly outdated.
	Outdated bool
}

LocalRead holds the result of reading a value from the local cache.

type LockInfo

type LockInfo struct {
	Type       LockType
	LockedBy   []data.TxID
	LastWriter data.TxID
}

LockInfo describes the current lock state of a storage object.

func TagsLockInfo

func TagsLockInfo(tags backend.Tags) (LockInfo, error)

TagsLockInfo parses tags managing locks on an object.

func (LockInfo) Valid

func (v LockInfo) Valid() error

Valid checks that the lock info is internally consistent, returning an error if any invariants are violated.

type LockOps

type LockOps struct {
	// Update is the possible next update on the lock. If nothing should be
	// updated, HasUpdate will be false.
	Update    LockUpdate
	HasUpdate bool
	// WaitFor is the list of transactions that need to unlock before any
	// operation can be performed.
	WaitFor []data.TxID
	// What effect these operations will have.
	LockedFor   []data.TxID
	UnlockedFor []data.TxID
}

LockOps represents what possible next update can be done to a lock.

This includes the update, what transactions need to unlock before this can done and what effects the operation will have.

func ComputeLockUpdate

func ComputeLockUpdate(curr LockInfo, req LockRequest, txs []TxPathState) (LockOps, error)

ComputeLockUpdate determines the next lock operation to perform given the current lock state, a lock request, and the status of relevant transactions.

type LockRequest

type LockRequest struct {
	Type      LockType
	Lockers   []data.TxID
	Unlockers []data.TxID
}

LockRequest specifies the transactions that want to acquire or release a lock.

type LockType

type LockType int

LockType represents the type of lock held on a storage object.

const (
	LockTypeUnknown LockType = iota
	LockTypeNone
	LockTypeRead
	LockTypeWrite
	LockTypeCreate
)

Possible values for LockType.

type LockUpdate

type LockUpdate struct {
	Type     LockType
	PrevType LockType
	Lockers  []data.TxID
	Writer   data.TxID
	Value    TValue
}

LockUpdate describes the desired state of a lock after an update operation.

type Locker

type Locker struct {
	// contains filtered or unexported fields
}

Locker applies lock updates to storage objects by writing lock state into backend tags and conditionally updating values.

func NewLocker

func NewLocker(g Global) Locker

NewLocker returns a Locker that manages locks through the given global storage.

func (Locker) UnlockCreateUncommitted

func (l Locker) UnlockCreateUncommitted(
	ctx context.Context,
	key string,
	expected backend.Version,
) error

UnlockCreateUncommitted releases a create-lock on an object whose transaction was not committed, deleting the object.

func (Locker) UpdateLock

func (l Locker) UpdateLock(
	ctx context.Context,
	key string,
	expected backend.Version,
	update LockUpdate,
) error

UpdateLock applies the given lock update to the object at key, using conditional writes to ensure the object's version matches expected.

type PathLock

type PathLock struct {
	Path string
	Type LockType
}

PathLock associates a storage path with its lock type.

type TLogger

type TLogger struct {
	// contains filtered or unexported fields
}

TLogger provides tools to deal with transaction logs.

func NewTLogger

func NewTLogger(c clockwork.Clock, g Global, l Local, prefix string) TLogger

NewTLogger returns a TLogger that stores transaction logs under the given prefix.

func (TLogger) CommitStatus

func (t TLogger) CommitStatus(ctx context.Context, id data.TxID) (TxStatus, error)

CommitStatus returns the commit status of the transaction with the given ID, reading from the local cache when possible.

func (TLogger) Delete

func (t TLogger) Delete(ctx context.Context, id data.TxID) error

Delete removes the transaction log for the given ID, ignoring not-found errors.

func (TLogger) Get

func (t TLogger) Get(ctx context.Context, id data.TxID) (TxLog, error)

Get reads and parses the full transaction log for the given transaction ID.

func (TLogger) Set

func (t TLogger) Set(ctx context.Context, l TxLog) (backend.Version, error)

Set creates a new transaction log entry, failing if one already exists.

func (TLogger) SetIf

func (t TLogger) SetIf(ctx context.Context, l TxLog, expected backend.Version) (backend.Version, error)

SetIf updates the transaction log only if its current version matches expected.

type TValue

type TValue struct {
	Value   []byte
	Deleted bool
	// NotWritten is true when the transaction was committed but the value
	// was not written to (e.g. when only locked in read).
	NotWritten bool
}

TValue holds a value written by a transaction, including whether it was a deletion or was not written at all.

type TxCommitStatus

type TxCommitStatus int

TxCommitStatus represents the commit state of a transaction.

const (
	TxCommitStatusUnknown TxCommitStatus = iota
	TxCommitStatusOK
	TxCommitStatusAborted
	TxCommitStatusPending
)

Possible values for TxCommitStatus.

func (TxCommitStatus) IsFinal

func (s TxCommitStatus) IsFinal() bool

IsFinal reports whether the status represents a terminal state (committed or aborted).

type TxLog

type TxLog struct {
	ID        data.TxID
	Timestamp time.Time
	Status    TxCommitStatus
	Writes    []TxWrite
	Locks     []PathLock
}

TxLog holds the full contents of a transaction log entry, including its writes and acquired locks.

type TxPathState

type TxPathState struct {
	Tx     data.TxID
	Status TxCommitStatus
	Value  TValue
}

TxPathState describes a transaction's commit status and the value it wrote for a particular path.

type TxStatus

type TxStatus struct {
	Status     TxCommitStatus
	LastUpdate time.Time
	Version    backend.Version
}

TxStatus holds the commit status of a transaction along with its timestamp and backend version.

type TxWrite

type TxWrite struct {
	Path       string
	Value      []byte
	Deleted    bool
	PrevWriter data.TxID
}

TxWrite represents a single write operation within a transaction.

type Version

type Version struct {
	B      backend.Version
	Writer data.TxID
}

Version represents a storage object's version, combining a backend version with an optional local transaction writer.

func VersionFromMeta

func VersionFromMeta(m backend.Metadata) Version

VersionFromMeta constructs a Version from backend metadata, extracting the last writer from the metadata tags.

func (Version) EqualContents

func (v Version) EqualContents(other Version) bool

EqualContents reports whether v and other refer to the same version content, comparing backend contents or writer IDs as appropriate.

func (Version) EqualMetaContents

func (v Version) EqualMetaContents(m backend.Metadata) bool

EqualMetaContents reports whether v matches the version described by the given backend metadata.

func (Version) IsLocal

func (v Version) IsLocal() bool

IsLocal reports whether the version was written by a local transaction that has not yet been committed to the backend.

func (Version) IsNull

func (v Version) IsNull() bool

IsNull reports whether the version has no backend version and no writer.

Jump to

Keyboard shortcuts

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