@fuzionx/framework 0.1.45 → 0.1.46

package/lib/core/Context.js

@@ -1,72 +1,29 @@
 /**
- * Context — 요청/응답 통합 API
+ * Context — 요청/응답 통합 API (고성능 버전)
  *
  * Bridge rawReq → Context 변환.
  * 미들웨어/핸들러에 전달되는 단일 객체.
  *
- * Session은 Bridge sessionSet/Destroy/Renew N-API에 위임.
- * Cookie는 rawReq.headers.cookie 파싱 + Set-Cookie 헤더 생성.
+ * 최적화:
+ *   - 프로토타입 기반 메서드 공유 (프로토타입에 메서드 정의 → 함수 생성 0)
+ *   - Lazy 프로퍼티: session, cookies, locale, t() 는 접근 시에만 생성
+ *   - 공유 인스턴스(sync용) + Object.create(async용) 패턴
+ *   - _toFusionResponse()에서 공유 응답 객체 재사용
  *
  * @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;
-    }
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Context 프로토타입 — 모든 메서드를 여기에 정의
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Request 유틸
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const ContextProto = {
 
-    /** lazy JSON 파싱 */
+    // ── Request 유틸 ──
+
+    /** lazy JSON 파싱 — body가 이미 object면 그대로 반환 */
     get getJson() {
         if (this._json !== undefined) return this._json;
         if (typeof this.body === 'object' && this.body !== null) {
@@ -78,14 +35,22 @@ export default class Context {
             this._json = null;
         }
         return this._json;
-    }
+    },
 
-    /** 헤더 값 가져오기 (case-insensitive) */
+    /**
+     * 헤더 값 가져오기 (case-insensitive)
+     * @param {string} name - 헤더 이름
+     * @returns {string|undefined}
+     */
     get(name) {
         return this.headers[name.toLowerCase()];
-    }
+    },
 
-    /** Content-Type 확인 */
+    /**
+     * Content-Type 확인
+     * @param {string} type - 'json', 'html', 'form', 'multipart'
+     * @returns {boolean}
+     */
     is(type) {
         const ct = this.get('content-type') || '';
         const map = {
@@ -95,7 +60,7 @@ export default class Context {
             multipart: 'multipart/form-data',
         };
         return ct.includes(map[type] || type);
-    }
+    },
 
     /**
      * Accept 협상 (06-context.md)
@@ -115,16 +80,66 @@ export default class Context {
             if (accept.includes(mime) || accept.includes('*/*')) return type;
         }
         return false;
-    }
+    },
+
+    // ── Lazy 프로퍼티: cookies ──
+
+    /** lazy 쿠키 파싱 — 최초 접근 시에만 파싱 */
+    get cookies() {
+        if (this._cookies !== undefined) return this._cookies;
+        this._cookies = _parseCookies(this.headers);
+        return this._cookies;
+    },
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Cookie (06-context.md)
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // ── Lazy 프로퍼티: session ──
+
+    /** lazy 세션 객체 — 최초 접근 시에만 생성 */
+    get session() {
+        if (this._session !== undefined) return this._session;
+        this._session = _createSession(this._rawReq, this.app);
+        return this._session;
+    },
+
+    // ── Lazy 프로퍼티: locale ──
+
+    /** lazy locale 감지 — 최초 접근 시에만 계산 */
+    get locale() {
+        if (this._locale !== undefined) return this._locale;
+        this._locale = _detectLocale(this);
+        return this._locale;
+    },
+
+    // ── Lazy 프로퍼티: t (i18n) ──
+
+    /** lazy i18n 함수 — 최초 접근 시에만 생성 */
+    get t() {
+        if (this._t !== undefined) return this._t;
+        this._t = _createT(this);
+        return this._t;
+    },
+
+    // ── Lazy 프로퍼티: protocol, host ──
+
+    /** 프로토콜 (x-forwarded-proto 우선) */
+    get protocol() {
+        return this.headers['x-forwarded-proto'] || 'http';
+    },
+
+    /** 호스트 헤더 */
+    get host() {
+        return this.headers['host'] || '';
+    },
+
+    // ── Cookie 읽기/쓰기 ──
 
     /**
      * 쿠키 읽기/쓰기
-     * @overload cookie(name) → 읽기
-     * @overload cookie(name, value, opts?) → 쓰기
+     * @overload cookie(name) → 값 반환
+     * @overload cookie(name, value, opts?) → Set-Cookie 추가
+     * @param {string} name - 쿠키 이름
+     * @param {string} [value] - 쿠키 값
+     * @param {object} [opts] - 쿠키 옵션
+     * @returns {string|null|this}
      */
     cookie(name, value, opts) {
         if (arguments.length === 1) {
@@ -142,41 +157,46 @@ export default class Context {
         if (o.sameSite) str += `; SameSite=${o.sameSite}`;
         this._setCookies.push(str);
         return this;
-    }
+    },
 
-    /** 쿠키 삭제 */
+    /**
+     * 쿠키 삭제
+     * @param {string} name - 쿠키 이름
+     * @param {object} [opts] - 쿠키 옵션
+     */
     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 메서드
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // ── Response 메서드 ──
 
+    /**
+     * 상태 코드 설정
+     * @param {number} code - HTTP 상태 코드
+     * @returns {this}
+     */
     status(code) {
         this._statusCode = code;
         return this;
-    }
+    },
 
