Request Lifecycle

Request Lifecycle

This page describes the source-level request path. User-facing behavior lives in Using ProxAI and protocol behavior lives in Protocol Guide.

Follow the data phase

The easiest way to reason about the code is to track which phase owns the data: inbound_request, provider_request, upstream_response, or outbound_response.

Flow

Stages

1. 1
   inbound_request

   Modules

   src/ingress/src/pipeline/inbound.rs

   Responsibility

   Detect request path, read body, parse protocol payload, normalize inbound request metadata.

2. 2
   routing

   Modules

   src/routing/src/config.rs

   Responsibility

   Resolve explicit route or protocol-aware default provider; enforce request_protocol guards.

3. 3
   provider_request

   Modules

   src/provider/*/requestsrc/translation/

   Responsibility

   Translate payload if protocols differ, rewrite provider model, serialize the upstream request.

4. 4
   provider transport

   Modules

   src/provider/*/transport

   Responsibility

   Construct upstream URL, attach provider-owned auth headers, and send via HTTP.

5. 5
   upstream_response

   Modules

   src/upstream/src/provider/*/response

   Responsibility

   Read status, headers, non-streaming body, or streaming byte carrier.

6. 6
   outbound_response

   Modules

   src/translation/src/http_support/

   Responsibility

   Translate provider response back to the inbound protocol and rebuild the client HTTP response.

Important invariants

Invariant	Reason
Translation does not own HTTP Response	The translation layer should stay pure at the carrier boundary.
Provider auth comes from provider config	Client-supplied Authorization does not control upstream provider auth.
Route match errors are explicit	A protocol guard mismatch should not fall through to a different provider.
Streaming completion is semantic	Completion requires terminal protocol events, not just socket closure.

Related docs

• Architecture
• Protocol Conversion
• Capture Phases
• Behavior Contracts