cayu.egress.broker

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`CapturedRequest`

from cayu.egress import CapturedRequest

One outbound request captured outside the sandbox by the egress proxy.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`method`	`str`	`required`
`host`	`str`	`required`
`path`	`str`	`required`
`protocol`	`EgressProtocol`	`'https'`
`port`	`int`	`443`
`query`	`str`	`''`
`headers`	`dict[str, str]`	`Field(default_factory=dict)`
`body`	`bytes`	`b''`

normalize_method (method)

CapturedRequest.normalize_method(value: str, info) -> str

normalize_host (method)

CapturedRequest.normalize_host(value: str, info) -> str

validate_path (method)

CapturedRequest.validate_path(value: str, info) -> str

validate_port (method)

CapturedRequest.validate_port(value: int) -> int

policy_view (method)

CapturedRequest.policy_view() -> EgressRequest

url (method)

CapturedRequest.url() -> str

Release source · Runtime guarantees · Capability guides

`CapturedResponse`

from cayu.egress import CapturedResponse

The provider response returned to the sandbox after scrubbing.

Repeated Set-Cookie values belong in set_cookie_headers, in wire order, not a comma-joined mapping value. A single Set-Cookie in headers is also supported and precedes the separate values when both are supplied.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`status_code`	`int`	`required`
`headers`	`dict[str, str]`	`Field(default_factory=dict)`
`set_cookie_headers`	`tuple[str, ...]`	`Field(default_factory=tuple, repr=False)`
`body`	`bytes`	`b''`

validate_set_cookie_headers (method)

CapturedResponse.validate_set_cookie_headers(value: object) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`EgressDecision`

from cayu.egress import EgressDecision

Secret-free audit record of one broker decision.

Intentionally has no field that could carry the real credential, so it is always safe to log or emit as an event.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`allowed`	`bool`	`required`
`status_code`	`int`	`required`
`destination`	`str`	`required`
`method`	`str`	`required`
`path`	`str`	`required`
`grant_id`	`str \| None`	`required`
`policy_name`	`str \| None`	`required`
`reason`	`str \| None`	`required`
`authorization_kind`	`Literal['virtual_credential', 'credentialless', 'transport']`	`'virtual_credential'`
`error_code`	`str \| None`	`None`

Release source · Runtime guarantees · Capability guides

`EgressResponseBuffer`

from cayu.egress import EgressResponseBuffer

One forwarded request’s reservation against an egress buffer budget.

The broker creates one per forwarded request. It holds the reservation until the response body has been handed on: handle_request releases it when it returns, and the proxy server releases it only after it has written or dropped the body. reserve_to only grows the reservation; it raises when the shared budget cannot hold the new total, or after release. Both are thread-safe, so a custom upstream may reserve from another thread.

init (method)

EgressResponseBuffer.__init__(budget: EgressResponseBufferBudget) -> None

reserved_bytes (property)

EgressResponseBuffer.reserved_bytes() -> int

released (property)

EgressResponseBuffer.released() -> bool

reserve_to (method)

EgressResponseBuffer.reserve_to(total_bytes: int) -> None

release (method)

EgressResponseBuffer.release() -> None

Return the reservation to the budget; later calls do nothing.

Release source · Runtime guarantees · Capability guides

`EgressResponseBufferBudget`

from cayu.egress import EgressResponseBufferBudget

Bytes of buffered upstream responses held at once, shared by brokers.

One budget may back many brokers (VirtualEgressEnvironmentFactory shares one across every session it creates), so its accounting is thread-safe.

init (method)

EgressResponseBufferBudget.__init__(limit_bytes: int=DEFAULT_EGRESS_RESPONSE_BUFFER_BUDGET_BYTES) -> None

limit_bytes (property)

EgressResponseBufferBudget.limit_bytes() -> int

used_bytes (property)

EgressResponseBufferBudget.used_bytes() -> int

Release source · Runtime guarantees · Capability guides

`EgressUpstream`

from cayu.egress import EgressUpstream

Prepares a bounded provider call without dispatching it.

Decorators: @runtime_checkable.

Bases: Protocol.

prepare (method)

EgressUpstream.prepare(request: CapturedRequest, *, limits: EgressUpstreamLimits) -> EgressUpstreamOperation

Release source · Runtime guarantees · Capability guides

`EgressUpstreamLimits`

from cayu.egress import EgressUpstreamLimits

Cayu-owned limits that an upstream must enforce while reading.

response_buffer, when present, is this operation’s share of the broker-wide buffer budget: an upstream calls reserve_to with the bytes it holds for the response so far, and stops reading if that raises.

Decorators: @dataclass(frozen=True).

Fields and attributes

Name	Type	Default
`max_response_bytes`	`int`	`required`
`total_timeout_s`	`float`	`required`
`response_buffer`	`EgressResponseBuffer \| None`	`None`

Release source · Runtime guarantees · Capability guides

`EgressUpstreamOperation`

from cayu.egress import EgressUpstreamOperation

One prepared upstream call with positive cancellation settlement.

Construction is side-effect free. result() starts the operation once. When no cancellation owner is supplied, cancellation waits for natural completion rather than treating cancellation of an asyncio wrapper as proof that opaque delegated work stopped.

init (method)

