@gencow/core 0.1.18 → 0.1.21

package/src/storage.ts

@@ -1,4 +1,5 @@
 import * as fs from "fs/promises";
+import * as fsSync from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 
@@ -52,8 +53,9 @@ export interface Storage {
 const metaStore = new Map<string, StorageFile>();
 
 /**
- * files 테이블 자동 생성 (이미 존재하면 무시)
+ * _system_files 테이블 자동 생성 (이미 존재하면 무시)
  * admin.ts의 CREATE_FILES_TABLE_SQL과 동일한 스키마 사용
+ * ⚠️ 테이블명 '_system_files' — 사용자 테이블과 네이밍 충돌 방지 (2026-04-10)
  */
 let filesTableEnsured = false;
 
@@ -67,9 +69,9 @@ async function ensureFilesTable(
             IF NOT EXISTS (
                 SELECT 1 FROM information_schema.tables
                 WHERE table_schema = current_schema()
-                AND table_name = 'files'
+                AND table_name = '_system_files'
             ) THEN
-                CREATE TABLE files (
+                CREATE TABLE _system_files (
                     id SERIAL PRIMARY KEY,
                     storage_id TEXT NOT NULL,
                     name TEXT NOT NULL,
@@ -95,7 +97,7 @@ async function checkStorageQuota(
     if (quota <= 0) return; // 무제한
 
     const rows = await rawSql(
-        `SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM files`,
+        `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;
@@ -124,7 +126,7 @@ async function recordFileToDb(
 ): Promise<void> {
     await ensureFilesTable(rawSql);
     await rawSql(
-        `INSERT INTO files (storage_id, name, size, type, uploaded_by, created_at)
+        `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],
     );
@@ -174,6 +176,9 @@ export function createStorage(
 
             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,
@@ -218,6 +223,9 @@ export function createStorage(
 
             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,
@@ -251,14 +259,33 @@ export function createStorage(
             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 files WHERE storage_id = $1`,
+                        `DELETE FROM _system_files WHERE storage_id = $1`,
                         [storageId],
                     );
                 } catch { /* 삭제 실패 무시 — 파일은 이미 제거됨 */ }
@@ -267,18 +294,254 @@ export function createStorage(
     };
 }
 
+// ─── 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)
+}
+
+/** 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;
+}
+
+// ─── Image Optimization Constants ───────────────────────
+
+/** 변환 가능한 원본 MIME 타입 */
+const TRANSFORMABLE_TYPES = new Set([
+    "image/png", "image/jpeg", "image/jpg", "image/webp",
+]);
+
+/** 허용 출력 포맷 */
+const ALLOWED_FORMATS = new Set(["webp", "avif", "jpeg", "png"]);
+
+/** 허용 맞춤 모드 */
+const ALLOWED_FIT_MODES = new Set(["cover", "contain", "fill", "inside"]);
+
+/** 최대 치수 (px) — DoS 방지 */
+const MAX_DIMENSION = 4096;
+
+/** 기본 품질 */
+const DEFAULT_QUALITY = 80;
+/** Auto WebP 전용 설정 — JPEG에서도 효과를 내려면 q75 + effort 6 필요
+ *  (테스트: 2.5MB JPEG → q80 effort4=더커짐, q75 effort6=15.6% 감소) */
+const AUTO_WEBP_QUALITY = 75;
+const AUTO_WEBP_EFFORT = 6;
+
+/** 앱당 최대 캐시 엔트리 수 — 랜덤 파라미터 DoS 방지 */
+const MAX_CACHE_ENTRIES = 1000;
+
+// ─── Image Optimization Helpers ─────────────────────────
+
+/** 동시 변환 세마포어 — CPU 폭발 방지 (최대 3 동시) */
+let activeTransforms = 0;
+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();
+        });
+    });
+}
+
+function releaseTransformSlot(): void {
+    activeTransforms--;
+    const next = transformQueue.shift();
+    if (next) next();
+}
+
 /**
- * Hono routes for serving stored files
+ * 쿼리 파라미터를 파싱 + 정규화 + 검증
+ * Hono의 c.req.query()로 추출한 개별 값을 받아 정규화.
+ * @returns null if no transform params, parsed params otherwise
+ */
+function parseTransformParams(
+    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;
+}
+
+/**
+ * 변환 파라미터에서 캐시 키 생성
+ * 결정론적: 동일 파라미터 → 동일 키
+ */
+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;
+    }
+}
+
+/**
+ * Hono routes for serving stored files + Image Optimization
  *
  * 인증 없이 public URL로 서빙 — Convex getUrl() 패턴과 동일.
  * 접근 제어는 URL을 반환하는 query/mutation 레벨에서 개발자가 구현.
+ *
+ * 이미지 최적화:
+ * - Auto WebP: Accept: image/webp 헤더 감지 → 자동 WebP 변환
+ * - URL 파라미터: ?w=300&h=200&f=webp&q=80&fit=cover
+ * - 디스크 캐시: uploads/.cache/{uuid}_{params}.{ext}
+ * - 원본 보존: 원본 파일은 절대 수정하지 않음
  */
 export function storageRoutes(
     storage: ReturnType<typeof createStorage>,
     rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>,
     storageDir?: string,
+    tierConfig?: StorageImageTierConfig,
 ) {
-    return async (c: { req: { param: (key: string) => string }; json: (data: unknown, status?: number) => Response; body: (data: unknown, status: number, headers: Record<string, string>) => Response }) => {
+    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;
+
+    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);
 
@@ -286,7 +549,7 @@ export function storageRoutes(
         if (!meta && rawSql) {
             try {
                 const rows = await rawSql(
-                    `SELECT storage_id, name, size, type FROM files WHERE storage_id = $1 LIMIT 1`,
+                    `SELECT storage_id, name, size, type FROM _system_files WHERE storage_id = $1 LIMIT 1`,
                     [id]
                 );
                 if (rows.length > 0) {
@@ -307,23 +570,226 @@ export function storageRoutes(
             return c.json({ error: "Not found" }, 404);
         }
 
-        // Bun 런타임에서는 Bun.file()을 사용하여 바이너리 무결성 보장
-        // Node의 fs.readFile()은 Bun에서 Buffer 인코딩 문제가 있을 수 있음
+        // ── 이미지 최적화 분기 ─────────────────────────────
+        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);
+        }
+
+        // ── 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);
+            }
+        }
+
+        // ── sharp 로드 확인 ─────────────────────────────
+        const sharp = await getSharp();
+        if (!sharp) {
+            // sharp 미설치 → 원본 서빙 (graceful degradation)
+            return serveOriginal(c, meta);
+        }
+
+        // ── 캐시 확인 ───────────────────────────────────
+        const cacheDir = path.join(dir, ".cache");
+        const cacheKey = buildCacheKey(id, transformParams || {}, isAutoWebp, config.autoMaxWidth || undefined, config.autoQuality);
+        const cachePath = path.join(cacheDir, cacheKey);
+
+        // 캐시 HIT
+        try {
+            await fs.access(cachePath);
+            // 캐시 파일이 존재 → 바로 서빙
+            return serveCachedFile(c, cachePath, transformParams, isAutoWebp, meta);
+        } catch {
+            // 캐시 MISS → 변환 필요
+        }
+
+        // ── 캐시 엔트리 수 제한 확인 ─────────────────────
+        const cacheCount = await getCacheEntryCount(cacheDir);
+        if (cacheCount >= MAX_CACHE_ENTRIES) {
+            // 캐시 상한 초과 → 변환은 수행하되 캐시 저장 안 함 (or 원본 반환)
+            // 보안상 원본 서빙으로 fallback
+            return serveOriginal(c, meta);
+        }
+
+        // ── 이미지 변환 수행 ─────────────────────────────
+        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)
+            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",
         };
 
