handler

Module: handler

Contents

Structs

• DispatchedResponse - Response returned by the current raw-forward placeholder.
• RequestHandler - Shared handler used by every interceptor.

Enums

• AbortReason - Reason an approved call was aborted before producing a target
• ConnectDecision - CONNECT-specific decision surface used by the HTTP proxy interceptor.
• DenialContext - Structural context of a denial.
• HandledResponse - Response produced by the transport-agnostic request handler.
• UpgradeAuthorization - Authorization result for HTTP upgrade requests (for example WebSocket

Functions

• abort_body_json - Serialize an abort into the canonical JSON body used by HTTP-facing
• denial_context_from_params - Maps an [ActionParams] variant to its [DenialContext].
• denial_context_of - Derives the denial context from a normalized envelope.
• deny_body_json - Serialize a denial into the canonical JSON body used by HTTP-facing
• tool_denial_body_json - Serialize a tool-call denial into the canonical JSON body shape

---

firma_sidecar::handler::AbortReason

Enum

Reason an approved call was aborted before producing a target response.

The variant surface is intentionally small in V1. Later tasks (009) add authority-driven and revocation-driven aborts.

Variants:

• ConnectorTimeout - Connector exceeded its configured timeout.

Methods:

• fn code(self: Self) -> &'static str - Canonical reason code string used in audit events and in the

Traits: Eq, Copy

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &AbortReason) -> bool
• Clone
  • fn clone(self: &Self) -> AbortReason

firma_sidecar::handler::ConnectDecision

Enum

CONNECT-specific decision surface used by the HTTP proxy interceptor.

Variants:

• Allow - CONNECT target is allowed and tunneling may proceed.
• Deny{ reason: firma_core::DenyReason, detail: String } - CONNECT target is denied before tunnel establishment.

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_sidecar::handler::DenialContext

Enum

Structural context of a denial.

Derived from the NormalizedEnvelope carried on [EnforcementDecision::Deny]. Interceptors select the transport response shape from this value without re-inspecting the envelope.

See FEP §5.1–§5.2 for the behavioural contract:

• Tool: agent loop continues; body is a structured tool result.
• Api: synchronous terminal failure; body is the canonical deny JSON (HTTP 403 for HTTP interceptors).

Variants:

• Tool - Denial originated from a tool-call transport.
• Api - Denial originated from an API-class transport (HTTP, DB, etc.)

Traits: Eq, Copy

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> DenialContext
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &DenialContext) -> bool

firma_sidecar::handler::DispatchedResponse

Struct

Response returned by the current raw-forward placeholder.

Fields:

• status: u16 - Target HTTP status code.
• headers: std::collections::HashMap<String, String> - Target response headers.
• body: Vec<u8> - Target response body.

Traits: Eq

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> DispatchedResponse
• PartialEq
  • fn eq(self: &Self, other: &DispatchedResponse) -> bool
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_sidecar::handler::HandledResponse

Enum

Response produced by the transport-agnostic request handler.

Variants:

• Ok(DispatchedResponse) - Request was allowed and the target replied.
• Passthrough(DispatchedResponse) - Non-protected request was forwarded without enforcement.
• Deny{ reason: firma_core::DenyReason, detail: String, context: DenialContext } - Request was blocked before dispatch.
• Aborted{ reason: AbortReason, detail: String } - Request was approved by enforcement but the dispatch could not

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_sidecar::handler::RequestHandler

Struct

Shared handler used by every interceptor.

Methods:

• fn new(pipeline: Arc<EnforcementPipeline>, connector_registry: Arc<ConnectorRegistry>, audit_sink_sender: mpsc::Sender<AuditPayload>) -> Self - Constructs a request handler from the enforcement pipeline, the
• fn handle(self: &Self, request: RawRequest, session_id: &str) -> HandledResponse - Handles one normalized transport request.
• fn handle_connect(self: &Self, request: RawRequest, session_id: &str) -> ConnectDecision - Handles CONNECT authorization without performing connector HTTP dispatch.
• fn authorize_upgrade(self: &Self, request: RawRequest, session_id: &str) -> UpgradeAuthorization - Authorizes an HTTP upgrade request without dispatching via the connector
• fn emit_upgrade_audit(self: &Self, payload: AuditPayload, dispatch_status: u16, response_size: usize) - Emits audit payload for an authorized HTTP upgrade flow.
• fn emit_connect_relay_failure_audit(self: &Self, session_id: &str, host: &str, detail: &str) - Emits a synthetic audit event when CONNECT was policy-allowed but

firma_sidecar::handler::UpgradeAuthorization

Enum

Authorization result for HTTP upgrade requests (for example WebSocket handshakes) where the interceptor owns upstream byte relay.

Variants:

• Allow{ credentials: firma_core::InjectedCredentials, audit_payload: Box<crate::audit::AuditPayload> } - Upgrade request is authorized. The interceptor must complete upstream
• Deny{ reason: firma_core::DenyReason, detail: String } - Upgrade request denied by policy pipeline.

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_sidecar::handler::abort_body_json

Function

Serialize an abort into the canonical JSON body used by HTTP-facing interceptors.

Agents key off the aborted boolean flag to distinguish abort responses from upstream-reported errors.

fn abort_body_json(reason: AbortReason, detail: &str) -> Vec<u8>

firma_sidecar::handler::denial_context_from_params

Function

Maps an [ActionParams] variant to its [DenialContext].

ToolUse → Tool; Http / DbQuery → Api.

fn denial_context_from_params(params: &firma_core::ActionParams) -> DenialContext

firma_sidecar::handler::denial_context_of

Function

Derives the denial context from a normalized envelope.

Fail-closed default: when no envelope is available (pre-normalization denial such as MalformedRequest or UnclassifiedIntent), returns [DenialContext::Api] — the hard-block shape. A tool denial on a non-tool call would silently mask the failure.

fn denial_context_of(envelope: Option<&crate::normalizer::NormalizedEnvelope>) -> DenialContext

firma_sidecar::handler::deny_body_json

Function

Serialize a denial into the canonical JSON body used by HTTP-facing interceptors.

fn deny_body_json(reason: firma_core::DenyReason, detail: &str) -> Vec<u8>

firma_sidecar::handler::tool_denial_body_json

Function

Serialize a tool-call denial into the canonical JSON body shape defined by FEP §5.1.

The agent receives this as it would any other tool result; the session continues. No HTTP status semantics are implied — the body is the tool’s structured result.

fn tool_denial_body_json(reason: firma_core::DenyReason, detail: &str, action_class: &str, tool_name: &str) -> Vec<u8>