@chidchanun/bcp 0.1.23 → 0.1.25

package/packages/server/src/storage.ts

@@ -0,0 +1,829 @@
+import {
+    createHash,
+    randomUUID,
+} from "node:crypto";
+import {
+    mkdir,
+    open,
+    readFile,
+    rm,
+    stat,
+    unlink,
+    writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+import {
+    validateUploadedFile,
+    type UploadConstraints,
+} from "./upload.js";
+
+const METADATA_DIRECTORY =
+    ".bcp-storage-meta";
+
+export type StorageErrorCode =
+    | "INVALID_KEY"
+    | "OBJECT_NOT_FOUND"
+    | "OBJECT_EXISTS"
+    | "RANGE_NOT_SATISFIABLE";
+
+export class StorageError extends Error {
+    readonly code:
+        StorageErrorCode;
+    readonly status:
+        number;
+
+    constructor(
+        code: StorageErrorCode,
+        message: string,
+        status: number
+    ) {
+        super(message);
+        this.name =
+            "StorageError";
+        this.code =
+            code;
+        this.status =
+            status;
+    }
+}
+
+export interface StorageObjectMetadata {
+    key: string;
+    size: number;
+    contentType: string;
+    lastModified: Date;
+    etag: string;
+    checksumSha256?: string;
+}
+
+export interface StoragePutOptions {
+    contentType?: string;
+    overwrite?: boolean;
+}
+
+export interface StorageReadOptions {
+    start?: number;
+    end?: number;
+}
+
+export interface StorageAdapter {
+    put(
+        key: string,
+        value: StorageWriteValue,
+        options?: StoragePutOptions
+    ): Promise<StorageObjectMetadata>;
+
+    stat(
+        key: string
+    ): Promise<StorageObjectMetadata | null>;
+
+    read(
+        key: string,
+        options?: StorageReadOptions
+    ): Promise<Uint8Array>;
+
+    exists(
+        key: string
+    ): Promise<boolean>;
+
+    delete(
+        key: string
+    ): Promise<boolean>;
+}
+
+export type StorageWriteValue =
+    | string
+    | Blob
+    | ArrayBuffer
+    | ArrayBufferView;
+
+export interface LocalStorageOptions {
+    directory: string;
+}
+
+export interface StoreUploadedFileOptions {
+    storage: StorageAdapter;
+    key?: string;
+    overwrite?: boolean;
+    constraints?: UploadConstraints;
+}
+
+export interface StoredUploadedObject
+extends StorageObjectMetadata {
+    originalName: string;
+}
+
+interface LocalMetadataRecord {
+    version: 1;
+    key: string;
+    contentType: string;
+    checksumSha256: string;
+}
+
+export function createLocalStorage(
+    options: LocalStorageOptions
+): StorageAdapter {
+    const rootDirectory =
+        path.resolve(
+            assertNonEmptyString(
+                options.directory,
+                "directory"
+            )
+        );
+    const metadataDirectory =
+        path.join(
+            rootDirectory,
+            METADATA_DIRECTORY
+        );
+
+    return {
+        async put(
+            key,
+            value,
+            putOptions = {}
+        ) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+            const bytes =
+                await toStorageBytes(
+                    value
+                );
+            const checksumSha256 =
+                createHash(
+                    "sha256"
+                )
+                    .update(bytes)
+                    .digest("hex");
+            const contentType =
+                normalizeContentType(
+                    putOptions.contentType ??
+                    (
+                        value instanceof Blob
+                            ? value.type
+                            : ""
+                    )
+                );
+
+            await mkdir(
+                path.dirname(
+                    destination
+                ),
+                {
+                    recursive: true,
+                }
+            );
+
+            try {
+                await writeFile(
+                    destination,
+                    bytes,
+                    {
+                        flag:
+                            putOptions.overwrite
+                                ? "w"
+                                : "wx",
+                    }
+                );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "EEXIST"
+                    )
+                ) {
+                    throw new StorageError(
+                        "OBJECT_EXISTS",
+                        `BCP Framework: storage object "${normalizedKey}" already exists.`,
+                        409
+                    );
+                }
+
+                throw error;
+            }
+
+            await writeMetadataRecord(
+                metadataDirectory,
+                {
+                    version: 1,
+                    key:
+                        normalizedKey,
+                    contentType,
+                    checksumSha256,
+                }
+            );
+
+            const fileStat =
+                await stat(
+                    destination
+                );
+
+            return createObjectMetadata(
+                normalizedKey,
+                fileStat.size,
+                fileStat.mtime,
+                contentType,
+                checksumSha256
+            );
+        },
+
+        async stat(key) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+
+            let fileStat;
+
+            try {
+                fileStat =
+                    await stat(
+                        destination
+                    );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "ENOENT"
+                    )
+                ) {
+                    return null;
+                }
+
+                throw error;
+            }
+
+            if (!fileStat.isFile()) {
+                return null;
+            }
+
+            const record =
+                await readMetadataRecord(
+                    metadataDirectory,
+                    normalizedKey
+                );
+
+            return createObjectMetadata(
+                normalizedKey,
+                fileStat.size,
+                fileStat.mtime,
+                record?.contentType ??
+                    "application/octet-stream",
+                record?.checksumSha256
+            );
+        },
+
+        async read(
+            key,
+            readOptions = {}
+        ) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+            const metadata =
+                await this.stat(
+                    normalizedKey
+                );
+
+            if (!metadata) {
+                throw new StorageError(
+                    "OBJECT_NOT_FOUND",
+                    `BCP Framework: storage object "${normalizedKey}" was not found.`,
+                    404
+                );
+            }
+
+            const range =
+                normalizeReadRange(
+                    metadata.size,
+                    readOptions
+                );
+
+            if (!range) {
+                return Uint8Array.from(
+                    await readFile(
+                        destination
+                    )
+                );
+            }
+
+            const length =
+                range.end -
+                range.start +
+                1;
+            const handle =
+                await open(
+                    destination,
+                    "r"
+                );
+
+            try {
+                const buffer =
+                    Buffer.allocUnsafe(
+                        length
+                    );
+                const result =
+                    await handle.read(
+                        buffer,
+                        0,
+                        length,
+                        range.start
+                    );
+
+                return Uint8Array.from(
+                    buffer.subarray(
+                        0,
+                        result.bytesRead
+                    )
+                );
+            } finally {
+                await handle.close();
+            }
+        },
+
+        async exists(key) {
+            return (
+                await this.stat(
+                    key
+                )
+            ) !== null;
+        },
+
+        async delete(key) {
+            const normalizedKey =
+                normalizeStorageKey(
+                    key
+                );
+            const destination =
+                resolveStoragePath(
+                    rootDirectory,
+                    normalizedKey
+                );
+
+            try {
+                await unlink(
+                    destination
+                );
+            } catch (error) {
+                if (
+                    isNodeErrorCode(
+                        error,
+                        "ENOENT"
+                    )
+                ) {
+                    return false;
+                }
+
+                throw error;
+            }
+
+            await rm(
+                metadataFilePath(
+                    metadataDirectory,
+                    normalizedKey
+                ),
+                {
+                    force: true,
+                }
+            );
+
+            return true;
+        },
+    };
+}
+
+export async function storeUploadedFile(
+    file: File,
+    options: StoreUploadedFileOptions
+): Promise<StoredUploadedObject> {
+    validateUploadedFile(
+        file,
+        options.constraints
+    );
+
+    const key =
+        options.key === undefined
+            ? createUploadStorageKey(
+                file.name
+            )
+            : normalizeStorageKey(
+                options.key
+            );
+    const metadata =
+        await options.storage.put(
+            key,
+            file,
+            {
+                overwrite:
+                    options.overwrite,
+                contentType:
+                    file.type ||
+                    "application/octet-stream",
+            }
+        );
+
+    return {
+        ...metadata,
+        originalName:
+            file.name,
+    };
+}
+
+export function normalizeStorageKey(
+    value: string
+): string {
+    if (
+        typeof value !== "string" ||
+        value.trim().length === 0
+    ) {
+        throw new StorageError(
+            "INVALID_KEY",
+            "BCP Framework: storage key must be a non-empty relative path.",
+            400
+        );
+    }
+
+    const normalized =
+        value
+            .replace(
+                /\\/g,
+                "/"
+            )
+            .replace(
+                /^\/+|\/+$/g,
+                ""
+            );
+    const segments =
+        normalized.split("/");
+
+    if (
+        normalized.length === 0 ||
+        path.isAbsolute(
+            value
+        ) ||
+        segments.some(
+            (segment) =>
+                segment.length === 0 ||
+                segment === "." ||
+                segment === ".." ||
+                /[\u0000-\u001F\u007F]/.test(
+                    segment
+                )
+        ) ||
+        segments[0] ===
+            METADATA_DIRECTORY
+    ) {
+        throw new StorageError(
+            "INVALID_KEY",
+            `BCP Framework: invalid storage key "${value}".`,
+            400
+        );
+    }
+
+    return segments.join("/");
+}
+
+function resolveStoragePath(
+    rootDirectory: string,
+    key: string
+): string {
+    const destination =
+        path.resolve(
+            rootDirectory,
+            ...key.split("/")
+        );
+    const relative =
+        path.relative(
+            rootDirectory,
+            destination
+        );
+
+    if (
+        relative === "" ||
+        relative.startsWith("..") ||
+        path.isAbsolute(
+            relative
+        )
+    ) {
+        throw new StorageError(
+            "INVALID_KEY",
+            `BCP Framework: storage key "${key}" escapes the configured storage directory.`,
+            400
+        );
+    }
+
+    return destination;
+}
+
+async function toStorageBytes(
+    value: StorageWriteValue
+): Promise<Uint8Array> {
+    if (
+        typeof value ===
+        "string"
+    ) {
+        return Uint8Array.from(
+            Buffer.from(
+                value,
+                "utf8"
+            )
+        );
+    }
+
+    if (
+        value instanceof Blob
+    ) {
+        return new Uint8Array(
+            await value.arrayBuffer()
+        );
+    }
+
+    if (
+        value instanceof ArrayBuffer
+    ) {
+        return new Uint8Array(
+            value
+        );
+    }
+
+    if (
+        ArrayBuffer.isView(
+            value
+        )
+    ) {
+        return Uint8Array.from(
+            new Uint8Array(
+                value.buffer,
+                value.byteOffset,
+                value.byteLength
+            )
+        );
+    }
+
+    throw new TypeError(
+        "BCP Framework: unsupported storage write value."
+    );
+}
+
+function normalizeReadRange(
+    size: number,
+    options: StorageReadOptions
+): {
+    start: number;
+    end: number;
+} | null {
+    if (
+        options.start === undefined &&
+        options.end === undefined
+    ) {
+        return null;
+    }
+
+    const start =
+        options.start ??
+        0;
+    const end =
+        options.end ??
+        size - 1;
+
+    if (
+        !Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(end) ||
+        start < 0 ||
+        end < start ||
+        start >= size ||
+        end >= size
+    ) {
+        throw new StorageError(
+            "RANGE_NOT_SATISFIABLE",
+            `BCP Framework: requested storage range ${start}-${end} is invalid for ${size} bytes.`,
+            416
+        );
+    }
+
+    return {
+        start,
+        end,
+    };
+}
+
+function createObjectMetadata(
+    key: string,
+    size: number,
+    lastModified: Date,
+    contentType: string,
+    checksumSha256?: string
+): StorageObjectMetadata {
+    const etag =
+        checksumSha256
+            ? `"sha256-${checksumSha256}"`
+            : `W/"${size}-${Math.trunc(
+                lastModified.getTime()
+            )}"`;
+
+    return {
+        key,
+        size,
+        contentType:
+            normalizeContentType(
+                contentType
+            ),
+        lastModified:
+            new Date(
+                lastModified.getTime()
+            ),
+        etag,
+        ...(checksumSha256
+            ? {
+                checksumSha256,
+            }
+            : {}),
+    };
+}
+
+async function writeMetadataRecord(
+    metadataDirectory: string,
+    record: LocalMetadataRecord
+): Promise<void> {
+    await mkdir(
+        metadataDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    await writeFile(
+        metadataFilePath(
+            metadataDirectory,
+            record.key
+        ),
+        JSON.stringify(
+            record
+        ),
+        "utf8"
+    );
+}
+
+async function readMetadataRecord(
+    metadataDirectory: string,
+    key: string
+): Promise<LocalMetadataRecord | null> {
+    try {
+        const raw =
+            await readFile(
+                metadataFilePath(
+                    metadataDirectory,
+                    key
+                ),
+                "utf8"
+            );
+        const parsed =
+            JSON.parse(
+                raw
+            ) as Partial<
+                LocalMetadataRecord
+            >;
+
+        if (
+            parsed.version !== 1 ||
+            parsed.key !== key ||
+            typeof parsed.contentType !==
+                "string" ||
+            typeof parsed.checksumSha256 !==
+                "string"
+        ) {
+            return null;
+        }
+
+        return {
+            version: 1,
+            key,
+            contentType:
+                parsed.contentType,
+            checksumSha256:
+                parsed.checksumSha256,
+        };
+    } catch (error) {
+        if (
+            isNodeErrorCode(
+                error,
+                "ENOENT"
+            ) ||
+            error instanceof SyntaxError
+        ) {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
+function metadataFilePath(
+    metadataDirectory: string,
+    key: string
+): string {
+    const digest =
+        createHash(
+            "sha256"
+        )
+            .update(
+                key
+            )
+            .digest(
+                "hex"
+            );
+
+    return path.join(
+        metadataDirectory,
+        `${digest}.json`
+    );
+}
+
+function createUploadStorageKey(
+    originalName: string
+): string {
+    const extension =
+        path.extname(
+            originalName
+        )
+            .toLowerCase()
+            .replace(
+                /[^.a-z0-9]/g,
+                ""
+            )
+            .slice(
+                0,
+                16
+            );
+
+    return `${randomUUID()}${extension}`;
+}
+
+function normalizeContentType(
+    value: string
+): string {
+    const normalized =
+        value
+            .trim()
+            .toLowerCase();
+
+    if (
+        normalized.length === 0 ||
+        /[\r\n]/.test(
+            normalized
+        )
+    ) {
+        return "application/octet-stream";
+    }
+
+    return normalized;
+}
+
+function assertNonEmptyString(
+    value: string,
+    label: string
+): string {
+    if (
+        typeof value !== "string" ||
+        value.trim().length === 0
+    ) {
+        throw new TypeError(
+            `BCP Framework: storage ${label} must be a non-empty string.`
+        );
+    }
+
+    return value;
+}
+
+function isNodeErrorCode(
+    error: unknown,
+    code: string
+): boolean {
+    return (
+        error instanceof Error &&
+        "code" in error &&
+        (
+            error as Error & {
+                code?: string;
+            }
+        ).code === code
+    );
+}