silk/http_connection_pool

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc.

Bounded local HTTP/1 connection pooling with explicit ownership and deterministic eviction.

Details

A pool preallocates every shared slot before publication. Shared callbacks only scan and move already-owned values; clock reads, connector calls, user callbacks, allocation, and physical close operations remain outside shared access. Capacity is fail-fast and local to one scheduler thread. There is no waiter queue, background expiry worker, request replay, HTTP/2 coalescing, or WebSocket pooling.

Import as Pool with import silk.http_connection_pool { Pool }.

Public declarations: 27.

DEFAULT_MAX_TOTAL

pub const DEFAULT_MAX_TOTAL: usize

Default maximum number of opening, leased, and idle connections together.

DEFAULT_MAX_IDLE

pub const DEFAULT_MAX_IDLE: usize

Default maximum number of retained idle connections.

DEFAULT_MAX_PER_ORIGIN

pub const DEFAULT_MAX_PER_ORIGIN: usize

Default maximum number of connections for one normalized original origin.

DEFAULT_IDLE_TIMEOUT_NANOSECONDS

pub const DEFAULT_IDLE_TIMEOUT_NANOSECONDS: u64

Default idle lifetime in nanoseconds.

MAX_TOTAL

pub const MAX_TOTAL: usize

Hard maximum total pool capacity.

Config

pub struct Config

Finite pool limits admitted before shared state is allocated.

Field maxTotal

pub maxTotal: usize

Maximum opening, leased, and idle count.

Field maxIdle

pub maxIdle: usize

Maximum retained idle count. Zero disables retention.

Field maxPerOrigin

pub maxPerOrigin: usize

Maximum count for one normalized original origin.

Field idleTimeoutNanoseconds

pub idleTimeoutNanoseconds: u64

Positive idle lifetime on the pool's monotonic timeline.

Associated function Config.defaults

pub fn defaults() -> Config

Returns the finite standard limits: 32 total, 16 idle, 8 per origin, and 30 seconds idle.

Implementation Copy for Config

impl Copy for Config

ConfigField

pub enum ConfigField

The configuration field rejected before pool publication.

MaxTotal

MaxTotal = 0

maxTotal is outside 1 through 1024.

MaxIdle

MaxIdle = 1

maxIdle exceeds maxTotal.

MaxPerOrigin

MaxPerOrigin = 2

maxPerOrigin is zero or exceeds maxTotal.

IdleTimeout

IdleTimeout = 3

The idle duration is zero.

PoolError

pub union PoolError

A pool admission, capacity, lifecycle, or checked-accounting failure.

InvalidConfig

PoolError.InvalidConfig { field: ConfigField }: PoolError

Configuration was rejected before allocation or publication.

Field field

pub field: ConfigField

The configuration field whose value is outside its admitted range.

PoolFull

PoolError.PoolFull: PoolError

No legal idle eviction can satisfy global and per-origin capacity.

PoolClosed

PoolError.PoolClosed: PoolError

The root pool has closed; surviving handles cannot acquire or publish.

ContextMismatch

PoolError.ContextMismatch: PoolError

The key is incompatible with the handle's frozen acquisition/security context.

OpeningExpired

PoolError.OpeningExpired: PoolError

Opening could not begin or completed at or after its effective acquisition deadline.

Implementation Copy for PoolError

impl Copy for PoolError

Counts

pub struct Counts

A synchronous snapshot of bounded shared accounting.

Field opening

pub opening: usize

Connections whose capacity is reserved while opening.

Field leased

pub leased: usize

Connections currently lent to callbacks.

Field idle

pub idle: usize

Complete connections retained for later reuse.

Field total

pub total: usize

opening + leased + idle.

Field closed

pub closed: bool

Whether root ownership has closed the pool.

Implementation Copy for Counts

impl Copy for Counts

Collection

pub struct Collection

Result of explicit lazy expiry collection.

Field expired

pub expired: usize

Number of expired idle owners physically closed by this call.

Implementation Copy for Collection

impl Copy for Collection

CheckoutSource

pub enum CheckoutSource

Whether checkout selected an idle owner or opened a new one.

Reused

Reused = 0

A compatible most-recently-returned idle owner was selected.

Opened

Opened = 1

Capacity was reserved and the immutable connector opened a new owner.

CheckoutResult

pub struct CheckoutResult<A>

A successful callback value paired with its checkout source.

