service

import "github.com/jbcom/radioactive-ralph/internal/service"

Package service manages per-user OS service units for radioactive-ralph.

Platform dispatch:

• macOS → launchd user agent (~/Library/LaunchAgents/jbcom.radioactive-ralph.<variant>.plist)

• Linux/WSL → systemd user unit (~/.config/systemd/user/radioactive_ralph-<variant>.service)

• Homebrew → brew-services wrapper (invokes the launchd/systemd path)

Gating:

• Variants with SafetyFloors.RefuseServiceContext = true refuse to install. Running savage/old-man/world-breaker under a service manager is operator malpractice (they burn money or force-push repos; neither should be on a cron).

• Variants with a confirmation gate require the operator to have passed the gate flag to `radioactive_ralph service install` explicitly.

Service-context detection at `radioactive_ralph run` time uses:

• LAUNCHED_BY=launchd (our own plist sets this)

• INVOCATION_ID set (systemd user services set this)

• RALPH_SERVICE_CONTEXT=1 (manual override for tests)

Supervisor refuses to spawn a RefuseServiceContext variant when any of those are set.

Index

• Variables

• func Install(opts InstallOptions) (path string, err error)

• func IsServiceContext() bool

• func Uninstall(opts InstallOptions) error

• func UnitName(b Backend, v variant.Name) string

• func UnitPath(b Backend, home string, v variant.Name) string

• type Backend

  • func DetectBackend() Backend

• type InstallOptions

Variables

ErrGateNotConfirmed is returned when a gated variant is installed without GateConfirmed=true.

var ErrGateNotConfirmed = errors.New("service: gated variant requires explicit confirmation")

ErrMissingRalphBin is returned when RalphBin is empty.

var ErrMissingRalphBin = errors.New("service: RalphBin required")

ErrRefuseServiceContext is returned when the variant pins RefuseServiceContext=true.

var ErrRefuseServiceContext = errors.New("service: variant refuses to run in a service context")

ErrUnsupportedBackend is returned for platforms we don’t manage.

var ErrUnsupportedBackend = errors.New("service: unsupported platform")

func Install

func Install(opts InstallOptions) (path string, err error)

Install writes the unit file for the given variant. Does not load it into launchd/systemd — callers do that via `radioactive_ralph service start` to keep Install a pure filesystem operation (trivial to test and to undo).

func IsServiceContext

func IsServiceContext() bool

IsServiceContext reports whether the current process looks like it’s running under a service manager (launchd / systemd –user). Checked in pre-flight before spawning a RefuseServiceContext variant.

func Uninstall

func Uninstall(opts InstallOptions) error

Uninstall removes the unit file. Returns nil if already absent.

func UnitName

func UnitName(b Backend, v variant.Name) string

UnitName returns the canonical service unit name for a variant. launchd: “jbcom.radioactive-ralph.green” systemd: “radioactive_ralph-green”

func UnitPath

func UnitPath(b Backend, home string, v variant.Name) string

UnitPath returns the on-disk path where the unit file will be written. Callers pass the operator’s home dir (tests inject a tmpdir).

type Backend

Backend identifies which platform mechanism is in use.

type Backend string

const (
    // BackendLaunchd is macOS per-user launchd agent.
    BackendLaunchd Backend = "launchd"
    // BackendSystemdUser is Linux/WSL systemd user unit.
    BackendSystemdUser Backend = "systemd-user"
    // BackendUnsupported is returned for platforms we don't manage.
    BackendUnsupported Backend = "unsupported"
)

func DetectBackend

func DetectBackend() Backend

DetectBackend returns the appropriate backend for the current OS.

type InstallOptions

InstallOptions configures an install.

type InstallOptions struct {
    // Backend overrides the detected platform. Empty = detect.
    Backend Backend
    // HomeDir overrides os.UserHomeDir. Empty = use os.UserHomeDir().
    HomeDir string
    // RalphBin is the absolute path to the radioactive_ralph binary that
    // the unit should exec. Required.
    RalphBin string
    // RepoPath is the operator's repo — written into the unit as the
    // working directory for the daemon.
    RepoPath string
    // Variant is the variant profile to install for. Required.
    Variant variant.Profile
    // GateConfirmed must be true when Variant has a ConfirmationGate.
    // Enforces "operator explicitly passed --confirm-X to
    // radioactive_ralph service install" so gates aren't bypassed via
    // the service wrapper.
    GateConfirmed bool
    // ExtraEnv is merged into the unit's environment block. Callers use
    // this for RALPH_SPEND_CAP_USD etc.
    ExtraEnv map[string]string
}

Generated by gomarkdoc