update documents

2026-08-11 14:16:15 +08:00
parent 6709f7c73f
commit a80365adc7
3 changed files with 557 additions and 0 deletions
@@ -0,0 +1,73 @@
+# AGENTS.md — collab-go
+
+Go 1.24 WebSocket gateway that authenticates JWT tokens and proxies collaborative editing traffic to `collab-core`.
+
+Part of a multi-repo project. Parent `../AGENTS.md` has full architecture context.
+
+## Build & Run
+
+```bash
+go run main.go                       # requires generated proto stubs first
+go build -o collab-go main.go
+```
+
+Port: `1234` (override with `ADDR` env var).
+
+### Prerequisites — generated proto stubs
+
+`pkg/gen/` is gitignored. Code **will not compile** without it. Generate from the parent directory:
+
+```bash
+# Option A: parent repo script (recommended)
+bash ../deploy/script/gen_proto.sh
+
+# Option B: manual protoc (requires protoc-gen-go + protoc-gen-go-grpc)
+mkdir -p pkg/gen
+protoc -I ../proto \
+  --go_out=pkg/gen --go_opt=paths=source_relative \
+  --go-grpc_out=pkg/gen --go-grpc_opt=paths=source_relative \
+  ../proto/yoresee_doc/v1/yoresee_doc.proto
+```
+
+Install codegen tools: `go install google.golang.org/protobuf/cmd/protoc-gen-go@latest && go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest`
+
+## Environment Variables
+
+| Var | Default | Required |
+|-----|---------|----------|
+| `ADDR` | `:1234` | no |
+| `JWT_SECRET` | _(empty)_ | yes — empty = accept any parseable JWT |
+| `COLLAB_CORE_URL` | `ws://collab-core:1234` | no |
+| `BACKEND_GRPC_ADDR` | `backend:9090` | no |
+| `INTERNAL_RPC_KEY` | _(empty)_ | no — sent as `x-internal-key` gRPC metadata |
+
+## Verification
+
+No tests exist. Verify with:
+
+```bash
+go vet ./...
+go build ./...
+```
+
+## Architecture
+
+- `auth/` — JWT validation (HS256/384/512)
+- `config/` — env-based config via `caarlos0/env/v11`
+- `handler/` — WebSocket upgrade, auth check, doc-existence check via gRPC, proxy to collab-core
+- `health/` — `/health`, `/readyz`, `/livez` probes (readiness checks backend gRPC)
+- `proxy/` — bidirectional WebSocket proxy to collab-core at path `/doc-{docID}`
+- `pkg/gen/` — generated protobuf stubs (gitignored)
+
+Connection flow: `Browser → /ws/doc/{docId}?token=... → collab-go (auth + gRPC doc check) → collab-core /doc-{docId}`
+
+## Docker
+
+- `Dockerfile` — dev image, runs `go run main.go`
+- `Dockerfile.prod` — production build; **expects build context at parent directory** (`COPY collab-go/...`). Proto codegen runs inside the build.
+
+## Conventions
+
+- Logs use prefix `collab-gateway`
+- `CheckOrigin` allows all origins (WebSocket upgrader)
+- When `JWT_SECRET` is empty, JWTs are parsed but not signature-verified (dev mode)