@nmvuong92/fluxe 0.2.0 → 0.3.0

package/lib/core/client.d.ts

@@ -16,6 +16,15 @@ export interface RpcMeta {
 }
 export declare const lastRpcMeta: () => RpcMeta;
 export declare function rpc<T = any>(cell: string, action: string, input: unknown): Promise<T>;
+export declare function upload(field: string, files: File | File[]): Promise<{
+    key: string;
+    url: string;
+    size: number;
+} | Array<{
+    key: string;
+    url: string;
+    size: number;
+}>>;
 export declare function mutate<T>(opts: {
     optimistic?: () => void;
     run: () => Promise<T>;

package/lib/core/client.js

@@ -70,6 +70,20 @@ export async function rpc(cell, action, input) {
         throw parseRpcError(res.status, await res.text());
     return res.json();
 }
+/* Upload file qua POST /__upload/<field> (multipart). Trả { key, url, size } (hoặc mảng nếu nhiều). */
+export async function upload(field, files) {
+    const fd = new FormData();
+    for (const f of Array.isArray(files) ? files : [files])
+        fd.append(field, f);
+    const res = await fetch(`/__upload/${field}`, {
+        method: "POST",
+        headers: { "x-csrf-token": cookie("csrf") }, // KHÔNG set content-type — browser tự thêm boundary
+        body: fd,
+    });
+    if (!res.ok)
+        throw parseRpcError(res.status, await res.text());
+    return res.json();
+}
 // Optimistic update: chạy optimistic() ngay, run() ngầm; lỗi → rollback() + ném lại.
 export async function mutate(opts) {
     opts.optimistic?.();

package/lib/core/multipart.d.ts

@@ -0,0 +1,8 @@
+export interface Part {
+    name: string;
+    filename?: string;
+    contentType?: string;
+    data: Buffer;
+}
+export declare function boundaryFromContentType(contentType: string | undefined): string | null;
+export declare function parseMultipart(body: Buffer, boundary: string): Part[];

package/lib/core/multipart.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Parser multipart/form-data — THUẦN, chỉ Buffer (không lib). Tách body theo boundary thành
+ * các part { name, filename?, contentType?, data }. Dùng cho upload. */
+const CRLFCRLF = Buffer.from("\r\n\r\n");
+/* boundary lấy từ header Content-Type: multipart/form-data; boundary=XXXX */
+export function boundaryFromContentType(contentType) {
+    if (!contentType)
+        return null;
+    const m = /boundary=(?:"([^"]+)"|([^;]+))/i.exec(contentType);
+    return m ? (m[1] ?? m[2]).trim() : null;
+}
+export function parseMultipart(body, boundary) {
+    const parts = [];
+    const delim = Buffer.from(`--${boundary}`);
+    const positions = [];
+    let idx = body.indexOf(delim, 0);
+    while (idx !== -1) {
+        positions.push(idx);
+        idx = body.indexOf(delim, idx + delim.length);
+    }
+    for (let i = 0; i < positions.length - 1; i++) {
+        let start = positions[i] + delim.length;
+        if (body[start] === 0x2d && body[start + 1] === 0x2d)
+            continue; // "--" → delim đóng, bỏ
+        if (body[start] === 0x0d && body[start + 1] === 0x0a)
+            start += 2; // bỏ \r\n sau delim
+        let end = positions[i + 1];
+        if (body[end - 2] === 0x0d && body[end - 1] === 0x0a)
+            end -= 2; // bỏ \r\n trước delim kế
+        const seg = body.subarray(start, end);
+        const sep = seg.indexOf(CRLFCRLF);
+        if (sep === -1)
+            continue;
+        const headerStr = seg.subarray(0, sep).toString("utf8");
+        const data = seg.subarray(sep + CRLFCRLF.length);
+        const cd = /content-disposition:[^\r\n]*?name="([^"]*)"(?:[^\r\n]*?filename="([^"]*)")?/i.exec(headerStr);
+        if (!cd)
+            continue;
+        const ct = /content-type:\s*([^\r\n]+)/i.exec(headerStr);
+        parts.push({
+            name: cd[1],
+            filename: cd[2] || undefined,
+            contentType: ct?.[1]?.trim(),
+            data,
+        });
+    }
+    return parts;
+}

package/lib/index.d.ts

@@ -15,6 +15,10 @@ export * from "./core/layouts.ts";
 export * from "./core/router.ts";
 export * from "./core/testing.ts";
 export * from "./backends/types.ts";
+export * from "./storage/types.ts";
+export { createMemoryStorage } from "./storage/memory.ts";
+export { createLocalStorage } from "./storage/local.ts";
+export { createS3Storage } from "./storage/s3.ts";
 export { createMemoryBackend } from "./backends/memory.ts";
 export { createHttpBackend } from "./backends/http.ts";
 export { createPostgresBackend } from "./backends/postgres.ts";

package/lib/index.js

@@ -19,6 +19,10 @@ export * from "./core/layouts.js"; // layoutChain, LayoutMeta
 export * from "./core/router.js"; // makeRouter
 export * from "./core/testing.js"; // createTestBackend
 export * from "./backends/types.js"; // Backend, Todo
+export * from "./storage/types.js"; // Storage, PutResult, GetResult, safeKey, makeKey
+export { createMemoryStorage } from "./storage/memory.js";
+export { createLocalStorage } from "./storage/local.js";
+export { createS3Storage } from "./storage/s3.js"; // adapter tham chiếu (cần @aws-sdk/client-s3)
 export { createMemoryBackend } from "./backends/memory.js";
 export { createHttpBackend } from "./backends/http.js";
 export { createPostgresBackend } from "./backends/postgres.js";

package/lib/server_factory.d.ts

@@ -9,7 +9,10 @@ type LayoutEntry = LayoutMeta & {
 };
 type LayoutMap = Record<string, LayoutEntry>;
 import { type I18n } from "./core/i18n.ts";
+import { type Storage } from "./storage/types.ts";
 export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
     i18n?: I18n;
+    storage?: Storage;
+    maxUpload?: number;
 }): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -21,6 +21,8 @@ import { etagOf, etagMatches } from "./core/etag.js";
 import { createRenderCache } from "./core/rendercache.js";
 import { parseChaos } from "./core/chaos.js";
 import { resolveLocale, makeT } from "./core/i18n.js";
