@furystack/rest-service 13.0.0 → 14.1.0

package/src/helpers.ts

@@ -1,55 +1,138 @@
-import type { User } from '@furystack/core'
 import { useSystemIdentityContext } from '@furystack/core'
 import type { Injector } from '@furystack/inject'
 import type { RestApi } from '@furystack/rest'
-import type { DataSet } from '@furystack/repository'
 import { PasswordAuthenticator } from '@furystack/security'
-
-import type { ImplementApiOptions } from './api-manager.js'
-import { ApiManager } from './api-manager.js'
+import { PathHelper } from '@furystack/utils'
 import type { AuthenticationProvider } from './authentication-providers/authentication-provider.js'
 import { createBasicAuthProvider } from './authentication-providers/basic-auth-provider.js'
 import { createCookieAuthProvider } from './authentication-providers/cookie-auth-provider.js'
 import { authenticateUserWithDataSet, findSessionById, findUserByName } from './authentication-providers/helpers.js'
-import { HttpAuthenticationSettings } from './http-authentication-settings.js'
-import type { DefaultSession } from './models/default-session.js'
-import type { ProxyOptions } from './proxy-manager.js'
-import { ProxyManager } from './proxy-manager.js'
-import type { StaticServerOptions } from './static-server-manager.js'
-import { StaticServerManager } from './static-server-manager.js'
+import { CreateGetOpenApiDocumentAction } from './endpoint-generators/create-get-openapi-document-action.js'
+import { CreateGetSchemaAction } from './endpoint-generators/create-get-schema-action.js'
+import { defaultHttpAuthenticationSettings, HttpAuthenticationSettings } from './http-authentication-settings.js'
+import { HttpServerPoolToken, type ServerApi } from './http-server-pool.js'
+import { HttpUserContext } from './http-user-context.js'
+import type { CorsOptions } from './models/cors-options.js'
+import { buildProxyServerApi, type ProxyOptions } from './proxy-runtime.js'
+import { compileApi, onRestApiMessage, type RestApiImplementation, shouldExecRequest } from './rest-api-runtime.js'
+import { ServerTelemetryToken } from './server-telemetry.js'
+import { buildStaticSiteServerApi, type StaticServerOptions } from './static-site-runtime.js'
+import type { SessionStore, UserStore } from './user-store.js'
 
 /**
- * Sets up the @furystack/rest-service with the provided settings
- * @param api The API implementation details
- * @returns a promise that resolves when the API is added to the server
+ * Options accepted by {@link useRestService}. Cross-cutting concerns
+ * (authentication, telemetry) have moved to DI tokens — they are not
+ * configured here.
  */
