@fuzionx/framework 0.1.39 → 0.1.42

package/lib/core/Context.js

@@ -1,484 +1,484 @@
-/**
- * Context — 요청/응답 통합 API
- *
- * Bridge rawReq → Context 변환.
- * 미들웨어/핸들러에 전달되는 단일 객체.
- *
- * Session은 Bridge sessionSet/Destroy/Renew N-API에 위임.
- * Cookie는 rawReq.headers.cookie 파싱 + Set-Cookie 헤더 생성.
- *
- * @see docs/framework/06-context.md
- * @see packages/fuzionx/lib/context.js (Core SessionProto 참조)
- */
-import AppError, { ValidationError } from '../core/AppError.js';
-import { readFileSync } from 'node:fs';
-
-export default class Context {
-    /**
-     * @param {object} rawReq - Bridge에서 전달된 raw 요청 객체
-     * @param {import('./Application.js').default} app
-     */
-    constructor(rawReq, app) {
-        // ── 요청 프로퍼티 ──
-        this.method = rawReq.method || 'GET';
-        this.url = rawReq.url || '/';
-        this.path = rawReq.path || this.url.split('?')[0];
-        this.query = rawReq.query || {};
-        this.params = rawReq.params || {};
-        this.headers = rawReq.headers || {};
-        this.body = rawReq.body || null;
-        this.ip = rawReq.remoteIp || '';
-        this.files = rawReq.files || null;
-        this.uploadError = rawReq.uploadError || null;
-        this.formFields = rawReq.formFields || null;
-        this.handlerId = rawReq.handlerId;
-
-        // 파생 속성 (06-context.md)
-        this.protocol = this.headers['x-forwarded-proto'] || 'http';
-        this.host = this.headers['host'] || '';
-
-        // ── 프레임워크 주입 ──
-        this.app = app;
-        this.user = null;
-        this._sessionId = rawReq.sessionId || null;
-        this._rawSession = rawReq.session || {};
-        // ── Cookie (parseCookies 먼저 — _detectLocale에서 참조) ──
-        this.cookies = this._parseCookies();
-
-        this.session = this._createSession(rawReq, app);
-        this.locale = this._detectLocale(rawReq);
-
-        // i18n — ctx.t() + ctx.t.all() (18-i18n.md)
-        this.t = this._createT();
-
-        // ── lazy 캐시 ──
-        this._json = undefined;
-        this._setCookies = []; // Set-Cookie 헤더 배열
-
-        // ── 응답 상태 ──
-        this._statusCode = 200;
-        this._headers = {};
-        this._body = '';
-        this._sent = false;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Request 유틸
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /** lazy JSON 파싱 */
-    get getJson() {
-        if (this._json !== undefined) return this._json;
-        if (typeof this.body === 'object' && this.body !== null) {
-            this._json = this.body;
-        } else if (typeof this.body === 'string' && this.body) {
-            try { this._json = JSON.parse(this.body); }
-            catch { this._json = null; }
-        } else {
-            this._json = null;
-        }
-        return this._json;
-    }
-
-    /** 헤더 값 가져오기 (case-insensitive) */
-    get(name) {
-        return this.headers[name.toLowerCase()];
-    }
-
-    /** Content-Type 확인 */
-    is(type) {
-        const ct = this.get('content-type') || '';
-        const map = {
-            json: 'application/json',
-            html: 'text/html',
-            form: 'application/x-www-form-urlencoded',
-            multipart: 'multipart/form-data',
-        };
-        return ct.includes(map[type] || type);
-    }
-
-    /**
-     * Accept 협상 (06-context.md)
-     * @param {...string} types - 'json', 'html', 'text'
-     * @returns {string|false} 매칭된 타입 또는 false
-     */
-    accepts(...types) {
-        const accept = this.get('accept') || '*/*';
-        const mimeMap = {
-            json: 'application/json',
-            html: 'text/html',
-            text: 'text/plain',
-            xml: 'application/xml',
-        };
-        for (const type of types) {
-            const mime = mimeMap[type] || type;
-            if (accept.includes(mime) || accept.includes('*/*')) return type;
-        }
-        return false;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Cookie (06-context.md)
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /**
-     * 쿠키 읽기/쓰기
-     * @overload cookie(name) → 읽기
-     * @overload cookie(name, value, opts?) → 쓰기
-     */
-    cookie(name, value, opts) {
-        if (arguments.length === 1) {
-            return this.cookies[name] ?? null;
-        }
-        // 쓰기 → Set-Cookie 헤더
-        const o = opts || {};
-        let str = `${name}=${encodeURIComponent(String(value))}`;
-        if (o.maxAge != null) str += `; Max-Age=${o.maxAge}`;
-        if (o.path) str += `; Path=${o.path}`;
-        else str += '; Path=/';
-        if (o.domain) str += `; Domain=${o.domain}`;
-        if (o.httpOnly !== false) str += '; HttpOnly';
-        if (o.secure) str += '; Secure';
-        if (o.sameSite) str += `; SameSite=${o.sameSite}`;
-        this._setCookies.push(str);
-        return this;
-    }
-
-    /** 쿠키 삭제 */
-    clearCookie(name, opts) {
-        return this.cookie(name, '', { ...opts, maxAge: 0 });
-    }
-
-    /** @private */
-    _parseCookies() {
-        const header = this.headers?.cookie || this.headers?.Cookie || '';
-        if (!header) return {};
-        const result = {};
-        for (const pair of header.split(';')) {
-            const [k, ...v] = pair.trim().split('=');
-            if (k) result[k.trim()] = decodeURIComponent(v.join('='));
-        }
-        return result;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Response 메서드
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    status(code) {
-        this._statusCode = code;
-        return this;
-    }
-
-    json(data) {
-        this._body = JSON.stringify(data);
-        this._headers['Content-Type'] = 'application/json';
-        this._sent = true;
-        return this;
-    }
-
-    send(data) {
-        if (typeof data === 'object' && data !== null) {
-            return this.json(data);
-        }
-        this._body = String(data);
-        if (!this._headers['Content-Type']) {
-            this._headers['Content-Type'] = 'text/html; charset=utf-8';
-        }
-        this._sent = true;
-        return this;
-    }
-
-    html(content) {
-        return this.send(content);
-    }
-
-    text(content) {
-        this._body = String(content);
-        this._headers['Content-Type'] = 'text/plain; charset=utf-8';
-        this._sent = true;
-        return this;
-    }
-
-    redirect(url, code = 302) {
-        this._statusCode = code;
-        this._headers['Location'] = url;
-        this._body = '';
-        this._sent = true;
-        return this;
-    }
-
-    back() {
-        const referer = this.get('referer') || '/';
-        return this.redirect(referer);
-    }
-
-    end() {
-        this._body = '';
-        this._sent = true;
-        return this;
-    }
-
-    header(key, value) {
-        this._headers[key] = value;
-        return this;
-    }
-
-    /** setHeader alias (06-context.md) */
-    setHeader(key, value) {
-        return this.header(key, value);
-    }
-
-    error(statusCode, message) {
-        throw new AppError(message, statusCode);
-    }
-
-    /**
-     * 파일 다운로드 (06-context.md)
-     * Bridge는 문자열 body만 지원하므로 파일 내용을 직접 읽어 base64 전송.
-     * @param {string} filePath - 절대 경로
-     * @param {string} [filename]
-     */
-    download(filePath, filename) {
-        const name = filename || filePath.split('/').pop();
-        this._headers['Content-Disposition'] = `attachment; filename="${name}"`;
-        try {
-            const buf = readFileSync(filePath);
-            this._body = buf.toString('base64');
-            this._headers['Content-Transfer-Encoding'] = 'base64';
-            this._headers['Content-Type'] = this._headers['Content-Type'] || 'application/octet-stream';
-        } catch (err) {
-            this._statusCode = 404;
-            this._body = JSON.stringify({ error: `File not found: ${name}` });
-            this._headers['Content-Type'] = 'application/json';
-        }
-        this._sent = true;
-        return this;
-    }
-
-    /**
-     * 스트리밍 응답 (06-context.md)
-     * Bridge는 문자열 body만 지원하므로 Buffer/Stream을 문자열로 변환.
-     * Buffer → toString(), ReadableStream → 청크 수집.
-     * @param {ReadableStream|Buffer|string} readableStream
-     * @param {string} [contentType='application/octet-stream']
-     */
-    async stream(readableStream, contentType = 'application/octet-stream') {
-        this._headers['Content-Type'] = contentType;
-        if (Buffer.isBuffer(readableStream)) {
-            this._body = readableStream.toString();
-        } else if (typeof readableStream === 'string') {
-            this._body = readableStream;
-        } else if (readableStream && typeof readableStream[Symbol.asyncIterator] === 'function') {
-            // ReadableStream/AsyncIterable → 청크 수집
-            const chunks = [];
-            for await (const chunk of readableStream) {
-                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-            }
-            this._body = Buffer.concat(chunks).toString();
-        } else {
-            this._body = String(readableStream || '');
-        }
-        this._sent = true;
-        return this;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Validate
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    validate(schema) {
-        if (schema && typeof schema.validate === 'function') {
-            const { error, value } = schema.validate(this.body, { abortEarly: false, stripUnknown: true });
-            if (error) {
-                const fields = {};
-                for (const detail of error.details) {
-                    fields[detail.path.join('.')] = detail.message;
-                }
-                throw new ValidationError('Validation failed', fields);
-            }
-            return value;
-        }
-        return this.body;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  i18n (Bridge 연동)
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /** @private Setup i18n t() function with .all() support */
-    _createT() {
-        const self = this;
-        const t = (key, vars) => {
-            const locale = vars?.locale || self.locale;
-            if (self.app?.i18n) {
-                return self.app.i18n.translate(locale, key, vars);
-            }
-            return vars?.default || key;
-        };
-        // ctx.t.all() — 현재 locale 전체 번역 데이터 (18-i18n.md)
-        t.all = () => {
-            if (self.app?.i18n?.getAll) {
-                return self.app.i18n.getAll(self.locale);
-            }
-            return {};
-        };
-        return t;
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  View 렌더링
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    render(view, data) {
-        // 글로벌 변수 주입 (03-views-templates.md)
-        const bridge = this.app?._bridge;
-        let aspVars = {};
-        if (bridge?.getAspConfig && bridge?.cryptoEncryptCustom) {
-            try {
-                const aspCfg = JSON.parse(bridge.getAspConfig());
-                const clientSecret = this.app?.config?.get('app.client_secret') || '';
-                if (clientSecret && aspCfg.masterSecret) {
-                    aspVars = {
-                        _fx_client_secret: clientSecret,
-                        _fx_asp_secret: bridge.cryptoEncryptCustom(clientSecret, aspCfg.masterSecret),
-                        _fx_asp_header: aspCfg.headerSignal || 'Ruxy-Enc-Mode',
-                    };
-                }
-            } catch {}
-        }
-
-        const globals = {
-            session: this._rawSession,
-            auth: { user: this.user },
-            config: this.app?.config?._raw || {},
-            request: { url: this.url, method: this.method, path: this.path, ip: this.ip },
-            csrf_token: this._rawSession?._csrfToken || '',
-            flash: this.session?.getFlash() || {},
-            theme: this.theme || this.app?.config?.get('themes.default', 'default') || 'default',
-            locale: this.locale,
-            locales: this.app?.i18n?.locales?.() || [],
-            ...aspVars,
-            ...data,
-        };
-
-        // Bridge Tera SSR — 앱별 View 인스턴스 사용
-        const appEntry = this.app?._appRegistry?.get(this.appName);
-        const viewEngine = appEntry?.view;
-        if (!viewEngine) {
-            throw new Error(`View not initialized for app '${this.appName}' — Bridge not available`);
-        }
-
-        const html = viewEngine.render(view, globals);
-        return this.html(html);
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Session + Flash (Bridge sessionSet/Destroy/Renew)
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /** @private */
-    _createSession(rawReq, app) {
-        const data = rawReq.session || {};
-        // Flash 추출 + 세션에서 삭제 (one-time read)
-        const flash = { ...(data._flash || {}) };
-        const hadFlash = !!data._flash;
-        delete data._flash;
-        const sessionId = rawReq.sessionId || null;
-        const bridge = app?._bridge || null;
-
-        // Flash 소비 후 세션 저장소에 즉시 반영
-        if (hadFlash && sessionId && bridge?.sessionSet) {
-            try { bridge.sessionSet(sessionId, { ...data }); } catch {}
-        }
-
-        return {
-            /** 세션 값 조회 */
-            get: (key) => key ? (data[key] ?? null) : { ...data },
-
-            /** 세션 값 설정 — Bridge sessionSet 연동 */
-            set: (key, value) => {
-                data[key] = value;
-                // Core SessionProto 참조: bridge.sessionSet(id, { ...data })
-                if (sessionId && bridge?.sessionSet) {
-                    try {
-                        bridge.sessionSet(sessionId, { ...data });
-                    } catch (e) {
-                        console.error('[Session] sessionSet failed:', e?.message || e);
-                    }
-                }
-            },
-
-            /** 세션 삭제 — Bridge sessionDestroy 연동 */
-            destroy: () => {
-                Object.keys(data).forEach(k => delete data[k]);
-                if (sessionId && bridge?.sessionDestroy) {
-                    try { bridge.sessionDestroy(sessionId); } catch {}
-                }
-            },
-
-            /** 세션 갱신 — Bridge sessionRenew 연동 */
-            renew: () => {
-                if (sessionId && bridge?.sessionRenew) {
-                    try { return bridge.sessionRenew(sessionId); } catch {}
-                }
-                return null;
-            },
-
-            /** 플래시 메시지 설정 */
-            flash: (key, value) => {
-                if (!data._flash) data._flash = {};
-                data._flash[key] = value;
-                // 플래시도 세션에 영속화
-                if (sessionId && bridge?.sessionSet) {
-                    try { bridge.sessionSet(sessionId, { ...data }); } catch {}
-                }
-            },
-
-            /** 플래시 메시지 조회 (1회 후 삭제) */
-            getFlash: (key) => {
-                if (key) {
-                    const val = flash[key];
-                    delete flash[key];
-                    return val ?? null;
-                }
-                const all = { ...flash };
-                Object.keys(flash).forEach(k => delete flash[k]);
-                return all;
-            },
-        };
-    }
-
-    /** locale 감지 (5단계 우선순위) — 06-context.md */
-    _detectLocale(rawReq) {
-        if (rawReq.locale) return rawReq.locale;
-        if (this.query?.lang) return this.query.lang;
-        // 쿠키 fuzionx.lang
-        const cookieLang = this.cookies?.['fuzionx.lang'];
-        if (cookieLang) return cookieLang;
-        if (this._rawSession?.locale) return this._rawSession.locale;
-        const al = this.headers?.['accept-language'];
-        if (al) {
-            const first = al.split(',')[0]?.split('-')[0];
-            if (first) return first;
-        }
-        return this.app?.config?.get('app.i18n.default_locale', 'ko') || 'ko';
-    }
-
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  응답 변환
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-    /** Bridge 응답 포맷 { status, body, headers } */
-    toResponse() {
-        // Set-Cookie 헤더 병합
-        if (this._setCookies.length > 0) {
-            this._headers['Set-Cookie'] = this._setCookies;  // 배열 → Bridge 다중 헤더
-        }
-        return {
-            status: this._statusCode,
-            body: this._body,
-            headers: this._headers,
-        };
-    }
-}
+/**
+ * Context — 요청/응답 통합 API
+ *
+ * Bridge rawReq → Context 변환.
+ * 미들웨어/핸들러에 전달되는 단일 객체.
+ *
+ * Session은 Bridge sessionSet/Destroy/Renew N-API에 위임.
+ * Cookie는 rawReq.headers.cookie 파싱 + Set-Cookie 헤더 생성.
+ *
+ * @see docs/framework/06-context.md
+ * @see packages/fuzionx/lib/context.js (Core SessionProto 참조)
+ */
+import AppError, { ValidationError } from '../core/AppError.js';
+import { readFileSync } from 'node:fs';
+
+export default class Context {
+    /**
+     * @param {object} rawReq - Bridge에서 전달된 raw 요청 객체
+     * @param {import('./Application.js').default} app
+     */
+    constructor(rawReq, app) {
+        // ── 요청 프로퍼티 ──
+        this.method = rawReq.method || 'GET';
+        this.url = rawReq.url || '/';
+        this.path = rawReq.path || this.url.split('?')[0];
+        this.query = rawReq.query || {};
+        this.params = rawReq.params || {};
+        this.headers = rawReq.headers || {};
+        this.body = rawReq.body || null;
+        this.ip = rawReq.remoteIp || '';
+        this.files = rawReq.files || null;
+        this.uploadError = rawReq.uploadError || null;
+        this.formFields = rawReq.formFields || null;
+        this.handlerId = rawReq.handlerId;
+
+        // 파생 속성 (06-context.md)
+        this.protocol = this.headers['x-forwarded-proto'] || 'http';
+        this.host = this.headers['host'] || '';
+
+        // ── 프레임워크 주입 ──
+        this.app = app;
+        this.user = null;
+        this._sessionId = rawReq.sessionId || null;
+        this._rawSession = rawReq.session || {};
+        // ── Cookie (parseCookies 먼저 — _detectLocale에서 참조) ──
+        this.cookies = this._parseCookies();
+
+        this.session = this._createSession(rawReq, app);
+        this.locale = this._detectLocale(rawReq);
+
+        // i18n — ctx.t() + ctx.t.all() (18-i18n.md)
+        this.t = this._createT();
+
+        // ── lazy 캐시 ──
+        this._json = undefined;
+        this._setCookies = []; // Set-Cookie 헤더 배열
+
+        // ── 응답 상태 ──
+        this._statusCode = 200;
+        this._headers = {};
+        this._body = '';
+        this._sent = false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Request 유틸
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** lazy JSON 파싱 */
+    get getJson() {
+        if (this._json !== undefined) return this._json;
+        if (typeof this.body === 'object' && this.body !== null) {
+            this._json = this.body;
+        } else if (typeof this.body === 'string' && this.body) {
+            try { this._json = JSON.parse(this.body); }
+            catch { this._json = null; }
+        } else {
+            this._json = null;
+        }
+        return this._json;
+    }
+
+    /** 헤더 값 가져오기 (case-insensitive) */
+    get(name) {
+        return this.headers[name.toLowerCase()];
+    }
+
+    /** Content-Type 확인 */
+    is(type) {
+        const ct = this.get('content-type') || '';
+        const map = {
+            json: 'application/json',
+            html: 'text/html',
+            form: 'application/x-www-form-urlencoded',
+            multipart: 'multipart/form-data',
+        };
+        return ct.includes(map[type] || type);
+    }
+
+    /**
+     * Accept 협상 (06-context.md)
+     * @param {...string} types - 'json', 'html', 'text'
+     * @returns {string|false} 매칭된 타입 또는 false
+     */
+    accepts(...types) {
+        const accept = this.get('accept') || '*/*';
+        const mimeMap = {
+            json: 'application/json',
+            html: 'text/html',
+            text: 'text/plain',
+            xml: 'application/xml',
+        };
+        for (const type of types) {
+            const mime = mimeMap[type] || type;
+            if (accept.includes(mime) || accept.includes('*/*')) return type;
+        }
+        return false;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Cookie (06-context.md)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /**
+     * 쿠키 읽기/쓰기
+     * @overload cookie(name) → 읽기
+     * @overload cookie(name, value, opts?) → 쓰기
+     */
+    cookie(name, value, opts) {
+        if (arguments.length === 1) {
+            return this.cookies[name] ?? null;
+        }
+        // 쓰기 → Set-Cookie 헤더
+        const o = opts || {};
+        let str = `${name}=${encodeURIComponent(String(value))}`;
+        if (o.maxAge != null) str += `; Max-Age=${o.maxAge}`;
+        if (o.path) str += `; Path=${o.path}`;
+        else str += '; Path=/';
+        if (o.domain) str += `; Domain=${o.domain}`;
+        if (o.httpOnly !== false) str += '; HttpOnly';
+        if (o.secure) str += '; Secure';
+        if (o.sameSite) str += `; SameSite=${o.sameSite}`;
+        this._setCookies.push(str);
+        return this;
+    }
+
+    /** 쿠키 삭제 */
+    clearCookie(name, opts) {
+        return this.cookie(name, '', { ...opts, maxAge: 0 });
+    }
+
+    /** @private */
+    _parseCookies() {
+        const header = this.headers?.cookie || this.headers?.Cookie || '';
+        if (!header) return {};
+        const result = {};
+        for (const pair of header.split(';')) {
+            const [k, ...v] = pair.trim().split('=');
+            if (k) result[k.trim()] = decodeURIComponent(v.join('='));
+        }
+        return result;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Response 메서드
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    status(code) {
+        this._statusCode = code;
+        return this;
+    }
+
+    json(data) {
+        this._body = JSON.stringify(data);
+        this._headers['Content-Type'] = 'application/json';
+        this._sent = true;
+        return this;
+    }
+
+    send(data) {
+        if (typeof data === 'object' && data !== null) {
+            return this.json(data);
+        }
+        this._body = String(data);
+        if (!this._headers['Content-Type']) {
+            this._headers['Content-Type'] = 'text/html; charset=utf-8';
+        }
+        this._sent = true;
+        return this;
+    }
+
+    html(content) {
+        return this.send(content);
+    }
+
+    text(content) {
+        this._body = String(content);
+        this._headers['Content-Type'] = 'text/plain; charset=utf-8';
+        this._sent = true;
+        return this;
+    }
+
+    redirect(url, code = 302) {
+        this._statusCode = code;
+        this._headers['Location'] = url;
+        this._body = '';
+        this._sent = true;
+        return this;
+    }
+
+    back() {
+        const referer = this.get('referer') || '/';
+        return this.redirect(referer);
+    }
+
+    end() {
+        this._body = '';
+        this._sent = true;
+        return this;
+    }
+
+    header(key, value) {
+        this._headers[key] = value;
+        return this;
+    }
+
+    /** setHeader alias (06-context.md) */
+    setHeader(key, value) {
+        return this.header(key, value);
+    }
+
+    error(statusCode, message) {
+        throw new AppError(message, statusCode);
+    }
+
+    /**
+     * 파일 다운로드 (06-context.md)
+     * Bridge는 문자열 body만 지원하므로 파일 내용을 직접 읽어 base64 전송.
+     * @param {string} filePath - 절대 경로
+     * @param {string} [filename]
+     */
+    download(filePath, filename) {
+        const name = filename || filePath.split('/').pop();
+        this._headers['Content-Disposition'] = `attachment; filename="${name}"`;
+        try {
+            const buf = readFileSync(filePath);
+            this._body = buf.toString('base64');
+            this._headers['Content-Transfer-Encoding'] = 'base64';
+            this._headers['Content-Type'] = this._headers['Content-Type'] || 'application/octet-stream';
+        } catch (err) {
+            this._statusCode = 404;
+            this._body = JSON.stringify({ error: `File not found: ${name}` });
+            this._headers['Content-Type'] = 'application/json';
+        }
+        this._sent = true;
+        return this;
+    }
+
+    /**
+     * 스트리밍 응답 (06-context.md)
+     * Bridge는 문자열 body만 지원하므로 Buffer/Stream을 문자열로 변환.
+     * Buffer → toString(), ReadableStream → 청크 수집.
+     * @param {ReadableStream|Buffer|string} readableStream
+     * @param {string} [contentType='application/octet-stream']
+     */
+    async stream(readableStream, contentType = 'application/octet-stream') {
+        this._headers['Content-Type'] = contentType;
+        if (Buffer.isBuffer(readableStream)) {
+            this._body = readableStream.toString();
+        } else if (typeof readableStream === 'string') {
+            this._body = readableStream;
+        } else if (readableStream && typeof readableStream[Symbol.asyncIterator] === 'function') {
+            // ReadableStream/AsyncIterable → 청크 수집
+            const chunks = [];
+            for await (const chunk of readableStream) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            this._body = Buffer.concat(chunks).toString();
+        } else {
+            this._body = String(readableStream || '');
+        }
+        this._sent = true;
+        return this;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Validate
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    validate(schema) {
+        if (schema && typeof schema.validate === 'function') {
+            const { error, value } = schema.validate(this.body, { abortEarly: false, stripUnknown: true });
+            if (error) {
+                const fields = {};
+                for (const detail of error.details) {
+                    fields[detail.path.join('.')] = detail.message;
+                }
+                throw new ValidationError('Validation failed', fields);
+            }
+            return value;
+        }
+        return this.body;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  i18n (Bridge 연동)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** @private Setup i18n t() function with .all() support */
+    _createT() {
+        const self = this;
+        const t = (key, vars) => {
+            const locale = vars?.locale || self.locale;
+            if (self.app?.i18n) {
+                return self.app.i18n.translate(locale, key, vars);
+            }
+            return vars?.default || key;
+        };
+        // ctx.t.all() — 현재 locale 전체 번역 데이터 (18-i18n.md)
+        t.all = () => {
+            if (self.app?.i18n?.getAll) {
+                return self.app.i18n.getAll(self.locale);
+            }
+            return {};
+        };
+        return t;
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  View 렌더링
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    render(view, data) {
+        // 글로벌 변수 주입 (03-views-templates.md)
+        const bridge = this.app?._bridge;
+        let aspVars = {};
+        if (bridge?.getAspConfig && bridge?.cryptoEncryptCustom) {
+            try {
+                const aspCfg = JSON.parse(bridge.getAspConfig());
+                const clientSecret = this.app?.config?.get('app.client_secret') || '';
+                if (clientSecret && aspCfg.masterSecret) {
+                    aspVars = {
+                        _fx_client_secret: clientSecret,
+                        _fx_asp_secret: bridge.cryptoEncryptCustom(clientSecret, aspCfg.masterSecret),
+                        _fx_asp_header: aspCfg.headerSignal || 'Ruxy-Enc-Mode',
+                    };
+                }
+            } catch {}
+        }
+
+        const globals = {
+            session: this._rawSession,
+            auth: { user: this.user },
+            config: this.app?.config?._raw || {},
+            request: { url: this.url, method: this.method, path: this.path, ip: this.ip },
+            csrf_token: this._rawSession?._csrfToken || '',
+            flash: this.session?.getFlash() || {},
+            theme: this.theme || this.app?.config?.get('themes.default', 'default') || 'default',
+            locale: this.locale,
+            locales: this.app?.i18n?.locales?.() || [],
+            ...aspVars,
+            ...data,
+        };
+
+        // Bridge Tera SSR — 앱별 View 인스턴스 사용
+        const appEntry = this.app?._appRegistry?.get(this.appName);
+        const viewEngine = appEntry?.view;
+        if (!viewEngine) {
+            throw new Error(`View not initialized for app '${this.appName}' — Bridge not available`);
+        }
+
+        const html = viewEngine.render(view, globals);
+        return this.html(html);
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  Session + Flash (Bridge sessionSet/Destroy/Renew)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** @private */
+    _createSession(rawReq, app) {
+        const data = rawReq.session || {};
+        // Flash 추출 + 세션에서 삭제 (one-time read)
+        const flash = { ...(data._flash || {}) };
+        const hadFlash = !!data._flash;
+        delete data._flash;
+        const sessionId = rawReq.sessionId || null;
+        const bridge = app?._bridge || null;
+
+        // Flash 소비 후 세션 저장소에 즉시 반영
+        if (hadFlash && sessionId && bridge?.sessionSet) {
+            try { bridge.sessionSet(sessionId, { ...data }); } catch {}
+        }
+
+        return {
+            /** 세션 값 조회 */
+            get: (key) => key ? (data[key] ?? null) : { ...data },
+
+            /** 세션 값 설정 — Bridge sessionSet 연동 */
+            set: (key, value) => {
+                data[key] = value;
+                // Core SessionProto 참조: bridge.sessionSet(id, { ...data })
+                if (sessionId && bridge?.sessionSet) {
+                    try {
+                        bridge.sessionSet(sessionId, { ...data });
+                    } catch (e) {
+                        console.error('[Session] sessionSet failed:', e?.message || e);
+                    }
+                }
+            },
+
+            /** 세션 삭제 — Bridge sessionDestroy 연동 */
+            destroy: () => {
+                Object.keys(data).forEach(k => delete data[k]);
+                if (sessionId && bridge?.sessionDestroy) {
+                    try { bridge.sessionDestroy(sessionId); } catch {}
+                }
+            },
+
+            /** 세션 갱신 — Bridge sessionRenew 연동 */
+            renew: () => {
+                if (sessionId && bridge?.sessionRenew) {
+                    try { return bridge.sessionRenew(sessionId); } catch {}
+                }
+                return null;
+            },
+
+            /** 플래시 메시지 설정 */
+            flash: (key, value) => {
+                if (!data._flash) data._flash = {};
+                data._flash[key] = value;
+                // 플래시도 세션에 영속화
+                if (sessionId && bridge?.sessionSet) {
+                    try { bridge.sessionSet(sessionId, { ...data }); } catch {}
+                }
+            },
+
+            /** 플래시 메시지 조회 (1회 후 삭제) */
+            getFlash: (key) => {
+                if (key) {
+                    const val = flash[key];
+                    delete flash[key];
+                    return val ?? null;
+                }
+                const all = { ...flash };
+                Object.keys(flash).forEach(k => delete flash[k]);
+                return all;
+            },
+        };
+    }
+
+    /** locale 감지 (5단계 우선순위) — 06-context.md */
+    _detectLocale(rawReq) {
+        if (rawReq.locale) return rawReq.locale;
+        if (this.query?.lang) return this.query.lang;
+        // 쿠키 fuzionx.lang
+        const cookieLang = this.cookies?.['fuzionx.lang'];
+        if (cookieLang) return cookieLang;
+        if (this._rawSession?.locale) return this._rawSession.locale;
+        const al = this.headers?.['accept-language'];
+        if (al) {
+            const first = al.split(',')[0]?.split('-')[0];
+            if (first) return first;
+        }
+        return this.app?.config?.get('app.i18n.default_locale', 'ko') || 'ko';
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    //  응답 변환
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /** Bridge 응답 포맷 { status, body, headers } */
+    toResponse() {
+        // Set-Cookie 헤더 병합
+        if (this._setCookies.length > 0) {
+            this._headers['Set-Cookie'] = this._setCookies;  // 배열 → Bridge 다중 헤더
+        }
+        return {
+            status: this._statusCode,
+            body: this._body,
+            headers: this._headers,
+        };
+    }
+}