chore: update README, rules, and add roadmap
This commit is contained in:
parent
cffebc0fc7
commit
68ec5e7d67
10 changed files with 351 additions and 3 deletions
|
|
@ -45,7 +45,7 @@ Protocol compatibility is tracked separately from language package versions. See
|
|||
|
||||
New language implementations should start from [PORTING_GUIDE.md](PORTING_GUIDE.md) and the templates in [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/). Mark an implementation available only after its same-language tests and cross-language tests pass.
|
||||
|
||||
Roadmap direction: every implementation should stay as close to native platform behavior as possible outside the protobuf layer. Prefer built-in TCP/TLS/WebSocket, concurrency, timer, and binary APIs over external packages. A focused library that directly matches a protocol need is acceptable when native support is missing or impractical, but broad frameworks or runtime layers must not be introduced just to cover a narrow feature such as WebSocket transport. Runtime dependencies beyond protobuf must be explicitly justified, protocol-relevant, and kept minimal.
|
||||
Detailed planning now lives in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md). Keep implementation status here as the public snapshot; roadmap direction, CI automation, and future C#/Swift work are tracked in the roadmap.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -172,7 +172,7 @@ If you want a copyable scaffold for using this module from another repository, s
|
|||
|
||||
## Running Tests
|
||||
|
||||
Local commands are documented here for development and troubleshooting. Continuous verification is expected to run in an external tool, with Jenkins planned to execute the full supported-language and cross-language test suite.
|
||||
Local commands are documented here for development and troubleshooting. Continuous verification automation is tracked in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md).
|
||||
|
||||
```bash
|
||||
cd dart
|
||||
|
|
|
|||
54
agent-ops/roadmap/ROADMAP.md
Normal file
54
agent-ops/roadmap/ROADMAP.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# Proto Socket Roadmap
|
||||
|
||||
## Overall Goal
|
||||
|
||||
Proto Socket aims to provide a thin, stable, protocol-first socket communication library that behaves consistently across languages and platforms. The shared contract is Protocol Buffers serialization, TCP/WebSocket binary framing, type-based routing, request-response correlation, and built-in heartbeat.
|
||||
|
||||
The core should stay small: application semantics such as auth, sessions, chat, game rules, room logic, and agent workflow belong above this protocol layer.
|
||||
|
||||
## Current Position
|
||||
|
||||
- Active Phase: Phase 2 - Verification and compatibility
|
||||
- Active Milestone: M03 Continuous Verification
|
||||
- Active Milestone File: agent-ops/roadmap/milestones/M03-continuous-verification.md
|
||||
|
||||
## Migration Notes
|
||||
|
||||
This roadmap migrates the roadmap-like planning that previously lived in top-level documentation:
|
||||
|
||||
- `README.md` implementation status table: summarized in the Milestone Index as available and planned language work.
|
||||
- `README.md` roadmap direction paragraph: migrated into the dependency and native-platform direction in M02, M04, and M05.
|
||||
- `README.md` Jenkins planning note: migrated into M03 Continuous Verification.
|
||||
- `PORTING_GUIDE.md` C# and Swift guidance: linked to planned port milestones M04 and M05.
|
||||
|
||||
## Phase Overview
|
||||
|
||||
| Phase | Status | Goal |
|
||||
|-------|--------|------|
|
||||
| Phase 1 - Protocol foundation | Done | Define protocol version `0.1`, wire format, versioning policy, canonical proto source, and reference implementation patterns. |
|
||||
| Phase 2 - Verification and compatibility | Active | Keep available implementations aligned through same-language tests, cross-language tests, proto sync checks, and continuous verification. |
|
||||
| Phase 3 - Remaining native platform ports | Planned | Add C# and Swift implementations while preserving the protocol contract and native-first runtime direction. |
|
||||
| Phase 4 - Release readiness | Planned | Prepare language packages, release documentation, and compatibility statements for external consumption. |
|
||||
|
||||
## Milestone Index
|
||||
|
||||
| Milestone | Phase | Status | File | Summary |
|
||||
|-----------|-------|--------|------|---------|
|
||||
| M01 Protocol Baseline | Phase 1 | Done | agent-ops/roadmap/milestones/M01-protocol-baseline.md | Protocol `0.1`, canonical proto, framing, heartbeat, nonce, and versioning policy are documented. |
|
||||
| M02 Available Language Parity | Phase 2 | Done | agent-ops/roadmap/milestones/M02-available-language-parity.md | Dart, Go, Kotlin, Python, and TypeScript are listed as available and have same-language and cross-language test entry points. |
|
||||
| M03 Continuous Verification | Phase 2 | Active | agent-ops/roadmap/milestones/M03-continuous-verification.md | Automate the supported-language and cross-language test matrix, with Jenkins currently named as the expected external runner. |
|
||||
| M04 C# Unity/.NET Port | Phase 3 | Planned | agent-ops/roadmap/milestones/M04-csharp-port.md | Add a C# implementation for Unity and .NET using native runtime patterns where possible. |
|
||||
| M05 Swift Apple Platform Port | Phase 3 | Planned | agent-ops/roadmap/milestones/M05-swift-port.md | Add a Swift implementation for iOS and macOS using Swift concurrency and Apple-native transport APIs where possible. |
|
||||
| M06 Release Readiness | Phase 4 | Planned | agent-ops/roadmap/milestones/M06-release-readiness.md | Prepare package publication, compatibility notes, and release checks per language. |
|
||||
|
||||
## Loading Policy
|
||||
|
||||
- General implementation work should read `agent-ops/roadmap/current.md` and the Active Milestone file only.
|
||||
- Read this full `ROADMAP.md` only for roadmap creation, roadmap updates, Phase transitions, Milestone additions, or Milestone restructuring.
|
||||
- If a requested task conflicts with the Active Milestone Goal or Non-Goals, pause and confirm direction before implementing.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Active Milestone is inferred from the existing README note that Jenkins is planned for full supported-language and cross-language verification.
|
||||
- The order between C# and Swift may change if product priorities shift.
|
||||
- Release target registries and package publishing order are not yet confirmed.
|
||||
5
agent-ops/roadmap/current.md
Normal file
5
agent-ops/roadmap/current.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
# Current Roadmap Context
|
||||
|
||||
- Active Phase: Phase 2 - Verification and compatibility
|
||||
- Active Milestone: M03 Continuous Verification
|
||||
- Active Milestone File: agent-ops/roadmap/milestones/M03-continuous-verification.md
|
||||
45
agent-ops/roadmap/milestones/M01-protocol-baseline.md
Normal file
45
agent-ops/roadmap/milestones/M01-protocol-baseline.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# M01 Protocol Baseline
|
||||
|
||||
## Goal
|
||||
|
||||
Establish the shared Proto Socket protocol contract so every implementation can interoperate without embedding application-specific behavior into the core.
|
||||
|
||||
## Phase
|
||||
|
||||
Phase 1 - Protocol foundation
|
||||
|
||||
## Status
|
||||
|
||||
Done
|
||||
|
||||
## Scope
|
||||
|
||||
- Document TCP 4-byte big-endian length-prefixed framing.
|
||||
- Document WebSocket/WSS binary-frame transport.
|
||||
- Define `PacketBase`, `typeName`, `nonce`, `responseNonce`, and `HeartBeat` behavior.
|
||||
- Define protocol/package version separation.
|
||||
- Treat `proto/message_common.proto` as the canonical proto source.
|
||||
|
||||
## Required Features
|
||||
|
||||
- [x] Protocol version `0.1` documented in `PROTOCOL.md` and `VERSIONING.md`.
|
||||
- [x] Canonical proto source documented as `proto/message_common.proto`.
|
||||
- [x] TCP and WebSocket wire formats documented.
|
||||
- [x] Heartbeat lifecycle and request-response correlation documented.
|
||||
- [x] Breaking and non-breaking protocol change policy documented.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Implementers can build a conforming language port from `PROTOCOL.md`, `VERSIONING.md`, and `PORTING_GUIDE.md`.
|
||||
- Protocol-level changes have an explicit compatibility review path.
|
||||
- Generated language proto copies can be checked against the canonical schema.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Define application-level auth, session, chat, game, room, or agent workflow semantics.
|
||||
- Publish language packages.
|
||||
- Add new transport families beyond TCP/TLS and WebSocket/WSS.
|
||||
|
||||
## Context for Work
|
||||
|
||||
Use `PROTOCOL.md` as the wire-format source of truth and `VERSIONING.md` for compatibility policy. If proto schemas change, regenerate bindings and run `tools/check_proto_sync.sh`.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# M02 Available Language Parity
|
||||
|
||||
## Goal
|
||||
|
||||
Bring the checked-in available implementations into a common protocol surface with same-language tests and cross-language test entry points.
|
||||
|
||||
## Phase
|
||||
|
||||
Phase 2 - Verification and compatibility
|
||||
|
||||
## Status
|
||||
|
||||
Done
|
||||
|
||||
## Scope
|
||||
|
||||
- Maintain the available implementation set listed in `README.md` and `PROTOCOL.md`.
|
||||
- Keep Dart, Go, Kotlin, Python, and TypeScript aligned with protocol version `0.1`.
|
||||
- Keep runtime dependencies native-first and narrowly scoped outside protobuf.
|
||||
- Keep cross-language test runners available for the supported language matrix.
|
||||
|
||||
## Required Features
|
||||
|
||||
- [x] Dart implementation available under `dart/`.
|
||||
- [x] Go implementation available under `go/`.
|
||||
- [x] Kotlin implementation available under `kotlin/`.
|
||||
- [x] Python implementation available under `python/`.
|
||||
- [x] TypeScript implementation available under `typescript/`.
|
||||
- [x] Cross-language test entry points exist across the available implementations.
|
||||
- [x] Dependency direction documented: protobuf is the core protocol dependency; other runtime dependencies must be native-first, protocol-relevant, and minimal.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A maintainer can identify available and planned implementations from top-level docs.
|
||||
- New language work can start from `PORTING_GUIDE.md` and the project crosstest templates.
|
||||
- Available implementations preserve the documented protocol contract.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Mark C# or Swift as available before implementation, same-language tests, and cross-language tests pass.
|
||||
- Introduce broad frameworks or runtime layers only to cover narrow protocol needs.
|
||||
- Expand protocol semantics beyond the transport-level contract.
|
||||
|
||||
## Context for Work
|
||||
|
||||
When adding or changing language implementations, use `PORTING_GUIDE.md` and the project skill `agent-ops/skills/project/add-proto-socket-crosstest-language/SKILL.md`. Before changing protocol files, read the protocol domain rule.
|
||||
49
agent-ops/roadmap/milestones/M03-continuous-verification.md
Normal file
49
agent-ops/roadmap/milestones/M03-continuous-verification.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
# M03 Continuous Verification
|
||||
|
||||
## Goal
|
||||
|
||||
Automate confidence for all available implementations by running same-language tests, cross-language tests, and proto sync checks in an external CI runner.
|
||||
|
||||
## Phase
|
||||
|
||||
Phase 2 - Verification and compatibility
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Scope
|
||||
|
||||
- Turn the README test command matrix into a repeatable CI workflow.
|
||||
- Include Dart, Go, Kotlin, Python, and TypeScript same-language tests.
|
||||
- Include the available cross-language test runners.
|
||||
- Include proto synchronization checks when proto files change.
|
||||
- Keep the workflow aligned with the existing local commands and project test-matrix skill.
|
||||
|
||||
## Required Features
|
||||
|
||||
- [ ] Confirm the external CI entry point. The migrated roadmap context keeps Jenkins as the current candidate until changed.
|
||||
- [ ] Run Dart unit tests.
|
||||
- [ ] Run Go unit tests.
|
||||
- [ ] Run Kotlin unit tests.
|
||||
- [ ] Run Python unit tests.
|
||||
- [ ] Run TypeScript checks and unit tests.
|
||||
- [ ] Run available cross-language checks across Dart, Go, Kotlin, Python, and TypeScript.
|
||||
- [ ] Run `tools/check_proto_sync.sh` when proto bindings may be affected.
|
||||
- [ ] Document how to inspect failures and rerun the matrix locally.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A single CI job or pipeline can validate the full supported-language and cross-language matrix.
|
||||
- CI failures identify the failing language pair or same-language package clearly.
|
||||
- The local commands in `README.md` remain consistent with the automated workflow.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Add C# or Swift implementation work in this milestone.
|
||||
- Change protocol behavior or package APIs for the sake of CI convenience.
|
||||
- Require every normal development task to read the full roadmap.
|
||||
|
||||
## Context for Work
|
||||
|
||||
Use `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md` and `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh` as the closest existing automation context. Treat Jenkins as the current documented candidate unless the user chooses another runner.
|
||||
47
agent-ops/roadmap/milestones/M04-csharp-port.md
Normal file
47
agent-ops/roadmap/milestones/M04-csharp-port.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# M04 C# Unity/.NET Port
|
||||
|
||||
## Goal
|
||||
|
||||
Add a C# implementation that supports Unity and .NET consumers while preserving the protocol `0.1` contract and native-first runtime direction.
|
||||
|
||||
## Phase
|
||||
|
||||
Phase 3 - Remaining native platform ports
|
||||
|
||||
## Status
|
||||
|
||||
Planned
|
||||
|
||||
## Scope
|
||||
|
||||
- Implement the core transport abstraction, communicator, nonce handling, request-response correlation, heartbeat, and close-once behavior.
|
||||
- Implement TCP/TLS and WebSocket/WSS support where practical for the target runtime.
|
||||
- Add same-language tests and cross-language tests before marking the implementation available.
|
||||
- Document any non-protobuf runtime dependency and why native APIs are insufficient.
|
||||
|
||||
## Required Features
|
||||
|
||||
- [ ] Choose supported .NET and Unity version targets.
|
||||
- [ ] Generate or maintain C# protobuf bindings from the canonical schema.
|
||||
- [ ] Implement `ITransport` and communicator core.
|
||||
- [ ] Implement TCP/TLS client and server support.
|
||||
- [ ] Implement WebSocket/WSS support with a focused dependency only if native support is insufficient.
|
||||
- [ ] Add same-language tests.
|
||||
- [ ] Add cross-language test runners.
|
||||
- [ ] Update top-level implementation status only after tests pass.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- C# peers interoperate with at least one available implementation through the documented protocol.
|
||||
- C# implementation follows `PORTING_GUIDE.md` and keeps Unity main-thread concerns outside the protocol core.
|
||||
- Runtime dependency choices are documented and protocol-relevant.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Add Unity-specific gameplay, room, auth, session, or chat semantics.
|
||||
- Change the protocol to accommodate C#-specific APIs.
|
||||
- Mark C# as available without passing same-language and cross-language checks.
|
||||
|
||||
## Context for Work
|
||||
|
||||
Use the C# section of `PORTING_GUIDE.md` before implementation. Reference Go for concurrency and close-once patterns, and Dart for public API shape and parser map examples.
|
||||
47
agent-ops/roadmap/milestones/M05-swift-port.md
Normal file
47
agent-ops/roadmap/milestones/M05-swift-port.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# M05 Swift Apple Platform Port
|
||||
|
||||
## Goal
|
||||
|
||||
Add a Swift implementation for iOS and macOS while preserving the protocol `0.1` contract and Apple-native runtime direction.
|
||||
|
||||
## Phase
|
||||
|
||||
Phase 3 - Remaining native platform ports
|
||||
|
||||
## Status
|
||||
|
||||
Planned
|
||||
|
||||
## Scope
|
||||
|
||||
- Implement the core transport abstraction, communicator, nonce handling, request-response correlation, heartbeat, and close-once behavior.
|
||||
- Use Swift concurrency, actors, `URLSessionWebSocketTask`, and Apple platform APIs where practical.
|
||||
- Add same-language tests and cross-language tests before marking the implementation available.
|
||||
- Document any non-protobuf runtime dependency and why native APIs are insufficient.
|
||||
|
||||
## Required Features
|
||||
|
||||
- [ ] Choose supported Swift and Apple platform targets.
|
||||
- [ ] Generate Swift protobuf bindings from the canonical schema.
|
||||
- [ ] Implement transport and communicator core.
|
||||
- [ ] Implement TCP/TLS support.
|
||||
- [ ] Implement WebSocket/WSS support.
|
||||
- [ ] Add same-language tests.
|
||||
- [ ] Add cross-language test runners.
|
||||
- [ ] Update top-level implementation status only after tests pass.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Swift peers interoperate with at least one available implementation through the documented protocol.
|
||||
- Swift implementation follows `PORTING_GUIDE.md` and keeps platform UI/threading concerns outside the protocol core.
|
||||
- Runtime dependency choices are documented and protocol-relevant.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Add app-specific auth, session, chat, game, or Apple UI abstractions.
|
||||
- Change the protocol to accommodate Swift-specific APIs.
|
||||
- Mark Swift as available without passing same-language and cross-language checks.
|
||||
|
||||
## Context for Work
|
||||
|
||||
Use the Swift section of `PORTING_GUIDE.md` before implementation. Prefer actor isolation and Swift concurrency for shared state and cancellation behavior where it fits the protocol core.
|
||||
44
agent-ops/roadmap/milestones/M06-release-readiness.md
Normal file
44
agent-ops/roadmap/milestones/M06-release-readiness.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# M06 Release Readiness
|
||||
|
||||
## Goal
|
||||
|
||||
Prepare the project for repeatable external consumption with clear package versions, protocol compatibility statements, and release checks per available language.
|
||||
|
||||
## Phase
|
||||
|
||||
Phase 4 - Release readiness
|
||||
|
||||
## Status
|
||||
|
||||
Planned
|
||||
|
||||
## Scope
|
||||
|
||||
- Clarify package publication targets and release order per language.
|
||||
- Ensure each published package states the protocol version it implements.
|
||||
- Keep package versions independent from protocol compatibility versioning.
|
||||
- Document release checks and compatibility notes.
|
||||
|
||||
## Required Features
|
||||
|
||||
- [ ] Confirm package registry targets for each available language.
|
||||
- [ ] Define release checklist per language.
|
||||
- [ ] Ensure package docs state protocol version support.
|
||||
- [ ] Keep changelog or release notes aligned with `VERSIONING.md`.
|
||||
- [ ] Verify same-language and cross-language tests before release.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A maintainer can release a language package without guessing the compatibility checklist.
|
||||
- Package releases communicate protocol version support separately from package version changes.
|
||||
- Release documentation does not imply a protocol bump unless wire format or required behavior changes.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Change protocol compatibility policy.
|
||||
- Add new language implementations.
|
||||
- Publish packages without the verification milestone being complete.
|
||||
|
||||
## Context for Work
|
||||
|
||||
Use `VERSIONING.md` as the release compatibility source of truth. README currently notes that checked-in implementations must preserve the documented protocol contract even before packages are published.
|
||||
|
|
@ -11,7 +11,7 @@
|
|||
- Protocol Buffers 기반 직렬화
|
||||
- TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍 / WebSocket 바이너리 프레임
|
||||
- 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트
|
||||
- 현재 구현 완료: Dart, Go, Kotlin / 계획: C#, Swift, Python, TypeScript
|
||||
- 현재 구현 완료: Dart, Go, Kotlin, Python, TypeScript / 계획: C#, Swift
|
||||
|
||||
## 주요 구조
|
||||
|
||||
|
|
@ -19,7 +19,10 @@
|
|||
dart/ — Dart/Flutter 구현체 (lib/, test/, crosstest/)
|
||||
go/ — Go 구현체 (*.go, test/, crosstest/)
|
||||
kotlin/ — Kotlin/Android 구현체 (src/, crosstest/)
|
||||
python/ — Python 구현체 (proto_socket/, test/, crosstest/)
|
||||
typescript/ — TypeScript 구현체 (src/, test/, crosstest/)
|
||||
tools/ — proto 생성/동기화 스크립트
|
||||
agent-ops/roadmap/ — Goal / Phase / Milestone 기반 로드맵과 현재 마일스톤 포인터
|
||||
PROTOCOL.md — 와이어 포맷 명세 (정식 스펙)
|
||||
PORTING_GUIDE.md — 새 언어 구현 가이드
|
||||
VERSIONING.md — 프로토콜/패키지 버전 정책
|
||||
|
|
@ -34,6 +37,8 @@ VERSIONING.md — 프로토콜/패키지 버전 정책
|
|||
| Dart | dart pub, protoc_plugin |
|
||||
| Go | Go modules, google.golang.org/protobuf |
|
||||
| Kotlin | Gradle, protobuf-kotlin |
|
||||
| Python | pytest, protobuf |
|
||||
| TypeScript | npm, tsx, TypeScript |
|
||||
| Proto 관리 | tools/generate_proto.sh, tools/check_proto_sync.sh |
|
||||
|
||||
## 프로젝트 특화 컨벤션
|
||||
|
|
@ -43,6 +48,12 @@ VERSIONING.md — 프로토콜/패키지 버전 정책
|
|||
- 새 언어 구현은 PORTING_GUIDE.md에 따라 동일 언어 테스트 + 크로스 언어 테스트 통과 후 Available 표시
|
||||
- 프로토콜 버전과 패키지 버전은 분리 관리 (VERSIONING.md 참조)
|
||||
|
||||
## 마일스톤 컨텍스트 로딩
|
||||
|
||||
- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다.
|
||||
- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
|
||||
- 작업 요청이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.
|
||||
|
||||
## 도메인 매핑
|
||||
|
||||
더 구체적인 경로가 우선한다. 여러 도메인에 걸친 변경이면 가장 구체적인 도메인 규칙을 먼저 읽고, 실제로 함께 수정하는 관련 도메인 규칙도 읽는다.
|
||||
|
|
|
|||
Loading…
Reference in a new issue