feat: enhance WebSocket plugin with custom headers and improved close functionality

- Updated `WebSocketPlugin.connect` to accept custom headers.
- Enhanced `WebSocketInstance.close` method to allow specifying close code and reason.
- Added `WebSocketPlugin.listClients` method to list active WebSocket instances.
- Updated JavaScript interface to support new features and improved documentation.

Author: UnschooledGamer

src/plugins/websocket/README.md

@@ -8,7 +8,9 @@ It aims to mimic the [WebSocket API](https://developer.mozilla.org/en-US/docs/We
 * ✅ WebSocket API-like interface
 * ✅ Event support: `onopen`, `onmessage`, `onerror`, `onclose`
 * ✅ `extensions` and `readyState` properties
+* ✅ `listClients()` to list active connections
 * ✅ Support for protocols
+* ✅ Support for Custom Headers.
 * ✅ Compatible with Cordova for Android
 
 ---
@@ -24,7 +26,7 @@ const WebSocketPlugin = cordova.websocket;
 ### Connect to WebSocket
 
 ```javascript
-WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"])
+WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"], headers)
   .then(ws => {
     ws.onopen = (e) => console.log("Connected!", e);
     ws.onmessage = (e) => console.log("Message:", e.data);
@@ -43,21 +45,35 @@ WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"])
 
 ### Methods
 
-* `WebSocketPlugin.connect(url, protocols)`
+* `WebSocketPlugin.connect(url, protocols, headers)`
 
     * Connects to a WebSocket server.
     * `url`: The WebSocket server URL.
     * `protocols`: (Optional) An array of subprotocol strings.
-    * Returns: A Promise that resolves to a `WebSocketInstance`.
+    * `headers` (object, optional): Custom headers as key-value pairs.
+    * **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.
+
+* `WebSocketPlugin.close(instanceId, code, reason)`
+    * same as `WebSocketInstance.close(code, reason)` but needs `instanceId`.
+    * **Returns:** `Promise` that resolves.
 
 * `WebSocketInstance.send(message)`
 
     * Sends a message to the server.
     * Throws an error if the connection is not open.
 
-* `WebSocketInstance.close()`
+* `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).
 
 ---
 
@@ -81,5 +97,5 @@ WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"])
 
 * Only supported on Android (via OkHttp).
 * Make sure to handle connection lifecycle properly (close sockets when done).
-
+* `listClients()` is useful for debugging and management.
 ---

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

@@ -8,27 +8,44 @@
 import org.json.JSONArray;
 import org.json.JSONObject;
 
