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

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:

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)

1.8 KiB Raw Blame History