-        // Bun은 Bun.file()로 직접 BunFile(Blob) 생성 → Response에 그대로 전달
         if (typeof globalThis.Bun !== "undefined") {
             const bunFile = Bun.file(meta.path);
             return new Response(bunFile, { headers });
         }
 
-        // Node.js 폴백
-        const file = await fs.readFile(meta.path);
+        // 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" } : {}),
+        };
+
+        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);
+    }
 }
+

package/src/v.ts

@@ -135,11 +135,15 @@ export function parseArgs(schema: any, args: any): any {
 
     // Shorthand object — e.g. { id: v.number(), title: v.optional(v.string()) }
     if (typeof schema === "object" && schema !== null) {
+        // Empty schema {} → passthrough all args (e.g. FormData with file field)
+        const schemaKeys = Object.keys(schema);
+        if (schemaKeys.length === 0) return args;
+
         if (typeof args !== "object" || args === null) {
             throw new GencowValidationError("Expected an object for arguments");
         }
         const result: any = {};
-        for (const key in schema) {
+        for (const key of schemaKeys) {
             const validator = schema[key];
             if (validator && typeof validator.parse === "function") {
                 try {

package/dist/scoped-db.d.ts

@@ -1,34 +0,0 @@
-/**
- * packages/core/src/scoped-db.ts
- *
- * Creates a scoped (Proxy-wrapped) Drizzle DB instance that auto-injects
- * schema-level access control filters from gencowTable() metadata.
- *
- * Key behaviors:
- *   - .select().from(gencowTable) → auto-inject filter into WHERE
- *   - .insert(table) / .update(table) / .delete(table) → inject filter for writes
- *   - .leftJoin(table) / .innerJoin(table) → detect and inject filter
- *   - .execute() → blocked (throws Error)
- *   - .query.tableName.findMany() → inject filter into relational queries
- *
- * Run tests: bun test packages/core/src/__tests__/scoped-db.test.ts
- */
-import type { GencowCtx } from "./reactive";
-/**
- * Wrap a Drizzle DB instance with access control Proxy.
- *
- * @param db  - Raw Drizzle DB instance
- * @param ctx - GencowCtx (provides auth for filter evaluation)
- * @returns Proxy-wrapped DB with auto-filter injection
- */
-export declare function createScopedDb(db: any, ctx: GencowCtx): any;
-/**
- * Apply field-level access control to query results.
- * Nullifies fields that the current user is not authorized to read.
- *
- * @param result - Query result (array or single object)
- * @param table  - The gencowTable used in the query
- * @param ctx    - GencowCtx for auth checks
- * @returns Filtered result with unauthorized fields set to null
- */
-export declare function applyFieldAccess(result: any, table: any, ctx: GencowCtx): any;