Request Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Request Lifecycle in Honmoon describes the end-to-end journey of a network request from an AI agent through the Honmoon gateway to its final destination. Honmoon acts as a policy-enforcing intermediary that intercepts outbound traffic to apply security verdicts—allow, deny, or pause (human approval)—based on a combination of egress domain filtering and protocol-aware inspection.
This lifecycle is distributed across three primary crates: honmoon-proxy (handling the TCP/HTTP CONNECT connection), honmoon-core (extracting facts and making policy decisions), and honmoon-mgmt (handling audit logging and approval holds). The architecture ensures a "fail-closed" posture, meaning any failure in the lifecycle or an unmatched request results in a deny verdict by default.
Connection Interception and Fact Extraction
The lifecycle begins when an AI agent initiates a connection. Honmoon primarily operates as a CONNECT egress proxy in Phase 1. The gateway intercepts the connection, reads the request head, and canonicalizes the target host to begin building a Facts object.
Fact Construction
Facts are extracted at the network and protocol layers. In the current implementation, the proxy primarily builds facts based on the domain and host. However, the system is designed to support deep protocol parsing for SQL and Kubernetes as traffic-driven relay capabilities are introduced.
| Source Layer | Fact Type | Extracted Information |
|---|---|---|
| Network | Domain | The canonicalized host from the CONNECT request |
| HTTP | HttpFacts | Method, host, path, and body size (requires TLS termination) |
| SQL | SqlFacts | Verb (e.g., DROP, SELECT) and extracted table names |
| Kubernetes | K8sFacts | Verb (e.g., list, delete), resource type, and namespace |
Sources: wiki/deep-dive/architecture.md, crates/honmoon-proxy/src/gateway.rs:81-92, wiki/deep-dive/protocol-parsing.md
Protocol Parsing Logic
When protocol bytes are available, the gateway utilizes specialized parsers in honmoon-core::protocols. For example, the SQL parser uses a heuristic to identify dangerous verbs and target tables, while the Kubernetes parser maps HTTP methods and API paths to specific K8s actions.
Sources: wiki/deep-dive/protocol-parsing.md, crates/honmoon-core/src/protocols.rs:111-156
The Decision Algorithm
Once facts are extracted, they are passed to the decide() function in the policy engine. The engine follows a strict order of precedence to reach a Verdict.
Decision Flow
- Rule Evaluation: The engine iterates through defined protocol rules in order. It evaluates CEL (Common Expression Language) conditions against the provided facts. The first matching rule determines the verdict.
- Egress Matching: If no protocol rules match, the engine falls back to egress domain filtering. It checks the
denylist first, followed by theallowlist. - Default Fallback: If no rules or egress patterns match, the engine returns the
egress.defaultverdict, which isdenyin a standard security configuration.
Verdict Enforcement and State Handling
The resulting Verdict dictates the final stage of the request lifecycle. The gateway handles each verdict type with specific logic to either facilitate the connection, block it, or suspend it.
Verdict Execution Table
| Verdict | Gateway Action | Result to Agent |
|---|---|---|
| Allow | Establish TCP connection to upstream and copy bytes bidirectionally. | Successful Tunnel |
| Deny | Terminate connection and log the event. | 403 Forbidden |
| Pause | Place request in ApprovalRegistry and hold the connection for up to 300s. | Pending/403 if Timeout |
Sources: crates/honmoon-proxy/src/gateway.rs:62-112, README.md, wiki/deep-dive/control-plane.md
The Pause/Approval Lifecycle
When a pause verdict is issued, the lifecycle enters a suspended state. The request is assigned a unique ID and stored in an in-memory ApprovalRegistry. An operator can then resolve the request via the management dashboard.
Audit and Lifecycle Completion
The final step in every request lifecycle is the creation of an audit record. Honmoon logs the metadata of the request, the facts used for the decision, the specific rule that matched (if any), and the final outcome (including whether a paused request was eventually approved or rejected).
Records are stored in an in-memory ring buffer for live viewing and optionally appended to a JSONL audit log file for durable storage and historical query via the @honmoon/api service.
Sources: wiki/deep-dive/architecture.md, wiki/deep-dive/control-plane.md
Summary
The Honmoon Request Lifecycle is a pipeline designed for security and auditability. By separating fact extraction, pure-functional decision logic, and asynchronous enforcement, the system maintains a robust security posture. The lifecycle ensures that AI agents are restricted to authorized domains and protocol actions, while providing a human-in-the-loop mechanism for sensitive operations through the pause and approval workflow.