docs: add Reddit post for chanx WebSocket package

Author: claude

reddit_post.md

@@ -0,0 +1,183 @@
+# Chanx: Stop fighting WebSocket boilerplate in FastAPI (and Django)
+
+After years of building WebSocket apps, I got tired of the same pain points: endless if-else chains, manual validation, missing type safety, and zero documentation. So I built **Chanx** - a batteries-included WebSocket framework that makes FastAPI (and Django Channels) WebSocket development actually enjoyable.
+
+## The Problem
+
+**Without Chanx**, your FastAPI WebSocket code probably looks like this:
+
+```python
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_json()
+        action = data.get("action")
+
+        if action == "chat":
+            if "message" not in data.get("payload", {}):
+                await websocket.send_json({"error": "Missing message"})
+                continue
+            # No broadcasting, must manually track connections
+            # No type safety, no validation, no documentation
+        elif action == "ping":
+            await websocket.send_json({"action": "pong"})
+        # ... more manual handling
+```
+
+You're stuck with:
+- Manual if-else routing hell
+- Hand-written validation code
+- No type safety (runtime surprises!)
+- Zero API documentation
+- No broadcasting/groups out of the box
+- Painful testing setup
+
+## The Solution
+
+**With Chanx**, the same code becomes:
+
+```python
+@channel(name="chat", description="Real-time chat API")
+class ChatConsumer(AsyncJsonWebsocketConsumer):
+    groups = ["chat_room"]  # Auto-join on connect
+
+    @ws_handler(
+        summary="Handle chat messages",
+        output_type=ChatNotificationMessage
+    )
+    async def handle_chat(self, message: ChatMessage) -> None:
+        # Automatically routed, validated, and type-safe
+        await self.broadcast_message(
+            ChatNotificationMessage(
+                payload=ChatPayload(message=f"User: {message.payload.message}")
+            )
+        )
+
+    @ws_handler
+    async def handle_ping(self, message: PingMessage) -> PongMessage:
+        return PongMessage()  # Auto-documented in AsyncAPI
+```
+
+## What You Get
+
+### **Performance & Structure**
+- **Automatic routing** via Pydantic discriminated unions (no if-else chains!)
+- **Type-safe broadcasting** with channel layer integration
+- **Async/await** throughout for maximum performance
+- **Zero overhead** - decorators compile to efficient handlers
+
+### **Offload the Boring Stuff**
+- **Auto-validation** with Pydantic models
+- **AsyncAPI 3.0 docs** generated automatically (like Swagger for WebSockets!)
+- **Type-safe client generator** - generates Python clients from your API
+- **Built-in testing utilities** for both FastAPI and Django
+
+### **Consistency & Type Safety**
+- **mypy/pyright compatible** - catch errors at dev time, not runtime
+- **Single codebase** works with both FastAPI and Django Channels
+- **Enforced patterns** via decorators (no more inconsistent implementations)
+- **Structured logging** with automatic request/response tracing
+
+### **Developer Experience**
+- **Self-documenting code** - AsyncAPI spec is the single source of truth
+- **Clean code reviews** - declarative handlers instead of nested logic
+- **Fast onboarding** - newcomers read the AsyncAPI docs and they're good to go
+- **Framework agnostic** - switch between Django/FastAPI with zero refactoring
+
+## Real-World Impact
+
+What Chanx eliminates in your daily workflow:
+
+**Technical Pain:**
+- Writing manual routing logic
+- Hand-crafting validation code
+- Debugging runtime type errors
+- Writing API documentation
+- Setting up WebSocket test infrastructure
+
+**Team Collaboration:**
+- Inconsistent WebSocket implementations across the team
+- Painful code reviews of nested if-else chains
+- Slow onboarding (no API contract for frontend teams)
+- Debugging hell with unstructured logs
+
+## Quick Example
+
+**1. Define typed messages:**
+```python
+class ChatMessage(BaseMessage):
+    action: Literal["chat"] = "chat"
+    payload: ChatPayload
+
+class ChatNotificationMessage(BaseMessage):
+    action: Literal["chat_notification"] = "chat_notification"
+    payload: ChatPayload
+```
+
+**2. Create consumer:**
+```python
+@channel(name="chat")
+class ChatConsumer(AsyncJsonWebsocketConsumer):
+    groups = ["chat_room"]
+
+    @ws_handler(output_type=ChatNotificationMessage)
+    async def handle_chat(self, message: ChatMessage) -> None:
+        await self.broadcast_message(
+            ChatNotificationMessage(payload=message.payload)
+        )
+```
+
+**3. Setup routing (FastAPI):**
+```python
+app = FastAPI()
+ws_router = FastAPI()
+ws_router.add_websocket_route("/chat", ChatConsumer.as_asgi())
+app.mount("/ws", ws_router)
+```
+
+**4. Visit `/asyncapi/` for interactive documentation**
+
+## Advanced Features
+
+- **Built-in auth** with DRF permission support (+ extensible for custom flows)
+- **Testing utilities** - framework-specific WebSocket communicators
+- **Structured logging** with automatic tracing
+- **Flexible config** - Django settings or class-level attributes
+- **Client generator CLI** - `chanx generate-client --schema http://localhost:8000/asyncapi.json`
+
+## Installation
+
+```bash
+# For FastAPI
+pip install "chanx[fast_channels]"
+
+# For Django Channels
+pip install "chanx[channels]"
+
+# For client generator
+pip install "chanx[cli]"
+```
+
+## Why I Built This
+
+I spent years building real-time features for production apps, and every project had the same problems:
+- Junior devs writing fragile if-else chains
+- No one documenting the WebSocket API
+- Frontend teams guessing message formats
+- Tests breaking on every refactor
+
+Chanx solves all of this by providing **proven patterns** that help teams ship faster, maintain cleaner code, and actually enjoy working with WebSockets.
+
+---
+
+**Links:**
+- PyPI: https://pypi.org/project/chanx/
+- Docs: https://chanx.readthedocs.io/
+- GitHub: https://github.com/huynguyengl99/chanx
+
+Built for the FastAPI and Django communities. Open to feedback and contributions!
+
+---
+
+*Works with Python 3.11+, FastAPI, and Django Channels. Full type safety with mypy/pyright. 100% test coverage.*