[WEBSOCKET]: Documentation

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"});
+```