From 87920fb1d7ef67aecc3ce8866bfb700f1ef3fd5b Mon Sep 17 00:00:00 2001
From: Jens Langhammer <jens.langhammer@beryju.org>
Date: Sun, 29 Aug 2021 19:49:18 +0200
Subject: [PATCH] website/docs: add docs for websocket connections

Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>
---
 website/developer-docs/{ => api}/api.md       |  0
 .../developer-docs/{ => api}/flow-executor.md |  0
 .../{ => api}/making-schema-changes.md        |  0
 website/developer-docs/api/websocket.md       | 48 +++++++++++++++++++
 .../frontend-only-dev-environment.md          |  0
 .../{ => setup}/full-dev-environment.md       |  0
 website/sidebarsDev.js                        | 30 ++++++------
 7 files changed, 62 insertions(+), 16 deletions(-)
 rename website/developer-docs/{ => api}/api.md (100%)
 rename website/developer-docs/{ => api}/flow-executor.md (100%)
 rename website/developer-docs/{ => api}/making-schema-changes.md (100%)
 create mode 100644 website/developer-docs/api/websocket.md
 rename website/developer-docs/{ => setup}/frontend-only-dev-environment.md (100%)
 rename website/developer-docs/{ => setup}/full-dev-environment.md (100%)

diff --git a/website/developer-docs/api.md b/website/developer-docs/api/api.md
similarity index 100%
rename from website/developer-docs/api.md
rename to website/developer-docs/api/api.md
diff --git a/website/developer-docs/flow-executor.md b/website/developer-docs/api/flow-executor.md
similarity index 100%
rename from website/developer-docs/flow-executor.md
rename to website/developer-docs/api/flow-executor.md
diff --git a/website/developer-docs/making-schema-changes.md b/website/developer-docs/api/making-schema-changes.md
similarity index 100%
rename from website/developer-docs/making-schema-changes.md
rename to website/developer-docs/api/making-schema-changes.md
diff --git a/website/developer-docs/api/websocket.md b/website/developer-docs/api/websocket.md
new file mode 100644
index 000000000..b664ccac9
--- /dev/null
+++ b/website/developer-docs/api/websocket.md
@@ -0,0 +1,48 @@
+---
+title: Websocket API
+---
+
+authentik has two different WebSocket endpoints, one is used for web-based clients to get real-time updates, and the other is used for outposts to report their healthiness.
+
+
+### Web `/ws/client/`
+
+:::info
+Authentication is done using the session, so make sure to send the `Cookie` header.
+:::
+
+All messages have a common field called `message_type` to discern the type of message.
+
+#### `message` type:
+
+This type is used when the backend has a notice to show to the user. A full payload looks like:
+
+```json
+{
+    "message_type": "message",
+    "level": "error" | "warning" | "success" | "info",
+    "tags": "",
+    "message": "a message",
+}
+```
+
+### Outpost `/ws/outpost/<outpost-uuid>/`
+
+:::info
+Authentication is done via the `Authorization` header, same as the regular API. You must send a valid token with a `Bearer ` prefix.
+:::
+
+All messages have two fields, `instruction` and `args`. Instruction is any number from this list:
+
+- `0`: ACK, simply acknowledges the previous message
+- `1`: HELLO, used for monitoring and regularly sent by outposts
+- `2`: TRIGGER_UPDATE, sent by authentik to trigger a reload of the configuration
+
+Arguments for these messages vary, all though these common args are always sent:
+
+- `args['uuid']`: A unique UUID generated on startup of an outpost, used to uniquely identify it.
+
+These fields are only sent for HELLO instructions:
+
+- `args['version']`: Version of the outpost
+- `args['buildHash']`: Build hash of the outpost, when available
diff --git a/website/developer-docs/frontend-only-dev-environment.md b/website/developer-docs/setup/frontend-only-dev-environment.md
similarity index 100%
rename from website/developer-docs/frontend-only-dev-environment.md
rename to website/developer-docs/setup/frontend-only-dev-environment.md
diff --git a/website/developer-docs/full-dev-environment.md b/website/developer-docs/setup/full-dev-environment.md
similarity index 100%
rename from website/developer-docs/full-dev-environment.md
rename to website/developer-docs/setup/full-dev-environment.md
diff --git a/website/sidebarsDev.js b/website/sidebarsDev.js
index 0435711d5..e6ad0979e 100644
--- a/website/sidebarsDev.js
+++ b/website/sidebarsDev.js
@@ -5,28 +5,26 @@ module.exports = {
             id: "index",
         },
         {
-            type: "doc",
-            id: "full-dev-environment",
+            type: "category",
+            label: "Setup",
+            items: [
+                "api/api",
+                "api/flow-executor",
+                "api/making-schema-changes",
+                "api/websocket",
+            ],
         },
         {
-            type: "doc",
-            id: "frontend-only-dev-environment",
-        },
-        {
-            type: "doc",
-            id: "making-schema-changes",
-        },
-        {
-            type: "doc",
-            id: "api",
+            type: "category",
+            label: "Setup",
+            items: [
+                "setup/full-dev-environment",
+                "setup/frontend-only-dev-environment",
+            ],
         },
         {
             type: "doc",
             id: "translation",
         },
-        {
-            type: "doc",
-            id: "flow-executor",
-        },
     ],
 };