From b6468c7602b1f5a02fba14141902205e15e651f6 Mon Sep 17 00:00:00 2001
From: "Alexie (Boyong) Madolid" <maex@tuta.io>
Date: Fri, 8 Nov 2024 01:05:10 +0800
Subject: [PATCH] [WEBSOCKET]: Documentation

---
 .../plugin/implementation/websocket.md        | 155 ++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 jac-cloud/jac_cloud/plugin/implementation/websocket.md

diff --git a/jac-cloud/jac_cloud/plugin/implementation/websocket.md b/jac-cloud/jac_cloud/plugin/implementation/websocket.md
new file mode 100644
index 0000000000..11a6f42b02
--- /dev/null
+++ b/jac-cloud/jac_cloud/plugin/implementation/websocket.md
@@ -0,0 +1,155 @@
+# **`WEBSOCKET`**
+
+## Walker Declaration
+- walker can be declared as websocket thru __specs__ configurations.
+- it can still work along with other http methods however, the only limitation is it doesn't support file (maybe in the future).
+```python
+walker your_event_name {
+    has val: int;
+    can enter with `root entry {
+        report "Do something!";
+    }
+
+    class __specs__ {
+        has methods: list = ["websocket"];
+    }
+}
+```
+
+## **`Websocket Connection`**
+> PROTOCOL: **`ws`** \
+> URL: **`/websocket`** \
+> HEADER (optional): **`Authorization: Bearer {{USER-TOKEN}}`** \
+> QUERY PARAM (optional): **`?channel_id=anystring`**
+- once connected, you will recieved first event for connection information
+- there's two type of connection
+    - Authenticated - with valid Authorization Token
+    - Non Authenticated
+- you may specify your desired channel_id via query param
+    - this will recieved notification from specific channel
+    - usage: group chat/notification
+```python
+{
+	"type": "connection",
+	"data": {
+        # your websocket client id
+		"client_id": "1730887348:f46d85203c704c099e9f44e948322a20",
+
+        # user's root_id
+		"root_id": "n::672b35cec309e5ef8469c372",
+
+        # non authenticated
+		# "root_id": "n::000000000000000000000001",
+
+        # user's channel id, random if not specified
+		"channel_id": "1730887348:796ad2e9fa3e484ebe01f071c381b7e8"
+	}
+}
+```
+
+## **`Client Valid Events`**
+### Walker
+- this will trigger a normal walker as if it was trigger via rest API
+```python
+{
+    # event type
+	"type": "walker",
+
+    # walker's name
+	"walker": "your_event_name",
+
+    # if you want to recieve a notification for response
+	"response": true,
+
+    # walker's request context
+	"context": {
+        "val": 1
+    }
+}
+```
+
+### User
+- this will send notification to target user's clients
+- if target user/s has multiple clients, all of it will get notified
+```python
+{
+    # event type
+	"type": "user",
+
+    # target user/s via root_id
+    "root_ids": ["n::672b35cec309e5ef8469c372"],
+
+    # data you want to send
+	"data": {
+        "val": 1
+    }
+}
+```
+
+### Channel
+- this will send notification to target channel/s
+- all clients that's subcribed to the channel will get notified
+```python
+{
+    # event type
+	"type": "channel",
+
+    # target channel_id/s
+    "channel_ids": ["anystring"],
+
+    # data you want to send
+	"data": {
+        "val": 1
+    }
+}
+```
+
+### Client
+- this will send notification to target client/s
+```python
+{
+    # event type
+	"type": "client",
+
+    # target client_id/s
+    "client_ids": ["1730887348:f46d85203c704c099e9f44e948322a20"],
+
+    # data you want to send
+	"data": {
+        "val": 1
+    }
+}
+```
+
+## **`Walker Client Notification`**
+### **`PREREQUISITE`**
+```python
+import:py from jac_cloud.plugin {WEBSOCKET_MANAGER as socket}
+```
+
+### Self
+- this will send notification to current websocket it was from (only valid on websocket walker event)
+- if via walker api, nothing will happen
+```python
+socket.notify_self({"any_field": "for_progress", "progress": "0%", "status": "started"});
+```
+
+### User
+- this will send notification to target user's clients
+- if target user/s has multiple clients, all of it will get notified
+```python
+socket.notify_users([root], {"any_field": "for_progress", "progress": "0%", "status": "started"});
+```
+
+### Channel
+- this will send notification to target channel/s
+- all clients that's subcribed to the channel will get notified
+```python
+socket.notify_channels([channel_id], {"any_field": "for_progress", "progress": "0%", "status": "started"});
+```
+
+### Client
+- this will send notification to target client/s
+```python
+socket.notify_clients([client_id], {"any_field": "for_progress", "progress": "0%", "status": "started"});
+```