mega-framework 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

package/sample/crud/.env

@@ -1,27 +1,175 @@
+# =============================================================================
+# sample-crud 환경변수 (.env) — 프레임워크 전체 설정 참조
+# =============================================================================
+# CLI(`mega start`/`worker`/`scheduler`)가 부팅 전에 이 파일을 process.env 로
+# 자동 로드한다(Node `process.loadEnvFile`, 20.6+, ADR-152). 이미 설정된 실제
+# 환경변수는 덮어쓰지 않는다(실 env 우선 — `--env-file` 과 동일). 그 뒤 mega.config.js·
+# apps/<app>/app.config.js 가 `process.env.X` 로 이 값들을 참조한다.
+#
+# [표기 규칙]
+#   KEY=value     → 이 데모(crud)가 실제로 쓰는 값.
+#   # KEY=value   → 프레임워크는 지원하지만 이 데모는 안 쓰는 옵션(참고용 — 필요 시 주석 해제).
+#
+# ⚠️ 아래 시크릿/비밀번호는 로컬 도커 데모 전용. 운영 배포 전 반드시 교체할 것.
+# =============================================================================
+
+
+# ── 실행 환경 ────────────────────────────────────────────────────────────────
+# development | production | test. pretty 로깅·정적자산 캐싱·i18n 자동완성 등에 영향.
+# 보통 npm 스크립트(dev=development / start=production)가 설정하므로 .env 에선 생략 가능.
+# NODE_ENV=development
+
+
+# ── 서버 (mega.config.js > server) ───────────────────────────────────────────
+# HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000
-DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
-MEGA_CLUSTER_WORKERS=8
+# 세션 쿠키 HMAC 서명 시크릿(필수) — server.sessionSecret. 32자 이상 랜덤 강제(ADR-129/155).
 SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
+# cluster 워커 프로세스 수(CLI 가 읽음, ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일.
+#   우선순위: `--cluster` 플래그 > MEGA_CLUSTER_WORKERS > server.cluster config.
+MEGA_CLUSTER_WORKERS=8
+
+
+# ── ASP: Application-layer Secure Protocol (mega.config.js > asp) ─────────────
+# /ws/chat 의 E:/P: 프레임 키 유도 masterSecret(필수) — asp.masterSecret (ADR-127/158).
+# 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 유도하는 공유키 구조라 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+
+
+# ── 데이터베이스 (mega.config.js > services.databases) ────────────────────────
+# Postgres(필수) — databases.primary.url. 모델·마이그레이션(mega migrate)·세션 사용자.
+DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
+# MongoDB(필수) — databases.mongo.url. /demo/notes 컬렉션(ADR-108). url path 의 dbName 추출,
+#   authSource=인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+# MariaDB(미사용) — 프레임워크는 mariadb 드라이버 지원. 쓰려면 mega.config 의 services.databases 에
+#   { driver:'mariadb', url: process.env.MARIA_URL } 추가. (url 은 query string 미지원)
+# MARIA_URL=mariadb://mega:dkTkqkfl12@localhost:3306/mega_test
+
+
+# ── Redis 캐시 (mega.config.js > services.caches, app.config > session) ───────
+# 논리 DB 인덱스를 분리해 키 충돌 회피(/0 세션 · /1 demo · /2 rate · /3 lock).
+# 세션 store(app.config.js session.store.url, ADR-129/155).
 REDIS_SESSION_URL=redis://:dkTkqkfl12@localhost:6379/0
+# brute-force 카운터(ctx.bruteForce, ADR-049/130) — caches.rate.
 REDIS_RATE_URL=redis://:dkTkqkfl12@localhost:6379/2
+# /demo/redis·cron·jobs 데모 캐시 — caches.demo.
 REDIS_DEMO_URL=redis://:dkTkqkfl12@localhost:6379/1
+# 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
-MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
+# 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
+# REDIS_CACHE_URL=redis://:dkTkqkfl12@localhost:6379/4
+
+
+# ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
+# 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
+#   JetStream 활성 서버 필요(nats-server -js).
 NATS_JOBS_URL=nats://localhost:4222
-ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+# 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
+# NATS_EVENTS_URL=nats://localhost:4222
+
 
+# ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
+# crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
+# start-ws-hub.sh)로 별도 프로세스 기동. 아래 MEGA_WSHUB_* 는 src/cli/ws-hub.js 가 읽는다.
+# --- 허브 서버가 읽는 값 (`mega ws-hub`) ---
+# 수락 토큰 CSV(필수) — 브릿지 인증. 빈 값이면 허브 기동 실패. 운영 교체.
 MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
-MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
 MEGA_WSHUB_PORT=3100
 MEGA_WSHUB_HOST=0.0.0.0
+# 허브 튜닝(선택) — 미설정 시 코드 기본값(heartbeat 25000 / maxPayload 1 MiB / 압축 off).
+MEGA_WSHUB_HEARTBEAT_MS=25000
+MEGA_WSHUB_MAX_PAYLOAD=1048576
+MEGA_WSHUB_COMPRESSION=false
+MEGA_WSHUB_COMPRESSION_THRESHOLD=1024     # MEGA_WSHUB_COMPRESSION=true 일 때만 적용
+# --- 앱(브릿지 클라이언트)이 읽는 값 (app.config.js > bridgeHub) ---
 MEGA_WSHUB_URL=ws://localhost:3100
+MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
+# 이 노드(브릿지) 식별자 — bridgeHub.bridgeId. roster/로그 구분용(클러스터 워커는 -w{id} suffix 자동).
+BRIDGE_ID=crud-1
+
 
+# ── OpenTelemetry 분산 트레이싱 (선택, ADR-104/114/126/163) ───────────────────
+# MegaTracing.fromEnv() 가 부팅 시 읽는다(boot.js). ENABLED!=='true' 면 0 비용 no-op.
+# /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 딥링크로 잇는다. docker 의
+# otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 true 로 켠다(collector 부재 시 export 실패 로그).
 MEGA_OTEL_ENABLED=true
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
+MEGA_OTEL_EXPORTER=otlp                      # otlp | zipkin | console | inmemory
+MEGA_OTEL_SAMPLING_RATIO=1.0                 # 0.0~1.0 또는 always_on | always_off
+# Zipkin UI API base — /demo/tracing 딥링크 base(앱 코드가 읽음).
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+# resource 속성(선택) — 미설정 시 생략.
+# MEGA_OTEL_VERSION=1.0.0
+# MEGA_OTEL_ENVIRONMENT=local
+
+
+# ── Prometheus 메트릭 (선택, ADR-072/131) ────────────────────────────────────
+# crud 는 mega.config.js 의 health.exposeMetrics:true 로 /metrics 를 켠다(config 주도 — env 아님).
+# 아래 env 는 MegaMetrics.fromEnv() 를 직접 호출하는 커스텀 부팅에서만 효과(기본 boot 는 config 사용).
+# METRICS_ENABLED=true                       # 또는 MEGA_METRICS_ENABLED
+# MEGA_METRICS_SERVICE_NAME=sample-crud
+# MEGA_METRICS_ENVIRONMENT=local
+
+
+# ── 로깅 (mega.config.js > logger, ADR-023/141) ──────────────────────────────
+# pino 레벨 — logger.level. fatal | error | warn | info | debug | trace.
+LOG_LEVEL=info
+# (참고) 파일/텔레그램 sink 등은 .env 가 아니라 mega.config.js 의 logger.sinks 배열로 설정한다.
+
+
+# ── 데모 (앱 코드가 읽음) ─────────────────────────────────────────────────────
+# /demo/upload 저장 디렉터리. 상대경로=프로젝트 루트(cwd) 기준. 미설정 시 var/uploads.
 DEMO_UPLOAD_DIR=var/uploads
 
