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 ExecResult
- 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) 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) ListCheckpoints(id string) ([]CheckpointInfo, error)
- func (s *Store) Restore(id, checkpointID string) error
- 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 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 Sprite ¶
type Sprite struct {
ID string
Status Status
URL string
FS map[string]string
Checkpoints []Checkpoint
Policy any
// 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) 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) 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) 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.
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"`
}
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