feat: api parser map 및 contracts 디렉터리 추가, server.go 수정

2026-05-28 05:40:53 +09:00 · 2026-05-28 05:40:53 +09:00 · 4fe5777781
commit 4fe5777781
parent 47f3b75381
7 changed files with 97 additions and 301 deletions
--- a/agent-task/m-contract-codegen-baseline/03+02_api_parser_map/CODE_REVIEW-cloud-G06.md
+++ b/agent-task/m-contract-codegen-baseline/03+02_api_parser_map/CODE_REVIEW-cloud-G06.md
@ -1,111 +0,0 @@
-<!-- task=m-contract-codegen-baseline/03+02_api_parser_map plan=0 tag=API -->
-
-# Code Review Reference - API
-
-> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
-> The task is NOT complete until every implementation-owned section below is filled in.
-> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
-> Fill implementation-owned sections, then stop with active files in place and report ready for review.
-> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
-> Follow the ownership table at the bottom of this file for which sections you own.
-
-## 개요
-
-date=2026-05-28
-task=m-contract-codegen-baseline/03+02_api_parser_map, plan=0, tag=API
-
-## 이 파일을 읽는 리뷰 에이전트에게
-
-> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
-
-각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
-리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
-
-1. 판정을 append한다.
-2. `CODE_REVIEW-cloud-G06.md` → `code_review_cloud_G06_N.log`, `PLAN-cloud-G06.md` → `plan_cloud_G06_M.log`로 아카이브한다.
-3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-contract-codegen-baseline/03+02_api_parser_map/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
-4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
-5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
-
---
-
-## 구현 항목별 완료 여부
-
-| 항목 | 완료 여부 |
-|------|---------|
-| [API-1] API contract parser map helper | [ ] |
-| [API-2] Wire parser map into socket server | [ ] |
-
-## 구현 체크리스트
-
- [ ] [API-1] API 내부 contract parser map helper와 unit test를 추가한다.
- [ ] [API-2] socket server construction이 API parser map을 사용하도록 연결하고 module dependency를 정리한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
-
-## 코드리뷰 전용 체크리스트
-
-> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
-> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
-
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G06_N.log`로 아카이브한다.
- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G06_M.log`로 아카이브한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/m-contract-codegen-baseline/03+02_api_parser_map/`를 `agent-task/archive/YYYY/MM/m-contract-codegen-baseline/03+02_api_parser_map/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-contract-codegen-baseline/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G06.md`와 `CODE_REVIEW-cloud-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
-
-## 계획 대비 변경 사항
-
-_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
-
-## 주요 설계 결정
-
-_구현 에이전트가 주요 설계 결정 사항을 기록한다._
-
-## 리뷰어를 위한 체크포인트
-
- API parser map이 모든 generated request/response payload를 등록하는지 확인한다.
- parser helper가 package-level mutable map을 공유하지 않는지 확인한다.
- `server.go`가 empty parser map 대신 API parser map을 쓰는지 확인한다.
-
-## 검증 결과
-
-_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
-
-필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
-
-### API-1 중간 검증
-```bash
-$ cd services/api && go test ./internal/contracts
-(output)
-```
-
-### API-2 중간 검증
-```bash
-$ cd services/api && go test ./...
-(output)
-```
-
-### 최종 검증
-```bash
-$ cd services/api && go test ./...
-(output)
-$ bin/test
-(output)
-$ bin/lint
-(output)
-```
-
---
-
-> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
-> If anything is blank, go back and fill it in before saving this file.
-> Leave review-agent-only sections unchanged.
--- a/agent-task/m-contract-codegen-baseline/03+02_api_parser_map/PLAN-cloud-G06.md
+++ b/agent-task/m-contract-codegen-baseline/03+02_api_parser_map/PLAN-cloud-G06.md
@ -1,188 +0,0 @@
-<!-- task=m-contract-codegen-baseline/03+02_api_parser_map plan=0 tag=API -->
-
-# Plan - API Parser Map
-
-## 이 파일을 읽는 구현 에이전트에게
-
-`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 검증 명령을 실행하고 실제 stdout/stderr를 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종화는 code-review 스킬 전용이다.
-
-## 배경
-
-Go API는 proto-socket session boundary를 맡지만 현재 ALT application payload parser map을 등록하지 않는다. `02+01_codegen_check`가 generated Go contracts를 만든 뒤, API 내부에 표준 parser map 위치를 두면 다음 `Socket Session Loop` Milestone에서 handshake/request-response를 바로 얹을 수 있다.
-
-## 분석 결과
-
-### 읽은 파일
-
- `agent-roadmap/current.md`
- `agent-roadmap/phase/foundation-alignment/PHASE.md`
- `agent-roadmap/phase/foundation-alignment/milestones/contract-codegen-baseline.md`
- `agent-ops/rules/project/domain/api/rules.md`
- `agent-ops/rules/project/domain/contracts/rules.md`
- `services/api/go.mod`
- `services/api/internal/socket/server.go`
- `services/api/internal/config/config.go`
- `services/api/cmd/alt-api/main.go`
- `packages/contracts/proto/alt/v1/common.proto`
- `packages/contracts/proto/alt/v1/market.proto`
- `packages/contracts/proto/alt/v1/backtest.proto`
- `../proto-socket/go/communicator.go`
- `bin/test`
- `bin/lint`
-
-### 테스트 커버리지 공백
-
- API parser map helper: 기존 테스트 없음. 새 unit test가 모든 ALT request/response/result message key와 parse success를 검증해야 한다.
- `socket.NewServer` parser map 주입: 기존 테스트 없음. 최소한 helper가 non-empty이고 server construction이 컴파일되는 것을 `go test ./...`로 검증한다.
-
-### 심볼 참조
-
- renamed/removed symbols: none.
-
-### 분할 판단
-
-분할 정책을 먼저 평가했다. 이 plan은 `03+02_api_parser_map`이며 `02+01_codegen_check`가 `complete.log`를 만든 뒤 시작한다. Client Dart parser map은 별도 `04+02_client_parser_map`에서 병렬 처리한다.
-
-### 범위 결정 근거
-
-이 subtask는 `services/api/**`와 API module dependency만 다룬다. Flutter client parser map, UI, actual request handlers, worker execution은 범위 밖이다.
-
-### 빌드 등급
-
-build=`cloud-G06`, review=`cloud-G06`. Protocol parser registration이 API runtime boundary에 들어가고 generated module dependency를 추가하므로 cloud review가 필요하다.
-
-## 의존 관계 및 구현 순서
-
-`03+02_api_parser_map`은 같은 task group의 `02+01_codegen_check`가 `complete.log`를 만든 뒤 시작한다. 이 의존성은 directory name의 `+02`가 source of truth다.
-
-## 구현 체크리스트
-
- [ ] [API-1] API 내부 contract parser map helper와 unit test를 추가한다.
- [ ] [API-2] socket server construction이 API parser map을 사용하도록 연결하고 module dependency를 정리한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
-
-### [API-1] API contract parser map helper
-
-#### 문제
-
-`../proto-socket/go/communicator.go:20`의 `ParserMap`은 `map[string]func([]byte) (proto.Message, error)`이고, parser가 없으면 `../proto-socket/go/communicator.go:304`에서 error를 반환한다. ALT API에는 generated `alt.v1` messages를 parser map으로 묶는 표준 위치가 없다.
-
-Before:
-
-```go
-// ../proto-socket/go/communicator.go:304
-func (c *Communicator) parse(typeName string, data []byte) (proto.Message, error) {
-	c.mu.RLock()
-	parser := c.parserMap[typeName]
-	c.mu.RUnlock()
-	if parser == nil {
-		return nil, fmt.Errorf("protobuf parser is not registered for type %s", typeName)
-	}
-	return parser(data)
-}
-```
-
-해결 후 형태:
-
-```go
-package contracts
-
-func ParserMap() protoSocket.ParserMap {
-	return protoSocket.ParserMap{
-		protoSocket.TypeNameOf(&altv1.HelloRequest{}): parserFor(func() proto.Message { return &altv1.HelloRequest{} }),
-	}
-}
-```
-
-#### 해결 방법
-
-`services/api/internal/contracts/parser_map.go`를 만들고 generated `altv1` message 전체를 등록한다. request/response/result payload를 모두 포함하고 helper는 map을 새로 반환해 호출자가 mutate해도 package 전역 상태가 생기지 않게 한다.
-
-#### 수정 파일 및 체크리스트
-
- [ ] `services/api/internal/contracts/parser_map.go`: `ParserMap()`과 shared `parserFor` helper 추가.
- [ ] `services/api/internal/contracts/parser_map_test.go`: map keys와 parse success 검증.
- [ ] `services/api/go.mod`: generated Go module require 추가.
-
-#### 테스트 작성
-
-작성한다. `TestParserMapIncludesAltMessages`는 `HelloRequest`, `HelloResponse`, `ListInstrumentsRequest`, `ListInstrumentsResponse`, `ListBarsRequest`, `ListBarsResponse`, `StartBacktestRequest`, `StartBacktestResponse`, `GetBacktestRunRequest`, `GetBacktestRunResponse`, `GetBacktestResultRequest`, `GetBacktestResultResponse`, `BacktestResult`를 등록/parse한다.
-
-#### 중간 검증
-
-```bash
-cd services/api && go test ./internal/contracts
-```
-
-기대 결과: exit 0.
-
-### [API-2] Wire parser map into socket server
-
-#### 문제
-
-`services/api/internal/socket/server.go:12`는 `protoSocket.ParserMap{}`를 전달해 ALT payload가 들어와도 parse할 수 없다.
-
-Before:
-
-```go
-// services/api/internal/socket/server.go:10
-func NewServer(cfg config.Config) *protoSocket.WsServer {
-	return protoSocket.NewWsServer(cfg.Host, cfg.Port, cfg.SocketPath, func(conn *websocket.Conn) *protoSocket.WsClient {
-		return protoSocket.NewWsClient(conn, cfg.HeartbeatIntervalSec, cfg.HeartbeatWaitSec, protoSocket.ParserMap{})
-	})
-}
-```
-
-해결 후 형태:
-
-```go
-import (
-	apiContracts "git.toki-labs.com/toki/alt/services/api/internal/contracts"
-)
-
-return protoSocket.NewWsClient(conn, cfg.HeartbeatIntervalSec, cfg.HeartbeatWaitSec, apiContracts.ParserMap())
-```
-
-#### 해결 방법
-
-`server.go`에서 API contracts helper를 import하고 `NewWsClient`에 `apiContracts.ParserMap()`을 전달한다. `go mod tidy`로 generated contract module dependency를 정리한다.
-
-#### 수정 파일 및 체크리스트
-
- [ ] `services/api/internal/socket/server.go`: empty parser map을 API parser map으로 교체.
- [ ] `services/api/go.mod`: generated contract module dependency 유지.
- [ ] `services/api/go.sum`: 필요한 checksum 변경 반영.
-
-#### 테스트 작성
-
-별도 socket server unit test는 작성하지 않는다. 이 subtask는 parser map helper unit test와 `go test ./...` 컴파일 검증으로 충분하다. 실제 handshake/request-response behavior는 후속 `Socket Session Loop` Milestone 범위다.
-
-#### 중간 검증
-
-```bash
-cd services/api && go test ./...
-```
-
-기대 결과: exit 0.
-
-## 수정 파일 요약
-
-| 파일 | 항목 |
-|------|------|
-| `services/api/internal/contracts/parser_map.go` | API-1 |
-| `services/api/internal/contracts/parser_map_test.go` | API-1 |
-| `services/api/internal/socket/server.go` | API-2 |
-| `services/api/go.mod` | API-1, API-2 |
-| `services/api/go.sum` | API-2 |
-
-## 최종 검증
-
-```bash
-cd services/api && go test ./...
-bin/test
-bin/lint
-```
-
-기대 결과: 모든 명령 exit 0. Go test cache output은 허용한다.
-
-모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
--- a/services/api/go.mod
+++ b/services/api/go.mod
@ -3,10 +3,11 @@ module git.toki-labs.com/toki/alt/services/api
 go 1.22

 require (
+	git.toki-labs.com/toki/alt/packages/contracts/gen/go v0.0.0-20260527202903-88c673d97307
 	git.toki-labs.com/toki/proto-socket/go v0.0.0
 	nhooyr.io/websocket v1.8.17
 )

-require google.golang.org/protobuf v1.36.5 // indirect
+require google.golang.org/protobuf v1.36.5

 replace git.toki-labs.com/toki/proto-socket/go => ../../../proto-socket/go
--- a/services/api/go.sum
+++ b/services/api/go.sum
@ -1,3 +1,5 @@
+git.toki-labs.com/toki/alt/packages/contracts/gen/go v0.0.0-20260527202903-88c673d97307 h1:0127klckbNovR/VlASM+w5mC51iN/jf4XR0b4ZGwFOQ=
+git.toki-labs.com/toki/alt/packages/contracts/gen/go v0.0.0-20260527202903-88c673d97307/go.mod h1:wf7tcjiAKQB3uLR/jKELLtWsSZkCssq9jIIWLKBT5vk=
 github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
--- a/services/api/internal/contracts/parser_map.go
+++ b/services/api/internal/contracts/parser_map.go
@ -0,0 +1,37 @@
+package contracts
+
+import (
+	"google.golang.org/protobuf/proto"
+
+	protoSocket "git.toki-labs.com/toki/proto-socket/go"
+	altv1 "git.toki-labs.com/toki/alt/packages/contracts/gen/go/alt/v1"
+)
+
+// ParserMap returns a fresh ParserMap populated with all ALT API messages.
+func ParserMap() protoSocket.ParserMap {
+	return protoSocket.ParserMap{
+		protoSocket.TypeNameOf(&altv1.HelloRequest{}):              parserFor(func() proto.Message { return &altv1.HelloRequest{} }),
+		protoSocket.TypeNameOf(&altv1.HelloResponse{}):             parserFor(func() proto.Message { return &altv1.HelloResponse{} }),
+		protoSocket.TypeNameOf(&altv1.ListInstrumentsRequest{}):    parserFor(func() proto.Message { return &altv1.ListInstrumentsRequest{} }),
+		protoSocket.TypeNameOf(&altv1.ListInstrumentsResponse{}):   parserFor(func() proto.Message { return &altv1.ListInstrumentsResponse{} }),
+		protoSocket.TypeNameOf(&altv1.ListBarsRequest{}):           parserFor(func() proto.Message { return &altv1.ListBarsRequest{} }),
+		protoSocket.TypeNameOf(&altv1.ListBarsResponse{}):          parserFor(func() proto.Message { return &altv1.ListBarsResponse{} }),
+		protoSocket.TypeNameOf(&altv1.StartBacktestRequest{}):      parserFor(func() proto.Message { return &altv1.StartBacktestRequest{} }),
+		protoSocket.TypeNameOf(&altv1.StartBacktestResponse{}):     parserFor(func() proto.Message { return &altv1.StartBacktestResponse{} }),
+		protoSocket.TypeNameOf(&altv1.GetBacktestRunRequest{}):     parserFor(func() proto.Message { return &altv1.GetBacktestRunRequest{} }),
+		protoSocket.TypeNameOf(&altv1.GetBacktestRunResponse{}):    parserFor(func() proto.Message { return &altv1.GetBacktestRunResponse{} }),
+		protoSocket.TypeNameOf(&altv1.GetBacktestResultRequest{}):  parserFor(func() proto.Message { return &altv1.GetBacktestResultRequest{} }),
+		protoSocket.TypeNameOf(&altv1.GetBacktestResultResponse{}): parserFor(func() proto.Message { return &altv1.GetBacktestResultResponse{} }),
+		protoSocket.TypeNameOf(&altv1.BacktestResult{}):            parserFor(func() proto.Message { return &altv1.BacktestResult{} }),
+	}
+}
+
+func parserFor(factory func() proto.Message) func([]byte) (proto.Message, error) {
+	return func(data []byte) (proto.Message, error) {
+		msg := factory()
+		if err := proto.Unmarshal(data, msg); err != nil {
+			return nil, err
+		}
+		return msg, nil
+	}
+}
--- a/services/api/internal/contracts/parser_map_test.go
+++ b/services/api/internal/contracts/parser_map_test.go
@ -0,0 +1,54 @@
+package contracts
+
+import (
+	"testing"
+
+	"google.golang.org/protobuf/proto"
+
+	protoSocket "git.toki-labs.com/toki/proto-socket/go"
+	altv1 "git.toki-labs.com/toki/alt/packages/contracts/gen/go/alt/v1"
+)
+
+func TestParserMapIncludesAltMessages(t *testing.T) {
+	pm := ParserMap()
+
+	messages := []proto.Message{
+		&altv1.HelloRequest{},
+		&altv1.HelloResponse{},
+		&altv1.ListInstrumentsRequest{},
+		&altv1.ListInstrumentsResponse{},
+		&altv1.ListBarsRequest{},
+		&altv1.ListBarsResponse{},
+		&altv1.StartBacktestRequest{},
+		&altv1.StartBacktestResponse{},
+		&altv1.GetBacktestRunRequest{},
+		&altv1.GetBacktestRunResponse{},
+		&altv1.GetBacktestResultRequest{},
+		&altv1.GetBacktestResultResponse{},
+		&altv1.BacktestResult{},
+	}
+
+	for _, msg := range messages {
+		typeName := protoSocket.TypeNameOf(msg)
+		t.Run(typeName, func(t *testing.T) {
+			parser := pm[typeName]
+			if parser == nil {
+				t.Fatalf("parser not registered for type %s", typeName)
+			}
+
+			data, err := proto.Marshal(msg)
+			if err != nil {
+				t.Fatalf("failed to marshal message: %v", err)
+			}
+
+			parsed, err := parser(data)
+			if err != nil {
+				t.Fatalf("failed to parse message: %v", err)
+			}
+
+			if protoSocket.TypeNameOf(parsed) != typeName {
+				t.Errorf("parsed type mismatch: expected %s, got %s", typeName, protoSocket.TypeNameOf(parsed))
+			}
+		})
+	}
+}
--- a/services/api/internal/socket/server.go
+++ b/services/api/internal/socket/server.go
@ -5,10 +5,11 @@ import (
 	"nhooyr.io/websocket"

 	"git.toki-labs.com/toki/alt/services/api/internal/config"
+	apiContracts "git.toki-labs.com/toki/alt/services/api/internal/contracts"
 )

 func NewServer(cfg config.Config) *protoSocket.WsServer {
 	return protoSocket.NewWsServer(cfg.Host, cfg.Port, cfg.SocketPath, func(conn *websocket.Conn) *protoSocket.WsClient {
-		return protoSocket.NewWsClient(conn, cfg.HeartbeatIntervalSec, cfg.HeartbeatWaitSec, protoSocket.ParserMap{})
+		return protoSocket.NewWsClient(conn, cfg.HeartbeatIntervalSec, cfg.HeartbeatWaitSec, apiContracts.ParserMap())
 	})
 }