Architecture and Runtime Flow

Overview

The agent is an async HTTP server (axum) listening on a Unix domain socket and exposes a small JSON API to manage nginx configuration fragments.
Core lifecycle is implemented in apps/agent/src/main.rs:
- parse CLI args and environment variables
- ensure the socket path and directory exist and have permissive but secure defaults
- bind a tokio::net::UnixListener to the socket
- create an NginxService (shared state) and an in-process cron JobScheduler
- mount axum routes (/status, /validate, /validate_and_reload, /write_config) and serve HTTP over the Unix socket

Key components

main.rs — Bootstrapping, argument handling, socket setup and permission handling, scheduler start, and axum server startup.
routes.rs — axum handlers for the HTTP API. It deserializes JSON payloads and delegates to NginxService methods. Handlers return appropriate HTTP status codes and JSON on error or success.
commands/ — Implementation of lower-level actions (writing fragment files, running nginx -t, validating, reloads). The validate.rs command contains sophisticated behavior to handle permission-limited environments by:
- creating wrapper nginx configs that include a single fragment
- trying nginx -t directly, attempting a privileged wrapper via sudo if available, and finally passing a writable PID override via -g pid ...; to avoid permission failures

Concurrency and state

A single shared NginxService instance is stored in axum State and cloned into handlers; it holds the scheduler and the configured nginx config directory path.
The JobScheduler is created with tokio_cron_scheduler::JobScheduler and started before serving requests.

Error handling and best-effort behavior

Socket permission changes, GID changes, and directory creations are best-effort and log warnings on failure rather than failing hard.
Most command failures are converted into JSON errors with appropriate HTTP status codes so callers can inspect command output.

Integration and packaging

The agent is intended to run as a companion to the API server in apps/api. The API calls the agent over the unix socket to write fragments, validate them, and trigger reloads.
apps/agent/Dockerfile builds a runtime image that includes nginx and the yanpm-agent binary (the Dockerfile uses s6-overlay to run multiple services). This image is suitable for deployments that prefer nginx and the agent colocated in a single container.