@irvinebroque/http-rfc-utils 0.1.0

package/dist/etag.js

@@ -0,0 +1,182 @@
+/**
+ * ETag utilities per RFC 9110.
+ * RFC 9110 §8.8.3, §8.8.3.2.
+ * @see https://httpwg.org/specs/rfc9110.html#field.etag
+ */
+const MAX_ETAG_CHAR = 0xFF;
+// RFC 9110 §8.8.3: etagc character set validation.
+function isValidETagValue(value) {
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (code === undefined) {
+            return false;
+        }
+        if (code > MAX_ETAG_CHAR) {
+            return false;
+        }
+        if (code === 0x21) {
+            continue;
+        }
+        if (code >= 0x23 && code <= 0x7E) {
+            continue;
+        }
+        if (code >= 0x80 && code <= 0xFF) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+/**
+ * Simple djb2 hash algorithm for sync ETag generation
+ */
+function djb2Hash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+    }
+    // Convert to unsigned 32-bit integer and then to hex
+    return (hash >>> 0).toString(16);
+}
+/**
+ * Convert data to a string representation for hashing
+ */
+function dataToString(data) {
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (data instanceof ArrayBuffer) {
+        return Array.from(new Uint8Array(data))
+            .map(b => String.fromCharCode(b))
+            .join('');
+    }
+    if (ArrayBuffer.isView(data)) {
+        return Array.from(new Uint8Array(data.buffer, data.byteOffset, data.byteLength))
+            .map(b => String.fromCharCode(b))
+            .join('');
+    }
+    return JSON.stringify(data) ?? String(data);
+}
+function toBufferSource(data) {
+    if (data instanceof ArrayBuffer) {
+        return data;
+    }
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+/**
+ * Generate a simple ETag from data (sync, using string hash)
+ * Uses a simple hash algorithm suitable for most use cases.
+ * Returns format: "hash" (strong) or W/"hash" (if weak option specified)
+ */
+// RFC 9110 §8.8.3: Entity-tag field-value formatting.
+export function generateETag(data, options) {
+    const str = dataToString(data);
+    const hash = djb2Hash(str);
+    const weak = options?.weak ?? false;
+    return weak ? `W/"${hash}"` : `"${hash}"`;
+}
+/**
+ * Generate an ETag using Web Crypto API (async, more secure)
+ * Uses SHA-256 by default.
+ */
+// RFC 9110 §8.8.3: Entity-tag field-value formatting.
+export async function generateETagAsync(data, options) {
+    const algorithm = options?.algorithm ?? 'SHA-256';
+    const weak = options?.weak ?? false;
+    let dataBuffer;
+    if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+        dataBuffer = toBufferSource(data);
+    }
+    else {
+        const str = dataToString(data);
+        const encoder = new TextEncoder();
+        dataBuffer = encoder.encode(str);
+    }
+    const hashBuffer = await globalThis.crypto.subtle.digest(algorithm, dataBuffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    // Use first 16 bytes (32 hex chars) for reasonable length
+    const hash = hashArray.slice(0, 16).map(b => b.toString(16).padStart(2, '0')).join('');
+    return weak ? `W/"${hash}"` : `"${hash}"`;
+}
+/**
+ * Parse an ETag string into its components
+ * Handles: "abc", W/"abc", ""
+ * Returns null for invalid format
+ */
+// RFC 9110 §8.8.3: Entity-tag field parsing.
+export function parseETag(etag) {
+    if (!etag) {
+        return null;
+    }
+    const trimmed = etag.trim();
+    // Check for weak prefix
+    let weak = false;
+    let rest = trimmed;
+    if (trimmed.startsWith('W/')) {
+        weak = true;
+        rest = trimmed.slice(2);
+    }
+    // Must be quoted
+    if (!rest.startsWith('"') || !rest.endsWith('"')) {
+        return null;
+    }
+    // Extract value (everything between the quotes)
+    const value = rest.slice(1, -1);
+    // Value cannot contain unescaped quotes
+    // Per RFC 9110, etagc = %x21 / %x23-7E / obs-text (no DQUOTE = %x22)
+    if (value.includes('"')) {
+        return null;
+    }
+    if (!isValidETagValue(value)) {
+        return null;
+    }
+    return { weak, value };
+}
+/**
+ * Format an ETag object back to string
+ */
+// RFC 9110 §8.8.3: Entity-tag field formatting.
+export function formatETag(etag) {
+    return etag.weak ? `W/"${etag.value}"` : `"${etag.value}"`;
+}
+/**
+ * Compare two ETags per RFC 9110 §8.8.3.
+ *
+ * Strong comparison: both must be strong AND values match
+ * Weak comparison: values match (regardless of weak/strong)
+ *
+ * RFC 9110 §8.8.3.2 comparison table:
+ * | ETag 1  | ETag 2  | Strong | Weak  |
+ * |---------|---------|--------|-------|
+ * | W/"1"   | W/"1"   | false  | true  |
+ * | W/"1"   | "1"     | false  | true  |
+ * | "1"     | "1"     | true   | true  |
+ * | "1"     | W/"1"   | false  | true  |
+ * | W/"1"   | W/"2"   | false  | false |
+ * | "1"     | "2"     | false  | false |
+ */
+export function compareETags(a, b, strong = false) {
+    // Values must always match
+    if (a.value !== b.value) {
+        return false;
+    }
+    // For weak comparison, value match is sufficient
+    if (!strong) {
+        return true;
+    }
+    // For strong comparison, both must be strong (not weak)
+    return !a.weak && !b.weak;
+}
+/**
+ * Convenience function to compare ETag strings directly
+ */
+// RFC 9110 §8.8.3.2: Strong/weak comparison via parsed entity-tags.
+export function compareETagStrings(a, b, strong = false) {
+    const parsedA = parseETag(a);
+    const parsedB = parseETag(b);
+    if (!parsedA || !parsedB) {
+        return false;
+    }
+    return compareETags(parsedA, parsedB, strong);
+}
+//# sourceMappingURL=etag.js.map

package/dist/etag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"etag.js","sourceRoot":"","sources":["../src/etag.ts"],"names":[],"mappings":"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"}

