1 Daemon Lifecycle

Virgil edited this page 2026-03-11 12:05:31 +00:00

Table of Contents

• Daemon Lifecycle
• Overview
• Lifecycle
• Start()
• Run(ctx)
• Stop()
• Registry
• Health Server

Daemon Lifecycle

Module: forge.lthn.ai/core/go-process

Overview

The Daemon struct orchestrates three concerns: single-instance enforcement (PID file), health monitoring (HTTP server), and fleet tracking (registry).

Lifecycle

NewDaemon(opts) -> Start() -> SetReady(true) -> Run(ctx) -> [ctx cancelled] -> Stop()

Start()

1. Acquire PID file (fails if another instance holds it)
2. Start health server (HTTP /health + /ready)
3. Auto-register in daemon registry (if configured)

Run(ctx)

Blocks until ctx.Done(), then calls Stop().

Stop()

1. Set readiness to false (health server returns 503)
2. Graceful shutdown of health server (with timeout)
3. Release PID file
4. Unregister from daemon registry

Registry

Registry tracks daemons via JSON files in a directory (default ~/.core/daemons/).

File naming: {code}-{daemon}.json (slashes replaced with dashes).

Each file contains:

{
  "code": "myapp",
  "daemon": "server",
  "pid": 12345,
  "health": "127.0.0.1:9090",
  "started": "2026-03-10T12:00:00Z"
}

List() and Get() automatically prune entries whose PIDs are no longer alive (checked via kill -0).

Health Server

Endpoints:

• GET /health — Runs all registered HealthCheck functions. Returns 200 if all pass, 503 if any fail.
• GET /ready — Returns 200 when SetReady(true), 503 otherwise.

WaitForHealth(addr, timeoutMs) polls /health every 200ms until 200 or timeout.