state

Documentation

Overview

Package state manages devc's per-workspace host-side directories and the state.json that records facts we must not keep inside the container: which container identity a workspace last used, which lifecycle hooks have run, the cached environment probe, and the injected agent version.

The layout under the user's data dir (XDG_DATA_HOME or ~/.local/share):

devc/<id>/
  state.json
  logs/
  (ssh keys live here too)

Index

• type Dir
  • func For(id string) (*Dir, error)
  • func (d *Dir) Load() (*State, error)
  • func (d *Dir) LogsDir() (string, error)
  • func (d *Dir) Path(name string) string
  • func (d *Dir) Remove() error
  • func (d *Dir) Save(s *State) error
• type State
  • func Peek(id string) (*State, error)

Types

type Dir

type Dir struct {
	Root string // .../devc/<id>
}

Dir is a workspace's state directory.

func For

func For(id string) (*Dir, error)

For returns the state directory for a workspace id, creating it (0700) if needed.

func (*Dir) Load

func (d *Dir) Load() (*State, error)

Load reads state.json, returning a zero State (not an error) when it does not yet exist.

func (*Dir) LogsDir

func (d *Dir) LogsDir() (string, error)

LogsDir returns (and creates) the per-workspace logs directory.

func (*Dir) Path

func (d *Dir) Path(name string) string

Path returns a path inside the workspace directory.

func (*Dir) Remove

func (d *Dir) Remove() error

Remove deletes the entire workspace state directory.

func (*Dir) Save

func (d *Dir) Save(s *State) error

Save writes state.json atomically (write temp + rename).

type State

type State struct {
	ID             string            `json:"id"`
	Name           string            `json:"name,omitempty"`
	LocalFolder    string            `json:"localWorkspaceFolder,omitempty"`
	ContainerID    string            `json:"containerID,omitempty"`
	ComposeProject string            `json:"composeProject,omitempty"`
	ConfigHash     string            `json:"configHash,omitempty"`
	Hooks          map[string]string `json:"hooks,omitempty"` // hook name -> RFC3339 timestamp
	EnvProbe       map[string]string `json:"envProbe,omitempty"`
	AgentVersion   string            `json:"agentVersion,omitempty"`
}

State is the persisted per-workspace record: the workspace's identity and origin, the container identity, which hooks have run, the cached env probe, and the injected agent version.

Name and LocalFolder duplicate what a single container carries as devc labels. They are recorded here because compose creates the service containers itself and devc cannot label them, so for a compose workspace this is the only place the display name and originating folder survive - `devc list` and -n/--name read them back from here.

func Peek

func Peek(id string) (*State, error)

Peek reads a workspace's state without creating its directory, for read-only callers (list, -n/--name) that must not conjure state dirs for ids they are merely inspecting. A workspace with no state yet yields a zero State.