-BRIDGE_ID=crud-1
+
+# =============================================================================
+# Docker 인프라 (docker-compose.yml 이 읽음, ADR-103) — 전부 선택/주석
+# =============================================================================
+# 위 연결 문자열(DATABASE_URL 등)은 아래 도커 기본값과 정합한다. docker-compose.yml 에 인라인
+# 디폴트가 있어 미설정이어도 컨테이너가 뜨지만, 포트/비번을 바꾸려면 아래를 켜고 위 URL 도 함께 맞춘다.
+# 네이밍: MEGA_<SERVICE>_<FIELD>.
+# MEGA_PG_PORT=5432
+# MEGA_PG_USER=mega
+# MEGA_PG_PASSWORD=dkTkqkfl12
+# MEGA_PG_DB=mega_test
+# MEGA_MONGO_PORT=27017
+# MEGA_MONGO_USER=mega
+# MEGA_MONGO_PASSWORD=dkTkqkfl12
+# MEGA_MONGO_DB=mega_test
+# MEGA_REDIS_PORT=6379
+# MEGA_REDIS_PASSWORD=dkTkqkfl12
+# MEGA_NATS_PORT=4222
+# MEGA_NATS_MONITOR_PORT=8222
+# MEGA_MARIA_PORT=3306
+# MEGA_MARIA_ROOT_PASSWORD=dkTkqkfl12
+# MEGA_MARIA_USER=mega
+# MEGA_MARIA_PASSWORD=dkTkqkfl12
+# MEGA_MARIA_DB=mega_test
+# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no.
+# MEGA_INFRA_RESTART=unless-stopped
+
+
+# =============================================================================
+# 어댑터 옵션 자동매핑 (ADR-109, 12-factor) — 전부 선택/주석
+# =============================================================================
+# services.<domain>.<key> 에 `envPrefix: 'PG'` 처럼 지정하면 MegaAdapterManager 가
+# MEGA_<PREFIX>_<KEY> 를 읽어 어댑터 옵션에 병합(env 우선). url 직접 지정 대신 12-factor 분리용.
+# (crud 는 url 직접 방식이라 미사용 — 아래는 문법 참고.)
+#   문법: MEGA_<PREFIX>_<KEY>
+#     URL                     → url
+#     HOST / PORT / USER / PASSWORD → 연결필드 (PORT 만 정수, 나머지 문자열)
+#     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
+#     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
+#     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# MEGA_PG_POOL_MIN=0
+# MEGA_PG_POOL_MAX=10
+# MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
+# 드라이버 특화 옵션 예:
+# MEGA_PG_OPTIONS_SSL=true                          # → options.ssl
+# MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000           # → options.statement_timeout (pg=snake)
+# MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin              # → options.authSource (mongo=camel)
+# MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS
+# MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number        # number(기본,2^53 초과 손실) | bigint | string

package/sample/crud/.env.example

@@ -1,50 +1,175 @@
-# sample-crud 환경변수 (.env.example) — 복사해서 .env 로 쓰고 실제 값 채우기. .env 는 git 에 안 올림.
+# =============================================================================
+# sample-crud 환경변수 (.env.example) — 프레임워크 전체 설정 참조
+# =============================================================================
+# 복사해서 `.env` 로 쓰고 시크릿/비밀번호를 실제 값으로 채운다. CLI(`mega start`/`worker`/
+# `scheduler`)가 부팅 전에 `.env` 를 process.env 로 자동 로드한다(Node `process.loadEnvFile`,
+# 20.6+, ADR-152). 이미 설정된 실제 환경변수는 덮어쓰지 않는다(실 env 우선). 그 뒤 mega.config.js·
+# apps/<app>/app.config.js 가 `process.env.X` 로 이 값들을 참조한다.
+#
+# [표기 규칙]
+#   KEY=value     → 이 데모(crud)가 실제로 쓰는 값.
+#   # KEY=value   → 프레임워크는 지원하지만 이 데모는 안 쓰는 옵션(참고용 — 필요 시 주석 해제).
+#
+# ⚠️ change-me 로 표시된 값은 반드시 교체할 것(시크릿은 32자 이상 랜덤 권장).
+# =============================================================================
 
-# HTTP 포트
+
+# ── 실행 환경 ────────────────────────────────────────────────────────────────
+# development | production | test. pretty 로깅·정적자산 캐싱·i18n 자동완성 등에 영향.
+# 보통 npm 스크립트(dev=development / start=production)가 설정하므로 .env 에선 생략 가능.
+# NODE_ENV=development
+
+
+# ── 서버 (mega.config.js > server) ───────────────────────────────────────────
+# HTTP listen 포트 — server.port. CLI `--port N` 이 우선(ADR-146).
 PORT=3000
+# 세션 쿠키 HMAC 서명 시크릿(필수) — server.sessionSecret. 32자 이상 랜덤 강제(ADR-129/155).
+SESSION_SECRET=change-me-to-a-long-random-secret-at-least-32-chars
+# cluster 워커 프로세스 수(CLI 가 읽음, ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일.
+#   우선순위: `--cluster` 플래그 > MEGA_CLUSTER_WORKERS > server.cluster config.
+MEGA_CLUSTER_WORKERS=8
+
+
+# ── ASP: Application-layer Secure Protocol (mega.config.js > asp) ─────────────
+# /ws/chat 의 E:/P: 프레임 키 유도 masterSecret(필수) — asp.masterSecret (ADR-127/158).
+# 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 유도하는 공유키 구조라 데모 전용 값을 둔다.
+ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
 
-# cluster 워커 프로세스 수(ADR-154) — 정수 N 또는 max(CPU 코어 수). 미설정/1=단일 프로세스.
-# MEGA_CLUSTER_WORKERS=max
 
