mega-framework 0.1.6 → 0.1.8

package/src/core/mega-cluster.js

@@ -32,7 +32,10 @@ export class MegaCluster {
    * @param {Object} [opts]
    * @param {number | 'max'} [opts.instances] - 워커 수. 'max' 면 CPU 코어 수.
    * @param {boolean} [opts.respawn=true] - 워커 crash 시 자동 재시작
-   * @param {number} [opts.gracePeriodMs=30000] - SIGTERM 후 강제 kill 까지 대기
+   * @param {number} [opts.gracePeriodMs=30000] - SIGTERM 후 강제 kill 까지 대기. ⚠️ 워커가
+   *   `MegaShutdown.setupSignals()` 를 쓰면 워커 종료 예산 상한은 hardKill(기본 60s)이다 — 마스터 grace 가
+   *   그보다 작으면 워커 drain 도중 SIGKILL 되는 예산 역전이 생긴다. `mega start` CLI 는
+   *   `DEFAULT_HARD_KILL_MS + 5s` 로 위계화해 전달한다(직접 생성 시에도 동일 권장).
    * @param {import('node:cluster').Cluster} [opts._cluster] - 테스트용 cluster 주입(기본 node:cluster). per ADR-165
    * @param {NodeJS.Process} [opts._proc] - 테스트용 process 주입(기본 전역 process). per ADR-165
    * @param {{ info?: Function, warn?: Function, error?: Function } | null} [opts.logger] - 조율 로그용 pino 로거.

package/src/core/mega-server.js

@@ -2,6 +2,22 @@
 import { createServer as createHttpServer } from 'node:http'
 import { MegaConfigError } from '../errors/config-error.js'
 
+/**
+ * Host 헤더에서 hostname 만 추출한다 (소문자 정규화). IPv6 리터럴(`[::1]:3000`)은 hostname 자체가
+ * 콜론을 포함하므로 단순 `split(':')` 으로는 `'['` 가 나와 vhost 매칭이 전부 깨진다 — 대괄호 형식이면
+ * 괄호 안(`::1`)을, 아니면 첫 콜론 앞(포트 제거)을 취한다.
+ * @param {unknown} hostHeader - `req.headers.host` 원본.
+ * @returns {string}
+ */
+export function hostnameOf(hostHeader) {
+  const h = String(hostHeader || '')
+  if (h.startsWith('[')) {
+    const end = h.indexOf(']')
+    return (end === -1 ? h.slice(1) : h.slice(1, end)).toLowerCase()
+  }
+  return h.split(':')[0].toLowerCase()
+}
+
 /**
  * MegaServer — 여러 MegaApp 을 하나의 HTTP 서버에서 호스트네임 기반으로 라우팅.
  *
@@ -17,7 +33,9 @@ import { MegaConfigError } from '../errors/config-error.js'
  */
 export class MegaServer {
   /**
-   * @param {{ port?: number, host?: string }} [opts] - listen 기본값 (listen() 인자로 override 가능)
+   * @param {{ port?: number, host?: string, logger?: { debug?: Function, warn?: Function } }} [opts] -
+   *   listen 기본값 (listen() 인자로 override 가능). `logger` 는 pino 호환 로거(선택) — 미매핑 host
+   *   404·upgrade 소켓 에러 같은 비치명 이벤트를 구조적으로 남긴다(미주입 시 console 폴백).
    */
   constructor(opts = {}) {
     /** @type {Map<string, import('./mega-app.js').MegaApp>} */
@@ -26,6 +44,8 @@ export class MegaServer {
     this._apps = []
     /** @type {import('node:http').Server | null} */
     this._httpServer = null
+    /** @type {{ debug?: Function, warn?: Function } | null} */
+    this._log = opts.logger ?? null
     this._opts = opts
   }
 
@@ -73,6 +93,10 @@ export class MegaServer {
     if (this._apps.length === 0) {
       throw new Error('MegaServer.listen: no MegaApps mounted')
     }
+    // 재호출 가드 — 호출마다 새 http.Server 를 만들면 기존 서버(리스너·소켓)가 참조만 잃고 누수된다.
+    if (this._httpServer) {
+      throw new Error('MegaServer.listen: already listening — call close() first.')
+    }
 
     // 모든 Fastify 인스턴스 ready (라우트 등록 완료 보장)
     for (const app of this._apps) {
@@ -80,10 +104,12 @@ export class MegaServer {
     }
 
     this._httpServer = createHttpServer((req, res) => {
-      const hostHeader = String(req.headers.host || '')
-      const hostname = hostHeader.split(':')[0].toLowerCase()
+      const hostname = hostnameOf(req.headers.host)
       const app = this._hostMap.get(hostname)
       if (!app) {
+        // 등록 host 목록은 응답에 싣지 않는다 — 임의 클라이언트에게 내부 도메인 구성이 노출된다.
+        // 운영자 디버그용 목록은 debug 로그로만 남긴다.
+        this._log?.debug?.({ hostname, knownHosts: [...this._hostMap.keys()] }, 'host.not_mounted (404)')
         res.statusCode = 404
         res.setHeader('content-type', 'application/json')
         res.end(
@@ -91,7 +117,7 @@ export class MegaServer {
             ok: false,
             error: {
               code: 'host.not_mounted',
-              message: `No app mounted for host '${hostname}'. Known hosts: ${[...this._hostMap.keys()].join(', ')}`,
+              message: `No app mounted for host '${hostname}'.`,
             },
           }),
         )
@@ -106,16 +132,16 @@ export class MegaServer {
     // WS HTTP Upgrade 핸들오프 — 호스트 분기 후 해당 MegaApp 에 위임.
     // Fastify 는 (websocket 플러그인 없으면) 'upgrade' 를 듣지 않으므로 여기서 직접 배선한다.
     this._httpServer.on('upgrade', (req, socket, head) => {
-      const hostHeader = String(req.headers.host || '')
-      const hostname = hostHeader.split(':')[0].toLowerCase()
+      const hostname = hostnameOf(req.headers.host)
       const app = this._hostMap.get(hostname)
       if (!app) {
         // 매핑 안 된 host 의 upgrade 는 거부 (소켓 파괴). HTTP 404 와 동일 정책.
         // L4: destroy 전 error 가드. listener 없는 raw 소켓이 ECONNRESET 등으로 uncaught
-        // exception → 프로세스 크래시 하는 것을 막는다 (H1 과 동일 패턴). MegaServer 는
-        // 아직 pino 미통합이라 비치명적 소켓 에러는 console.warn 으로 명시 로그.
+        // exception → 프로세스 크래시 하는 것을 막는다 (H1 과 동일 패턴). 비치명적 소켓 에러는
+        // 주입 로거(warn)로, 미주입이면 console.warn 폴백으로 명시 로그.
         socket.on('error', (err) => {
-          console.warn('[MegaServer] raw socket error on unmapped-host upgrade:', err?.message ?? err)
+          if (this._log?.warn) this._log.warn({ err, hostname }, 'raw socket error on unmapped-host upgrade')
+          else console.warn('[MegaServer] raw socket error on unmapped-host upgrade:', err?.message ?? err)
         })
         socket.destroy()
         return
@@ -134,6 +160,9 @@ export class MegaServer {
       // 다른 쪽 리스너를 제거해 누수를 막는다.
       const onError = (/** @type {Error} */ err) => {
         httpServer.removeListener('listening', onListening)
+        // listen 실패(EADDRINUSE 등)한 서버는 참조를 비운다 — 남기면 재호출 가드가 "이미 listening"
+        // 으로 오인해 같은 인스턴스의 재시도(포트 바꿔 listen)가 막힌다.
+        this._httpServer = null
         reject(err)
       }
       const onListening = () => {
@@ -167,6 +196,8 @@ export class MegaServer {
         this._httpServer.close((err) => (err ? reject(err) : resolve(undefined)))
       })
     }
+    // 참조 해제 — listen() 재호출 가드가 "이미 listening" 과 "close 후 재기동" 을 구분할 수 있게 한다.
+    this._httpServer = null
   }
 
   /** 등록된 호스트 목록 (디버그·테스트용). */

package/src/core/migration/dialect-registry.js

@@ -0,0 +1,107 @@
+// @ts-check
+/**
+ * Dialect 레지스트리 (ADR-204/205) — adapter driver 이름 → SQL 렌더 dialect 매핑 + **contract 검증**.
+ *
+ * dialect 는 `dialects/README.md` 의 표준 인터페이스(함수 12 + 속성 7)를 전부 구현해야 한다 —
+ * differ/generate 는 이 표면만 호출하므로, M-6(maria/sqlite) 확장은 dialect 모듈 추가만으로 동작한다.
+ * 미구현 멤버는 등록 조회 시점에 fail-fast(`migration.dialect_contract`) — 런타임 한가운데서
+ * undefined 호출로 죽는 것을 차단.
+ *
+ * 미지원 driver 는 **명시 fail-fast** —
+ * 조용히 건너뛰면 사용자가 "스키마를 선언했는데 마이그레이션이 안 나온다" 를 모른다(P7).
+ *
+ * @module core/migration/dialect-registry
+ */
+import { MegaConfigError } from '../../errors/config-error.js'
+import * as postgres from './dialects/postgres.js'
+import * as maria from './dialects/maria.js'
+import * as sqlite from './dialects/sqlite.js'
+import * as mongo from './dialects/mongo.js'
+
+/** 표준 인터페이스 — 함수 멤버 (dialects/README.md 정본). */
+const CONTRACT_FNS = [
+  'renderOps', 'renderOp',
+  'quoteIdent', 'quoteLiteral', 'enumCheckExpr',
+  'indexName', 'resolveIndexName', 'uniqueName', 'fkName', 'checkName', 'pkName', 'inlinePkName',
+]
+
+/** 표준 인터페이스 — 능력/한계 속성 멤버 (boolean | number | string). */
+const CONTRACT_PROPS = [
+  'identifierMaxBytes',
+  'supportsConcurrentIndex',
+  'enumStrategy',
+  'supportsRenameInTx',
+  'canDropColumnInTx',
+  'dependsOnRebuild',
+  'supportsRenameConstraint',
+  'supportsAlterAddFk',
+  'requiresDropFkBeforeDropColumn',
+  'usesSqlDdl',
+]
+
+/** @type {Record<string, Record<string, any>>} driver → dialect. */
+const DIALECTS = {
+  postgres,
+  mariadb: maria,
+  sqlite,
+  mongodb: mongo,
+}
+
+/** 자동 생성을 지원하는 driver 목록. */
+export const SUPPORTED_DRIVERS = Object.keys(DIALECTS)
+
+/**
+ * dialect 의 contract 충족 검증 — 미구현 멤버 목록을 모아 한 번에 보고.
+ * @param {string} driver @param {Record<string, any>} dialect
+ * @throws {MegaConfigError} `migration.dialect_contract`
+ */
+export function assertDialectContract(driver, dialect) {
+  const missing = [
+    ...CONTRACT_FNS.filter((f) => typeof dialect[f] !== 'function').map((f) => `${f}()`),
+    ...CONTRACT_PROPS.filter((p) => dialect[p] === undefined),
+  ]
+  if (missing.length > 0) {
+    throw new MegaConfigError(
+      'migration.dialect_contract',
+      `dialect '${driver}' 가 표준 인터페이스를 충족하지 않습니다 — 누락: [${missing.join(', ')}] (dialects/README.md 참조).`,
+      { details: { driver, missing } },
+    )
+  }
+}
+
+/**
+ * driver 의 dialect 조회(+contract 검증).
+ * @param {string} driver - services.databases.<key>.driver 값.
+ * @returns {Record<string, any>}
+ * @throws {MegaConfigError} `migration.dialect_unsupported` | `migration.dialect_contract`
+ */
+export function getDialect(driver) {
+  const dialect = DIALECTS[driver]
+  if (dialect === undefined) {
+    throw new MegaConfigError(
+      'migration.dialect_unsupported',
+      `driver '${driver}' 는 마이그레이션 자동 생성을 아직 지원하지 않습니다 — 지원: [${SUPPORTED_DRIVERS.join(', ')}]. ` +
+        '해당 adapter 의 변경은 raw SQL 마이그레이션(mega generate migration)으로 작성하세요.',
+      { details: { driver, supported: SUPPORTED_DRIVERS } },
+    )
+  }
+  assertDialectContract(driver, dialect)
+  return dialect
+}
+
+/** DML facet(ADR-212) — CRUD(model-crud)가 쓰는 dialect 보조 멤버. DDL 계약과 별개. */
+const DML_CONTRACT_FNS = ['placeholder', 'parseReadResult', 'parseWriteResult', 'upsertClause']
+const DML_CONTRACT_PROPS = ['paramStyle', 'supportsReturning', 'supportsBulkReturning']
+
+/**
+ * dialect 가 DML facet 을 충족하는지 — **누락 멤버 배열**(빈 배열=충족)을 반환한다(throw 아님 — 호출부
+ * model-crud 가 `model.*` 에러로 표면화). mongo 등 DML facet 미구현 dialect 는 비어있지 않은 배열을 돌려준다.
+ * @param {Record<string, any>} dialect
+ * @returns {string[]}
+ */
+export function dmlFacetMissing(dialect) {
+  return [
+    ...DML_CONTRACT_FNS.filter((f) => typeof dialect?.[f] !== 'function').map((f) => `${f}()`),
+    ...DML_CONTRACT_PROPS.filter((p) => dialect?.[p] === undefined),
+  ]
+}

package/src/core/migration/dialects/README.md

@@ -0,0 +1,62 @@
+# Migration Dialect Contract (ADR-205)
+
+`mega migrate:generate` 의 diff 엔진(`differ.js`)과 호스트(`generate.js`)는 **이 인터페이스만**
+호출한다. 새 dialect(maria/sqlite — M-6, mongodb — M-5)는 본 contract 를 구현한 모듈을
+`dialect-registry.js` 의 `DIALECTS` 에 추가하는 것만으로 동작해야 한다. 누락 멤버는 `getDialect()` 가
+`migration.dialect_contract` 로 fail-fast 한다. mongodb 는 SQL 이 아니라 **mongo command JS 문**을
+렌더한다(`usesSqlDdl: false` — generate 가 파일 템플릿을 분기, ADR-209).
+
+## 함수 (12)
+
+| 멤버 | 의미 | postgres 구현 |
+|---|---|---|
+| `renderOps(ops)` | op 목록 → `{ up: string[], down: string[] }` (down 은 역순) | `dialects/postgres.js` |
+| `renderOp(op)` | op 1개 → up/down 쌍. op 종류는 differ 가 정본(19종 + renameFk) | 〃 |
+| `quoteIdent(name)` | 식별자 인용 깔때기 — **`identifierMaxBytes` 초과 fail-fast**(`migration.identifier_too_long`) 포함 | `"x"` (필요 시만) |
+| `quoteLiteral(value)` | 값 literal 인용(injection 방지 깔때기). NaN/Infinity 거부 | `'..'` escape |
+| `enumCheckExpr(col, values)` | enum 의 CHECK 식 — **유일한 enum 렌더 지점**(differ 는 values 만 전달) | `col IN ('a','b')` |
+| `indexName(table, cols, unique?)` | 인덱스 명명 표준 | `idx_`/`uniq_` |
+| `resolveIndexName(table, ix)` | IndexDef 의 유효 이름(명시 name 우선, 표현식은 name 필수) | 〃 |
+| `uniqueName(table, col)` | UNIQUE 제약 명명 | `uniq_<t>_<c>` |
+| `fkName(table, col, refTable)` | FK 제약 명명 | `fk_<t>_<c>_<r>` |
+| `checkName(table, col)` | CHECK 제약 명명 | `chk_<t>_<c>` |
+| `pkName(table)` | 명시(복합·후행) PK 명명 | `pk_<t>` |
+| `inlinePkName(table)` | CREATE TABLE 인라인 단일 PK 의 **서버 자동 명명** | `<t>_pkey` |
+
+명명 함수들은 diff 의 식별자이기도 하다 — 이름이 흔들리면 변경이 drop+add 로 오판되므로
+**dialect 간에도 같은 표준**(`idx_/uniq_/fk_/chk_/pk_`)을 권장한다. 서버 자동 명명만
+dialect 별로 다르다(`inlinePkName`).
+
+## 능력/한계 속성 (10)
+
+| 멤버 | 타입 | postgres | maria | sqlite | mongodb |
+|---|---|---|---|---|---|
+| `identifierMaxBytes` | number | 63 (byte) | 64 (**자** 단위 — utf8 멀티바이트도 64자, ADR-208 L-3) | `Infinity` | 64 (namespace 한도의 보수적 적용) |
+| `supportsConcurrentIndex` | boolean | true (`CONCURRENTLY`, no-tx 필요) | true (`ALGORITHM=INPLACE, LOCK=NONE`) | false | true (4.2+ 항상 online — 표기일 뿐) |
+| `enumStrategy` | string | `'check'` | `'enum-type'` (값 변경 = MODIFY COLUMN) | `'check'` | `'jsonschema-enum'` ($jsonSchema enum 키워드) |
+| `supportsRenameInTx` | boolean | true | false (DDL 암묵 commit) | true (3.25+) | false (renameCollection 은 tx 불가) |
+| `canDropColumnInTx` | boolean | true | false (DDL 암묵 commit) | true — 단 본 dialect 는 rebuild 사용 | false (DDL 자체가 tx 밖) |
+| `dependsOnRebuild` | boolean | false | false | **true** — 트리거 op 는 rebuildTable 로 수렴 | **true** — validator 통짜 교체(collMod) 수렴 |
+| `supportsRenameConstraint` | boolean | true (9.2+) | **false** (11.8 실측 — 구문 에러) → DROP+ADD | false (FK 인라인 — 동기화 불필요) | false (constraint 개념 없음) |
+| `supportsAlterAddFk` | boolean | true | true (`ADD/DROP CONSTRAINT` 실측) | **false** — FK 는 CREATE TABLE 인라인, 변경은 rebuild | false (FK 없음 — `.references()` 는 명시 거부) |
+| `requiresDropFkBeforeDropColumn` | boolean | false (DROP COLUMN 이 FK 동반 제거) | **true** — InnoDB 가 FK 인덱스 겸용 컬럼의 단독 DROP 을 거부(1553), differ 가 dropFk 선행 산출(ADR-208 H-1) | false (rebuild 경로) | false |
+| `usesSqlDdl` | boolean | true | true | true | **false** — mongo command JS 문 렌더(파일의 `db` = mongodb `Db`, ADR-209) |
+
+선택 멤버: `rebuildTriggerKinds`(Set) — `dependsOnRebuild` dialect 가 수렴 트리거 종류를 확장한다
+(mongodb: addColumn/renameColumn/setComment 포함 — validator 가 통짜라 모든 컬럼 수준 변경이 수렴.
+미지정 시 differ 의 sqlite 기본 집합).
+
+## 구현 규칙
+
+- **식별자/값은 반드시 `quoteIdent`/`quoteLiteral` 를 거친다** — differ 등 상위 계층은 SQL 조각을
+  직접 합성하지 않는다(H-1 재발 방지).
+- 파괴적 변경(DROP TABLE/COLUMN)·위험 캐스트는 SQL 안에 `-- 경고`/`-- TODO` 주석을 동반한다
+  (silent 손실 금지 — 사용자가 적용 전 검토).
+- `supportsRenameConstraint === false` 인 dialect 의 FK 이름 동기화는 differ 가 `dropFk + addFk` 로 산출한다.
+- `dependsOnRebuild === true` 면 differ 가 ALTER 로 표현 못하는 테이블 변경 전체를 `rebuildTable`
+  op(`{ from, to, renames }`) 1개로 수렴한다 — sqlite 는 12-step 재생성을, mongodb 는 validator
+  교체(collMod 우선 → `$rename` — strict 검증이 update 결과를 현재 validator 로 평가하므로 순서가
+  정본, ADR-209)를 렌더한다. generate 는 rebuildTable 포함 파일(sqlite)·mongodb 파일 전체에
+  `export const transaction = false` 를 설정한다.
+- op 의 형태(필드)는 `differ.js` 의 산출이 정본 — dialect 는 렌더만 한다. setNotNull/dropNotNull/
+  setDefault/dropDefault/setComment 는 대상 `def`(+`prevDef`)를 동반한다(maria MODIFY COLUMN 용).