+import { parseMultipart, boundaryFromContentType } from "./core/multipart.js";
+import { makeKey } from "./storage/types.js";
 import { createMemoryBackend } from "./backends/memory.js";
 import { createHttpBackend } from "./backends/http.js";
 // Build backend theo ngôn ngữ (cho live swap trong devtools).
@@ -37,7 +39,7 @@ function devBackend(lang) {
     const url = process.env[`${lang.toUpperCase()}_URL`] ?? DEV_BACKENDS[lang];
     return url ? createHttpBackend(lang, url) : createMemoryBackend();
 }
-import { randomUUID } from "node:crypto";
+import { randomUUID, randomBytes } from "node:crypto";
 const DEV = process.env.NODE_ENV !== "production";
 const SECRET = process.env.FLUXE_SECRET ?? "dev-secret-change-me";
 // Demo user store (password hash scrypt tạo lúc boot). App thật: lấy từ DB.
@@ -89,6 +91,23 @@ function renderBodyToString(node) {
 }
 export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const i18n = opts.i18n;
+    const storage = opts.storage;
+    const MAX_UPLOAD = opts.maxUpload ?? 10 * 1024 * 1024; // 10MB mặc định
+    const readBodyBuffer = (req) => new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_UPLOAD) {
+                req.destroy();
+                reject(new FluxeError("upload", "File quá lớn", 413));
+            }
+            else
+                chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
     // Cells được TIÊM từ app (DI) — engine không import ngược vào app/. Thêm trang = sửa app/app.ts.
     const matchRoute = makeRouter(cells);
     const byId = new Map(cells.map((c) => [c.id, c]));