-# Postgres 연결 (필수) — services.databases.primary.url 이 읽는다.
-# 예: docker compose 의 postgres
+# ── 데이터베이스 (mega.config.js > services.databases) ────────────────────────
+# Postgres(필수) — databases.primary.url. 모델·마이그레이션(mega migrate)·세션 사용자.
 DATABASE_URL=postgres://mega:change-me@localhost:5432/mega_test
+# MongoDB(필수) — databases.mongo.url. /demo/notes 컬렉션(ADR-108). url path 의 dbName 추출,
+#   authSource=인증 DB(보통 admin).
+MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
+# MariaDB(미사용) — 프레임워크는 mariadb 드라이버 지원. 쓰려면 mega.config 의 services.databases 에
+#   { driver:'mariadb', url: process.env.MARIA_URL } 추가. (url 은 query string 미지원)
+# MARIA_URL=mariadb://mega:change-me@localhost:3306/mega_test
 
-# 세션 쿠키 HMAC 서명 시크릿 (필수, ADR-155) — server.sessionSecret 이 읽는다. 충분히 긴 랜덤 문자열.
-SESSION_SECRET=change-me-to-a-long-random-secret
 
-# Redis 연결 (필수, ADR-155/157) — 세션 store·brute-force·/demo/redis·cron·jobs 데모 캐시 + 분산 락(redlock).
-# DB 인덱스를 분리해 키 충돌을 피한다(/0 세션, /1 demo, /2 rate, /3 lock).
+# ── Redis 캐시 (mega.config.js > services.caches, app.config > session) ───────
+# 논리 DB 인덱스를 분리해 키 충돌 회피(/0 세션 · /1 demo · /2 rate · /3 lock).
+# 세션 store(app.config.js session.store.url, ADR-129/155).
 REDIS_SESSION_URL=redis://:change-me@localhost:6379/0
+# brute-force 카운터(ctx.bruteForce, ADR-049/130) — caches.rate.
 REDIS_RATE_URL=redis://:change-me@localhost:6379/2
+# /demo/redis·cron·jobs 데모 캐시 — caches.demo.
 REDIS_DEMO_URL=redis://:change-me@localhost:6379/1
-# 분산 락(redlock, ADR-113) — services.caches.lock 이 읽는다. /demo/cron 스케줄의 클러스터 중복방지(leader election).
+# 분산 락(redlock, ADR-113) — caches.lock(locks.main 이 빌려 씀). /demo/cron leader election.
 REDIS_LOCK_URL=redis://:change-me@localhost:6379/3
+# 범용 캐시(미사용) — 별도 캐시 어댑터가 필요하면 services.caches 에 추가해 참조.
+# REDIS_CACHE_URL=redis://:change-me@localhost:6379/4
+
 
-# NATS 연결 (필수, ADR-119) — services.buses.jobs.url 이 읽는다. /demo/jobs 잡 큐(EmailJob)의 JetStream 백엔드.
-# `mega worker` 프로세스가 소비하고 웹은 enqueue 한다. JetStream 활성 NATS 서버 필요(nats-server -js).
+# ── NATS 버스 (mega.config.js > services.buses) ──────────────────────────────
+# 잡 큐(EmailJob JetStream, ADR-119) — buses.jobs.url. `mega worker` 가 소비, 웹이 enqueue.
+#   JetStream 활성 서버 필요(nats-server -js).
 NATS_JOBS_URL=nats://localhost:4222
+# 이벤트 버스(미사용) — pub/sub 등 두 번째 버스가 필요하면 services.buses 에 추가.
+# NATS_EVENTS_URL=nats://localhost:4222
 
-# MongoDB 연결 (필수, ADR-157) — services.databases.mongo.url 이 읽는다. /demo/notes 데모 컬렉션의 백엔드.
-# url path 의 dbName(mega_test)을 어댑터가 추출한다. authSource 는 인증 DB(보통 admin).
-MONGO_URL=mongodb://mega:change-me@localhost:27017/mega_test?authSource=admin
 
