GEN-13: Initial implementation of realtime activity stream service #1

Closed

backmeupplz wants to merge 1 commit from feat/GEN-13-initial-implementation into main

backmeupplz commented

2026-05-13 18:58:49 +00:00

(Migrated from github.com)

Summary

Implements GEN-13 — a lightweight authenticated live activity stream service for borodutch projects.

What was built

POST /events — Authenticated endpoint for submitting activity events
- Bearer token auth (35-character secret via STREAM_TOKEN env var)
- Max payload length limit (default 500 chars)
- Rate limiting per source (default 10 events/second)
- Returns structured event envelope with UUID and ISO timestamp
WebSocket /stream — Live event streaming
- Replays recent events from ring buffer on connect
- Real-time broadcast of new events to all connected clients
- Connection limits per IP and global max connections
- Periodic ping to detect dead connections
GET /health — Health check with connection and event counts
Bounded in-memory ring buffer — No database required, configurable max size (default 1000 events)
CORS support — Configurable origin
Graceful shutdown — SIGTERM/SIGINT handling

Tech stack

Node.js + TypeScript (native http + ws library)
Jest for testing
Nixpacks for EasyPanel/Hetzner deployment
Single repo: borodutch-stream

Test results

✓ health endpoint returns ok
✓ POST /events without auth returns 401
✓ POST /events with invalid token returns 401
✓ POST /events with valid auth creates event
✓ POST /events with missing text returns 400
✓ POST /events with large payload returns 400
✓ POST /events with invalid JSON returns 400
✓ WebSocket receives replay on connect
✓ WebSocket receives new events in realtime

9 passed in ~1s

Environment variables

See .env.sample for all required env vars. Key ones:

Variable	Required	Description
`STREAM_TOKEN`	Yes	35-character secret token
`PORT`	No	Server port (default: 1340)
`MAX_EVENTS`	No	Ring buffer size (default: 1000)

Generate token

node -e "console.log(require('crypto').randomBytes(26).toString('base64url').slice(0,35))"

Deployment

Deployed via Nixpacks on EasyPanel/Hetzner. See nixpacks.toml.

Security

No secrets committed (all via env vars)
No raw Telegram content collected — emitters send pre-anonymized text
Token is exactly 35 characters to prevent brute force

## Summary Implements [GEN-13](https://kaneo.icefish-betta.ts.net) — a lightweight authenticated live activity stream service for borodutch projects. ## What was built - **POST /events** — Authenticated endpoint for submitting activity events - Bearer token auth (35-character secret via `STREAM_TOKEN` env var) - Max payload length limit (default 500 chars) - Rate limiting per source (default 10 events/second) - Returns structured event envelope with UUID and ISO timestamp - **WebSocket /stream** — Live event streaming - Replays recent events from ring buffer on connect - Real-time broadcast of new events to all connected clients - Connection limits per IP and global max connections - Periodic ping to detect dead connections - **GET /health** — Health check with connection and event counts - **Bounded in-memory ring buffer** — No database required, configurable max size (default 1000 events) - **CORS support** — Configurable origin - **Graceful shutdown** — SIGTERM/SIGINT handling ## Tech stack - Node.js + TypeScript (native `http` + `ws` library) - Jest for testing - Nixpacks for EasyPanel/Hetzner deployment - Single repo: `borodutch-stream` ## Test results ``` ✓ health endpoint returns ok ✓ POST /events without auth returns 401 ✓ POST /events with invalid token returns 401 ✓ POST /events with valid auth creates event ✓ POST /events with missing text returns 400 ✓ POST /events with large payload returns 400 ✓ POST /events with invalid JSON returns 400 ✓ WebSocket receives replay on connect ✓ WebSocket receives new events in realtime 9 passed in ~1s ``` ## Environment variables See `.env.sample` for all required env vars. Key ones: | Variable | Required | Description | |----------|----------|-------------| | `STREAM_TOKEN` | Yes | 35-character secret token | | `PORT` | No | Server port (default: 1340) | | `MAX_EVENTS` | No | Ring buffer size (default: 1000) | ## Generate token ```bash node -e "console.log(require('crypto').randomBytes(26).toString('base64url').slice(0,35))" ``` ## Deployment Deployed via Nixpacks on EasyPanel/Hetzner. See `nixpacks.toml`. ## Security - No secrets committed (all via env vars) - No raw Telegram content collected — emitters send pre-anonymized text - Token is exactly 35 characters to prevent brute force