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                       # 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:

# 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:

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)

2.4 KiB Raw Blame History