toki
0ffcb88db0
- Archive provider-resource-admission-ownership milestone/SDD - Align contract: CP-edge wire, runtime refresh, node runtime, OpenAI surface - Update roadmap: phase state, priority queue - Update specs: control-plane ops, OpenAI surface, edge execution, provider pool refresh - Add node runtime supervisor bootstrapping and unit tests - Fix control-plane edge registry handler and http_views - Fix edge model queue admission and long context queue tests
121 lines
6.8 KiB
Markdown
121 lines
6.8 KiB
Markdown
---
|
|
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 구현과 계약 기준으로 동기화.
|