From 61e60133ef6d169cb82ca2fd26f10cdbebfc46ff Mon Sep 17 00:00:00 2001
From: tobi <31960611+tsmethurst@users.noreply.github.com>
Date: Fri, 22 Apr 2022 13:35:19 +0200
Subject: [PATCH] [documentation] Add WebSocket protocol documentation (#470)

---
 docs/installation_guide/websocket.md | 43 ++++++++++++++++++++++++++++
 mkdocs.yml                           |  1 +
 2 files changed, 44 insertions(+)
 create mode 100644 docs/installation_guide/websocket.md

diff --git a/docs/installation_guide/websocket.md b/docs/installation_guide/websocket.md
new file mode 100644
index 000000000..cc5a56c69
--- /dev/null
+++ b/docs/installation_guide/websocket.md
@@ -0,0 +1,43 @@
+# WebSocket
+
+GoToSocial uses the secure [WebSocket protocol](https://en.wikipedia.org/wiki/WebSocket) (aka `wss`) to allow for streaming updates of statuses and notifications via client apps like Pinafore.
+
+In order to use this functionality, you need to ensure that whatever proxy you've configured GoToSocial to run behind allows WebSocket connections through.
+
+The WebSocket endpoint is located at `wss://example.org/api/v1/streaming` where `example.org` is the hostname of your GoToSocial instance.
+
+The WebSocket endpoint uses the same port as configured in the `port` section of your [general config](../configuration/general.md).
+
+Typical WebSocket **request** headers as sent by Pinafore look like the following:
+
+```text
+Host: example.org
+User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:99.0) Gecko/20100101 Firefox/99.0
+Accept: */*
+Accept-Language: en-US,en;q=0.5
+Accept-Encoding: gzip, deflate, br
+Sec-WebSocket-Version: 13
+Origin: https://pinafore.social
+Sec-WebSocket-Protocol: null
+Sec-WebSocket-Extensions: permessage-deflate
+Sec-WebSocket-Key: YWFhYWFhYm9vYmllcwo=
+DNT: 1
+Connection: keep-alive, Upgrade
+Sec-Fetch-Dest: websocket
+Sec-Fetch-Mode: websocket
+Sec-Fetch-Site: cross-site
+Pragma: no-cache
+Cache-Control: no-cache
+Upgrade: websocket
+```
+
+Typical WebSocket **response** headers as returned by GoToSocial look like the following:
+
+```text
+HTTP/1.1 101 Switching Protocols
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Accept: WVdGaFlXRmhZbTl2WW1sbGN3bz0K
+```
+
+Whatever your setup, you need to ensure that these headers are allowed through your proxy, which may require extra configuration depending on the exact proxy being used.
diff --git a/mkdocs.yml b/mkdocs.yml
index 5e128ce21..b5704a3d3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -20,6 +20,7 @@ nav:
     - "installation_guide/nginx.md"
     - "installation_guide/apache-httpd.md"
     - "installation_guide/third_party.md"
+    - "installation_guide/websocket.md"
   - "Configuration":
     - "configuration/index.md"
     - "configuration/general.md"