+import java.util.Iterator;
 import java.util.concurrent.TimeUnit;
 
 import okhttp3.*;
 
 public class WebSocketInstance extends WebSocketListener {
+    private static final int DEFAULT_CLOSE_CODE = 1000;
+    private static final String DEFAULT_CLOSE_REASON = "Normal closure";
+
     private WebSocket webSocket;
     private CallbackContext callbackContext;
-    private CordovaInterface cordova;
-    private String instanceId;
+    private final CordovaInterface cordova;
+    private final String instanceId;
     private String extensions = "";
     private int readyState = 0; // CONNECTING
 
-    public WebSocketInstance(String url, JSONArray protocols, CordovaInterface cordova, String instanceId) {
+    // okHttpMainClient parameter is used. To have a single main client(singleton), with per-websocket configuration using newBuilder method.
+    public WebSocketInstance(String url, JSONArray protocols, JSONObject headers, OkHttpClient okHttpMainClient, CordovaInterface cordova, String instanceId) {
         this.cordova = cordova;
         this.instanceId = instanceId;
 
-        OkHttpClient client = new OkHttpClient.Builder()
+        OkHttpClient client = okHttpMainClient.newBuilder()
                 .connectTimeout(10, TimeUnit.SECONDS)
                 .build();
 
         Request.Builder requestBuilder = new Request.Builder().url(url);
+
+        // custom headers support.
+        if (headers != null) {
+            Iterator<String> keys = headers.keys();
+            while (keys.hasNext()) {
+                String key = keys.next();
+                String value = headers.optString(key);
+                requestBuilder.addHeader(key, value);
+            }
+        }
+
+        // adds Sec-WebSocket-Protocol header if protocols is present.
         if (protocols != null) {
             StringBuilder protocolHeader = new StringBuilder();
             for (int i = 0; i < protocols.length(); i++) {
@@ -56,16 +73,22 @@ public void send(String message) {
         }
     }
 
-    public void close() {
+    public void close(int code, String reason) {
         if (webSocket != null) {
             readyState = 2; // CLOSING
-            webSocket.close(1000, "Normal closure");
+            webSocket.close(code, reason);
             Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received close() action call");
         } else {
             Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received close() action call, ignoring... as webSocket is null (not present)");
         }
     }
 
+    public void close() {
+        Log.d("WebSocketInstance", "WebSocket instanceId=" + this.instanceId + " close() called with no arguments. Using defaults.");
+        // Calls the more specific version with default values
+        close(DEFAULT_CLOSE_CODE, DEFAULT_CLOSE_REASON);
+    }
+
     @Override
     public void onOpen(@NonNull WebSocket webSocket, Response response) {
         this.webSocket = webSocket;
@@ -76,26 +99,26 @@ public void onOpen(@NonNull WebSocket webSocket, Response response) {
     }
 
     @Override
-    public void onMessage(@NonNull WebSocket webSocket, String text) {
+    public void onMessage(@NonNull WebSocket webSocket, @NonNull String text) {
         sendEvent("message", text);
         Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId +  " Received message: " + text);
     }
 
     @Override
-    public void onClosing(WebSocket webSocket, int code, String reason) {
+    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);
     }
 
     @Override
-    public void onClosed(WebSocket webSocket, int code, String reason) {
+    public void onClosed(@NonNull WebSocket webSocket, int code, @NonNull String reason) {
         this.readyState = 3; // CLOSED
         sendEvent("close", reason);
         Log.i("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Closed code: " + code + " reason: " + reason);
     }
 
     @Override
-    public void onFailure(WebSocket webSocket, Throwable t, Response response) {
+    public void onFailure(@NonNull WebSocket webSocket, Throwable t, Response response) {
         this.readyState = 3; // CLOSED
         sendEvent("error", t.getMessage());
         Log.e("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Error: " + t.getMessage());

src/plugins/websocket/src/android/WebSocketPlugin.java

@@ -6,18 +6,27 @@
 import java.util.HashMap;
 import java.util.UUID;
 
-// @TODO: plugin init & plugin destroy(closing okhttp clients) lifecycles.
+import okhttp3.OkHttpClient;
+
+// TODO: plugin init & plugin destroy(closing okhttp clients) lifecycles. (✅)
 public class WebSocketPlugin extends CordovaPlugin {
     private static final HashMap<String, WebSocketInstance> instances = new HashMap<>();
+    public OkHttpClient okHttpMainClient = null;
+
+    @Override
+    protected void pluginInitialize() {
+        this.okHttpMainClient = new OkHttpClient();
+    }
 
     @Override
     public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {
         switch (action) {
             case "connect":
                 String url = args.optString(0);
                 JSONArray protocols = args.optJSONArray(1);
+                JSONObject headers = args.optJSONObject(2);
                 String id = UUID.randomUUID().toString();
-                WebSocketInstance instance = new WebSocketInstance(url, protocols, cordova, id);
+                WebSocketInstance instance = new WebSocketInstance(url, protocols, headers, this.okHttpMainClient, cordova, id);
                 instances.put(id, instance);
                 callbackContext.success(id);
                 return true;
@@ -36,9 +45,11 @@ public boolean execute(String action, JSONArray args, final CallbackContext call
 
             case "close":
                 instanceId = args.optString(0);
+                int code = args.optInt(1);
+                String reason = args.optString(2);
                 inst = instances.get(instanceId);
                 if (inst != null) {
-                    inst.close();
+                    inst.close(code, reason);
                     instances.remove(instanceId);
                     callbackContext.success();
                 } else {
@@ -56,8 +67,26 @@ public boolean execute(String action, JSONArray args, final CallbackContext call
                 }
                 return true;
 
+            case "listClients":
+                JSONArray clientIds = new JSONArray();
+                for (String clientId : instances.keySet()) {
+                    clientIds.put(clientId);
+                }
+                callbackContext.success(clientIds);
+                return true;
             default:
                 return false;
         }
     }
+
+    @Override
+    public void onDestroy() {
+        // clear all.
+        for (WebSocketInstance instance : instances.values()) {
+            // Closing them gracefully.
+            instance.close();
+        }
+        instances.clear();
+        okHttpMainClient.dispatcher().executorService().shutdown();
+    }
 }

src/plugins/websocket/www/websocket.js

@@ -34,9 +34,15 @@ class WebSocketInstance {
         }
     }
 
-    close() {
+    /**
+     * Closes the WebSocket connection.
+     *
+     * @param {number} code The status code explaining why the connection is being closed.
+     * @param {string} reason A human-readable string explaining why the connection is being closed.
+     */
+    close(code, reason) {
         this.readyState = WebSocketInstance.CLOSING;
-        exec(null, null, "WebSocketPlugin", "close", [this.instanceId]);
+        exec(null, null, "WebSocketPlugin", "close", [this.instanceId, code, reason]);
     }
 }
 
@@ -45,10 +51,39 @@ WebSocketInstance.OPEN = 1;
 WebSocketInstance.CLOSING = 2;
 WebSocketInstance.CLOSED = 3;
 
-const connect = function(url, protocols = null) {
+const connect = function(url, protocols = null, headers = null) {
     return new Promise((resolve, reject) => {
-        exec(instanceId => resolve(new WebSocketInstance(url, instanceId)), reject, "WebSocketPlugin", "connect", [url, protocols]);
+        exec(instanceId => resolve(new WebSocketInstance(url, instanceId)), reject, "WebSocketPlugin", "connect", [url, protocols, headers]);
     });
 };
 
-module.exports = { connect };
+const listClients = function() {
+    return new Promise((resolve, reject) => {
+        exec(resolve, reject, "WebSocketPlugin", "listClients", []);
+    });
+};
+
+/** Utility functions, in-case you lost the websocketInstance returned from the connect function */
+
+const send = function(instanceId, message) {
+    return new Promise((resolve, reject) => {
+        exec(resolve, reject, "WebSocketPlugin", "send", [instanceId, message]);
+    });
+};
+
+/**
+ * Closes the WebSocket connection.
+ *
+ * @param {string} instanceId The ID of the WebSocketInstance to close.
+ * @param {number} [code] (optional) The status code explaining why the connection is being closed.
+ * @param {string} [reason] (optional) A human-readable string explaining why the connection is being closed.
+ *
+ * @returns {Promise} A promise that resolves when the close operation has completed.
+ */
+const close = function(instanceId, code, reason) {
+    return new Promise((resolve, reject) => {
+        exec(resolve, reject, "WebSocketPlugin", "close", [instanceId, code, reason]);
+    });
+};
+
+module.exports = { connect, listClients, send, close };