@vouchington/utils 0.4.0 → 0.4.1

package/README.md

@@ -44,6 +44,10 @@ import { createMessageTranslator } from '@vouchington/utils/message-catalog'
 - `hashtags`: caller-configured authored/key length and separator policy for canonical ASCII hashtag
   keys. The package does not choose application limits or accepted input separators.
 - `fetch-ports`: the Fetch standard forbidden-port list and membership predicates.
+- `http-body`: bounded Fetch response-body reads with abort propagation and typed missing/oversize
+  errors.
+- `http-link-pagination`: fail-closed RFC 8288 next-link parsing with same-origin URL and
+  unambiguous cursor extraction.
 - `language-tags`: caller-configured locale normalization and strict `Accept-Language` parsing and
   best matching. HTTP ranges reject malformed syntax and quality parameters; explicit `q=0` ranges
   exclude a candidate when they tie for that candidate's most-specific matching range, so `en;q=0`

package/dist/http-body.d.mts

@@ -0,0 +1,18 @@
+export interface ReadResponseBodyOptions {
+    readonly response: Response;
+    readonly url: string;
+    readonly maxSizeBytes: number;
+    readonly signal?: AbortSignal;
+}
+export declare class MissingResponseBodyError extends Error {
+    readonly url: string;
+    constructor(url: string);
+}
+export declare class ResponseBodyTooLargeError extends Error {
+    readonly url: string;
+    readonly sizeBytes: number;
+    readonly maxSizeBytes: number;
+    constructor(url: string, sizeBytes: number, maxSizeBytes: number);
+}
+export declare function readResponseBodyAsBuffer({ response, url, maxSizeBytes, signal, }: ReadResponseBodyOptions): Promise<Buffer>;
+export declare function readResponseBody(options: ReadResponseBodyOptions): Promise<string>;

package/dist/http-body.mjs

