52 lines
2.8 KiB
Markdown
52 lines
2.8 KiB
Markdown
---
|
|
domain: workflow-execution
|
|
last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
|
|
last_rule_updated_at: 2026-07-18
|
|
---
|
|
|
|
# workflow-execution
|
|
|
|
## 목적 / 책임
|
|
|
|
Go worker가 제어 플레인의 workflow step을 lease해 in-process executor registry로 실행하고 결과 상태를 갱신한다. 별도 Python executor는 버전 있는 gRPC 계약으로 capability, streaming 진행, 취소와 결과 의미를 제공한다.
|
|
|
|
## 포함 경로
|
|
|
|
- `apps/worker/` — Go workflow worker 프로세스 조립과 실행 진입점
|
|
- `packages/go/workflow/` — step lease, executor registry, 재시도와 상태 전이
|
|
- `packages/python/` — Python gRPC executor와 adaptation 실행 구현
|
|
- `api/proto/` — Go/Python executor wire contract 원본
|
|
- `gen/go/rara/v1/` — Protobuf에서 생성된 Go 타입과 gRPC stub
|
|
|
|
## 제외 경로
|
|
|
|
- `packages/go/controlplane/`, `db/migrations/` — workflow 정의와 영속 상태의 소유권
|
|
- `packages/go/rag/` — 온라인 retrieve/answer 요청 처리
|
|
- `packages/go/integration/` — 제품 중립적인 외부 capability port
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `workflow.Worker` — 실행 가능한 step을 lease하고 executor 결과에 따라 상태 갱신
|
|
- `workflow.Registry` — operation 이름과 in-process Go executor 구현 연결
|
|
- `rara_worker.server.ExecutorService` — Python capability 조회, streaming 실행, 취소 gRPC 서비스
|
|
- `api/proto/rara/v1/executor.proto` — job, progress, artifact, error 계약
|
|
|
|
## 유지할 패턴
|
|
|
|
- worker identity, lease duration, retry delay를 설정에서 읽고 lease 소유권과 재시도 의미를 보존한다.
|
|
- Go executor operation은 명시적 이름으로 registry에 등록하고, Python capability는 이름과 버전을 응답한다.
|
|
- Go worker의 상태 변경은 `leased_by`와 현재 step 상태 조건을 유지한다.
|
|
- Python executor는 `accepted`, `running`, `succeeded`/`failed`/`cancelled` event 순서와 구조화된 오류를 유지한다.
|
|
- Protobuf 변경은 기존 field number를 재사용하지 않고 Go/Python 생성물을 `make proto`로 함께 갱신한다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **control-plane**: workflow와 step run의 영속 스키마는 control-plane 소유이며 이 도메인은 lease된 실행과 결과 갱신만 처리한다.
|
|
- **rag-data-plane**: 온라인 요청 경로를 worker에서 처리하지 않고, workflow가 만든 artifact를 release 승격 뒤 소비하게 한다.
|
|
- **platform-common**: database, config, observability, artifact와 integration port는 공통 adapter에 위임한다.
|
|
|
|
## 금지 사항
|
|
|
|
- `gen/go/rara/v1/`과 `packages/python/src/rara/v1/*_pb2*.py`를 직접 수정하지 않는다.
|
|
- lease 없이 step을 실행하거나 다른 worker 소유의 step 상태를 완료 처리하지 않는다.
|
|
- secret 원문이나 제품별 credential을 job payload와 추적 문서에 기록하지 않는다.
|