Management API (honmoon-mgmt)
Relevant source files
The following files were used as context for generating this wiki page:
The honmoon-mgmt module provides the in-process management and observation layer for the Honmoon data plane. It is implemented as an asynchronous service using the axum framework, running alongside the core proxy to facilitate real-time monitoring and administrative actions. Its primary responsibilities include exposing the internal audit log, managing pending request approvals, and serving an embedded React-based dashboard.
Within the broader project architecture, honmoon-mgmt acts as the interface between the low-level data plane (honmoon-proxy) and the user-facing control plane. It shares state with the proxy via an atomic reference-counted (Arc) GatewayState, allowing it to resolve held connections and access in-memory audit buffers.
Core Architecture and Data Flow
The management API is designed to be tightly coupled with the data plane for performance and immediate consistency, yet it maintains a clean boundary by interacting only with shared state objects. It runs on a dedicated port (defaulting to :8444) separate from the main gateway proxy.
The diagram shows the relationship between the proxy, the management API, and the shared state components.
Sources: wiki/deep-dive/control-plane.md:15-32, crates/honmoon-mgmt/src/lib.rs:40-60
API Endpoints
The API exposes several RESTful endpoints for observability and control. All endpoints under the /api prefix return JSON responses.
Administrative Endpoints
| Route | Method | Description |
|---|---|---|
/api/audit | GET | Returns the most recent audit events from the in-memory ring buffer. Supports a limit parameter (max 1000). |
/api/approvals | GET | Lists all requests currently held in the "pause" state awaiting human intervention. |
/api/approvals/:id/approve | POST | Signals the proxy to allow a previously held request to proceed to the upstream destination. |
/api/approvals/:id/reject | POST | Signals the proxy to terminate a held request and return a 403 Forbidden to the client. |
/api/policy | GET | Returns the active policy configuration in both raw YAML and parsed JSON formats. |
/healthz | GET | Standard health check endpoint returning a simple "ok" status. |
Sources: crates/honmoon-mgmt/src/lib.rs:77-134, wiki/deep-dive/control-plane.md:45-56
Approval Workflow Sequence
When a policy rule triggers a pause verdict, the management API is the mechanism used to resolve the hold.
This sequence illustrates the interaction between the data plane and the management API during a manual approval process.
Sources: wiki/deep-dive/control-plane.md:85-103, crates/honmoon-mgmt/src/lib.rs:104-121
Embedded Dashboard
One of the unique features of honmoon-mgmt is that it serves a full React single-page application (SPA) directly from the Rust binary. This is achieved using the rust-embed crate, which includes the dashboard's build artifacts in the final executable.
Serving Logic
The API uses a fallback mechanism to serve the SPA. If a request does not match a defined API route, the server attempts to serve a file from the embedded assets. If the path does not exist as a static file, it falls back to index.html to allow React Router to handle client-side navigation.
// Static asset embedding in honmoon-mgmt
#[derive(RustEmbed)]
#[folder = "../../apps/dashboard/dist"]
struct Assets;
// Fallback logic for SPA routing
async fn static_handler(uri: Uri) -> impl IntoResponse {
let path = uri.path().trim_start_matches('/');
if path.is_empty() || path == "index.html" {
return index_html().await;
}
// ... logic to serve specific files (JS, CSS) ...
}
Sources: crates/honmoon-mgmt/src/lib.rs:30-36, crates/honmoon-mgmt/src/lib.rs:138-168
Build-time Safety
To ensure cargo build succeeds even if the dashboard hasn't been built yet, honmoon-mgmt includes a build.rs script. This script checks for the existence of the dist/index.html file and creates a placeholder if it is missing, preventing compilation errors during initial setup or in environments without Node.js.
Sources: crates/honmoon-mgmt/build.rs:1-36
Integration with honmoon-cli
The management service is initialized and started by the honmoon-cli when the gateway command is executed. The CLI handles the configuration of the management port and passes the shared GatewayState into the honmoon_mgmt::serve function.
| Configuration Item | Default Value | Description |
|---|---|---|
| Mgmt Address | 127.0.0.1:8444 | The bind address and port for the management API and dashboard. |
| Audit Log Path | (optional) | Path to the JSONL file; the API reads from memory, but the proxy writes to this file. |
Sources: crates/honmoon-cli/src/main.rs:78-128, wiki/deep-dive/control-plane.md:40-42
Summary
The honmoon-mgmt crate provides the essential human-in-the-loop capabilities required for a policy-based firewall. By exposing in-memory state through a standard REST API and embedding a modern dashboard, it allows operators to observe agent behavior and intervene in high-risk actions without requiring external database dependencies or complex management infrastructure.