Add ability for plugins to register ws routes

2 files changed, 41 insertions, 0 deletions

diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 431d5332f..1c809258a 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -12,6 +12,7 @@
     - [Storage](#storage)
     - [Update video constants](#update-video-constants)
     - [Add custom routes](#add-custom-routes)
+    - [Add custom WebSocket handlers](#add-custom-websocket-handlers)
     - [Add external auth methods](#add-external-auth-methods)
     - [Add new transcoding profiles](#add-new-transcoding-profiles)
     - [Server helpers](#server-helpers)
@@ -317,6 +318,41 @@ The `ping` route can be accessed using:
  * Or `/plugins/:pluginName/router/ping`
 
 
+#### Add custom WebSocket handlers
+
+You can create custom WebSocket servers (like [ws](https://github.com/websockets/ws) for example) using `registerWebSocketRoute`:
+
+```js
+function register ({
+  registerWebSocketRoute,
+  peertubeHelpers
+}) {
+  const wss = new WebSocketServer({ noServer: true })
+
+  wss.on('connection', function connection(ws) {
+    peertubeHelpers.logger.info('WebSocket connected!')
+
+    setInterval(() => {
+      ws.send('WebSocket message sent by server');
+    }, 1000)
+  })
+
+  registerWebSocketRoute({
+    route: '/my-websocket-route',
+
+    handler: (request, socket, head) => {
+      wss.handleUpgrade(request, socket, head, ws => {
+        wss.emit('connection', ws, request)
+      })
+    }
+  })
+}
+```
+
+The `my-websocket-route` route can be accessed using:
+ * `/plugins/:pluginName/:pluginVersion/ws/my-websocket-route`
+ * Or `/plugins/:pluginName/ws/my-websocket-route`
+
 #### Add external auth methods
 
 If you want to add a classic username/email and password auth method (like [LDAP](https://framagit.org/framasoft/peertube/official-plugins/-/tree/master/peertube-plugin-auth-ldap) for example):
diff --git a/support/nginx/peertube b/support/nginx/peertube
index abb83d5c4..f6f754b58 100644
--- a/support/nginx/peertube
+++ b/support/nginx/peertube
@@ -132,6 +132,11 @@ server {
     try_files /dev/null @api_websocket;
   }
 
+  # Plugin websocket routes
+  location ~ ^/plugins/[^/]+(/[^/]+)?/ws/ {
+    try_files /dev/null @api_websocket;
+  }
+
   ##
   # Performance optimizations
   # For extra performance please refer to https://github.com/denji/nginx-tuning