iop/agent-spec/control/control-plane-operations.md

spec_doc_type	spec_id	status	source_evidence
spec	control/control-plane-operations	부분	type path notes contract agent-contract/inner/control-plane-edge-wire.md Control Plane-Edge proto-socket TCP 계약 type path notes contract agent-contract/inner/client-control-plane-wire.md Client-Control Plane proto-socket WebSocket 계약 type path notes code apps/control-plane/internal/wire/edge_server.go Control Plane Edge TCP server, hello, status request, command dispatch type path notes code apps/edge/internal/controlplane/connector.go Edge outbound connector, hello, status response, command event relay type path notes code apps/control-plane/cmd/control-plane/http_edge_handlers.go Control Plane HTTP edge registry/status/events/commands view type path notes code apps/client/lib/control_plane_status_repository.dart Flutter client HTTP status repository type path notes code apps/client/lib/iop_wire/client_wire_client.dart Flutter proto-socket Client hello baseline type path notes test apps/control-plane/internal/wire/edge_server_test.go Control Plane-Edge wire 검증 type path notes test apps/control-plane/cmd/control-plane/edge_registry_handler_test.go provider 일반·long counter의 typed view와 HTTP JSON mapping 검증 type path notes test apps/edge/internal/service/status_provider_test.go configured offline Node/provider snapshot과 reconnect capacity 복구 검증

스펙: Control Plane 운영 기능

목적

Control Plane과 Client가 Edge 운영 상태를 어떻게 관찰하고 명령을 전달하는지 설명한다.

기능 목록

기능	설명
Control Plane server	HTTP health/readiness endpoint, Client proto-socket WebSocket endpoint, Edge proto-socket TCP endpoint를 함께 시작한다.
Client hello wire	/client WebSocket proto-socket에서 ClientHelloRequest/ClientHelloResponse baseline을 제공한다.
Edge outbound enrollment	Edge가 Control Plane TCP wire로 outbound 연결하고 EdgeHelloRequest를 보낸다. edge_id가 비어 있으면 거부된다.
Edge connection registry	Control Plane은 Edge connection을 in-memory로 관리하고 reconnect stale cleanup을 connection token으로 방지한다.
Edge status request	Control Plane이 connected Edge에 EdgeStatusRequest를 보내 node/provider snapshot을 받는다.
connectivity-aligned provider snapshot	configured Node는 disconnect/pending 상태에도 connected=false로 남고 provider identity는 offline/zero effective state로 유지되며 reconnect ready 뒤 capacity와 함께 복구된다.
Edge command dispatch	Control Plane이 EdgeCommandRequest를 connected Edge에 보내고 response와 lifecycle event를 bounded audit view에 기록한다.
Edge/Fleet HTTP view	/edges, /edges/{id}, /edges/{id}/status, /edges/{id}/events, /edges/{id}/operations, /edges/{id}/commands와 fleet status 계열을 제공한다.
Flutter status repository	Flutter Client가 HTTP repository로 Edge/fleet status, events, operations, command response를 가져온다.
Flutter proto-socket client	Flutter proto-socket client는 현재 hello baseline을 지원한다.
IOP console package	packages/flutter/iop_console은 embeddable console shell/panel contract를 제공한다.

범위

• 포함: Control Plane process endpoints, Edge outbound enrollment, Edge registry, status request/response, command dispatch/event audit, Client hello wire, Flutter status repository.
• 제외: Control Plane이 Edge config/state canonical store가 되는 기능, Node 직접 연결/스케줄링, durable audit DB, 정책/권한 model, full UI 정의 동기화.

주요 흐름

sequenceDiagram
  participant Client
  participant CP as Control Plane
  participant Edge

  Edge->>CP: EdgeHelloRequest
  CP->>CP: connection registry 갱신
  Client->>CP: HTTP edge/fleet status
  CP->>Edge: EdgeStatusRequest
  Edge-->>CP: EdgeStatusResponse
  CP-->>Client: status view
  Client->>CP: command request
  CP->>Edge: EdgeCommandRequest
  Edge-->>CP: command response/event
  CP-->>Client: command result

계약

• iop.control-plane-edge-wire: agent-contract/inner/control-plane-edge-wire.md
• iop.client-control-plane-wire: agent-contract/inner/client-control-plane-wire.md
• proto 원문: proto/iop/control.proto

설정/데이터/이벤트

• Control Plane config는 configs/control-plane.yaml과 apps/control-plane/cmd/control-plane/main.go config loader를 기준으로 한다.
• Client WS listen은 IOP_WIRE_LISTEN, Edge TCP listen은 IOP_EDGE_WIRE_LISTEN으로 override할 수 있다.
• Edge connector 설정은 configs/edge.yaml의 control_plane 섹션이다.
• Edge registry recent node events와 command audit는 bounded in-memory buffer다. durable audit store가 아니다.
• EdgeNodeSnapshot.connected는 current dispatch-ready ownership과 같고 accepted/pending connection은 false다. configured offline provider는 status=unavailable, health=offline, capacity/in-flight/queued/long-context 관련 수치를 0으로 보고한다.
• online provider의 in-flight는 Edge provider lease state, queued 값은 Edge queue의 candidate pressure다. current owner의 ready/disconnect 전이 뒤에만 관측 event가 relay되고 stale/rejected close는 live snapshot/event를 바꾸지 않는다.
• Client build-time endpoint는 IOP_CONTROL_PLANE_HTTP_URL, IOP_CONTROL_PLANE_WIRE_URL Dart define으로 주입된다.

검증

• go test ./apps/control-plane/internal/wire
• go test ./apps/control-plane/cmd/control-plane
• go test ./apps/edge/internal/controlplane
• make test-control-plane-edge-wire
• make client-test - Flutter 환경과 dependency가 준비되어 있을 때 실행한다.

한계와 주의사항

• Control Plane은 현재 MVP/scaffold 성격이 강하며 DB/Redis 설정은 예약되어 있다.
• Client-Control Plane proto-socket wire는 hello baseline이고, 운영 상태 조회는 현재 HTTP repository가 담당한다.
• Edge/command/event registry는 in-memory bounded view다. audit, 권한, durable history는 별도 설계가 필요하다.
• Control Plane status/command 응답에 Node address, token, transport internals를 넣지 않는다.
• Control Plane이 Node를 직접 연결하거나 스케줄링하는 구조를 만들지 않는다.

변경 기록

• 2026-07-07: 현재 Control Plane/Client 코드와 wire 계약 기준으로 bootstrap spec 작성.
• 2026-07-07: 기능 목록 중심으로 축소하고 주요 흐름을 Mermaid sequence diagram으로 정리.
• 2026-07-22: dispatch-ready connectivity와 configured offline provider snapshot, reconnect capacity 복구, current-owner event 의미를 현재 Edge status 구현과 계약 기준으로 동기화.