state

package
v0.45.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package state provides functionality for storing and retrieving runner state across different environments (local filesystem, Kubernetes, etc.)

Index

Constants

View Source
const (
	// RunConfigsDir is the directory name for storing run configurations
	RunConfigsDir = "runconfigs"

	// GroupConfigsDir is the directory name for storing group configurations
	GroupConfigsDir = "groups"
)
View Source
const (
	// DefaultAppName is the default application name used for XDG paths
	DefaultAppName = "toolhive"

	// FileExtension is the file extension for stored configurations
	FileExtension = ".json"
)

Variables

This section is empty.

Functions

func AbortWriter added in v0.45.0

func AbortWriter(writer io.WriteCloser) error

AbortWriter discards uncommitted data written to writer.

Writers returned by Store.GetWriter and Store.CreateExclusive must implement Aborter. Callers must use AbortWriter, rather than Close, when abandoning a write because Close may publish the data.

func DeleteSavedRunConfig added in v0.2.4

func DeleteSavedRunConfig(ctx context.Context, name string) error

DeleteSavedRunConfig deletes a saved run configuration

func LoadRunConfig added in v0.2.6

func LoadRunConfig[T any](ctx context.Context, name string, readJSONFunc ReadJSONFunc[T]) (T, error)

LoadRunConfig loads a run configuration from the state store using the provided reader function

func LoadRunConfigJSON added in v0.2.4

func LoadRunConfigJSON(ctx context.Context, name string) (io.ReadCloser, error)

LoadRunConfigJSON loads a run configuration from the state store and returns the raw reader

func ReadJSON added in v0.2.6

func ReadJSON(r io.Reader, target interface{}) error

ReadJSON deserializes JSON from the provided reader into a generic interface This function is moved from the runner package to avoid circular dependencies

func SaveRunConfig added in v0.2.6

func SaveRunConfig[T RunConfigPersister](ctx context.Context, config T) error

SaveRunConfig saves a run configuration to the state store

Types

type Aborter added in v0.45.0

type Aborter interface {
	Abort() error
}

Aborter is implemented by state writers that can discard uncommitted data. Abort must release the writer's resources without publishing its contents.

type KubernetesStore added in v0.2.17

type KubernetesStore struct{}

KubernetesStore is a no-op implementation of Store for Kubernetes environments. In Kubernetes, workload state is managed by the cluster, not by local files.

func (*KubernetesStore) CreateExclusive added in v0.8.1

func (*KubernetesStore) CreateExclusive(_ context.Context, _ string) (io.WriteCloser, error)

CreateExclusive returns a no-op writer for Kubernetes stores. In Kubernetes, state management is handled by the cluster, not local files.

func (*KubernetesStore) Delete added in v0.2.17

func (*KubernetesStore) Delete(_ context.Context, _ string) error

Delete is a no-op for Kubernetes stores.

func (*KubernetesStore) Exists added in v0.2.17

func (*KubernetesStore) Exists(_ context.Context, _ string) (bool, error)

Exists always returns false for Kubernetes stores since state is not persisted locally.

func (*KubernetesStore) GetReader added in v0.2.17

func (*KubernetesStore) GetReader(_ context.Context, _ string) (io.ReadCloser, error)

GetReader returns a no-op reader for Kubernetes stores.

func (*KubernetesStore) GetWriter added in v0.2.17

GetWriter returns a no-op writer for Kubernetes stores.

func (*KubernetesStore) List added in v0.2.17

func (*KubernetesStore) List(_ context.Context) ([]string, error)

List always returns an empty slice for Kubernetes stores.

type LocalStore

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

LocalStore implements the Store interface using the local filesystem following the XDG Base Directory Specification

func NewLocalStore

func NewLocalStore(appName string, storeName string) (*LocalStore, error)

NewLocalStore creates a new LocalStore with the given application name and store type If appName is empty, DefaultAppName will be used

