workspace

Documentation

Overview

Package workspace defines the shared storage backend that every agent execution node mounts. All nodes in a deployment read and write the same workspace, so state lives in exactly one place regardless of how many agents are running.

The interface is a minimal blob store so that backends (a local directory today; GCS, S3, or similar later) can slot in without touching any other package.

Index

• Variables
• func ValidKey(key string) bool
• type Local
  • func NewLocal(dir string) (*Local, error)
  • func (l *Local) Delete(_ context.Context, key string) error
  • func (l *Local) List(_ context.Context, prefix string) ([]string, error)
  • func (l *Local) Read(_ context.Context, key string) (io.ReadCloser, error)
  • func (l *Local) Write(_ context.Context, key string, r io.Reader) error
• type Workspace

Variables

var ErrInvalidKey = errors.New("workspace: invalid key")

ErrInvalidKey is returned when a key is empty, absolute, or attempts to escape the workspace (e.g. contains "..").

var ErrNotFound = errors.New("workspace: key not found")

ErrNotFound is returned when a key does not exist in the workspace.

Functions

func ValidKey

func ValidKey(key string) bool

ValidKey reports whether key is a well-formed workspace key: non-empty, relative, slash-separated, with no empty or "."/".." segments. Backends and decorators share this check so traversal is rejected uniformly.

Types

type Local

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

Local is a Workspace backed by a directory on the local filesystem. It is the default backend for single-machine deployments and for tests.

func NewLocal

func NewLocal(dir string) (*Local, error)

NewLocal creates (if needed) and opens a workspace rooted at dir.

func (*Local) Delete

func (l *Local) Delete(_ context.Context, key string) error

Delete implements Workspace.

func (*Local) List

func (l *Local) List(_ context.Context, prefix string) ([]string, error)

List implements Workspace.

func (*Local) Read

func (l *Local) Read(_ context.Context, key string) (io.ReadCloser, error)

Read implements Workspace.

func (*Local) Write

func (l *Local) Write(_ context.Context, key string, r io.Reader) error

Write implements Workspace.

type Workspace

type Workspace interface {
	// Read opens the blob at key. The caller must close the returned reader.
	// Returns ErrNotFound if the key does not exist.
	Read(ctx context.Context, key string) (io.ReadCloser, error)

	// Write stores the blob at key, replacing any existing value.
	Write(ctx context.Context, key string, r io.Reader) error

	// List returns all keys under prefix in lexical order. An empty prefix
	// lists every key.
	List(ctx context.Context, prefix string) ([]string, error)

	// Delete removes the blob at key. Returns ErrNotFound if the key does
	// not exist.
	Delete(ctx context.Context, key string) error
}

Workspace is a flat, prefix-addressable blob store shared by every node in a deployment. Keys are slash-separated relative paths such as "runs/42/output.json".