package/dist/ext-value.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RFC 8187 extended parameter value encoding/decoding.
+ * RFC 8187 §3.2, §3.2.1.
+ * @see https://www.rfc-editor.org/rfc/rfc8187.html#section-3.2
+ */
+import type { ExtValue, ExtValueOptions } from './types.js';
+/**
+ * Check if a character is a valid attr-char per RFC 8187 §3.2.1.
+ *
+ * @param char - Single character to check
+ * @returns True if char is attr-char
+ */
+export declare function isAttrChar(char: string): boolean;
+/**
+ * Check if a string needs extended encoding (contains non-ASCII or non-attr-char).
+ *
+ * @param value - String to check
+ * @returns True if extended encoding is needed
+ */
+export declare function needsExtendedEncoding(value: string): boolean;
+/**
+ * Decode an RFC 8187 ext-value (charset'language'value-chars).
+ *
+ * Returns null for malformed input to allow fallback to non-extended value.
+ *
+ * @param encoded - The ext-value string (e.g., "UTF-8'en'%C2%A3%20rates")
+ * @returns Decoded ExtValue or null if malformed
+ */
+export declare function decodeExtValue(encoded: string): ExtValue | null;
+/**
+ * Encode a string as RFC 8187 ext-value (UTF-8'language'value-chars).
+ *
+ * Per RFC 8187 §3.2.1, producers MUST use UTF-8 encoding.
+ *
+ * @param value - String to encode
+ * @param options - Encoding options (language tag)
+ * @returns Encoded ext-value string
+ */
+export declare function encodeExtValue(value: string, options?: ExtValueOptions): string;
+//# sourceMappingURL=ext-value.d.ts.map