-export const useRestService = async <T extends RestApi>(api: ImplementApiOptions<T>) =>
-  await api.injector.getInstance(ApiManager).addApi({ ...api })
+export interface ImplementApiOptions<T extends RestApi> {
+  /** The structure of the implemented API. */
+  api: RestApiImplementation<T>
+  /** Injector used to resolve request-scoped services and to acquire the HTTP server. */
+  injector: Injector
+  /** Optional host name; defaults to `localhost`. */
+  hostName?: string
+  /** Root path prepended to every API route. */
+  root: string
+  /** Port the API should listen on. */
+  port: number
+  /** Optional CORS configuration applied to every matched request. */
+  cors?: CorsOptions
+  /** Optional query-string deserialiser override. */
+  deserializeQueryParams?: (param: string) => Record<string, unknown>
+  /** When `true`, adds `GET /schema` and `GET /openapi.json` endpoints. */
+  enableGetSchema?: boolean
+  /** OpenAPI display name. */
+  name?: string
+  /** OpenAPI description. */
+  description?: string
+  /** OpenAPI version. */
+  version?: string
+}
 
 /**
- * Sets up the HTTP Authentication with pluggable providers.
- *
- * Registers Basic Auth (if enabled) and Cookie Auth as built-in providers,
- * then appends any custom providers passed via settings.
+ * Acquires a pooled HTTP server (creating one if needed), compiles `api`
+ * and attaches a {@link ServerApi} that dispatches matching requests.
+ * Multiple `useRestService` calls on the same `port` + `hostName` share a
+ * single underlying HTTP server.
+ */
+export const useRestService = async <T extends RestApi>(options: ImplementApiOptions<T>): Promise<ServerApi> => {
+  const {
+    injector,
+    api,
+    hostName,
+    port,
+    root,
+    cors,
+    deserializeQueryParams,
+    enableGetSchema,
+    name,
+    description,
+    version,
+  } = options
+
+  const extendedApi: typeof api = enableGetSchema
+    ? {
+        ...api,
+        GET: {
+          ...api.GET,
+          '/schema': CreateGetSchemaAction(api, name, description, version),
+          '/openapi.json': CreateGetOpenApiDocumentAction(api, name, description, version),
+        },
+      }
+    : api
+
+  const supportedMethods = Object.keys(extendedApi)
+  const rootApiPath = PathHelper.normalize(root)
+  const compiledApi = compileApi(extendedApi, root)
+
+  const serverApi: ServerApi = {
+    shouldExec: ({ req }) =>
+      shouldExecRequest({
+        method: req.method?.toUpperCase() as never,
+        url: PathHelper.normalize(req.url || ''),
+        rootApiPath,
+        supportedMethods,
+      }),
+    onRequest: (msg) =>
+      onRestApiMessage({
+        ...msg,
+        compiledApi,
+        rootApiPath,
+        port,
+        supportedMethods,
+        cors,
+        injector,
+        hostName,
+        deserializeQueryParams,
+      }),
+  }
+
+  const pool = injector.get(HttpServerPoolToken)
+  const record = await pool.acquire({ port, hostName })
+  record.apis.push(serverApi)
+  return serverApi
+}
+
+/**
+ * Installs HTTP authentication on the given injector: builds the provider
+ * chain (Basic + Cookie by default), appends any caller-provided providers
+ * and rebinds {@link HttpAuthenticationSettings}.
  *
- * @param injector  The Injector instance
- * @param settings Settings for HTTP Authentication
+ * Prerequisite: {@link UserStore} and {@link SessionStore} must be bound to
+ * persistent implementations before calling this helper, since the Basic
+ * and Cookie providers need to read users and sessions immediately.
  */
