WebSocket

Prism has built-in WebSocket support with no external dependencies. It handles the HTTP upgrade handshake, frame parsing, and provides an actor-based connection model for safe concurrent messaging.

How It Works

Client sends an HTTP request with Upgrade: websocket
Prism validates the handshake and sends a 101 Switching Protocols response
The connection switches to the WebSocket protocol
Your handler receives connect, message, and disconnect events

Creating a Handler

Implement the PrismWebSocketHandler protocol:

Echo Handler

struct EchoHandler: PrismWebSocketHandler {
    func onConnect(connection: PrismWebSocketConnection) async {
        print("Client connected: \(connection.id)")
        await connection.send("Welcome!")
    }

    func onMessage(connection: PrismWebSocketConnection, message: PrismWebSocketMessage) async {
        switch message {
        case .text(let text):
            await connection.send("Echo: \(text)")
        case .binary(let data):
            await connection.send(data)
        }
    }

    func onDisconnect(connection: PrismWebSocketConnection) async {
        print("Client disconnected: \(connection.id)")
    }
}

Registering WebSocket Routes

let server = PrismHTTPServer(port: 8080)
await server.webSocket("/ws", handler: EchoHandler())
try await server.start()

Building a Chat Server

Simple Chat Server

actor ChatServer: PrismWebSocketHandler {
    private var connections: [String: PrismWebSocketConnection] = [:]

    func onConnect(connection: PrismWebSocketConnection) async {
        connections[connection.id] = connection
        await broadcast("User \(connection.id.prefix(8)) joined")
    }

    func onMessage(connection: PrismWebSocketConnection, message: PrismWebSocketMessage) async {
        if case .text(let text) = message {
            await broadcast("[\(connection.id.prefix(8))]: \(text)")
        }
    }

    func onDisconnect(connection: PrismWebSocketConnection) async {
        connections.removeValue(forKey: connection.id)
        await broadcast("User \(connection.id.prefix(8)) left")
    }

    private func broadcast(_ message: String) async {
        for (_, conn) in connections {
            await conn.send(message)
        }
    }
}

Client-Side Connection

Browser Client

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onopen = () => {
    console.log('Connected');
    ws.send('Hello from browser!');
};

ws.onmessage = (event) => {
    console.log('Received:', event.data);
};

ws.onclose = () => {
    console.log('Disconnected');
};

Message Types

Text
Binary

// Send text
await connection.send("Hello, World!")

// Receive text
case .text(let text):
    print(text)

// Send binary data
let imageData = Data(...)
await connection.send(imageData)

// Receive binary
case .binary(let data):
    processImage(data)

Real-Time Notifications Example

Notification System

actor NotificationHandler: PrismWebSocketHandler {
    private var userConnections: [String: PrismWebSocketConnection] = [:]

    func onConnect(connection: PrismWebSocketConnection) async {
        // Client sends user ID as first message
    }

    func onMessage(connection: PrismWebSocketConnection, message: PrismWebSocketMessage) async {
        if case .text(let text) = message {
            // Register user connection
            userConnections[text] = connection
        }
    }

    func onDisconnect(connection: PrismWebSocketConnection) async {
        userConnections = userConnections.filter { $0.value.id != connection.id }
    }

    // Called from your API routes
    func notify(userId: String, message: String) async {
        if let conn = userConnections[userId] {
            await conn.send(message)
        }
    }
}

For multi-room scenarios, check out WebSocket Rooms — it provides room management, broadcasting, and presence tracking out of the box.

Ping/Pong

Prism automatically responds to WebSocket ping frames with pong frames. This keeps connections alive through proxies and load balancers that might otherwise time out idle connections.

Core

Middleware

Database

Real-Time

Content

Server Security

GraphQL

MCP

Infrastructure

Advanced

Testing

WebSocket

WebSocket

How It Works

Creating a Handler

Registering WebSocket Routes

Building a Chat Server

Client-Side Connection

Message Types

Real-Time Notifications Example

Ping/Pong

​WebSocket

​How It Works

​Creating a Handler

​Registering WebSocket Routes

​Building a Chat Server

​Client-Side Connection

​Message Types

​Real-Time Notifications Example

​Ping/Pong

WebSocket

How It Works

Creating a Handler

Registering WebSocket Routes

Building a Chat Server

Client-Side Connection

Message Types

Real-Time Notifications Example

Ping/Pong