@gencow/core 0.1.18 → 0.1.21

package/dist/storage.d.ts

@@ -35,15 +35,42 @@ export interface Storage {
  * const url = storage.getUrl(id);
  */
 export declare function createStorage(dir?: string, options?: StorageOptions): Storage;
+/** 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;
+}
 /**
- * Hono routes for serving stored files
+ * 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 declare function storageRoutes(storage: ReturnType<typeof createStorage>, rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>, storageDir?: string): (c: {
+export declare function storageRoutes(storage: ReturnType<typeof createStorage>, rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>, storageDir?: string, tierConfig?: StorageImageTierConfig): (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;

package/dist/storage.js

@@ -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";
 // ─── Constants ──────────────────────────────────────────
@@ -18,8 +19,9 @@ function formatBytes(bytes) {
 // ─── Implementation ─────────────────────────────────────
 const metaStore = new Map();
 /**
- * files 테이블 자동 생성 (이미 존재하면 무시)
+ * _system_files 테이블 자동 생성 (이미 존재하면 무시)
  * admin.ts의 CREATE_FILES_TABLE_SQL과 동일한 스키마 사용
+ * ⚠️ 테이블명 '_system_files' — 사용자 테이블과 네이밍 충돌 방지 (2026-04-10)
  */
 let filesTableEnsured = false;
 async function ensureFilesTable(rawSql) {
@@ -31,9 +33,9 @@ async function ensureFilesTable(rawSql) {
             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,
@@ -53,7 +55,7 @@ async function ensureFilesTable(rawSql) {
 async function checkStorageQuota(rawSql, newFileSize, quota) {
     if (quota <= 0)
         return; // 무제한
-    const rows = await rawSql(`SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM files`);
+    const rows = await rawSql(`SELECT COALESCE(SUM(CAST(size AS BIGINT)), 0) AS total FROM _system_files`);
     const currentUsage = Number(rows[0]?.total || "0");
     const projectedUsage = currentUsage + newFileSize;
     if (projectedUsage > quota) {
@@ -69,7 +71,7 @@ async function checkStorageQuota(rawSql, newFileSize, quota) {
  */
 async function recordFileToDb(rawSql, storageId, name, size, type, uploadedBy = "api") {
     await ensureFilesTable(rawSql);
-    await rawSql(`INSERT INTO files (storage_id, name, size, type, uploaded_by, created_at)
+    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]);
 }
 /**
@@ -104,6 +106,8 @@ export function createStorage(dir = "./uploads", options) {
             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,
@@ -136,6 +140,8 @@ export function createStorage(dir = "./uploads", options) {
             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,
@@ -165,32 +171,240 @@ export function createStorage(dir = "./uploads", options) {
             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`, [storageId]);
+                    await rawSql(`DELETE FROM _system_files WHERE storage_id = $1`, [storageId]);
                 }
                 catch { /* 삭제 실패 무시 — 파일은 이미 제거됨 */ }
             }
         },
     };
 }
+// ─── 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 = [];
+function acquireTransformSlot() {
+    if (activeTransforms < MAX_CONCURRENT_TRANSFORMS) {
+        activeTransforms++;
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        transformQueue.push(() => {
+            activeTransforms++;
+            resolve();
+        });
+    });
+}
+function releaseTransformSlot() {
+    activeTransforms--;
+    const next = transformQueue.shift();
+    if (next)
+        next();
+}
+/**
+ * 쿼리 파라미터를 파싱 + 정규화 + 검증
+ * Hono의 c.req.query()로 추출한 개별 값을 받아 정규화.
+ * @returns null if no transform params, parsed params otherwise
+ */
+function parseTransformParams(wStr, hStr, fStr, qStr, fitStr) {
+    const params = {};
+    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, params, isAutoWebp, autoMaxWidth, autoQuality) {
+    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 = [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}`;
+}
 /**
- * Hono routes for serving stored files
+ * 캐시 디렉토리의 엔트리 수 확인 — DoS 방지
+ */
+async function getCacheEntryCount(cacheDir) {
+    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, rawSql, storageDir) {
+export function storageRoutes(storage, rawSql, storageDir, tierConfig) {
+    const baseTierConfig = {
+        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) {
+        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 = null;
+    let sharpLoadAttempted = false;
+    async function getSharp() {
+        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) => {
+        // 매 요청마다 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 files WHERE storage_id = $1 LIMIT 1`, [id]);
+                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];
                     const dir = storageDir || "./uploads";
@@ -208,21 +422,196 @@ export function storageRoutes(storage, rawSql, storageDir) {
         if (!meta) {
             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");
+                    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) {
+            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, meta) {
         const headers = {
             "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, cachePath, params, isAutoWebp, originalMeta) {
+        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 = {
+            "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/dist/v.js

@@ -113,11 +113,15 @@ export function parseArgs(schema, args) {
     }
     // 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 = {};
-        for (const key in schema) {
+        for (const key of schemaKeys) {
             const validator = schema[key];
             if (validator && typeof validator.parse === "function") {
                 try {

package/package.json

@@ -1,42 +1,45 @@
 {
-    "name": "@gencow/core",
-    "version": "0.1.18",
-    "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
-    "type": "module",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "require": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        },
-        "./server": {
-            "import": "./dist/server.js",
-            "require": "./dist/server.js",
-            "types": "./dist/server.d.ts"
-        }
+  "name": "@gencow/core",
+  "version": "0.1.21",
+  "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     },
-    "files": [
-        "dist/",
-        "src/"
-    ],
-    "scripts": {
-        "build": "tsc",
-        "typecheck": "tsc --noEmit",
-        "prepublishOnly": "npm run build",
-        "postinstall": "tsc"
-    },
-    "dependencies": {
-        "@electric-sql/pglite": "^0.3.15",
-        "drizzle-orm": "^0.45.1",
-        "hono": "^4.12.0",
-        "node-cron": "^4.2.1"
-    },
-    "devDependencies": {
-        "@types/bun": "^1.3.9",
-        "@types/node": "^25.3.0",
-        "@types/node-cron": "^3.0.11",
-        "typescript": "^5.9.3"
+    "./server": {
+      "import": "./dist/server.js",
+      "require": "./dist/server.js",
+      "types": "./dist/server.d.ts"
     }
-}
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "@electric-sql/pglite": "^0.3.15",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.12.0",
+    "node-cron": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "@types/node": "^25.3.0",
+    "@types/node-cron": "^3.0.11",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-seed": "^0.3.1",
+    "typescript": "^5.9.3",
+    "uuid": "^13.0.0"
+  },
+  "scripts": {
+    "db:generate:fixture-basic": "drizzle-kit generate --config ./src/__tests__/fixtures/basic/drizzle.config.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "tsc"
+  }
+}