-# ASP WebSocket 데모 masterSecret (필수, ADR-158) — asp.masterSecret 이 읽는다. /ws/chat 의 E:/P:
-# 프레임 키 유도에 쓰인다. ASP 는 클라이언트(WASM MegaSocket)도 같은 secret 으로 키를 만드는 공유-키
-# 구조라 데모 페이지가 이 값을 브라우저에 주입한다 — 운영 secret 과 섞이지 않게 데모 전용 값을 둔다.
-ASP_MASTER_SECRET=change-me-to-a-demo-asp-secret
+# ── WS Hub: 클러스터 채팅 브릿지 (ADR-059/065/137/176) ────────────────────────
+# crud 는 app.config.js 의 bridgeHub 로 /ws/chat 을 클러스터 전파한다. 허브는 `mega ws-hub`(scripts/
+# start-ws-hub.sh)로 별도 프로세스 기동. 아래 MEGA_WSHUB_* 는 src/cli/ws-hub.js 가 읽는다.
+# --- 허브 서버가 읽는 값 (`mega ws-hub`) ---
+# 수락 토큰 CSV(필수) — 브릿지 인증. 빈 값이면 허브 기동 실패. 운영 교체.
+MEGA_WSHUB_TOKENS=change-me-hub-token
+MEGA_WSHUB_PORT=3100
+MEGA_WSHUB_HOST=0.0.0.0
+# 허브 튜닝(선택) — 미설정 시 코드 기본값(heartbeat 25000 / maxPayload 1 MiB / 압축 off).
+# MEGA_WSHUB_HEARTBEAT_MS=25000
+# MEGA_WSHUB_MAX_PAYLOAD=1048576
+# MEGA_WSHUB_COMPRESSION=false
+# MEGA_WSHUB_COMPRESSION_THRESHOLD=1024     # MEGA_WSHUB_COMPRESSION=true 일 때만 적용
+# --- 앱(브릿지 클라이언트)이 읽는 값 (app.config.js > bridgeHub) ---
+MEGA_WSHUB_URL=ws://localhost:3100
+MEGA_WSHUB_TOKEN=change-me-hub-token
+# 이 노드(브릿지) 식별자 — bridgeHub.bridgeId. roster/로그 구분용(클러스터 워커는 -w{id} suffix 자동).
+BRIDGE_ID=crud-1
 
-# OpenTelemetry 트레이싱 (선택, ADR-104/126/163) — /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 으로
-# 잇는다. 미설정/false 면 트레이싱 OFF(데모는 비활성 안내를 보여줌). docker 의 otel-collector(:4318 OTLP HTTP)·
-# zipkin(:9411) 가동 시 true 로 켠다. exporter otlp → collector → zipkin 경로로 span 이 전달된다.
+
+# ── OpenTelemetry 분산 트레이싱 (선택, ADR-104/114/126/163) ───────────────────
+# MegaTracing.fromEnv() 가 부팅 시 읽는다(boot.js). ENABLED!=='true' 면 0 비용 no-op.
+# /demo/tracing 데모가 요청별 trace_id 를 만들고 Zipkin 딥링크로 잇는다. docker 의
+# otel-collector(:4318 OTLP HTTP)·zipkin(:9411) 가동 시 true 로 켠다(collector 부재 시 export 실패 로그).
 MEGA_OTEL_ENABLED=false
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-MEGA_OTEL_EXPORTER=otlp
-MEGA_OTEL_SAMPLING_RATIO=1.0
-# Zipkin UI API base — /demo/tracing 이 trace 딥링크 base(.../api/v2 를 떼 UI 루트)로 쓴다.
+MEGA_OTEL_EXPORTER=otlp                      # otlp | zipkin | console | inmemory
+MEGA_OTEL_SAMPLING_RATIO=1.0                 # 0.0~1.0 또는 always_on | always_off
+# Zipkin UI API base — /demo/tracing 딥링크 base(앱 코드가 읽음).
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
+# resource 속성(선택) — 미설정 시 생략.
+# MEGA_OTEL_VERSION=1.0.0
+# MEGA_OTEL_ENVIRONMENT=local
+
+
+# ── Prometheus 메트릭 (선택, ADR-072/131) ────────────────────────────────────
+# crud 는 mega.config.js 의 health.exposeMetrics:true 로 /metrics 를 켠다(config 주도 — env 아님).
+# 아래 env 는 MegaMetrics.fromEnv() 를 직접 호출하는 커스텀 부팅에서만 효과(기본 boot 는 config 사용).
+# METRICS_ENABLED=true                       # 또는 MEGA_METRICS_ENABLED
+# MEGA_METRICS_SERVICE_NAME=sample-crud
+# MEGA_METRICS_ENVIRONMENT=local
+
+
+# ── 로깅 (mega.config.js > logger, ADR-023/141) ──────────────────────────────
+# pino 레벨 — logger.level. fatal | error | warn | info | debug | trace.
+LOG_LEVEL=info
+# (참고) 파일/텔레그램 sink 등은 .env 가 아니라 mega.config.js 의 logger.sinks 배열로 설정한다.
 
