Module pool 

Connection pooling with explicit runtime and network placement.

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. Partitions in the same eligibility group are exactly those whose configured reuse scope permits them to share a connection.

Connection establishment and installed connection lifetime are separate ownership phases:

establishment task
    |-- DNS, socket, proxy, TLS, and ALPN
    `-- negotiated transport
            `-- PendingOpen
                    |-- Hyper protocol setup
                    `-- Open
                            `-- pool installation
                                    `-- discoverable -> draining -> closed

The establishment task and its permit represent work that may fail before a physical connection exists. ConnectionState begins only after the connector returns connected I/O and selects HTTP/1 or HTTP/2. For TLS, that boundary follows TLS and ALPN. Hyper protocol setup moves the state from PendingOpen to Open; cell installation then makes the connection discoverable. Establishment and connection events can therefore be observed independently without representing failed attempts as installed connections.

State ownership

ConnectionPool
`-- PoolInner
    |-- immutable policy and transport factory
    `-- PartitionRegistry
        |-- PartitionState per partition
        |   |-- runtime placement and idle maintenance
        |   `-- OriginCell per canonical origin
        |       |-- acquisition queue and supply revisions
        |       |-- H1 connection ownership
        |       `-- H2 flights, generations, routes, and gates
        `-- OriginAdmission per bounded origin
            |-- capacity budget
            |-- demand schedule
            |-- H1 supply index and retained matches
            `-- H2 supply index and route/reclaim state

One OriginCell lock owns local acquisition order and protocol state. For a bounded origin, OriginAdmission separately owns the origin-wide connection limit and cross-cell matching. An H2 request-claim lock records independent upload and response completion. ConnectionState owns logical connection lifetime, and partition maintenance owns its timer state.

No two pool locks are held together. Demand snapshots and supply revisions move cell state into admission. Assignments and detached guards carry one selected payload or route back toward a cell. H2 claim completion detaches its dispatch guard before entering connection or cell state. Maintenance detaches cells and wakers before expiration or wake callbacks.

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.

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.

HTTP/2 request lifecycle

One HTTP/2 connection carries many concurrent request streams. The pool calls one installed incarnation of that connection a generation. A replacement connection receives a new generation identity so delayed close, route, and completion work cannot affect it.

The connection-owning cell retains the generation’s authoritative Hyper request handle and capacity. A requesting cell may retain only a route that names the owning cell and one exact accepting generation. Each use revalidates that route before cloning a transient request handle.

Client(partition, request)
`-- OriginCell(partition, origin)
    |-- local accepting generation ----------------> H2Activation
    `-- acquisition queue
        |-- local flight result --------------------> H2Activation
        |-- eligible peer generation route --------> H2Activation
        `-- capacity permit -> connect + ALPN
            |-- HTTP/2 -> join or drive one flight -> H2Activation
            `-- HTTP/1 -> H1Selection or incompatible-version error

H2Activation -- Hyper accepts request --> H2RequestClaim
H2RequestClaim
    |-- request body ends or drops -----> upload side complete
    `-- response body ends or drops ----> response side complete
both sides complete --------------------> release generation request count

H2Activation reserves pool accounting for a prospective stream on one exact generation. It is not yet an HTTP/2 stream. Dropping it before Hyper accepts the request returns its generation-gate turn and request count. Acceptance creates two independent completion sides because upload and response can finish in either order. Logical close stops new activations and releases bounded capacity; accepted streams retain the draining generation until both sides end. Hyper remains responsible for stream identifiers, stream credit, and flow control.

A peer route moves only generation identity. The socket, protocol driver, request handle, and capacity remain with the connection-owning partition.

ConnectionState separates logical close, accepted-request accounting, and physical connection ownership. Logical close rejects new dispatch and normally releases bounded capacity while accepted work drains. An HTTP/1 upgrade retains capacity until upgraded root I/O leaves the client. DispatchGuard follows an accepted request, while PhysicalConnectionGuard follows root I/O until the client releases its transport handle. The operating system may continue TCP teardown afterward. All connection-owned work runs through the partition DriverSpawner.

Observation

A pool-wide ConnectionEventListener observes establishment failure, successful installation, logical close, and release of the client’s root transport handle. Callbacks run synchronously after pool locks are released. Observation is disabled unless a listener is configured.

ConnectionPool::origin_stats reports the bounded capacity shared by all partitions for one canonical origin. ConnectionPool::partition_stats reports request acquisition and connection state for one exact partition-origin cell. These snapshots are diagnostic; the pool does not use them for admission, reuse, reclaim, routing, or dispatch.

Structs

BuildError

Error returned when a pool configuration is internally inconsistent.

Builder

Builds a partition-aware connection pool.

Client

Smithy HTTP client bound to one connection-pool partition.

ClientBuildError

Error returned when a Client cannot be resolved from a pool.

ConnectionCapacityStats

Bounded connection capacity shared by every partition for one origin.

ConnectionEstablishmentFailed

A terminal failure before a connection became available for pool dispatch.

ConnectionEstablishmentId

Opaque identity for one connection establishment.

ConnectionEstablishmentInfo

Stable identity and routing context for one pool-level establishment.

ConnectionEstablishmentStats

Measurements collected during one pool-level connection establishment.

ConnectionId

Opaque identifier for a physical HTTP connection.

ConnectionInfo

Immutable identity and transport facts for one installed connection.

ConnectionLogicalClose

Observation that an installed connection stopped accepting new dispatch.

ConnectionOpened

A connection installed and available for pool dispatch.

ConnectionPhysicalClose

Observation that the client released root transport ownership.

ConnectionPool

Shared connection topology and pooling policy.

DriverSpawner

Runtime placement for one partition’s connection-owned work.

Http1ConnectionStats

HTTP/1 connection state owned by one partition-origin cell.

Http2ConnectionStats

HTTP/2 connection state owned by one partition-origin cell.

InvalidOrigin

Error returned when a URI or set of parts does not name an HTTP origin.

OriginConnectionStats

Origin-wide connection capacity.

OriginKey

An owned, canonical HTTP or HTTPS origin.

Partition

Declares where a client’s connections are established and driven.

PartitionConnectionStats

Diagnostic connection state for one configured partition and origin.

PartitionId

Identifies one declared connection partition.

SharedConnectionEventListener

Cloneable, type-erased connection event listener.

Enums

CloseReason

Final protocol and ownership classification for a closed connection.

ConnectPath

How an established transport reaches its origin.

ConnectionEstablishmentStage

Stage that terminated one failed connection establishment.

ConnectionEvent

One connection establishment or installed-lifetime observation.

ConnectionProtocol

Protocol selected for one installed physical connection.

ConnectionReuseScope

Controls which partitions may dispatch through each other’s connections.

LogicalCloseCause

Stable cause recorded when pool dispatch ownership ends.

Traits

ConnectionEventListener

Receives connection lifecycle observations from one pool.