@zudojs/http 0.1.0 → 1.1.0

package/dist/httpCacheControl/core/httpCacheControl.parse.js

@@ -0,0 +1,229 @@
+/**
+ * Cache control header parsing and formatting.
+ *
+ * @module httpCacheControl/parsing
+ */
+/**
+ * RFC 9111 section 1.2.2 recommends clamping `delta-seconds` to this value.
+ */
+const MAX_DELTA_SECONDS = 2_147_483_648;
+/**
+ * Maximum number of directives parsed from one header.
+ */
+const MAX_DIRECTIVES = 64;
+/**
+ * Parses a Cache-Control header value into directives.
+ *
+ * The comma split honours `quoted-string`, so the qualified form
+ * `no-cache="Set-Cookie, Authorization"` survives instead of being torn into
+ * an unqualified `no-cache` — which would let a shared cache store and replay
+ * a response's `Set-Cookie` and `Authorization` headers to other users.
+ *
+ * A directive that appears more than once with conflicting values is dropped
+ * entirely, per RFC 9111 section 4.2.1; taking the last value is the
+ * attacker-favourable choice.
+ *
+ * @param header - The raw header value.
+ * @returns The parsed directives.
+ */
+export function parseCacheControl(header) {
+    if (!header) {
+        return {};
+    }
+    const directives = Object.create(null);
+    const conflicting = new Set();
+    for (const part of splitDirectives(header).slice(0, MAX_DIRECTIVES)) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        const eqIndex = trimmed.indexOf("=");
+        const key = eqIndex === -1
+            ? trimmed.toLowerCase()
+            : trimmed.slice(0, eqIndex).trim().toLowerCase();
+        const value = eqIndex === -1 ? true : unquoteDirective(trimmed.slice(eqIndex + 1));
+        if (Object.prototype.hasOwnProperty.call(directives, key)) {
+            if (directives[key] !== value) {
+                conflicting.add(key);
+            }
+            continue;
+        }
+        directives[key] = value;
+    }
+    for (const key of conflicting) {
+        delete directives[key];
+    }
+    return {
+        noCache: directives["no-cache"] === true ||
+            typeof directives["no-cache"] === "string",
+        noStore: directives["no-store"] === true,
+        noTransform: directives["no-transform"] === true,
+        onlyIfCached: directives["only-if-cached"] === true,
+        maxAge: parseDirectiveValue(directives["max-age"]),
+        maxStale: parseDirectiveValue(directives["max-stale"]),
+        minFresh: parseDirectiveValue(directives["min-fresh"]),
+        sMaxAge: parseDirectiveValue(directives["s-maxage"]),
+        mustRevalidate: directives["must-revalidate"] === true,
+        proxyRevalidate: directives["proxy-revalidate"] === true,
+        mustUnderstand: directives["must-understand"] === true,
+        private: directives["private"] === true,
+        public: directives["public"] === true,
+        immutable: directives["immutable"] === true,
+        staleWhileRevalidate: parseDirectiveValue(directives["stale-while-revalidate"]),
+        staleIfError: parseDirectiveValue(directives["stale-if-error"]),
+        noCacheHeaders: parseNoCacheHeaders(directives["no-cache"]),
+    };
+}
+/**
+ * Splits a Cache-Control header on commas outside a `quoted-string`.
+ *
+ * @param header - The raw header value.
+ * @returns The directive fragments, quotes preserved.
+ */
+function splitDirectives(header) {
+    const result = [];
+    let current = "";
+    let quoted = false;
+    let escaped = false;
+    for (const character of header) {
+        if (escaped) {
+            current += character;
+            escaped = false;
+            continue;
+        }
+        if (quoted && character === "\\") {
+            current += character;
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            quoted = !quoted;
+            current += character;
+            continue;
+        }
+        if (character === "," && !quoted) {
+            result.push(current);
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    result.push(current);
+    return result;
+}
+/**
+ * Strips the surrounding quotes from a directive value.
+ *
+ * @param raw - The raw value, possibly a `quoted-string`.
+ * @returns The unquoted value.
+ */
+function unquoteDirective(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/**
+ * Parses a `delta-seconds` directive value.
+ *
+ * RFC 9111 section 1.2.2 defines `delta-seconds` as a non-negative integer,
+ * so `-1`, `100abc` and `1e20` are rejected rather than silently coerced into
+ * date arithmetic that then computes a time in the past or overflows.
+ *
+ * @param value - The raw directive value.
+ * @returns The clamped seconds, or `undefined` if malformed.
+ */
+function parseDirectiveValue(value) {
+    if (typeof value === "boolean") {
+        return value ? 0 : undefined;
+    }
+    if (typeof value !== "string" || !/^\d+$/.test(value.trim())) {
+        return undefined;
+    }
+    return Math.min(Number(value.trim()), MAX_DELTA_SECONDS);
+}
+/**
+ * Parses the field-name list of a qualified `no-cache` directive.
+ *
+ * @param value - The `no-cache` directive value.
+ * @returns The listed field names, or `undefined` when unqualified.
+ */
+function parseNoCacheHeaders(value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        return undefined;
+    }
+    return value
+        .split(",")
+        .map((name) => name.trim().replace(/"/g, ""))
+        .filter((name) => name.length > 0);
+}
+/**
+ * Formats CacheControlDirectives into a Cache-Control header string.
+ */
+export function formatCacheControl(directives) {
+    const parts = [];
+    if (directives.maxAge !== undefined) {
+        parts.push(`max-age=${directives.maxAge}`);
+    }
+    if (directives.sMaxAge !== undefined) {
+        parts.push(`s-maxage=${directives.sMaxAge}`);
+    }
+    if (directives.noCache) {
+        parts.push("no-cache");
+    }
+    if (directives.noStore) {
+        parts.push("no-store");
+    }
+    if (directives.mustRevalidate) {
+        parts.push("must-revalidate");
+    }
+    if (directives.proxyRevalidate) {
+        parts.push("proxy-revalidate");
+    }
+    if (directives.private) {
+        parts.push("private");
+    }
+    if (directives.public) {
+        parts.push("public");
+    }
+    if (directives.immutable) {
+        parts.push("immutable");
+    }
+    if (directives.staleWhileRevalidate !== undefined) {
+        parts.push(`stale-while-revalidate=${directives.staleWhileRevalidate}`);
+    }
+    if (directives.staleIfError !== undefined) {
+        parts.push(`stale-if-error=${directives.staleIfError}`);
+    }
+    if (directives.noTransform) {
+        parts.push("no-transform");
+    }
+    if (directives.onlyIfCached) {
+        parts.push("only-if-cached");
+    }
+    if (directives.mustUnderstand) {
+        parts.push("must-understand");
+    }
+    if (directives.maxStale !== undefined) {
+        parts.push(`max-stale=${directives.maxStale}`);
+    }
+    if (directives.minFresh !== undefined) {
+        parts.push(`min-fresh=${directives.minFresh}`);
+    }
+    if (directives.noCacheHeaders && directives.noCacheHeaders.length > 0) {
+        /*
+         * The qualified form replaces the bare no-cache emitted above.
+         */
+        const index = parts.indexOf("no-cache");
+        const qualified = `no-cache="${directives.noCacheHeaders.join(", ")}"`;
+        if (index === -1) {
+            parts.push(qualified);
+        }
+        else {
+            parts[index] = qualified;
+        }
+    }
+    return parts.join(", ");
+}
+//# sourceMappingURL=httpCacheControl.parse.js.map

package/dist/httpCacheControl/core/httpCacheControl.type.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cache control types and constants.
+ *
+ * @module httpCacheControl/types
+ */
+export interface CacheControlDirectives {
+    readonly noCache?: boolean;
+    readonly noStore?: boolean;
+    readonly noTransform?: boolean;
+    readonly onlyIfCached?: boolean;
+    readonly maxAge?: number;
+    readonly maxStale?: number;
+    readonly minFresh?: number;
+    readonly sMaxAge?: number;
+    readonly mustRevalidate?: boolean;
+    readonly proxyRevalidate?: boolean;
+    readonly mustUnderstand?: boolean;
+    readonly private?: boolean;
+    readonly public?: boolean;
+    readonly immutable?: boolean;
+    readonly staleWhileRevalidate?: number;
+    readonly staleIfError?: number;
+    readonly noCacheHeaders?: readonly string[];
+}
+export interface CacheControlOptions {
+    readonly maxAge?: number;
+    readonly maxStale?: number;
+    readonly minFresh?: number;
+    readonly mustUnderstand?: boolean;
+    readonly noCacheHeaders?: readonly string[];
+    readonly sMaxAge?: number;
+    readonly noCache?: boolean;
+    readonly noStore?: boolean;
+    readonly mustRevalidate?: boolean;
+    readonly proxyRevalidate?: boolean;
+    readonly private?: boolean;
+    readonly public?: boolean;
+    readonly immutable?: boolean;
+    readonly staleWhileRevalidate?: number;
+    readonly staleIfError?: number;
+    readonly noTransform?: boolean;
+    readonly onlyIfCached?: boolean;
+}
+export interface CacheFreshness {
+    readonly maxAge: number;
+    readonly expires: Date | undefined;
+    readonly date: Date | undefined;
+    readonly age: number;
+    readonly stale: boolean;
+    readonly remaining: number;
+}
+export declare const CACHE_CONTROL_HEADER: "cache-control";
+export declare const DEFAULT_MAX_AGE = 0;
+//# sourceMappingURL=httpCacheControl.type.d.ts.map

package/dist/httpCacheControl/core/httpCacheControl.type.js

@@ -0,0 +1,8 @@
+/**
+ * Cache control types and constants.
+ *
+ * @module httpCacheControl/types
+ */
+export const CACHE_CONTROL_HEADER = "cache-control";
+export const DEFAULT_MAX_AGE = 0;
+//# sourceMappingURL=httpCacheControl.type.js.map

package/dist/httpCacheControl/core/httpCacheControl.validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cache control validation.
+ *
+ * @module httpCacheControl/validation
+ */
+/**
+ * Validates cache control directives for correctness.
+ */
+export declare function validateCacheControl(header: string | undefined): {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+};
+//# sourceMappingURL=httpCacheControl.validation.d.ts.map

package/dist/httpCacheControl/core/httpCacheControl.validation.js

@@ -0,0 +1,87 @@
+/**
+ * Cache control validation.
+ *
+ * @module httpCacheControl/validation
+ */
+import { parseCacheControl } from "./httpCacheControl.parse.js";
+/**
+ * Validates cache control directives for correctness.
+ */
+export function validateCacheControl(header) {
+    const errors = [];
+    const directives = parseCacheControl(header);
+    errors.push(...findMalformedDeltaSeconds(header));
+    if (directives.maxAge !== undefined && directives.maxAge < 0) {
+        errors.push("max-age must be non-negative");
+    }
+    if (directives.sMaxAge !== undefined && directives.sMaxAge < 0) {
+        errors.push("s-maxage must be non-negative");
+    }
+    if (directives.maxStale !== undefined && directives.maxStale < 0) {
+        errors.push("max-stale must be non-negative");
+    }
+    if (directives.minFresh !== undefined && directives.minFresh < 0) {
+        errors.push("min-fresh must be non-negative");
+    }
+    if (directives.staleWhileRevalidate !== undefined &&
+        directives.staleWhileRevalidate < 0) {
+        errors.push("stale-while-revalidate must be non-negative");
+    }
+    if (directives.staleIfError !== undefined && directives.staleIfError < 0) {
+        errors.push("stale-if-error must be non-negative");
+    }
+    if (directives.private && directives.public) {
+        errors.push("cannot have both private and public directives");
+    }
+    if (directives.noStore &&
+        (directives.maxAge !== undefined || directives.sMaxAge !== undefined)) {
+        errors.push("no-store is incompatible with max-age/s-maxage");
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Directives whose value must be `delta-seconds`.
+ */
+const DELTA_SECONDS_DIRECTIVES = new Set([
+    "max-age",
+    "s-maxage",
+    "max-stale",
+    "min-fresh",
+    "stale-while-revalidate",
+    "stale-if-error",
+]);
+/**
+ * Reports directives whose value is not a valid `delta-seconds`.
+ *
+ * The parser drops a malformed value, so without this scan
+ * `Cache-Control: max-age=abc` would be reported as valid — the validator
+ * would see nothing to complain about.
+ *
+ * @param header - The raw header value.
+ * @returns One error message per malformed directive.
+ */
+function findMalformedDeltaSeconds(header) {
+    if (!header) {
+        return [];
+    }
+    const errors = [];
+    for (const part of header.split(",")) {
+        const trimmed = part.trim();
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, eqIndex).trim().toLowerCase();
+        if (!DELTA_SECONDS_DIRECTIVES.has(key)) {
+            continue;
+        }
+        if (!/^\d+$/.test(trimmed.slice(eqIndex + 1).trim())) {
+            errors.push(`${key} must be a non-negative integer`);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=httpCacheControl.validation.js.map

package/dist/httpCacheControl/core/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Core cache control utilities.
+ *
+ * @module httpCacheControl/core
+ */
+export * from "./httpCacheControl.type.js";
+export * from "./httpCacheControl.parse.js";
+export * from "./httpCacheControl.validation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpCacheControl/core/index.js

@@ -0,0 +1,9 @@
+/**
+ * Core cache control utilities.
+ *
+ * @module httpCacheControl/core
+ */
+export * from "./httpCacheControl.type.js";
+export * from "./httpCacheControl.parse.js";
+export * from "./httpCacheControl.validation.js";
+//# sourceMappingURL=index.js.map

package/dist/httpCacheControl/httpCacheControl.core.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cache control utilities for HTTP responses.
+ *
+ * @module httpCacheControl
+ */
+export * from "./core/httpCacheControl.type.js";
+export * from "./core/httpCacheControl.parse.js";
+export * from "./core/httpCacheControl.validation.js";
+export * from "./httpCacheControl.requestHelper.js";
+export * from "./httpCacheControl.responseHelper.js";
+export * from "./httpCacheControl.freshness.js";
+export * from "./httpCacheControl.factory.js";
+//# sourceMappingURL=httpCacheControl.core.d.ts.map

package/dist/httpCacheControl/httpCacheControl.core.js

@@ -0,0 +1,13 @@
+/**
+ * Cache control utilities for HTTP responses.
+ *
+ * @module httpCacheControl
+ */
+export * from "./core/httpCacheControl.type.js";
+export * from "./core/httpCacheControl.parse.js";
+export * from "./core/httpCacheControl.validation.js";
+export * from "./httpCacheControl.requestHelper.js";
+export * from "./httpCacheControl.responseHelper.js";
+export * from "./httpCacheControl.freshness.js";
+export * from "./httpCacheControl.factory.js";
+//# sourceMappingURL=httpCacheControl.core.js.map

package/dist/httpCacheControl/httpCacheControl.factory.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cache control factory.
+ *
+ * @module httpCacheControl/factory
+ */
+import type { CacheControlOptions } from "./core/httpCacheControl.type.js";
+/**
+ * Creates a Cache-Control header string from options.
+ */
+export declare function createCacheControl(options?: CacheControlOptions): string;
+/**
+ * Creates a no-cache header.
+ */
+export declare function createNoCacheHeader(): string;
+/**
+ * Creates a no-store header.
+ */
+export declare function createNoStoreHeader(): string;
+/**
+ * Creates a public cache header with max-age.
+ */
+export declare function createPublicCacheHeader(maxAge: number): string;
+/**
+ * Creates a private cache header with max-age.
+ */
+export declare function createPrivateCacheHeader(maxAge: number): string;
+/**
+ * Creates an immutable cache header.
+ */
+export declare function createImmutableCacheHeader(maxAge: number): string;
+/**
+ * Creates a stale-while-revalidate header.
+ */
+export declare function createStaleWhileRevalidateHeader(maxAge: number, staleWhileRevalidate: number): string;
+//# sourceMappingURL=httpCacheControl.factory.d.ts.map

package/dist/httpCacheControl/httpCacheControl.factory.js

@@ -0,0 +1,53 @@
+/**
+ * Cache control factory.
+ *
+ * @module httpCacheControl/factory
+ */
+import { formatCacheControl } from "./core/httpCacheControl.parse.js";
+/**
+ * Creates a Cache-Control header string from options.
+ */
+export function createCacheControl(options = {}) {
+    return formatCacheControl(options);
+}
+/**
+ * Creates a no-cache header.
+ */
+export function createNoCacheHeader() {
+    return createCacheControl({ noCache: true, maxAge: 0 });
+}
+/**
+ * Creates a no-store header.
+ */
+export function createNoStoreHeader() {
+    return createCacheControl({ noStore: true });
+}
+/**
+ * Creates a public cache header with max-age.
+ */
+export function createPublicCacheHeader(maxAge) {
+    return createCacheControl({ public: true, maxAge });
+}
+/**
+ * Creates a private cache header with max-age.
+ */
+export function createPrivateCacheHeader(maxAge) {
+    return createCacheControl({ private: true, maxAge });
+}
+/**
+ * Creates an immutable cache header.
+ */
+export function createImmutableCacheHeader(maxAge) {
+    return createCacheControl({ public: true, maxAge, immutable: true });
+}
+/**
+ * Creates a stale-while-revalidate header.
+ */
+export function createStaleWhileRevalidateHeader(maxAge, staleWhileRevalidate) {
+    return createCacheControl({
+        public: true,
+        maxAge,
+        staleWhileRevalidate,
+    });
+}
+//# sourceMappingURL=httpCacheControl.factory.js.map

package/dist/httpCacheControl/httpCacheControl.freshness.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cache freshness calculations.
+ *
+ * @module httpCacheControl/freshness
+ */
+import type { CacheFreshness } from "./core/httpCacheControl.type.js";
+/**
+ * Calculates the freshness of a cached response.
+ *
+ * `s-maxage` is preferred over `max-age`, and `Expires` is used when neither
+ * is present. `no-cache` and `no-store` force the response stale — a response
+ * the origin marked must-revalidate-before-reuse must never be reported
+ * fresh.
+ *
+ * @param responseHeaders - The cached response's headers.
+ * @param responseDate - The response's `Date`, if already parsed.
+ * @returns The freshness calculation.
+ */
+export declare function calculateFreshness(responseHeaders: Readonly<Record<string, string>>, responseDate?: Date): CacheFreshness;
+/**
+ * Determines if a cached response is still fresh.
+ */
+export declare function isFresh(responseHeaders: Readonly<Record<string, string>>, requestHeaders?: Readonly<Record<string, string>>): boolean;
+/**
+ * Gets the remaining freshness in seconds.
+ */
+export declare function getRemainingFreshness(responseHeaders: Readonly<Record<string, string>>): number;
+/**
+ * Determines if a stale response can be served while revalidating.
+ */
+export declare function canServeStaleWhileRevalidate(responseHeaders: Readonly<Record<string, string>>): boolean;
+/**
+ * Determines if a stale response can be served on error.
+ */
+export declare function canServeStaleIfError(responseHeaders: Readonly<Record<string, string>>): boolean;
+//# sourceMappingURL=httpCacheControl.freshness.d.ts.map