Documentation
¶
Overview ¶
Package state provides functionality for storing and retrieving runner state across different environments (local filesystem, Kubernetes, etc.)
Index ¶
- Constants
- func AbortWriter(writer io.WriteCloser) error
- func DeleteSavedRunConfig(ctx context.Context, name string) error
- func LoadRunConfig[T any](ctx context.Context, name string, readJSONFunc ReadJSONFunc[T]) (T, error)
- func LoadRunConfigJSON(ctx context.Context, name string) (io.ReadCloser, error)
- func ReadJSON(r io.Reader, target interface{}) error
- func SaveRunConfig[T RunConfigPersister](ctx context.Context, config T) error
- type Aborter
- type KubernetesStore
- func (*KubernetesStore) CreateExclusive(_ context.Context, _ string) (io.WriteCloser, error)
- func (*KubernetesStore) Delete(_ context.Context, _ string) error
- func (*KubernetesStore) Exists(_ context.Context, _ string) (bool, error)
- func (*KubernetesStore) GetReader(_ context.Context, _ string) (io.ReadCloser, error)
- func (*KubernetesStore) GetWriter(_ context.Context, _ string) (io.WriteCloser, error)
- func (*KubernetesStore) List(_ context.Context) ([]string, error)
- type LocalStore
- func (s *LocalStore) CreateExclusive(_ context.Context, name string) (io.WriteCloser, error)
- func (s *LocalStore) Delete(_ context.Context, name string) error
- func (s *LocalStore) Exists(_ context.Context, name string) (bool, error)
- func (s *LocalStore) GetReader(_ context.Context, name string) (io.ReadCloser, error)
- func (s *LocalStore) GetWriter(_ context.Context, name string) (io.WriteCloser, error)
- func (s *LocalStore) List(_ context.Context) ([]string, error)
- type ReadJSONFunc
- type RunConfigPersister
- type Store
Constants ¶
const ( // RunConfigsDir is the directory name for storing run configurations RunConfigsDir = "runconfigs" // GroupConfigsDir is the directory name for storing group configurations GroupConfigsDir = "groups" )
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
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
LoadRunConfigJSON loads a run configuration from the state store and returns the raw reader
func ReadJSON ¶ added in v0.2.6
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
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
func (*KubernetesStore) GetWriter(_ context.Context, _ string) (io.WriteCloser, error)
GetWriter returns a no-op writer 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) 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.
type ReadJSONFunc ¶ added in v0.2.6
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 ¶
NewGroupConfigStore creates a store for group configurations
func NewGroupConfigStoreWithDetector ¶ added in v0.2.17
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 ¶
NewRunConfigStore creates a store for run configuration state
func NewRunConfigStoreWithDetector ¶ added in v0.2.17
NewRunConfigStoreWithDetector creates a store