Documentation
¶
Overview ¶
Package sprite is a thread-safe, in-memory model of Sprites and their checkpoint/restore semantics. It owns the canonical state; callers receive copies so that concurrent reads and writes never share mutable memory.
A sprite's filesystem is modeled as a path -> contents map. exec runs a small scripted interpreter (see exec.go) that can write or modify an fs key, so a checkpoint (a deep copy of the fs under a server-assigned version id) and a later restore (replace the fs with that copy) are observable. This mirrors the behavior of chant's in-process Sprites fake rather than real code execution.
Checkpoints are addressed by a server-assigned version id (v1, v2, …), not by a caller label. The caller supplies only an optional comment; the store assigns the id sequentially per sprite in creation order.
Index ¶
- Variables
- type Checkpoint
- type CheckpointInfo
- type DirEntry
- type ExecResult
- type NetworkRule
- type Service
- type ServiceState
- type Sprite
- type Status
- type Store
- func (s *Store) Checkpoint(id, comment string) (string, error)
- func (s *Store) Create(id, url string, policy any) Sprite
- func (s *Store) CreateTask(id, name string, expire any) error
- func (s *Store) Destroy(id string) error
- func (s *Store) Exec(id, cmd string) (ExecResult, error)
- func (s *Store) Get(id string) (View, error)
- func (s *Store) GetCheckpoint(id, checkpointID string) (CheckpointInfo, error)
- func (s *Store) GetPolicy(id string) ([]NetworkRule, error)
- func (s *Store) GetService(id, name string) (Service, bool, error)
- func (s *Store) ListCheckpoints(id string) ([]CheckpointInfo, error)
- func (s *Store) ListDir(id, dir string) ([]DirEntry, error)
- func (s *Store) ListServices(id string) ([]Service, error)
- func (s *Store) ListTasks(id string) ([]Task, error)
- func (s *Store) PutService(id string, svc Service) (Service, error)
- func (s *Store) ReadFile(id, path string) (string, bool, error)
- func (s *Store) RefreshTask(id, name string, expire any) (bool, error)
- func (s *Store) ReleaseTask(id, name string) (bool, error)
- func (s *Store) Remove(id, path string, recursive bool) (bool, error)
- func (s *Store) Restore(id, checkpointID string) error
- func (s *Store) SetPolicy(id string, rules []NetworkRule) ([]NetworkRule, error)
- func (s *Store) SetServiceState(id, name, action string) (Service, bool, error)
- func (s *Store) WriteFile(id, path, content string) error
- type Task
- type View
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound is returned for a sprite that was never created or has been // destroyed. A destroyed sprite is treated as absent, matching the fake. ErrNotFound = errors.New("sprite not found") // ErrCheckpointNotFound is returned by Restore for an unknown checkpoint id. ErrCheckpointNotFound = errors.New("checkpoint not found") )
Sentinel errors returned by the store.
Functions ¶
This section is empty.
Types ¶
type Checkpoint ¶ added in v0.2.0
type Checkpoint struct {
ID string
Comment string
CreateTime string
IsAuto bool
FS map[string]string
}
Checkpoint is a captured filesystem snapshot: a server-assigned version id (v1, v2, …), the caller-supplied comment, the creation timestamp, whether it was created automatically, and a full copy of the fs at checkpoint time.
type CheckpointInfo ¶ added in v0.2.0
type CheckpointInfo struct {
ID string `json:"id"`
Comment string `json:"comment"`
CreateTime string `json:"create_time"`
IsAuto bool `json:"is_auto"`
}
CheckpointInfo is the metadata projection of a checkpoint, without its fs copy. It is what the list endpoint, the individual GET, and the sprite view expose so a client can pick a checkpoint by id (or, for compensation, by the newest matching comment). The JSON tags match the real Sprites checkpoint shape: id, comment, create_time, is_auto.
type DirEntry ¶ added in v0.4.0
type DirEntry struct {
Name string `json:"name"`
Type string `json:"type"`
Size int `json:"size,omitempty"`
}
DirEntry is one filesystem listing entry. Type is "file" or "dir".
type ExecResult ¶
ExecResult is the outcome of running a command in a sprite. The server's control-WebSocket exec handler carries these three fields to the client as framed messages: stdout as StreamStdout, stderr as StreamStderr, and the exit code as the StreamExit frame's single payload byte.
type NetworkRule ¶ added in v0.4.0
NetworkRule is one outbound rule. Ordered — specificity is positional.
type Service ¶ added in v0.4.0
type Service struct {
Name string `json:"name"`
Cmd string `json:"cmd"`
Args []string `json:"args,omitempty"`
Env map[string]string `json:"env,omitempty"`
Dir string `json:"dir,omitempty"`
Needs []string `json:"needs,omitempty"`
HTTPPort int `json:"http_port,omitempty"`
State ServiceState `json:"state"`
}
Service is a background service: its create config plus live state. Keyed by name; PUT is create-or-update.
type ServiceState ¶ added in v0.4.0
type ServiceState struct {
Name string `json:"name"`
PID int `json:"pid"`
Status string `json:"status"`
StartedAt string `json:"started_at,omitempty"`
}
ServiceState is the live state projection of a background service.
type Sprite ¶
type Sprite struct {
ID string
Status Status
URL string
FS map[string]string
Checkpoints []Checkpoint
Policy any
// NetPolicy is the outbound network policy (whole-object replace).
NetPolicy []NetworkRule
// Services are background services keyed by name (create-or-update).
Services map[string]*Service
// Tasks are keep-alive holds keyed by name; while any exists the sprite
// stays active.
Tasks map[string]Task
// CreatedAt is stamped from the injected clock at creation. It is internal
// bookkeeping and is not part of the wire contract.
CreatedAt string
}
Sprite is a single sprite: its lifecycle status, its addressable URL, its filesystem, and its checkpoints (an ordered list, each a full copy of the fs at checkpoint time under a sequential v<N> id).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds sprites keyed by id.
func (*Store) Checkpoint ¶
Checkpoint deep-copies the sprite's current filesystem under a fresh, server-assigned version id and returns that id. Ids are assigned sequentially per sprite: "v1", "v2", …, one past the current checkpoint count. The caller controls only the comment, which may be empty. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) Create ¶
Create records a new running sprite under id, with an empty filesystem and no checkpoints. Like the fake, it overwrites any existing sprite with the same id. It returns a copy of the created sprite.
func (*Store) CreateTask ¶ added in v0.4.0
CreateTask records a keep-alive hold. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) Destroy ¶
Destroy marks the sprite destroyed. It returns ErrNotFound if the sprite is missing or already destroyed.
func (*Store) Exec ¶
func (s *Store) Exec(id, cmd string) (ExecResult, error)
Exec runs cmd against the sprite's filesystem and returns the result. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) Get ¶
Get returns a read-only view of the sprite. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) GetCheckpoint ¶ added in v0.3.0
func (s *Store) GetCheckpoint(id, checkpointID string) (CheckpointInfo, error)
GetCheckpoint returns a single checkpoint's metadata projection. It returns ErrNotFound for a missing or destroyed sprite, and ErrCheckpointNotFound for an unknown id.
func (*Store) GetPolicy ¶ added in v0.4.0
func (s *Store) GetPolicy(id string) ([]NetworkRule, error)
GetPolicy returns the sprite's outbound rules (a non-nil slice). It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) GetService ¶ added in v0.4.0
GetService returns a single service and whether it exists. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) ListCheckpoints ¶ added in v0.2.0
func (s *Store) ListCheckpoints(id string) ([]CheckpointInfo, error)
ListCheckpoints returns the sprite's checkpoints as {id, comment} projections in creation order (oldest first), so a client can pick the newest deterministically. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) ListDir ¶ added in v0.4.0
ListDir returns the immediate children of dir: a key "<dir>/name" is a file, "<dir>/name/..." contributes the dir "name" once. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) ListServices ¶ added in v0.4.0
ListServices returns the sprite's services in name order. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) ListTasks ¶ added in v0.4.0
ListTasks returns the sprite's active tasks in name order. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) PutService ¶ added in v0.4.0
PutService creates or updates a service by name, preserving its live state across an update. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) ReadFile ¶ added in v0.4.0
ReadFile returns the contents at path and whether it exists. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) RefreshTask ¶ added in v0.4.0
RefreshTask updates a task's expiry, returning whether it existed. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) ReleaseTask ¶ added in v0.4.0
ReleaseTask removes a task, returning whether it existed. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) Remove ¶ added in v0.4.0
Remove deletes path (recursively when recursive is set: path itself and every key under "<path>/"). It returns whether anything was removed, and ErrNotFound for a missing or destroyed sprite.
func (*Store) Restore ¶
Restore replaces the sprite's filesystem with the identified checkpoint's copy and sets its status back to running. The checkpoint is addressed by its server-assigned version id (v1, v2, …). It returns ErrNotFound for a missing or destroyed sprite, and ErrCheckpointNotFound for an unknown id.
func (*Store) SetPolicy ¶ added in v0.4.0
func (s *Store) SetPolicy(id string, rules []NetworkRule) ([]NetworkRule, error)
SetPolicy replaces the sprite's outbound rules (whole-object replace) and returns the applied set. It returns ErrNotFound for a missing or destroyed sprite.
func (*Store) SetServiceState ¶ added in v0.4.0
SetServiceState applies a start/stop/restart action to a service, flipping its status, and returns the service and whether it exists. It returns ErrNotFound for a missing or destroyed sprite.
type Task ¶ added in v0.4.0
Task is a keep-alive hold. While any task exists the sprite stays active.
type View ¶
type View struct {
ID string `json:"id"`
Status Status `json:"status"`
URL string `json:"url"`
FS map[string]string `json:"fs"`
Checkpoints []CheckpointInfo `json:"checkpoints"`
NetPolicy []NetworkRule `json:"netPolicy"`
Services map[string]Service `json:"services"`
Tasks map[string]Task `json:"tasks"`
}
View is the read-only projection returned by GET /v1/sprites/{id}: the checkpoints are exposed as an ordered list of {id, comment} projections, not their fs copies.
Source Files