Documentation
¶
Overview ¶
Package daemon provides helpers for daemonizing the boid server process. It implements a self-re-exec pattern: the parent spawns a copy of itself with BOID_DAEMON_CHILD=1, waits for the UNIX socket to become ready, and then exits. The child redirects stdin/stdout/stderr to a log file, calls syscall.Setsid to detach from the terminal session, and runs the server.
Index ¶
- Variables
- func ApplyLogLevel(level string)
- func CloseStartupFD3()
- func IsChild() bool
- func IsSocketAlive(socketPath string, timeout time.Duration) bool
- func LogFilePath() string
- func RedirectToLog(logPath string) error
- func RedirectToLogRotating(logPath string) error
- func ShouldLogToStdout() bool
- func Spawn(args []string) (int, *os.File, error)
- func WriteStartupStatusOnFD3(err error)
- type StartupStatus
- type StartupStatusKind
Constants ¶
This section is empty.
Variables ¶
var ErrStartupOK = errors.New("daemon startup succeeded")
ErrStartupOK is returned by ReadStartupStatus when the child closed fd 3 without writing a payload — i.e. the daemon started successfully.
Functions ¶
func ApplyLogLevel ¶ added in v0.1.0
func ApplyLogLevel(level string)
ApplyLogLevel sets the daemon process's slog output level from config.yaml's log.level, called once from cmd/start.go's runDaemonChild right after the log file redirect is in place.
It calls only slog.SetLogLoggerLevel, never slog.SetDefault — see internal/config.LogConfig's doc comment for why: that keeps boid.log's line format untouched, since SetLogLoggerLevel only moves the threshold slog's default handler compares against, not how a record is formatted.
level == "" is a deliberate no-op (slog's built-in default level stands). An unrecognized level should be unreachable — config.Load already validates it at startup — but is handled defensively with a warning rather than aborting an otherwise-healthy daemon.
func CloseStartupFD3 ¶ added in v0.0.8
func CloseStartupFD3()
CloseStartupFD3 closes fd 3 without writing a payload. The parent observes EOF on its read-end and treats it as success. Best-effort, and a no-op unless Spawn actually wired the pipe (see statusPipeEnvKey).
func IsSocketAlive ¶
IsSocketAlive reports whether something is actively listening on socketPath. It returns true if a UNIX domain socket can be dialed within timeout, which distinguishes a running server from a stale socket file (ECONNREFUSED) or missing socket file (ENOENT).
func LogFilePath ¶
func LogFilePath() string
LogFilePath returns the path for the daemon log file. Uses $XDG_STATE_HOME/boid/boid.log, falling back to ~/.local/state/boid/boid.log.
func RedirectToLog ¶
RedirectToLog opens logPath (O_APPEND|O_CREATE|O_WRONLY, 0o644), creates the parent directory if necessary, and replaces file descriptors 0, 1, and 2:
- fd 0 (stdin) → /dev/null
- fd 1 (stdout) → logPath
- fd 2 (stderr) → logPath
func RedirectToLogRotating ¶
RedirectToLogRotating is the size-rotating variant of RedirectToLog. It creates an OS pipe, redirects stdin to /dev/null, and redirects stdout and stderr to the pipe write-end. A background goroutine copies from the pipe read-end into a logrotate.Writer so the log is rotated automatically when it grows past MaxSize.
The goroutine exits (and closes the writer) when all write-ends of the pipe are closed, which happens naturally when the process exits.
func ShouldLogToStdout ¶ added in v0.1.0
func ShouldLogToStdout() bool
ShouldLogToStdout reports whether the daemon child should skip RedirectToLogRotating and syscall.Setsid — see logStdoutEnvKey's doc comment for why.
func Spawn ¶
Spawn forks a daemon child by re-executing the current binary with the same arguments and with BOID_DAEMON_CHILD=1 added to the environment.
It also wires a one-shot status pipe on the child's fd 3 so the child can surface its startup outcome to the parent without depending on log file scraping. The parent receives the read-end (statusR): EOF means the child closed fd 3 without writing (successful startup); a JSON payload (see startup_status.go) means startup failed.
Spawn closes its own copy of the write-end before returning so that EOF arrives at statusR even if the child exits without explicitly closing fd 3 (e.g. crash). The caller is responsible for closing statusR.
func WriteStartupStatusOnFD3 ¶ added in v0.0.8
func WriteStartupStatusOnFD3(err error)
Types ¶
type StartupStatus ¶ added in v0.0.8
type StartupStatus struct {
Kind StartupStatusKind `json:"kind"`
Message string `json:"message,omitempty"` // populated when Kind == other
}
StartupStatus is the JSON payload the daemon child writes on fd 3 when startup fails. On success the child closes fd 3 without writing — the parent observes EOF (ReadStartupStatus returns ErrStartupOK).
func ReadStartupStatus ¶ added in v0.0.8
func ReadStartupStatus(r io.Reader) (*StartupStatus, error)
ReadStartupStatus decodes a StartupStatus from r. EOF (the child closed fd 3 without writing) is returned as ErrStartupOK so callers can branch cleanly on success vs structured failure.
type StartupStatusKind ¶ added in v0.0.8
type StartupStatusKind string
StartupStatusKind discriminates the payload variants written on fd 3.
const ( // StartupKindOther indicates a startup failure with no structured // remediation path. The parent prints Message and points the user at // the log file. StartupKindOther StartupStatusKind = "other" )