func (*LocalStore) CreateExclusive added in v0.8.1

func (s *LocalStore) CreateExclusive(_ context.Context, name string) (io.WriteCloser, error)

CreateExclusive creates a new state entry exclusively. Data is atomically published when the writer is closed.

func (*LocalStore) Delete

func (s *LocalStore) Delete(_ context.Context, name string) error

Delete removes the data for the given name

func (*LocalStore) Exists

func (s *LocalStore) Exists(_ context.Context, name string) (bool, error)

Exists checks if data exists for the given name

func (*LocalStore) GetReader

func (s *LocalStore) GetReader(_ context.Context, name string) (io.ReadCloser, error)

GetReader returns a reader for the state data

func (*LocalStore) GetWriter

func (s *LocalStore) GetWriter(_ context.Context, name string) (io.WriteCloser, error)

GetWriter returns a writer for the state data. Data is atomically published when the writer is closed.

func (*LocalStore) List

func (s *LocalStore) List(_ context.Context) ([]string, error)

List returns all available state names

type ReadJSONFunc added in v0.2.6

type ReadJSONFunc[T any] func(r io.Reader) (T, error)

ReadJSONFunc defines a function type for reading JSON into an object

type RunConfigPersister added in v0.2.6

type RunConfigPersister interface {
	// WriteJSON serializes the object to JSON and writes it to the provided writer
	WriteJSON(w io.Writer) error
	// GetBaseName returns the base name used for persistence
	GetBaseName() string
}

RunConfigPersister defines an interface for objects that can be persisted and loaded as JSON

type Store

type Store interface {
	// GetReader returns a reader for the state data
	// This is useful for streaming large state data
	GetReader(ctx context.Context, name string) (io.ReadCloser, error)

	// GetWriter returns a writer for the state data. For stores that publish state on Close,
	// callers must return Close errors because the write may not be visible until Close succeeds.
	// Callers must use AbortWriter instead of Close when abandoning a write, because Close may publish it.
	// This is useful for streaming large state data.
	GetWriter(ctx context.Context, name string) (io.WriteCloser, error)

	// CreateExclusive creates a new state entry exclusively, returning an error if it already exists.
	// For stores that publish state on Close, exclusivity is enforced at Close and Close can return
	// an error with http.StatusConflict if another writer published the entry first.
	// Callers must return Close errors and use AbortWriter rather than Close when abandoning a write,
	// because the write may not be visible until Close succeeds.
	// This provides atomic check-and-create semantics to prevent race conditions.
	CreateExclusive(ctx context.Context, name string) (io.WriteCloser, error)

	// Delete removes the data for the given name
	Delete(ctx context.Context, name string) error

	// List returns all available state names
	List(ctx context.Context) ([]string, error)

	// Exists checks if data exists for the given name
	Exists(ctx context.Context, name string) (bool, error)
}

Store defines the interface for runner state storage operations. Writers returned by GetWriter and CreateExclusive must support Aborter; callers must call AbortWriter rather than Close when abandoning a write, since Close may publish it.

func NewGroupConfigStore

func NewGroupConfigStore(appName string) (Store, error)

NewGroupConfigStore creates a store for group configurations

func NewGroupConfigStoreWithDetector added in v0.2.17

func NewGroupConfigStoreWithDetector(appName string) (Store, error)

NewGroupConfigStoreWithDetector creates a store

func NewKubernetesStore added in v0.2.17

func NewKubernetesStore() Store

NewKubernetesStore creates a new no-op store for Kubernetes environments.

func NewRunConfigStore

func NewRunConfigStore(appName string) (Store, error)

NewRunConfigStore creates a store for run configuration state

func NewRunConfigStoreWithDetector added in v0.2.17

func NewRunConfigStoreWithDetector(appName string) (Store, error)

NewRunConfigStoreWithDetector creates a store

Directories

Path Synopsis
Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

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