diff --git a/README.md b/README.md index 484cab0..d691fdc 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,116 @@ # Proto Socket -Binary socket protocol library for bidirectional, heterogeneous communication across languages and platforms. +Proto Socket은 여러 언어와 플랫폼 사이에서 양방향 통신을 하기 위한 바이너리 소켓 프로토콜 라이브러리다. -Built on Protocol Buffers with TCP length-prefixed framing, WebSocket binary frames, type-based message routing, request-response correlation, and built-in heartbeat. +Protocol Buffers 직렬화, TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍, WebSocket 바이너리 프레임, 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트를 제공한다. --- -## Current Status +## 현재 상태 -Proto Socket currently treats the Dart, Go, Kotlin, Python, and TypeScript implementations as the available compatibility set for protocol `0.1`. +현재 프로토콜 `0.1`의 사용 가능 호환 구현은 Dart, Go, Kotlin, Python, TypeScript다. -The project is in a stabilization and maintenance pass before adding more language targets or publishing package registry releases. Git-based consumption from this repository is the primary supported workflow for now. C# and Swift remain planned targets, but implementation work is deferred until there is concrete demand. +이 프로젝트는 새 언어 대상을 늘리거나 패키지 registry에 배포하기 전 안정화와 유지보수 단계에 있다. 지금은 이 저장소를 Git 기반으로 소비하는 흐름을 기본 지원 방식으로 둔다. C#과 Swift는 계획된 대상이지만, 실제 수요가 생기기 전까지 구현을 미룬다. -Use the local validation matrix as the stability gate for protocol or implementation changes: +프로토콜이나 구현을 바꿀 때는 아래 로컬 검증 매트릭스를 안정성 gate로 사용한다. ```bash bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all ``` -Protocol or public API changes should be treated as compatibility work: update the relevant docs, regenerate protobuf bindings when needed, and keep the full validation matrix passing. +프로토콜 또는 공개 API 변경은 호환성 작업으로 다룬다. 관련 문서를 갱신하고, 필요한 경우 protobuf binding을 재생성하며, 전체 검증 매트릭스가 통과해야 한다. --- -## Design Principles +## 설계 원칙 -- Keep the core transport layer thin and stable -- Provide only the minimum common foundation for cross-language communication -- Standardize framing, serialization, routing, request-response correlation, and heartbeat -- Treat Protocol Buffers as the core protocol dependency. Other runtime dependencies should be native-first, narrowly scoped, and proportional to the feature they implement -- Do not embed application semantics into the protocol core -- Domain-specific concerns such as auth, session, agent workflow, chat features, and game logic belong in upper-layer implementations +- core transport layer는 얇고 안정적으로 유지한다. +- 언어 간 통신에 필요한 최소 공통 기반만 제공한다. +- framing, serialization, routing, request-response correlation, heartbeat를 표준화한다. +- Protocol Buffers를 핵심 프로토콜 의존성으로 둔다. 다른 런타임 의존성은 native-first, 좁은 범위, 기능에 비례한 수준으로 유지한다. +- 애플리케이션 의미를 프로토콜 core에 넣지 않는다. +- auth, session, agent workflow, chat, game logic 같은 도메인 관심사는 상위 레이어 구현의 책임이다. --- -## Protocol +## 프로토콜 -See [PROTOCOL.md](PROTOCOL.md) for the full wire format specification. +전체 wire format 명세는 [PROTOCOL.md](PROTOCOL.md)를 본다. -``` +```text [4-byte big-endian length] [PacketBase protobuf bytes] ``` -For WebSocket/WSS transports, each binary frame contains one `PacketBase` protobuf payload without the TCP length header. +WebSocket/WSS transport에서는 각 binary frame이 TCP length header 없이 `PacketBase` protobuf payload 하나를 담는다. -Protocol compatibility is tracked separately from language package versions. See [VERSIONING.md](VERSIONING.md). Even while packages are not published, the checked-in implementations must preserve the documented protocol contract. +프로토콜 호환성은 언어별 package version과 분리해서 추적한다. 자세한 정책은 [VERSIONING.md](VERSIONING.md)를 본다. 패키지를 아직 registry에 배포하지 않더라도, 저장소에 포함된 구현은 문서화된 프로토콜 계약을 지켜야 한다. --- -## Implementations +## 구현체 -| Language | Status | Path | Use case | -|----------|--------|------|----------| -| Dart | Available | [dart/](dart/) | Flutter, Dart server | -| Kotlin | Available | [kotlin/](kotlin/) | Android, JVM | -| Go | Available | [go/](go/) | Server, tooling, scripting | -| TypeScript | Available | [typescript/](typescript/) | Browser, Node.js | -| Python | Available | [python/](python/) | Server, tooling, scripting | -| C# | Planned / deferred | `csharp/` | Unity, .NET | -| Swift | Planned / deferred | `swift/` | iOS, macOS | +| 언어 | 상태 | 경로 | 사용처 | +|------|------|------|--------| +| Dart | 사용 가능 | [dart/](dart/) | Flutter, Dart server | +| Kotlin | 사용 가능 | [kotlin/](kotlin/) | Android, JVM | +| Go | 사용 가능 | [go/](go/) | Server, tooling, scripting | +| TypeScript | 사용 가능 | [typescript/](typescript/) | Browser, Node.js | +| Python | 사용 가능 | [python/](python/) | Server, tooling, scripting | +| C# | 계획 / 보류 | `csharp/` | Unity, .NET | +| Swift | 계획 / 보류 | `swift/` | iOS, macOS | -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. +새 언어 구현은 [PORTING_GUIDE.md](PORTING_GUIDE.md)와 [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/)의 템플릿에서 시작한다. 동일 언어 테스트와 크로스 언어 테스트가 통과한 뒤에만 구현 상태를 사용 가능으로 표시한다. -Keep implementation status here as the public snapshot. Current work context is selected through [agent-roadmap/current.md](agent-roadmap/current.md), and broader roadmap direction lives in [agent-roadmap/ROADMAP.md](agent-roadmap/ROADMAP.md). +현재 구현 상태는 이 README를 공개 snapshot으로 본다. 현재 작업 맥락은 [agent-roadmap/current.md](agent-roadmap/current.md)에서 선택하고, 큰 로드맵 방향은 [agent-roadmap/ROADMAP.md](agent-roadmap/ROADMAP.md)에 둔다. --- -## Common Commands +## 주요 명령 -| Purpose | Command | Notes | -|---------|---------|-------| -| Full local validation | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | Proto sync, same-language tests, and all available cross-language checks | -| Proto schema sync check | `tools/check_proto_sync.sh` | Verifies language proto copies match `proto/message_common.proto` except allowed language options | -| Regenerate protobuf bindings | `tools/generate_proto.sh` | Run after changing the canonical proto schema | -| Dart tests | `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | Dart VM/IO tests and web import compile check | -| Go tests | `cd go && go test ./...` | Go same-language checks | -| Kotlin tests | `cd kotlin && ./gradlew test` | Kotlin same-language checks | -| Python tests | `cd python && python3 -m pytest -q` | Python same-language checks | -| TypeScript checks | `cd typescript && npm run check && npm test` | TypeScript type check and tests | +| 목적 | 명령 | 비고 | +|------|------|------| +| 전체 로컬 검증 | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | proto sync, 동일 언어 테스트, 사용 가능 구현의 크로스 언어 검증을 실행한다. | +| Proto schema sync 확인 | `tools/check_proto_sync.sh` | 언어별 proto copy가 허용된 언어 옵션을 제외하고 `proto/message_common.proto`와 일치하는지 확인한다. | +| Protobuf binding 재생성 | `tools/generate_proto.sh` | canonical proto schema를 바꾼 뒤 실행한다. | +| Dart 테스트 | `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | Dart VM/IO 테스트와 web import compile 확인 | +| Go 테스트 | `cd go && go test ./...` | Go 동일 언어 검증 | +| Kotlin 테스트 | `cd kotlin && ./gradlew test` | Kotlin 동일 언어 검증 | +| Python 테스트 | `cd python && python3 -m pytest -q` | Python 동일 언어 검증 | +| TypeScript 확인 | `cd typescript && npm run check && npm test` | TypeScript type check와 테스트 | --- -## Repository Structure +## 저장소 구조 -| Path | Role | +| 경로 | 역할 | |------|------| -| [proto/](proto/) | Canonical protobuf schema source | -| [dart/](dart/) | Dart / Flutter implementation and tests | -| [go/](go/) | Go implementation, tests, and Go-led crosstests | -| [kotlin/](kotlin/) | Kotlin / JVM implementation and crosstests | -| [python/](python/) | Python implementation and crosstests | -| [typescript/](typescript/) | TypeScript implementation and crosstests | -| [tools/](tools/) | Proto generation and sync helpers | -| [examples/](examples/) | Consumer-oriented examples | -| [agent-ops/](agent-ops/) | Project rules, roadmap, and repeatable agent workflows | +| [proto/](proto/) | canonical protobuf schema 원본 | +| [dart/](dart/) | Dart / Flutter 구현체와 테스트 | +| [go/](go/) | Go 구현체, 테스트, Go 주도 crosstest | +| [kotlin/](kotlin/) | Kotlin / JVM 구현체와 crosstest | +| [python/](python/) | Python 구현체와 crosstest | +| [typescript/](typescript/) | TypeScript 구현체와 crosstest | +| [tools/](tools/) | proto 생성과 sync helper | +| [examples/](examples/) | 소비자 지향 예제 | +| [agent-ops/](agent-ops/) | 프로젝트 규칙, 로드맵, 반복 agent workflow | --- -## Quick Start (Dart) +## 빠른 시작: Dart ```dart import 'package:proto_socket/proto_socket.dart'; -// 1. Define your message in message_common.proto, generate with protoc +// 1. message_common.proto에 메시지를 정의하고 protoc로 생성한다. -// 2. Implement a client +// 2. client를 구현한다. class MyClient extends ProtobufClient { MyClient(Socket socket) : super(socket, 30, 10, { MyMessage.getDefault().info_.qualifiedMessageName: MyMessage.fromBuffer, }); } -// 3. Implement a server +// 3. server를 구현한다. class MyServer extends ProtobufServer { MyServer() : super('0.0.0.0', 9090, (socket) => MyClient(socket)); @@ -120,11 +120,11 @@ class MyServer extends ProtobufServer { } } -// 4. Start +// 4. server를 시작한다. final server = MyServer(); await server.start(); -// 5. Connect and send +// 5. 연결하고 메시지를 보낸다. final socket = await Socket.connect('localhost', 9090); final client = MyClient(socket); await client.send(MyMessage()..text = 'hello'); @@ -132,20 +132,20 @@ await client.send(MyMessage()..text = 'hello'); --- -## Adding Message Types +## 메시지 타입 추가 -Edit the canonical proto at `proto/message_common.proto`, then regenerate all checked-in bindings: +canonical proto인 `proto/message_common.proto`를 수정한 뒤, 저장소에 포함된 모든 binding을 재생성한다. ```bash tools/generate_proto.sh tools/check_proto_sync.sh ``` -The Go and Kotlin proto copies are allowed to keep only language-specific options such as `option go_package` or Java package/class options. `tools/check_proto_sync.sh` fails with a diff when their message schema drifts from `proto/message_common.proto`. +Go와 Kotlin proto copy에는 `option go_package`, Java package/class option 같은 언어별 옵션만 추가로 허용한다. 메시지 schema가 `proto/message_common.proto`와 달라지면 `tools/check_proto_sync.sh`가 diff와 함께 실패한다. --- -## Quick Start (Go) +## 빠른 시작: Go ```go package main @@ -207,27 +207,27 @@ func main() { } ``` -Go also provides: +Go 구현체는 다음 표면도 제공한다. - TCP: `NewTcpServer`, `DialTcp`, `NewTcpServerTLS`, `DialTcpTLS` - WebSocket: `NewWsServer`, `DialWs`, `NewWsServerTLS`, `DialWss` - Shared helpers: `Send`, `SendRequest`, `AddListenerTyped`, `AddRequestListenerTyped`, `Broadcast` -If you want a copyable scaffold for using this module from another repository, see [examples/go-module-consumer/](examples/go-module-consumer/). +다른 저장소에서 이 모듈을 사용하는 복사 가능한 scaffold가 필요하면 [examples/go-module-consumer/](examples/go-module-consumer/)를 본다. --- -## Running Tests +## 테스트 실행 -Local commands are documented here for development and troubleshooting. The repeatable repository-local validation entry point is: +개발과 문제 재현을 위한 로컬 명령은 이 문서에 정리한다. 반복 가능한 저장소 로컬 검증 진입점은 다음 명령이다. ```bash bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all ``` -It runs proto schema sync, same-language tests, and cross-language checks, then prints PASS/FAIL tables with reproduction commands for failures. Use `--proto`, `--unit`, or `--cross` to run a smaller slice. +이 명령은 proto schema sync, 동일 언어 테스트, 크로스 언어 검증을 실행하고, 실패가 있으면 재현 명령과 함께 PASS/FAIL 표를 출력한다. 더 작은 범위만 확인하려면 `--proto`, `--unit`, `--cross`를 사용한다. -External CI runner integration is deferred until the parent `../oto` project standardizes its execution path. Until then, the local matrix above is the project stability gate. +외부 CI runner 연동은 상위 `../oto` 프로젝트가 실행 경로를 표준화할 때까지 보류한다. 그 전까지는 위 로컬 매트릭스를 프로젝트 안정성 gate로 본다. Proto schema sync: @@ -235,7 +235,7 @@ Proto schema sync: tools/check_proto_sync.sh ``` -Same-language checks: +동일 언어 검증: ```bash cd dart @@ -265,7 +265,7 @@ npm run check npm test ``` -Cross-language checks: +크로스 언어 검증: ```bash cd go @@ -307,9 +307,9 @@ cd typescript ./node_modules/.bin/tsx crosstest/typescript_python.ts ``` -### Dart.io vs Dart.web E2E matrix +### Dart.io와 Dart.web E2E 매트릭스 -The `Dart` column above refers to the Dart VM/IO client. `Dart.web` is a separate axis: a browser WS client only — TCP and any server role are not possible in the browser, so those cells are `N/A`. WSS is `Deferred` because there is no automation for trusting the self-signed test certificate in a browser. +위 표의 `Dart` 열은 Dart VM/IO client를 뜻한다. `Dart.web`은 별도 축이다. 브라우저 WS client만 가능하며, 브라우저에서는 TCP와 server 역할이 불가능하므로 해당 cell은 `N/A`다. WSS는 브라우저에서 self-signed test certificate 신뢰를 자동화하지 않았기 때문에 `Deferred`다. | Server | Dart.io TCP | Dart.io WS | Dart.io TLS TCP | Dart.io WSS | Dart.web WS | Dart.web WSS | Dart.web TCP | |---|---|---|---|---|---|---|---| @@ -319,7 +319,7 @@ The `Dart` column above refers to the Dart VM/IO client. `Dart.web` is a separat | Python | Covered | Covered | Covered | Covered | Covered | Deferred | N/A | | TypeScript | Covered | Covered | Covered | Covered | Covered | Deferred | N/A | -Each Dart.web cell is exercised by a server-language runner that boots its WS server, launches `dart test -p chrome` against the matching browser test file, and asserts the send-push and request-response scenarios: +각 Dart.web cell은 server-language runner가 해당 WS server를 띄우고, matching browser test file에 대해 `dart test -p chrome`을 실행하며, send-push와 request-response 시나리오를 검증한다. ```bash cd dart && dart run crosstest/dart_web.dart @@ -331,13 +331,13 @@ cd typescript && ./node_modules/.bin/tsx crosstest/typescript_dart_web.ts --- -## Work Context +## 작업 맥락 -Before making code or protocol changes, check the project rules in [agent-ops/rules/project/rules.md](agent-ops/rules/project/rules.md) and any matching domain rule listed there. The active roadmap window is in [agent-roadmap/current.md](agent-roadmap/current.md). +코드나 프로토콜을 변경하기 전에 [agent-ops/rules/project/rules.md](agent-ops/rules/project/rules.md)의 프로젝트 규칙과 해당 경로의 domain rule을 확인한다. 활성 로드맵 창은 [agent-roadmap/current.md](agent-roadmap/current.md)에 있다. -Stabilization boundaries: +안정화 경계는 다음과 같다. -- Keep protocol `0.1` behavior stable unless compatibility work is explicitly requested. -- Maintenance-mode work may include bug fixes, documentation corrections, test hardening, and compatibility-preserving implementation fixes. -- Resume C#/Swift, package registry release, or protocol/API change work only when there is concrete consumer demand, a compatibility plan, and a passing full validation matrix. -- Do not connect external CI/CD runners from this repository until the parent `../oto` workflow is decided. +- 명시적인 호환성 작업 요청이 없으면 프로토콜 `0.1` 동작을 안정적으로 유지한다. +- 유지보수 모드 작업에는 bug fix, 문서 정정, 테스트 강화, 호환성을 유지하는 구현 수정이 포함될 수 있다. +- C#/Swift, package registry release, protocol/API 변경 작업은 구체적인 소비자 수요, 호환성 계획, 전체 검증 매트릭스 통과 조건이 있을 때 재개한다. +- 상위 `../oto` workflow가 결정되기 전까지 이 저장소에서 외부 CI/CD runner를 직접 연결하지 않는다.