---
spec_doc_type: spec
spec_id: control/control-plane-operations
status: 부분
source_evidence:
  - type: contract
    path: agent-contract/inner/control-plane-edge-wire.md
    notes: Control Plane-Edge proto-socket TCP 계약
  - type: contract
    path: agent-contract/inner/client-control-plane-wire.md
    notes: Client-Control Plane proto-socket WebSocket 계약
  - type: code
    path: apps/control-plane/internal/wire/edge_server.go
    notes: Control Plane Edge TCP server, hello, status request, command dispatch
  - type: code
    path: apps/edge/internal/controlplane/connector.go
    notes: Edge outbound connector, hello, status response, command event relay
  - type: code
    path: apps/control-plane/cmd/control-plane/http_edge_handlers.go
    notes: Control Plane HTTP edge registry/status/events/commands view
  - type: code
    path: apps/client/lib/control_plane_status_repository.dart
    notes: Flutter client HTTP status repository
  - type: code
    path: apps/client/lib/iop_wire/client_wire_client.dart
    notes: Flutter proto-socket Client hello baseline
  - type: test
    path: apps/control-plane/internal/wire/edge_server_test.go
    notes: Control Plane-Edge wire 검증
  - type: test
    path: apps/control-plane/cmd/control-plane/edge_registry_handler_test.go
    notes: provider 일반·long counter의 typed view와 HTTP JSON mapping 검증
  - type: test
    path: apps/edge/internal/service/status_provider_test.go
    notes: 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 정의 동기화.

## 주요 흐름

```mermaid
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 구현과 계약 기준으로 동기화.