{"id":36443924,"url":"https://github.com/coregx/stream","last_synced_at":"2026-01-11T22:02:18.989Z","repository":{"id":325093358,"uuid":"1099836068","full_name":"coregx/stream","owner":"coregx","description":"Production-ready Server-Sent Events (SSE) and WebSocket for Go 1.25+ | RFC-compliant | Zero dependencies | 84% test coverage","archived":false,"fork":false,"pushed_at":"2025-11-19T14:09:21.000Z","size":132,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-19T15:29:48.263Z","etag":null,"topics":["broadcasting","go","golang","http","hub","networking","production-ready","real-time","rfc6455","server-sent-events","sse","streaming","websocket","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/coregx/stream","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coregx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-19T14:00:40.000Z","updated_at":"2025-11-19T14:17:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coregx/stream","commit_stats":null,"previous_names":["coregx/stream"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/coregx/stream","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coregx%2Fstream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coregx%2Fstream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coregx%2Fstream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coregx%2Fstream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coregx","download_url":"https://codeload.github.com/coregx/stream/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coregx%2Fstream/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28324838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T18:42:50.174Z","status":"ssl_error","status_checked_at":"2026-01-11T18:39:13.842Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["broadcasting","go","golang","http","hub","networking","production-ready","real-time","rfc6455","server-sent-events","sse","streaming","websocket","zero-dependencies"],"created_at":"2026-01-11T22:02:18.906Z","updated_at":"2026-01-11T22:02:18.968Z","avatar_url":"https://github.com/coregx.png","language":"Go","readme":"# 🌊 stream - Real-time Communications for Go 1.25+\n\n\u003e Server-Sent Events and WebSocket implementations - Zero external dependencies, RFC-compliant, production-ready\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/coregx/stream.svg)](https://pkg.go.dev/github.com/coregx/stream)\n[![Go Report Card](https://goreportcard.com/badge/github.com/coregx/stream)](https://goreportcard.com/report/github.com/coregx/stream)\n[![Tests](https://github.com/coregx/stream/actions/workflows/test.yml/badge.svg)](https://github.com/coregx/stream/actions)\n[![codecov](https://codecov.io/gh/coregx/stream/branch/main/graph/badge.svg)](https://codecov.io/gh/coregx/stream)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Release](https://img.shields.io/github/v/release/coregx/stream)](https://github.com/coregx/stream/releases)\n\n---\n\n## ⚡ Quick Start\n\n### SSE (Server-Sent Events)\n\n```go\npackage main\n\nimport (\n    \"net/http\"\n    \"time\"\n    \"github.com/coregx/stream/sse\"\n)\n\nfunc main() {\n    http.HandleFunc(\"/events\", func(w http.ResponseWriter, r *http.Request) {\n        conn, _ := sse.Upgrade(w, r)\n        defer conn.Close()\n\n        ticker := time.NewTicker(1 * time.Second)\n        defer ticker.Stop()\n\n        for {\n            select {\n            case t := \u003c-ticker.C:\n                event := sse.NewEvent(t.Format(time.RFC3339)).WithType(\"time\")\n                conn.Send(event)\n            case \u003c-conn.Done():\n                return\n            }\n        }\n    })\n\n    http.ListenAndServe(\":8080\", nil)\n}\n```\n\n### WebSocket\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"net/http\"\n    \"github.com/coregx/stream/websocket\"\n)\n\nfunc main() {\n    http.HandleFunc(\"/ws\", func(w http.ResponseWriter, r *http.Request) {\n        conn, _ := websocket.Upgrade(w, r, nil)\n        defer conn.Close()\n\n        for {\n            msgType, data, err := conn.Read()\n            if err != nil {\n                break\n            }\n            conn.Write(msgType, data)\n        }\n    })\n\n    log.Fatal(http.ListenAndServe(\":8080\", nil))\n}\n```\n\n**Broadcasting with Hub:**\n\n```go\nhub := websocket.NewHub()\ngo hub.Run()\ndefer hub.Close()\n\nhttp.HandleFunc(\"/ws\", func(w http.ResponseWriter, r *http.Request) {\n    conn, _ := websocket.Upgrade(w, r, nil)\n    hub.Register(conn)\n    defer hub.Unregister(conn)\n\n    for {\n        _, data, _ := conn.Read()\n        hub.Broadcast(data)\n    }\n})\n```\n\n---\n\n## 🌟 Why stream?\n\n### Zero Dependencies, Maximum Control\n\n```go\n// Pure stdlib - no external dependencies in production\nimport \"github.com/coregx/stream/sse\"\nimport \"github.com/coregx/stream/websocket\"\n```\n\n**stream** is built with **zero external dependencies** for production code. No vendor lock-in, no dependency hell, just pure Go stdlib implementations of SSE and WebSocket protocols.\n\n### RFC-Compliant Protocols\n\n- **SSE**: RFC [text/event-stream](https://html.spec.whatwg.org/multipage/server-sent-events.html) compliant\n- **WebSocket**: [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455) compliant\n\nFully standards-compliant implementations ensure compatibility with all browsers and clients.\n\n### Broadcasting Made Simple\n\n```go\n// Hub pattern for efficient broadcasting\nhub := websocket.NewHub()\nhub.BroadcastText(\"Hello, everyone!\")\nhub.BroadcastJSON(Message{Type: \"update\", Data: \"...\"})\n```\n\nBuilt-in Hub pattern for efficient message broadcasting to multiple clients with minimal allocations.\n\n---\n\n## 📦 Installation\n\n```bash\ngo get github.com/coregx/stream\n```\n\n**Requirements**: Go 1.25+ (uses `encoding/json/v2` and modern generics)\n\n---\n\n## 🚀 Features\n\n### SSE (Server-Sent Events)\n\n- ✅ **RFC Compliant** - text/event-stream standard\n- ✅ **Event Types** - Named events (`message`, `update`, custom)\n- ✅ **Event IDs** - Client reconnection with Last-Event-ID\n- ✅ **Retry Control** - Configurable reconnection delays\n- ✅ **Automatic Flushing** - Real-time event delivery\n- ✅ **Graceful Shutdown** - Clean connection closure\n- ✅ **92.3% Test Coverage** - 215 tests, comprehensive validation\n\n### WebSocket\n\n- ✅ **RFC 6455 Compliant** - Full WebSocket protocol\n- ✅ **Text \u0026 Binary** - Both message types supported\n- ✅ **Control Frames** - Ping/Pong, Close handshake\n- ✅ **Broadcasting Hub** - Efficient multi-client messaging\n- ✅ **Connection Management** - Auto cleanup, timeouts\n- ✅ **Frame Masking** - Client-to-server masking (RFC requirement)\n- ✅ **84.3% Test Coverage** - 99 tests, production-ready\n\n### Common Features\n\n- 🚀 **Zero Dependencies** - Pure stdlib implementation\n- 🎯 **Type-Safe** - Modern Go 1.25+ with generics\n- ⚡ **High Performance** - \u003c100 μs broadcasts, minimal allocations\n- 🧪 **Well-Tested** - 314 tests total, 84.3% coverage\n- 🏢 **Production Ready** - Used in coregx ecosystem\n- 📚 **Comprehensive Docs** - Guides, examples, API reference\n\n---\n\n## 📚 Documentation\n\n- **[SSE Guide](docs/SSE_GUIDE.md)** - Complete SSE documentation with examples\n- **[WebSocket Guide](docs/WEBSOCKET_GUIDE.md)** - Complete WebSocket documentation with examples\n- **[API Reference](https://pkg.go.dev/github.com/coregx/stream)** - Full API documentation on pkg.go.dev\n- **[Examples](examples/)** - Working code examples\n  - **SSE**: [sse-basic](examples/sse-basic/), [sse-chat](examples/sse-chat/)\n  - **WebSocket**: [echo-server](examples/websocket/echo-server/), [chat-server](examples/websocket/chat-server/), [ping-pong](examples/websocket/ping-pong/)\n- **[ROADMAP](ROADMAP.md)** - Future plans and versioning strategy\n\n---\n\n## 🎯 Use Cases\n\n### Real-time Dashboards (SSE)\n\n```go\n// Push live metrics to dashboard\nconn.Send(sse.NewEvent(metricsJSON).WithType(\"metrics\"))\n```\n\nPerfect for server-to-client updates: live metrics, notifications, stock prices, or any real-time data stream.\n\n### Chat Applications (WebSocket)\n\n```go\n// Bidirectional messaging\nhub.BroadcastText(fmt.Sprintf(\"%s: %s\", username, message))\n```\n\nFull-duplex communication for chat, collaborative editing, multiplayer games.\n\n### Live Notifications (SSE)\n\n```go\n// Server pushes notifications\nevent := sse.NewEvent(notification).WithType(\"alert\").WithRetry(3000)\nconn.Send(event)\n```\n\nLightweight server push for notifications without WebSocket overhead.\n\n### IoT \u0026 Sensors (WebSocket)\n\n```go\n// Binary data streaming\nconn.Write(websocket.BinaryMessage, sensorData)\n```\n\nEfficient binary data transfer for IoT devices, sensors, telemetry.\n\n---\n\n## 📊 Benchmarks\n\n### SSE Performance\n\n```\nBenchmarkSSE_Send-8              50000    23.4 μs/op     0 allocs/op\nBenchmarkSSE_Broadcast-8         30000    47.2 μs/op     1 allocs/op\nBenchmarkSSE_E2E_Latency-8       20000    68.5 μs/op     2 allocs/op\n```\n\n### WebSocket Performance\n\n```\nBenchmarkWS_Echo-8               100000   15.3 μs/op     0 allocs/op\nBenchmarkWS_Broadcast-8          50000    32.1 μs/op     1 allocs/op\nBenchmarkWS_Hub_1000clients-8    10000    156 μs/op      3 allocs/op\n```\n\n**High throughput**: \u003e20,000 messages/sec per connection, minimal allocations, sub-100μs latency.\n\n---\n\n## 🔧 Advanced Usage\n\n### SSE with Custom Headers\n\n```go\nconn, err := sse.Upgrade(w, r)\nif err != nil {\n    http.Error(w, err.Error(), http.StatusBadRequest)\n    return\n}\n\n// Set custom retry interval\nevent := sse.NewEvent(\"data\").WithRetry(5000) // 5 seconds\n\n// Named event types\nevent = sse.NewEvent(\"update\").WithType(\"user-joined\")\n\n// Event IDs for reconnection\nevent = sse.NewEvent(\"data\").WithID(\"msg-123\")\n```\n\n### WebSocket with Configuration\n\n```go\nopts := \u0026websocket.UpgradeOptions{\n    ReadBufferSize:  4096,\n    WriteBufferSize: 4096,\n    CheckOrigin: func(r *http.Request) bool {\n        return r.Header.Get(\"Origin\") == \"https://example.com\"\n    },\n}\n\nconn, err := websocket.Upgrade(w, r, opts)\n```\n\n### Graceful Shutdown\n\n```go\n// SSE\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\ndefer cancel()\n\nselect {\ncase \u003c-ctx.Done():\n    conn.Close()\ncase \u003c-conn.Done():\n    // Client disconnected\n}\n\n// WebSocket Hub\nhub.Close() // Gracefully closes all connections\n```\n\n---\n\n## 🤝 Sister Projects\n\nPart of the **coregx** ecosystem - production-ready Go libraries:\n\n- **[fursy](https://github.com/coregx/fursy)** - HTTP Router with generics, OpenAPI, RFC 9457\n- **[relica](https://github.com/coregx/relica)** - Database Query Builder (coming soon)\n- **[stream](https://github.com/coregx/stream)** - Real-time Communications (this library)\n\n---\n\n## 📊 Status\n\n| Metric | Value |\n|--------|-------|\n| **Version** | v0.1.0 (Production Ready) |\n| **Test Coverage** | 84.3% (SSE: 92.3%, WebSocket: 84.3%) |\n| **Tests** | 314 total (215 SSE, 99 WebSocket) |\n| **Test Lines** | 9,245 lines |\n| **Benchmarks** | 23 (E2E latency, throughput, load tests) |\n| **Dependencies** | 0 (production) |\n| **Go Version** | 1.25+ |\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- **SSE Spec**: [WHATWG HTML Living Standard](https://html.spec.whatwg.org/multipage/server-sent-events.html)\n- **WebSocket Spec**: [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455)\n- **Inspiration**: Production needs of the coregx ecosystem\n\n### Special Thanks\n\n**Professor Ancha Baranova** - This project would not have been possible without her invaluable help and support. Her assistance was crucial in making all coregx projects a reality.\n\n---\n\nBuilt with ❤️ for the Go community by [coregx](https://github.com/coregx)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoregx%2Fstream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoregx%2Fstream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoregx%2Fstream/lists"}