Field value

pub value: A

The callback result.

Field source

pub source: CheckoutSource

How the exclusive owner was obtained.

PoolKey

pub interface PoolKey<CopyError, ?CopyRequirements>

Compile-time contract for an independently owned conservative connection key.

Operation copy

effect<'env> fn copy<'life2: 'env, 'env>(key: &'life2 Self) -> Self ! CopyError ? CopyRequirements

Copies the complete key before entering shared state.

Operation equals

fn equals<'life2, 'life3>(left: &'life2 Self, right: &'life3 Self) -> bool

Reports exact route, provider, and security compatibility.

Operation sameOrigin

fn sameOrigin<'life2, 'life3>(left: &'life2 Self, right: &'life3 Self) -> bool

Reports normalized original-origin equality for the per-origin cap.

PoolContextCopy

pub interface PoolContextCopy<CopyError, ?CopyRequirements>

Fallible bounded-copy contract for immutable context retained beside shared mutable state.

Operation copy

effect<'env> fn copy<'life2: 'env, 'env>(context: &'life2 Self) -> Self ! CopyError ? CopyRequirements

Fallibly copies all bounded context before a new Shared alias is published.

PoolContext

pub interface PoolContext<K, P, AcquisitionError, ?AcquisitionRequirements>

Immutable acquisition context retained beside, never inside, shared mutable state.

Operation accepts

fn accepts<'life4, 'life5>(context: &'life4 Self, key: &'life5 K) -> bool

Checks key compatibility without allocation, clock access, or transport contact.

Operation acquire

effect<'env> fn acquire<'life4: 'env, 'life5: 'env, 'env>(context: &'life4 Self, key: &'life5 K, deadline: silk/option.Option<silk/system_clock.Instant>) -> silk/http_client.Connection<P> ! AcquisitionError ? AcquisitionRequirements

Opens one complete HTTP owner under only the effective acquisition deadline.

PoolHandler

pub interface PoolHandler<K, P, C, A, E, ?R>

A higher-ranked root-pool callback whose pool borrow cannot escape.

Operation handle

effect<'scope> fn handle<'scope: 'scope>(handler: Self, pool: &'scope mut silk/http_connection_pool.Pool<K, P, C>) -> A ! E ? R

Uses one root pool until success, failure, or structured cancellation closes it.

EndpointIdentity

pub union EndpointIdentity

Exact endpoint identity retained by the standard conservative key.

Direct

EndpointIdentity.Direct: EndpointIdentity

Direct network contact, conservatively partitioned by the original origin.

Proxy

EndpointIdentity.Proxy { route: RouteKey }: EndpointIdentity

A sealed JUL-199 route, including mode, endpoint, original origin, and credential identity.

Field route

pub route: RouteKey

The sealed proxy route identity used to partition reusable connections.

Unix

EndpointIdentity.Unix { path: Bytes }: EndpointIdentity

Direct Unix-domain contact with an exact owned pathname.

ConnectionKey

pub struct ConnectionKey

The standard conservative key used by direct native and proxy-aware pool contexts.

Details

Provider representation, HTTP policy, TLS verification/trust/ALPN policy, and connector policy belong to the constructor-sealed PoolContext. This key retains only request-visible route identity; direct resolution results never establish equivalence.

Associated function ConnectionKey.direct

pub fn direct(originalOrigin: Origin) -> ConnectionKey

Creates a direct network key from the normalized original origin without allocation.

Associated function ConnectionKey.proxy

pub fn proxy(route: RouteKey) -> ConnectionKey

Creates a proxy-aware key from the sealed JUL-199 route identity.

Associated function ConnectionKey.unix

pub effect<'life0> fn unix<'life0>(originalOrigin: Origin, path: &'life0 [u8]) -> ConnectionKey ! OutOfMemoryError ? &mut Allocator

Copies one exact Unix pathname into a conservative direct key.

Method ConnectionKey.origin

pub fn origin<'life0>(self: &'life0 ConnectionKey) -> Origin

Returns the normalized original origin used for per-origin capacity.

Method ConnectionKey.isDirect

pub fn isDirect<'life0>(self: &'life0 ConnectionKey) -> bool

Returns whether this key selects direct native contact for its original origin.

Method ConnectionKey.matchesUnixPath

pub fn matchesUnixPath<'life0, 'life1>(self: &'life0 ConnectionKey, path: &'life1 [u8]) -> bool

