@fluojs/http 1.1.2 → 3.0.0

package/dist/byte-range-response.js

@@ -0,0 +1,347 @@
+import { readFirstNonEmptyRequestHeaderValue } from './header-helpers.js';
+import { matchesIfRange } from './dispatch/conditional-request-policy.js';
+import { registerFrameworkResponseWriter } from './dispatch/response-integration.js';
+const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+
+/**
+ * Input accepted by {@link createByteRangeResponse}.
+ *
+ * A streamed representation needs its exact full byte length so the response
+ * can evaluate `Range`, `If-Range`, and `HEAD` before consuming the stream.
+ * Pass a stream factory when `HEAD` must not construct the stream.
+ */
+
+/** Options that describe a range-capable byte representation. */
+
+/** Internal byte-representation data shared by response writers. */
+
+/** Inputs for writing a byte representation through a portable response facade. */
+
+/**
+ * Creates a response entry with RFC single-byte-range semantics.
+ *
+ * `Uint8Array` and `ArrayBuffer` values can be returned directly from a
+ * handler. Use this helper when returning a portable `ReadableStream`.
+ *
+ * @param source Byte representation or stream factory to expose with range support.
+ * @param options Optional content type and required stream size metadata.
+ * @returns A registered response entry that applies single-byte-range semantics.
+ */
+export function createByteRangeResponse(source, options = {}) {
+  const bytes = toBytes(source);
+  const size = bytes?.byteLength ?? options.size;
+  if (typeof size !== 'number' || !Number.isSafeInteger(size) || size < 0) {
+    throw new TypeError('A readable byte-range response requires a non-negative integer size.');
+  }
+  const entry = {
+    source,
+    contentType: options.contentType ?? DEFAULT_CONTENT_TYPE,
+    size
+  };
+  return registerFrameworkResponseWriter(entry, async context => {
+    await writeByteRangeResponse({
+      applySuccessResponseMetadata: context.applySuccessResponseMetadata,
+      entry,
+      request: context.request,
+      response: context.response,
+      validators: context.validators
+    });
+  });
+}
+
+/**
+ * Returns whether a normal handler result is an automatically range-capable byte value.
+ *
+ * @param value Value to test for a byte representation.
+ * @returns `true` when the value is an `ArrayBuffer` or `Uint8Array`; otherwise `false`.
+ */
+export function isByteRangeByteSource(value) {
+  return value instanceof ArrayBuffer || value instanceof Uint8Array;
+}
+
+/**
+ * Determines whether an ordinary byte result requires byte-range processing.
+ *
+ * Explicit byte-range responses retain their full-response metadata behavior;
+ * this only guards automatic range handling for plain handler values.
+ *
+ * @param request Incoming request whose `Range` and `If-Range` fields are evaluated.
+ * @param validators Selected response validators used to evaluate `If-Range`.
+ * @returns `true` when the request has a valid byte range and `If-Range` permits it.
+ */
+export function shouldApplyByteRange(request, validators) {
+  return isByteRangeRequestMethod(request.method) && parseByteRangeHeader(readFirstNonEmptyRequestHeaderValue(request, 'range')) !== undefined && matchesIfRange(request, validators);
+}
+function resolveByteRange(rangeHeader, size, ifRangeMatches) {
+  const match = parseByteRangeHeader(rangeHeader);
+  if (!match || !ifRangeMatches) {
+    return {
+      kind: 'full'
+    };
+  }
+  const [, startText, endText] = match;
+  if ((startText?.length ?? 0) === 0) {
+    const suffixLength = Number(endText);
+    if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0 || size === 0) {
+      return {
+        kind: 'unsatisfiable'
+      };
+    }
+    return {
+      end: size - 1,
+      kind: 'partial',
+      start: Math.max(size - suffixLength, 0)
+    };
+  }
+  const start = Number(startText);
+  if (!Number.isSafeInteger(start) || start < 0 || start >= size) {
+    return {
+      kind: 'unsatisfiable'
+    };
+  }
+  if ((endText?.length ?? 0) === 0) {
+    return {
+      end: size - 1,
+      kind: 'partial',
+      start
+    };
+  }
+  const requestedEnd = Number(endText);
+  if (!Number.isSafeInteger(requestedEnd) || requestedEnd < start) {
+    return {
+      kind: 'unsatisfiable'
+    };
+  }
+  return {
+    end: Math.min(requestedEnd, size - 1),
+    kind: 'partial',
+    start
+  };
+}
+function parseByteRangeHeader(rangeHeader) {
+  if (!rangeHeader) {
+    return undefined;
+  }
+  const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim());
+  return match && (match[1]?.length ?? 0) + (match[2]?.length ?? 0) > 0 ? match : undefined;
+}
+
+/**
+ * Writes one byte representation while preserving range and cancellation semantics.
+ *
+ * @param options Request, response, validators, and representation metadata.
+ * @returns A promise that settles after the representation completes or fails.
+ */
+export async function writeByteRangeResponse(options) {
+  const {
+    entry,
+    request,
+    response,
+    validators
+  } = options;
+  if (response.committed) {
+    return;
+  }
+  const acceptsByteRange = isByteRangeRequestMethod(request.method);
+  const range = resolveByteRange(acceptsByteRange ? readFirstNonEmptyRequestHeaderValue(request, 'range') : undefined, entry.size, acceptsByteRange && matchesIfRange(request, validators));
+  const isHead = request.method.toUpperCase() === 'HEAD';
+  const bytes = toBytes(entry.source);
+  if (range.kind === 'unsatisfiable') {
+    options.applySuccessResponseMetadata();
+    if (acceptsByteRange) {
+      response.setHeader('Accept-Ranges', 'bytes');
+    }
+    if (!hasHeader(response, 'content-type')) {
+      response.setHeader('Content-Type', entry.contentType);
+    }
+    response.setStatus(416);
+    response.setHeader('Content-Length', '0');
+    response.setHeader('Content-Range', `bytes */${entry.size}`);
+    await response.send(undefined, sendOptions(options.compression));
+    return;
+  }
+  let reader;
+  let stream;
+  if (!isHead && !bytes) {
+    const streamSource = openByteRangeStream(entry.source);
+    if (!streamSource) {
+      throw new TypeError('A byte-range response must contain bytes or a portable readable stream.');
+    }
+    reader = streamSource.getReader();
+    try {
+      stream = response.stream;
+    } catch (error) {
+      await cancelAndReleaseReader(reader);
+      throw error;
+    }
+    if (!stream) {
+      await cancelAndReleaseReader(reader);
+      throw new TypeError('The active HTTP adapter cannot write a portable byte stream.');
+    }
+  }
+  options.applySuccessResponseMetadata();
+  if (acceptsByteRange) {
+    response.setHeader('Accept-Ranges', 'bytes');
+  }
+  if (!hasHeader(response, 'content-type')) {
+    response.setHeader('Content-Type', entry.contentType);
+  }
+  if (range.kind === 'partial') {
+    response.setStatus(206);
+    response.setHeader('Content-Length', String(range.end - range.start + 1));
+    response.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${entry.size}`);
+  } else {
+    response.setHeader('Content-Length', String(entry.size));
+  }
+  if (isHead) {
+    await response.send(undefined, sendOptions(options.compression));
+    return;
+  }
+  if (bytes) {
+    await response.send(range.kind === 'partial' ? bytes.slice(range.start, range.end + 1) : bytes, sendOptions(options.compression));
+    return;
+  }
+  if (!reader || !stream) {
+    throw new TypeError('A byte-range response must contain an opened portable readable stream.');
+  }
+  response.committed = true;
+  await writeReadableStream(reader, range.kind === 'partial' ? range.start : 0, range.kind === 'partial' ? range.end : entry.size - 1, request, stream);
+}
+function sendOptions(compression) {
+  return compression === false ? {
+    compression: false
+  } : undefined;
+}
+function hasHeader(response, name) {
+  const lowerName = name.toLowerCase();
+  return Object.keys(response.headers).some(header => header.toLowerCase() === lowerName);
+}
+function toBytes(source) {
+  if (source instanceof Uint8Array) {
+    return source;
+  }
+  if (source instanceof ArrayBuffer) {
+    return new Uint8Array(source);
+  }
+  return undefined;
+}
+function isByteRangeRequestMethod(method) {
+  const normalizedMethod = method.toUpperCase();
+  return normalizedMethod === 'GET' || normalizedMethod === 'HEAD';
+}
+function isReadableStream(source) {
+  return typeof source === 'object' && source !== null && 'getReader' in source && typeof source.getReader === 'function';
+}
+function openByteRangeStream(source) {
+  const stream = typeof source === 'function' ? source() : source;
+  return isReadableStream(stream) ? stream : undefined;
+}
+async function cancelAndReleaseReader(reader) {
+  void reader.cancel().catch(() => undefined);
+  reader.releaseLock();
+}
+async function writeReadableStream(reader, start, end, request, stream) {
+  let skip = start;
+  let remaining = end - start + 1;
+  let stopped = false;
+  let hasTransportFailure = false;
+  let transportFailure;
+  let resolveStop = () => {};
+  let resolveTransportFailure = () => {};
+  let cancellation;
+  const stopPromise = new Promise(resolve => {
+    resolveStop = resolve;
+  });
+  const transportFailurePromise = new Promise(resolve => {
+    resolveTransportFailure = resolve;
+  });
+  const cancel = () => {
+    cancellation ??= reader.cancel();
+    void cancellation.catch(() => undefined);
+    return cancellation;
+  };
+  const stop = () => {
+    if (!stopped) {
+      stopped = true;
+      resolveStop();
+    }
+    void cancel();
+  };
+  const fail = error => {
+    if (!hasTransportFailure) {
+      hasTransportFailure = true;
+      transportFailure = error;
+      resolveTransportFailure();
+    }
+    stop();
+  };
+  const removeCloseListener = stream.onClose?.(stop);
+  const removeErrorListener = stream.onError?.(fail);
+  stream.disableCompression?.();
+  request.signal?.addEventListener('abort', stop, {
+    once: true
+  });
+  if (isByteRangeRequestAborted(request)) {
+    stop();
+  }
+  try {
+    while (remaining > 0 && !stopped && !stream.closed) {
+      if (isByteRangeRequestAborted(request)) {
+        stop();
+        break;
+      }
+      const result = await raceWithStop(reader.read(), stopPromise, transportFailurePromise);
+      if (!result || stopped || hasTransportFailure || isByteRangeRequestAborted(request)) {
+        stop();
+        break;
+      }
+      const {
+        done,
+        value
+      } = result;
+      if (done) {
+        break;
+      }
+      if (skip >= value.byteLength) {
+        skip -= value.byteLength;
+        continue;
+      }
+      const chunkStart = skip;
+      skip = 0;
+      const chunkEnd = Math.min(value.byteLength, chunkStart + remaining);
+      const chunk = value.subarray(chunkStart, chunkEnd);
+      remaining -= chunk.byteLength;
+      if (chunk.byteLength > 0 && stream.write(chunk) === false) {
+        const drain = stream.waitForDrain?.();
+        if (drain) {
+          await raceWithStop(drain, stopPromise, transportFailurePromise);
+        }
+        if (isByteRangeRequestAborted(request)) {
+          stop();
+        }
+      }
+    }
+  } finally {
+    request.signal?.removeEventListener('abort', stop);
+    removeCloseListener?.();
+    removeErrorListener?.();
+    void cancel();
+    reader.releaseLock();
+    if (!stream.closed && !hasTransportFailure) {
+      stream.close();
+    }
+  }
+  if (hasTransportFailure) {
+    throw transportFailure;
+  }
+}
+function isByteRangeRequestAborted(request) {
+  return request.signal?.aborted === true || request.isAborted?.() === true;
+}
+async function raceWithStop(operation, stop, transportFailure) {
+  const terminalSignals = [operation, stop.then(() => undefined)];
+  if (transportFailure) {
+    terminalSignals.push(transportFailure.then(() => undefined));
+  }
+  return await Promise.race([...terminalSignals]);
+}

package/dist/client-identity.d.ts

@@ -1,15 +1,19 @@
 import type { FrameworkRequest } from './types.js';
+import { type TrustProxyPolicy } from './connection.js';
 interface ClientIdentityResolutionOptions {
+    trustProxy?: TrustProxyPolicy;
     trustProxyHeaders?: boolean;
 }
 /**
  * Resolve one stable client identity from the normalized request contract.
  *
  * By default, resolution uses only the raw socket's `remoteAddress`. When
- * `trustProxyHeaders` is enabled, resolution order becomes `Forwarded`,
- * `X-Forwarded-For`, `X-Real-IP`, then the raw socket fallback. If none are
- * available, callers must provide an explicit resolver because falling back to
- * a shared `unknown` bucket is not safe in proxied or serverless environments.
+ * `trustProxyHeaders` enables the broad legacy compatibility path: it accepts
+ * the complete forwarding chain from `Forwarded`, `X-Forwarded-For`, or
+ * `X-Real-IP` without a deployment-specific peer boundary. Prefer
+ * `trustProxy` for new deployments. If no trusted identity is available,
+ * callers must provide an explicit resolver because falling back to a shared
+ * `unknown` bucket is not safe in proxied or serverless environments.
  *
  * @param request Adapter-normalized request whose headers/raw transport state should be inspected.
  * @param options Client-identity trust settings for proxy-header handling.

package/dist/client-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-identity.d.ts","sourceRoot":"","sources":["../src/client-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD,UAAU,+BAA+B;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA8HD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAeR"}
+{"version":3,"file":"client-identity.d.ts","sourceRoot":"","sources":["../src/client-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,KAAK,gBAAgB,EAAyB,MAAM,iBAAiB,CAAC;AAE/E,UAAU,+BAA+B;IACvC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,+BAAoC,GAC5C,MAAM,CAaR"}

package/dist/client-identity.js

@@ -1,97 +1,14 @@
-const FORWARDED_HEADER = 'forwarded';
-const X_FORWARDED_FOR_HEADER = 'x-forwarded-for';
-const X_REAL_IP_HEADER = 'x-real-ip';
-function readHeader(headers, name) {
-  const direct = headers[name];
-  if (typeof direct === 'string') {
-    return direct;
-  }
-  if (Array.isArray(direct)) {
-    return direct.find(value => value.trim().length > 0);
-  }
-  const match = Object.entries(headers).find(([key]) => key.toLowerCase() === name);
-  const value = match?.[1];
-  if (typeof value === 'string') {
-    return value;
-  }
-  return value?.find(entry => entry.trim().length > 0);
-}
-function normalizeClientIdentity(value) {
-  if (!value) {
-    return undefined;
-  }
-  let normalized = value.trim();
-  if (!normalized || normalized.toLowerCase() === 'unknown') {
-    return undefined;
-  }
-  if (normalized.startsWith('"') && normalized.endsWith('"')) {
-    normalized = normalized.slice(1, -1).trim();
-  }
-  const bracketedHostPort = normalized.match(/^\[(.+)]:(\d+)$/);
-  if (bracketedHostPort) {
-    return bracketedHostPort[1]?.trim() || undefined;
-  }
-  if (normalized.startsWith('[') && normalized.endsWith(']')) {
-    normalized = normalized.slice(1, -1).trim();
-  }
-  const ipv4HostPort = normalized.match(/^((?:\d{1,3}\.){3}\d{1,3}):(\d+)$/);
-  if (ipv4HostPort) {
-    return ipv4HostPort[1]?.trim() || undefined;
-  }
-  return normalized || undefined;
-}
-function resolveForwardedClientIdentity(headers) {
-  const forwarded = readHeader(headers, FORWARDED_HEADER);
-  if (!forwarded) {
-    return undefined;
-  }
-  for (const field of forwarded.split(',')) {
-    for (const part of field.split(';')) {
-      const separator = part.indexOf('=');
-      if (separator === -1) {
-        continue;
-      }
-      const key = part.slice(0, separator).trim().toLowerCase();
-      if (key !== 'for') {
-        continue;
-      }
-      const normalized = normalizeClientIdentity(part.slice(separator + 1));
-      if (normalized) {
-        return normalized;
-      }
-    }
-  }
-  return undefined;
-}
-function resolveCommaSeparatedClientIdentity(headers, headerName) {
-  const headerValue = readHeader(headers, headerName);
-  if (!headerValue) {
-    return undefined;
-  }
-  for (const value of headerValue.split(',')) {
-    const normalized = normalizeClientIdentity(value);
-    if (normalized) {
-      return normalized;
-    }
-  }
-  return undefined;
-}
-function resolveSocketClientIdentity(raw) {
-  if (!raw || typeof raw !== 'object') {
-    return undefined;
-  }
-  const socket = raw.socket;
-  return typeof socket?.remoteAddress === 'string' ? normalizeClientIdentity(socket.remoteAddress) : undefined;
-}
-
+import { resolveHttpConnection } from './connection.js';
 /**
  * Resolve one stable client identity from the normalized request contract.
  *
  * By default, resolution uses only the raw socket's `remoteAddress`. When
- * `trustProxyHeaders` is enabled, resolution order becomes `Forwarded`,
- * `X-Forwarded-For`, `X-Real-IP`, then the raw socket fallback. If none are
- * available, callers must provide an explicit resolver because falling back to
- * a shared `unknown` bucket is not safe in proxied or serverless environments.
+ * `trustProxyHeaders` enables the broad legacy compatibility path: it accepts
+ * the complete forwarding chain from `Forwarded`, `X-Forwarded-For`, or
+ * `X-Real-IP` without a deployment-specific peer boundary. Prefer
+ * `trustProxy` for new deployments. If no trusted identity is available,
+ * callers must provide an explicit resolver because falling back to a shared
+ * `unknown` bucket is not safe in proxied or serverless environments.
  *
  * @param request Adapter-normalized request whose headers/raw transport state should be inspected.
  * @param options Client-identity trust settings for proxy-header handling.
@@ -99,10 +16,12 @@ function resolveSocketClientIdentity(raw) {
  * @throws Error When the request exposes no trusted proxy header or socket identity.
  */
 export function resolveClientIdentity(request, options = {}) {
-  const proxyClientIdentity = options.trustProxyHeaders ? resolveForwardedClientIdentity(request.headers) ?? resolveCommaSeparatedClientIdentity(request.headers, X_FORWARDED_FOR_HEADER) ?? normalizeClientIdentity(readHeader(request.headers, X_REAL_IP_HEADER)) : undefined;
-  const clientIdentity = proxyClientIdentity ?? resolveSocketClientIdentity(request.raw);
+  const clientIdentity = resolveHttpConnection(request, {
+    allowForwardedWithoutPeer: options.trustProxyHeaders === true,
+    trustProxy: options.trustProxy ?? (options.trustProxyHeaders ? Number.MAX_SAFE_INTEGER : false)
+  }).clientAddress;
   if (clientIdentity) {
     return clientIdentity;
   }
-  throw new Error('Unable to resolve client identity from the trusted request transport. Enable trustProxyHeaders only behind a trusted proxy, or provide an explicit keyResolver/keyGenerator for this environment.');
+  throw new Error('Unable to resolve client identity from the trusted request transport. Configure resolveHttpConnection(...) with an explicit trust policy, or provide an explicit keyResolver/keyGenerator for this environment.');
 }

package/dist/compiled-route-identity.d.ts

@@ -0,0 +1,17 @@
+import type { HandlerDescriptor } from './types.js';
+/**
+ * Attach the deterministic compiler identity to a handler descriptor.
+ *
+ * @param descriptor Handler descriptor produced by route compilation.
+ * @param identity Stable identity assigned to the compiled route.
+ * @returns The descriptor with its non-writable compiler identity attached.
+ */
+export declare function attachCompiledRouteIdentity<Descriptor extends HandlerDescriptor>(descriptor: Descriptor, identity: string): Descriptor;
+/**
+ * Read the deterministic identity assigned by the HTTP route compiler.
+ *
+ * @param descriptor Compiled handler descriptor produced by `createHandlerMapping(...)`.
+ * @returns The compiler identity, or `undefined` for a manually authored descriptor.
+ */
+export declare function getCompiledRouteIdentity(descriptor: HandlerDescriptor): string | undefined;
+//# sourceMappingURL=compiled-route-identity.d.ts.map

package/dist/compiled-route-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiled-route-identity.d.ts","sourceRoot":"","sources":["../src/compiled-route-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,SAAS,iBAAiB,EAC9E,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,GACf,UAAU,CASZ;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAI1F"}

package/dist/compiled-route-identity.js

@@ -0,0 +1,29 @@
+const COMPILED_ROUTE_IDENTITY_SYMBOL = Symbol.for('fluo.http.compiledRouteIdentity');
+
+/**
+ * Attach the deterministic compiler identity to a handler descriptor.
+ *
+ * @param descriptor Handler descriptor produced by route compilation.
+ * @param identity Stable identity assigned to the compiled route.
+ * @returns The descriptor with its non-writable compiler identity attached.
+ */
+export function attachCompiledRouteIdentity(descriptor, identity) {
+  Object.defineProperty(descriptor, COMPILED_ROUTE_IDENTITY_SYMBOL, {
+    configurable: false,
+    enumerable: true,
+    value: identity,
+    writable: false
+  });
+  return descriptor;
+}
+
+/**
+ * Read the deterministic identity assigned by the HTTP route compiler.
+ *
+ * @param descriptor Compiled handler descriptor produced by `createHandlerMapping(...)`.
+ * @returns The compiler identity, or `undefined` for a manually authored descriptor.
+ */
+export function getCompiledRouteIdentity(descriptor) {
+  const identity = Reflect.get(descriptor, COMPILED_ROUTE_IDENTITY_SYMBOL);
+  return typeof identity === 'string' ? identity : undefined;
+}

package/dist/connection.d.ts

@@ -0,0 +1,67 @@
+import type { FrameworkRequest } from './types.js';
+/**
+ * Function that decides whether one proxy hop is trusted.
+ *
+ * @param address Proxy address being considered, starting with the direct transport peer.
+ * @param index Zero-based distance from the direct transport peer.
+ * @returns Whether the proxy hop may supply forwarding metadata.
+ */
+export type TrustProxyPredicate = (address: string, index: number) => boolean;
+/**
+ * Explicit policy that permits forwarding metadata from known proxy hops.
+ *
+ * `false` disables proxy trust, a number trusts that many nearest hops, an
+ * address/CIDR list matches nearest hops, and a predicate receives each hop
+ * from nearest to furthest.
+ */
+export type TrustProxyPolicy = false | number | readonly string[] | TrustProxyPredicate;
+/**
+ * Options used to derive a trusted connection snapshot.
+ */
+export interface ResolveHttpConnectionOptions {
+    /**
+     * Proxy trust boundary. The default is `false`, so forwarded headers never
+     * override the direct transport identity without an explicit policy.
+     */
+    trustProxy?: TrustProxyPolicy;
+    /**
+     * Retains the legacy header-only migration path for integrations that do not
+     * expose a transport peer. New integrations must leave this disabled.
+     */
+    allowForwardedWithoutPeer?: boolean;
+}
+/**
+ * Immutable, runtime-neutral view of the connection identity selected for a request.
+ */
+export interface HttpConnection {
+    /** First untrusted address in the client-to-server chain, when available. */
+    readonly clientAddress: string | undefined;
+    /** Public host selected from trusted forwarding metadata or the request host header. */
+    readonly host: string | undefined;
+    /** Host without an optional port selected from `host`. */
+    readonly hostname: string | undefined;
+    /** Numeric port selected from `host`, when present and valid. */
+    readonly port: number | undefined;
+    /** `http` or `https` selected from transport or trusted forwarding metadata. */
+    readonly protocol: 'http' | 'https';
+    /** Trusted proxy addresses between `clientAddress` and `remoteAddress`. */
+    readonly proxyChain: readonly string[];
+    /** Direct adapter transport peer address, when available. */
+    readonly remoteAddress: string | undefined;
+    /** Whether `protocol` is `https`. */
+    readonly secure: boolean;
+}
+/**
+ * Resolve an immutable connection snapshot using a direct transport identity
+ * and only proxy metadata allowed by the explicit trust policy.
+ *
+ * Malformed forwarding input is ignored as a whole, preserving the direct
+ * transport identity. Adapters without a socket address produce an undefined
+ * identity rather than trusting a forwarding header by default.
+ *
+ * @param request Adapter-normalized request whose headers and raw transport are inspected.
+ * @param options Explicit proxy trust policy for the current deployment.
+ * @returns Immutable connection identity, protocol, host, and trusted proxy chain.
+ */
+export declare function resolveHttpConnection(request: FrameworkRequest, options?: ResolveHttpConnectionOptions): HttpConnection;
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4BnD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,mBAAmB,CAAC;AAExF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AA8gBD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,4BAAiC,GACzC,cAAc,CAmDhB"}