-export const useHttpAuthentication = <TUser extends User, TSession extends DefaultSession>(
-  injector: Injector,
-  settings?: Partial<HttpAuthenticationSettings<TUser, TSession>>,
-) => {
-  const mergedSettings = Object.assign(new HttpAuthenticationSettings<TUser, TSession>(), settings)
+export const useHttpAuthentication = (injector: Injector, overrides?: Partial<HttpAuthenticationSettings>): void => {
+  const mergedSettings: HttpAuthenticationSettings = {
+    ...defaultHttpAuthenticationSettings(),
+    ...overrides,
+  }
   const systemInjector = useSystemIdentityContext({ injector, username: 'useHttpAuthentication' })
-  const passwordAuthenticator = injector.getInstance(PasswordAuthenticator)
-  const userDataSet = mergedSettings.getUserDataSet(systemInjector) as unknown as DataSet<User, 'username'>
-  const sessionDataSet = mergedSettings.getSessionDataSet(systemInjector) as unknown as DataSet<
-    DefaultSession,
-    'sessionId'
-  >
+  const passwordAuthenticator = injector.get(PasswordAuthenticator)
+  const userDataSet = systemInjector.get(mergedSettings.userDataSet)
+  const sessionDataSet = systemInjector.get(mergedSettings.sessionDataSet)
 
   const providers: AuthenticationProvider[] = []
-
   if (mergedSettings.enableBasicAuth) {
     providers.push(
       createBasicAuthProvider((username, password) =>
@@ -57,7 +140,6 @@ export const useHttpAuthentication = <TUser extends User, TSession extends Defau
       ),
     )
   }
-
   providers.push(
     createCookieAuthProvider(
       mergedSettings.cookieName,
@@ -65,90 +147,39 @@ export const useHttpAuthentication = <TUser extends User, TSession extends Defau
       (username) => findUserByName(userDataSet, systemInjector, username),
     ),
   )
-
-  providers.push(...(settings?.authenticationProviders ?? []))
+  providers.push(...(overrides?.authenticationProviders ?? []))
   mergedSettings.authenticationProviders = providers
 
-  injector.setExplicitInstance(mergedSettings, HttpAuthenticationSettings)
+  injector.bind(HttpAuthenticationSettings, () => mergedSettings)
+  injector.invalidate(HttpAuthenticationSettings)
+  injector.invalidate(HttpUserContext)
 }
 
 /**
- * Sets up a static file server
- * @param options The settings for the static file server
- * @param options.injector The Injector instance
- * @param options.settings Settings for the static file server
- * @returns a promise that resolves when the server is ready
+ * Attaches a static-file {@link ServerApi} to the pooled HTTP server
+ * identified by `options.port`/`options.hostName`.
  */
-export const useStaticFiles = (options: { injector: Injector } & StaticServerOptions) => {
+export const useStaticFiles = async (options: { injector: Injector } & StaticServerOptions): Promise<ServerApi> => {
   const { injector, ...settings } = options
-  return injector.getInstance(StaticServerManager).addStaticSite(settings)
+  const pool = injector.get(HttpServerPoolToken)
+  const record = await pool.acquire({ port: settings.port, hostName: settings.hostName })
+  const serverApi = buildStaticSiteServerApi(settings)
+  record.apis.push(serverApi)
+  return serverApi
 }
 
 /**
- * Sets up a proxy server that forwards HTTP requests from a source URL to a target URL.
- *
- * The proxy acts as an intermediary, forwarding requests and responses while allowing
- * transformation of headers, cookies, and paths. It returns 502 Bad Gateway on errors
- * and emits 'onProxyFailed' events for monitoring.
- *
- * WebSocket connections can also be proxied by setting `enableWebsockets: true`, allowing
- * bidirectional real-time communication through the proxy.
- *
- * @param options The settings for the proxy server
- * @param options.injector The Injector instance
- * @param options.sourceBaseUrl The base URL path to match for proxying (e.g., '/api', '/old').
- *                               Can be specified with or without a trailing slash.
- * @param options.targetBaseUrl The target server URL (must be a valid HTTP/HTTPS URL)
- * @param options.pathRewrite Optional function to rewrite the path before forwarding.
- *                            Receives the path after sourceBaseUrl, including leading slash and query string.
- *                            Example: for 'GET /api/users?active=true' with sourceBaseUrl='/api',
- *                            pathRewrite receives '/users?active=true'
- * @param options.sourceHostName The hostname for the source server (optional, defaults to all interfaces)
- * @param options.sourcePort The port for the source server
- * @param options.headers Optional function to transform request headers.
- *                        **Note**: Receives headers AFTER filtering hop-by-hop headers
- *                        (Connection, Keep-Alive, Transfer-Encoding, Upgrade, etc.) for security
- *                        and protocol compliance. The proxy automatically adds X-Forwarded-* headers.
- *                        This transformation applies to both HTTP and WebSocket requests.
- * @param options.cookies Optional function to transform request cookies (array of cookie strings)
- * @param options.responseCookies Optional function to transform response Set-Cookie headers
- * @param options.timeout Optional timeout in milliseconds for proxy requests (default: 30000).
- *                        If exceeded, the request is aborted and 502 is returned.
- *                        Applies to both HTTP and WebSocket upgrade requests.
- * @param options.enableWebsockets Optional flag to enable WebSocket proxying (default: false).
- *                                 When enabled, WebSocket upgrade requests will be forwarded to the target.
- * @returns a promise that resolves when the proxy is set up
- * @example
- * ```ts
- * // Basic HTTP proxy with timeout
- * await useProxy({
- *   injector,
- *   sourceBaseUrl: '/api',
- *   targetBaseUrl: 'https://api.example.com',
- *   sourcePort: 3000,
- *   timeout: 5000,
- * })
- *
- * // Proxy with WebSocket support
- * await useProxy({
- *   injector,
- *   sourceBaseUrl: '/ws',
- *   targetBaseUrl: 'https://ws.example.com',
- *   sourcePort: 3000,
- *   enableWebsockets: true,
- * })
- *
- * // Proxy with error monitoring (HTTP and WebSocket)
- * const proxyManager = injector.getInstance(ProxyManager)
- * proxyManager.subscribe('onProxyFailed', ({ from, to, error }) => {
- *   console.error(`HTTP Proxy failed: ${from} -> ${to}`, error)
- * })
- * proxyManager.subscribe('onWebSocketProxyFailed', ({ from, to, error }) => {
- *   console.error(`WebSocket Proxy failed: ${from} -> ${to}`, error)
- * })
- * ```
+ * Attaches a proxy {@link ServerApi} that forwards HTTP (and optionally
+ * WebSocket) traffic from `options.sourceBaseUrl` to `options.targetBaseUrl`.
+ * Emits `onProxyFailed` and `onWebSocketProxyFailed` events into the shared
+ * {@link ServerTelemetryToken} — subscribe there for observability.
  */
-export const useProxy = (options: { injector: Injector } & ProxyOptions) => {
+export const useProxy = async (options: { injector: Injector } & ProxyOptions): Promise<ServerApi> => {
   const { injector, ...settings } = options
-  return injector.getInstance(ProxyManager).addProxy(settings)
+  const telemetry = injector.get(ServerTelemetryToken)
+  const pool = injector.get(HttpServerPoolToken)
+  const record = await pool.acquire({ port: settings.sourcePort, hostName: settings.sourceHostName })
+  const serverApi = buildProxyServerApi(settings, telemetry)
+  record.apis.push(serverApi)
+  return serverApi
 }

package/src/http-authentication-settings.ts

@@ -1,32 +1,86 @@
-import { User } from '@furystack/core'
-import type { Constructable, Injector } from '@furystack/inject'
-import { Injectable } from '@furystack/inject'
-import { getDataSetFor } from '@furystack/repository'
+import type { User } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
+import { defineService, type Token } from '@furystack/inject'
+import type { DataSetToken } from '@furystack/repository'
 import type { AuthenticationProvider } from './authentication-providers/authentication-provider.js'
-import { DefaultSession } from './models/default-session.js'
+import type { useHttpAuthentication } from './helpers.js'
+import type { HttpUserContext } from './http-user-context.js'
+import type { DefaultSession } from './models/default-session.js'
+import { SessionDataSet, UserDataSet } from './user-store.js'
 
 /**
- * Authentication settings object for FuryStack HTTP Api
+ * HTTP-authentication settings — rebound by {@link useHttpAuthentication}
+ * during application setup and consumed by {@link HttpUserContext},
+ * cookie-login strategies and OpenAPI generators.
+ *
+ * `userDataSet` / `sessionDataSet` are token references — consumers resolve
+ * them through the injector at the appropriate scope. `authenticationProviders`
+ * is an ordered list walked by {@link HttpUserContext} on every
+ * unauthenticated request.
  */
-@Injectable({ lifetime: 'singleton' })
-export class HttpAuthenticationSettings<TUser extends User, TSession extends DefaultSession> {
-  public model: Constructable<TUser> = User as Constructable<TUser>
-
-  public getUserDataSet = (injector: Injector) =>
-    getDataSetFor(injector, this.model, 'username' as 'username' & keyof TUser)
+export interface HttpAuthenticationSettings {
+  /** Data set token for user lookups. */
+  userDataSet: DataSetToken<User, 'username'>
+  /** Data set token for session lookups. */
+  sessionDataSet: DataSetToken<DefaultSession, 'sessionId'>
+  /** Cookie name used by the built-in cookie-auth provider. */
+  cookieName: string
+  /** Whether the built-in Basic Auth provider is installed by {@link useHttpAuthentication}. */
+  enableBasicAuth: boolean
+  /**
+   * Ordered list of authentication providers. Populated during
+   * {@link useHttpAuthentication} and extended by plugins such as
+   * `useJwtAuthentication`.
+   */
+  authenticationProviders: AuthenticationProvider[]
+  /**
+   * TTL applied to the user-resolution cache. Every authenticated request
+   * runs at most one provider chain walk per cache key per TTL window;
+   * subsequent calls within the window return the cached `User`.
+   *
+   * Bounds the staleness window for out-of-band identity changes
+   * (session invalidation on a sibling instance, role mutation in storage,
+   * etc.) when the application is deployed across multiple nodes.
+   *
+   * Set to `0` to disable caching entirely. When omitted, the default
+   * {@link DEFAULT_USER_CACHE_TTL_MS} is used by `UserResolutionCache`.
+   */
+  userCacheTtlMs?: number
+  /**
+   * Maximum number of entries in the user-resolution cache before LRU
+   * eviction kicks in. When omitted, the default
+   * {@link DEFAULT_USER_CACHE_CAPACITY} is used by `UserResolutionCache`.
+   */
+  userCacheCapacity?: number
+}
 
-  public sessionModel: Constructable<TSession> = DefaultSession as Constructable<TSession>
+/** Default TTL applied to the user-resolution cache (30 seconds). */
+export const DEFAULT_USER_CACHE_TTL_MS = 30_000
 
-  public getSessionDataSet = (injector: Injector) =>
-    getDataSetFor(injector, this.sessionModel, 'sessionId' as 'sessionId' & keyof TSession)
+/** Default LRU capacity ceiling for the user-resolution cache. */
+export const DEFAULT_USER_CACHE_CAPACITY = 10_000
 
-  public cookieName = 'fss'
-  public enableBasicAuth = true
+/**
+ * Returns a fresh copy of the default {@link HttpAuthenticationSettings}.
+ * Used as the starting point inside {@link useHttpAuthentication}.
+ */
+export const defaultHttpAuthenticationSettings = (): HttpAuthenticationSettings => ({
+  userDataSet: UserDataSet,
+  sessionDataSet: SessionDataSet,
+  cookieName: 'fss',
+  enableBasicAuth: true,
+  authenticationProviders: [],
+  userCacheTtlMs: DEFAULT_USER_CACHE_TTL_MS,
+  userCacheCapacity: DEFAULT_USER_CACHE_CAPACITY,
+})
 
-  /**
-   * Ordered list of authentication providers. Populated by {@link useHttpAuthentication}
-   * and extended by `useJwtAuthentication()` or other auth plugins.
-   * Safe to mutate only during setup, before the first request is served.
-   */
-  public authenticationProviders: AuthenticationProvider[] = []
-}
+/**
+ * DI token carrying the current {@link HttpAuthenticationSettings}. Rebind
+ * via {@link useHttpAuthentication} (preferred) or directly through
+ * {@link Injector.bind} for advanced scenarios.
+ */
+export const HttpAuthenticationSettings: Token<HttpAuthenticationSettings, 'singleton'> = defineService({
+  name: 'furystack/rest-service/HttpAuthenticationSettings',
+  lifetime: 'singleton',
+  factory: () => defaultHttpAuthenticationSettings(),
+})

package/src/http-server-pool.spec.ts

@@ -0,0 +1,220 @@
+import { getPort } from '@furystack/core/port-generator'
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import type { IncomingMessage, ServerResponse } from 'http'
+import { describe, expect, it, vi } from 'vitest'
+import { WebSocket } from 'ws'
+import { HttpServerPoolToken, type OnRequest, type OnUpgrade, type ServerApi } from './http-server-pool.js'
+import { ServerTelemetryToken } from './server-telemetry.js'
+
+/** Returns a `ServerApi` that executes `handler` on every matching request. */
+const makeApi = (handler: (options: OnRequest) => Promise<void>): ServerApi => ({
+  shouldExec: () => true,
+  onRequest: handler,
+})
+
+describe('HttpServerPool', () => {
+  it('Should return the cached record on subsequent acquire calls for the same url', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      const first = await pool.acquire({ port })
+      const second = await pool.acquire({ port })
+      expect(second).toBe(first)
+    })
+  })
+
+  it('Should de-duplicate concurrent acquire calls into a single server creation', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      const [a, b, c] = await Promise.all([pool.acquire({ port }), pool.acquire({ port }), pool.acquire({ port })])
+      expect(b).toBe(a)
+      expect(c).toBe(a)
+    })
+  })
+
+  it('Should emit onServerListening when a new record is opened', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const telemetry = injector.get(ServerTelemetryToken)
+      const listening = vi.fn()
+      telemetry.subscribe('onServerListening', listening)
+
+      const port = getPort()
+      await injector.get(HttpServerPoolToken).acquire({ port })
+      expect(listening).toHaveBeenCalledWith({ url: `http://localhost:${port}`, port, hostName: undefined })
+    })
+  })
+
+  it('Should destroy the socket and route the rejection through telemetry when onUpgrade rejects', async () => {
+    const injector = createInjector()
+    try {
+      const pool = injector.get(HttpServerPoolToken)
+      const telemetry = injector.get(ServerTelemetryToken)
+      const onRequestFailed = vi.fn()
+      telemetry.subscribe('onRequestFailed', onRequestFailed)
+
+      const port = getPort()
+      const record = await pool.acquire({ port })
+
+      const rejection = new Error('upgrade boom')
+      const onUpgrade = vi.fn<(options: OnUpgrade) => Promise<void>>().mockRejectedValue(rejection)
+      record.apis.push({
+        shouldExec: () => true,
+        onRequest: () => Promise.resolve(),
+        onUpgrade,
+      })
+
+      const socketClosed = new Promise<void>((resolve) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${port}`)
+        ws.on('close', () => resolve())
+        ws.on('error', () => resolve())
+      })
+      await socketClosed
+      await new Promise((r) => setTimeout(r, 20))
+
+      expect(onUpgrade).toHaveBeenCalledTimes(1)
+      expect(onRequestFailed).toHaveBeenCalledTimes(1)
+      const [error] = onRequestFailed.mock.calls[0][0] as [unknown, IncomingMessage, ServerResponse]
+      expect(error).toBe(rejection)
+    } finally {
+      await injector[Symbol.asyncDispose]()
+    }
+  })
+
+  it('Should destroy the socket when no API claims the upgrade', async () => {
+    const injector = createInjector()
+    try {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      await pool.acquire({ port })
+
+      const ws = new WebSocket(`ws://127.0.0.1:${port}`)
+      await new Promise<void>((resolve) => {
+        ws.on('close', () => resolve())
+        ws.on('error', () => resolve())
+      })
+      expect(ws.readyState).toBe(WebSocket.CLOSED)
+    } finally {
+      await injector[Symbol.asyncDispose]()
+    }
+  })
+
+  it('Should destroy the raw socket when no API matches a normal request', async () => {
+    const injector = createInjector()
+    try {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      await pool.acquire({ port })
+
+      await expect(fetch(`http://127.0.0.1:${port}/nothing`)).rejects.toBeDefined()
+    } finally {
+      await injector[Symbol.asyncDispose]()
+    }
+  })
+
+  it('Should surface onRequest rejections through telemetry without crashing the server', async () => {
+    const injector = createInjector()
+    try {
+      const pool = injector.get(HttpServerPoolToken)
+      const telemetry = injector.get(ServerTelemetryToken)
+      const onRequestFailed = vi.fn()
+      telemetry.subscribe('onRequestFailed', onRequestFailed)
+
+      const port = getPort()
+      const record = await pool.acquire({ port })
+      const rejection = new Error('request boom')
+      record.apis.push(
+        makeApi(async ({ res }) => {
+          res.end()
+          throw rejection
+        }),
+      )
+
+      await fetch(`http://127.0.0.1:${port}/test`)
+      await new Promise((r) => setTimeout(r, 20))
+
+      expect(onRequestFailed).toHaveBeenCalledTimes(1)
+      const [error] = onRequestFailed.mock.calls[0][0] as [unknown, IncomingMessage, ServerResponse]
+      expect(error).toBe(rejection)
+    } finally {
+      await injector[Symbol.asyncDispose]()
+    }
+  })
+
+  it('Should destroy open client sockets during disposal', async () => {
+    const injector = createInjector()
+    const pool = injector.get(HttpServerPoolToken)
+    const port = getPort()
+    const record = await pool.acquire({ port })
+
+    record.apis.push({
+      shouldExec: () => true,
+      onRequest: async ({ res }) => {
+        res.writeHead(200)
+        res.write('streaming')
+      },
+    })
+
+    // Keep a client socket open so the dispose path has something to destroy.
+    const inflight = fetch(`http://127.0.0.1:${port}/slow`).catch(() => undefined)
+    await new Promise((r) => setTimeout(r, 50))
+
+    await injector[Symbol.asyncDispose]()
+    await inflight
+  })
+
+  it('Should absorb server.close errors during dispose without crashing', async () => {
+    const injector = createInjector()
+    const pool = injector.get(HttpServerPoolToken)
+    const port = getPort()
+    const record = await pool.acquire({ port })
+
+    // Force `server.close` to invoke its callback with an error -- the pool
+    // wraps every close in `Promise.allSettled`, so the rejected branch
+    // (`if (err) { reject(err); return }`) is exercised but the injector's
+    // dispose still resolves cleanly.
+    const closeError = new Error('close boom')
+    const closeSpy = vi.fn((cb?: (err?: Error) => void) => {
+      cb?.(closeError)
+      return record.server
+    })
+    record.server.close = closeSpy
+    ;(record.server as unknown as { off: (...args: unknown[]) => void }).off = () => undefined
+
+    await expect(injector[Symbol.asyncDispose]()).resolves.toBeUndefined()
+    expect(closeSpy).toHaveBeenCalled()
+  })
+
+  it('Should drain in-flight acquire promises during dispose', async () => {
+    const injector = createInjector()
+    const port = getPort()
+    const pool = injector.get(HttpServerPoolToken)
+    const inflight = pool.acquire({ port })
+    await injector[Symbol.asyncDispose]()
+    // The in-flight promise either resolved (server opened before dispose)
+    // or rejected cleanly — both are acceptable; we just assert no process
+    // crash / unhandled rejection escaped the pool's `allSettled` guard.
+    await inflight.catch(() => undefined)
+  })
+
+  it('Should stop tracking sockets that close before dispose', async () => {
+    const injector = createInjector()
+    try {
+      const pool = injector.get(HttpServerPoolToken)
+      const port = getPort()
+      const record = await pool.acquire({ port })
+      record.apis.push(
+        makeApi(async ({ res }) => {
+          res.end('ok')
+        }),
+      )
+
+      await fetch(`http://127.0.0.1:${port}/ok`)
+      // Let the TCP socket actually flip to 'close' before we tear down.
+      await new Promise((r) => setTimeout(r, 50))
+    } finally {
+      await injector[Symbol.asyncDispose]()
+    }
+  })
+})