@gencow/core 0.1.24 → 0.1.25

package/src/storage.ts

@@ -12,40 +12,40 @@ const MAX_FILE_SIZE = 50 * 1024 * 1024;
 const DEFAULT_STORAGE_QUOTA = 1024 * 1024 * 1024;
 
 function formatBytes(bytes: number): string {
-    if (bytes < 1024) return `${bytes}B`;
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-    if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
 }
 
 // ─── Types ──────────────────────────────────────────────
 
 interface StorageFile {
-    id: string;
-    name: string;
-    size: number;
-    type: string;
-    path: string;
+  id: string;
+  name: string;
+  size: number;
+  type: string;
+  path: string;
 }
 
 export interface StorageOptions {
-    /** Raw SQL 실행 함수 — DB 자동 기록 + 쿼터 검증에 필요 */
-    rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>;
-    /** 앱별 스토리지 쿼터 (bytes). 0 = 무제한. 기본: 1GB */
-    storageQuota?: number;
+  /** Raw SQL 실행 함수 — DB 자동 기록 + 쿼터 검증에 필요 */
+  rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+  /** 앱별 스토리지 쿼터 (bytes). 0 = 무제한. 기본: 1GB */
+  storageQuota?: number;
 }
 
 export interface Storage {
-    /** Store a file and return a storageId — Convex의 ctx.storage.store() */
-    store(file: File | Blob, filename?: string): Promise<string>;
-    /** Store from raw buffer */
-    storeBuffer(buffer: Buffer, filename: string, type?: string): Promise<string>;
-    /** Get a serving URL for the file — Convex의 ctx.storage.getUrl() */
-    getUrl(storageId: string): string;
-    /** Get file metadata */
-    getMeta(storageId: string): Promise<StorageFile | null>;
-    /** Delete a stored file — Convex의 ctx.storage.delete() */
-    delete(storageId: string): Promise<void>;
+  /** Store a file and return a storageId — Convex의 ctx.storage.store() */
+  store(file: File | Blob, filename?: string): Promise<string>;
+  /** Store from raw buffer */
+  storeBuffer(buffer: Buffer, filename: string, type?: string): Promise<string>;
+  /** Get a serving URL for the file — Convex의 ctx.storage.getUrl() */
+  getUrl(storageId: string): string;
+  /** Get file metadata */
+  getMeta(storageId: string): Promise<StorageFile | null>;
+  /** Delete a stored file — Convex의 ctx.storage.delete() */
+  delete(storageId: string): Promise<void>;
 }
 
 // ─── Implementation ─────────────────────────────────────