+    /**
+     * JSON 응답
+     * @param {object} data - 응답 데이터
+     * @returns {this}
+     */
     json(data) {
         this._body = JSON.stringify(data);
         this._headers['Content-Type'] = 'application/json';
         this._sent = true;
         return this;
-    }
+    },
 
+    /**
+     * 텍스트/HTML 응답
+     * @param {string|object} data - 응답 데이터
+     * @returns {this}
+     */
     send(data) {
         if (typeof data === 'object' && data !== null) {
             return this.json(data);
@@ -187,57 +207,92 @@ export default class Context {
         }
         this._sent = true;
         return this;
-    }
+    },
 
+    /**
+     * HTML 응답 (send 위임)
+     * @param {string} content - HTML 문자열
+     * @returns {this}
+     */
     html(content) {
+        this._headers['Content-Type'] = 'text/html; charset=utf-8';
         return this.send(content);
-    }
+    },
 
+    /**
+     * 텍스트 응답
+     * @param {string} content - 텍스트 문자열
+     * @returns {this}
+     */
     text(content) {
         this._body = String(content);
         this._headers['Content-Type'] = 'text/plain; charset=utf-8';
         this._sent = true;
         return this;
-    }
+    },
 
+    /**
+     * 리다이렉트 응답
+     * @param {string} url - 리다이렉트 URL
+     * @param {number} [code=302] - 상태 코드
+     * @returns {this}
+     */
     redirect(url, code = 302) {
         this._statusCode = code;
         this._headers['Location'] = url;
         this._body = '';
         this._sent = true;
         return this;
-    }
+    },
 
+    /** Referer 기반 리다이렉트 */
     back() {
         const referer = this.get('referer') || '/';
         return this.redirect(referer);
-    }
+    },
 
+    /** 빈 응답으로 종료 */
     end() {
         this._body = '';
         this._sent = true;
         return this;
-    }
+    },
 
+    /**
+     * 응답 헤더 설정
+     * @param {string} key - 헤더 키
+     * @param {string} value - 헤더 값
+     * @returns {this}
+     */
     header(key, value) {
         this._headers[key] = value;
         return this;
-    }
+    },
 
-    /** setHeader alias (06-context.md) */
+    /**
+     * setHeader alias (06-context.md)
+     * @param {string} key - 헤더 키
+     * @param {string} value - 헤더 값
+     * @returns {this}
+     */
     setHeader(key, value) {
         return this.header(key, value);
-    }
+    },
 
