Documentation
¶
Overview ¶
Package store manages VM state directories under ~/.fleetbox/clusters/<cluster>/<member>/.
Index ¶
- func ClusterName(name string) string
- type Fixture
- type Lock
- type Store
- func (s *Store) BaseDir() string
- func (s *Store) BinDir() string
- func (s *Store) ControlSocketPath(primary string) string
- func (s *Store) Create(vm *VM) error
- func (s *Store) Delete(name string) error
- func (s *Store) DiskPath(name string) string
- func (s *Store) EFIPath(name string) string
- func (s *Store) EnsureDir(name string) error
- func (s *Store) Exists(name string) bool
- func (s *Store) FixturePath(name string, i int) string
- func (s *Store) ImagesDir() string
- func (s *Store) List() ([]string, error)
- func (s *Store) Load(name string) (*VM, error)
- func (s *Store) NetworkStateDir() string
- func (s *Store) PidfilePath(name string) string
- func (s *Store) SSHKeyPath() string
- func (s *Store) Save(vm *VM) error
- func (s *Store) SeedPath(name string) string
- func (s *Store) SerialLogPath(name string) string
- func (s *Store) SocketPath(name string) string
- func (s *Store) TryLock(name string) (*Lock, error)
- func (s *Store) VMDir(name string) string
- type VM
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClusterName ¶ added in v0.3.1
ClusterName derives a member's cluster name by stripping a single trailing "-<digits>" group, e.g. "web-3" → "web", "dev" → "dev". It is the exported, documented entry point to the membership rule (see clusterName for the exact cases) so callers outside the package — the CLI's down/rm target resolution — reuse the one canonical rule instead of re-deriving the digits-suffix logic.
Types ¶
type Fixture ¶
type Fixture struct {
HostPath string `json:"host_path"`
GuestPath string `json:"guest_path"`
Label string `json:"label"`
}
Fixture is a persisted read-only host directory packed into the guest at boot. HostPath is absolute; Label is the stable ext4 volume label assigned at first creation (FBFIX<i>, i = position in the fixture list). The label is the single source of truth shared between the image's volume label and the guest's cloud-init LABEL= mount line, so it is computed once and persisted here rather than re-derived in two places (ADR-0015).
type Lock ¶
type Lock struct {
// contains filtered or unexported fields
}
Lock represents an advisory file lock on a VM.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store manages VM storage.
func New ¶
New creates a Store at the default location (<home>/.fleetbox). When the process is root via sudo it resolves the INVOKING user's home, not /root, so state never splits between /root/.fleetbox and ~/.fleetbox across an auto-elevated `up` and a non-root `ls`/`ssh` (ADR-0023). This is the single place the base-dir rule lives, so every process — CLI, orchestrator, holder — agrees.
func (*Store) BinDir ¶
BinDir returns the cache directory for downloaded executables and firmware (~/.fleetbox/bin). The Linux backend caches the checksum-pinned cloud-hypervisor binary and its firmware here; it is created on first download rather than by New, so macOS installs never grow an empty bin directory.
func (*Store) ControlSocketPath ¶
ControlSocketPath returns the path to a bound helper's holder-wide control socket. It is distinct from the per-member SocketPath: the library client holds one long-lived connection to it for the helper's lifetime, and the helper treats that connection's EOF as "parent gone — tear everything down" (ADR-0017, R4). Like SocketPath it lives in run/ under a name hash to stay under the sun_path limit.
func (*Store) Delete ¶
Delete removes a VM's member directory and all its contents, then drops the parent cluster directory if it is now empty.
func (*Store) EnsureDir ¶
EnsureDir creates the member directory (and its cluster parent) for a VM. It is idempotent and is the single place member directories are created, so the holder (which serves a member's socket/pidfile before the VM boots) and Create both go through it.
func (*Store) FixturePath ¶
FixturePath returns the path to the i-th fixture's ext4 image inside the VM's member directory (fixture-<i>.img). It is per-member, not cluster-level, so the existing Delete → RemoveAll(memberDir) wipes it for free with no extra teardown (ADR-0015).
func (*Store) List ¶
List returns the names of all stored VM members, walking the two-level clusters/<cluster>/<member>/ tree and returning the flat list of member names (the unit every caller works in). Results are cluster-sorted then member-sorted (os.ReadDir sorts each level), not creation order.
func (*Store) NetworkStateDir ¶
NetworkStateDir returns the directory holding the Linux backend's per-network write-ahead records and ip_forward marker (~/.fleetbox/networks). It lets a crashed cluster's bridges/taps/iptables rules be reclaimed on the next up or via prune (ADR-0013); it is created on first network create, so macOS installs never grow it.
func (*Store) PidfilePath ¶
PidfilePath returns the path to the VM's holder pidfile, inside its member directory. Every member served by one holder writes the same PID (os.Getpid) into its own pidfile.
func (*Store) SSHKeyPath ¶
SSHKeyPath returns the path to the SSH private key.
func (*Store) SerialLogPath ¶
SerialLogPath returns the path to the VM's serial log.
func (*Store) SocketPath ¶
SocketPath returns the path to a member's holder control socket. It lives in ~/.fleetbox/run/ under a hash of the name, NOT in the member directory: a unix socket path must fit the 104-byte sun_path limit, and the nested member dir (clusters/<cluster>/<member>/) plus a long name and a long home dir blows past it. The hash keeps the path short and bounded regardless of name length (amends ADR-0014, which had placed it in the member dir).
func (*Store) TryLock ¶
TryLock attempts to acquire an exclusive lock on the VM. Returns nil if locked successfully, error otherwise.
func (*Store) VMDir ¶
VMDir returns the member directory for a VM, nested under its cluster: <baseDir>/clusters/<cluster>/<member>/. The cluster segment is derived from the member name (see clusterName), so a solo VM "dev" lives at clusters/dev/dev/ and a cluster member "web-2" at clusters/web/web-2/.
type VM ¶
type VM struct {
Name string `json:"name"`
MAC string `json:"mac"`
CPUs int `json:"cpus"`
MemoryMB int `json:"memory_mb"`
DiskMB int `json:"disk_mb"`
Image string `json:"image"`
CreatedAt time.Time `json:"created_at"`
Fixtures []Fixture `json:"fixtures,omitempty"`
// IP is the static IPv4 address assigned at first create on backends that
// allocate from a known subnet (Linux/cloud-hypervisor). It is the persisted
// source of truth so a rebooted VM keeps its address and a re-joining cluster
// member does not collide. Empty on macOS, where addresses come from DHCP.
IP string `json:"ip,omitempty"`
}
VM represents a stored VM configuration.
Source Files