-# 업로드 저장 디렉터리 (선택, ADR-163) — /demo/upload 이 파일을 저장할 위치. 상대경로는 프로젝트 루트
-# (cwd) 기준, 절대경로면 그대로. 미설정 시 var/uploads(.gitignore). 다운로드도 같은 위치에서 소스로 읽는다.
+
+# ── 데모 (앱 코드가 읽음) ─────────────────────────────────────────────────────
+# /demo/upload 저장 디렉터리. 상대경로=프로젝트 루트(cwd) 기준. 미설정 시 var/uploads.
 DEMO_UPLOAD_DIR=var/uploads
+
+
+# =============================================================================
+# Docker 인프라 (docker-compose.yml 이 읽음, ADR-103) — 전부 선택/주석
+# =============================================================================
+# 위 연결 문자열(DATABASE_URL 등)은 아래 도커 기본값과 정합한다. docker-compose.yml 에 인라인
+# 디폴트가 있어 미설정이어도 컨테이너가 뜨지만, 포트/비번을 바꾸려면 아래를 켜고 위 URL 도 함께 맞춘다.
+# 네이밍: MEGA_<SERVICE>_<FIELD>.
+# MEGA_PG_PORT=5432
+# MEGA_PG_USER=mega
+# MEGA_PG_PASSWORD=change-me
+# MEGA_PG_DB=mega_test
+# MEGA_MONGO_PORT=27017
+# MEGA_MONGO_USER=mega
+# MEGA_MONGO_PASSWORD=change-me
+# MEGA_MONGO_DB=mega_test
+# MEGA_REDIS_PORT=6379
+# MEGA_REDIS_PASSWORD=change-me
+# MEGA_NATS_PORT=4222
+# MEGA_NATS_MONITOR_PORT=8222
+# MEGA_MARIA_PORT=3306
+# MEGA_MARIA_ROOT_PASSWORD=change-me
+# MEGA_MARIA_USER=mega
+# MEGA_MARIA_PASSWORD=change-me
+# MEGA_MARIA_DB=mega_test
+# 컨테이너 restart 정책: 개발=unless-stopped / CI 일회성=no.
+# MEGA_INFRA_RESTART=unless-stopped
+
+
+# =============================================================================
+# 어댑터 옵션 자동매핑 (ADR-109, 12-factor) — 전부 선택/주석
+# =============================================================================
+# services.<domain>.<key> 에 `envPrefix: 'PG'` 처럼 지정하면 MegaAdapterManager 가
+# MEGA_<PREFIX>_<KEY> 를 읽어 어댑터 옵션에 병합(env 우선). url 직접 지정 대신 12-factor 분리용.
+# (crud 는 url 직접 방식이라 미사용 — 아래는 문법 참고.)
+#   문법: MEGA_<PREFIX>_<KEY>
+#     URL                     → url
+#     HOST / PORT / USER / PASSWORD → 연결필드 (PORT 만 정수, 나머지 문자열)
+#     DATABASE | DB           → database   /   DBNAME → dbName(Mongo)
+#     POOL_<X>                → pool.{camelCase(X)}    (드라이버 공통, 값 자동 타입변환)
+#     OPTIONS_<X>             → options.{드라이버 표기}  (postgres/sqlite=snake, 그 외=camel; MS 대문자 보존)
+# 공통 풀 인터페이스(min/max/idleTimeoutMs/acquireTimeoutMs/maxLifetimeMs) 예:
+# MEGA_PG_POOL_MIN=0
+# MEGA_PG_POOL_MAX=10
+# MEGA_PG_POOL_IDLE_TIMEOUT_MS=10000
+# 드라이버 특화 옵션 예:
+# MEGA_PG_OPTIONS_SSL=true                          # → options.ssl
+# MEGA_PG_OPTIONS_STATEMENT_TIMEOUT=30000           # → options.statement_timeout (pg=snake)
+# MEGA_MONGO_OPTIONS_AUTH_SOURCE=admin              # → options.authSource (mongo=camel)
+# MEGA_MONGO_OPTIONS_SERVER_SELECTION_TIMEOUT_MS=5000  # → options.serverSelectionTimeoutMS
+# MEGA_MARIA_OPTIONS_BIG_INT_STRATEGY=number        # number(기본,2^53 초과 손실) | bigint | string

package/sample/crud/mega.config.js

