@btravstack/http-server
The protocol-neutral Node HTTP runtime for @btravstack/core. It owns the
listener, HttpHandler set port, one unit per request, authentication helpers,
readiness, and graceful drain. Each protocol contributes a handler from its
own package:
@btravstack/orpc-serverfor contract-first oRPC and OpenAPI routes.@btravstack/htmx-serverfor escaped HTML fragments.@btravstack/graphql-serverfor a Yoga schema.
Choose the answerer packages for the deployment. The order API runs oRPC and htmx; the GraphQL gateway runs separately and calls the order API through its client package.
pnpm add @btravstack/http-server @btravstack/core @btravstack/config \
@btravstack/di unthrown
The HTTP runtime is composed by HttpModule (@btravstack/orpc-server) or
GraphqlModule (@btravstack/graphql-server); its HttpHandler members route
by longest matching prefix. defineAuth() names shared schemes without choosing a
protocol. JWT, session and OIDC helpers remain on /jwt, /session and
/oidc. Opt-in /oidc-tokens retains delegated access, refresh and ID tokens in
application-supplied shared storage, with refresh and logout serialized across
replicas. Pass its manager port to both the login and session authenticator;
credentials stay out of the principal and session cookie. Set
oidc()'s postLogoutRedirectUri or HTTP_OIDC_POST_LOGOUT_REDIRECT_URI to a
provider-registered absolute return URI to enable RP-initiated logout. The login
uses the retained ID token only as the provider's logout hint, after atomically
deleting the credentials. Without that setting, logout keeps its existing
parameterless behavior. See server-side OIDC tokens.
protectedResource() publishes Protected Resource Metadata (RFC 9728)
for one resource, protectedResourcePerHost() for one per served host. See the HTTP reference
for request units, security, configuration and shutdown behavior.
Application authenticators can return AuthenticatorUnavailable when a
dependency cannot decide. It stops the authentication walk and every HTTP
answerer returns 503, reporting the scheme through Observers. See
authentication dependency outages.
jwtAuthenticator() returns Unauthenticated when the issuer's key set is
unavailable or unusable. The answerer determines the response: usually 401,
or a 303 login redirect for a navigating browser on an htmx route with a
configured login route. It reports the outage through Observers
with component: "jwt", name: "verify", outcome: "error" and a bounded
reason, rather than returning AuthenticatorUnavailable. See the
JWT issuer-outage policy and its distinction from
authentication dependency outages.
Request-scoped providers may inject HttpRequestMetadata to decode headers,
method and URL independently of authentication. The runtime seeds its immutable
snapshot and cancellation signal once per request unit; it is unavailable in
application-scoped providers. See the HTTP reference.
jwtVerifier() on /jwt provides cached signed-evidence verification independently
of an HTTP authentication scheme. Inject JwtVerifier and supply the expected
audience on each verify({ token, audience }) call; issuer and JWKS trust remain
fixed at startup. See signed evidence.
JWT verifier options
issuer: pins the required issuer.jwks: pins the trusted key-set endpoint.variablePrefix: names the issuer/JWKS environment prefix.algorithms: pins the signature allowlist.clockToleranceSec: pins expiry/not-before leeway.allowInsecureJwks: explicitly permits non-loopback cleartext development keys.port: names a second issuer's verifier capability.
Defaults and configuration semantics are in the HTTP reference.
Listener options
port,hostname: bind the listener.headersTimeoutMs,requestTimeoutMs: bound request reception.keepAliveTimeoutMs: bound idle reusable connections after a response.keepAliveTimeoutBufferMs: extend the actual keepalive lifetime beyond its advertised budget.socketTimeoutMs: bound inactivity during request and response progress.
Each has a matching environment variable; defaults, zero semantics and Node compatibility are in the HTTP reference.