AWS SDK

The facade clones the complete non-exhaustive `HttpConnectorSettings` and extracts the operation components

its request policy uses. Its `call` moves a `Client` clone and that policy into the request future, which is the

strong pool reference already shown above. A facade may be cached as an implementation optimization, but its

identity is never a partition, origin, pool, or admission key. Differing connect or read timeouts therefore do

not multiply `max_connections_per_host`: every facade for one `Client` reaches the same origin-wide admission

authority.

Connect and read timeouts remain operation policy rather than connection identity. The facade uses the

operation's `AsyncSleep` from `RuntimeComponents` when present, then the same default-sleep fallback as the

existing client. A configured timeout requires the resulting sleep implementation; its absence never disables

Idle maintenance is pool policy, not operation policy. Its `TimeSource` and `AsyncSleep` are fixed by the pool

builder and shared by the partition maintenance tasks; they do not depend on which operation first asks for a

facade. Operation `RuntimeComponents` may vary between smithy clients sharing a pool without changing idle

age or creating another pool.

`Client::validate_base_client_config` runs an idempotent transport preflight so native trust roots, when

applicable, load when this HTTP client is selected rather than on its first request. The preflight opens no

socket and creates no settings-keyed pool or connector cache. `validate_final_config` remains a no-op.

`connector_metadata` reports `hyper/1.x`, preserving the HTTP client identifier used in user-agent metadata.

#### Establishment

A connection's socket, driver, and reactor must all live on one runtime, because Tokio registers a socket with

the I/O reactor of whatever runtime creates it — it captures the current runtime's handle at socket creation