EgressUpstreamOperation.__init__(operation_factory: UpstreamOperationFactory, *, cancel_and_wait: UpstreamCancellationOwner | None=None) -> None

result (method)

async EgressUpstreamOperation.result() -> CapturedResponse

Return the provider result, preserving fatal signals for direct callers.

cancel_and_wait (method)

async EgressUpstreamOperation.cancel_and_wait() -> None

Request cancellation and return only after positive quiescence.

Release source · Runtime guarantees · Capability guides

`HttpxUpstream`

from cayu.egress import HttpxUpstream

Default upstream that forwards requests to the provider over HTTPS.

init (method)

HttpxUpstream.__init__(*, timeout_s: float=DEFAULT_EGRESS_UPSTREAM_TOTAL_TIMEOUT_S, max_response_bytes: int=DEFAULT_EGRESS_UPSTREAM_MAX_RESPONSE_BYTES, transport: httpx.AsyncBaseTransport | None=None, routes: Mapping[str, str] | None=None, destination_resolver: DestinationResolver | None=None) -> None

prepare (method)

HttpxUpstream.prepare(request: CapturedRequest, *, limits: EgressUpstreamLimits) -> EgressUpstreamOperation

send (method)

async HttpxUpstream.send(request: CapturedRequest) -> CapturedResponse

Direct convenience entrance using this upstream’s configured limits.

Release source · Runtime guarantees · Capability guides

`TransparentEgressBroker`

from cayu.egress import TransparentEgressBroker

Authorizes, resolves, rewrites, forwards, and scrubs outbound requests.

The broker is the only place a SecretRef is resolved to a real value. The real value is written into the upstream request and nowhere else — never into a decision record, a returned response’s diagnostics, or an exception.

init (method)

TransparentEgressBroker.__init__(*, registry: VirtualCredentialRegistry, resolver: SecretResolver | None=None, policies: Mapping[str, EgressPolicy], approved_destinations: Sequence[ApprovedEgressDestination]=(), public_web_policy: str | None=None, upstream: EgressUpstream | None=None, audit: Callable[[EgressDecision], None] | None=None, require_test_mode_credentials: bool=True, browser_max_response_bytes: int | None=None, max_active_upstream_operations: int=DEFAULT_EGRESS_MAX_ACTIVE_UPSTREAM_OPERATIONS, upstream_max_response_bytes: int=DEFAULT_EGRESS_UPSTREAM_MAX_RESPONSE_BYTES, upstream_total_timeout_s: float=DEFAULT_EGRESS_UPSTREAM_TOTAL_TIMEOUT_S, response_buffer_budget_bytes: int | None=None, response_buffer_budget: EgressResponseBufferBudget | None=None) -> None

upstream_total_timeout_s (property)

TransparentEgressBroker.upstream_total_timeout_s() -> float

Total time one upstream request may take, including the response body.

registry (property)

TransparentEgressBroker.registry() -> VirtualCredentialRegistry

The credential registry, for session-close revocation by adapters.

has_credentialless_destinations (property)

TransparentEgressBroker.has_credentialless_destinations() -> bool

Whether the broker requires an isolated, independently authenticated transport.

authorize_connect_destination (method)

async TransparentEgressBroker.authorize_connect_destination(*, host: str, port: int) -> bool

Return positive coarse authority before the proxy mints a leaf certificate.

This entrance deliberately authorizes only the HTTPS destination. It does not acquire a credential lease, resolve a secret, or replace the complete method/path authorization performed by handle_request after TLS. Keeping the lookup on the broker’s event loop also avoids reading the mutable grant registry from a proxy worker thread.

begin_connect_destination_admission (method)

async TransparentEgressBroker.begin_connect_destination_admission(*, host: str, port: int) -> _ConnectDestinationAdmission | None

Lease coarse CONNECT authority through leaf generation and success.

connect_destination_admission_is_active (method)

async TransparentEgressBroker.connect_destination_admission_is_active(admission: _ConnectDestinationAdmission) -> bool

Revalidate one broker-owned CONNECT admission before success.

end_connect_destination_admission (method)

async TransparentEgressBroker.end_connect_destination_admission(admission: _ConnectDestinationAdmission) -> None

Release one CONNECT admission after success or denial is written.

handle_request (method)

async TransparentEgressBroker.handle_request(request: CapturedRequest) -> CapturedResponse

revoke_authority_and_wait (method)

async TransparentEgressBroker.revoke_authority_and_wait(presented_values: Sequence[str]) -> int

Revoke routes, settle dispatched upstream work, and drain requests.

settle_active_operations (method)

async TransparentEgressBroker.settle_active_operations() -> None

Settle every dispatched credential resolution and upstream call.

settle_active_credential_resolutions (method)

async TransparentEgressBroker.settle_active_credential_resolutions() -> None

Retain cancellation-opaque resolution work until natural settlement.

settle_active_upstream_operations (method)

async TransparentEgressBroker.settle_active_upstream_operations() -> None

Cancel dispatched upstream calls and retain failures for retry.

renew_authority (method)

TransparentEgressBroker.renew_authority(grants: Sequence[VirtualCredentialGrant]) -> None

Install fresh virtual values and reopen unchanged credentialless routes.

Release source · Runtime guarantees · Capability guides