launcher

Documentation

Overview

Package launcher manages the optional OS-backed worker launcher.

Index

• Constants
• Variables
• func Delete(path string) error
• func IsEnabled() bool
• func Kickstart(ctx context.Context, target string) error
• func List(repoRoot string) ([]string, error)
• func MarkerPath(repoRoot, checkpointID string) string
• func PendingDir(repoRoot string) string
• func SettingsPath() (string, error)
• func UnitPath() (string, error)
• func UnitTarget() string
• func UserDomain() string
• func WorkerLogPath() (string, error)
• func Write(m Marker) error
• func WriteSettings(s UserSettings) error
• type DisableResult
  • func Disable(ctx context.Context) (*DisableResult, error)
• type InstallResult
  • func Enable(ctx context.Context, binaryPath string) (*InstallResult, error)
• type LauncherSettings
  • func (s LauncherSettings) MarshalJSON() ([]byte, error)
  • func (s *LauncherSettings) UnmarshalJSON(data []byte) error
• type Marker
  • func Read(path string) (Marker, error)
  • func ReadInQueue(repoRoot, path string) (Marker, error)
  • func (m Marker) Validate() error
• type StatusResult
  • func Status(ctx context.Context) (StatusResult, error)
• type UserSettings
  • func ReadSettings() (UserSettings, error)

Constants

const LabelWorker = "sh.semantica.worker"

LabelWorker is the worker service label, used as the launchd plist label, the systemd unit base name, and the Task Scheduler task name. Same identifier across all backends so diagnostics stay consistent.

Variables

var ErrUnsupportedOS = errors.New("launcher: unsupported OS")

ErrUnsupportedOS reports that the launcher has no backend on the current OS.

Functions

func Delete

func Delete(path string) error

Delete removes a marker file. Missing files are ignored.

func IsEnabled

func IsEnabled() bool

IsEnabled reports whether the launcher is enabled. Read errors fall back to false so hook-side callers do not break commits.

func Kickstart

func Kickstart(ctx context.Context, target string) error

Kickstart triggers an on-demand activation of the worker unit. The target argument is the systemd unit name; honors the caller-supplied target rather than deriving its own so callers retain control over which unit is started.

func List

func List(repoRoot string) ([]string, error)

List returns committed marker paths in lexical order. A missing directory is treated as empty.

func MarkerPath

func MarkerPath(repoRoot, checkpointID string) string

MarkerPath returns the canonical marker path.

func PendingDir

func PendingDir(repoRoot string) string

PendingDir returns <repoRoot>/.semantica/pending.

func SettingsPath

func SettingsPath() (string, error)

SettingsPath returns the launcher settings path. It honors SEMANTICA_HOME via broker.GlobalBase.

func UnitPath

func UnitPath() (string, error)

UnitPath returns the systemd user unit path for the worker. Honors XDG_CONFIG_HOME via os.UserConfigDir; falls back to $HOME/.config when XDG_CONFIG_HOME is unset.

func UnitTarget

func UnitTarget() string

UnitTarget returns the systemd unit name. systemctl --user accepts this string as the unit argument.

func UserDomain

func UserDomain() string

UserDomain returns the empty string on Linux. The systemd user instance has no analog to launchctl's gui/<uid> tuple; the systemctl --user invocation is the access point.

func WorkerLogPath

func WorkerLogPath() (string, error)

WorkerLogPath returns the launcher worker log path. Cross-platform.

func Write

func Write(m Marker) error

Write atomically persists a marker to the pending directory.

func WriteSettings

func WriteSettings(s UserSettings) error

WriteSettings atomically writes the user-level settings file.

Types

type DisableResult

type DisableResult struct {
	// WasEnabled reflects the settings flag prior to disable.
	WasEnabled bool

	// RemovedUnitPath is the unit/plist/task path that was
	// removed, if any. Empty when no file was on disk.
	RemovedUnitPath string
}

DisableResult describes the outcome of a Disable call.

func Disable

func Disable(ctx context.Context) (*DisableResult, error)

Disable unregisters the worker, removes the unit/plist/task file, and clears the launcher settings. Idempotent. Returns ErrUnsupportedOS on platforms without a launcher backend.

type InstallResult

type InstallResult struct {
	// UnitPath is the installed unit/plist/task path.
	UnitPath string

	// UnitTarget is the OS-specific service identifier.
	UnitTarget string

	// Reinstalled reports whether a previous service was already
	// loaded at the time of install.
	Reinstalled bool
}

InstallResult describes a successful Enable or reinstall.

func Enable

func Enable(ctx context.Context, binaryPath string) (*InstallResult, error)

Enable installs the worker, registers it with the OS daemon manager, and records the enabled state in user settings. The OS-specific work runs through the active manager backend; on platforms without one, this returns ErrUnsupportedOS.

