35 lines
2.5 KiB
Markdown
35 lines
2.5 KiB
Markdown
# 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.
|