@@ -0,0 +1,86 @@
+export class MissingResponseBodyError extends Error {
+    url;
+    constructor(url) {
+        super(`HTTP response from ${url} has no body`);
+        this.name = 'MissingResponseBodyError';
+        this.url = url;
+    }
+}
+export class ResponseBodyTooLargeError extends Error {
+    url;
+    sizeBytes;
+    maxSizeBytes;
+    constructor(url, sizeBytes, maxSizeBytes) {
+        super(`HTTP response from ${url} exceeded ${maxSizeBytes} bytes (read ${sizeBytes})`);
+        this.name = 'ResponseBodyTooLargeError';
+        this.url = url;
+        this.sizeBytes = sizeBytes;
+        this.maxSizeBytes = maxSizeBytes;
+    }
+}
+function abortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    if (signal.reason !== undefined)
+        return new Error(String(signal.reason));
+    return new Error('HTTP response body read aborted');
+}
+function validateMaxSize(maxSizeBytes) {
+    if (!Number.isSafeInteger(maxSizeBytes) || maxSizeBytes < 0) {
+        throw new RangeError('maxSizeBytes must be a non-negative safe integer');
+    }
+}
+export async function readResponseBodyAsBuffer({ response, url, maxSizeBytes, signal, }) {
+    validateMaxSize(maxSizeBytes);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new MissingResponseBodyError(url);
+    let abortListener;
+    let abortPromise;
+    if (signal) {
+        abortPromise = new Promise((_resolve, reject) => {
+            abortListener = () => {
+                const reason = abortReason(signal);
+                void reader.cancel(reason).catch(() => undefined);
+                reject(reason);
+            };
+            if (signal.aborted)
+                abortListener();
+            else
+                signal.addEventListener('abort', abortListener, { once: true });
+        });
+        void abortPromise.catch(() => undefined);
+    }
+    const chunks = [];
+    let totalSize = 0;
+    try {
+        for (;;) {
+            const result = await (abortPromise
+                ? Promise.race([reader.read(), abortPromise])
+                : reader.read());
+            if (signal?.aborted)
+                throw abortReason(signal);
+            if (result.done)
+                return Buffer.concat(chunks, totalSize);
+            totalSize += result.value.byteLength;
+            if (totalSize > maxSizeBytes) {
+                const error = new ResponseBodyTooLargeError(url, totalSize, maxSizeBytes);
+                await reader.cancel(error).catch(() => undefined);
+                throw error;
+            }
+            chunks.push(result.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        if (signal && abortListener)
+            signal.removeEventListener('abort', abortListener);
+        reader.releaseLock();
+    }
+}
+export async function readResponseBody(options) {
+    return (await readResponseBodyAsBuffer(options)).toString('utf8');
+}

package/dist/http-link-pagination.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Resolve the `rel=next` target in an RFC 8288 Link header without permitting a
+ * response to redirect an authenticated pagination client to another origin.
+ *
+ * A malformed or unsafe Link header is treated as having no next page. Callers
+ * can therefore stop safely without having to distinguish an exhausted list
+ * from a provider that returned an unusable continuation.
+ */
+export declare function nextPageUrlFromLinkHeader(linkHeader: string | null | undefined, requestUrl: string | URL): URL | null;
+/** Return an unambiguous next-page cursor from a safe Link header target. */
+export declare function nextPageCursorFromLinkHeader(linkHeader: string | null | undefined, requestUrl: string | URL, cursorParameter?: string): string | null;
+/** Validate a pagination request URL before it is used as a Link resolution base. */
+export declare function validatePaginationRequestUrl(requestUrl: string | URL): URL;

package/dist/http-link-pagination.mjs

@@ -0,0 +1,141 @@
+/**
+ * Resolve the `rel=next` target in an RFC 8288 Link header without permitting a
+ * response to redirect an authenticated pagination client to another origin.
+ *
+ * A malformed or unsafe Link header is treated as having no next page. Callers
+ * can therefore stop safely without having to distinguish an exhausted list
+ * from a provider that returned an unusable continuation.
+ */
+export function nextPageUrlFromLinkHeader(linkHeader, requestUrl) {
+    const baseUrl = validatePaginationRequestUrl(requestUrl);
+    if (linkHeader == null)
+        return null;
+    const links = parseLinkHeader(linkHeader);
+    if (!links)
+        return null;
+    const nextLinks = links.filter((link) => link.relations.includes('next'));
+    if (nextLinks.length !== 1)
+        return null;
+    let nextUrl;
+    try {
+        nextUrl = new URL(nextLinks[0].target, baseUrl);
+    }
+    catch {
+        return null;
+    }
+    if (nextUrl.origin !== baseUrl.origin ||
+        nextUrl.username !== '' ||
+        nextUrl.password !== '' ||
+        nextUrl.hash !== '') {
+        return null;
+    }
+    return nextUrl;
+}
+/** Return an unambiguous next-page cursor from a safe Link header target. */
+export function nextPageCursorFromLinkHeader(linkHeader, requestUrl, cursorParameter = 'page') {
+    const nextUrl = nextPageUrlFromLinkHeader(linkHeader, requestUrl);
+    if (!nextUrl)
+        return null;
+    const values = nextUrl.searchParams.getAll(cursorParameter);
+    return values.length === 1 && values[0] !== '' ? values[0] : null;
+}
+/** Validate a pagination request URL before it is used as a Link resolution base. */
+export function validatePaginationRequestUrl(requestUrl) {
+    let url;
+    try {
+        url = new URL(requestUrl);
+    }
+    catch {
+        throw new Error('pagination request URL must be an absolute HTTP(S) URL without credentials');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.hash !== '') {
+        throw new Error('pagination request URL must be an absolute HTTP(S) URL without credentials');
+    }
+    return url;
+}
+function parseLinkHeader(header) {
+    const links = [];
+    let index = 0;
+    while (index < header.length) {
+        index = skipWhitespace(header, index);
+        if (header[index] !== '<')
+            return null;
+        const targetEnd = header.indexOf('>', index + 1);
+        if (targetEnd === -1)
+            return null;
+        const target = header.slice(index + 1, targetEnd);
+        if (target === '')
+            return null;
+        index = targetEnd + 1;
+        const relations = [];
+        while (true) {
+            index = skipWhitespace(header, index);
+            if (index === header.length || header[index] === ',')
+                break;
+            if (header[index] !== ';')
+                return null;
+            index = skipWhitespace(header, index + 1);
+            const name = readToken(header, index);
+            if (!name)
+                return null;
+            index = name.end;
+            index = skipWhitespace(header, index);
+            if (header[index] !== '=')
+                return null;
+            index = skipWhitespace(header, index + 1);
+            const value = readParameterValue(header, index);
+            if (!value)
+                return null;
+            index = value.end;
+            if (name.value.toLowerCase() === 'rel') {
+                relations.push(...value.value.toLowerCase().split(/\s+/).filter(Boolean));
+            }
+        }
+        links.push({ target, relations });
+        if (index === header.length)
+            return links;
+        index += 1;
+        if (index === header.length)
+            return null;
+    }
+    return null;
+}
+function skipWhitespace(value, index) {
+    while (value[index] === ' ' || value[index] === '\t')
+        index += 1;
+    return index;
+}
+function readToken(value, index) {
+    const start = index;
+    while (index < value.length && isTokenCharacter(value[index]))
+        index += 1;
+    return index === start ? null : { value: value.slice(start, index), end: index };
+}
+function isTokenCharacter(value) {
+    return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]$/.test(value);
+}
+function readParameterValue(value, index) {
+    if (value[index] !== '"')
+        return readToken(value, index);
+    let parsed = '';
+    index += 1;
+    while (index < value.length) {
+        const character = value[index];
+        if (character === '"')
+            return { value: parsed, end: index + 1 };
+        if (character === '\\') {
+            const escaped = value[index + 1];
+            if (!escaped)
+                return null;
+            parsed += escaped;
+            index += 2;
+            continue;
+        }
+        parsed += character;
+        index += 1;
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -154,6 +154,16 @@
       "types": "./dist/fetch-ports.d.mts",
       "import": "./dist/fetch-ports.mjs",
       "default": "./dist/fetch-ports.mjs"
+    },
+    "./http-body": {
+      "types": "./dist/http-body.d.mts",
+      "import": "./dist/http-body.mjs",
+      "default": "./dist/http-body.mjs"
+    },
+    "./http-link-pagination": {
+      "types": "./dist/http-link-pagination.d.mts",
+      "import": "./dist/http-link-pagination.mjs",
+      "default": "./dist/http-link-pagination.mjs"
     }
   },
   "publishConfig": {