@@ -182,6 +201,43 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
                 });
                 return res.end(`<p>Đã đăng xuất. <a href="/">trang chủ</a></p>`);
             }
+            // File upload: POST /__upload/<field> → parse multipart → storage.put. CSRF + giới hạn size.
+            if (url.pathname.startsWith("/__upload/") && req.method === "POST") {
+                if (!storage) {
+                    res.writeHead(501);
+                    return res.end(JSON.stringify({ error: { code: "no_storage", message: "Chưa cấu hình storage", status: 501 } }));
+                }
+                if (!cookies.csrf || req.headers["x-csrf-token"] !== cookies.csrf)
+                    throw new FluxeError("csrf", "CSRF không hợp lệ", 403);
+                const boundary = boundaryFromContentType(req.headers["content-type"]);
+                if (!boundary)
+                    throw new FluxeError("upload", "Cần multipart/form-data", 400);
+                const files = parseMultipart(await readBodyBuffer(req), boundary).filter((p) => p.filename);
+                if (!files.length)
+                    throw new FluxeError("upload", "Không có file", 400);
+                const out = [];
+                for (const f of files) {
+                    const key = makeKey(f.filename, randomBytes(8).toString("hex"));
+                    out.push(await storage.put(key, f.data, { contentType: f.contentType }));
+                }
+                res.writeHead(200, { "content-type": "application/json" });
+                return res.end(JSON.stringify(out.length === 1 ? out[0] : out));
+            }
+            // Serve file: GET /__file/<key> → storage.get → stream về.
+            if (url.pathname.startsWith("/__file/") && req.method === "GET") {
+                if (!storage) {
+                    res.writeHead(404);
+                    return res.end();
+                }
+                const key = decodeURIComponent(url.pathname.slice("/__file/".length));
+                const file = await storage.get(key);
+                if (!file) {
+                    res.writeHead(404);
+                    return res.end();
+                }
+                res.writeHead(200, { "content-type": file.contentType ?? "application/octet-stream", "content-length": String(file.size) });
+                return res.end(file.data);
+            }
             if (url.pathname.startsWith("/__sse/")) {
                 // Realtime channel (SSE): giữ kết nối, đẩy event khi publish trên topic. ?id= → presence.
                 const topic = decodeURIComponent(url.pathname.slice("/__sse/".length));

package/lib/storage/local.d.ts

@@ -0,0 +1,5 @@
+import type { Storage } from "./types.ts";
+export declare function createLocalStorage(opts: {
+    dir: string;
+    baseUrl?: string;
+}): Storage;

package/lib/storage/local.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+import { mkdir, writeFile, readFile, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { safeKey } from "./types.js";
+/* Driver đĩa local — ghi dưới `dir`, serve qua baseUrl (/__file/<key>). Key được làm sạch
+ * (safeKey) nên không thoát thư mục (path traversal). */
+export function createLocalStorage(opts) {
+    const baseUrl = opts.baseUrl ?? "/__file";
+    const pathOf = (key) => join(opts.dir, safeKey(key)); // chặn ../
+    const u = (key) => `${baseUrl}/${encodeURIComponent(safeKey(key))}`;
+    return {
+        name: "local",
+        async put(key, data, _opts) {
+            const p = pathOf(key);
+            await mkdir(dirname(p), { recursive: true });
+            await writeFile(p, data);
+            return { key: safeKey(key), url: u(key), size: data.length };
+        },
+        async get(key) {
+            try {
+                const data = await readFile(pathOf(key));
+                return { data, size: data.length };
+            }
+            catch {
+                return null;
+            }
+        },
+        async delete(key) {
+            try {
+                await unlink(pathOf(key));
+            }
+            catch { /* không có thì thôi */ }
+        },
+        url: u,
+    };
+}

package/lib/storage/memory.d.ts

@@ -0,0 +1,2 @@
+import type { Storage } from "./types.ts";
+export declare function createMemoryStorage(baseUrl?: string): Storage;

package/lib/storage/memory.js

@@ -0,0 +1,19 @@
+/* Driver in-RAM (dev/test). 0 đĩa, mất khi restart. */
+export function createMemoryStorage(baseUrl = "/__file") {
+    const m = new Map();
+    const u = (key) => `${baseUrl}/${encodeURIComponent(key)}`;
+    return {
+        name: "memory",
+        async put(key, data, opts) {
+            m.set(key, { data, contentType: opts?.contentType, size: data.length });
+            return { key, url: u(key), size: data.length };
+        },
+        async get(key) {
+            return m.get(key) ?? null;
+        },
+        async delete(key) {
+            m.delete(key);
+        },
+        url: u,
+    };
+}

package/lib/storage/s3.d.ts

@@ -0,0 +1,6 @@
+import type { Storage } from "./types.ts";
+export declare function createS3Storage(opts: {
+    bucket: string;
+    region: string;
+    publicBaseUrl?: string;
+}): Storage;

package/lib/storage/s3.js

@@ -0,0 +1,28 @@
+import { safeKey } from "./types.js";
+export function createS3Storage(opts) {
+    const base = opts.publicBaseUrl ?? `https://${opts.bucket}.s3.${opts.region}.amazonaws.com`;
+    const u = (key) => `${base}/${safeKey(key)}`;
+    // Khi đã `npm i @aws-sdk/client-s3`, thay phần ném lỗi bằng lệnh thật (mẫu trong comment).
+    const notReady = () => {
+        throw new Error("createS3Storage: cài '@aws-sdk/client-s3' rồi bỏ comment phần triển khai trong src/storage/s3.ts");
+    };
+    return {
+        name: "s3",
+        async put(key, _data, _o) {
+            notReady();
+            // await client.send(new PutObjectCommand({ Bucket: opts.bucket, Key: safeKey(key), Body: _data, ContentType: _o?.contentType }));
+            return { key: safeKey(key), url: u(key), size: _data.length };
+        },
+        async get(_key) {
+            notReady();
+            // const r = await client.send(new GetObjectCommand({ Bucket: opts.bucket, Key: safeKey(_key) }));
+            // return { data: Buffer.from(await r.Body!.transformToByteArray()), contentType: r.ContentType, size: r.ContentLength ?? 0 };
+            return null;
+        },
+        async delete(_key) {
+            notReady();
+            // await client.send(new DeleteObjectCommand({ Bucket: opts.bucket, Key: safeKey(_key) }));
+        },
+        url: u,
+    };
+}

package/lib/storage/types.d.ts

@@ -0,0 +1,21 @@
+export interface PutResult {
+    key: string;
+    url: string;
+    size: number;
+}
+export interface GetResult {
+    data: Buffer;
+    contentType?: string;
+    size: number;
+}
+export interface Storage {
+    name: string;
+    put(key: string, data: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<PutResult>;
+    get(key: string): Promise<GetResult | null>;
+    delete(key: string): Promise<void>;
+    url(key: string): string;
+}
+export declare function safeKey(name: string): string;
+export declare function makeKey(filename: string, randomHex: string): string;

package/lib/storage/types.js

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Storage Adapter — interface chuẩn để SWITCH driver lưu file (như Backend).
+ * Cell/endpoint chỉ biết interface này; đổi local ↔ S3 ↔ … = thay implementation. */
+/* Làm sạch tên file → key an toàn (không slash, không '..', chỉ [A-Za-z0-9._-]). */
+export function safeKey(name) {
+    const base = name.split(/[\\/]/).pop() ?? name; // bỏ path
+    const clean = base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/\.{2,}/g, "_");
+    return clean.slice(0, 120) || "file";
+}
+/* Sinh key duy nhất: <randomHex>-<safeName>. randomHex truyền vào để thuần (test dễ). */
+export function makeKey(filename, randomHex) {
+    return `${randomHex}-${safeKey(filename)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "fluxe — khung fullstack tối giản polyglot (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",