@gaonjs/config 0.11.0 → 0.13.0

package/dist/testkit.d.ts

@@ -1,9 +1,10 @@
 export interface TestDbHandle {
-    /** 등록한 모든 커넥션을 종료한다(afterAll 에서 호출). */
+    /** 등록한 모든 커넥션을 종료하고 배터리를 리셋한다(afterAll 에서 호출). */
     close(): Promise<void>;
 }
 /**
- * 테스트용 DB 커넥션을 등록한다(결정 111). 각 커넥션을 `<db>_test` 로 파생해
- * poolMax:1 로 붙인다. 반환값의 close() 를 afterAll 에서 호출해 정리한다.
+ * 테스트용 DB 커넥션 + DB 외 배터리(mail·storage·i18n)를 배선한다(결정 111·136).
+ * 각 커넥션을 `<db>_test` 로 파생해 poolMax:1 로 붙이고, 스토리지·메일을 테스트
+ * 격리 값으로 배선한다. 반환값의 close() 를 afterAll 에서 호출해 정리한다.
  */
 export declare function connectTestDatabase(cwd?: string): Promise<TestDbHandle>;

package/dist/testkit.js

@@ -1,15 +1,24 @@
-// @gaonjs/config · 테스트 DB 커넥션 배선 (결정 111)
+// @gaonjs/config · 테스트 DB·배터리 배선 (결정 111 · 결정 136)
 //
 // gaon.config 의 각 커넥션을 `<db>_test` 로 파생해 등록한다 — `gaon test` 가 미리
 // 만들어 마이그레이션한 그 DB 다. 스캐폴드 `test/setup.ts` 가 부트스트랩으로 쓰고,
 // 매 테스트 뒤 `truncateAll()` 로 격리한다(§9 실 인프라 · 근거는 결정 111).
 //
-// wireGaon 과 달리 Redis·NATS·mail 은 배선하지 않는다 — DB 격리만 담당한다.
+// Redis·NATS 는 배선하지 않는다(웹 전용). mail·storage·i18n 은 serve·work 와 같은
+// 경로(configureNonDbBatteries)로 배선한다 — 스토리지·메일을 쓰는 잡·서비스가
+// 테스트에서도 운영과 같은 코드로 돌아야 한다(결정 136 · "wireDomain 안 태워 테스트만
+// 깨지던" 사각). 스토리지 s3 버킷은 `<bucket>-test`, 로컬 root 는 `<root>-test` 로
+// 격리한다(<db>_test 대칭). MailPit 은 dev 이자 테스트 sink(캡처 · 외부 발송 없음).
 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';
 /**
- * 테스트용 DB 커넥션을 등록한다(결정 111). 각 커넥션을 `<db>_test` 로 파생해
- * poolMax:1 로 붙인다. 반환값의 close() 를 afterAll 에서 호출해 정리한다.
+ * 테스트용 DB 커넥션 + DB 외 배터리(mail·storage·i18n)를 배선한다(결정 111·136).
+ * 각 커넥션을 `<db>_test` 로 파생해 poolMax:1 로 붙이고, 스토리지·메일을 테스트
+ * 격리 값으로 배선한다. 반환값의 close() 를 afterAll 에서 호출해 정리한다.
  */
 export async function connectTestDatabase(cwd = process.cwd()) {
     const config = await loadGaonConfig(cwd);
@@ -20,9 +29,33 @@ export async function connectTestDatabase(cwd = process.cwd()) {
             registerConnection(key, createDb(testCfg), base.adapter);
         }
     }
+    // 결정 136: 스토리지·메일·i18n 을 serve·work 와 같은 경로로 배선(테스트 격리 값).
+    await configureNonDbBatteries(config, cwd, {
+        bucketFor: (b) => `${b}-test`,
+        localRootFor: (r) => `${r}-test`,
+    });
+    // 결정 143(12차 W5): 잡·이벤트 전송을 serve·work 와 같은 경로로 배선한다. 이게 없으면
+    // 테스트에서 도는 도메인 서비스가 `.later()`·emit() 를 할 때 "전송 미설정" 으로 깨졌다 —
+    // 운영과 같은 코드가 테스트에서만 실패하는 사각(11차 W4 연장). 스트림/subject 격리는
+    // GAON_STREAM_PREFIX(결정 130 · gaon test 가 세팅)로 자동 적용된다.
+    let nats;
+    if (config.nats) {
+        nats = await connectNats({ servers: config.nats.url, name: config.nats.name ?? 'gaon-test' });
+        configureJobs(nats);
+        configureEvents(nats);
+        configureBroadcast(nats); // 결정 126: 잡·리스너에서 broadcast() 사용.
+    }
     return {
         close: async () => {
             await destroyAllConnections();
+            resetStorage();
+            resetI18n();
+            // 잡·이벤트·broadcast 배선 해제 후 NATS 종료(다음 테스트 파일로 상태 누출 방지).
+            resetJobs();
+            resetEvents();
+            resetBroadcast();
+            if (nats)
+                await nats.close();
         },
     };
 }