@@ -15,6 +15,13 @@ export default {
     port: Number(process.env.PORT ?? 3000),
     // 세션 쿠키 HMAC 서명 시크릿(global 스코프, ADR-129). boot 이 앱에 주입한다. .env 의 SESSION_SECRET.
     sessionSecret: process.env.SESSION_SECRET,
+    // (예시·미사용) listen 호스트 — 기본 '0.0.0.0'. `mega start --host H`(CLI)가 우선.
+    // host: '0.0.0.0',
+    // (예시·미사용) cluster 워커 수 — CLI `--cluster` > .env MEGA_CLUSTER_WORKERS > 이 값(ADR-154). 정수 N | 'max'.
+    // cluster: 'max',
+    // (예시·미사용) 메트릭/트레이싱 resource 의 service.name·version(health.serviceName 미지정 시 폴백).
+    // serviceName: 'sample-crud',
+    // version: '0.1.0',
   },
 
   // ASP(Application-layer Secure Protocol) masterSecret — global 스코프 시크릿(ADR-127, scope-registry).
@@ -24,6 +31,8 @@ export default {
   // 이 값을 브라우저에 주입한다 — 그래서 운영 secret 과 분리된 데모 전용 값을 .env 의 ASP_MASTER_SECRET 에 둔다.
   asp: {
     masterSecret: process.env.ASP_MASTER_SECRET,
+    // (예시·미사용) HTTP body/query 암호화 옵션(enabledPaths·driftMs·nonceCache 등)은 **앱 스코프** —
+    //   apps/<app>/app.config.js 의 asp.http 에 둔다. 여기 global 블록엔 masterSecret 만(scope-registry).
   },
 
   // 전역 어댑터(ADR-102/106/109) — globalKey 로 선언, 앱은 app.config.js 의 별명으로 참조.
@@ -33,6 +42,11 @@ export default {
       primary: {
         driver: 'postgres',
         url: process.env.DATABASE_URL,
+        // (예시·미사용) url 대신 discrete 도 가능: { host, port, user, password, database } (url 과 상호배타).
+        // (예시·미사용) 공통 풀 인터페이스 — 드라이버별 키로 자동 매핑(ADR-109). 단위 *Ms=밀리초.
+        // pool: { min: 0, max: 10, idleTimeoutMs: 10_000 },
+        // (예시·미사용) 드라이버 네이티브 옵션 passthrough(pg=snake_case).
+        // options: { ssl: false, statement_timeout: 30_000 },
       },
       // DB 'mongo' — Document DB 어댑터(ADR-108). notes 데모 컬렉션(Note 모델 static adapter='mongo')의 공유
       // 인스턴스. url path 의 dbName(mega_test)을 어댑터가 추출한다. .env 의 MONGO_URL(authSource=admin).
@@ -40,6 +54,12 @@ export default {
         driver: 'mongodb',
         url: process.env.MONGO_URL,
       },
+      // (예시·미사용) MariaDB 어댑터(ADR-105). 쓰려면 주석 해제 + .env 의 MARIA_URL 설정.
+      // 모델은 static adapter='maria'(globalKey)로 닿고, app.config.js databases 에 별명 추가.
+      // maria: {
+      //   driver: 'mariadb',
+      //   url: process.env.MARIA_URL,
+      // },
     },
     caches: {
       // redis 캐시 'rate' — brute-force(ctx.bruteForce, ADR-049/130)의 원자적 INCR 백엔드. .env 의 REDIS_RATE_URL(db 2).
@@ -60,6 +80,12 @@ export default {
         driver: 'redis',
         url: process.env.REDIS_LOCK_URL,
       },
+      // (예시·미사용) 범용 캐시 — 일반 키/값 캐싱이 필요하면 주석 해제 + .env 의 REDIS_CACHE_URL 설정.
+      // 기존 캐시(rate/demo/lock)와 키 충돌을 피해 별도 논리 DB(/4 등)를 권장. app.config.js caches 에 별명 추가.
+      // cache: {
+      //   driver: 'redis',
+      //   url: process.env.REDIS_CACHE_URL,
+      // },
     },
     // NATS 버스 'jobs' — 잡 큐(EmailJob, ADR-119)의 JetStream 백엔드. producer(웹)는 ctx.bus('jobs').native(nc)로
     // enqueue, consumer(`mega worker`)는 같은 버스로 소비한다. .env 의 NATS_JOBS_URL.
@@ -68,6 +94,11 @@ export default {
         driver: 'nats',
         url: process.env.NATS_JOBS_URL,
       },
+      // (예시·미사용) 이벤트 버스 — pub/sub 등 두 번째 NATS 버스가 필요하면 주석 해제 + .env 의 NATS_EVENTS_URL.
+      // events: {
+      //   driver: 'nats',
+      //   url: process.env.NATS_EVENTS_URL,
+      // },
     },
     // 분산 락 'main' — redlock(ADR-113). caches.lock(Redis) 을 빌려 단일 노드 redlock 을 구성한다. /demo/cron
     // 스케줄(CronCounterSchedule.static lock)의 클러스터 중복방지(leader election)에 쓰인다.
