Header Governance Client

A lightweight HTTP helper focused on spec-compliant header handling for outgoing requests and response inspection.

Capabilities

Sends allowed headers

• Given a GET request with a custom header (for example X-Trace-Id: abc123), the request includes the header and the returned sentHeaders map exposes it regardless of casing. @test

Blocks forbidden headers by default

• When a request attempts to set a header that is normally disallowed (for example Content-Length) without opting into overrides, that header is omitted from the outgoing request and absent from the sentHeaders map. @test

Allows explicit override

• When header overrides are enabled, a header that is otherwise disallowed is sent and reported in the sentHeaders map alongside allowed headers. @test

Reads response headers safely

• For a response containing a custom header (for example X-Reply-Token: ok-42) and a cookie header, the resolved headers map exposes the custom header case-insensitively and does not surface cookie headers. @test

Implementation

@generates

API

/**
 * Sends an HTTP(S) request with spec-compliant header handling.
 *
 * @param {string} url - Target endpoint.
 * @param {object} [options]
 * @param {string} [options.method="GET"] - HTTP method to use.
 * @param {Record<string, string>} [options.headers] - Request headers to apply.
 * @param {boolean} [options.allowForbiddenHeaders=false] - Whether to permit headers that are normally disallowed.
 * @param {string|Buffer} [options.body] - Optional request payload for non-GET/HEAD methods.
 * @returns {Promise<{status: number, body: string, headers: Record<string, string>, sentHeaders: Record<string, string>}>}
 * Resolves when the request completes with response metadata and normalized header maps.
 */
export async function sendWithHeaders(url, options = {}) {}

Dependencies { .dependencies }

xmlhttprequest { .dependency }

Node-friendly implementation of the browser request API with header management utilities.

@satisfied-by