Skip to content

# WebSockets

WebSockets in Ignyx provide full bidirectional, full-duplex communication between the client and the server. Built on top of the high-performance Rust `tokio-tungstenite` library, Ignyx WebSockets are incredibly fast and efficient.

## Overview

Unlike standard HTTP requests, WebSockets maintain a persistent connection, allowing both parties to send data at any time. This is ideal for real-time applications like chat servers, live dashboards, and multiplayer games.

## Basic Example: Echo Server

Creating a WebSocket endpoint is simple. You use the `@app.websocket` decorator and an `async def` function.

    from ignyx import Ignyx

    app = Ignyx()

    @app.websocket("/ws")
    async def websocket_endpoint(ws):
        await ws.accept()
        while True:
            try:
                data = await ws.receive_text()
                await ws.send_text(f"Echo: {data}")
            except Exception:
                # Handle disconnection
                break

## Advanced Example: Chat Room

You can manage multiple connections using a simple dictionary or list.

    from ignyx import Ignyx

    app = Ignyx()
    connected_clients = set()

    @app.websocket("/chat")
    async def chat_room(ws):
        await ws.accept()
        connected_clients.add(ws)
        try:
            while True:
                msg = await ws.receive_text()
                # Broadcast to all connected clients
                for client in connected_clients:
                    await client.send_text(f"User: {msg}")
        except Exception:
            pass
        finally:
            connected_clients.remove(ws)

## Sending JSON

Ignyx makes it easy to work with structured data over WebSockets using JSON.

    @app.websocket("/notifications")
    async def notifications(ws):
        await ws.accept()
        # Sending a JSON object
        await ws.send_json({"type": "info", "message": "Welcome to the real-time era!"})

        # Receiving JSON
        data = await ws.receive_json()
        print(f"Received JSON: {data['content']}")

## Closing

You can close a connection gracefully at any time.

    @app.websocket("/once")
    async def once(ws):
        await ws.accept()
        await ws.send_text("Goodbye!")
        await ws.close(code=1000)

## Error Handling

Always wrap your communication loop in a `try/except` block to detect when a client disconnects.

    @app.websocket("/safe")
    async def safe_ws(ws):
        await ws.accept()
        try:
            while True:
                data = await ws.receive_text()
                # process data
        except Exception as e:
            print(f"Client disconnected or error occurred: {e}")

## API Reference

### `ws.accept()`

Accepts the incoming WebSocket connection. This must be called before sending or receiving data.

### `await ws.receive_text()`

Wait for a text message from the client. Returns a `str`.

### `await ws.receive_json()`

Wait for a text message and parse it as JSON. Returns a `dict` or `list`.

### `await ws.send_text(data)`

Send a string message to the client.

### `await ws.send_json(data)`

Serialize the data and send it as a JSON string message.

### `await ws.close(code=1000)`

Close the connection with the specified status code.