demo

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package demo owns the disposable installed local measurement.

Index

Constants

View Source
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.

View Source
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

View Source
var ErrForcedKill = errors.New("demo child required forced termination")

ErrForcedKill distinguishes cleanup that required SIGKILL from graceful exit.

Functions

func DefaultLocalStateDir

func DefaultLocalStateDir() (string, error)

DefaultLocalStateDir follows the XDG state convention without depending on the current working directory.

func DispatcherConfiguration

func DispatcherConfiguration(version, db string) map[string]any

DispatcherConfiguration generates the loopback TEST dispatcher profile.

func DispatcherUp

func DispatcherUp(ctx context.Context, assets Assets, options RoleOptions) error

func ExecutorConfiguration

func ExecutorConfiguration(version, id, db string, record readiness.Record) map[string]any

ExecutorConfiguration generates the TEST executor profile for local targets.

func ExecutorUp

func ExecutorUp(ctx context.Context, assets Assets, options RoleOptions) error

func FileNames

func FileNames(info fs.FileInfo) (uint64, bool)

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

func ValidateControlAddress(address string) error

ValidateControlAddress accepts the literal-loopback host:port spelling the generated configurations use for the local control plane.

func WriteConfig

func WriteConfig(path string, config map[string]any) error

WriteConfig writes a generated configuration to an absent path, mode 0600.

Types

type Assets

type Assets struct {
	Root, CLI, Dispatcher, Executor, Guest string
	Manifest                               Manifest
}

func ResolveAssets

func ResolveAssets(executable string) (Assets, error)

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 BackupOptions struct {
	StateDir, Destination string
	// Offline acknowledges that no unmanaged daemon is writing this directory.
	// A completed foreground shutdown receipt and its free lock are also required.
	Offline bool
	Package Manifest
}

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 StartChild(spec ChildSpec) (*Child, error)

func (*Child) CleanupComplete

func (c *Child) CleanupComplete() bool

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.

func (*Child) Done

func (c *Child) Done() <-chan struct{}

func (*Child) PID

func (c *Child) PID() int

func (*Child) Stop

func (c *Child) Stop(ctx context.Context) error

Stop starts teardown once. The first caller owns its bounded controller; other callers can join it with their own context. No stop goroutine outlives its caller. Done alone describes the direct child, not its process group.

func (*Child) Wait

func (c *Child) Wait(ctx context.Context) error

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 ChildSpec

type ChildSpec struct {
	Path, Dir      string
	Args, Env      []string
	Stdout, Stderr io.Writer
}

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

type LogOptions struct {
	MaxBytes int64
	Files    int
	MaxAge   time.Duration
}

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 Manifest

type Manifest = artifact.Manifest

type ProcessCleanup added in v0.3.0

type ProcessCleanup struct {
	Joined      bool
	ForcedKills int
}

type RestoreOptions added in v0.3.0

type RestoreOptions struct {
	BackupDir, StateDir string
	Package             Manifest
}

type Result

type Result struct {
	Version    string `json:"version"`
	ExecutorID string `json:"executor_id"`
	RunID      string `json:"run_id"`
	Response   string `json:"response"`
	State      string `json:"state"`
	Cleanup    string `json:"cleanup"`
}

func Run

func Run(ctx context.Context, assets Assets) (Result, error)

Run verifies the installed assets, runs one wallet-free local measurement, and joins all owned processes and callbacks before reporting success.

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

func EnsureRoleState(dir string, role storagecheck.Role, manifest Manifest) (RoleState, error)

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 (*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.

Directories

Path Synopsis
Package service installs a verified Debuglet role payload as a service the host's service manager supervises.
Package service installs a verified Debuglet role payload as a service the host's service manager supervises.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL