eggup-service 0.2.0

Service registration, ownership, and lifecycle adapters without automatic privilege escalation
Documentation

eggup-service

Manager-neutral service-registration, ownership, state, and lifecycle-snapshot model plus reusable Unix manager mechanics (systemd, launchd, user crontab) and a native Windows SCM adapter.

  • ServiceId / ServiceSpec identify desired registrations with exact executable, arguments, and config evidence.
  • Ownership::{Absent, Owned, Foreign, Unknown} is eggup_core::Ownership: the service crate re-exports the canonical type rather than defining its own, so the two crates denote one type and no conversion exists. Ownership::Owned is never inferred — it is returned only by a caller-proven ownership check. Destructive manager operations are authorized only for Owned; Foreign and Unknown fail closed. CronOwnership is a public type alias of the same canonical type.
  • LifecycleState::{Stopped, Running, Transitioning, Unknown} is distinct from application health (HealthState::{Healthy, Degraded, Unknown}).
  • LifecycleSnapshot preserves pre-update intent (was_running, was_registered) so orchestration can restore "was running" versus "was registered but stopped". Stopped services remain stopped by default.
  • ServiceManager trait plus TestDoubleManager for deterministic tests; HealthProbe seam is consumer-supplied and never mutates manager state.
  • WindowsScmManager uses the safe windows-service SCM wrapper on Windows and a Windows command-line parser for exact executable/argument ownership. Service key name alone never authorizes a mutation; ambiguous registrations are Unknown and foreign registrations are denied.
  • WindowsScmInstall supplies caller-owned display/start/error settings. Creation never starts the service. Optional caller-supplied service or load-order-group dependencies are supported. Refresh preserves service type, unspecified dependencies, account, load-order group, and tag fields outside the adapter's ownership. Account selection is create-time only; custom passwords, descriptions, and recovery actions are not supported by this generic adapter.
  • Windows start/stop/restart polling shares one monotonic deadline per transition. Uninstall reports incomplete while SCM still exposes a marked-for-delete entry and completes only after confirmed absence. Access denial returns bounded remediation and never starts an elevation flow.
  • The native Windows SCM adapter returns typed errors on every path. The SCM's "the service does not exist" (1060) and "the service is marked for deletion" (1072) codes keep their exact meanings — Absent, MarkedForDelete, and the "the service disappeared before the operation" conflict — and every other SCM code becomes a ServiceError::Manager that still carries the raw OS code. No SCM condition panics, and no new error variant or taxonomy was added: the codes are surfaced through the existing ServiceError::Manager / ServiceError::Conflict constructors and the existing ManagerFailureKind set.
  • The native Windows SCM backend is exercised against the real Service Control Manager by a Windows-only fixture (tests/windows_scm_live.rs): it registers a disposable service through the crate's public API and drives install → inspect → ownership → start → stop → uninstall, asserting the windows-service mapping layer explicitly. It removes its own registrations on every exit path, never touches a pre-existing service, waits only under explicit deadlines, and skips with a recorded reason when the runner lacks the administrator rights a real registration needs.
  • windows-service is a Windows-target dependency. windows-args is the small cross-platform parser dependency used for the same ownership tests on Unix.
  • Bounded TransitionResult with conflict diagnostics; no automatic privilege elevation; no updater/release/network policy.
  • Crate-produced service errors and manager stderr excerpts share one declared ceiling, MAX_DIAGNOSTIC_BYTES (512 bytes), truncated only at UTF-8 character boundaries.
  • ServiceError::Manager is a struct variant: it carries a machine-readable ManagerFailureKind (Spawn | Timeout | Permission | NotFound | Protocol | LocalFilesystem), the bounded diagnostic detail, and the platform OS code when the platform supplied a structured one. The kind — not the text — is the carrier of meaning: ServiceError::manager_kind() and ServiceError::manager_os_code() are the programmatic discriminators, and no adapter or helper classifies a failure by substring-matching its own error text. The classification is decided by two pure mapping functions (ManagerFailureKind::from_spawn_error, ManagerFailureKind::from_scm_os_code), so it is assertable on every lane without a real privilege failure, a real spawn, or a wall-clock sleep.
  • Every adapter creates exactly one OperationDeadline per public operation and threads it through every manager invocation that operation makes. No invocation is granted a fresh full budget: the single initial clamp happens at deadline construction and each call receives the remaining budget. start/stop/restart use the caller-supplied timeout; install/uninstall/inspect use the descriptor's transition_timeout for the whole operation.
  • Cron has one ownership rule, stated once and used by inspect, install, and uninstall alike: ownership is decided only by cron_classify, i.e. exact content identity of the managed block body. inspect lists the crontab exactly once, and the pre-write re-listing before a destructive write is retained. An executable-containment gate applies before any listing or mutation: the caller's managed block body must contain spec.executable(), otherwise every cron operation refuses with ServiceError::InvalidInput.
  • commit_with_lifecycle and commit_with_disposition are two orchestrators over one commit-and-rollback engine (commit_engine). The transition, rollback-quiesce, panic-safe-inspect, panic-safe-restore, deadline, and detail-truncation mechanics have a single implementation, and both orchestrators reach it. A desired lifecycle state outside {Running, Stopped} is a typed, bounded failure, never a panic.
  • The two behavioural inputs that used to differ between the former engine copies are named, separately testable policy inputs on CommitEnginePolicy:
    • PostTransitionVerification::Verify (default) re-inspects the manager and validates the observed ownership and state after every transition — a manager's own completed flag is a self-report, not evidence; TrustManagerReport is the explicitly selected non-default input.
    • OwnershipLossTolerance::Deny (default) makes an ownership that is no longer Owned a typed failure; TolerateAlreadyStopped is the explicitly selected non-default input. The selected policy is observable in the returned receipt's engine_policy field.
  • commit_with_lifecycle composes an already validated eggup_core transaction with owned-service quiescence, successful-update restoration, a bounded caller-owned PostInstallCheck, and Core's KeepInstalled / RollBack policy. It requires an existing Owned registration in Running or Stopped state; it never installs or refreshes the registration.
  • commit_with_disposition (M006) generalizes orchestration with a product-neutral UpdateRuntimeDisposition::{ManagedRunning, ManagedStopped, DirectRunning, Stopped, ForeignPreserved}. Artifact commit authority and manager mutation authority are separate facts: ForeignPreserved performs zero manager mutation, DirectRunning uses only the caller-owned DirectRuntimeControl seam (exact instance/config, bounded deadlines, no health-protocol content), and Stopped fabricates no restart. Pure plan_unix / plan_windows planners reproduce the reference decision matrix without native managers. The disposition observed after preparation is revalidated immediately before mutation; owned-to-foreign/unknown or direct-identity changes fail before destructive action with zero further mutation.
  • With RestoreIntent::Preserve, a stopped service stays stopped after success. RestoreIntent only controls the successful new generation; after a successful artifact rollback, orchestration restores the pre-update running/stopped state. If Core reports RecoveryRequired, it does not automatically start the service against uncertain artifacts.
  • The post-install check receives the remaining shared deadline and must finish within it. Existing HealthProbe has no timeout contract and alone does not meet this bound. Application health semantics remain caller-owned.
  • M003 hardening: each start/stop/restart validates one monotonic caller deadline shared by ownership queries, manager commands, and state polling. Zero transition timeouts are rejected; expiry is returned as an incomplete transition or a manager timeout.
  • Production SystemExecutor resolves systemctl, launchctl, and crontab only from fixed absolute platform paths, never ambient PATH. It clears the child environment; only user-scoped systemd retains DBUS_SESSION_BUS_ADDRESS, XDG_RUNTIME_DIR, and SYSTEMD_BUS_ADDRESS when present.
  • ManagerCommandOutput is the bounded output of one manager command invocation. The former CommandOutput spelling survives as a type alias to it, so existing CommandExecutor implementations written against either spelling still satisfy the trait. The alias is deliberately not deprecated; its disposition is settled at the intentional 0.2/1.0 API boundary.
  • systemd/launchd config ownership is proven by one exact config path occurrence in canonical argv. Missing identity is Foreign; repeated/ambiguous identity is Unknown.
  • M002 Unix adapters (SystemdManager, LaunchdManager, CronManager) implement ServiceManager on top of the M001 contract:
    • shared bounded command runner (literal argv, no shell, null/controlled stdin, bounded output, deadline with kill/reap, injectable FakeExecutor for tests); the bounded execution itself is delegated to eggup_core::run_bounded, while this crate's own pre-flight — the allowlisted absolute program path, the cleared environment, the bounded stdin payload, and the timeout range — stays in front of that call and is unchanged;
    • systemd: explicit --system/--user scope, narrow ExecStart parsing (ambiguous/specifier shapes yield Unknown), atomic definition writes, explicit enable/daemon-reload only, bounded start/stop/restart with state confirmation, no sudo; a recognized exact-owned failed unit is stopped only after ownership revalidation and proof that its manager job, main/control processes, and cgroup work are gone;
    • launchd: explicit gui/<uid> vs system targets (never guessed), structured ProgramArguments parsing (malformed yields Unknown), label-only never proves ownership, bounded bootstrap/bootout/ kickstart/stop, foreign labels fail closed;
    • cron: managed # BEGIN/# END <marker> block (caller-owned marker + exact block), pure cron_merge/cron_remove preserving unrelated bytes, idempotent install, owned-only removal, no redundant crontab - writes, re-read before destructive writes to expose races, explicit "no start/stop semantics" errors, one listing per inspect, one ownership rule, and the executable-containment gate on the destructive paths;
    • atomic_write_definition (same-dir exclusive temp, owner-safe mode, fsync, no-replace vs overwrite authority, owned-temp-only cleanup, never creates privileged parents);
    • inspect_host facts vs candidate_managers policy (Linux systemd or cron; macOS launchd or cron; detection failure distinct from absent).
  • Ownership for systemd/launchd uses exact executable plus critical args and reconciles optional config identity against those exact args. Consumer unit/plist bodies, usernames, paths, hardening text, health checks, and CLI messages stay consumer-owned. No consumer is migrated here.
  • The crate's public API surface is guarded locally. Every public item is bound to an explicit type in tests/public_api_surface.rs, so a removed item or a changed signature is a compilation error in the crate's own test gate. The committed snapshot tests/public-api-surface.txt is the reviewable artifact: it is maintained by hand, and a change to it, or to the guard, is a deliberate, separately reviewed edit. The guard adds no dependency and changes no public API.