@chidchanun/bcp 0.1.24 → 0.1.26

package/packages/server/src/upload-stream.ts

@@ -0,0 +1,846 @@
+import {
+    randomUUID,
+} from "node:crypto";
+import {
+    createRequire,
+} from "node:module";
+import path from "node:path";
+import {
+    Readable,
+    type Writable,
+} from "node:stream";
+
+import {
+    UploadError,
+    type UploadConstraints,
+} from "./upload.js";
+import {
+    putStorageStream,
+    StorageError,
+    type StorageAdapter,
+    type StorageObjectMetadata,
+} from "./storage.js";
+
+const require =
+    createRequire(
+        import.meta.url
+    );
+
+interface BusboyFileInfo {
+    filename: string;
+    encoding: string;
+    mimeType: string;
+}
+
+type MultipartParser =
+    Writable & {
+        on(
+            event: "file",
+            listener:
+                (
+                    fieldName: string,
+                    file: Readable,
+                    info: BusboyFileInfo
+                ) => void
+        ): MultipartParser;
+    };
+
+type BusboyFactory =
+    (
+        options: {
+            headers:
+                Record<
+                    string,
+                    string
+                >;
+        }
+    ) => MultipartParser;
+
+const createBusboy =
+    require(
+        "busboy"
+    ) as BusboyFactory;
+
+export interface MultipartStorageFileInfo {
+    fieldName: string;
+    originalName: string;
+    encoding: string;
+    contentType: string;
+}
+
+export interface MultipartStorageUploadOptions {
+    storage: StorageAdapter;
+    fieldName: string;
+    key?:
+        | string
+        | (
+            (
+                file:
+                    MultipartStorageFileInfo
+            ) =>
+                | string
+                | Promise<string>
+        );
+    overwrite?: boolean;
+    maxBytes?: number;
+    constraints?: UploadConstraints;
+    signal?: AbortSignal;
+}
+
+export interface StoredMultipartFile
+extends StorageObjectMetadata,
+    MultipartStorageFileInfo {}
+
+export async function storeMultipartFile(
+    request: Request,
+    options:
+        MultipartStorageUploadOptions
+): Promise<StoredMultipartFile> {
+    const fieldName =
+        assertNonEmptyString(
+            options.fieldName,
+            "multipart fieldName"
+        );
+    const contentType =
+        request.headers.get(
+            "content-type"
+        ) ?? "";
+
+    if (
+        !contentType
+            .toLowerCase()
+            .startsWith(
+                "multipart/form-data"
+            )
+    ) {
+        throw new UploadError(
+            "INVALID_MULTIPART",
+            "BCP Framework: streaming upload request must use multipart/form-data.",
+            400
+        );
+    }
+
+    if (!request.body) {
+        throw new UploadError(
+            "INVALID_MULTIPART",
+            "BCP Framework: streaming multipart request body is missing.",
+            400
+        );
+    }
+
+    const maxRequestBytes =
+        normalizePositiveLimit(
+            options.maxBytes,
+            "maxBytes"
+        );
+    const contentLength =
+        readContentLength(
+            request.headers.get(
+                "content-length"
+            )
+        );
+
+    if (
+        maxRequestBytes !== null &&
+        contentLength !== null &&
+        contentLength >
+            maxRequestBytes
+    ) {
+        throw new UploadError(
+            "UPLOAD_TOO_LARGE",
+            `BCP Framework: multipart request exceeds the ${maxRequestBytes} byte upload limit.`,
+            413
+        );
+    }
+
+    let parser:
+        MultipartParser;
+
+    try {
+        parser =
+            createBusboy({
+                headers:
+                    Object.fromEntries(
+                        request.headers
+                            .entries()
+                    ),
+            });
+    } catch (error) {
+        throw new UploadError(
+            "INVALID_MULTIPART",
+            `BCP Framework: invalid multipart request (${errorMessage(
+                error
+            )}).`,
+            400
+        );
+    }
+
+    const uploadAbort =
+        new AbortController();
+    let targetSeen =
+        false;
+    const uploadState: {
+        current:
+            Promise<StoredMultipartFile> |
+            null;
+    } = {
+        current: null,
+    };
+    let primaryError:
+        unknown =
+        null;
+    let parserSettled =
+        false;
+
+    const recordFailure =
+        (error: unknown) => {
+            if (primaryError === null) {
+                primaryError =
+                    error;
+            }
+        };
+
+    const fail =
+        (error: unknown) => {
+            recordFailure(
+                error
+            );
+
+            if (
+                !uploadAbort.signal
+                    .aborted
+            ) {
+                uploadAbort.abort(
+                    error
+                );
+            }
+
+            if (
+                !parserSettled &&
+                !parser.destroyed
+            ) {
+                parser.destroy(
+                    asError(
+                        error
+                    )
+                );
+            }
+        };
+
+    const parserDone =
+        new Promise<void>(
+            (
+                resolve,
+                reject
+            ) => {
+                parser.once(
+                    "finish",
+                    () => {
+                        parserSettled =
+                            true;
+                        resolve();
+                    }
+                );
+                parser.once(
+                    "error",
+                    (error) => {
+                        parserSettled =
+                            true;
+                        reject(
+                            error
+                        );
+                    }
+                );
+            }
+        );
+
+    void parserDone.catch(
+        () => {
+            // The main flow awaits and reports parser failures.
+        }
+    );
+
+    parser.on(
+        "file",
+        (
+            incomingField,
+            file,
+            info
+        ) => {
+            if (
+                incomingField !==
+                fieldName
+            ) {
+                file.resume();
+                return;
+            }
+
+            if (targetSeen) {
+                file.resume();
+                fail(
+                    new UploadError(
+                        "INVALID_MULTIPART",
+                        `BCP Framework: multipart field "${fieldName}" must contain only one streamed file.`,
+                        400
+                    )
+                );
+                return;
+            }
+
+            targetSeen =
+                true;
+
+            let fileInfo:
+                MultipartStorageFileInfo;
+
+            try {
+                fileInfo =
+                    createFileInfo(
+                        incomingField,
+                        info,
+                        options.constraints
+                    );
+            } catch (error) {
+                recordFailure(
+                    error
+                );
+                file.resume();
+                return;
+            }
+
+            uploadState.current =
+                (async () => {
+                    const key =
+                        await resolveStorageKey(
+                            options.key,
+                            fileInfo
+                        );
+                    const stream =
+                        Readable.toWeb(
+                            file
+                        ) as ReadableStream<
+                            Uint8Array
+                        >;
+
+                    try {
+                        const metadata =
+                            await putStorageStream(
+                                options.storage,
+                                key,
+                                stream,
+                                {
+                                    overwrite:
+                                        options.overwrite,
+                                    contentType:
+                                        fileInfo.contentType,
+                                    maxBytes:
+                                        normalizePositiveLimit(
+                                            options.constraints
+                                                ?.maxBytes,
+                                            "file maxBytes"
+                                        ) ??
+                                        undefined,
+                                    signal:
+                                        uploadAbort.signal,
+                                }
+                            );
+
+                        return {
+                            ...metadata,
+                            ...fileInfo,
+                        };
+                    } catch (error) {
+                        const mapped =
+                            mapStorageUploadError(
+                                error,
+                                fileInfo.originalName,
+                                key
+                            );
+                        fail(
+                            mapped
+                        );
+                        throw mapped;
+                    }
+                })();
+
+            void uploadState.current.catch(
+                () => {
+                    // The main flow awaits and reports this failure.
+                }
+            );
+        }
+    );
+
+    const onCallerAbort =
+        () => {
+            fail(
+                options.signal
+                    ?.reason ??
+                    new Error(
+                        "BCP Framework: streaming multipart upload was aborted."
+                    )
+            );
+        };
+
+    options.signal
+        ?.addEventListener(
+            "abort",
+            onCallerAbort,
+            {
+                once: true,
+            }
+        );
+
+    try {
+        options.signal
+            ?.throwIfAborted();
+
+        await pumpRequestBody(
+            request.body,
+            parser,
+            maxRequestBytes
+        );
+        await parserDone;
+
+        if (primaryError !== null) {
+            throw primaryError;
+        }
+
+        const uploadPromise =
+            uploadState.current;
+
+        if (
+            !targetSeen ||
+            uploadPromise === null
+        ) {
+            throw new UploadError(
+                "FILE_REQUIRED",
+                `BCP Framework: upload field "${fieldName}" must contain a file.`,
+                400
+            );
+        }
+
+        return await uploadPromise;
+    } catch (error) {
+        fail(
+            error
+        );
+
+        const uploadPromise =
+            uploadState.current;
+
+        if (uploadPromise !== null) {
+            await uploadPromise.catch(
+                () => {
+                    // Preserve the primary parser/upload error.
+                }
+            );
+        }
+
+        throw primaryError ??
+            error;
+    } finally {
+        options.signal
+            ?.removeEventListener(
+                "abort",
+                onCallerAbort
+            );
+    }
+}
+
+async function pumpRequestBody(
+    body:
+        ReadableStream<Uint8Array>,
+    parser: MultipartParser,
+    maxBytes: number | null
+): Promise<void> {
+    const reader =
+        body.getReader();
+    let totalBytes =
+        0;
+
+    try {
+        while (true) {
+            const result =
+                await reader.read();
+
+            if (result.done) {
+                break;
+            }
+
+            const nextTotal =
+                totalBytes +
+                result.value.byteLength;
+
+            if (
+                maxBytes !== null &&
+                nextTotal > maxBytes
+            ) {
+                throw new UploadError(
+                    "UPLOAD_TOO_LARGE",
+                    `BCP Framework: multipart payload exceeds the ${maxBytes} byte upload limit.`,
+                    413
+                );
+            }
+
+            totalBytes =
+                nextTotal;
+
+            if (
+                !parser.write(
+                    Buffer.from(
+                        result.value
+                    )
+                )
+            ) {
+                await waitForDrain(
+                    parser
+                );
+            }
+        }
+
+        parser.end();
+    } catch (error) {
+        try {
+            await reader.cancel(
+                error
+            );
+        } catch {
+            // Preserve the parser/upload failure.
+        }
+
+        throw error;
+    } finally {
+        reader.releaseLock();
+    }
+}
+
+function waitForDrain(
+    parser: MultipartParser
+): Promise<void> {
+    return new Promise<void>(
+        (
+            resolve,
+            reject
+        ) => {
+            const cleanup =
+                () => {
+                    parser.off(
+                        "drain",
+                        onDrain
+                    );
+                    parser.off(
+                        "error",
+                        onError
+                    );
+                };
+            const onDrain =
+                () => {
+                    cleanup();
+                    resolve();
+                };
+            const onError =
+                (error: Error) => {
+                    cleanup();
+                    reject(
+                        error
+                    );
+                };
+
+            parser.once(
+                "drain",
+                onDrain
+            );
+            parser.once(
+                "error",
+                onError
+            );
+        }
+    );
+}
+
+function createFileInfo(
+    fieldName: string,
+    info: BusboyFileInfo,
+    constraints:
+        UploadConstraints |
+        undefined
+): MultipartStorageFileInfo {
+    const originalName =
+        path.basename(
+            String(
+                info.filename ??
+                ""
+            ).replace(
+                /\\/g,
+                "/"
+            )
+        );
+
+    if (
+        originalName.length === 0 ||
+        originalName === "." ||
+        originalName === ".."
+    ) {
+        throw new UploadError(
+            "INVALID_FILE_NAME",
+            "BCP Framework: streamed upload file name is invalid.",
+            400
+        );
+    }
+
+    const contentType =
+        String(
+            info.mimeType ??
+            ""
+        )
+            .trim()
+            .toLowerCase() ||
+        "application/octet-stream";
+
+    if (
+        constraints?.allowedTypes &&
+        constraints.allowedTypes.length >
+            0
+    ) {
+        const allowedTypes =
+            constraints.allowedTypes.map(
+                (value) =>
+                    value
+                        .trim()
+                        .toLowerCase()
+            );
+
+        if (
+            !allowedTypes.includes(
+                contentType
+            )
+        ) {
+            throw new UploadError(
+                "FILE_TYPE_NOT_ALLOWED",
+                `BCP Framework: file type "${contentType}" is not allowed for "${originalName}".`,
+                415
+            );
+        }
+    }
+
+    if (
+        constraints?.allowedExtensions &&
+        constraints.allowedExtensions.length >
+            0
+    ) {
+        const extension =
+            path.extname(
+                originalName
+            ).toLowerCase();
+        const allowedExtensions =
+            constraints.allowedExtensions.map(
+                normalizeExtension
+            );
+
+        if (
+            !allowedExtensions.includes(
+                extension
+            )
+        ) {
+            throw new UploadError(
+                "FILE_EXTENSION_NOT_ALLOWED",
+                `BCP Framework: file extension "${extension || "(none)"}" is not allowed for "${originalName}".`,
+                415
+            );
+        }
+    }
+
+    return {
+        fieldName,
+        originalName,
+        encoding:
+            String(
+                info.encoding ??
+                ""
+            ),
+        contentType,
+    };
+}
+
+async function resolveStorageKey(
+    value:
+        MultipartStorageUploadOptions[
+            "key"
+        ],
+    file:
+        MultipartStorageFileInfo
+): Promise<string> {
+    if (
+        typeof value ===
+        "function"
+    ) {
+        return value(
+            file
+        );
+    }
+
+    if (
+        typeof value ===
+            "string"
+    ) {
+        return value;
+    }
+
+    const extension =
+        path.extname(
+            file.originalName
+        )
+            .toLowerCase()
+            .replace(
+                /[^.a-z0-9]/g,
+                ""
+            )
+            .slice(
+                0,
+                16
+            );
+
+    return `${randomUUID()}${extension}`;
+}
+
+function mapStorageUploadError(
+    error: unknown,
+    originalName: string,
+    key: string
+): unknown {
+    if (
+        !(error instanceof
+            StorageError)
+    ) {
+        return error;
+    }
+
+    if (
+        error.code ===
+            "STREAM_TOO_LARGE"
+    ) {
+        return new UploadError(
+            "FILE_TOO_LARGE",
+            `BCP Framework: file "${originalName}" exceeded the configured streaming file limit.`,
+            413
+        );
+    }
+
+    if (
+        error.code ===
+            "OBJECT_EXISTS"
+    ) {
+        return new UploadError(
+            "FILE_EXISTS",
+            `BCP Framework: upload storage key "${key}" already exists.`,
+            409
+        );
+    }
+
+    return error;
+}
+
+function normalizePositiveLimit(
+    value: number | undefined,
+    label: string
+): number | null {
+    if (value === undefined) {
+        return null;
+    }
+
+    if (
+        !Number.isSafeInteger(
+            value
+        ) ||
+        value <= 0
+    ) {
+        throw new TypeError(
+            `BCP Framework: streaming upload ${label} must be a positive safe integer.`
+        );
+    }
+
+    return value;
+}
+
+function readContentLength(
+    value: string | null
+): number | null {
+    if (!value) {
+        return null;
+    }
+
+    if (!/^\d+$/.test(value)) {
+        return null;
+    }
+
+    const parsed =
+        Number(
+            value
+        );
+
+    return Number.isSafeInteger(
+        parsed
+    )
+        ? parsed
+        : null;
+}
+
+function normalizeExtension(
+    value: string
+): string {
+    const normalized =
+        value
+            .trim()
+            .toLowerCase();
+
+    if (normalized.length === 0) {
+        return normalized;
+    }
+
+    return normalized.startsWith(
+        "."
+    )
+        ? normalized
+        : `.${normalized}`;
+}
+
+function assertNonEmptyString(
+    value: string,
+    label: string
+): string {
+    if (
+        typeof value !== "string" ||
+        value.trim().length === 0
+    ) {
+        throw new TypeError(
+            `BCP Framework: ${label} must be a non-empty string.`
+        );
+    }
+
+    return value.trim();
+}
+
+function asError(
+    value: unknown
+): Error {
+    if (value instanceof Error) {
+        return value;
+    }
+
+    return new Error(
+        errorMessage(
+            value
+        )
+    );
+}
+
+function errorMessage(
+    value: unknown
+): string {
+    return value instanceof Error
+        ? value.message
+        : String(
+            value
+        );
+}