iop/agent-test/dev/control-plane-smoke.md

test_env	test_profile	domain	verification_type	last_rule_updated_at
dev	control-plane-smoke	control-plane	smoke	2026-06-12

control-plane-smoke dev 테스트

읽기 조건

• apps/control-plane/** 변경 또는 Control Plane health/readiness, config loading, wire endpoint dev 검증 판단이 필요한 경우

적용 범위

• apps/control-plane/cmd/control-plane/**
• apps/control-plane/internal/wire/**
• apps/control-plane/Dockerfile
• Control Plane HTTP health/readiness와 proto-socket WebSocket hello baseline
• Control Plane-Edge TCP wire endpoint, Edge outbound hello, disconnect baseline
• dev compose host publish와 DB/Redis 분리

분류

• domain: control-plane
• verification_type: smoke
• scope: control-plane HTTP와 wire baseline

환경

• host: Docker compose 또는 Flutter client가 포함된 runtime evidence는 원격 runner ssh toki@toki-labs.com의 /Users/toki/agent-work/iop-dev 기준으로 수행한다.
• port: Control Plane HTTP 18001 (host-facing), Portal/Control Plane wire test endpoint 19001, CP-Edge wire 19002, Edge-Node TCP transport 19003, web/dev preview 13001.
• runtime: Go 1.24, Docker compose
• package manager: Go modules / Makefile
• docker: docker-compose.yml에 postgres, redis, control-plane, edge, web service가 정의되어 있다. dev 검증은 docker compose --env-file .env.dev.example ...로 수행한다.
• external service: postgres host publish 15401, redis host publish 16301
• model endpoint:
• credential: DB/Redis credential 원문은 문서에 기록하지 않는다.

명령

• setup: IOP_EDGE_NODE_TOKEN=<token> docker compose --env-file .env.dev.example up -d postgres redis control-plane edge web
• lint:
• unit: go test ./apps/control-plane/...
• smoke: curl -fsS http://127.0.0.1:18001/healthz, curl -fsS http://127.0.0.1:18001/readyz
• e2e: make test-control-plane-edge-wire는 보조 smoke이며 기본 포트를 쓰는 스크립트이므로 dev 포트 override 가능 여부를 먼저 확인한다.
• model:
• full-cycle: Control Plane command, health/readiness, wire hello 수동 검증

필수 검증

• 변경한 control-plane 패키지 또는 go test ./apps/control-plane/...를 실행한다.
• HTTP lifecycle 변경 시 dev port /healthz와 /readyz를 확인한다.
• Client-Control Plane wire protocol 변경 시 proto-socket WebSocket hello baseline을 dev wire port 19001 기준으로 확인한다.
• Control Plane-Edge TCP wire, Edge outbound connector, registry lifecycle 변경 시 dev 19002 기준으로 hello accepted, Edge connected, Edge disconnected marker를 확인한다.

보조 검증

• docker compose control-plane service healthcheck를 확인한다.
• Edge 포함 compose 검증에서는 IOP_EDGE_NODE_TOKEN을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다.

판정 기준

• control-plane service가 dev stack으로 기동되고 health endpoint가 성공 응답을 반환한다.
• wire endpoint는 Control Plane 브라우저/앱 경계로 유지되고 Node 직접 연결/스케줄링 경로로 확장되지 않는다.
• dev stack은 local/test stack의 host publish 포트(13000, 18000, 19080, 19081, 15400, 16300)를 점유하지 않는다.

기준 출력 예시

curl -fsS http://127.0.0.1:18001/healthz
curl -fsS http://127.0.0.1:18001/readyz

차단 기준

• docker compose 실행 권한 또는 postgres/redis service 기동이 불가능하다.
• 현재 작업 컨테이너에서 Docker-in-Docker가 필요해지는 검증은 수행하지 않고 원격 runner 차단으로 보고한다.
• 실제 DB/Redis credential 확인이 필요한데 안전하게 제공되지 않았다.
• dev 포트가 이미 점유되어 있어 local/test stack과 공존할 수 없다.

보고 항목

• 실행한 명령:
• 성공한 검증:
• 실패/차단된 검증:
• 생략 사유:
• 남은 위험:

금지 사항

• Control Plane에서 Node 직접 연결이나 직접 스케줄링을 제품 기본 계약으로 만들지 않는다.
• 실제 DB/Redis credential이나 private endpoint를 tracked docs/rules에 기록하지 않는다.
• secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.