package/dist/wire.d.ts

@@ -27,6 +27,24 @@ export interface WiredDomain {
  * 세션·NATS 잡 발행·Fastify)은 여기 두지 않는다 — wireGaon 이 이 위에 얹는다.
  */
 export declare function wireDomain(config: GaonConfig, cwd?: string): Promise<WiredDomain>;
+/** DB 외 배터리 배선 옵션. 테스트 하네스가 격리 값을 주입할 때 쓴다(결정 136). */
+export interface NonDbBatteryOptions {
+    /**
+     * s3 디스크 버킷명 변환기. 테스트 하네스가 `<bucket>-test` 로 격리할 때 준다
+     * (`<db>_test` 대칭). 생략 = 원본 버킷 그대로. 로컬 디스크는 root 를 변환한다.
+     */
+    readonly bucketFor?: (bucket: string) => string;
+    /** 로컬 디스크 root 변환기(테스트 임시 디렉터리 격리). 생략 = 원본 그대로. */
+    readonly localRootFor?: (root: string) => string;
+}
+/**
+ * mail · storage · i18n 을 프로세스 전역에 배선한다(결정 136). wireDomain(serve·work)
+ * 과 테스트 하네스(connectTestDatabase)가 공유하는 단일 경로다 — 스토리지·메일을
+ * 쓰는 잡·서비스가 테스트에서도 운영과 같은 코드로 돌아야 한다("wireDomain 안 태워
+ * 테스트만 깨지던" 사각 · §13.9). DB 는 여기서 다루지 않는다(테스트는 <db>_test 로,
+ * 운영은 config.db 로 각자 등록).
+ */
+export declare function configureNonDbBatteries(config: GaonConfig, cwd?: string, opts?: NonDbBatteryOptions): Promise<void>;
 /**
  * gaon.config.ts + apps/ 를 바탕으로 배터리를 배선하고 Fastify 앱을 만든다.
  *

package/dist/wire.js

@@ -7,8 +7,8 @@
 // 세션은 세션 옵션이 세팅된 앱에만 등록된다. AppSessionOptions.secret 은
 // 필수이므로 auth 앱은 명시적으로 secret 을 제공해야 한다(env 로 주입 권장).
 import { Redis } from 'ioredis';
-import { createDb, registerConnection, destroyAllConnections, } from '@gaonjs/data';
-import { connectNats, configureJobs } from '@gaonjs/async';
+import { createDb, registerConnection, destroyAllConnections, getConnection, hasConnection, setServiceTxWrapper, } from '@gaonjs/data';
+import { connectNats, configureJobs, configureEvents, outboxServiceTxWrapper, ensureOutboxTable, } from '@gaonjs/async';
 import { configureMailer, smtpTransport } from '@gaonjs/mail';
 import { configureStorage, localDisk, s3Disk, resetStorage } from '@gaonjs/storage';
 import { configureI18n, loadLocales, resetI18n } from '@gaonjs/i18n';
@@ -32,7 +32,29 @@ export async function wireDomain(config, cwd = process.cwd()) {
             registerConnection(key, db, cfg.adapter);
         }
     }
-    // 2) mail — SMTP 전송(개발은 MailPit, 운영은 실 SMTP).
+    // 2~4) mail · storage · i18n — DB 외 프로세스 전역 배터리. serve·work·테스트
+    //       하네스가 공유한다(결정 136 · gaon test 도 이 경로를 태워야 스토리지·메일
+    //       잡이 테스트에서 실제로 돈다).
+    await configureNonDbBatteries(config, root);
+    return {
+        config,
+        async closeDomain() {
+            await destroyAllConnections();
+            resetStorage();
+            resetI18n();
+        },
+    };
+}
+/**
+ * mail · storage · i18n 을 프로세스 전역에 배선한다(결정 136). wireDomain(serve·work)
+ * 과 테스트 하네스(connectTestDatabase)가 공유하는 단일 경로다 — 스토리지·메일을
+ * 쓰는 잡·서비스가 테스트에서도 운영과 같은 코드로 돌아야 한다("wireDomain 안 태워
+ * 테스트만 깨지던" 사각 · §13.9). DB 는 여기서 다루지 않는다(테스트는 <db>_test 로,
+ * 운영은 config.db 로 각자 등록).
+ */
+export async function configureNonDbBatteries(config, cwd = process.cwd(), opts = {}) {
+    const root = resolvePath(cwd);
+    // mail — SMTP 전송(개발·테스트는 MailPit sink, 운영은 실 SMTP).
     if (config.mail) {
         const m = config.mail;
         configureMailer({
@@ -45,18 +67,19 @@ export async function wireDomain(config, cwd = process.cwd()) {
             defaultFrom: m.defaultFrom,
         });
     }
-    // 3) storage — 로컬(기본) 또는 S3.
+    // storage — 로컬(기본) 또는 S3. 테스트는 버킷/roots 를 격리 값으로 변환(opts).
     if (config.storage) {
         const disks = {};
         for (const [name, d] of Object.entries(config.storage.disks)) {
             if (d.driver === 'local') {
                 // root 는 프로젝트 상대 경로면 cwd 로 절대화.
-                const root2 = d.root.startsWith('/') ? d.root : join(root, d.root);
+                const base = d.root.startsWith('/') ? d.root : join(root, d.root);
+                const root2 = opts.localRootFor ? opts.localRootFor(base) : base;
                 disks[name] = localDisk({ root: root2, baseUrl: d.publicUrl });
             }
             else {
                 disks[name] = s3Disk({
-                    bucket: d.bucket,
+                    bucket: opts.bucketFor ? opts.bucketFor(d.bucket) : d.bucket,
                     region: d.region,
                     endpoint: d.endpoint,
                     credentials: d.accessKeyId && d.secretAccessKey
@@ -69,7 +92,7 @@ export async function wireDomain(config, cwd = process.cwd()) {
         }
         configureStorage({ default: config.storage.default, disks });
     }
-    // 4) i18n — locales/ 로드 후 초기화.
+    // i18n — locales/ 로드 후 초기화.
     if (config.i18n) {
         const dir = config.i18n.dir ?? 'locales';
         const abs = dir.startsWith('/') ? dir : join(root, dir);
@@ -80,14 +103,6 @@ export async function wireDomain(config, cwd = process.cwd()) {
             supportedLngs: config.i18n.supportedLngs,
         });
     }
-    return {
-        config,
-        async closeDomain() {
-            await destroyAllConnections();
-            resetStorage();
-            resetI18n();
-        },
-    };
 }
 /**
  * gaon.config.ts + apps/ 를 바탕으로 배터리를 배선하고 Fastify 앱을 만든다.
@@ -110,15 +125,22 @@ export async function wireGaon(config, cwd = process.cwd()) {
     if (config.redis) {
         redis = new Redis(config.redis.url, { lazyConnect: false, maxRetriesPerRequest: 3 });
     }
-    // 3) NATS — 웹 프로세스도 채널·잡 publish 를 위해 연결한다.
-    //    연결만으로는 부족하다 — 잡 전송 런타임(configureJobs)까지 배선해야
-    //    컨트롤러의 `.later()` 가 실제로 publish 된다. 이걸 빠뜨리면 웹에서
-    //    잡 발행 시 "잡 전송이 설정되지 않았습니다" 로 깨진다(work 는 runWork
-    //    가 이미 설정하지만 serve 는 여기서 해야 한다).
+    // 3) NATS — 웹 프로세스도 채널·잡·이벤트 publish 를 위해 연결한다.
+    //    연결만으로는 부족하다 — 전송 런타임까지 배선해야 컨트롤러·서비스의
+    //    `.later()`·`emit()` 이 실제로 publish 된다(work 는 runWork 가 이미 설정하지만
+    //    serve 는 여기서 해야 한다).
     let nats;
     if (config.nats) {
         nats = await connectNats({ servers: config.nats.url, name: config.nats.name ?? 'gaon-serve' });
         configureJobs(nats);
+        // 결정 144(F2a): 이벤트 전송 배선 — 이게 없으면 웹 요청 emit() 이 "전송 미설정" 500.
+        configureEvents(nats);
+        // 결정 144(A): 서비스 트랜잭션 emit → 같은 트랜잭션으로 _gaon_outbox 적재(이중 쓰기
+        // 방지). @gaonjs/async 의 아웃박스 래퍼를 data 의 service() 트랜잭션에 주입하고,
+        // 적재 대상 테이블을 main 커넥션에 보장한다(worker 의 릴레이가 그 행을 발행한다).
+        setServiceTxWrapper(outboxServiceTxWrapper());
+        if (hasConnection('main'))
+            await ensureOutboxTable(getConnection('main'));
     }
     // 5) 앱 스캔 · createApp.
     const apps = await resolveApps(root);
@@ -193,6 +215,8 @@ export async function wireGaon(config, cwd = process.cwd()) {
                 await nats.close();
             if (redis)
                 redis.disconnect();
+            // 결정 144: 서비스 트랜잭션 래퍼 배선 해제(다음 wireGaon 인스턴스로 누출 방지).
+            setServiceTxWrapper(undefined);
             await domain.closeDomain();
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/config",
-  "version": "0.11.0",
+  "version": "0.13.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.8.0",
-    "@gaonjs/data": "0.13.1",
+    "@gaonjs/async": "0.9.0",
     "@gaonjs/core": "0.2.1",
-    "@gaonjs/storage": "0.1.2",
+    "@gaonjs/i18n": "0.1.2",
+    "@gaonjs/data": "0.15.0",
     "@gaonjs/mail": "0.1.3",
-    "@gaonjs/web": "0.14.0",
-    "@gaonjs/i18n": "0.1.2"
+    "@gaonjs/storage": "0.1.2",
+    "@gaonjs/web": "0.15.0"
   },
   "devDependencies": {
     "fastify": "^5.0.0"