@gaonjs/config 0.13.0 → 0.14.0

package/dist/testkit.js

@@ -13,8 +13,8 @@ import { loadGaonConfig } from './load.js';
 import { configureNonDbBatteries } from './wire.js';
 import { resetStorage } from '@gaonjs/storage';
 import { resetI18n } from '@gaonjs/i18n';
-import { connectNats, configureJobs, configureEvents, configureBroadcast, resetJobs, resetEvents, resetBroadcast, } from '@gaonjs/async';
-import { createDb, registerConnection, deriveTestDatabaseConfig, destroyAllConnections, } from '@gaonjs/data';
+import { connectNats, configureJobs, configureEvents, configureBroadcast, resetJobs, resetEvents, resetBroadcast, outboxServiceTxWrapper, ensureOutboxTable, } from '@gaonjs/async';
+import { createDb, registerConnection, deriveTestDatabaseConfig, destroyAllConnections, setServiceTxWrapper, getConnection, hasConnection, } from '@gaonjs/data';
 /**
  * 테스트용 DB 커넥션 + DB 외 배터리(mail·storage·i18n)를 배선한다(결정 111·136).
  * 각 커넥션을 `<db>_test` 로 파생해 poolMax:1 로 붙이고, 스토리지·메일을 테스트
@@ -44,6 +44,13 @@ export async function connectTestDatabase(cwd = process.cwd()) {
         configureJobs(nats);
         configureEvents(nats);
         configureBroadcast(nats); // 결정 126: 잡·리스너에서 broadcast() 사용.
+        // 결정 144(테스트 짝): 서비스 트랜잭션 emit 을 아웃박스로 스테이징하는 래퍼를
+        // serve·work 의 wireGaon 과 같이 배선한다. 이게 없으면 테스트의 service() 가
+        // currentOutbox() 없이 즉시발행 경로를 타, "롤백 시 미발행" 보장이 표준 하네스에서
+        // 공허하게 통과했다(13차 프로브 실측 · 결정 143 은 넣었는데 144 는 빠진 비대칭).
+        setServiceTxWrapper(outboxServiceTxWrapper());
+        if (hasConnection('main'))
+            await ensureOutboxTable(getConnection('main'));
     }
     return {
         close: async () => {
@@ -54,6 +61,8 @@ export async function connectTestDatabase(cwd = process.cwd()) {
             resetJobs();
             resetEvents();
             resetBroadcast();
+            // 결정 144: 서비스 트랜잭션 래퍼 해제(다음 테스트 파일로 누출 방지 · wireGaon close 대칭).
+            setServiceTxWrapper(undefined);
             if (nats)
                 await nats.close();
         },

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectionConfig } from '@gaonjs/data';
 import type { SecurityOptions, ClientIpConfig } from '@gaonjs/web';
-import type { AuthOptions, JwtAuthOptions } from '@gaonjs/web';
+import type { AuthOptions, JwtAuthOptions, SharedPropsFn } from '@gaonjs/web';
 /**
  * DB 커넥션 맵 — 키는 커넥션 이름(§4.5), 값은 어댑터 설정. `main` 은 관례
  * (스키마가 `{ db: 'legacy' }` 처럼 명시하지 않으면 main 으로 붙는다).
@@ -56,7 +56,7 @@ export interface StorageConfig {
     readonly default: string;
     readonly disks: Record<string, StorageDiskConfig>;
 }
-/** i18n — locales/ 로드 옵션. */
+/** i18n — locales/ 로드 + 요청별 로케일 협상 옵션(결정 159 · 13차 W1). */
 export interface I18nConfig {
     /** locales/ 디렉토리 경로 (cwd 기준 상대). 생략 시 'locales'. */
     readonly dir?: string;
@@ -64,6 +64,16 @@ export interface I18nConfig {
     readonly fallbackLng: string;
     /** 허용 언어(생략 시 locales 폴더 하위 언어들). */
     readonly supportedLngs?: readonly string[];
+    /**
+     * 요청별 로케일 감지(결정 159 · W1). i18n 설정이 있으면 `gaon serve`/`gaon dev` 가
+     * 매 요청 자동으로 detectLanguage → enterLanguage 를 배선한다(자동 · opt-in 아님).
+     */
+    readonly detect?: {
+        /** 로케일 쿠키 이름. 생략 시 'gaon_locale'. `this.setLocale()` 이 이 쿠키를 쓴다. */
+        readonly cookieName?: string;
+        /** 출처 우선순위. 생략 시 ['session','cookie','header']. */
+        readonly priority?: readonly ('session' | 'cookie' | 'header')[];
+    };
 }
 /** 웹 서버 부팅 옵션 — `gaon serve` 가 소비. */
 export interface WebConfig {
@@ -159,6 +169,13 @@ export interface AppConfig {
     readonly seal?: boolean | {
         readonly except?: readonly string[];
     };
+    /**
+     * 결정 150: 앱 전역 공유 prop 제공자. 요청마다 실행돼 반환 객체가 이 앱의 모든 렌더
+     * shared 에 병합된다 — 코어 3종(currentUser·csrf·flash)은 예약이라 덮지 못한다.
+     * 페이지는 `useShared()` 로 읽는다(gaonjs/vue GaonSharedProps 선언 병합으로 타입 확장):
+     *   sharedProps: (ctx) => ({ locale: ctx.session?.locale ?? 'en' })
+     */
+    readonly sharedProps?: SharedPropsFn;
 }
 /** 타입 안전 헬퍼 — `export default defineAppConfig({...})`. */
 export declare function defineAppConfig(config: AppConfig): AppConfig;

package/dist/wire.js

@@ -7,11 +7,11 @@
 // 세션은 세션 옵션이 세팅된 앱에만 등록된다. AppSessionOptions.secret 은
 // 필수이므로 auth 앱은 명시적으로 secret 을 제공해야 한다(env 로 주입 권장).
 import { Redis } from 'ioredis';
-import { createDb, registerConnection, destroyAllConnections, getConnection, hasConnection, setServiceTxWrapper, } from '@gaonjs/data';
-import { connectNats, configureJobs, configureEvents, outboxServiceTxWrapper, ensureOutboxTable, } from '@gaonjs/async';
+import { createDb, registerConnection, destroyAllConnections, getConnection, hasConnection, setServiceTxWrapper, setCacheBackend, redisCacheBackend, } from '@gaonjs/data';
+import { connectNats, configureJobs, configureEvents, outboxServiceTxWrapper, ensureOutboxTable, setLockBackend, redisLockBackend, memoryLockBackend, } from '@gaonjs/async';
 import { configureMailer, smtpTransport } from '@gaonjs/mail';
 import { configureStorage, localDisk, s3Disk, resetStorage } from '@gaonjs/storage';
-import { configureI18n, loadLocales, resetI18n } from '@gaonjs/i18n';
+import { configureI18n, loadLocales, resetI18n, detectLanguage, enterLanguage, languages, } from '@gaonjs/i18n';
 import { createApp, redisSessionStore } from '@gaonjs/web';
 import { resolveApps, toAppSpec } from './apps.js';
 import { existsSync } from 'node:fs';
@@ -125,6 +125,19 @@ export async function wireGaon(config, cwd = process.cwd()) {
     if (config.redis) {
         redis = new Redis(config.redis.url, { lazyConnect: false, maxRetriesPerRequest: 3 });
     }
+    // 결정 147: 분산 락 백엔드 배선. redis 가 있으면 진짜 분산 락(Redis SET NX PX),
+    // 없으면 dev/테스트용 in-memory 폴백을 심는다. prod 에서 redis 미설정이면 여기서
+    // 아무 것도 안 심어 lock() 은 미설정 백엔드로 남아 사용 시 수리 안내로 throw 한다
+    // (로컬 뮤텍스로 조용히 떨어지지 않는다 · 결정 88 ①).
+    if (redis)
+        setLockBackend(redisLockBackend(redis));
+    else if (process.env.NODE_ENV !== 'production')
+        setLockBackend(memoryLockBackend());
+    // 결정 148: 캐시 백엔드 배선. redis 가 있으면 Redis 캐시(§7.4), 없으면 data 의
+    // 기본 in-memory 폴백을 그대로 둔다(캐시는 best-effort 라 미설정 폴백이 안전 ·
+    // 락과 다른 지점 · 결정 147).
+    if (redis)
+        setCacheBackend(redisCacheBackend(redis));
     // 3) NATS — 웹 프로세스도 채널·잡·이벤트 publish 를 위해 연결한다.
     //    연결만으로는 부족하다 — 전송 런타임까지 배선해야 컨트롤러·서비스의
     //    `.later()`·`emit()` 이 실제로 publish 된다(work 는 runWork 가 이미 설정하지만
@@ -169,6 +182,10 @@ export async function wireGaon(config, cwd = process.cwd()) {
         if (ac?.auth && typeof ac.auth.loadUser === 'function') {
             spec = { ...spec, auth: ac.auth };
         }
+        // 결정 150: app.config 의 sharedProps 제공자를 AppSpec 으로 전달한다(앱 전역 공유 prop).
+        if (typeof ac?.sharedProps === 'function') {
+            spec = { ...spec, sharedProps: ac.sharedProps };
+        }
         if (ac?.session?.secret && redis) {
             spec = {
                 ...spec,
@@ -183,12 +200,21 @@ export async function wireGaon(config, cwd = process.cwd()) {
                 },
             };
         }
+        // 결정 159(W1): i18n 설정이 있으면 this.setLocale() 이 쓸 로케일 쿠키 이름을 배선
+        // (detectLanguage 가 읽는 이름과 일치 · 기본 gaon_locale).
+        if (config.i18n) {
+            spec = { ...spec, localeCookie: config.i18n.detect?.cookieName ?? 'gaon_locale' };
+        }
         return spec;
     });
     const opts = {
         apps: specs,
         version: config.web?.assetsVersion,
         cookieSecret: config.web?.cookieSecret,
+        // 결정 159(W1): i18n 설정이 있으면 매 요청 로케일을 협상해 ALS 에 심는다(자동 배선).
+        // createApp 의 onRequest 슬롯이 이 통로다(web↔i18n 결합 회피). 이게 없으면
+        // detectLanguage·enterLanguage 가 죽은 코드라 t() 가 항상 fallback 이었다(반쪽 배선).
+        onRequest: config.i18n ? makeI18nOnRequest(config.i18n) : undefined,
         // 보안 기본값 조정(생략 시 코어 기본값 전부 켬 · CLAUDE.md 규칙 8).
         security: config.web?.security,
         // 결정 131: 스토리지 오리진 CSP 자동 배선(설정 있으면 img-src·connect-src 에 부착).
@@ -215,12 +241,57 @@ export async function wireGaon(config, cwd = process.cwd()) {
                 await nats.close();
             if (redis)
                 redis.disconnect();
+            // 결정 147: 락 백엔드 배선 해제(다음 wireGaon 인스턴스로 누출 방지).
+            setLockBackend(undefined);
+            // 결정 148: 캐시 백엔드 배선 해제(메모리 폴백으로 되돌림 · 인스턴스 누출 방지).
+            setCacheBackend(undefined);
             // 결정 144: 서비스 트랜잭션 래퍼 배선 해제(다음 wireGaon 인스턴스로 누출 방지).
             setServiceTxWrapper(undefined);
             await domain.closeDomain();
         },
     };
 }
+/**
+ * 결정 159(W1): 요청별 로케일 협상 훅을 만든다. 매 요청 header(Accept-Language)·
+ * cookie(gaon_locale)·session(가능 시)에서 로케일을 감지해 ALS 에 심는다 → 이후 같은
+ * 요청의 모든 t() 가 그 로케일로 번역된다. 세션은 앱 스코프라 이 전역 훅 시점엔 대개
+ * 없지만, setLocale 이 쿠키에도 함께 기록하므로 쿠키가 그 선택을 실어 나른다.
+ */
+function makeI18nOnRequest(i18n) {
+    const cookieName = i18n.detect?.cookieName ?? 'gaon_locale';
+    const priority = i18n.detect?.priority;
+    return (request) => {
+        const supported = languages();
+        if (supported.length === 0)
+            return; // i18n 미구성 — 폴백만.
+        const h = request.headers['accept-language'];
+        const header = typeof h === 'string' ? h : undefined;
+        const rawCookie = request.headers['cookie'];
+        const cookie = readLocaleCookie(typeof rawCookie === 'string' ? rawCookie : undefined, cookieName);
+        // 세션은 앱 스코프라 전역 훅 시점엔 대개 없다(있으면 읽고, 없으면 쿠키가 실어 나른다).
+        const session = request.session?.locale;
+        enterLanguage(detectLanguage({ header, cookie, session }, { supported, fallback: i18n.fallbackLng, priority }));
+    };
+}
+/** Cookie 헤더에서 로케일 쿠키 값을 뽑는다(@fastify/cookie 파싱 순서 이전에 도는 훅용). */
+function readLocaleCookie(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() === name) {
+            try {
+                return decodeURIComponent(part.slice(eq + 1).trim());
+            }
+            catch {
+                return part.slice(eq + 1).trim();
+            }
+        }
+    }
+    return undefined;
+}
 // redisSessionStore 는 참조만 유지(트리 셰이킹 방지 · 향후 캐시 재사용).
 void redisSessionStore;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/config",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Gaon 루트 설정 로더·자동 배선 (gaon.config.ts · §3.3 · M9-A)",
   "type": "module",
   "license": "MIT",
@@ -25,13 +25,13 @@
   ],
   "dependencies": {
     "ioredis": "^5.4.1",
-    "@gaonjs/async": "0.9.0",
     "@gaonjs/core": "0.2.1",
-    "@gaonjs/i18n": "0.1.2",
-    "@gaonjs/data": "0.15.0",
-    "@gaonjs/mail": "0.1.3",
+    "@gaonjs/data": "0.16.0",
+    "@gaonjs/async": "0.10.0",
+    "@gaonjs/i18n": "0.2.0",
+    "@gaonjs/mail": "0.2.0",
     "@gaonjs/storage": "0.1.2",
-    "@gaonjs/web": "0.15.0"
+    "@gaonjs/web": "0.16.0"
   },
   "devDependencies": {
     "fastify": "^5.0.0"