@chidchanun/bcp 0.1.6 → 0.1.7

package/packages/server/src/request-context.ts

@@ -0,0 +1,1043 @@
+import {
+    AsyncLocalStorage,
+} from "node:async_hooks";
+import {
+    randomUUID,
+} from "node:crypto";
+import {
+    isIP,
+} from "node:net";
+
+/*
+ * =====================================
+ * Public Types
+ * =====================================
+ */
+
+export interface RequestCookie {
+    name: string;
+    value: string;
+}
+
+export type CookieSameSite =
+    | "lax"
+    | "strict"
+    | "none";
+
+export interface ResponseCookieOptions {
+    domain?: string;
+
+    path?: string;
+
+    expires?:
+        Date;
+
+    maxAge?:
+        number;
+
+    httpOnly?:
+        boolean;
+
+    secure?:
+        boolean;
+
+    sameSite?:
+        CookieSameSite;
+}
+
+export interface ResponseCookie
+extends
+    RequestCookie,
+    ResponseCookieOptions {}
+
+export interface RequestCookieStore {
+    get(
+        name: string
+    ): RequestCookie | undefined;
+
+    getAll(
+        name?: string
+    ): RequestCookie[];
+
+    has(
+        name: string
+    ): boolean;
+
+    set(
+        name: string,
+        value: string,
+        options?:
+            ResponseCookieOptions
+    ): void;
+
+    set(
+        cookie:
+            ResponseCookie
+    ): void;
+
+    delete(
+        name: string,
+        options?: {
+            domain?: string;
+            path?: string;
+        }
+    ): void;
+}
+
+export interface ClientIpOptions {
+    trustProxy?:
+        boolean;
+}
+
+interface BcpRequestContext {
+    url:
+        URL;
+
+    method:
+        string;
+
+    requestId:
+        string;
+
+    remoteAddress:
+        string | null;
+
+    headers:
+        Headers;
+
+    cookies:
+        BcpRequestCookieStore;
+}
+
+interface RequestContextOptions {
+    remoteAddress?:
+        string | null;
+}
+
+const requestStorage =
+    new AsyncLocalStorage<
+        BcpRequestContext
+    >();
+
+export async function requestUrl():
+Promise<URL> {
+    const context =
+        getRequestContext();
+
+    return new URL(
+        context.url.href
+    );
+}
+
+export async function requestMethod():
+Promise<string> {
+    return getRequestContext()
+        .method;
+}
+
+export async function requestId():
+Promise<string> {
+    return getRequestContext()
+        .requestId;
+}
+
+export async function bearerToken():
+Promise<string | null> {
+    const authorization =
+        getRequestContext()
+            .headers.get(
+                "authorization"
+            );
+
+    if (!authorization) {
+        return null;
+    }
+
+    const match =
+        /^Bearer\s+(.+)$/i.exec(
+            authorization.trim()
+        );
+
+    if (!match) {
+        return null;
+    }
+
+    const token =
+        match[1].trim();
+
+    return token.length > 0
+        ? token
+        : null;
+}
+
+export async function clientIp(
+    options:
+        ClientIpOptions = {}
+): Promise<string | null> {
+    const context =
+        getRequestContext();
+
+    if (
+        options.trustProxy ===
+        true
+    ) {
+        const forwarded =
+            parseForwardedFor(
+                context.headers
+                    .get(
+                        "forwarded"
+                    )
+            ) ??
+            parseXForwardedFor(
+                context.headers
+                    .get(
+                        "x-forwarded-for"
+                    )
+            ) ??
+            normalizeIpAddress(
+                context.headers
+                    .get(
+                        "x-real-ip"
+                    )
+            );
+
+        if (forwarded) {
+            return forwarded;
+        }
+    }
+
+    return normalizeIpAddress(
+        context.remoteAddress
+    );
+}
+
+export async function headers():
+Promise<Headers> {
+    const context =
+        getRequestContext();
+
+    return new Headers(
+        context.headers
+    );
+}
+
+export async function cookies():
+Promise<RequestCookieStore> {
+    const context =
+        getRequestContext();
+
+    return context.cookies;
+}
+
+export function runWithRequestContext<
+    T
+>(
+    request: Request,
+    callback: () => T,
+    options:
+        RequestContextOptions = {}
+): T {
+    const requestHeaders =
+        new Headers(
+            request.headers
+        );
+
+    const cookieStore =
+        new BcpRequestCookieStore(
+            requestHeaders.get(
+                "cookie"
+            )
+        );
+
+    const incomingRequestId =
+        normalizeRequestId(
+            requestHeaders.get(
+                "x-request-id"
+            )
+        );
+
+    return requestStorage.run(
+        {
+            url:
+                new URL(
+                    request.url
+                ),
+
+            method:
+                request.method
+                    .toUpperCase(),
+
+            requestId:
+                incomingRequestId ??
+                randomUUID(),
+
+            remoteAddress:
+                options.remoteAddress ??
+                null,
+
+            headers:
+                requestHeaders,
+
+            cookies:
+                cookieStore,
+        },
+        callback
+    );
+}
+
+export function applyResponseCookies(
+    response: Response
+): Response {
+    const context =
+        getRequestContext();
+
+    const setCookies =
+        context.cookies
+            .getPendingSetCookies();
+
+    if (
+        setCookies.length ===
+        0
+    ) {
+        return response;
+    }
+
+    const responseHeaders =
+        new Headers(
+            response.headers
+        );
+
+    for (
+        const cookie
+        of setCookies
+    ) {
+        responseHeaders.append(
+            "set-cookie",
+            cookie
+        );
+    }
+
+    return new Response(
+        response.body,
+        {
+            status:
+                response.status,
+
+            statusText:
+                response.statusText,
+
+            headers:
+                responseHeaders,
+        }
+    );
+}
+
+function getRequestContext():
+BcpRequestContext {
+    const context =
+        requestStorage.getStore();
+
+    if (!context) {
+        throw new Error(
+            "BCP Framework: server request APIs can only be used while handling a request."
+        );
+    }
+
+    return context;
+}
+
+function normalizeRequestId(
+    value:
+        string | null
+): string | null {
+    if (!value) {
+        return null;
+    }
+
+    const normalized =
+        value.trim();
+
+    if (
+        normalized.length ===
+        0 ||
+        normalized.length >
+        256 ||
+        /[\u0000-\u001F\u007F]/.test(
+            normalized
+        )
+    ) {
+        return null;
+    }
+
+    return normalized;
+}
+
+function parseXForwardedFor(
+    value:
+        string | null
+): string | null {
+    if (!value) {
+        return null;
+    }
+
+    for (
+        const part
+        of value.split(",")
+    ) {
+        const candidate =
+            normalizeIpAddress(
+                part
+            );
+
+        if (candidate) {
+            return candidate;
+        }
+    }
+
+    return null;
+}
+
+function parseForwardedFor(
+    value:
+        string | null
+): string | null {
+    if (!value) {
+        return null;
+    }
+
+    for (
+        const forwardedElement
+        of value.split(",")
+    ) {
+        for (
+            const parameter
+            of forwardedElement
+                .split(";")
+        ) {
+            const separator =
+                parameter.indexOf("=");
+
+            if (
+                separator <= 0 ||
+                parameter
+                    .slice(
+                        0,
+                        separator
+                    )
+                    .trim()
+                    .toLowerCase() !==
+                    "for"
+            ) {
+                continue;
+            }
+
+            let candidate =
+                parameter
+                    .slice(
+                        separator + 1
+                    )
+                    .trim();
+
+            if (
+                candidate.startsWith(
+                    "\""
+                ) &&
+                candidate.endsWith(
+                    "\""
+                )
+            ) {
+                candidate =
+                    candidate.slice(
+                        1,
+                        -1
+                    );
+            }
+
+            const normalized =
+                normalizeIpAddress(
+                    candidate
+                );
+
+            if (normalized) {
+                return normalized;
+            }
+        }
+    }
+
+    return null;
+}
+
+function normalizeIpAddress(
+    value:
+        string | null
+): string | null {
+    if (!value) {
+        return null;
+    }
+
+    let normalized =
+        value.trim();
+
+    if (
+        normalized.length ===
+        0 ||
+        normalized.toLowerCase() ===
+        "unknown" ||
+        normalized.startsWith(
+            "_"
+        )
+    ) {
+        return null;
+    }
+
+    if (
+        normalized.startsWith(
+            "["
+        )
+    ) {
+        const closingBracket =
+            normalized.indexOf(
+                "]"
+            );
+
+        if (
+            closingBracket > 0
+        ) {
+            normalized =
+                normalized.slice(
+                    1,
+                    closingBracket
+                );
+        }
+    } else {
+        const ipv4WithPort =
+            /^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/.exec(
+                normalized
+            );
+
+        if (ipv4WithPort) {
+            normalized =
+                ipv4WithPort[1];
+        }
+    }
+
+    if (
+        normalized.startsWith(
+            "::ffff:"
+        )
+    ) {
+        normalized =
+            normalized.slice(
+                "::ffff:".length
+            );
+    }
+
+    return isIP(
+        normalized
+    ) > 0
+        ? normalized
+        : null;
+}
+
+class BcpRequestCookieStore
+implements RequestCookieStore {
+    private readonly items:
+        RequestCookie[];
+
+    private readonly pendingSetCookies:
+        string[] = [];
+
+    constructor(
+        cookieHeader:
+            string | null
+    ) {
+        this.items =
+            parseCookieHeader(
+                cookieHeader
+            );
+    }
+
+    get(
+        name: string
+    ):
+        RequestCookie |
+        undefined {
+        const cookie =
+            this.items.find(
+                (item) =>
+                    item.name ===
+                    name
+            );
+
+        if (!cookie) {
+            return undefined;
+        }
+
+        return {
+            ...cookie,
+        };
+    }
+
+    getAll(
+        name?: string
+    ): RequestCookie[] {
+        const result =
+            name === undefined
+                ? this.items
+                : this.items.filter(
+                    (item) =>
+                        item.name ===
+                        name
+                );
+
+        return result.map(
+            (cookie) => ({
+                ...cookie,
+            })
+        );
+    }
+
+    has(
+        name: string
+    ): boolean {
+        return this.items.some(
+            (cookie) =>
+                cookie.name ===
+                name
+        );
+    }
+
+    set(
+        nameOrCookie:
+            string |
+            ResponseCookie,
+
+        value?: string,
+
+        options:
+            ResponseCookieOptions =
+                {}
+    ): void {
+        let cookie:
+            ResponseCookie;
+
+        if (
+            typeof nameOrCookie ===
+            "string"
+        ) {
+            if (
+                value ===
+                undefined
+            ) {
+                throw new Error(
+                    "BCP Framework: cookie value is required."
+                );
+            }
+
+            cookie = {
+                name:
+                    nameOrCookie,
+
+                value,
+
+                ...options,
+            };
+        } else {
+            cookie = {
+                ...nameOrCookie,
+            };
+        }
+
+        validateCookieName(
+            cookie.name
+        );
+
+        validateCookieValue(
+            cookie.value
+        );
+
+        this.upsertLocalCookie(
+            cookie.name,
+            cookie.value
+        );
+
+        this.pendingSetCookies.push(
+            serializeCookie(
+                cookie
+            )
+        );
+    }
+
+    delete(
+        name: string,
+        options: {
+            domain?: string;
+            path?: string;
+        } = {}
+    ): void {
+        validateCookieName(
+            name
+        );
+
+        for (
+            let index =
+                this.items.length - 1;
+
+            index >= 0;
+
+            index--
+        ) {
+            if (
+                this.items[index]
+                    .name ===
+                name
+            ) {
+                this.items.splice(
+                    index,
+                    1
+                );
+            }
+        }
+
+        this.pendingSetCookies.push(
+            serializeCookie({
+                name,
+
+                value:
+                    "",
+
+                path:
+                    options.path ??
+                    "/",
+
+                domain:
+                    options.domain,
+
+                expires:
+                    new Date(0),
+
+                maxAge:
+                    0,
+            })
+        );
+    }
+
+    getPendingSetCookies():
+    string[] {
+        return [
+            ...this.pendingSetCookies,
+        ];
+    }
+
+    private upsertLocalCookie(
+        name: string,
+        value: string
+    ): void {
+        const existing =
+            this.items.find(
+                (cookie) =>
+                    cookie.name ===
+                    name
+            );
+
+        if (existing) {
+            existing.value =
+                value;
+
+            return;
+        }
+
+        this.items.push({
+            name,
+            value,
+        });
+    }
+}
+
+function parseCookieHeader(
+    header:
+        string | null
+): RequestCookie[] {
+    if (!header) {
+        return [];
+    }
+
+    const result:
+        RequestCookie[] = [];
+
+    for (
+        const segment
+        of header.split(";")
+    ) {
+        const separator =
+            segment.indexOf("=");
+
+        if (
+            separator <= 0
+        ) {
+            continue;
+        }
+
+        const name =
+            segment
+                .slice(
+                    0,
+                    separator
+                )
+                .trim();
+
+        if (!name) {
+            continue;
+        }
+
+        const rawValue =
+            segment
+                .slice(
+                    separator + 1
+                )
+                .trim();
+
+        result.push({
+            name,
+
+            value:
+                decodeCookieValue(
+                    rawValue
+                ),
+        });
+    }
+
+    return result;
+}
+
+function serializeCookie(
+    cookie:
+        ResponseCookie
+): string {
+    validateCookieName(
+        cookie.name
+    );
+
+    validateCookieValue(
+        cookie.value
+    );
+
+    const parts:
+        string[] = [
+            `${cookie.name}=${encodeURIComponent(
+                cookie.value
+            )}`,
+        ];
+
+    if (
+        cookie.domain !==
+        undefined
+    ) {
+        validateCookieAttribute(
+            cookie.domain,
+            "domain"
+        );
+
+        parts.push(
+            `Domain=${cookie.domain}`
+        );
+    }
+
+    if (
+        cookie.path !==
+        undefined
+    ) {
+        validateCookieAttribute(
+            cookie.path,
+            "path"
+        );
+
+        parts.push(
+            `Path=${cookie.path}`
+        );
+    }
+
+    if (
+        cookie.expires !==
+        undefined
+    ) {
+        if (
+            !(
+                cookie.expires
+                instanceof Date
+            ) ||
+            Number.isNaN(
+                cookie.expires.getTime()
+            )
+        ) {
+            throw new Error(
+                "BCP Framework: cookie expires must be a valid Date."
+            );
+        }
+
+        parts.push(
+            `Expires=${cookie.expires.toUTCString()}`
+        );
+    }
+
+    if (
+        cookie.maxAge !==
+        undefined
+    ) {
+        if (
+            !Number.isFinite(
+                cookie.maxAge
+            )
+        ) {
+            throw new Error(
+                "BCP Framework: cookie maxAge must be a finite number."
+            );
+        }
+
+        parts.push(
+            `Max-Age=${Math.trunc(
+                cookie.maxAge
+            )}`
+        );
+    }
+
+    if (
+        cookie.httpOnly
+    ) {
+        parts.push(
+            "HttpOnly"
+        );
+    }
+
+    if (
+        cookie.secure
+    ) {
+        parts.push(
+            "Secure"
+        );
+    }
+
+    if (
+        cookie.sameSite !==
+        undefined
+    ) {
+        parts.push(
+            `SameSite=${formatSameSite(
+                cookie.sameSite
+            )}`
+        );
+    }
+
+    return parts.join(
+        "; "
+    );
+}
+
+function validateCookieName(
+    name: string
+): void {
+    if (
+        typeof name !==
+        "string" ||
+        name.length ===
+        0
+    ) {
+        throw new Error(
+            "BCP Framework: cookie name must be a non-empty string."
+        );
+    }
+
+    if (
+        !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(
+            name
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: invalid cookie name "${name}".`
+        );
+    }
+}
+
+function validateCookieValue(
+    value: string
+): void {
+    if (
+        typeof value !==
+        "string"
+    ) {
+        throw new Error(
+            "BCP Framework: cookie value must be a string."
+        );
+    }
+
+    if (
+        /[\u0000-\u001F\u007F]/.test(
+            value
+        )
+    ) {
+        throw new Error(
+            "BCP Framework: cookie value contains invalid control characters."
+        );
+    }
+}
+
+function validateCookieAttribute(
+    value: string,
+    label: string
+): void {
+    if (
+        typeof value !==
+        "string" ||
+        value.length ===
+        0
+    ) {
+        throw new Error(
+            `BCP Framework: cookie ${label} must be a non-empty string.`
+        );
+    }
+
+    if (
+        /[\r\n;]/.test(
+            value
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: invalid cookie ${label}.`
+        );
+    }
+}
+
+function formatSameSite(
+    value:
+        CookieSameSite
+): string {
+    switch (value) {
+        case "strict":
+            return "Strict";
+
+        case "none":
+            return "None";
+
+        case "lax":
+            return "Lax";
+
+        default:
+            throw new Error(
+                `BCP Framework: invalid SameSite value "${String(
+                    value
+                )}".`
+            );
+    }
+}
+
+function decodeCookieValue(
+    value: string
+): string {
+    try {
+        return decodeURIComponent(
+            value
+        );
+    } catch {
+        return value;
+    }
+}