feat: ✨ Native Websocket Plugin (uses okhttp)

package.json

@@ -35,7 +35,8 @@
       "cordova-plugin-system": {},
       "cordova-plugin-advanced-http": {
         "ANDROIDBLACKLISTSECURESOCKETPROTOCOLS": "SSLv3,TLSv1"
-      }
+      },
+      "cordova-plugin-websocket": {}
     },
     "platforms": [
       "android"
@@ -74,6 +75,7 @@
     "cordova-plugin-server": "file:src/plugins/server",
     "cordova-plugin-sftp": "file:src/plugins/sftp",
     "cordova-plugin-system": "file:src/plugins/system",
+    "cordova-plugin-websocket": "file:src/plugins/websocket",
     "css-loader": "^7.1.2",
     "mini-css-extract-plugin": "^2.9.0",
     "path-browserify": "^1.0.1",

src/plugins/websocket/README.md

@@ -0,0 +1,85 @@
+# Cordova Plugin: OkHttp WebSocket
+
+A Cordova plugin that uses [OkHttp](https://square.github.io/okhttp/) to provide WebSocket support in your Cordova app.
+It aims to mimic the [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) in JavaScript, with additional features.
+
+## Features
+
+* ✅ WebSocket API-like interface
+* ✅ Event support: `onopen`, `onmessage`, `onerror`, `onclose`
+* ✅ `extensions` and `readyState` properties
+* ✅ Support for protocols
+* ✅ Compatible with Cordova for Android
+
+---
+
+## Usage
+
+### Import
+
+```javascript
+const WebSocketPlugin = cordova.websocket;
+```
+
+### Connect to WebSocket
+
+```javascript
+WebSocketPlugin.connect("wss://example.com/socket", ["protocol1", "protocol2"])
+  .then(ws => {
+    ws.onopen = (e) => console.log("Connected!", e);
+    ws.onmessage = (e) => console.log("Message:", e.data);
+    ws.onerror = (e) => console.error("Error:", e);
+    ws.onclose = (e) => console.log("Closed:", e);
+
+    ws.send("Hello from Cordova!");
+    ws.close();
+  })
+  .catch(err => console.error("WebSocket connection failed:", err));
+```
+
+---
+
+## API Reference
+
+### Methods
+
+* `WebSocketPlugin.connect(url, protocols)`
+
+    * 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`.
+
+* `WebSocketInstance.send(message)`
+
+    * Sends a message to the server.
+    * Throws an error if the connection is not open.
+
+* `WebSocketInstance.close()`
+
+    * Closes the connection.
+
+---
+
+### Properties of `WebSocketInstance`
+
+* `onopen`: Event listener for connection open.
+* `onmessage`: Event listener for messages received.
+* `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).
+
+---
+
+## Notes
+
+* Only supported on Android (via OkHttp).
+* Make sure to handle connection lifecycle properly (close sockets when done).
+
+---

src/plugins/websocket/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "cordova-plugin-websocket",
+  "version": "0.0.1",
+  "description": "This cordova plugin is created to use WebSocket (client) in web/js.",
+  "cordova": {
+    "id": "cordova-plugin-websocket",
+    "platforms": [
+      "android"
+    ]
+  },
+  "keywords": [
+    "cordova",
+    "websocket",
+    "cordova-android",
+    "ws"
+  ],
+  "author": "Acode-Foundation (created by UnschooledGamer)",
+  "license": "Apache-2.0",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

src/plugins/websocket/plugin.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin id="cordova-plugin-websocket" version="0.0.1" xmlns="http://apache.org/cordova/ns/plugins/1.0">
+    <name>cordova-plugin-websocket</name>
+    <description>Cordova Websocket</description>
+    <license>MIT</license>
+    <keywords>cordova,ws,WebSocket</keywords>
+    <js-module src="www/websocket.js" name="WebSocket">
+        <clobbers target="cordova.websocket" />
+    </js-module>
+
+    <platform name="android">
+        <config-file target="res/xml/config.xml" parent="/*">
+            <feature name="WebSocketPlugin">
+                <param name="android-package" value="com.foxdebug.websocket.WebSocketPlugin" />
+            </feature>
+        </config-file>
+        <source-file src="src/android/WebSocketPlugin.java" target-dir="src/com/foxdebug/websocket" />
+        <source-file src="src/android/WebSocketInstance.java" target-dir="src/com/foxdebug/websocket" />
+        <framework src="com.squareup.okhttp3:okhttp:4.12.0" />
+    </platform>
+</plugin>

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

@@ -0,0 +1,114 @@
+package com.foxdebug.websocket;
+
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+
+import org.apache.cordova.*;
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.util.concurrent.TimeUnit;
+
+import okhttp3.*;
+
+public class WebSocketInstance extends WebSocketListener {
+    private WebSocket webSocket;
+    private CallbackContext callbackContext;
+    private CordovaInterface cordova;
+    private String instanceId;
+    private String extensions = "";
+    private int readyState = 0; // CONNECTING
+
+    public WebSocketInstance(String url, JSONArray protocols, CordovaInterface cordova, String instanceId) {
+        this.cordova = cordova;
+        this.instanceId = instanceId;
+
+        OkHttpClient client = new OkHttpClient.Builder()
+                .connectTimeout(10, TimeUnit.SECONDS)
+                .build();
+
+        Request.Builder requestBuilder = new Request.Builder().url(url);
+        if (protocols != null) {
+            StringBuilder protocolHeader = new StringBuilder();
+            for (int i = 0; i < protocols.length(); i++) {
+                protocolHeader.append(protocols.optString(i)).append(",");
+            }
+            if (protocolHeader.length() > 0) {
+                protocolHeader.setLength(protocolHeader.length() - 1);
+                requestBuilder.addHeader("Sec-WebSocket-Protocol", protocolHeader.toString());
+            }
+        }
+
+        client.newWebSocket(requestBuilder.build(), this);
+    }
+
+    public void setCallback(CallbackContext callbackContext) {
+        this.callbackContext = callbackContext;
+        PluginResult result = new PluginResult(PluginResult.Status.NO_RESULT);
+        result.setKeepCallback(true);
+        callbackContext.sendPluginResult(result);
+    }
+
+    public void send(String message) {
+        if (webSocket != null) {
+            webSocket.send(message);
+        }
+    }
+
+    public void close() {
+        if (webSocket != null) {
+            readyState = 2; // CLOSING
+            webSocket.close(1000, "Normal closure");
+            Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received close() action call");
+        }
+
+        Log.d("WebSocketInstance", "websocket instanceId=" + this.instanceId + " received close() action call, ignoring... as webSocket is null (not present)");
+    }
+
+    @Override
+    public void onOpen(@NonNull WebSocket webSocket, Response response) {
+        this.webSocket = webSocket;
+        this.readyState = 1; // OPEN
+        this.extensions = response.headers("Sec-WebSocket-Extensions").toString();
+        Log.i("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Opened" + "received extensions=" + this.extensions);
+        sendEvent("open", null);
+    }
+
+    @Override
+    public void onMessage(@NonNull WebSocket webSocket, 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) {
+        this.readyState = 2; // CLOSING
+        sendEvent("close", reason);
+        Log.i("WebSocketInstance", "websocket instanceId=" + this.instanceId + " is Closing code: " + code + " reason: " + reason);
+    }
+
+    @Override
+    public void onFailure(WebSocket webSocket, Throwable t, Response response) {
+        this.readyState = 3; // CLOSED
+        sendEvent("error", t.getMessage());
+        Log.e("WebSocketInstance", "websocket instanceId=" + this.instanceId + " Error: " + t.getMessage());
+    }
+
+    private void sendEvent(String type, String data) {
+        if (callbackContext != null) {
+            try {
+                JSONObject event = new JSONObject();
+                event.put("type", type);
+                event.put("extensions", this.extensions);
+                event.put("readyState", this.readyState);
+                if (data != null) event.put("data", data);
+                PluginResult result = new PluginResult(PluginResult.Status.OK, event);
+                result.setKeepCallback(true);
+                callbackContext.sendPluginResult(result);
+            } catch (Exception e) {
+                Log.e("WebSocketInstance", "Error sending event", e);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,63 @@
+package com.foxdebug.websocket;
+
+import org.apache.cordova.*;
+import org.json.*;
+
+import java.util.HashMap;
+import java.util.UUID;
+
+// @TODO: plugin init & plugin destroy(closing okhttp clients) lifecycles.
+public class WebSocketPlugin extends CordovaPlugin {
+    private static final HashMap<String, WebSocketInstance> instances = new HashMap<>();
+
+    @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);
+                String id = UUID.randomUUID().toString();
+                WebSocketInstance instance = new WebSocketInstance(url, protocols, cordova, id);
+                instances.put(id, instance);
+                callbackContext.success(id);
+                return true;
+
+            case "send":
+                String instanceId = args.optString(0);
+                String message = args.optString(1);
+                WebSocketInstance inst = instances.get(instanceId);
+                if (inst != null) {
+                    inst.send(message);
+                    callbackContext.success();
+                } else {
+                    callbackContext.error("Invalid instance ID");
+                }
+                return true;
+
+            case "close":
+                instanceId = args.optString(0);
+                inst = instances.get(instanceId);
+                if (inst != null) {
+                    inst.close();
+                    instances.remove(instanceId);
+                    callbackContext.success();
+                } else {
+                    callbackContext.error("Invalid instance ID");
+                }
+                return true;
+
+            case "registerListener":
+                instanceId = args.optString(0);
+                inst = instances.get(instanceId);
+                if (inst != null) {
+                    inst.setCallback(callbackContext);
+                } else {
+                    callbackContext.error("Invalid instance ID");
+                }
+                return true;
+
+            default:
+                return false;
+        }
+    }
+}