Documentation
¶
Overview ¶
Package demo owns the disposable installed local measurement.
Index ¶
- Constants
- Variables
- func DefaultLocalStateDir() (string, error)
- func DispatcherConfiguration(version, db string) map[string]any
- func DispatcherUp(ctx context.Context, assets Assets, options RoleOptions) error
- func ExecutorConfiguration(version, id, db string, record readiness.Record) map[string]any
- func ExecutorUp(ctx context.Context, assets Assets, options RoleOptions) error
- func FileNames(info fs.FileInfo) (uint64, bool)
- func PrepareRoleDatabase(ctx context.Context, role storagecheck.Role, dir string) (path string, created bool, err error)
- func RoleDatabase(dir string, role storagecheck.Role) string
- func Up(ctx context.Context, assets Assets, options LocalOptions) error
- func ValidateControlAddress(address string) error
- func WriteConfig(path string, config map[string]any) error
- type Assets
- type BackupManifest
- type BackupOptions
- type BackupRole
- type Child
- type ChildProcess
- type ChildSpec
- type LocalEnvironment
- type LocalOptions
- type LogOptions
- type Manifest
- type ProcessCleanup
- type RestoreOptions
- type Result
- type RoleEnvironment
- type RoleOptions
- type RoleProcess
- type RoleState
- type Supervisor
- func (s *Supervisor) Cancel(cause error)
- func (s *Supervisor) Close(ctx context.Context) (ProcessCleanup, error)
- func (s *Supervisor) Context() context.Context
- func (s *Supervisor) Healthy() error
- func (s *Supervisor) Quiesce()
- func (s *Supervisor) StartChild(name string, spec ChildSpec, daemon bool) (ChildProcess, error)
- func (s *Supervisor) StartRole(ctx context.Context, role RoleProcess) (ChildProcess, readiness.Record, error)
- func (s *Supervisor) Stop(ctx context.Context, process ChildProcess) error
Constants ¶
const OfflineStateFile = "offline-state.json"
OfflineStateFile records a foreground launcher's completed child shutdown. A launcher must remove it before starting any daemon against this state.
const OpenWithoutWaiting = syscall.O_NONBLOCK
OpenWithoutWaiting is the open flag that keeps opening a named pipe from waiting until somebody opens the other end. A privileged command that opens what it finds in a directory another account writes needs it, or that account can stop the command indefinitely by leaving a pipe there.
Variables ¶
var ErrForcedKill = errors.New("demo child required forced termination")
ErrForcedKill distinguishes cleanup that required SIGKILL from graceful exit.
Functions ¶
func DefaultLocalStateDir ¶
DefaultLocalStateDir follows the XDG state convention without depending on the current working directory.
func DispatcherConfiguration ¶
DispatcherConfiguration generates the loopback TEST dispatcher profile.
func DispatcherUp ¶
func DispatcherUp(ctx context.Context, assets Assets, options RoleOptions) error
func ExecutorConfiguration ¶
ExecutorConfiguration generates the TEST executor profile for local targets.
func ExecutorUp ¶
func ExecutorUp(ctx context.Context, assets Assets, options RoleOptions) error
func FileNames ¶
FileNames reports how many names a file has. A regular file with more than one is reachable under a name this caller never created and may not be able to see, so ownership applied to it is applied to that name too.
func PrepareRoleDatabase ¶
func PrepareRoleDatabase(ctx context.Context, role storagecheck.Role, dir string) (path string, created bool, err error)
PrepareRoleDatabase creates the role's database on first use and verifies an existing one against the schema versions this build serves. It never migrates: an unsupported database is reported with the action to take. It reports whether this call is the one that created the database. The caller owns the mode-0700 parent directory for the whole call.
Whether creating is allowed is the bootstrap's own decision, not a guess made here: it requires a mode-0700 parent this administrator owns, which is a directory an installation has just made and never one it handed to the service account when it last finished. So an installation interrupted before its database existed can be completed by the next one, a finished directory can have nothing created in it, and no account that could replace the name in between has the directory to do it in.
func RoleDatabase ¶
func RoleDatabase(dir string, role storagecheck.Role) string
RoleDatabase names the database file a role keeps in its state directory.
func Up ¶
func Up(ctx context.Context, assets Assets, options LocalOptions) error
Up runs an installed loopback environment until cancellation. Databases and identity survive clean shutdown; environment.json exists only while ready. A canceled context means a normal stop, provided child cleanup succeeds.
func ValidateControlAddress ¶
ValidateControlAddress accepts the literal-loopback host:port spelling the generated configurations use for the local control plane.
Types ¶
type Assets ¶
func ResolveAssets ¶
ResolveAssets follows the entry-point symlink once, then verifies the exact installed payload. Neither PATH nor the current directory supplies assets.
type BackupManifest ¶ added in v0.3.0
type BackupManifest struct {
SchemaVersion int `json:"schema_version"`
ObservedAt time.Time `json:"observed_at"`
Layout string `json:"layout"`
Package Manifest `json:"package"`
Roles []BackupRole `json:"roles"`
Files map[string]artifact.File `json:"files"`
Protection string `json:"protection"`
History string `json:"history"`
}
func BackupState ¶ added in v0.3.0
func BackupState(ctx context.Context, options BackupOptions) (result BackupManifest, err error)
BackupState snapshots a stopped foreground local environment or role. It never stops a process or opens the source database through SQLite. SQLite recovers/checkpoints the main file and journals together in private staging. Destination must not exist; previous versioned backups are never replaced.
func RestoreState ¶ added in v0.3.0
func RestoreState(ctx context.Context, options RestoreOptions) (result BackupManifest, err error)
RestoreState verifies a backup and publishes a separate, stopped state directory. It preserves identities and old control bindings; it never starts services, replays retained runs, changes a schema or revokes credentials.
type BackupOptions ¶ added in v0.3.0
type BackupRole ¶ added in v0.3.0
type BackupRole struct {
Role storagecheck.Role `json:"role"`
Identity string `json:"identity"`
SchemaVersion int64 `json:"schema_version"`
}
type Child ¶
type Child struct {
// contains filtered or unexported fields
}
Child owns one process group and exactly one cmd.Wait invocation. Closing done publishes waitErr and also joins os/exec's output-copy goroutines.
func StartChild ¶
func (*Child) CleanupComplete ¶
CleanupComplete proves both the controller and direct-child reaper joined, and that the entire tracked process group disappeared. Cache observed group removal so a future unrelated reuse of this numeric PGID cannot change it.
type ChildProcess ¶ added in v0.3.0
type ChildProcess interface {
PID() int
Done() <-chan struct{}
Wait(context.Context) error
Stop(context.Context) error
CleanupComplete() bool
}
ChildProcess owns a child and its process group until CleanupComplete.
type LocalEnvironment ¶
type LocalEnvironment struct {
State string `json:"state"`
Endpoint string `json:"endpoint"`
ExecutorID string `json:"executor_id"`
StateDir string `json:"state_dir"`
}
LocalEnvironment describes the currently running local services.
type LocalOptions ¶
type LocalOptions struct {
StateDir string
Port int
Ready func(LocalEnvironment) error
Logs LogOptions
}
type LogOptions ¶ added in v0.3.0
LogOptions bounds daemon diagnostics separately from measurement results. Zero values select 10 MiB per file, three files and seven days. Age limits are applied when opening or writing a log; a stopped role does not run a background cleanup process. Numbered archives belong to this policy.
type ProcessCleanup ¶ added in v0.3.0
type RestoreOptions ¶ added in v0.3.0
type Result ¶
type RoleEnvironment ¶
type RoleEnvironment struct {
State string `json:"state"`
Role string `json:"role"`
Name string `json:"name"`
Endpoint string `json:"endpoint"`
GRPCAddress string `json:"grpc_address,omitempty"`
YamuxAddress string `json:"yamux_address,omitempty"`
ExecutorID string `json:"executor_id,omitempty"`
StateDir string `json:"state_dir"`
}
RoleEnvironment describes one independently running local service.
type RoleOptions ¶
type RoleOptions struct {
Name, StateDir string
Port, GRPCPort int
Dispatcher connections.Profile
Ready func(RoleEnvironment) error
Logs LogOptions
}
type RoleProcess ¶ added in v0.3.0
type RoleProcess struct {
Role storagecheck.Role
Directory, Executable, ConfigPath, ReadyPath, ExecutorID string
Configuration map[string]any
Stdout, Stderr io.Writer
}
RoleProcess preserves the caller's state layout while sharing config writing, process ownership and PID-bound startup readiness across local launchers.
type RoleState ¶
type RoleState struct {
SchemaVersion int `json:"schema_version"`
Version string `json:"version"`
SourceSHA string `json:"source_sha"`
Identity string `json:"identity"`
Role storagecheck.Role `json:"role"`
// EarlierIdentity is the key earlier builds wrote the identity under. It
// is read when the file carries no identity value and is never written.
EarlierIdentity string `json:"executor_id,omitempty"`
}
RoleState is the persistent identity of one managed role directory. It pins the installed version that created the directory, so a payload the databases were never served by cannot silently adopt them.
func EnsureRoleState ¶
EnsureRoleState reads, or on first use creates, the persistent identity of a role state directory. The caller owns the mode-0700 directory and keeps it under its own control for the duration of the call.
type Supervisor ¶ added in v0.3.0
type Supervisor struct {
// contains filtered or unexported fields
}
Supervisor starts local commands, observes unexpected daemon exits and joins the children in reverse order. The caller serializes StartChild, Stop and Close.
func NewSupervisor ¶ added in v0.3.0
func NewSupervisor(ctx context.Context) *Supervisor
func (*Supervisor) Cancel ¶ added in v0.3.0
func (s *Supervisor) Cancel(cause error)
func (*Supervisor) Close ¶ added in v0.3.0
func (s *Supervisor) Close(ctx context.Context) (ProcessCleanup, error)
func (*Supervisor) Context ¶ added in v0.3.0
func (s *Supervisor) Context() context.Context
func (*Supervisor) Healthy ¶ added in v0.3.0
func (s *Supervisor) Healthy() error
Healthy also observes an exit whose watcher has not yet been scheduled.
func (*Supervisor) Quiesce ¶ added in v0.3.0
func (s *Supervisor) Quiesce()
Quiesce joins exit observers before a frontend begins phased cleanup of its other resources. Close also calls it, so cleanup is safe after partial setup.
func (*Supervisor) StartChild ¶ added in v0.3.0
func (s *Supervisor) StartChild(name string, spec ChildSpec, daemon bool) (ChildProcess, error)
StartChild tracks even a command which later fails. A daemon exit cancels the supervisor context; ordinary command exits belong to the waiting caller.
func (*Supervisor) StartRole ¶ added in v0.3.0
func (s *Supervisor) StartRole(ctx context.Context, role RoleProcess) (ChildProcess, readiness.Record, error)
func (*Supervisor) Stop ¶ added in v0.3.0
func (s *Supervisor) Stop(ctx context.Context, process ChildProcess) error
Stop deliberately stops one tracked child without declaring it an unexpected daemon exit. The child remains tracked until final cleanup joins its group.