@@ -79,6 +110,17 @@ export default {
     },
   },
 
+  // (예시·미사용) Embedded WS Hub(ADR-137) — `mega ws-hub` 별도 프로세스 대신 같은 프로세스에 허브를 띄움
+  //   (single-node). 켜면 app.config.js bridgeHub.url 을 이 host:port 로 맞춘다. acceptedTokens 필수(빈 값=throw).
+  // wsHub: {
+  //   enabled: true,
+  //   port: 3100,
+  //   host: '127.0.0.1',
+  //   acceptedTokens: (process.env.MEGA_WSHUB_TOKENS ?? '').split(',').filter(Boolean),
+  //   heartbeatMs: 25_000,
+  //   // compression: { enabled: false },
+  // },
+
   // ── 클러스터 전송 선택(ADR-176, 앱당 하나·상호배타) ───────────────────────────────────────────
   // 이 샘플은 현재 **WS Hub**(app.config 의 bridgeHub → `mega ws-hub` 서버, localhost:3100)로 채팅을
   // 클러스터 전파한다. boot 가 bridgeHub 를 보고 app.connectHub 를 자동 호출한다(개발자 배선 불요).
@@ -101,11 +143,20 @@ export default {
   // CPU 워커 풀(ADR-124) — `mega start`(boot)가 ctx.workers['hash'] 로 배선한다(config.workers).
   workers: [HashWorker],
 
+  // (예시·미사용) 플러그인 — 명시 등록만(auto-discovery 없음, ADR-079). 문자열 또는 { name, options }.
+  // plugins: [{ name: 'my-plugin', options: {} }],
+
   // pino 로깅(ADR-023/141) — console sink, dev pretty. redact 로 민감필드를 sink 출력 전 메인스레드에서
   // 마스킹한다(token/password/secret/authorization). /demo/logs 데모가 이 마스킹을 시연한다(ADR-163).
   logger: {
-    level: 'debug',
-    sinks: [{ type: 'console', pretty: true }],
+    level: process.env.LOG_LEVEL ?? 'info',
+    // sinks — 출력처 배열. console(dev pretty) 외에 file(pino-roll)·telegram sink 지원.
+    sinks: [
+      { type: 'console', pretty: true },
+      // (예시·미사용) 파일 sink — 날짜 로테이션 + keep N.
+      // { type: 'file', path: './logs/app.log', rotation: 'daily', keep: 14 },
+      // (예시·미사용) telegram sink — warn 이상 알림. botToken/chatId 는 .env 등 시크릿으로 주입(코드·git 직접 X).
+    ],
     redact: ['*.password', '*.token', '*.secret', '*.authorization', 'password', 'token', 'secret'],
   },
 
@@ -114,5 +165,13 @@ export default {
     exposeMetrics: true,
     metricsPath: '/metrics',
     metricsAllowList: ['127.0.0.1', '::1'],
+    // (예시·미사용) liveness/readiness 경로 — 기본 '/health' · '/health/ready'.
+    // paths: { live: '/health', ready: '/health/ready' },
+    // (예시·미사용) 메트릭 resource service.name — 미지정 시 server.serviceName → MEGA_OTEL_SERVICE_NAME 폴백.
+    // serviceName: 'sample-crud',
   },
+
+  // OpenTelemetry 분산 트레이싱 — **config 블록이 아니라 .env 의 MEGA_OTEL_\*** 로 설정한다
+  //   (MegaTracing.fromEnv, boot.js). MEGA_OTEL_ENABLED='true' + MEGA_OTEL_SERVICE_NAME 필수.
+  //   (`tracing` 키는 스키마엔 있으나 현재 부팅이 소비하지 않음 — 죽은 설정 회피 위해 블록을 두지 않음.)
 }

package/sample/crud/package.json

@@ -7,7 +7,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "dev": "NODE_ENV=development mega start",
+    "dev": "mega start --watch",
     "start": "NODE_ENV=production mega start",
     "migrate": "mega migrate",
     "migrate:down": "mega migrate:down",
@@ -25,4 +25,4 @@
     "concurrently": "^9.0.0",
     "vitest": "^4.0.0"
   }
-}
+}

package/sample/crud/yarn.lock

@@ -1234,7 +1234,7 @@ marked@^18.0.5:
   integrity sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==
 
 "mega-framework@file:../..":
-  version "0.1.3"
+  version "0.1.5"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"