WebSocket example (#5)

Author: Klavionik

README.md

@@ -1,9 +1,10 @@
 # BlackSheep-Examples
 Various examples for BlackSheep.
 
-| Example                                              | Description                                                                                                                                                                                                                                                                               |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [./testing-api/](./testing-api/)                     | Shows how to test a BlackSheep API using `pytest` and the provided `TestClient` (see also [testing](https://www.neoteroi.dev/blacksheep/testing/))                                                                                                                                        |
-| [./piccolo-admin/](./piccolo-admin/)                 | Shows how to use the mount feature to use [Piccolo Admin](https://github.com/piccolo-orm/piccolo_admin) in BlackSheep                                                                                                                                                                     |
-| [./jwt-validation](./jwt-validation)                 | Shows how to configure a BlackSheep API that uses JWTs to implement authentication and authorization for users                                                                                                                                                                            |
-| [./aad-machine-to-machine](./aad-machine-to-machine) | Shows how to configure an API that requires access tokens issued by Azure Active Directory, and how to obtain access tokens using [MSAL for Python](https://github.com/AzureAD/microsoft-authentication-library-for-python) for a confidential client (machine to machine communication). |
+| Example                                              | Description                                                                                                                                                                                                                                                                              |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [./testing-api/](./testing-api/)                     | Shows how to test a BlackSheep API using `pytest` and the provided `TestClient` (see also [testing](https://www.neoteroi.dev/blacksheep/testing/))                                                                                                                                       |
+| [./piccolo-admin/](./piccolo-admin/)                 | Shows how to use the mount feature to use [Piccolo Admin](https://github.com/piccolo-orm/piccolo_admin) in BlackSheep                                                                                                                                                                    |
+| [./jwt-validation](./jwt-validation)                 | Shows how to configure a BlackSheep API that uses JWTs to implement authentication and authorization for users                                                                                                                                                                           |
+| [./aad-machine-to-machine](./aad-machine-to-machine) | Shows how to configure an API that requires access tokens issued by Azure Active Directory, and how to obtain access tokens using [MSAL for Python](https://github.com/AzureAD/microsoft-authentication-library-for-python) for a confidential client (machine to machine communication) |
+| [./websocket-chat](./websocket-chat)                 | Shows how to use WebSocket with BlackSheep, the example consists of a simple chat application built using WebSocket and VueJS                                                                                                                                                            |

websocket-chat/README.md

@@ -0,0 +1,35 @@
+# Chat app example
+
+This folder contains a simple chat application built using WebSocket and VueJS.
+You can use it as a starting point to build your own real-time application using
+WebSocket.
+
+Bear in mind, though, that this is merely an example. In the real world, you would
+probably like to use a message queue like Redis to broadcast messages to the clients 
+and some persistent storage like PostgreSQL or MongoDB to store your messages, users, etc.
+
+## Getting started
+
+1. Create a Python virtual environment
+2. Activate the virtual environment
+3. Install dependencies in `requirements.txt`
+4. Run the application using `uvicorn --reload server:app`
+5. Navigate to `http://localhost:8000` in your browser and try sending
+some messages. You can open it in multiple tabs to simulate
+multiple clients connected.
+
+```bash
+# create a Python virtual environment
+python -m venv venv
+
+# activate
+source venv/bin/activate  # (Linux)
+
+venv\Scripts\activate  # (Windows)
+
+# install dependencies
+pip install -r requirements.txt
+
+# run app
+uvicorn --reload server:app
+```

websocket-chat/app/__init__.py

@@ -0,0 +1,60 @@
+from datetime import datetime
+from typing import List
+
+from blacksheep import WebSocket
+from .message import Message
+
+
+class Connection:
+    def __init__(self, socket: WebSocket, client_id: str):
+        self.socket = socket
+        self.client_id = client_id
+
+    async def receive(self) -> Message:
+        data = await self.socket.receive_json()
+        message = Message(**data)
+        return message
+
+    async def send(self, message: Message):
+        await self.socket.send_json(message.asdict())
+
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: List[Connection] = []
+
+    async def connect(self, websocket: WebSocket, client_id: str) -> Connection:
+        await websocket.accept()
+        connection = Connection(websocket, client_id)
+        await self.greet(connection)
+        self.active_connections.append(connection)
+        return connection
+
+    async def disconnect(self, connection: Connection):
+        self.active_connections.remove(connection)
+        await self.bye(connection)
+
+    async def manage(self, connection: Connection):
+        message = await connection.receive()
+        await self.broadcast(message)
+
+    async def broadcast(self, message: Message):
+        print('Broadcast to %s connections' % len(self.active_connections))
+        for connection in self.active_connections:
+            await connection.send(message)
+
+    async def greet(self, connection: Connection):
+        message = Message(
+            author='Server',
+            timestamp=datetime.now().isoformat(),
+            text=f'{connection.client_id} enters the chat',
+        )
+        await self.broadcast(message)
+
+    async def bye(self, connection: Connection):
+        message = Message(
+            author='Server',
+            timestamp=datetime.now().isoformat(),
+            text=f'{connection.client_id} disconnected',
+        )
+        await self.broadcast(message)

websocket-chat/app/connection.py

@@ -0,0 +1,28 @@
+import pathlib
+
+from blacksheep import Application, WebSocket, WebSocketDisconnectError
+from blacksheep.server.responses import redirect
+from .connection import ConnectionManager
+
+APP_PATH = pathlib.Path(__file__).parent / 'static'
+
+app = Application()
+app.serve_files(APP_PATH, root_path='app')
+
+manager = ConnectionManager()
+
+
+@app.router.ws('/ws/{client_id}')
+async def ws(websocket: WebSocket, client_id: str):
+    conn = await manager.connect(websocket, client_id)
+
+    try:
+        while True:
+            await manager.manage(conn)
+    except WebSocketDisconnectError:
+        await manager.disconnect(conn)
+
+
+@app.router.get('/')
+def index():
+    return redirect('/app')

websocket-chat/app/main.py

@@ -0,0 +1,11 @@
+import dataclasses
+
+
+@dataclasses.dataclass
+class Message:
+    author: str
+    text: str
+    timestamp: str
+
+    def asdict(self):
+        return dataclasses.asdict(self)

websocket-chat/app/message.py

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>BlackSheep WebSocket Example</title>
+    <script src="https://unpkg.com/vue@next"></script>
+    <style>
+        .controls {
+            display: flex;
+            column-gap: 3px;
+        }
+    </style>
+</head>
+<body>
+<div id="app">
+    <p><b>Your client ID is {{ CLIENT_ID }}</b></p>
+    <p>Status: {{ status }}</p>
+    <p>Messages:</p>
+    <ul>
+        <li v-for="message in messages" :key="message.timestamp">
+            <div><b>From:</b> {{ message.author }}</div>
+            <div><b>Sent:</b> {{ renderTimestamp(message.timestamp) }}</div>
+            <div><b>Text:</b> {{ message.text }}</div>
+        </li>
+    </ul>
+    <div class="controls" @keypress.enter.prevent="submit">
+        <input type="text" placeholder="Your message" v-model="messageText">
+        <button type="button" :disabled="!ws" @click.prevent="submit">Submit</button>
+        <button type="button" :disabled="ws" @click.prevent="connect(WS_URL)">Connect</button>
+        <button type="button" :disabled="!ws" @click.prevent="disconnect">Disconnect</button>
+    </div>
+</div>
+<script>
+  CLIENT_ID = crypto.randomUUID()
+  WS_URL = `ws://${location.host}/ws/${CLIENT_ID}`
+
+  const app = {
+    data() {
+      return {
+        messages: [],
+        messageText: "",
+        ws: null,
+        status: "Disconnected",
+        WS_URL,
+        CLIENT_ID
+      }
+    },
+    methods: {
+      makeMessage() {
+        return {
+          author: this.CLIENT_ID,
+          text: this.messageText,
+          timestamp: new Date().toISOString()
+        }
+      },
+      submit() {
+        const message = this.makeMessage()
+        this.ws.send(JSON.stringify(message))
+        this.messageText = ""
+      },
+      connect(url) {
+        const ws = new WebSocket(url)
+
+        ws.addEventListener("open", (evt) => {
+          this.status = "Connected"
+          console.log("Open", evt)
+        })
+
+        ws.addEventListener("message", (evt) => {
+          this.messages.push(JSON.parse(evt.data))
+          console.log("Message", evt)
+        })
+
+        ws.addEventListener("close", (evt) => {
+          this.status = "Disconnected"
+          console.log("Close", evt)
+        })
+
+        ws.addEventListener("error", (evt) => {
+          this.status = "Error (see console)"
+          console.error("Error", evt)
+        })
+
+        this.ws = ws
+      },
+      disconnect() {
+        this.ws.close()
+        this.ws = null
+        this.messages = []
+      },
+      renderTimestamp(timestamp) {
+        return new Date(timestamp).toLocaleTimeString()
+      }
+    }
+  }
+
+  Vue.createApp(app).mount("#app")
+</script>
+</body>
+</html>

websocket-chat/app/static/index.html

@@ -0,0 +1,2 @@
+uvicorn[standard]
+blacksheep

websocket-chat/requirements.txt

@@ -0,0 +1 @@
+from app.main import app