package/dist/ext-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-value.d.ts","sourceRoot":"","sources":["../src/ext-value.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAU5D;;;;;GAKG;AAEH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;GAKG;AAEH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAa5D;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA0C/D;AAED;;;;;;;;GAQG;AAEH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAmBnF"}

package/dist/ext-value.js

@@ -0,0 +1,119 @@
+/**
+ * RFC 8187 extended parameter value encoding/decoding.
+ * RFC 8187 §3.2, §3.2.1.
+ * @see https://www.rfc-editor.org/rfc/rfc8187.html#section-3.2
+ */
+/**
+ * RFC 8187 §3.2.1: attr-char characters that don't need percent-encoding.
+ * attr-char = ALPHA / DIGIT / "!" / "#" / "$" / "&" / "+" / "-" / "."
+ *           / "^" / "_" / "`" / "|" / "~"
+ * (token except "*" / "'" / "%")
+ */
+const ATTR_CHAR = /^[A-Za-z0-9!#$&+\-.^_`|~]$/;
+/**
+ * Check if a character is a valid attr-char per RFC 8187 §3.2.1.
+ *
+ * @param char - Single character to check
+ * @returns True if char is attr-char
+ */
+// RFC 8187 §3.2.1: attr-char validation.
+export function isAttrChar(char) {
+    return char.length === 1 && ATTR_CHAR.test(char);
+}
+/**
+ * Check if a string needs extended encoding (contains non-ASCII or non-attr-char).
+ *
+ * @param value - String to check
+ * @returns True if extended encoding is needed
+ */
+// RFC 8187 §3.2: Determine if ext-value encoding is required.
+export function needsExtendedEncoding(value) {
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        // Non-ASCII needs encoding
+        if (code > 0x7f) {
+            return true;
+        }
+        // Non-attr-char ASCII needs encoding
+        if (!ATTR_CHAR.test(char)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decode an RFC 8187 ext-value (charset'language'value-chars).
+ *
+ * Returns null for malformed input to allow fallback to non-extended value.
+ *
+ * @param encoded - The ext-value string (e.g., "UTF-8'en'%C2%A3%20rates")
+ * @returns Decoded ExtValue or null if malformed
+ */
+// RFC 8187 §3.2.1: Extended parameter value decoding.
+export function decodeExtValue(encoded) {
+    // RFC 8187 §3.2.1: ext-value cannot use quoted-string notation.
+    // Double-quotes are not valid in charset, language, or value-chars.
+    if (encoded.includes('"')) {
+        return null;
+    }
+    // Split on single quotes - format is charset'language'value-chars
+    const firstQuote = encoded.indexOf("'");
+    if (firstQuote === -1) {
+        return null;
+    }
+    const secondQuote = encoded.indexOf("'", firstQuote + 1);
+    if (secondQuote === -1) {
+        return null;
+    }
+    const charset = encoded.slice(0, firstQuote);
+    const language = encoded.slice(firstQuote + 1, secondQuote);
+    const valueChars = encoded.slice(secondQuote + 1);
+    // RFC 8187 §3.2: charset MUST NOT be omitted
+    if (!charset) {
+        return null;
+    }
+    // Decode percent-encoded value
+    let decoded;
+    try {
+        decoded = decodeURIComponent(valueChars);
+    }
+    catch {
+        // RFC 8187 §3.2.1: Handle encoding errors robustly
+        return null;
+    }
+    // RFC 8187 §3.2.1: charset is case-insensitive, normalize to lowercase
+    return {
+        charset: charset.toLowerCase(),
+        language: language || undefined,
+        value: decoded,
+    };
+}
+/**
+ * Encode a string as RFC 8187 ext-value (UTF-8'language'value-chars).
+ *
+ * Per RFC 8187 §3.2.1, producers MUST use UTF-8 encoding.
+ *
+ * @param value - String to encode
+ * @param options - Encoding options (language tag)
+ * @returns Encoded ext-value string
+ */
+// RFC 8187 §3.2: Extended parameter encoding.
+export function encodeExtValue(value, options = {}) {
+    const language = options.language ?? '';
+    // Build percent-encoded value, preserving attr-char
+    let encoded = '';
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(value);
+    for (const byte of bytes) {
+        const char = String.fromCharCode(byte);
+        if (ATTR_CHAR.test(char)) {
+            encoded += char;
+        }
+        else {
+            // Percent-encode with uppercase hex per RFC 3986 §2.1
+            encoded += '%' + byte.toString(16).toUpperCase().padStart(2, '0');
+        }
+    }
+    return `UTF-8'${language}'${encoded}`;
+}
+//# sourceMappingURL=ext-value.js.map

package/dist/ext-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-value.js","sourceRoot":"","sources":["../src/ext-value.ts"],"names":[],"mappings":"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"}

package/dist/forwarded.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Forwarded header utilities per RFC 7239.
+ * RFC 7239 §4.
+ */
+import type { ForwardedElement } from './types.js';
+/**
+ * Parse Forwarded header into elements.
+ */
+export declare function parseForwarded(header: string): ForwardedElement[];
+/**
+ * Format Forwarded header value from elements.
+ */
+export declare function formatForwarded(elements: ForwardedElement[]): string;
+//# sourceMappingURL=forwarded.d.ts.map

package/dist/forwarded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarded.d.ts","sourceRoot":"","sources":["../src/forwarded.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD;;GAEG;AAEH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,CA0DjE;AAED;;GAEG;AAEH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAyBpE"}

package/dist/forwarded.js

@@ -0,0 +1,93 @@
+/**
+ * Forwarded header utilities per RFC 7239.
+ * RFC 7239 §4.
+ */
+import { isEmptyHeader, splitQuotedValue, unquote, quoteIfNeeded } from './header-utils.js';
+/**
+ * Parse Forwarded header into elements.
+ */
+// RFC 7239 §4: Forwarded field-value parsing.
+export function parseForwarded(header) {
+    if (isEmptyHeader(header)) {
+        return [];
+    }
+    const elements = [];
+    const parts = splitQuotedValue(header, ',');
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const pairs = splitQuotedValue(trimmed, ';');
+        const element = {};
+        const extensions = {};
+        for (const pair of pairs) {
+            const segment = pair.trim();
+            if (!segment)
+                continue;
+            const eqIndex = segment.indexOf('=');
+            if (eqIndex === -1)
+                continue;
+            const key = segment.slice(0, eqIndex).trim().toLowerCase();
+            const rawValue = segment.slice(eqIndex + 1).trim();
+            const value = unquote(rawValue);
+            if (key === 'for') {
+                if (element.for === undefined) {
+                    element.for = value;
+                }
+            }
+            else if (key === 'by') {
+                if (element.by === undefined) {
+                    element.by = value;
+                }
+            }
+            else if (key === 'host') {
+                if (element.host === undefined) {
+                    element.host = value;
+                }
+            }
+            else if (key === 'proto') {
+                if (element.proto === undefined) {
+                    element.proto = value;
+                }
+            }
+            else if (key) {
+                if (!(key in extensions)) {
+                    extensions[key] = value;
+                }
+            }
+        }
+        if (Object.keys(extensions).length > 0) {
+            element.extensions = extensions;
+        }
+        elements.push(element);
+    }
+    return elements;
+}
+/**
+ * Format Forwarded header value from elements.
+ */
+// RFC 7239 §4: Forwarded field-value formatting.
+export function formatForwarded(elements) {
+    return elements.map(element => {
+        const parts = [];
+        if (element.for !== undefined) {
+            parts.push(`for=${quoteIfNeeded(element.for)}`);
+        }
+        if (element.by !== undefined) {
+            parts.push(`by=${quoteIfNeeded(element.by)}`);
+        }
+        if (element.host !== undefined) {
+            parts.push(`host=${quoteIfNeeded(element.host)}`);
+        }
+        if (element.proto !== undefined) {
+            parts.push(`proto=${quoteIfNeeded(element.proto)}`);
+        }
+        if (element.extensions) {
+            for (const [key, value] of Object.entries(element.extensions)) {
+                parts.push(`${key}=${quoteIfNeeded(value)}`);
+            }
+        }
+        return parts.join(';');
+    }).join(', ');
+}
+//# sourceMappingURL=forwarded.js.map

package/dist/forwarded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarded.js","sourceRoot":"","sources":["../src/forwarded.ts"],"names":[],"mappings":"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"}

package/dist/header-utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared HTTP header parsing utilities.
+ * Common patterns per RFC 9110 §5.6.2 (tokens), §5.6.4 (quoted-strings).
+ * @internal - not exported from the public API
+ * @see https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6
+ */
+/**
+ * RFC 9110 §5.6.2: token characters.
+ * token = 1*tchar
+ * tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
+ *         "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+ */
+export declare const TOKEN_CHARS: RegExp;
+/**
+ * RFC 9110 §12.4.2: q-value grammar.
+ * qvalue = ( "0" [ "." 0*3DIGIT ] ) / ( "1" [ "." 0*3("0") ] )
+ */
+export declare const QVALUE_REGEX: RegExp;
+/**
+ * Check if a header value is empty or whitespace-only.
+ *
+ * @param header - The header value to check
+ * @returns True if the header is null, undefined, empty, or whitespace-only
+ */
+export declare function isEmptyHeader(header: string | null | undefined): boolean;
+/**
+ * Split a header value by delimiter, respecting quoted strings.
+ * Handles escape sequences within quoted strings per RFC 9110 §5.6.4.
+ *
+ * RFC 9110 §5.6.4: quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
+ *
+ * @param value - The header value to split
+ * @param delimiter - The delimiter character (typically ',' or ';')
+ * @returns Array of split parts (not trimmed)
+ */
+export declare function splitQuotedValue(value: string, delimiter: string): string[];
+/**
+ * Simple comma-split for headers that don't contain quoted values.
+ * Use this for simple list headers like Accept-Language, Accept-Encoding.
+ *
+ * @param value - The header value to split
+ * @returns Array of trimmed, non-empty parts
+ */
+export declare function splitListValue(value: string): string[];
+/**
+ * Unquote a quoted-string value, handling escape sequences.
+ * If the value is not quoted, returns it trimmed.
+ *
+ * RFC 9110 §5.6.4: quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
+ *
+ * @param value - The potentially quoted value
+ * @returns Unquoted value with escapes resolved
+ */
+export declare function unquote(value: string): string;
+/**
+ * Quote a value if it contains non-token characters.
+ * Escapes backslashes and double quotes within the value.
+ *
+ * @param value - The value to potentially quote
+ * @returns Token value as-is, or quoted-string if needed
+ */
+export declare function quoteIfNeeded(value: string): string;
+/**
+ * Parse a q-value (quality value) from a string.
+ * Returns null if the value is invalid per RFC 9110 §12.4.2.
+ *
+ * @param value - The q-value string (e.g., "0.9", "1", "0.123")
+ * @returns Parsed number between 0 and 1, or null if invalid
+ */
+export declare function parseQValue(value: string): number | null;
+//# sourceMappingURL=header-utils.d.ts.map

package/dist/header-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-utils.d.ts","sourceRoot":"","sources":["../src/header-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAmC,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAyC,CAAC;AAEnE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAExE;AAED;;;;;;;;;GASG;AAEH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAoC3E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtD;AAED;;;;;;;;GAQG;AAEH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqB7C;AAED;;;;;;GAMG;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASnD;AAED;;;;;;GAMG;AAEH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxD"}