The backend check runs before binary-path validation so the "unsupported OS" contract holds for callers that use errors.Is(err, ErrUnsupportedOS): a non-darwin host returns ErrUnsupportedOS regardless of whether the supplied path is absolute or exists.

type LauncherSettings

type LauncherSettings struct {
	// Enabled reports whether the launcher is enabled.
	Enabled bool `json:"enabled"`

	// InstalledUnitPath is the launcher install path written by
	// Enable. The JSON tag is "installed_unit_path"; the legacy
	// "installed_plist_path" key is handled by the dual-key
	// MarshalJSON / UnmarshalJSON below.
	InstalledUnitPath string `json:"installed_unit_path,omitempty"`

	// InstalledAt is the enable-time Unix millisecond timestamp.
	InstalledAt int64 `json:"installed_at,omitempty"`
}

LauncherSettings records the launcher's installed state.

The canonical on-disk install-path key is "installed_unit_path". During the transition, the legacy "installed_plist_path" key is also written with the same value, and the read path accepts either key.

func (LauncherSettings) MarshalJSON

func (s LauncherSettings) MarshalJSON() ([]byte, error)

MarshalJSON writes both install-path keys with the same value while the legacy key is still supported.

func (*LauncherSettings) UnmarshalJSON

func (s *LauncherSettings) UnmarshalJSON(data []byte) error

UnmarshalJSON reads both install-path keys and prefers installed_unit_path when it is present, even if it is the empty string. A nil pointer means the key was absent or null, so the legacy installed_plist_path fallback applies.

Conflicting non-empty values resolve to the canonical key. The next WriteSettings overwrites both keys with the canonical value, so the conflict cannot persist past one read/write cycle.

type Marker

type Marker struct {
	// CheckpointID also becomes the filename stem.
	CheckpointID string `json:"checkpoint_id"`

	// CommitHash is the linked commit.
	CommitHash string `json:"commit_hash"`

	// RepoRoot is the absolute repository path.
	RepoRoot string `json:"repo_root"`

	// WrittenAt is the hook-side Unix millisecond timestamp.
	WrittenAt int64 `json:"written_at"`
}

Marker is the handoff written by the hook and read by the drain command.

func Read

func Read(path string) (Marker, error)

Read loads and validates one marker. Use ReadInQueue when the caller discovered the file from a specific queue directory.

func ReadInQueue

func ReadInQueue(repoRoot, path string) (Marker, error)

ReadInQueue loads a marker and checks that it matches the queue it came from.

func (Marker) Validate

func (m Marker) Validate() error

Validate checks the on-disk marker contract. RepoRoot uses the host OS's absolute-path rules. Plist paths stay POSIX-only because launchd consumes them directly.

type StatusResult

type StatusResult struct {
	// OS is the runtime.GOOS value at the time of the call.
	OS string

	// SettingsEnabled is the launcher.enabled flag from settings.json.
	SettingsEnabled bool

	// InstalledUnitPath is the unit/plist/task path recorded in
	// settings.
	InstalledUnitPath string

	// InstalledAt is the enable-time Unix millisecond timestamp.
	InstalledAt int64

	// SettingsError is set when the settings file exists but could
	// not be read cleanly.
	SettingsError string

	// ExpectedUnitPath is the canonical unit/plist/task path for
	// the current user.
	ExpectedUnitPath string

	// UnitOnDisk reports whether the unit/plist/task file exists
	// at the recorded or expected path.
	UnitOnDisk bool

	// UnitTarget is the OS-specific service identifier.
	UnitTarget string

	// LoadedInDaemon reports whether the OS daemon manager has the
	// service registered.
	LoadedInDaemon bool

	// ServiceState is a short summary of what the OS daemon manager
	// reported:
	//   - "loaded"       : service is registered
	//   - "not loaded"   : service is not registered
	//   - "unsupported"  : no launcher backend on this OS
	//   - "error: <msg>" : daemon-manager call failed
	ServiceState string

	// LogPath is the launcher worker log path.
	LogPath string
}

StatusResult describes launcher state as reported by settings, the unit/plist/task file on disk, and the OS daemon manager.

func Status

func Status(ctx context.Context) (StatusResult, error)

Status gathers launcher state from settings, the filesystem, and the OS daemon manager. Non-fatal problems are encoded into StatusResult so the caller can render a coherent view even when one source disagrees with another.

type UserSettings

type UserSettings struct {
	Launcher LauncherSettings `json:"launcher,omitempty"`
}

UserSettings is the user-level settings file at $HOME/.semantica/settings.json.

func ReadSettings

func ReadSettings() (UserSettings, error)

ReadSettings loads the user-level settings file. A missing file returns the zero value. A malformed file returns an error.