feat: enhance WebSocket plugin with binary message support and improved API

- Updated `WebSocketPlugin.connect` to accept an optional `binaryType` parameter.
- Modified `WebSocketInstance.send` method to handle both string and binary messages.
- Enhanced JavaScript interface to support binary message sending and receiving.
- Improved event handling for binary messages in both Java and JavaScript layers.
- Added logging for better debugging of message sending and receiving.

Author: UnschooledGamer

src/plugins/websocket/README.md

@@ -45,32 +45,38 @@ WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"],
 
 ### Methods
 
-* `WebSocketPlugin.connect(url, protocols, headers)`
-
+* `WebSocketPlugin.connect(url, protocols, headers, binaryType)`
     * Connects to a WebSocket server.
     * `url`: The WebSocket server URL.
     * `protocols`: (Optional) An array of subprotocol strings.
-    * `headers` (object, optional): Custom headers as key-value pairs.
+    * `headers`: (Optional) Custom headers as key-value pairs.
+    * `binaryType`: (Optional) Initial binary type setting.
     * **Returns:** A Promise that resolves to a `WebSocketInstance`.
+
 * `WebSocketPlugin.listClients()`
     * Lists all stored webSocket instance IDs.
-    * **Returns:** `Promise`that resolves to an array of `instanceId` strings.
-  
-* `WebSocketPlugin.send(instanceId, message)`
-    * same as `WebSocketInstance.send(message)` but needs `instanceId`.
-    * **Returns:** `Promise` that resolves.
+    * **Returns:** `Promise` that resolves to an array of `instanceId` strings.
+
+* `WebSocketPlugin.send(instanceId, message, binary)`
+    * Sends a message to the server using an instance ID.
+    * `instanceId`: The ID of the WebSocket instance.
+    * `message`: The message to send (string or ArrayBuffer/ArrayBufferView).
+    * `binary`: (Optional) Whether to send the message as binary, accepts `boolean`
+    * **Returns:** `Promise` that resolves when the message is sent.
 
 * `WebSocketPlugin.close(instanceId, code, reason)`
     * same as `WebSocketInstance.close(code, reason)` but needs `instanceId`.
     * **Returns:** `Promise` that resolves.
 
-* `WebSocketInstance.send(message)`
+### WebSocketInstance Methods
 
+* `WebSocketInstance.send(message, binary)`
     * Sends a message to the server.
+    * `message`: The message to send (string or ArrayBuffer/ArrayBufferView).
+    * `binary`: (Optional) Whether to send the message as binary. accepts `boolean`
     * Throws an error if the connection is not open.
 
 * `WebSocketInstance.close(code, reason)`