([`poll_evented.rs:111`](https://github.com/tokio-rs/tokio/blob/tokio-1.53.1/tokio/src/io/poll_evented.rs#L111))

— and the connector is what creates the socket. If the driver ran on one runtime while the socket was created

on another, every readiness event would cross runtimes, and the socket's reactor would outlive or predecease

the driver that holds it. So establishment — connector, transport, TLS, ALPN, handshake — and the driver it

produces run on the same runtime.

An **explicit partition** names its owner runtime through `DriverSpawner`. The

**anonymous partition** captures the current Tokio runtime on first use. A

request may be polled on another runtime, so every new connection submits the

still-unpolled connector, transport, TLS/ALPN, and Hyper handshake future to

the partition owner. Completion updates the cell and wakes the requesting task;

the resulting driver and pending return work use the same spawner. This policy

costs one task submission and wake per new connection. Local reuse and dispatch

on an established connection do not pay that handoff.

The submitted establishment future carries its own completion guard. If a spawner discards the future before

before calling it, and issues one call per readiness. The dispatch handle Hyper returns is a different thing.

Its readiness — whether the connection can accept another request — is an inherent

[`SendRequest::poll_ready`](https://github.com/hyperium/hyper/blob/v1.11.0/src/client/conn/http1.rs#L156),

not a Tower `Service`: Hyper has no Tower dependency, and the HTTP/2 form ignores its `Context` entirely

([`http2.rs:97`](https://github.com/hyperium/hyper/blob/v1.11.0/src/client/conn/http2.rs#L97)). Connection

readiness is thus a per-protocol dispatch question the pool answers against the connection's state, and does

not share machinery with the connector's Tower readiness. The two are related only by name.

#### HTTP/1 attempts and HTTP/2 flights

The two protocols establish differently because they reuse differently. An HTTP/1 connection carries one

request at a time, so a cell that needs more concurrency needs more connections: each establishment is an

independent *attempt*, and several may run at once, each producing a connection for the request that launched

it. An HTTP/2 connection multiplexes, so one connection serves the whole cell; a second connection to an

origin the cell already serves is nearly pure waste. HTTP/2 establishment is therefore a *flight*,

coordinated so the cell keeps at most one accepting HTTP/2 generation — a request arriving during a flight

waits for it rather than starting its own, and the resulting generation is published to compatible waiters.

##### Post-ALPN convergence

The initial API imposes no pool-wide HTTP/1-only or HTTP/2-only policy. Connector ALPN resolves a transport's

The logical owner carried through this decision is an *establishment authority*: the transport and, on a

bounded origin, its capacity lease. The authority has exactly one owner even though the request waiting for

its result does not own it; cancellation of that request cannot silently drop the transport or permit. After

ALPN, the owner performs one cell-local select-or-join transition before starting the Hyper protocol handshake:

```text

automatic attempt owns transport + optional capacity lease + launching waiter

  |

  +-- ALPN = H1

  |     `-- run H1 handshake

  |           +-- success -> install H1 record; record takes capacity lease

  |           |     +-- launching waiter accepts H1 -> dispatch

  |           |     `-- waiter requires H2 -> retain H1 for compatible demand;

  |           |                              return the existing unsupported-version error

  |           `-- error -> close transport; return lease; fail launching waiter

  |

  `-- ALPN = H2

              `-- atomically inspect this cell's accepting generation and H2 flight

                    +-- accepting generation -> register waiter against generation

                    |                           close losing transport; return its lease

                    |                           close losing transport; return its lease

                                                  |

                                                  +-- H2 handshake succeeds

                                                  |     -> install record; record takes lease

                                                  |     -> publish generation; serve participants

                                                  `-- error

                                                        -> close transport; return lease

                                                        -> fail participants

```

The inspection and either registration or flight installation are one transition under the cell's

coordination. This is the linearization point: many automatic attempts may reach H2 ALPN, but at most one

becomes the flight. A losing authority has not started a Hyper driver, so its guard closes the negotiated

transport and returns its capacity lease; its launching waiter remains represented exactly once, as a

revalidates the generation identity and accepting state; if either changed after registration, the waiter

returns to acquisition rather than dispatching through stale state.

A waiter that joins a flight or generation retains its original waiter sequence. On publication, the

[generation gate](#http2-publication) orders flight participants and already committed compatible local

waiters together; joining an accepting generation follows that same activation path. Post-ALPN convergence

therefore cannot let a later attempt barge ahead of an older compatible waiter.

Request version changes only compatibility. When an automatic attempt launched by an HTTP/2-marked request

negotiates HTTP/1, the H1 connection remains useful and is handed to compatible local demand or the idle set.

The launching request receives the same unsupported-version classification and connection metadata as the

existing client; it neither dispatches on H1 nor loops establishing until ALPN happens to choose H2.

The ownership transfer is therefore fixed at each boundary:

| State               | Transport owner           | Capacity owner                              | Waiting-request owner              |

| ------------------- | ------------------------- | ------------------------------------------- | ---------------------------------- |

| independent attempt | establishment authority   | its optional capacity lease                 | cell waiter entry                  |

| H1 installed        | H1 connection record      | record's capacity lease                     | checked-out H1 guard or cell queue |

| H2 joiner           | existing flight or record | existing owner; own capacity lease returned | participant or activation          |

| H2 published        | H2 connection record      | record's capacity lease                     | H2 request lease after activation  |

| failure or drop     | cleanup guard             | guard until admission return                | terminal result or re-acquisition  |

This is the mechanism behind the miss policy from

[Local connection selection](#local-connection-selection): a partition that misses locally establishes its

own connection. It reaches for a peer's connection only when it cannot establish, which the next section

covers.

#### Obligations

* **Establishment placement** [safety] — the connector, transport setup, TLS, ALPN, and handshake for a

  connection are polled only on its placement runtime: the runtime bound by the anonymous partition's first

  establishment or the runtime named by an explicit partition.

* **Hyper task placement** [safety] — tasks Hyper spawns for a connection run on that connection's partition

  runtime.

* **Single permit owner** [safety] — at every point in establishment a bounded connection's permit has

  exactly one owner, and a failed or dropped establishment returns its permit to admission.

* **Driver termination closes the record** [safety] — normal driver completion and cancellation of the

  guarded driver task both request the record's exactly-once logical close without owning or retaining its

  capacity lease.

* **Connector readiness** [safety] — the connector is driven to ready before each call, and each readiness

  admits one call.

* **Single generation** [safety] — a cell keeps at most one accepting HTTP/2 generation; establishments that

  resolve HTTP/2 collapse to one, and the losing transports close and return their permits.

* **Atomic H2 convergence** [safety] — after automatic ALPN selects H2, one cell-local transition either

  activates an accepting generation, joins the one current flight, or installs the caller as that flight's

  driver before any H2 handshake or publication begins.

* **Losing-attempt cleanup** [safety] — an automatic H2 attempt that joins existing state closes its

  unhandshaken transport and returns its capacity lease while retaining its launching waiter exactly once.

* **Compatibility-preserving H1 result** [safety] — an H1 result is retained for compatible demand; an

* **Flight cancellation** [safety] — participant cancellation removes only that participant; terminal flight

  drop closes its transport, returns its lease, and leaves no live waiter attached to the retired flight

  identity.

### Bounded-capacity coordination

A bounded origin at its limit cannot establish: admission has no permit to issue. The permit it needs may

still exist — held by a connection this waiter cannot use, or held in another partition's cell — but a

present permit is not a usable one. So two things have to happen. A waiter parks until a permit it can use

becomes available, and capacity that exists elsewhere moves to where the demand is. This section covers how a

cell signals demand, how the pool decides which capacity a waiter may take, the two operations that move

capacity, and how a freed resource is delivered to a parked waiter. All of it is bounded-mode only; an

unbounded origin never reaches here.

#### Demand

A cell's demand is one aggregate state, not a per-request count: a cell either wants another connection or it

does not. The state is active while any request waits and inactive when none do, so it is a single standing

ticket per cell rather than one ticket per waiting request.

The waiting requests queue behind the ticket in arrival order. An arriving permit goes to the request at the

head, which stops waiting; the next becomes the head. The ticket is how returning connections and other

cells find a cell with unmet demand; the queue is how that cell chooses whom to serve first.

The logical snapshot published to admission is:

```rust

enum ProtocolRequirement {

    H1Compatible,

    H2Required,

}

enum DemandState {

    Active {

        head: ProtocolRequirement,

        eligibility_group: EligibilityGroup,

    },

    Inactive,

    NetworkInterface,

    Pool,

}

```

`Partition` permits no cross-cell dispatch. `NetworkInterface` groups partitions by the exact configured

interface, with all unbound partitions in one group. `Pool` permits reuse across every partition. Scope

controls only dispatch eligibility: it does not constrain reclaim, which closes a connection and transfers

capacity rather than moving I/O authority.

Dispatching through a connection that already exists consumes no capacity; that connection already holds one

of the admitted permits. So an eligible reusable connection serves the waiter whether or not a permit is

free — a pool at its limit still dispatches freely through all `N` of its connections. Capacity is consulted

only when no eligible connection can serve the waiter and the cell must open one. The two questions do not

read each other's state, and only that second case reaches admission: eligibility decides reuse, capacity

decides establishment. Keeping them separate is what lets the two operations below relieve a shortage of one

without disturbing the other.

#### Borrow and reclaim

H2 publication carries no `AcquisitionPayload`. The connection-owning record continues to own the capacity

lease, while a `(connection-owning cell, generation identity)` notice says that compatible requests may take

H2 request leases. Publishing a new local generation first installs the record and accepting generation under

the connection-owning cell lock, then makes that identity visible to compatible local waiters. They are woken

and admitted in bounded local turns; publication does not scan or synchronously wake an unbounded queue.

Publication also installs a local fairness gate:

```rust

enum GenerationGate {

}

```

The peer-cell index holds one group-scoped advertisement for each accepting H2 generation. Record and

generation installation precede advertisement; transition out of accepting removes it. Either a new

advertisement or new group demand schedules a bounded publication turn from stored connection and demand heads.

The advertisement carries only connection-owning cell and generation identity, not a dispatch handle or

capacity lease. The publication guard revalidates it at the connection-owning and requesting cells. A stale

advertisement is removed or updated before the next turn, so peer H2 discovery does not scan cells.

Under bounded pressure, an accepting generation may also be announced to the

head of its eligibility-group all-protocol view. Admission fences that demand

generation in `Delivering` with a `DeliveryId`; the publication action carries

only connection-owning cell and generation identities plus an acknowledgement

fallback, never the record's capacity lease.

The requesting cell revalidates the generation identity, accepting state, demand

generation, and reuse scope.

Acceptance makes the generation visible to compatible waiters there; rejection discards the stale notice

while the generation and

permit remain at the connection-owning cell. Acceptance acknowledges after requesting-cell visibility and the

named head's activation opportunity are committed, not after every local waiter has activated. Remaining local

waiters proceed through the generation gate in bounded turns and no longer advertise a connection need while

that generation remains usable. Later group tickets are handled by subsequent bounded publication turns, so

one-to-many visibility does not turn one host action into work proportional to partition count.

Dropping a pending publication guard submits its `on_drop` acknowledgement so the fence retries or closes;

there is no single-owner payload to refunnel. Committing publication stores the requesting-cell

acknowledgement, which is submitted before the guard disarms.

This separates publication from single delivery: a permit or H1 has one owner and one requesting cell, while

an H2 generation remains owned by its connection cell and may be announced repeatedly. The transitions must

be model checked; their invariants are stated in [Correctness invariants](#correctness-invariants), with the

checks specified in [Appendix B](#appendix-b-validation).

#### Obligations

* **Bounded demand** [safety] — a cell carries at most one active demand generation regardless of how many

  requests wait, so demand accumulates no deficit and one residence receives at most one terminal outcome.

* **Snapshot ordering** [safety] — admission retains the newest complete demand version and rejects an action

  for a retired generation, so out-of-order publication cannot resurrect cancelled or satisfied demand.

* **Eligibility and capacity independence** [safety] — the capacity decision and the eligibility decision do

  not read each other's state.

* **Placement under transfer** [safety] — neither borrow nor reclaim moves a connection's driver or I/O off

  its owning partition.

* **Reclaim scope independence** [safety] — reclaim moves a permit without dispatching across a partition

  boundary, so it is not constrained by the reuse scope.

* **Single delivery** [safety] — one delivery identity owns at most one permit or provisional H1, commits it

  to at most one requesting waiter, and retains its scheduling fence until requesting-cell acknowledgement.

* **Refunnelling** [safety] — rejection, supersession, cancellation, task drop, or panic returns every

  undelivered permit to admission and every undelivered H1 to its connection-owning cell exactly once.

* **Publication ownership** [safety] — H2 publication carries generation identity, never the connection's

  capacity lease; request activation takes a request lease while the connection record remains the capacity owner.

* **Publication priority** [liveness] — publication closes the generation gate before visibility and offers

  activation to waiters committed at publication before newer arrivals, in bounded oldest-first turns.

* **Cross-cell order** [safety] — H1 borrow and reclaim both serve the current origin head, preferring an

  eligible peer connection for borrow and otherwise reclaiming an origin peer. Peer H2 publication uses its

endpoint and can rearm the same adapter for a later selection without retaining the rejected generation.

#### Retry, timeout, and errors

There is one authority for transparent dispatch retry: Hyper must return the original, unsent request from

`try_send_request`, and the selected connection must have been reused. The pool restores the absolute URI,

disarms any unaccepted H2 body endpoint, retires or invalidates the stale selected connection, and sends that

same request through acquisition again. An unsent failure from a fresh connection is terminal and still

retires a sender Hyper reported unable to accept the request; its inert body endpoint and selected guard cannot

survive the error. The pool does not clone a request or replay one Hyper accepted.

With Hyper 1.11, the returned-request path after `try_send_request` is reachable for H1; H2 dispatch errors

after call do not carry the original request and are terminal. An H2 readiness failure observed before call is

different: the request is still locally owned and may return to acquisition without being replayed.

Every error after Hyper accepts the envelope is terminal for this dispatch. H1 conservatively retires because

the request may have reached the wire. H2 releases or resets the affected stream and drives its send and

receive endpoints to terminal state; a stream-local reset does not by itself invalidate the accepting

generation. GOAWAY, a closed dispatcher, a connection error, or other connection-fatal evidence does

invalidate that generation. The resulting `ConnectorError` preserves the current source chain and

classification, including timeout, user, I/O, incomplete-message transient,

`establishing` starts when an attempt or flight is admitted and ends when it fails or installs a record.

`h1_idle` and `h1_active` partition logically open H1 records; checked-out and `Reserved` H1 records are

active, while only dispatch-eligible records in the idle set are idle.

`h2_accepting` counts generations that may issue request leases, while `h2_active_streams` counts accepted

request leases across accepting and draining generations. Logical close moves a connection out of those

admitted gauges and, while its transport remains, into `h1_draining` or `h2_draining`. An upgraded H1 remains

H1-draining until its wrapped root I/O drops. `physically_live` starts when the connector's returned transport

is wrapped for

lifecycle tracking and ends only at root-I/O drop, so it includes handshaking, admitted, draining, and

upgraded transports and may exceed the configured limit. `waiting_requests` counts requests registered in

`OriginStats::admitted` derives the saturating sum of `establishing`, `h1_idle`, `h1_active`, and

`h2_accepting` from the captured partition rows; it is not another shared counter or admission authority.

Draining connections are excluded because they hold no permits. `limit` is the configured per-origin bound,

or `None` for an unbounded origin. A connection and its streams are attributed to the owner partition even

when another partition dispatches through them; a waiting request is attributed to its requesting partition.

Each gauge changes at its named transition before any corresponding callback. The counters use relaxed or

otherwise non-coordinating reads so observation adds no origin-wide write to a local reuse hit. Consequently,

an `OriginStats` value is not an atomic multi-counter snapshot: a transition can appear in one loaded field

**Reclaim** — closing a connection so its permit can move to another cell. Transfers capacity, not I/O.

**Capacity lease**, **request lease**, and **handle** — a capacity lease is the exclusive hold on one permit

and moves from establishment to the connection record. An H2 request lease owns one prospective or accepted

stream's two-ended lifecycle but no permit. A dispatch handle can address a connection and owns neither kind of

capacity.

**Retry authority** — proof that the same request may be dispatched again. Only Hyper returning the original

request unsent from a reused connection creates this authority; request clonability does not.

**Publish** and **deliver** — publication makes state visible to many unnamed readers; delivery hands one

value to one waiting party. `DemandResidence` tracks a ticket's residence and acknowledgement fence;

`DeliveryGuardState` owns a one-to-one payload while it crosses locks.

**Attempt** and **flight** — an HTTP/1 establishment is an attempt, independent of other attempts; an

HTTP/2 establishment is a flight. Automatic attempts remain independent before ALPN, then atomically join or

**Logical close** — a connection stops accepting new work and releases its permit. **Physical close** —

the socket is gone. Physical close follows logical close by an unbounded interval, so live sockets can

outnumber admitted connections; `max_connections_per_host` bounds admitted connections, not file descriptors,

and no finite bound on live sockets follows from it.

**Draining generation** and **draining connection** — a draining H2 generation accepts no new request leases

while already accepted streams finish. A draining connection has logically closed and released its permit but

still has physically live root I/O, and is counted by `h1_draining` or `h2_draining`. An H2 record may be both

while its accepted streams and transport finish.

**Demand generation** — one cell queue head's `DemandId`. A **snapshot version** orders complete publications

for that generation. Readers retain the newest publication and reject work for a retired generation.

**Obligation** — a duty a component owes, stated as one sentence an implementation either satisfies or does

not. `[safety]` obligations forbid a state; `[liveness]` obligations require an outcome; `[optimization]`

obligations bound a cost, and violating one is a regression rather than a defect.

## Correctness invariants

an explicit partition using the reserved anonymous identity. `BuildError` reports the setting and value that

failed and implements `Error`; callers are not expected to branch on an exhaustive variant set.

When `partitions` is never set, construction creates the one anonymous, unbound partition. Once set, the

supplied nonempty set is the complete explicit topology and no anonymous partition is added.

`max_connections_per_host` is unset by default, and an unset bound constructs no admission machinery. When

set, it bounds one scheme-host-port origin across all partitions and interface groups, not per partition. HTTP

and HTTPS and distinct non-default ports are bounded separately. The limit counts every establishing, idle, and

active connection rather than only idle connections.

An unset `idle_timeout` uses a 90-second default. Passing `None` to the fluent setter disables idle

timeout. The mutable setter preserves all three configuration states: outer `None` restores the default,

`Some(None)` disables the timeout, and `Some(Some(duration))` selects a duration. The builder's time source and

sleep implementation drive pool maintenance; their defaults are the production system clock and Tokio sleep.

They are pool inputs and are not replaced by per-operation `RuntimeComponents`.

Building retains configuration and assembles the reusable transport factory but opens no socket. Native trust

loading is deferred to the idempotent connector preflight invoked when the `Client` is selected by smithy, or

to first establishment when used without smithy validation. Whether a configured interface exists and can be

used is therefore reported later as a connector error on establishment, not `BuildError`. Likewise,

`TokioDriverSpawner::current` retains its own documented panic outside a Tokio runtime because that constructor

is invoked before the spawner is passed to the pool.

### Module structure

```text

aws-smithy-http-client/src/client/

  pool.rs              — ConnectionPool ownership and public re-exports

  pool/

    builder.rs         — Builder typestate, validation, connector assembly

    client.rs          — Client, PoolConnector, and ClientBuildError

    partition.rs       — partition declarations and runtime/interface placement

    origin.rs          — owned OriginKey, borrowed lookup, and canonicalization

    registry.rs        — PartitionRegistry, PartitionState, and stable cell publication

    cell.rs            — OriginCell and cell-level acquisition coordination

    cell/

      h1.rs            — HTTP/1 records, sender ownership, and reuse reservation

      waiters.rs       — local acquisition queue and delivery reservation

    admission.rs       — bounded-origin capacity and unlocked action driving

    admission/

      demand.rs        — versioned demand order and delivery fences

      reuse.rs         — H1 availability order and cross-cell reuse operations

      delivery.rs      — capacity/H1 crossing guards and acknowledgements

    establish.rs       — transport construction below protocol establishment

    establish/

    dispatch.rs        — protocol-neutral request routing

    dispatch/

    maintenance.rs     — idle-deadline scheduling and partition task lifetime

    connection.rs      — records, leases, logical close, physical completion

    events.rs          — listener and lifecycle event types

    stats.rs           — origin/partition snapshots and lifecycle gauges

aws-smithy-http-client/src/

  sync/

    mod.rs              — standard-library and Loom backend selection

    std.rs              — production synchronization facade

    loom.rs             — modeled synchronization facade

```

The inventory describes ownership boundaries, not implementation order. The `pool` module re-exports every

public type above; private modules may be split or combined without changing the architecture so long as the

lock, ownership, and hot-path boundaries remain intact.

The transport-connector contract below the pool is unchanged: it is a `Service<Uri>` yielding

`(IO, Connected)`. The pool composes transport connectors and does not replace that contract; the smithy

`HttpConnector` above the pool is the request-policy facade described earlier.

---

## Appendix B: Validation

Validation supplies implementation evidence for the contracts above; it does not redefine them. The

implementation-neutral connection harness and existing-client behavior suites in smithy-rs

[PR #4767](https://github.com/smithy-lang/smithy-rs/pull/4767) form the compatibility baseline. Pool-specific

tests preserved on `archive/conn-pool-4708` are an additional inventory, not an acceptance target: applicable

contracts may be retained or rewritten, implementation-specific assumptions may be obsolete, and the owned

state machine requires coverage that prototype tests did not contain.

The evidence levels have distinct jobs:

* **Unit, property, and bounded transition tests** cover construction, canonicalization, indexing,

  accounting, and explicit state-machine transitions. Where focused state-space enumeration is used, the test

  identifies its operation alphabet and bound; ordinary transition tests are not described as exhaustive.

* Focused **Loom kernels** compile the production synchronization-bearing code against Loom and exercise

  concurrent cell publication, permit and H1 delivery, H1 selection and return, borrowed-H1 materialization,

* **Controlled-runtime tests** use injected time, sleep, connectors, and executors to force cancellation at

  ownership-distinct cancellation boundaries, submitted-future drop, idle deadlines, independent-runtime

  request movement, explicit placement checks, and connector or handshake failure.

* The **wire harness** verifies HTTP/1.1 and HTTP/2 behavior against scripted peers, including reuse,

* **Differential tests** run the same implementation-neutral behavior contracts against the current

  Hyper-util-backed client and this pool. Any difference in request behavior, metadata, timeout scope, or error

  classification requires an explicit design decision rather than a rewritten oracle.

* **Benchmarks and stress tests** establish that the optimization and liveness contracts remain true at

  production concurrency and topology.

The required evidence maps to the architecture as follows:

| Mechanism                                                             | Primary evidence                                                                  | What it must establish                                                                                                                                                                                                                                         |

| --------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

//!

//! A [`ConnectionPool`] owns connection policy and a fixed set of partitions.

//! A [`Client`] binds Smithy HTTP operations to one partition. Pools without

//! explicit [`Partition`] values contain one anonymous partition; otherwise a

//! client selects a declared partition by [`PartitionId`].

//!

//! A partition owns connection establishment, protocol drivers, and idle

//! maintenance. [`ConnectionReuseScope`] controls whether another partition may

//! dispatch through those connections. Reuse transfers protocol dispatch

//! authority; it never moves the socket, driver, or capacity accounting.

//!

//! # State ownership

//!

//! ```text

//! ConnectionPool

//! `-- PoolInner

//!     |-- immutable policy and transport factory

//!     `-- PartitionRegistry

//!         |-- PartitionState per partition

//!         |   |-- runtime placement and idle maintenance

//!         |   `-- OriginCell per canonical origin

//!         |       |-- acquisition queue

//!         |       `-- protocol connection records

//!         `-- OriginAdmission per bounded origin

//!             |-- connection permits

//!             |-- cross-cell demand order

//!             `-- peer reuse indexes

//! ```

//!

//! One `OriginCell` lock owns local acquisition order and protocol residence.

//! For a bounded origin, `OriginAdmission` separately owns the origin-wide

//!

//! # HTTP/1 request lifecycle

//!

//! Hyper represents an HTTP/1 connection with one exclusive

//! `SendRequest<SdkBody>` handle. This module calls that handle the sender. The

//! sender authorizes request dispatch but does not own the socket or protocol

//! driver.

//!

//! ```text

//! Client(partition, request)

//! `-- OriginCell(partition, origin)

//!     |-- local idle sender --------------------------> H1Selection

//!     `-- acquisition queue

//!         |-- returned local or eligible peer sender -> H1Selection

//!         |-- capacity permit -> establish HTTP/1 ---> H1Selection

//!         `-- reclaimed peer capacity -> establish ---> H1Selection

//!

//! H1Selection -- Hyper accepts request --> H1Exchange

//! H1Exchange

//!     |-- complete response + ready --> offer to owning OriginCell

//!     `-- failure, cancellation, or upgrade ----------> retire pool record

//! ```

//!

//! A local hit touches only the cell lock. On a miss, one queued acquisition

//! remains authoritative while a returned sender and establishment race to

//! satisfy it. Bounded origins may borrow an eligible peer sender or reclaim a

//! peer connection and transfer its permit; active connections are not

//! reclaimed.

//!

//! Dispatch commits against logical close before Hyper receives the request.

//! Once accepted, the response lifecycle retains the sender until Hyper proves

//! a complete reusable message boundary. Failure retires the connection, and

//! an upgrade closes the pool record before exposing upgraded root I/O.

//!

//! `ConnectionState` separates logical close, accepted-request accounting, and

//! root-I/O ownership. Logical close rejects new dispatch and releases bounded

//! capacity. `DispatchGuard` follows an accepted request, while

//! `PhysicalConnectionGuard` follows root I/O until the pool no longer owns

//! that transport; neither describes the operating system TCP state. All

//! connection-owned work runs through the partition [`DriverSpawner`].

#![cfg_attr(

    smithy_http_client_loom,

    allow(

 * SPDX-License-Identifier: Apache-2.0

 */

//! Capacity and demand shared by the cells of one bounded origin.

//!

//! [`OriginAdmission`] stores the origin once and keys its partition cells,

//! demand records, and availability indexes by [`PartitionId`]. Its lock is the

//! sole authority for available capacity, origin-wide demand order, and reuse

//! operations. Cell locks are never held with the admission lock.

//!

//!

//! 1. A cell publishes a complete [`DemandSnapshot`] after releasing its lock.

//! 2. [`DemandSchedule`] replaces that partition snapshot and links active

//!

use super::cell::OriginCell;

use super::origin::OriginKey;

use super::partition::{EligibilityGroup, PartitionId};

use crate::sync::{Arc, Mutex, Weak};

use std::collections::HashMap;

use std::fmt;

use std::num::NonZeroUsize;

mod delivery;

mod demand;

mod order;

pub(in crate::client::pool) mod reuse;

use self::demand::{DemandSchedule, PreparedCapacityDelivery};

use self::order::{IntrusiveLinks, IntrusiveOrder};

pub(in crate::client::pool) use delivery::DeliveryGuard;