Returns whether this key selects the exact supplied Unix path for its original origin.

Implementation silk/http_connection_pool.PoolKey<silk/allocator.OutOfMemoryError, ? &mut silk/allocator.Allocator> for ConnectionKey

impl silk/http_connection_pool.PoolKey<silk/allocator.OutOfMemoryError, ? &mut silk/allocator.Allocator> for ConnectionKey

Operation copy

copy = ConnectionKey.impl@4.copy

Operation equals

equals = ConnectionKey.impl@4.equals

Operation sameOrigin

sameOrigin = ConnectionKey.impl@4.sameOrigin

Pool

pub struct Pool<K, P, C>

The scoped root owner. Use withPool so closure runs on every structured exit.

Method Pool.handle

pub fn handle<K, P, C, 'life3>(self: &'life3 Pool<K, P, C>) -> &'life3 silk/http_connection_pool.Handle<K, P, C>

Borrows the root handle without publishing another Shared alias.

Handle

pub struct Handle<K, P, C>

A fallibly copied local handle sharing only preallocated mutable slot state.

context

pub fn context<'handle, K, P, C>(handle: &'handle silk/http_connection_pool.Handle<K, P, C>) -> &'handle C

Borrows one handle's immutable acquisition context without exposing shared slot state.

withPool

pub effect<'env> fn withPool<K, P, C: 'env, A, E, ?R, H: 'env, 'env>(config: Config, context: C, handler: H) -> A ! E | PoolError | OutOfMemoryError ? R | &mut Allocator where &mut P provides &HttpTransport from &mut HttpTransport

Constructs one finite pool, lends its root, and closes it on every structured exit.

copyHandle

pub effect<'env> fn copyHandle<K: 'env, P: 'env, CopyError, ?CopyRequirements, C: 'env, 'life5: 'env, 'env>(handle: &'life5 silk/http_connection_pool.Handle<K, P, C>) -> silk/http_connection_pool.Handle<K, P, C> ! CopyError ? CopyRequirements

Copies immutable context before cloning Shared state, so copy failure publishes no alias.

counts

pub fn counts<K, P, C, 'life3>(handle: &'life3 silk/http_connection_pool.Handle<K, P, C>) -> Counts

Inspects exact shared accounting without allocating or consulting the clock.

withConnection

pub effect<'env> fn withConnection<P: 'env, A, E, KeyCopyError, AcquisitionError, ?KeyCopyRequirements, ?AcquisitionRequirements, ?CallbackRequirements, K: 'env, C: 'env, H: 'env, 'life11: 'env, 'life12: 'env, 'env>(handle: &'life11 silk/http_connection_pool.Handle<K, P, C>, key: &'life12 K, requestDeadline: silk/option.Option<silk/system_clock.Instant>, acquisitionDeadline: silk/option.Option<silk/system_clock.Instant>, handler: H) -> silk/http_connection_pool.CheckoutResult<A> ! E | KeyCopyError | AcquisitionError | PoolError ? KeyCopyRequirements | AcquisitionRequirements | CallbackRequirements | &mut MonotonicClock where &mut P provides &HttpTransport from &mut HttpTransport | &mut MonotonicClock | &mut Allocator | &mut Random, &mut P provides &HttpTransport from &mut HttpTransport

Checks out exactly one owner, lends it to handler, and publishes it only when client-eligible.

Details

Acquisition uses the earlier of requestDeadline and acquisitionDeadline; the connector must construct pooled owners without retaining that bound. The handler remains responsible for passing the unchanged request deadline to each HTTP exchange. Failures and cancellation close instead of replaying the request.

collect

pub effect<'env> fn collect<K: 'env, P: 'env, C: 'env, 'life3: 'env, 'env>(handle: &'life3 silk/http_connection_pool.Handle<K, P, C>) -> Collection ? &mut MonotonicClock where &mut P provides &HttpTransport from &mut HttpTransport

Samples the monotonic clock once, lazily removes every expired idle owner, and closes outside Shared.

close

pub effect<'env> fn close<K: 'env, P: 'env, C: 'env, 'life3: 'env, 'env>(pool: &'life3 mut silk/http_connection_pool.Pool<K, P, C>) -> () ! ClientError where &mut P provides &HttpTransport from &mut HttpTransport

Marks the pool closed idempotently and physically closes all currently idle owners outside Shared.