Skip to main content

core.net.weft — reverse-proxy and middleware

weft is Verum's reverse-proxy / server-side-middleware subsystem. It sits between the transport primitives in core.net.tcp / core.net.quic / core.net.tls and your application handlers, providing the orthogonal "plumbing" concerns that every production HTTP/HTTP2/HTTP3 server re-implements badly:

ConcernModuleOne-liner
Connection poolingcore.net.weft.connectionKeep-alive pools with health checks and graceful close.
Load balancingcore.net.weft.dstDestination resolution + weighted/round-robin/least-conn.
Health probescore.net.weft.healthActive probing + passive circuit state.
Circuit breakercore.net.weft.adaptiveOpen/half-open/closed state with adaptive windowing.
Retries + timeoutcore.net.weft.handlerExponential-backoff retries wrapped as middleware.
Rate limitercore.net.weft.backpressureToken bucket + leaky bucket per-route / per-principal.
Buffer poolcore.net.weft.bufpoolLock-free per-size-class byte-buffer recycling.
Arena poolcore.net.weft.arena_poolPer-request arena lifetimes — tear down in one free call.
SPIFFE identitycore.net.weft.spiffeX.509-SVID / JWT-SVID identity retrieval + mTLS trust anchors.
Metricscore.net.weft.metricsPrometheus-shaped counters / histograms / summaries per route.

Weft is deliberately unopinionated about HTTP version: the connection pool, health checker, circuit breaker, and retry middleware are indistinguishable between HTTP/1.1, HTTP/2, and HTTP/3. The HTTP-version-specific layer (http2 / http3) plugs in as a protocol adapter on top of the Weft primitives.

Status

Weft is staged for v1.1. The primitives listed above exist as core/net/weft/*.vr today (see the crate map); this page consolidates the API surface that's pinned to ship. Individual per-module pages will follow the same pattern used for stdlib/net/quic and stdlib/net/http3.

Connection​

core.net.weft.connection defines a generic connection-pool that holds an inner transport (TCP, QUIC, mTLS-wrapped TCP) and exposes acquire / release with configurable:

  • per-endpoint and global concurrency caps,
  • idle close timers,
  • health-check integration (drop unhealthy endpoints),
  • graceful shutdown (quiesce + drain to new requests).

Destination resolution​

core.net.weft.dst — a destination is a named set of endpoints plus a routing strategy:

  • round-robin (static),
  • weighted round-robin,
  • least-connections (observed),
  • consistent hashing (for sticky routing).

Health​

core.net.weft.health — active probers and passive observers. A probe produces Healthy | Degraded | Unhealthy and feeds into both the connection pool's eviction policy and the circuit breaker's state machine.

Adaptive circuit breaker​

core.net.weft.adaptive — three-state breaker (closed ↔ half-open ↔ open) with an adaptive failure-rate window. Trips from closed to open on sustained errors; admits single trial calls from open to half-open; closes when a trial succeeds.

Handler / middleware​

core.net.weft.handler — the composable middleware core. Each middleware is a fn(Request, Next) -> Response and can wrap retries, timeouts, circuit-breaking, logging, and tracing around the inner handler.

Backpressure / rate limiting​

core.net.weft.backpressure — token-bucket and leaky-bucket limiters keyed on per-route identifier, per-principal (from the SPIFFE identity), or per-client-IP.

Buffer pool​

core.net.weft.bufpool — lock-free pool of [Byte; N] buffers segmented by size class (256B / 1KB / 4KB / 16KB / 64KB). Allocation is Shared<Buffer> with refcount-free release on drop.

Arena pool​

core.net.weft.arena_pool — per-request bumping arena reused across requests. Allocations during request handling go into the arena; end-of-request triggers one bump reset (no individual free calls). See stdlib/security/regions for the integration with region-typed lifetimes.

SPIFFE identity​

core.net.weft.spiffe — implements SPIFFE / SPIRE client for X.509-SVID and JWT-SVID retrieval from a local Workload API endpoint, caches identity + trust bundle, and exposes a middleware layer that validates peer identities against an allow-list of SPIFFE IDs or trust domains. Used by stdlib/security/spiffe.

Metrics​

core.net.weft.metrics — Prometheus-shaped counters, gauges, histograms, and summaries keyed per-route. Integrates with core.metrics for scraping and exposition format.

See also​