Docker / Compose / worktree の runtime invariant を静的検査する

[koh110]

背景

service-template では複数 worktree / dev environment を同時起動できることを前提に、runtime configuration に重要な invariant が存在する。

現在これらの多くは Dockerfile / Compose / init script / コメントに分散している。

例:

• production container は non-root user で起動する
• NODE_ENV=production
• APP_ENV=production
• runtime image は devDependency を含めない
• PORT と EXPOSE を整合させる
• dev service の host port は固定せず dynamic port を使う
• DB service に healthcheck を持たせる
• worktree ごとに COMPOSE_PROJECT_NAME を分離する
• cleanup が別 worktree の resource を巻き込まない

目的

「template 自体は動くが、派生 repository で runtime isolation / production hardening が崩れる」ことを防ぐ。

実装案

Docker checker

• final stage に root user を残さない
• production env の invariant
• EXPOSE と application port の整合
• production dependency install の確認

Compose checker

• dev host port の固定値を禁止 / warning
• DB healthcheck 必須
• named volume / network naming の worktree isolation

Worktree integration test

静的解析だけで十分でない部分について、2 worktree 相当の compose project を並行生成して resource collision がないことを検証する。

Acceptance Criteria

• production container の root execution を検出する
• required production env の欠落を検出する
• dev host port の固定化を検出する
• DB healthcheck の欠落を検出する
• worktree ごとの compose project isolation を検証する
• cleanup が他 project の resource を削除しないことを検証する
• hadolint 等の汎用 lint と project-specific checker の責務を分離する

追加: init / cleanup / nginx dynamic-port contract

runtime isolation のうち、静的検査だけでは保証しづらい部分は contract / integration test として機械化する。

init / cleanup

• init.sh / init-local は複数回実行しても壊れない
• 同名 branch の別 worktree / clone でも COMPOSE_PROJECT_NAME が衝突しない
• cleanup.sh は対象 compose project の container / network のみ停止する
  -通常 cleanup では named volume を削除しない

nginx dynamic-port protocol

API dev server と nginx の間で利用している dynamic port file を明示的な契約にする。

例:

{
  "port": 12345
}

検査対象:

• file path / filename
• JSON shape
• port の型 / valid range
• missing / malformed file 時は 503 fail-safe
• stale port / unavailable upstream 時の挙動

可能なら JSON Schema / Zod 等で producer / consumer が同じ schema を利用する。

Acceptance Criteria 追加

• init の idempotency test がある
• 同一 branch 名の複数 worktree で compose project が衝突しない
• cleanup で named volume が意図せず削除されない
• dynamic-port file の producer / consumer contract が共有される
• malformed / missing port file 時に nginx が fail-safe になることを検証する

追加: graceful shutdown contract

production runtime の shutdown behavior も integration contract として扱う。

検査対象

• SIGTERM を受けたら新規 request の受付を停止する
• HTTP server を graceful close する
• DB / queue / external client 等の connection を必要に応じて close する
• shutdown timeout を超えた場合は非0終了する
  -正常終了時は exit code 0
• shutdown 中の error を structured log に残す

Acceptance Criteria 追加

• SIGTERM に対する integration test がある
• graceful close 完了時に正常終了する
• timeout path を検証できる
• resource cleanup hook を追加しやすい構造にする