59 lines
1.8 KiB
Markdown
59 lines
1.8 KiB
Markdown
# 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
|
|
go build -o collab-go main.go
|
|
```
|
|
|
|
Port: `1234` (override with `ADDR` env var).
|
|
|
|
### Protobuf
|
|
|
|
Consumes Go stubs (`yoreseedocpb`) from `git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go`, pinned to tag `v0.1.0` in `go.mod`. No local codegen required.
|
|
|
|
## 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}`
|
|
|
|
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/...`).
|
|
|
|
## 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)
|