@@ -60,10 +60,10 @@ const metaStore = new Map<string, StorageFile>();
 let filesTableEnsured = false;
 
 async function ensureFilesTable(
-    rawSql: (sql: string, params?: unknown[]) => Promise<unknown[]>,
+  rawSql: (sql: string, params?: unknown[]) => Promise<unknown[]>,
 ): Promise<void> {
-    if (filesTableEnsured) return;
-    await rawSql(`
+  if (filesTableEnsured) return;
+  await rawSql(`
         DO $$
         BEGIN
             IF NOT EXISTS (
@@ -83,31 +83,29 @@ async function ensureFilesTable(
             END IF;
         END$$;
     `);
-    filesTableEnsured = true;
+  filesTableEnsured = true;
 }
 
 /**
  * 스토리지 쿼터 검증 — 현재 총 사용량 + 새 파일 크기가 쿼터를 초과하는지 확인
  */
 async function checkStorageQuota(
-    rawSql: (sql: string, params?: unknown[]) => Promise<unknown[]>,
-    newFileSize: number,
-    quota: number,
+  rawSql: (sql: string, params?: unknown[]) => Promise<unknown[]>,
+  newFileSize: number,
+  quota: number,
 ): Promise<void> {
-    if (quota <= 0) return; // 무제한
+  if (quota <= 0) return; // 무제한
 
-    const rows = await rawSql(
-        `SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM _system_files`,
-    );
-    const currentUsage = Number((rows[0] as Record<string, string>)?.total || "0");
-    const projectedUsage = currentUsage + newFileSize;
+  const rows = await rawSql(`SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM _system_files`);
+  const currentUsage = Number((rows[0] as Record<string, string>)?.total || "0");
+  const projectedUsage = currentUsage + newFileSize;
 
-    if (projectedUsage > quota) {
-        throw new Error(
-            `Storage quota exceeded: ${formatBytes(currentUsage)} used + ${formatBytes(newFileSize)} new = ${formatBytes(projectedUsage)}, ` +
-            `quota is ${formatBytes(quota)}. Delete files or increase quota.`
-        );
-    }
+  if (projectedUsage > quota) {
+    throw new Error(
+      `Storage quota exceeded: ${formatBytes(currentUsage)} used + ${formatBytes(newFileSize)} new = ${formatBytes(projectedUsage)}, ` +
+        `quota is ${formatBytes(quota)}. Delete files or increase quota.`,
+    );
+  }
 }
 
 /**
@@ -117,19 +115,19 @@ async function checkStorageQuota(
  * 여기서는 skipDbRecord 옵션으로 중복 방지 가능.
  */
 async function recordFileToDb(
-    rawSql: (sql: string, params?: unknown[]) => Promise<unknown[]>,
-    storageId: string,
-    name: string,
-    size: number,
-    type: string,
-    uploadedBy: string = "api",
+  rawSql: (sql: string, params?: unknown[]) => Promise<unknown[]>,
+  storageId: string,
+  name: string,
+  size: number,
+  type: string,
+  uploadedBy: string = "api",
 ): Promise<void> {
-    await ensureFilesTable(rawSql);
-    await rawSql(
-        `INSERT INTO _system_files (storage_id, name, size, type, uploaded_by, created_at)
+  await ensureFilesTable(rawSql);
+  await rawSql(
+    `INSERT INTO _system_files (storage_id, name, size, type, uploaded_by, created_at)
          VALUES ($1, $2, $3, $4, $5, NOW())`,
-        [storageId, name, String(size), type, uploadedBy],
-    );
+    [storageId, name, String(size), type, uploadedBy],
+  );
 }
 
 /**
@@ -143,194 +141,192 @@ async function recordFileToDb(
  * const id = await storage.store(file);
  * const url = storage.getUrl(id);
  */
-export function createStorage(
-    dir: string = "./uploads",
-    options?: StorageOptions,
-): Storage {
-    const rawSql = options?.rawSql;
-    const quota = options?.storageQuota ?? DEFAULT_STORAGE_QUOTA;
-
-    // Ensure directory exists
-    fs.mkdir(dir, { recursive: true }).catch(() => { });
-
-    return {
-        async store(file: File | Blob, filename?: string): Promise<string> {
-            // 크기 제한 검증 (단일 파일)
-            if (file.size > MAX_FILE_SIZE) {
-                throw new Error(
-                    `File too large: ${formatBytes(file.size)} exceeds limit of ${formatBytes(MAX_FILE_SIZE)}`
-                );
-            }
-
-            // 스토리지 쿼터 검증 (앱 전체 용량)
-            if (rawSql) {
-                await checkStorageQuota(rawSql, file.size, quota);
-            }
-
-            const id = crypto.randomUUID();
-            const name = filename || (file instanceof File ? file.name : `${id}.bin`);
-            const filePath = path.join(dir, id);
-
-            const arrayBuffer = await file.arrayBuffer();
-            await fs.writeFile(filePath, Buffer.from(arrayBuffer));
-
-            const type = file.type || "application/octet-stream";
-
-            // .meta JSON 기록 — Platform 레벨 직접 서빙용 (앱 DB 접근 불필요)
-            await fs.writeFile(`${filePath}.meta`, JSON.stringify({ name, type, size: file.size })).catch(() => {});
-
-            metaStore.set(id, {
-                id,
-                name,
-                size: file.size,
-                type,
-                path: filePath,
-            });
-
-            // DB 자동 기록 (rawSql 있을 때만)
-            if (rawSql) {
-                try {
-                    await recordFileToDb(rawSql, id, name, file.size, type, "api");
-                } catch (e: unknown) {
-                    // DB 기록 실패해도 파일 저장은 성공 — 로그만 남김
-                    const msg = e instanceof Error ? e.message : String(e);
-                    console.warn(`[storage] DB record failed for ${id}: ${msg}`);
-                }
-            }
-
-            return id;
-        },
-
-        async storeBuffer(
-            buffer: Buffer,
-            filename: string,
-            type: string = "application/octet-stream"
-        ): Promise<string> {
-            // 크기 제한 검증 (단일 파일)
-            if (buffer.length > MAX_FILE_SIZE) {
-                throw new Error(
-                    `File too large: ${formatBytes(buffer.length)} exceeds limit of ${formatBytes(MAX_FILE_SIZE)}`
-                );
-            }
-
-            // 스토리지 쿼터 검증 (앱 전체 용량)
-            if (rawSql) {
-                await checkStorageQuota(rawSql, buffer.length, quota);
-            }
-
-            const id = crypto.randomUUID();
-            const filePath = path.join(dir, id);
-
-            await fs.writeFile(filePath, buffer);
-
-            // .meta JSON 기록 — Platform 레벨 직접 서빙용
-            await fs.writeFile(`${filePath}.meta`, JSON.stringify({ name: filename, type, size: buffer.length })).catch(() => {});
-
-            metaStore.set(id, {
-                id,
-                name: filename,
-                size: buffer.length,
-                type,
-                path: filePath,
-            });
-
-            // DB 자동 기록
-            if (rawSql) {
-                try {
-                    await recordFileToDb(rawSql, id, filename, buffer.length, type, "api");
-                } catch (e: unknown) {
-                    const msg = e instanceof Error ? e.message : String(e);
-                    console.warn(`[storage] DB record failed for ${id}: ${msg}`);
-                }
-            }
-
-            return id;
-        },
-
-        getUrl(storageId: string): string {
-            return `/api/storage/${storageId}`;
-        },
-
-        async getMeta(storageId: string): Promise<StorageFile | null> {
-            return metaStore.get(storageId) || null;
-        },
-
-        async delete(storageId: string): Promise<void> {
-            const meta = metaStore.get(storageId);
-            if (meta) {
-                await fs.unlink(meta.path).catch(() => { });
-                // .meta JSON 동시 삭제
-                await fs.unlink(`${meta.path}.meta`).catch(() => { });
-                metaStore.delete(storageId);
-            } else {
-                // metaStore에 없어도 디스크에서 직접 삭제 시도
-                const filePath = path.join(dir, storageId);
-                await fs.unlink(filePath).catch(() => { });
-                await fs.unlink(`${filePath}.meta`).catch(() => { });
-            }
-
-            // 이미지 캐시 삭제 — uploads/.cache/{storageId}_* glob
-            const cacheDir = path.join(dir, ".cache");
-            try {
-                const entries = await fs.readdir(cacheDir);
-                const prefix = `${storageId}_`;
-                await Promise.all(
-                    entries
-                        .filter(e => e.startsWith(prefix))
-                        .map(e => fs.unlink(path.join(cacheDir, e)).catch(() => { }))
-                );
-            } catch { /* .cache 디렉토리 미존재 시 무시 */ }
-
-            // DB에서도 삭제 (rawSql 있을 때만)
-            if (rawSql) {
-                try {
-                    await rawSql(
-                        `DELETE FROM _system_files WHERE storage_id = $1`,
-                        [storageId],
-                    );
-                } catch { /* 삭제 실패 무시 — 파일은 이미 제거됨 */ }
-            }
-        },
-    };
+export function createStorage(dir: string = "./uploads", options?: StorageOptions): Storage {
+  const rawSql = options?.rawSql;
+  const quota = options?.storageQuota ?? DEFAULT_STORAGE_QUOTA;
+
+  // Ensure directory exists
+  fs.mkdir(dir, { recursive: true }).catch(() => {});
+
+  return {
+    async store(file: File | Blob, filename?: string): Promise<string> {
+      // 크기 제한 검증 (단일 파일)
+      if (file.size > MAX_FILE_SIZE) {
+        throw new Error(
+          `File too large: ${formatBytes(file.size)} exceeds limit of ${formatBytes(MAX_FILE_SIZE)}`,
+        );
+      }
+
+      // 스토리지 쿼터 검증 (앱 전체 용량)
+      if (rawSql) {
+        await checkStorageQuota(rawSql, file.size, quota);
+      }
+
+      const id = crypto.randomUUID();
+      const name = filename || (file instanceof File ? file.name : `${id}.bin`);
+      const filePath = path.join(dir, id);
+
+      const arrayBuffer = await file.arrayBuffer();
+      await fs.writeFile(filePath, Buffer.from(arrayBuffer));
+
+      const type = file.type || "application/octet-stream";
+
+      // .meta JSON 기록 — Platform 레벨 직접 서빙용 (앱 DB 접근 불필요)
+      await fs.writeFile(`${filePath}.meta`, JSON.stringify({ name, type, size: file.size })).catch(() => {});
+
+      metaStore.set(id, {
+        id,
+        name,
+        size: file.size,
+        type,
+        path: filePath,
+      });
+
+      // DB 자동 기록 (rawSql 있을 때만)
+      if (rawSql) {
+        try {
+          await recordFileToDb(rawSql, id, name, file.size, type, "api");
+        } catch (e: unknown) {
+          // DB 기록 실패해도 파일 저장은 성공 — 로그만 남김
+          const msg = e instanceof Error ? e.message : String(e);
+          console.warn(`[storage] DB record failed for ${id}: ${msg}`);
+        }
+      }
+
+      return id;
+    },
+
+    async storeBuffer(
+      buffer: Buffer,
+      filename: string,
+      type: string = "application/octet-stream",
+    ): Promise<string> {
+      // 크기 제한 검증 (단일 파일)
+      if (buffer.length > MAX_FILE_SIZE) {
+        throw new Error(
+          `File too large: ${formatBytes(buffer.length)} exceeds limit of ${formatBytes(MAX_FILE_SIZE)}`,
+        );
+      }
+
+      // 스토리지 쿼터 검증 (앱 전체 용량)
+      if (rawSql) {
+        await checkStorageQuota(rawSql, buffer.length, quota);
+      }
+
+      const id = crypto.randomUUID();
+      const filePath = path.join(dir, id);
+
+      await fs.writeFile(filePath, buffer);
+
+      // .meta JSON 기록 — Platform 레벨 직접 서빙용
+      await fs
+        .writeFile(`${filePath}.meta`, JSON.stringify({ name: filename, type, size: buffer.length }))
+        .catch(() => {});
+
+      metaStore.set(id, {
+        id,
+        name: filename,
+        size: buffer.length,
+        type,
+        path: filePath,
+      });
+
+      // DB 자동 기록
+      if (rawSql) {
+        try {
+          await recordFileToDb(rawSql, id, filename, buffer.length, type, "api");
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          console.warn(`[storage] DB record failed for ${id}: ${msg}`);
+        }
+      }
+
+      return id;
+    },
+
+    getUrl(storageId: string): string {
+      return `/api/storage/${storageId}`;
+    },
+
+    async getMeta(storageId: string): Promise<StorageFile | null> {
+      return metaStore.get(storageId) || null;
+    },
+
+    async delete(storageId: string): Promise<void> {
+      const meta = metaStore.get(storageId);
+      if (meta) {
+        await fs.unlink(meta.path).catch(() => {});
+        // .meta JSON 동시 삭제
+        await fs.unlink(`${meta.path}.meta`).catch(() => {});
+        metaStore.delete(storageId);
+      } else {
+        // metaStore에 없어도 디스크에서 직접 삭제 시도
+        const filePath = path.join(dir, storageId);
+        await fs.unlink(filePath).catch(() => {});
+        await fs.unlink(`${filePath}.meta`).catch(() => {});
+      }
+
+      // 이미지 캐시 삭제 — uploads/.cache/{storageId}_* glob
+      const cacheDir = path.join(dir, ".cache");
+      try {
+        const entries = await fs.readdir(cacheDir);
+        const prefix = `${storageId}_`;
+        await Promise.all(
+          entries
+            .filter((e) => e.startsWith(prefix))
+            .map((e) => fs.unlink(path.join(cacheDir, e)).catch(() => {})),
+        );
+      } catch {
+        /* .cache 디렉토리 미존재 시 무시 */
+      }
+
+      // DB에서도 삭제 (rawSql 있을 때만)
+      if (rawSql) {
+        try {
+          await rawSql(`DELETE FROM _system_files WHERE storage_id = $1`, [storageId]);
+        } catch {
+          /* 삭제 실패 무시 — 파일은 이미 제거됨 */
+        }
+      }
+    },
+  };
 }
 
 // ─── Image Optimization Types ───────────────────────────
 
 /** 이미지 변환 쿼리 파라미터 */
 interface ImageTransformParams {
-    w?: number;    // 너비 (1-4096)
-    h?: number;    // 높이 (1-4096)
-    f?: string;    // 출력 포맷 (webp, avif, jpeg, png)
-    q?: number;    // 품질 (1-100, 기본 80)
-    fit?: string;  // 맞춤 모드 (cover, contain, fill, inside)
+  w?: number; // 너비 (1-4096)
+  h?: number; // 높이 (1-4096)
+  f?: string; // 출력 포맷 (webp, avif, jpeg, png)
+  q?: number; // 품질 (1-100, 기본 80)
+  fit?: string; // 맞춤 모드 (cover, contain, fill, inside)
 }
 
 /** Tier별 이미지 최적화 설정 — Platform에서 주입 */
 export interface StorageImageTierConfig {
-    /** Auto WebP 허용 여부 (기본 true) */
-    autoWebp?: boolean;
-    /** Auto WebP 시 최대 폭 — 초과 시 자동 축소 (Hobby=1920, Pro=3840, Scale=무제한) */
-    autoMaxWidth?: number;
-    /** 리사이즈 허용 여부 */
-    resize?: boolean;
-    /** 허용 포맷 목록 */
-    formats?: string[];
-    /** 품질 조절 허용 여부 */
-    qualityControl?: boolean;
-    /** 캐시 상한 (MB) */
-    cacheMaxMB?: number;
-    /** 월간 변환 횟수 상한 (-1 = 무제한) */
-    transformsPerMonth?: number;
-    /** Auto WebP 품질 오버라이드 (1-100, 기본 75) — 앱별 설정에서 주입 */
-    autoQuality?: number;
+  /** Auto WebP 허용 여부 (기본 true) */
+  autoWebp?: boolean;
+  /** Auto WebP 시 최대 폭 — 초과 시 자동 축소 (Hobby=1920, Pro=3840, Scale=무제한) */
+  autoMaxWidth?: number;
+  /** 리사이즈 허용 여부 */
+  resize?: boolean;
+  /** 허용 포맷 목록 */
+  formats?: string[];
+  /** 품질 조절 허용 여부 */
+  qualityControl?: boolean;
+  /** 캐시 상한 (MB) */
+  cacheMaxMB?: number;
+  /** 월간 변환 횟수 상한 (-1 = 무제한) */
+  transformsPerMonth?: number;
+  /** Auto WebP 품질 오버라이드 (1-100, 기본 75) — 앱별 설정에서 주입 */
+  autoQuality?: number;
 }
 
 // ─── Image Optimization Constants ───────────────────────
 
 /** 변환 가능한 원본 MIME 타입 */
-const TRANSFORMABLE_TYPES = new Set([
-    "image/png", "image/jpeg", "image/jpg", "image/webp",
-]);
+const TRANSFORMABLE_TYPES = new Set(["image/png", "image/jpeg", "image/jpg", "image/webp"]);
 
 /** 허용 출력 포맷 */
 const ALLOWED_FORMATS = new Set(["webp", "avif", "jpeg", "png"]);
@@ -359,22 +355,22 @@ const MAX_CONCURRENT_TRANSFORMS = 3;
 const transformQueue: Array<() => void> = [];
 
 function acquireTransformSlot(): Promise<void> {
-    if (activeTransforms < MAX_CONCURRENT_TRANSFORMS) {
-        activeTransforms++;
-        return Promise.resolve();
-    }
-    return new Promise<void>((resolve) => {
-        transformQueue.push(() => {
-            activeTransforms++;
-            resolve();
-        });
+  if (activeTransforms < MAX_CONCURRENT_TRANSFORMS) {
+    activeTransforms++;
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    transformQueue.push(() => {
+      activeTransforms++;
+      resolve();
     });
+  });
 }
 
 function releaseTransformSlot(): void {
-    activeTransforms--;
-    const next = transformQueue.shift();
-    if (next) next();
+  activeTransforms--;
+  const next = transformQueue.shift();
+  if (next) next();
 }
 
 /**
@@ -383,80 +379,90 @@ function releaseTransformSlot(): void {
  * @returns null if no transform params, parsed params otherwise
  */
 function parseTransformParams(
-    wStr?: string, hStr?: string, fStr?: string, qStr?: string, fitStr?: string,
+  wStr?: string,
+  hStr?: string,
+  fStr?: string,
+  qStr?: string,
+  fitStr?: string,
 ): ImageTransformParams | null {
-    const params: ImageTransformParams = {};
-    let hasParam = false;
-
-    if (wStr) {
-        const w = parseInt(wStr, 10);
-        if (isNaN(w) || w < 1 || w > MAX_DIMENSION) return null;
-        params.w = w;
-        hasParam = true;
-    }
-
-    if (hStr) {
-        const h = parseInt(hStr, 10);
-        if (isNaN(h) || h < 1 || h > MAX_DIMENSION) return null;
-        params.h = h;
-        hasParam = true;
-    }
-
-    if (fStr) {
-        const fmt = fStr.toLowerCase();
-        if (!ALLOWED_FORMATS.has(fmt)) return null;
-        params.f = fmt;
-        hasParam = true;
-    }
-
-    if (qStr) {
-        const q = parseInt(qStr, 10);
-        if (isNaN(q) || q < 1 || q > 100) return null;
-        params.q = q;
-        hasParam = true;
-    }
-
-    if (fitStr) {
-        const fitMode = fitStr.toLowerCase();
-        if (!ALLOWED_FIT_MODES.has(fitMode)) return null;
-        params.fit = fitMode;
-        hasParam = true;
-    }
-
-    return hasParam ? params : null;
+  const params: ImageTransformParams = {};
+  let hasParam = false;
+
+  if (wStr) {
+    const w = parseInt(wStr, 10);
+    if (isNaN(w) || w < 1 || w > MAX_DIMENSION) return null;
+    params.w = w;
+    hasParam = true;
+  }
+
+  if (hStr) {
+    const h = parseInt(hStr, 10);
+    if (isNaN(h) || h < 1 || h > MAX_DIMENSION) return null;
+    params.h = h;
+    hasParam = true;
+  }
+
+  if (fStr) {
+    const fmt = fStr.toLowerCase();
+    if (!ALLOWED_FORMATS.has(fmt)) return null;
+    params.f = fmt;
+    hasParam = true;
+  }
+
+  if (qStr) {
+    const q = parseInt(qStr, 10);
+    if (isNaN(q) || q < 1 || q > 100) return null;
+    params.q = q;
+    hasParam = true;
+  }
+
+  if (fitStr) {
+    const fitMode = fitStr.toLowerCase();
+    if (!ALLOWED_FIT_MODES.has(fitMode)) return null;
+    params.fit = fitMode;
+    hasParam = true;
+  }
+
+  return hasParam ? params : null;
 }
 
 /**
  * 변환 파라미터에서 캐시 키 생성
  * 결정론적: 동일 파라미터 → 동일 키
  */
-function buildCacheKey(storageId: string, params: ImageTransformParams, isAutoWebp: boolean, autoMaxWidth?: number, autoQuality?: number): string {
-    if (isAutoWebp) {
-        // autoMaxWidth/autoQuality가 있으면 캐시 키에 포함 (Tier/앱별 다른 크기/품질)
-        const mwSuffix = autoMaxWidth ? `_mw${autoMaxWidth}` : "";
-        const qSuffix = autoQuality && autoQuality !== AUTO_WEBP_QUALITY ? `_q${autoQuality}` : "";
-        return `${storageId}_auto_webp${mwSuffix}${qSuffix}.webp`;
-    }
-    const parts: string[] = [storageId];
-    if (params.w) parts.push(`w${params.w}`);
-    if (params.h) parts.push(`h${params.h}`);
-    const fmt = params.f || "webp";
-    parts.push(`f${fmt}`);
-    parts.push(`q${params.q || DEFAULT_QUALITY}`);
-    if (params.fit) parts.push(params.fit);
-    return `${parts.join("_")}.${fmt === "jpeg" ? "jpg" : fmt}`;
+function buildCacheKey(
+  storageId: string,
+  params: ImageTransformParams,
+  isAutoWebp: boolean,
+  autoMaxWidth?: number,
+  autoQuality?: number,
+): string {
+  if (isAutoWebp) {
+    // autoMaxWidth/autoQuality가 있으면 캐시 키에 포함 (Tier/앱별 다른 크기/품질)
+    const mwSuffix = autoMaxWidth ? `_mw${autoMaxWidth}` : "";
+    const qSuffix = autoQuality && autoQuality !== AUTO_WEBP_QUALITY ? `_q${autoQuality}` : "";
+    return `${storageId}_auto_webp${mwSuffix}${qSuffix}.webp`;
+  }
+  const parts: string[] = [storageId];
+  if (params.w) parts.push(`w${params.w}`);
+  if (params.h) parts.push(`h${params.h}`);
+  const fmt = params.f || "webp";
+  parts.push(`f${fmt}`);
+  parts.push(`q${params.q || DEFAULT_QUALITY}`);
+  if (params.fit) parts.push(params.fit);
+  return `${parts.join("_")}.${fmt === "jpeg" ? "jpg" : fmt}`;
 }
 
 /**
  * 캐시 디렉토리의 엔트리 수 확인 — DoS 방지
  */
 async function getCacheEntryCount(cacheDir: string): Promise<number> {
-    try {
-        const entries = await fs.readdir(cacheDir);
-        return entries.length;
-    } catch {
-        return 0;
-    }
+  try {
+    const entries = await fs.readdir(cacheDir);
+    return entries.length;
+  } catch {
+    return 0;
+  }
 }
 
 /**
@@ -472,324 +478,357 @@ async function getCacheEntryCount(cacheDir: string): Promise<number> {
  * - 원본 보존: 원본 파일은 절대 수정하지 않음
  */
 export function storageRoutes(
-    storage: ReturnType<typeof createStorage>,
-    rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>,
-    storageDir?: string,
-    tierConfig?: StorageImageTierConfig,
+  storage: ReturnType<typeof createStorage>,
+  rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>,
+  storageDir?: string,
+  tierConfig?: StorageImageTierConfig,
 ) {
-    const baseTierConfig: Required<StorageImageTierConfig> = {
-        autoWebp: tierConfig?.autoWebp ?? true,
-        autoMaxWidth: tierConfig?.autoMaxWidth ?? 0, // 0 = 제한 없음
-        resize: tierConfig?.resize ?? true,
-        formats: tierConfig?.formats ?? ["webp", "avif", "jpeg", "png"],
-        qualityControl: tierConfig?.qualityControl ?? true,
-        cacheMaxMB: tierConfig?.cacheMaxMB ?? 1024, // 기본 1GB
-        transformsPerMonth: tierConfig?.transformsPerMonth ?? -1, // 무제한
-        autoQuality: tierConfig?.autoQuality ?? AUTO_WEBP_QUALITY,
-    };
-
-    /**
-     * 매 요청마다 uploads/.image-config.json 파일에서 앱별 이미지 설정을 읽어
-     * Tier config와 병합한 최종 config를 반환.
-     *
-     * 파일 기반 설계 이유:
-     *   - env var 방식은 전파 파이프라인이 6단계(DB→provisioner→env→dist→handler)로 깨지기 쉬움
-     *   - 파일은 대시보드에서 write → 다음 요청에서 즉시 read (2단계)
-     *   - 어느 프로세스든(Platform/앱) 동일 파일을 읽으므로 일관성 보장
-     *   - readFileSync ~0.01ms, 성능 영향 없음
-     */
-    function getImageConfig(uploadsDir: string): Required<StorageImageTierConfig> {
-        const config = { ...baseTierConfig };
-        try {
-            const raw = fsSync.readFileSync(path.join(uploadsDir, ".image-config.json"), "utf-8");
-            const appConfig = JSON.parse(raw);
-            // Tier ceiling 적용: min(앱 설정, Tier 최대값)
-            if (appConfig.autoMaxWidth > 0) {
-                config.autoMaxWidth = config.autoMaxWidth > 0
-                    ? Math.min(appConfig.autoMaxWidth, config.autoMaxWidth)
-                    : appConfig.autoMaxWidth;
-            }
-            if (appConfig.autoQuality > 0 && appConfig.autoQuality <= 100) {
-                config.autoQuality = appConfig.autoQuality;
-            }
-            if (appConfig.autoWebp === false) {
-                config.autoWebp = false;
-            }
-        } catch { /* 파일 없음 or 파싱 실패 → Tier 기본값 유지 */ }
-        return config;
+  const baseTierConfig: Required<StorageImageTierConfig> = {
+    autoWebp: tierConfig?.autoWebp ?? true,
+    autoMaxWidth: tierConfig?.autoMaxWidth ?? 0, // 0 = 제한 없음
+    resize: tierConfig?.resize ?? true,
+    formats: tierConfig?.formats ?? ["webp", "avif", "jpeg", "png"],
+    qualityControl: tierConfig?.qualityControl ?? true,
+    cacheMaxMB: tierConfig?.cacheMaxMB ?? 1024, // 기본 1GB
+    transformsPerMonth: tierConfig?.transformsPerMonth ?? -1, // 무제한
+    autoQuality: tierConfig?.autoQuality ?? AUTO_WEBP_QUALITY,
+  };
+
+  /**
+   * 매 요청마다 uploads/.image-config.json 파일에서 앱별 이미지 설정을 읽어
+   * Tier config와 병합한 최종 config를 반환.
+   *
+   * 파일 기반 설계 이유:
+   *   - env var 방식은 전파 파이프라인이 6단계(DB→provisioner→env→dist→handler)로 깨지기 쉬움
+   *   - 파일은 대시보드에서 write → 다음 요청에서 즉시 read (2단계)
+   *   - 어느 프로세스든(Platform/앱) 동일 파일을 읽으므로 일관성 보장
+   *   - readFileSync ~0.01ms, 성능 영향 없음
+   */
+  function getImageConfig(uploadsDir: string): Required<StorageImageTierConfig> {
+    const config = { ...baseTierConfig };
+    try {
+      const raw = fsSync.readFileSync(path.join(uploadsDir, ".image-config.json"), "utf-8");
+      const appConfig = JSON.parse(raw);
+      // Tier ceiling 적용: min(앱 설정, Tier 최대값)
+      if (appConfig.autoMaxWidth > 0) {
+        config.autoMaxWidth =
+          config.autoMaxWidth > 0
+            ? Math.min(appConfig.autoMaxWidth, config.autoMaxWidth)
+            : appConfig.autoMaxWidth;
+      }
+      if (appConfig.autoQuality > 0 && appConfig.autoQuality <= 100) {
+        config.autoQuality = appConfig.autoQuality;
+      }
+      if (appConfig.autoWebp === false) {
+        config.autoWebp = false;
+      }
+    } catch {
+      /* 파일 없음 or 파싱 실패 → Tier 기본값 유지 */
     }
+    return config;
+  }
 
-    // sharp 모듈 캐시 (동적 import 1회만)
-    let sharpModule: any = null;
-    let sharpLoadAttempted = false;
+  // sharp 모듈 캐시 (동적 import 1회만)
+  let sharpModule: any = null;
+  let sharpLoadAttempted = false;
 
-    async function getSharp(): Promise<any> {
-        if (sharpLoadAttempted) return sharpModule;
-        sharpLoadAttempted = true;
-        try {
-            // @ts-ignore — sharp는 런타임 선택적 의존성 (설치 안 된 환경에서도 빌드 가능)
-            sharpModule = (await import("sharp")).default;
-        } catch {
-            // sharp 미설치 시 null → 원본 서빙 fallback
-            console.warn("[storage] sharp not available — image optimization disabled");
-            sharpModule = null;
+  async function getSharp(): Promise<any> {
+    if (sharpLoadAttempted) return sharpModule;
+    sharpLoadAttempted = true;
+    try {
+      // @ts-ignore — sharp는 런타임 선택적 의존성 (설치 안 된 환경에서도 빌드 가능)
+      sharpModule = (await import("sharp")).default;
+    } catch {
+      // sharp 미설치 시 null → 원본 서빙 fallback
+      console.warn("[storage] sharp not available — image optimization disabled");
+      sharpModule = null;
+    }
+    return sharpModule;
+  }
+
+  return async (c: {
+    req: {
+      param: (key: string) => string;
+      query: (key: string) => string | undefined;
+      header: (name: string) => string | undefined;
+    };
+    json: (data: unknown, status?: number) => Response;
+    body: (data: unknown, status: number, headers: Record<string, string>) => Response;
+  }) => {
+    // 매 요청마다 uploads/.image-config.json에서 config 읽기 (파일 기반 hot-reload)
+    const dir = storageDir || "./uploads";
+    const config = getImageConfig(dir);
+
+    const id = c.req.param("id");
+    let meta = await storage.getMeta(id);
+
+    // Fallback: DB lookup when in-memory meta is missing (e.g. after server restart)
+    if (!meta && rawSql) {
+      try {
+        const rows = await rawSql(
+          `SELECT storage_id, name, size, type FROM _system_files WHERE storage_id = $1 LIMIT 1`,
+          [id],
+        );
+        if (rows.length > 0) {
+          const row = rows[0] as Record<string, string>;
+          const dir = storageDir || "./uploads";
+          meta = {
+            id: row.storage_id,
+            name: row.name,
+            size: Number(row.size),
+            type: row.type || "application/octet-stream",
+            path: path.join(dir, row.storage_id),
+          };
         }
-        return sharpModule;
+      } catch {
+        /* fallthrough to 404 */
+      }
     }
 
-    return async (c: { req: { param: (key: string) => string; query: (key: string) => string | undefined; header: (name: string) => string | undefined }; json: (data: unknown, status?: number) => Response; body: (data: unknown, status: number, headers: Record<string, string>) => Response }) => {
-        // 매 요청마다 uploads/.image-config.json에서 config 읽기 (파일 기반 hot-reload)
-        const dir = storageDir || "./uploads";
-        const config = getImageConfig(dir);
-
-        const id = c.req.param("id");
-        let meta = await storage.getMeta(id);
+    if (!meta) {
+      return c.json({ error: "Not found" }, 404);
+    }
 
-        // Fallback: DB lookup when in-memory meta is missing (e.g. after server restart)
-        if (!meta && rawSql) {
-            try {
-                const rows = await rawSql(
-                    `SELECT storage_id, name, size, type FROM _system_files WHERE storage_id = $1 LIMIT 1`,
-                    [id]
-                );
-                if (rows.length > 0) {
-                    const row = rows[0] as Record<string, string>;
-                    const dir = storageDir || "./uploads";
-                    meta = {
-                        id: row.storage_id,
-                        name: row.name,
-                        size: Number(row.size),
-                        type: row.type || "application/octet-stream",
-                        path: path.join(dir, row.storage_id),
-                    };
-                }
-            } catch { /* fallthrough to 404 */ }
-        }
+    // ── 이미지 최적화 분기 ─────────────────────────────
+    const isTransformable = TRANSFORMABLE_TYPES.has(meta.type);
+
+    // Hono native query 파서로 파라미터 추출
+    const transformParams = isTransformable
+      ? parseTransformParams(
+          c.req.query("w"),
+          c.req.query("h"),
+          c.req.query("f"),
+          c.req.query("q"),
+          c.req.query("fit"),
+        )
+      : null;
+
+    // Accept 헤더에서 WebP 지원 감지
+    const acceptHeader = c.req.header("accept") || "";
+    const clientAcceptsWebp = acceptHeader.includes("image/webp");
+
+    // Auto WebP: 파라미터 없지만 브라우저가 webp 지원 + 원본이 PNG/JPEG
+    const isAutoWebp =
+      !transformParams &&
+      isTransformable &&
+      clientAcceptsWebp &&
+      config.autoWebp &&
+      (meta.type === "image/png" || meta.type === "image/jpeg" || meta.type === "image/jpg");
+
+    // 이미지 변환이 필요 없는 경우 → 원본 서빙 (기존 동작 100% 유지)
+    if (!transformParams && !isAutoWebp) {
+      return serveOriginal(c, meta);
+    }
 
-        if (!meta) {
-            return c.json({ error: "Not found" }, 404);
-        }
+    // ── Tier 검증 (파라미터 변환 시) ──────────────────
+    if (transformParams) {
+      // 리사이즈 검증
+      if ((transformParams.w || transformParams.h) && !config.resize) {
+        return c.json(
+          {
+            error: "Image resize requires Pro plan",
+            code: "PLAN_LIMIT",
+            upgrade: "https://gencow.app/pricing",
+          },
+          403,
+        );
+      }
+      // 포맷 검증
+      if (transformParams.f && !config.formats.includes(transformParams.f)) {
+        return c.json(
+          {
+            error: `Format "${transformParams.f}" requires a higher plan`,
+            code: "PLAN_LIMIT",
+            upgrade: "https://gencow.app/pricing",
+            allowed: { formats: config.formats },
+          },
+          403,
+        );
+      }
+      // 품질 검증
+      if (transformParams.q && !config.qualityControl) {
+        return c.json(
+          {
+            error: "Quality control requires Pro plan",
+            code: "PLAN_LIMIT",
+            upgrade: "https://gencow.app/pricing",
+          },
+          403,
+        );
+      }
+      // fit 검증 (resize와 함께만 동작)
+      if (transformParams.fit && !config.resize) {
+        return c.json(
+          {
+            error: "Fit mode requires Pro plan",
+            code: "PLAN_LIMIT",
+            upgrade: "https://gencow.app/pricing",
+          },
+          403,
+        );
+      }
+    }
 
-        // ── 이미지 최적화 분기 ─────────────────────────────
-        const isTransformable = TRANSFORMABLE_TYPES.has(meta.type);
-
-        // Hono native query 파서로 파라미터 추출
-        const transformParams = isTransformable
-            ? parseTransformParams(
-                c.req.query("w"), c.req.query("h"),
-                c.req.query("f"), c.req.query("q"),
-                c.req.query("fit"),
-            )
-            : null;
-
-        // Accept 헤더에서 WebP 지원 감지
-        const acceptHeader = c.req.header("accept") || "";
-        const clientAcceptsWebp = acceptHeader.includes("image/webp");
-
-        // Auto WebP: 파라미터 없지만 브라우저가 webp 지원 + 원본이 PNG/JPEG
-        const isAutoWebp = !transformParams
-            && isTransformable
-            && clientAcceptsWebp
-            && config.autoWebp
-            && (meta.type === "image/png" || meta.type === "image/jpeg" || meta.type === "image/jpg");
-
-        // 이미지 변환이 필요 없는 경우 → 원본 서빙 (기존 동작 100% 유지)
-        if (!transformParams && !isAutoWebp) {
-            return serveOriginal(c, meta);
-        }
+    // ── sharp 로드 확인 ─────────────────────────────
+    const sharp = await getSharp();
+    if (!sharp) {
+      // sharp 미설치 → 원본 서빙 (graceful degradation)
+      return serveOriginal(c, meta);
+    }
 
-        // ── Tier 검증 (파라미터 변환 시) ──────────────────
-        if (transformParams) {
-            // 리사이즈 검증
-            if ((transformParams.w || transformParams.h) && !config.resize) {
-                return c.json({
-                    error: "Image resize requires Pro plan",
-                    code: "PLAN_LIMIT",
-                    upgrade: "https://gencow.app/pricing",
-                }, 403);
-            }
-            // 포맷 검증
-            if (transformParams.f && !config.formats.includes(transformParams.f)) {
-                return c.json({
-                    error: `Format "${transformParams.f}" requires a higher plan`,
-                    code: "PLAN_LIMIT",
-                    upgrade: "https://gencow.app/pricing",
-                    allowed: { formats: config.formats },
-                }, 403);
-            }
-            // 품질 검증
-            if (transformParams.q && !config.qualityControl) {
-                return c.json({
-                    error: "Quality control requires Pro plan",
-                    code: "PLAN_LIMIT",
-                    upgrade: "https://gencow.app/pricing",
-                }, 403);
-            }
-            // fit 검증 (resize와 함께만 동작)
-            if (transformParams.fit && !config.resize) {
-                return c.json({
-                    error: "Fit mode requires Pro plan",
-                    code: "PLAN_LIMIT",
-                    upgrade: "https://gencow.app/pricing",
-                }, 403);
-            }
-        }
+    // ── 캐시 확인 ───────────────────────────────────
+    const cacheDir = path.join(dir, ".cache");
+    const cacheKey = buildCacheKey(
+      id,
+      transformParams || {},
+      isAutoWebp,
+      config.autoMaxWidth || undefined,
+      config.autoQuality,
+    );
+    const cachePath = path.join(cacheDir, cacheKey);
 
-        // ── sharp 로드 확인 ─────────────────────────────
-        const sharp = await getSharp();
-        if (!sharp) {
-            // sharp 미설치 → 원본 서빙 (graceful degradation)
-            return serveOriginal(c, meta);
-        }
+    // 캐시 HIT
+    try {
+      await fs.access(cachePath);
+      // 캐시 파일이 존재 → 바로 서빙
+      return serveCachedFile(c, cachePath, transformParams, isAutoWebp, meta);
+    } catch {
+      // 캐시 MISS → 변환 필요
+    }
 
-        // ── 캐시 확인 ───────────────────────────────────
-        const cacheDir = path.join(dir, ".cache");
-        const cacheKey = buildCacheKey(id, transformParams || {}, isAutoWebp, config.autoMaxWidth || undefined, config.autoQuality);
-        const cachePath = path.join(cacheDir, cacheKey);
+    // ── 캐시 엔트리 수 제한 확인 ─────────────────────
+    const cacheCount = await getCacheEntryCount(cacheDir);
+    if (cacheCount >= MAX_CACHE_ENTRIES) {
+      // 캐시 상한 초과 → 변환은 수행하되 캐시 저장 안 함 (or 원본 반환)
+      // 보안상 원본 서빙으로 fallback
+      return serveOriginal(c, meta);
+    }
 
-        // 캐시 HIT
-        try {
-            await fs.access(cachePath);
-            // 캐시 파일이 존재 → 바로 서빙
-            return serveCachedFile(c, cachePath, transformParams, isAutoWebp, meta);
-        } catch {
-            // 캐시 MISS → 변환 필요
+    // ── 이미지 변환 수행 ─────────────────────────────
+    try {
+      await acquireTransformSlot();
+
+      try {
+        // 캐시 디렉토리 생성
+        await fs.mkdir(cacheDir, { recursive: true });
+
+        // sharp 파이프라인 구성
+        let pipeline = sharp(meta.path);
+
+        // 리사이즈
+        if (transformParams?.w || transformParams?.h) {
+          const fitMode = (transformParams.fit || "cover") as "cover" | "contain" | "fill" | "inside";
+          pipeline = pipeline.resize({
+            width: transformParams.w || undefined,
+            height: transformParams.h || undefined,
+            fit: fitMode,
+            withoutEnlargement: true, // 원본보다 크게 확대하지 않음
+          });
+        } else if (isAutoWebp && config.autoMaxWidth > 0) {
+          // Auto WebP 시 Tier별 최대폭 제한 (Hobby=1920, Pro=3840, Scale=0=무제한)
+          // 원본이 maxWidth 이하면 리사이즈하지 않음 (withoutEnlargement)
+          pipeline = pipeline.resize({
+            width: config.autoMaxWidth,
+            withoutEnlargement: true,
+          });
         }
 
-        // ── 캐시 엔트리 수 제한 확인 ─────────────────────
-        const cacheCount = await getCacheEntryCount(cacheDir);
-        if (cacheCount >= MAX_CACHE_ENTRIES) {
-            // 캐시 상한 초과 → 변환은 수행하되 캐시 저장 안 함 (or 원본 반환)
-            // 보안상 원본 서빙으로 fallback
-            return serveOriginal(c, meta);
+        // 출력 포맷 + 품질
+        const outputFormat = transformParams?.f || (isAutoWebp ? "webp" : null);
+        const quality = transformParams?.q ?? DEFAULT_QUALITY;
+
+        if (outputFormat === "webp") {
+          pipeline = pipeline.webp(
+            isAutoWebp
+              ? { quality: config.autoQuality, effort: AUTO_WEBP_EFFORT, alphaQuality: 100 }
+              : { quality, alphaQuality: 100 },
+          );
+        } else if (outputFormat === "avif") {
+          pipeline = pipeline.avif({ quality });
+        } else if (outputFormat === "jpeg" || outputFormat === "jpg") {
+          pipeline = pipeline.jpeg({ quality, mozjpeg: true });
+        } else if (outputFormat === "png") {
+          pipeline = pipeline.png({ compressionLevel: 9 });
         }
 
-        // ── 이미지 변환 수행 ─────────────────────────────
-        try {
-            await acquireTransformSlot();
-
-            try {
-                // 캐시 디렉토리 생성
-                await fs.mkdir(cacheDir, { recursive: true });
-
-                // sharp 파이프라인 구성
-                let pipeline = sharp(meta.path);
-
-                // 리사이즈
-                if (transformParams?.w || transformParams?.h) {
-                    const fitMode = (transformParams.fit || "cover") as "cover" | "contain" | "fill" | "inside";
-                    pipeline = pipeline.resize({
-                        width: transformParams.w || undefined,
-                        height: transformParams.h || undefined,
-                        fit: fitMode,
-                        withoutEnlargement: true, // 원본보다 크게 확대하지 않음
-                    });
-                } else if (isAutoWebp && config.autoMaxWidth > 0) {
-                    // Auto WebP 시 Tier별 최대폭 제한 (Hobby=1920, Pro=3840, Scale=0=무제한)
-                    // 원본이 maxWidth 이하면 리사이즈하지 않음 (withoutEnlargement)
-                    pipeline = pipeline.resize({
-                        width: config.autoMaxWidth,
-                        withoutEnlargement: true,
-                    });
-                }
-
-                // 출력 포맷 + 품질
-                const outputFormat = transformParams?.f || (isAutoWebp ? "webp" : null);
-                const quality = transformParams?.q ?? DEFAULT_QUALITY;
-
-                if (outputFormat === "webp") {
-                    pipeline = pipeline.webp(isAutoWebp
-                        ? { quality: config.autoQuality, effort: AUTO_WEBP_EFFORT, alphaQuality: 100 }
-                        : { quality, alphaQuality: 100 });
-                } else if (outputFormat === "avif") {
-                    pipeline = pipeline.avif({ quality });
-                } else if (outputFormat === "jpeg" || outputFormat === "jpg") {
-                    pipeline = pipeline.jpeg({ quality, mozjpeg: true });
-                } else if (outputFormat === "png") {
-                    pipeline = pipeline.png({ compressionLevel: 9 });
-                }
-
-                // 변환 실행 → 캐시에 저장
-                await pipeline.toFile(cachePath);
-
-                // WebP/AVIF가 원본보다 큰 경우 → 캐시 삭제 + 원본 서빙
-                // (Static Deploy와 동일 전략 — apps.ts L840-847)
-                if (isAutoWebp) {
-                    const cacheStats = await fs.stat(cachePath);
-                    if (cacheStats.size >= meta.size) {
-                        await fs.unlink(cachePath).catch(() => { });
-                        return serveOriginal(c, meta);
-                    }
-                }
-
-                return serveCachedFile(c, cachePath, transformParams, isAutoWebp, meta);
-            } finally {
-                releaseTransformSlot();
-            }
-        } catch (err: unknown) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`[storage] Image transform failed for ${id}: ${msg}`);
-            // 변환 실패 → 원본 서빙 (graceful degradation)
+        // 변환 실행 → 캐시에 저장
+        await pipeline.toFile(cachePath);
+
+        // WebP/AVIF가 원본보다 큰 경우 → 캐시 삭제 + 원본 서빙
+        // (Static Deploy와 동일 전략 — apps.ts L840-847)
+        if (isAutoWebp) {
+          const cacheStats = await fs.stat(cachePath);
+          if (cacheStats.size >= meta.size) {
+            await fs.unlink(cachePath).catch(() => {});
             return serveOriginal(c, meta);
+          }
         }
-    };
 
-    /** 원본 파일 서빙 (기존 동작) */
-    function serveOriginal(c: any, meta: StorageFile): Response {
-        const headers: Record<string, string> = {
-            "Content-Type": meta.type,
-            "Content-Disposition": `inline; filename="${encodeURIComponent(meta.name)}"; filename*=UTF-8''${encodeURIComponent(meta.name)}`,
-            "Cache-Control": "public, max-age=31536000, immutable",
-        };
-
-        if (typeof globalThis.Bun !== "undefined") {
-            const bunFile = Bun.file(meta.path);
-            return new Response(bunFile, { headers });
-        }
+        return serveCachedFile(c, cachePath, transformParams, isAutoWebp, meta);
+      } finally {
+        releaseTransformSlot();
+      }
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[storage] Image transform failed for ${id}: ${msg}`);
+      // 변환 실패 → 원본 서빙 (graceful degradation)
+      return serveOriginal(c, meta);
+    }
+  };
+
+  /** 원본 파일 서빙 (기존 동작) */
+  function serveOriginal(c: any, meta: StorageFile): Response {
+    const headers: Record<string, string> = {
+      "Content-Type": meta.type,
+      "Content-Disposition": `inline; filename="${encodeURIComponent(meta.name)}"; filename*=UTF-8''${encodeURIComponent(meta.name)}`,
+      "Cache-Control": "public, max-age=31536000, immutable",
+    };
 
-        // Node.js 폴백 — 동기 readFile (async context에서 호출되므로 안전)
-        const file = require("fs").readFileSync(meta.path);
-        headers["Content-Length"] = String(file.byteLength);
-        return c.body(file, 200, headers);
+    if (typeof globalThis.Bun !== "undefined") {
+      const bunFile = Bun.file(meta.path);
+      return new Response(bunFile, { headers });
     }
 
-    /** 캐시된 변환 파일 서빙 */
-    function serveCachedFile(
-        c: any,
-        cachePath: string,
-        params: ImageTransformParams | null,
-        isAutoWebp: boolean,
-        originalMeta: StorageFile,
-    ): Response {
-        const outputFormat = params?.f || (isAutoWebp ? "webp" : null);
-        const contentType = outputFormat
-            ? `image/${outputFormat === "jpg" ? "jpeg" : outputFormat}`
-            : originalMeta.type;
-
-        // 변환된 파일명: original.png → original.webp (또는 original_300x200.webp)
-        const baseName = originalMeta.name.replace(/\.[^.]+$/, "");
-        const ext = outputFormat || originalMeta.name.split(".").pop() || "bin";
-        const suffix = params?.w || params?.h
-            ? `_${params.w || "auto"}x${params.h || "auto"}`
-            : "";
-        const fileName = `${baseName}${suffix}.${ext}`;
-
-        const headers: Record<string, string> = {
-            "Content-Type": contentType,
-            "Content-Disposition": `inline; filename="${encodeURIComponent(fileName)}"; filename*=UTF-8''${encodeURIComponent(fileName)}`,
-            "Cache-Control": "public, max-age=31536000, immutable",
-            // Vary: Accept — Auto WebP 시 CDN/브라우저 캐시 분리
-            ...(isAutoWebp ? { "Vary": "Accept" } : {}),
-        };
-
-        if (typeof globalThis.Bun !== "undefined") {
-            const bunFile = Bun.file(cachePath);
-            return new Response(bunFile, { headers });
-        }
+    // Node.js 폴백 — 동기 readFile (async context에서 호출되므로 안전)
+    const file = require("fs").readFileSync(meta.path);
+    headers["Content-Length"] = String(file.byteLength);
+    return c.body(file, 200, headers);
+  }
+
+  /** 캐시된 변환 파일 서빙 */
+  function serveCachedFile(
+    c: any,
+    cachePath: string,
+    params: ImageTransformParams | null,
+    isAutoWebp: boolean,
+    originalMeta: StorageFile,
+  ): Response {
+    const outputFormat = params?.f || (isAutoWebp ? "webp" : null);
+    const contentType = outputFormat
+      ? `image/${outputFormat === "jpg" ? "jpeg" : outputFormat}`
+      : originalMeta.type;
+
+    // 변환된 파일명: original.png → original.webp (또는 original_300x200.webp)
+    const baseName = originalMeta.name.replace(/\.[^.]+$/, "");
+    const ext = outputFormat || originalMeta.name.split(".").pop() || "bin";
+    const suffix = params?.w || params?.h ? `_${params.w || "auto"}x${params.h || "auto"}` : "";
+    const fileName = `${baseName}${suffix}.${ext}`;
+
+    const headers: Record<string, string> = {
+      "Content-Type": contentType,
+      "Content-Disposition": `inline; filename="${encodeURIComponent(fileName)}"; filename*=UTF-8''${encodeURIComponent(fileName)}`,
+      "Cache-Control": "public, max-age=31536000, immutable",
+      // Vary: Accept — Auto WebP 시 CDN/브라우저 캐시 분리
+      ...(isAutoWebp ? { Vary: "Accept" } : {}),
+    };
 
-        const file = require("fs").readFileSync(cachePath);
-        headers["Content-Length"] = String(file.byteLength);
-        return c.body(file, 200, headers);
+    if (typeof globalThis.Bun !== "undefined") {
+      const bunFile = Bun.file(cachePath);
+      return new Response(bunFile, { headers });
     }
-}
 
+    const file = require("fs").readFileSync(cachePath);
+    headers["Content-Length"] = String(file.byteLength);
+    return c.body(file, 200, headers);
+  }
+}