From eae85abd8ac3ddf8cd143923642eff3e0e9817eb Mon Sep 17 00:00:00 2001
From: HenrikJannsen <boilingfrog@gmx.com>
Date: Mon, 13 Jan 2025 21:03:27 +0700
Subject: [PATCH] Add readme for websockets

---
 .../bisq/mobile/client/websocket/README.md    | 36 +++++++++++++++++++
 .../websocket/api_proxy/WebSocketApiClient.kt |  8 ++---
 2 files changed, 40 insertions(+), 4 deletions(-)
 create mode 100644 shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/README.md

diff --git a/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/README.md b/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/README.md
new file mode 100644
index 00000000..27f84a6f
--- /dev/null
+++ b/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/README.md
@@ -0,0 +1,36 @@
+# Websocket overview
+
+We use websockets for getting data pushed from the back-end.
+
+## Rest Api proxy
+
+As in case of Tor we want to avoid establishing unnecessary new connections due the delay and risk that a connection attempt fails, we
+use the existing websocket connection to tunnel the Rest API requests to the backend server which unpacks it and does a local Rest Api
+request and returns the result in the websocket connection.
+The request blocks until the response is provided.
+
+Note: For POST and PATCH there is a unresolved bug on the backend, so we use the Rest Api endpoints directly for now.
+
+## Topics
+
+Topics are used to subscribe for certain types of events.
+
+## Subscription
+
+To subscribe to some data stream we use a subscription ID and topic. Optional a parameter can be added.
+The response to the `SubscriptionRequest` will contain an optional payload and optional errorMessage.
+The payload is a json string and will be deserialized by the actual subscriber.
+The type of the payload is defined by the Subscription as well as provided in the Topic as a `kotlin.reflect.KType`.
+
+## Events
+
+When a data update on the back-end is propagated to the client, we receive a `WebSocketEvent`.
+This contains the payload, the `ModificationType` and a sequence number. The sequence number is to ensure order of events.
+`ModificationType` gives information if data was added, removed or replaced.
+We use a list for the payloads to support multiple changes being batched in one event.
+
+
+
+
+
+
diff --git a/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/api_proxy/WebSocketApiClient.kt b/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/api_proxy/WebSocketApiClient.kt
index b1c26981..ea620340 100644
--- a/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/api_proxy/WebSocketApiClient.kt
+++ b/shared/domain/src/commonMain/kotlin/network/bisq/mobile/client/websocket/api_proxy/WebSocketApiClient.kt
@@ -29,9 +29,9 @@ class WebSocketApiClient(
     val apiPath = "/api/v1/"
     var apiUrl = "http://$host:$port$apiPath"
 
-    // POST request still not working, but issue is likely on the bisq2 side.
+    // POST and PATCH request are not working yes on the backend.
     // So we use httpClient instead.
-    val useHttpClientForPost = true
+    val useHttpClient = true
 
     suspend inline fun <reified T> get(path: String): Result<T> {
         return request<T>("GET", path)
@@ -55,7 +55,7 @@ class WebSocketApiClient(
     }
 
     suspend inline fun <reified T, reified R> patch(path: String, requestBody: R): Result<T> {
-        if (useHttpClientForPost) {
+        if (useHttpClient) {
             try {
                 val response: HttpResponse = httpClient.patch(apiUrl + path) {
                     contentType(ContentType.Application.Json)
@@ -76,7 +76,7 @@ class WebSocketApiClient(
     }
 
     suspend inline fun <reified T, reified R> post(path: String, requestBody: R): Result<T> {
-        if (useHttpClientForPost) {
+        if (useHttpClient) {
             try {
                 val response: HttpResponse = httpClient.post(apiUrl + path) {
                     contentType(ContentType.Application.Json)