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/pipeline/inbound.rscrates/proxai-core/src/pipeline/crates/proxai-core/src/ingress/

   Responsibility

   Detect the request path and parse body bytes in the app, then let the core pipeline normalize and validate the structured payload.

2. 2
   routing

   Modules

   crates/proxai-core/src/pipeline/crates/proxai-core/src/routing/src/pipeline/provider_request.rs

   Responsibility

   Resolve a provider label, protocol, compatibility policy, and upstream model in core, then map the label to an application HTTP transport.

3. 3
   provider_request

   Modules

   crates/proxai-core/src/pipeline/crates/proxai-core/src/translation/crates/proxai-core/src/provider/request/src/provider/*/request

   Responsibility

   Return a prepared provider value and matching response pipeline from core, then serialize the upstream request in the application.

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

   crates/proxai-core/src/pipeline/src/sse_translation.rssrc/http_support/

   Responsibility

   Run structured provider normalization and translation through ResponsePipeline, then rebuild the client HTTP/SSE response in the application.

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