3.3 KiB
3.3 KiB
platform-common
목적 / 책임
여러 앱이 공유하는 설정, 인증, 정책, 메타데이터, 작업 상태, 관측성, 버전, protobuf 계약을 관리한다. 앱별 구현보다 안정적인 공통 계약과 작은 유틸리티를 제공하며, 내부 실행 계약은 adapter + target 방향을 우선한다.
포함 경로
packages/auth/— mTLS 인증 설정 helperpackages/config/— 앱 설정 struct, 기본값, YAML 로딩packages/jobs/— 작업 상태와 작업 메타데이터 타입packages/metadata/— 공통 metadata map helperpackages/observability/— zap logger와 Prometheus health/metrics 서버packages/policy/— 정책 엔진 인터페이스와 passthrough 구현packages/version/— 앱 버전 상수proto/iop/— protobuf 메시지 계약 원본proto/gen/iop/— protobuf 생성물configs/— 앱별 설정 예시
제외 경로
apps/node/— node 실행 파이프라인과 adapter 관리apps/edge/— 실행 그룹 컨트롤러와 node registryapps/control-plane/— control-plane 앱 구현 예정 영역apps/worker/— worker 앱 구현 예정 영역
주요 구성 요소
config.NodeConfig/config.EdgeConfig— 앱 설정 계약auth.LoadServerTLS/auth.LoadClientTLS— mTLS TLS config 생성observability.NewLogger/observability.ServeMetrics— 공통 로깅/메트릭policy.Engine— 정책 적용/검증 계약jobs.Job— 비동기 작업 상태 placeholder; 내부 실행 대상은target으로 표현proto/iop/*.proto— 앱 간 메시지 원본 계약
유지할 패턴
- 공통 패키지는 특정 앱의 내부 패키지를 import하지 않는다.
- 설정 struct 필드 변경 시 YAML tag, mapstructure tag, default,
configs/*.yaml예시를 함께 확인한다. - protobuf 계약 변경은
proto/iop/*.proto에서 시작하고make proto로 생성물을 갱신한다. - 생성 파일(
proto/gen/iop/*.pb.go)은 사람이 직접 편집하지 않는다. - 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다.
RunRequest,ExecutionSpec,NodeCommandRequest, job/history 계열 계약을 변경할 때 내부 실행 용어는target을 우선하고,model은 외부 호환 경계인지 확인한다.
다른 도메인과의 경계
- node: node가 필요로 하는 설정/타입/계약을 제공하지만 실행 파이프라인의 소유자는 node이다.
- edge: edge가 필요로 하는 설정/관측성/protobuf 계약을 제공하지만 실행 그룹 제어와 node registry 동작의 소유자는 edge이다.
- control-plane/worker 후보: 두 앱이 구현되면 필요한 공통 타입만 이 영역으로 승격하고 앱 내부 책임은 각 도메인에 둔다.
금지 사항
packages에서apps/*/internal패키지를 import하지 않는다.- 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다.
- 내부 실행 계약을 확장하면서
model중심 명명을 되살리지 않는다. 외부 API 호환이 필요한 경우 경계와 변환 위치를 명시한다. - protobuf 생성물을 직접 수정하지 않는다.
- 설정 파일만 바꾸고
packages/config의 로딩/default와 불일치하게 두지 않는다.