905c241daa
- Fix metrics: change MessagesTotal, ConnectionsTotal, DisconnectionsTotal from Gauge to Counter with proper _total naming convention - Fix broadcast write-error handling: failed clients now get properly removed with accurate metrics updates - Add graceful shutdown: SIGINT/SIGTERM handling with 10s timeout, CloseGoingAway frame sent to clients before disconnect - Add integration tests: 11 tests using real WebSocket connections covering connect, broadcast, disconnect, concurrency, and shutdown - Fix example client port: changed from 8000 to 8443 to match config - Rewrite README.md to reflect current features and usage - Add AGENTS.md and .agents/summary/ documentation for AI assistants
113 lines
6.1 KiB
Markdown
113 lines
6.1 KiB
Markdown
# Documentation Index — WebSocket Relay
|
|
|
|
> **Purpose:** This file serves as the primary knowledge base entry point for AI assistants working with this codebase. Read this file first to understand where to find detailed information.
|
|
|
|
## How to Use This Documentation
|
|
|
|
1. **Start here** — this index contains summaries of every documentation file
|
|
2. **Check the summary tables** below to determine which file has the information you need
|
|
3. **Only load additional files** when you need deeper detail on a specific topic
|
|
4. **Cross-references** are provided to help navigate between related topics
|
|
|
|
---
|
|
|
|
## Project Quick Reference
|
|
|
|
| Fact | Value |
|
|
|------|-------|
|
|
| **Project** | WebSocket Relay Server |
|
|
| **Language** | Go 1.21 |
|
|
| **Purpose** | Broadcast WebSocket messages to all connected clients (P2P relay) |
|
|
| **Entry Point** | `main.go` |
|
|
| **Config** | `config.yaml` (YAML) |
|
|
| **WebSocket Port** | 8443 (configurable) |
|
|
| **Metrics Port** | 9090 (configurable, optional) |
|
|
| **Build** | `make build` / `make release` |
|
|
| **Test** | `make test` / `go test ./...` |
|
|
| **Architecture** | Hub-and-Spoke broadcast pattern using Go channels |
|
|
|
|
---
|
|
|
|
## Documentation Files
|
|
|
|
### 📋 codebase_info.md
|
|
**What it contains:** Project metadata, directory tree, technology stack, build targets, and codebase statistics.
|
|
**When to consult:** When you need to understand the project layout, find a file, or check what tools/languages are used.
|
|
**Key topics:** Directory structure, Go module info, Makefile targets, dependency counts.
|
|
|
|
---
|
|
|
|
### 🏗️ architecture.md
|
|
**What it contains:** System design, Hub-and-Spoke pattern explanation, concurrency model, goroutine lifecycle, security model, and deployment architecture.
|
|
**When to consult:** When you need to understand HOW the system works at a high level, the threading model, or how components interact.
|
|
**Key topics:** CSP concurrency, fan-out broadcasting, TLS configuration, CI/CD pipeline structure.
|
|
**Cross-references:** → `components.md` for implementation details, → `workflows.md` for sequence flows.
|
|
|
|
---
|
|
|
|
### 🧩 components.md
|
|
**What it contains:** Detailed description of each Go package — structs, methods, fields, and their responsibilities.
|
|
**When to consult:** When you need to modify a specific package, understand a struct's fields, or find where functionality lives.
|
|
**Key topics:** Hub struct and methods, Config struct, metrics variables, test coverage map.
|
|
**Cross-references:** → `architecture.md` for design rationale, → `interfaces.md` for external contracts.
|
|
|
|
---
|
|
|
|
### 🔌 interfaces.md
|
|
**What it contains:** All external interfaces — WebSocket endpoint behavior, metrics endpoint, CLI flags, configuration schema, and integration points.
|
|
**When to consult:** When you need to understand how clients interact with the server, what the API contract is, or how to configure the service.
|
|
**Key topics:** WebSocket message protocol, Prometheus metric names, CLI usage, YAML config schema.
|
|
**Cross-references:** → `data_models.md` for config struct details, → `components.md` for handler implementation.
|
|
|
|
---
|
|
|
|
### 📊 data_models.md
|
|
**What it contains:** All data structures — Config struct, Hub state, message format, metrics model, and connection state machine.
|
|
**When to consult:** When you need to understand data shapes, struct definitions, channel types, or state transitions.
|
|
**Key topics:** Config YAML mapping, Hub channels and their payloads, connection lifecycle states.
|
|
**Cross-references:** → `interfaces.md` for how models are exposed externally, → `components.md` for methods operating on these models.
|
|
|
|
---
|
|
|
|
### 🔄 workflows.md
|
|
**What it contains:** Step-by-step process flows — startup, connection, broadcast, build/release, development, and error handling.
|
|
**When to consult:** When you need to understand the sequence of operations, debug a flow, or add a new feature that hooks into an existing workflow.
|
|
**Key topics:** Application startup sequence, client lifecycle, CI/CD pipeline steps, error handling paths.
|
|
**Cross-references:** → `architecture.md` for the concurrency model underlying workflows, → `components.md` for method details.
|
|
|
|
---
|
|
|
|
### 📦 dependencies.md
|
|
**What it contains:** Complete dependency inventory — direct and transitive deps, their versions, usage locations, security considerations, and build tools.
|
|
**When to consult:** When updating dependencies, evaluating security, understanding what libraries provide, or considering alternatives.
|
|
**Key topics:** gorilla/websocket APIs used, Prometheus client usage, gopkg.in/yaml.v3 usage, transitive dependency tree.
|
|
**Cross-references:** → `components.md` for where dependencies are imported.
|
|
|
|
---
|
|
|
|
### 📝 review_notes.md
|
|
**What it contains:** Documentation quality assessment — consistency issues, completeness gaps, bugs found during analysis, and prioritized recommendations.
|
|
**When to consult:** When looking for known issues, potential bugs, or areas needing improvement.
|
|
**Key topics:** Metrics type bug, port mismatch in example, missing features (graceful shutdown, rate limiting), test coverage gaps.
|
|
**Cross-references:** All other files (identifies issues across the entire codebase).
|
|
|
|
---
|
|
|
|
## Quick Lookup: Common Questions
|
|
|
|
| Question | File to Consult |
|
|
|----------|----------------|
|
|
| "What does this project do?" | This file (index.md) |
|
|
| "Where is X implemented?" | `codebase_info.md` → directory tree |
|
|
| "How does the Hub work?" | `components.md` → Hub section |
|
|
| "What's the WebSocket message format?" | `interfaces.md` → WebSocket Endpoint |
|
|
| "How do I build/test?" | `codebase_info.md` → Build Targets |
|
|
| "What metrics are exposed?" | `interfaces.md` → Metrics Endpoint |
|
|
| "What are the config options?" | `interfaces.md` → Configuration Interface |
|
|
| "Are there known bugs?" | `review_notes.md` → Inconsistencies |
|
|
| "What should I improve?" | `review_notes.md` → Recommendations |
|
|
| "What dependencies does it use?" | `dependencies.md` |
|
|
| "How does startup work?" | `workflows.md` → Application Startup |
|
|
| "How are connections handled?" | `workflows.md` → Client Connection Workflow |
|
|
| "What's the threading model?" | `architecture.md` → Concurrency Model |
|