-
     * Closes the connection.
     * `code`: (Optional) If unspecified, a close code for the connection is automatically set: to 1000 for a normal closure, or otherwise to [another standard value in the range 1001-1015](https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1) that indicates the actual reason the connection was closed.
     * `reason`: A string providing a [custom WebSocket connection close reason](https://www.rfc-editor.org/rfc/rfc6455.html#section-7.1.6) (a concise human-readable prose explanation for the closure). The value must be no longer than 123 bytes (encoded in UTF-8).
@@ -84,12 +90,40 @@ WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"],
 * `onclose`: Event listener for connection close.
 * `onerror`: Event listener for errors.
 * `readyState`: (number) The state of the connection.
-
     * 0 (`CONNECTING`): Socket created, not yet open.
     * 1 (`OPEN`): Connection is open and ready.
     * 2 (`CLOSING`): Connection is closing.
     * 3 (`CLOSED`): Connection is closed or couldn't be opened.
-* `extensions`: (string) Extensions negotiated by the server (usually empty or a list).
+* `extensions`: (string) Extensions negotiated by the server.
+* `binaryType`: (string) Type of binary data to use ('arraybuffer' or '' (binary payload returned as strings.)).
+* `url`: (string) The WebSocket server URL.
+* `instanceId`: (string) Unique identifier for this WebSocket instance.
+
+### Event Handling
+
+`WebSocketInstance` extends `EventTarget`, providing standard event handling methods:
+
+* `addEventListener(type, listener)`: Registers an event listener.
+* `removeEventListener(type, listener)`: Removes an event listener.
+* `dispatchEvent(event)`: Dispatches an event to the object.
+
+Example of using event listeners:
+```javascript
+const ws = await WebSocketPlugin.connect("wss://example.com/socket");
+
+// Using on* properties
+ws.onmessage = (event) => console.log("Message:", event.data);
+
+// Using addEventListener
+ws.addEventListener('message', (event) => console.log("Message:", event.data));
+```
+
+### Constants
+
+* `WebSocketInstance.CONNECTING`: 0
+* `WebSocketInstance.OPEN`: 1
+* `WebSocketInstance.CLOSING`: 2
+* `WebSocketInstance.CLOSED`: 3
 
 ---
 

src/plugins/websocket/src/android/WebSocketInstance.java

@@ -1,5 +1,6 @@
 package com.foxdebug.websocket;
 
+import android.util.Base64;
 import android.util.Log;
 
 import androidx.annotation.NonNull;
@@ -17,6 +18,7 @@
 import okio.ByteString;
 
 public class WebSocketInstance extends WebSocketListener {
+    private static final String TAG = "WebSocketInstance";
     private static final int DEFAULT_CLOSE_CODE = 1000;
     private static final String DEFAULT_CLOSE_REASON = "Normal closure";
 
@@ -73,21 +75,34 @@ public void setCallback(CallbackContext callbackContext) {
         callbackContext.sendPluginResult(result);
     }
 
-    public void send(String message) {
+    public void send(String message, boolean isBinary) {
         if (this.webSocket != null) {
+            Log.d(TAG, "websocket instanceId=" + this.instanceId + " received send(..., isBinary=" + isBinary + ") action call, sending message=" + message);
+            if(isBinary) {
+                this.sendBinary(message);
+                return;
+            }
             this.webSocket.send(message);
-            Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received send() action call, sending message=" + message);
         } else {
-            Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received send() action call, ignoring... as webSocket is null (not present)");
+            Log.d(TAG, "websocket instanceId=" + this.instanceId + " received send(..., isBinary=" + isBinary + ")  ignoring... as webSocket is null (not present/connected)");
         }
     }
 
+    /**
+     * Sends bytes as the data of a binary (type 0x2) message.
+     * @param base64Data Binary Data received from JS bridge encoded as base64 String
+     */
+    private void sendBinary(String base64Data) {
+        byte[] data = Base64.decode(base64Data, Base64.DEFAULT);
+        this.webSocket.send(ByteString.of(data));
+    }
+
     public String close(int code, String reason) {
         if (this.webSocket != null) {
             this.readyState = 2; // CLOSING
             try {
                 boolean result = this.webSocket.close(code, reason);
-                Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received close() action call");
+                Log.d(TAG, "websocket instanceId=" + this.instanceId + " received close() action call, code=" + code + " reason=" + reason + " close method result: " + result);
 
                 // if a graceful shutdown was already underway...
                 // or if the web socket is already closed or canceled. do nothing.
@@ -100,14 +115,14 @@ public String close(int code, String reason) {
 
             return null;
         } else {
-            Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received close() action call, ignoring... as webSocket is null (not present)");
+            Log.d(TAG, "websocket instanceId=" + this.instanceId + " received close() action call, ignoring... as webSocket is null (not present)");
             // TODO: finding a better way of telling it wasn't successful.
             return "";
         }
     }
 
     public String close() {
-        Log.d("WebSocketInstance", "WebSocket instanceId=" + this.instanceId + " close() called with no arguments. Using defaults.");
+        Log.d(TAG, "WebSocket instanceId=" + this.instanceId + " close() called with no arguments. Using defaults.");
         // Calls the more specific version with default values
         return close(DEFAULT_CLOSE_CODE, DEFAULT_CLOSE_REASON);
     }
@@ -118,76 +133,81 @@ public void onOpen(@NonNull WebSocket webSocket, Response response) {
         this.readyState = 1; // OPEN
         this.extensions = response.headers("Sec-WebSocket-Extensions").toString();
         this.protocol = response.header("Sec-WebSocket-Protocol");
-        Log.i("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Opened" + "received extensions=" + this.extensions);
-        sendEvent("open", null, false);
+        Log.i(TAG, "websocket instanceId=" + this.instanceId + " Opened" + "received extensions=" + this.extensions);
+        sendEvent("open", null, false, false);
     }
 
     @Override
     public void onMessage(@NonNull WebSocket webSocket, @NonNull String text) {
-        Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId +  " Received message: " + text);
-        sendEvent("message", text, false);
+        Log.d(TAG, "websocket instanceId=" + this.instanceId +  " Received message: " + text);
+        sendEvent("message", text, false, false);
     }
 
     // This is called when the Websocket server sends a binary(type 0x2) message.
     @Override
     public void onMessage(@NonNull WebSocket webSocket, @NonNull ByteString bytes) {
-        Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId +  " Received message(bytes): " + bytes.toString());
+        Log.d(TAG, "websocket instanceId=" + this.instanceId +  " Received message(bytes/binary payload): " + bytes.toString());
 
         try {
             if ("arraybuffer".equals(this.binaryType)) {
                 String base64 = bytes.base64();
-                sendEvent("message", base64, true);
+                sendEvent("message", base64, true, false);
             } else {
-                sendEvent("message", bytes.utf8(), true);
+                sendEvent("message", bytes.utf8(), true, true);
             }
         } catch (Exception e) {
-            Log.e("WebSocketInstance", "Error sending message", e);
+            Log.e(TAG, "Error sending message", e);
         }
 
     }
 
     @Override
     public void onClosing(@NonNull WebSocket webSocket, int code, @NonNull String reason) {
         this.readyState = 2; // CLOSING
-        Log.i("WebSocketInstance", "websocket instanceId=" + this.instanceId + " is Closing code: " + code + " reason: " + reason);
+        Log.i(TAG, "websocket instanceId=" + this.instanceId + " is Closing code: " + code + " reason: " + reason);
     }
 
     @Override
     public void onClosed(@NonNull WebSocket webSocket, int code, @NonNull String reason) {
         this.readyState = 3; // CLOSED
-        Log.i("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Closed code: " + code + " reason: " + reason);
+        Log.i(TAG, "websocket instanceId=" + this.instanceId + " Closed code: " + code + " reason: " + reason);
         JSONObject closedEvent = new JSONObject();
         try {
             closedEvent.put("code", code);
             closedEvent.put("reason", reason);
         } catch (JSONException e) {
-            Log.e("WebSocketInstance", "Error creating close event", e);
+            Log.e(TAG, "Error creating close event", e);
         }
-        sendEvent("close", closedEvent.toString(), false);
+        sendEvent("close", closedEvent.toString(), false, false);
     }
 
     @Override
     public void onFailure(@NonNull WebSocket webSocket, Throwable t, Response response) {
         this.readyState = 3; // CLOSED
-        sendEvent("error", t.getMessage(), false);
-        Log.e("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Error: " + t.getMessage());
+        sendEvent("error", t.getMessage(), false, false);
+        Log.e(TAG, "websocket instanceId=" + this.instanceId + " Error: " + t.getMessage());
+    }
+
+    public void setBinaryType(String binaryType) {
+        this.binaryType = binaryType;
     }
 
-    private void sendEvent(String type, String data, boolean isBinary) {
+    private void sendEvent(String type, String data, boolean isBinary, boolean parseAsText) {
         if (callbackContext != null) {
             try {
                 JSONObject event = new JSONObject();
                 event.put("type", type);
                 event.put("extensions", this.extensions);
                 event.put("readyState", this.readyState);
-                event.put("isBinary", isBinary ? true : false);
+                event.put("isBinary", isBinary);
+                event.put("parseAsText", parseAsText);
                 if (data != null) event.put("data", data);
-                Log.d("WebSocketInstance", "sending event: " + type + " eventObj " + event.toString());
+                Log.d(TAG, "sending event: " + type + " eventObj " + event.toString());
                 PluginResult result = new PluginResult(PluginResult.Status.OK, event);
                 result.setKeepCallback(true);
                 callbackContext.sendPluginResult(result);
             } catch (Exception e) {
-                Log.e("WebSocketInstance", "Error sending event", e);
+                Log.e(TAG, "Error sending event", e);
             }
         }
     }