iop/agent-ops/rules/project/domain/edge/rules.md

edge

목적 / 책임

외부 API gateway로 발전할 앱 영역이며, 현재는 node 연결을 수락하고 capability를 조회하여 registry에 등록하는 TCP/protobuf 서버 책임을 가진다.

포함 경로

• apps/edge/cmd/iop-edge/ — edge CLI 진입점과 serve 커맨드
• apps/edge/internal/bootstrap/ — fx 의존성 주입과 서버 시작/종료 lifecycle
• apps/edge/internal/node/ — 연결된 node registry와 node 선택
• apps/edge/internal/transport/ — node 연결 수락, capability 요청, run event 수신
• apps/edge/README.md — edge 계획과 현재 placeholder 범위

제외 경로

• apps/node/ — 실제 모델 실행과 adapter 관리
• apps/control-plane/ — 노드 등록/정책/스케줄링 예정 영역
• apps/worker/ — 비동기 작업 처리 예정 영역
• packages/ — 공통 설정/관측성/인증 패키지
• proto/ — 메시지 계약 원본과 생성물

주요 구성 요소

• transport.Server — proto-socket TCP 서버 wrapper
• node.Registry — 연결된 node의 NodeEntry 저장/조회
• node.NodeEntry — node ID, TCP client, adapter capability 정보
• bootstrap.Module — edge 서버와 metrics lifecycle 구성

유지할 패턴

• edge는 node 연결 상태와 capability를 registry에 반영하는 역할을 먼저 안정화한다.
• 외부 OpenAI-compatible HTTP API는 node/transport 안정화 이후 확장한다.
• 연결 직후 capability request를 보내고 실패 시 연결을 정리하는 흐름을 유지한다.
• registry는 동시성 안전성을 유지하고 외부로 내부 map을 노출하지 않는다.

다른 도메인과의 경계

• node: edge는 node를 실행하지 않는다. node capability를 기반으로 요청을 보낼 대상만 선택한다.
• platform-common: edge 설정, metrics, protobuf 타입은 platform-common 계약을 따른다.
• control-plane 후보: 장기적으로 노드 등록/정책/스케줄링이 control-plane으로 분리될 수 있으므로 edge에 해당 책임을 굳히기 전에 경계를 재검토한다.

금지 사항

• edge를 구현하면서 node adapter 실행 로직을 복제하지 않는다.
• OpenAI-compatible HTTP API를 추가할 때 내부 TCP/protobuf 경계를 우회하지 않는다.
• gRPC 또는 WebSocket을 기본 내부 transport로 바꾸지 않는다.
• proto/gen/iop/*.pb.go 생성 파일을 직접 수정하지 않는다.