+    /**
+     * 에러 throw (AppError)
+     * @param {number} statusCode - HTTP 상태 코드
+     * @param {string} message - 에러 메시지
+     */
     error(statusCode, message) {
         throw new AppError(message, statusCode);
-    }
+    },
 
     /**
      * 파일 다운로드 (06-context.md)
-     * Bridge는 문자열 body만 지원하므로 파일 내용을 직접 읽어 base64 전송.
      * @param {string} filePath - 절대 경로
-     * @param {string} [filename]
+     * @param {string} [filename] - 파일명
+     * @returns {this}
      */
     download(filePath, filename) {
         const name = filename || filePath.split('/').pop();
@@ -254,14 +309,13 @@ export default class Context {
         }
         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']
+     * @param {ReadableStream|Buffer|string} readableStream - 스트림 데이터
+     * @param {string} [contentType='application/octet-stream'] - Content-Type
+     * @returns {Promise<this>}
      */
     async stream(readableStream, contentType = 'application/octet-stream') {
         this._headers['Content-Type'] = contentType;
@@ -281,12 +335,15 @@ export default class Context {
         }
         this._sent = true;
         return this;
-    }
+    },
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  Validate
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // ── Validate ──
 
+    /**
+     * Joi 스키마 검증
+     * @param {object} schema - Joi 스키마 인스턴스
+     * @returns {object} 검증된 데이터
+     */
     validate(schema) {
         if (schema && typeof schema.validate === 'function') {
             const { error, value } = schema.validate(this.body, { abortEarly: false, stripUnknown: true });
@@ -300,36 +357,16 @@ export default class Context {
             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 렌더링
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // ── View 렌더링 ──
 
+    /**
+     * 템플릿 렌더링 (Bridge Tera SSR)
+     * @param {string} view - 뷰 이름
+     * @param {object} [data] - 템플릿 변수
+     * @returns {this}
+     */
     render(view, data) {
         // 글로벌 변수 주입 (03-views-templates.md)
         const bridge = this.app?._bridge;
@@ -349,11 +386,11 @@ export default class Context {
         }
 
         const globals = {
-            session: this._rawSession,
+            session: this._rawReq?.session || {},
             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 || '',
+            csrf_token: (this._rawReq?.session)?._csrfToken || '',
             flash: this.session?.getFlash() || {},
             theme: this.theme || this.app?.config?.get('themes.default', 'default') || 'default',
             locale: this.locale,
@@ -371,114 +408,381 @@ export default class Context {
 
         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 {}
+    /**
+     * Bridge 응답 포맷 { status, body, headers }
+     * sync 경로: 공유 응답 객체(_sharedFusionResponse)를 재사용하여 할당 0
+     * async 경로: 새 객체 생성
+     * @returns {{ status: number, body: string, headers: object }}
+     */
+    _toFusionResponse() {
+        // Set-Cookie 헤더 병합
+        if (this._setCookies.length > 0) {
+            this._headers['Set-Cookie'] = this._setCookies;
+        }
+        // async(비공유) 인스턴스면 새 객체 반환 → race condition 방지
+        if (this !== _sharedCtx) {
+            return { status: this._statusCode, body: this._body, headers: this._headers };
         }
+        // sync(공유) 인스턴스 → 사전 할당된 응답 객체 재사용
+        _sharedFusionResponse.status = this._statusCode;
+        _sharedFusionResponse.body = this._body;
+        _sharedFusionResponse.headers = this._headers;
+        return _sharedFusionResponse;
+    },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Private 헬퍼 함수 (프로토타입 외부)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-        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);
-                    }
-                }
-            },
+/**
+ * 쿠키 헤더 파싱 — 공통 함수
+ * @param {object} headers - 요청 헤더
+ * @returns {object} 파싱된 쿠키 맵
+ */
+function _parseCookies(headers) {
+    const header = headers?.cookie || 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;
+}
 
-            /** 세션 삭제 — Bridge sessionDestroy 연동 */
-            destroy: () => {
-                Object.keys(data).forEach(k => delete data[k]);
-                if (sessionId && bridge?.sessionDestroy) {
-                    try { bridge.sessionDestroy(sessionId); } catch {}
-                }
-            },
+/**
+ * 세션 프록시 객체 생성 — lazy 시점에만 호출
+ * @param {object} rawReq - 원시 요청 객체
+ * @param {import('./Application.js').default} app - Application 인스턴스
+ * @returns {object} 세션 프록시 (get/set/destroy/renew/flash/getFlash)
+ */
+function _createSession(rawReq, app) {
+    // Core req의 session은 SessionProto 인스턴스 → _data 프로퍼티 추출
+    const rawSession = rawReq?.session;
+    const data = (rawSession?._data !== undefined) ? rawSession._data : (rawSession || {});
+    // 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 {}
+    }
 
-            /** 세션 갱신 — 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;
-            },
-        };
+    return {
+        /** 세션 값 조회 */
+        get: (key) => key ? (data[key] ?? null) : { ...data },
+
+        /** 세션 값 설정 — Bridge sessionSet 연동 */
+        set: (key, value) => {
+            data[key] = value;
+            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
+ * @param {object} ctx - Context 인스턴스
+ * @returns {string} 감지된 locale
+ */
+function _detectLocale(ctx) {
+    if (ctx._rawReq?.locale) return ctx._rawReq.locale;
+    if (ctx.query?.lang) return ctx.query.lang;
+    // 쿠키 fuzionx.lang (lazy cookie 접근)
+    const cookieLang = ctx.cookies?.['fuzionx.lang'];
+    if (cookieLang) return cookieLang;
+    if (ctx._rawReq?.session?.locale) return ctx._rawReq.session.locale;
+    const al = ctx.headers?.['accept-language'];
+    if (al) {
+        const first = al.split(',')[0]?.split('-')[0];
+        if (first) return first;
     }
+    return ctx.app?.config?.get('app.i18n.default_locale', 'ko') || 'ko';
+}
 
-    /** 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;
+/**
+ * i18n 번역 함수 생성 — lazy 시점에만 호출
+ * @param {object} ctx - Context 인스턴스
+ * @returns {Function} t(key, vars) + t.all()
+ */
+function _createT(ctx) {
+    const t = (key, vars) => {
+        const locale = vars?.locale || ctx.locale;
+        if (ctx.app?.i18n) {
+            return ctx.app.i18n.translate(locale, key, vars);
         }
-        return this.app?.config?.get('app.i18n.default_locale', 'ko') || 'ko';
-    }
+        return vars?.default || key;
+    };
+    // ctx.t.all() — 현재 locale 전체 번역 데이터 (18-i18n.md)
+    t.all = () => {
+        if (ctx.app?.i18n?.getAll) {
+            return ctx.app.i18n.getAll(ctx.locale);
+        }
+        return {};
+    };
+    return t;
+}
 
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    //  응답 변환
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  공유 인스턴스 (sync 경로용 — 할당 0)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/** 사전 할당된 응답 객체 (sync 경로에서 재사용) */
+const _sharedFusionResponse = { status: 200, body: '', headers: null };
+
+/** 사전 할당된 응답 헤더 객체 (sync 경로에서 재사용) */
+const _sharedRespHeaders = {};
+
+/** 사전 할당된 Set-Cookie 배열 (sync 경로에서 재사용) */
+const _sharedSetCookies = [];
+
+/** 사전 할당된 Context 싱글톤 (sync 경로 전용 재사용) */
+const _sharedCtx = Object.create(ContextProto);
+_sharedCtx.method = '';
+_sharedCtx.url = '';
+_sharedCtx.path = '';
+_sharedCtx.query = null;
+_sharedCtx.params = null;
+_sharedCtx.headers = null;
+_sharedCtx.body = null;
+_sharedCtx.ip = '';
+_sharedCtx.files = null;
+_sharedCtx.uploadError = null;
+_sharedCtx.formFields = null;
+_sharedCtx.handlerId = 0;
+_sharedCtx.user = null;
+_sharedCtx.app = null;
+_sharedCtx.appName = null;
+_sharedCtx.theme = null;
+_sharedCtx._sessionId = null;
+_sharedCtx._rawReq = null;
+_sharedCtx._json = undefined;
+_sharedCtx._cookies = undefined;
+_sharedCtx._session = undefined;
+_sharedCtx._locale = undefined;
+_sharedCtx._t = undefined;
+_sharedCtx._setCookies = _sharedSetCookies;
+_sharedCtx._statusCode = 200;
+_sharedCtx._headers = _sharedRespHeaders;
+_sharedCtx._body = '';
+_sharedCtx._sent = false;
+_sharedCtx._res = null; // Core res 직접 참조용 (createContextFromReq에서 설정)
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Context 팩토리 함수
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-    /** Bridge 응답 포맷 { status, body, headers } */
-    toResponse() {
-        // Set-Cookie 헤더 병합
-        if (this._setCookies.length > 0) {
-            this._headers['Set-Cookie'] = this._setCookies;  // 배열 → Bridge 다중 헤더
+/**
+ * Context 인스턴스 생성 — 팩토리 패턴
+ *
+ * @param {object} rawReq - Bridge에서 전달된 raw 요청 객체
+ * @param {import('./Application.js').default} app - Application 인스턴스
+ * @param {boolean} [reusable=true] - true면 공유 인스턴스 재사용 (sync용), false면 새로 생성 (async용)
+ * @returns {object} Context 인스턴스
+ */
+export function createContext(rawReq, app, reusable = true) {
+    let ctx;
+    if (reusable) {
+        // sync 핸들러: 공유 인스턴스 리셋 후 재사용 (할당 0)
+        ctx = _sharedCtx;
+        // 이전 헤더 키 제거 (무조건 리셋)
+        const keys = Object.keys(_sharedRespHeaders);
+        for (let i = 0; i < keys.length; i++) {
+            delete _sharedRespHeaders[keys[i]];
         }
-        return {
-            status: this._statusCode,
-            body: this._body,
-            headers: this._headers,
-        };
+        ctx._headers = _sharedRespHeaders;
+        // Set-Cookie 배열 리셋
+        _sharedSetCookies.length = 0;
+        ctx._setCookies = _sharedSetCookies;
+    } else {
+        // async 핸들러: 새 인스턴스 (응답 전까지 유지 필요)
+        ctx = Object.create(ContextProto);
+        ctx._setCookies = [];
+        ctx._headers = {};
+    }
+
+    // ── 요청 프로퍼티 (핫 경로 — 즉시 할당) ──
+    ctx.method = rawReq.method || 'GET';
+    ctx.url = rawReq.url || '/';
+    ctx.path = rawReq.path || ctx.url.split('?')[0];
+    ctx.query = rawReq.query || {};
+    ctx.params = rawReq.params || {};
+    ctx.headers = rawReq.headers || {};
+    ctx.body = rawReq.body || null;
+    ctx.ip = rawReq.remoteIp || '';
+    ctx.files = rawReq.files || null;
+    ctx.uploadError = rawReq.uploadError || null;
+    ctx.formFields = rawReq.formFields || null;
+    ctx.handlerId = rawReq.handlerId;
+
+    // ── 프레임워크 주입 ──
+    ctx.app = app;
+    ctx.user = null;
+    ctx._sessionId = rawReq.sessionId || null;
+    ctx._rawReq = rawReq;
+
+    // ── lazy 캐시 초기화 (접근 시에만 생성) ──
+    ctx._json = undefined;
+    ctx._cookies = undefined;   // get cookies() 에서 lazy 파싱
+    ctx._session = undefined;   // get session() 에서 lazy 생성
+    ctx._locale = undefined;    // get locale() 에서 lazy 감지
+    ctx._t = undefined;         // get t() 에서 lazy 생성
+
+    // ── 응답 상태 리셋 ──
+    ctx._statusCode = 200;
+    ctx._body = '';
+    ctx._sent = false;
+
+    // ── 앱/테마 (디스패칭 후 설정) ──
+    ctx.appName = null;
+    ctx.theme = null;
+
+    return ctx;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Core req/res 직접 참조 팩토리 (최적화: 중간 객체 제거)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Core req/res에서 직접 Context 생성 — 중간 객체 리터럴 할당 제거
+ *
+ * ⚡ 최적화 핵심:
+ *   - Core req 프로퍼티를 직접 참조 (14-프로퍼티 중간 객체 힙 할당 제거)
+ *   - sync 경로: ctx._headers = res._headers (헤더 객체 공유 → _copyToRes 불필요)
+ *   - async 경로: 독립 인스턴스 (기존 createContext와 동일)
+ *
+ * @param {object} req - Core의 req 객체 (createReq로 생성된)
+ * @param {object|null} res - Core의 res 객체 (sync: 직접 참조, async: null)
+ * @param {import('./Application.js').default} app - Application 인스턴스
+ * @param {boolean} [reusable=true] - true면 공유 인스턴스 (sync용)
+ * @returns {object} Context 인스턴스
+ */
+export function createContextFromReq(req, res, app, reusable = true) {
+    let ctx;
+    if (reusable && res) {
+        // sync 핸들러: 공유 인스턴스 + Core res 헤더 공유 (할당 0)
+        ctx = _sharedCtx;
+        // Core res의 헤더 객체를 직접 공유 → 핸들러가 ctx._headers에 쓰면 res._headers에 반영
+        ctx._headers = res._headers;
+        // Set-Cookie 배열 리셋
+        _sharedSetCookies.length = 0;
+        ctx._setCookies = _sharedSetCookies;
+        ctx._res = res; // Core res 참조 저장
+    } else {
+        // async 핸들러: 새 인스턴스 (응답 전까지 유지 필요)
+        ctx = Object.create(ContextProto);
+        ctx._setCookies = [];
+        ctx._headers = {};
+        ctx._res = null;
+    }
+
+    // ── Core req 프로퍼티 직접 참조 (중간 객체 없이) ──
+    ctx.method = req.method || 'GET';
+    ctx.url = req.url || '/';
+    ctx.path = req.path || ctx.url.split('?')[0];
+    ctx.query = req.query || {};
+    ctx.params = req.params || {};
+    ctx.headers = req.headers || {};
+    ctx.body = req.body || req.json || null; // Core req는 body 또는 lazy json getter
+    ctx.ip = req.ip || ''; // Core req는 ip (remoteIp 아님)
+    ctx.files = req.files || null;
+    ctx.uploadError = null;
+    ctx.formFields = req.formFields || null;
+    ctx.handlerId = req.handlerId;
+
+    // ── 프레임워크 주입 ──
+    ctx.app = app;
+    ctx.user = null;
+    ctx._sessionId = req.sessionId || null;
+    ctx._rawReq = req; // Core의 req 직접 참조
+
+    // ── lazy 캐시 초기화 (접근 시에만 생성) ──
+    ctx._json = undefined;
+    ctx._cookies = undefined;
+    ctx._session = undefined;
+    ctx._locale = undefined;
+    ctx._t = undefined;
+
+    // ── 응답 상태 리셋 ──
+    ctx._statusCode = 200;
+    ctx._body = '';
+    ctx._sent = false;
+
+    // ── 앱/테마 (디스패칭 후 설정) ──
+    ctx.appName = null;
+    ctx.theme = null;
+
+    return ctx;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  하위 호환: default export = Context 클래스
+//  기존 코드에서 `new Context(rawReq, app)` 사용 시 호환
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Context 래거시 호환 클래스
+ * 기존 코드에서 `new Context(rawReq, app)` 형태로 사용 시 호환성 유지를 위해 제공.
+ * 내부에서 createContext(rawReq, app, false)를 호출하여 async-safe 인스턴스를 반환.
+ */
+export default class Context {
+    /**
+     * @param {object} rawReq - Bridge에서 전달된 raw 요청 객체
+     * @param {import('./Application.js').default} app - Application 인스턴스
+     */
+    constructor(rawReq, app) {
+        // 래거시 호환: new Context() → createContext(false) 위임
+        // 새 인스턴스(async-safe)를 생성하여 프록시 반환
+        return createContext(rawReq, app, false);
     }
 }