@annadata/capacitor-mqtt-quic 0.1.5 → 0.1.7

package/AnnadataCapacitorMqttQuic.podspec

@@ -0,0 +1,36 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'AnnadataCapacitorMqttQuic'
+  s.version = package['version']
+  s.summary = 'MQTT-over-QUIC Capacitor plugin (iOS)'
+  s.license = package['license']
+  s.homepage = 'https://github.com/annadata/capacitor-mqtt-quic'
+  s.author = 'Yakub Mohammad'
+  s.authors = { 'Yakub Mohammad' => 'yakub@annadata.ai' }
+  s.source = { :git => 'https://github.com/annadata/capacitor-mqtt-quic', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.resources = ['ios/Sources/MqttQuicPlugin/Resources/*.pem']
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+  s.vendored_libraries = [
+    'ios/libs/libngtcp2.a',
+    'ios/libs/libngtcp2_crypto_wolfssl.a',
+    'ios/libs/libnghttp3.a',
+    'ios/libs/libwolfssl.a'
+  ]
+  s.public_header_files = 'ios/Sources/**/*.h', 'ios/include/**/*.h'
+  s.private_header_files = 'ios/Sources/**/*.h', 'ios/include/**/*.h'
+  s.header_mappings_dir = 'ios/Sources'
+  s.pod_target_xcconfig = {
+    'HEADER_SEARCH_PATHS' => '$(PODS_TARGET_SRCROOT)/ios/include $(PODS_TARGET_SRCROOT)/ios/Sources/MqttQuicPlugin/QUIC',
+    'LIBRARY_SEARCH_PATHS' => '$(PODS_TARGET_SRCROOT)/ios/libs',
+    'OTHER_LDFLAGS' => '-lngtcp2 -lngtcp2_crypto_wolfssl -lnghttp3 -lwolfssl',
+    'SWIFT_ACTIVE_COMPILATION_CONDITIONS' => 'NGTCP2_ENABLED NGHTTP3_ENABLED',
+    'OTHER_CFLAGS' => '$(inherited) -fmodule-map-file=$(PODS_TARGET_SRCROOT)/ios/Sources/MqttQuicPlugin/QUIC/module.modulemap',
+    'OTHER_SWIFT_FLAGS' => '$(inherited) -Xcc -fmodule-map-file=$(PODS_TARGET_SRCROOT)/ios/Sources/MqttQuicPlugin/QUIC/module.modulemap'
+  }
+end

package/README.md

@@ -1,8 +1,8 @@
 # @annadata/capacitor-mqtt-quic
 
-MQTT-over-QUIC Capacitor plugin for iOS and Android. Uses ngtcp2 for QUIC on native; MQTT over WebSocket (WSS) fallback on web.
+MQTT-over-QUIC Capacitor plugin for **iOS**, **Android**, and **Web (browser/PWA)**. Native: ngtcp2 + WolfSSL for QUIC; Web: MQTT over WebSocket (WSS), same API and event listeners.
 
-**Capacitor:** Supports **Capacitor >= 7.0.0** (including Capacitor 8). See [CAPACITOR_VERSION_SUPPORT.md](./CAPACITOR_VERSION_SUPPORT.md) for details.
+**Capacitor:** Supports **Capacitor 7** and **Capacitor 8**.
 
 **Features:**
 - ✅ **MQTT 5.0** support with full properties and reason codes
@@ -330,7 +330,7 @@ interface MqttQuicTestHarnessOptions {
 
 ## ngtcp2 Build (Phase 2) ⏳
 
-**Current Status:** Real QUIC transport implemented using ngtcp2 + quictls (OpenSSL fork).
+**Current Status:** Real QUIC transport implemented using ngtcp2 + **WolfSSL** on both iOS and Android (single TLS backend for license/size/QUIC support).
 
 ### Quick Build (Recommended)
 
@@ -350,7 +350,7 @@ Use the unified build script to build all native dependencies:
 ./build-native.sh --android-only --abi arm64-v8a
 ```
 
-This script builds OpenSSL (quictls) → nghttp3 → ngtcp2 in the correct order for both platforms.
+This script builds WolfSSL → nghttp3 → ngtcp2 in the correct order for both platforms (or OpenSSL/QuicTLS when USE_WOLFSSL=0).
 
 ### Manual Build
 
@@ -363,6 +363,47 @@ For detailed manual build instructions, see:
 - iOS: macOS with Xcode 14+
 - Android: Android Studio with NDK r25+ (auto-detected from `$ANDROID_HOME`)
 
+## Production / First-time build
+
+When you install the plugin from npm (`npm install @annadata/capacitor-mqtt-quic`), the published package may include **prebuilt native libs** (iOS and optionally Android, both using **WolfSSL**). In that case you only need:
+
+```bash
+npm install @annadata/capacitor-mqtt-quic
+npx cap sync
+```
+
+**If your Android build fails with "WolfSSL not found"**, run this **one-time** setup from your app project root (requires Android NDK r25+). Both iOS and Android use **WolfSSL** as the TLS backend (license/size/QUIC support):
+
+```bash
+cd node_modules/@annadata/capacitor-mqtt-quic
+./build-native.sh --android-only --abi arm64-v8a
+./build-native.sh --android-only --abi armeabi-v7a
+./build-native.sh --android-only --abi x86_64
+```
+
+Or from the plugin’s `android` directory:
+
+```bash
+cd node_modules/@annadata/capacitor-mqtt-quic/android
+./build-wolfssl.sh --abi arm64-v8a
+./build-wolfssl.sh --abi armeabi-v7a
+./build-wolfssl.sh --abi x86_64
+./build-nghttp3.sh --abi arm64-v8a
+./build-nghttp3.sh --abi armeabi-v7a
+./build-nghttp3.sh --abi x86_64
+./build-ngtcp2.sh --abi arm64-v8a
+./build-ngtcp2.sh --abi armeabi-v7a
+./build-ngtcp2.sh --abi x86_64
+```
+
+Or add to your app’s `package.json` and run once:
+
+```json
+"setup:wolfssl-android": "cd node_modules/@annadata/capacitor-mqtt-quic && ./build-native.sh --android-only --abi arm64-v8a && ./build-native.sh --android-only --abi armeabi-v7a && ./build-native.sh --android-only --abi x86_64"
+```
+
+**iOS:** The plugin ships with vendored static libs (`ios/libs/`) using WolfSSL. If you built the plugin from source and those are missing, run from the plugin repo: `./build-native.sh --ios-only`, then pack/publish.
+
 ## Development
 
 ### Build Plugin
@@ -400,6 +441,10 @@ await MqttQuic.connect({
 });
 ```
 
+## Publishing (maintainers)
+
+To pack the plugin **with native libs** and publish to npm, follow **[PRODUCTION_PUBLISH_STEPS.md](./PRODUCTION_PUBLISH_STEPS.md)**.
+
 ## Documentation
 
 - [Implementation Summary](./IMPLEMENTATION_SUMMARY.md) - Complete project overview
@@ -407,22 +452,86 @@ await MqttQuic.connect({
 - [ngtcp2 Integration Plan](./NGTCP2_INTEGRATION_PLAN.md) - Build instructions for real QUIC
 - [MQTT Version Analysis](./MQTT_VERSION_ANALYSIS.md) - Why MQTT 5.0?
 
-## Web/PWA Support
+## Web / browser support
+
+The plugin runs in **browsers** (including PWA and `cap run web`) with the **same API** as iOS and Android.
+
+**Why web can’t use ngtcp2 + WolfSSL:** Browsers do not expose raw UDP or the TLS APIs ngtcp2/WolfSSL need. So the native stack cannot run in the browser. On web: (1) **Default:** MQTT over **WebSocket (WSS)** via `mqtt.js`. (2) **Optional:** MQTT over **WebTransport** (QUIC)—pass `webTransportUrl` in `connect()` when your server supports WebTransport; the browser uses its built-in HTTP/3/QUIC stack.
+
+- **Connect:** `ws://host:port` or `wss://host:port` (the plugin uses WSS when port is 8884 or 443, otherwise `ws`)
+- **Same methods:** `MqttQuic.connect`, `publish`, `subscribe`, `unsubscribe`, `disconnect`, `testHarness`
 
-On **web** (including PWA), the plugin uses **MQTT over WebSocket (WSS)** via `mqtt.js`. No QUIC; same API.
+**My MQTT+QUIC server is on port 1884 – can WSS connect?**  
+Port **1884** is usually **MQTT over QUIC** (UDP). A **WSS client cannot connect directly to 1884**, because WSS is TCP/WebSocket and 1884 is QUIC. You need one of:
 
-- **Connect:** `ws://host:port` or `wss://host:port` (wss when port is 8884 or 443)
-- **Build:** Ensure `mqtt` is installed (`npm install` in the plugin directory)
-- Use `MqttQuic.connect` / `publish` / `subscribe` / `unsubscribe` / `disconnect` as on native
+1. **Server also exposes MQTT over WebSocket**  
+   Many brokers listen on two ports: e.g. **1884** for MQTT-over-QUIC and **8884** (or 8084) for MQTT-over-WebSocket Secure. From the **web** plugin, connect to the **WebSocket port** (e.g. 8884), not 1884:
+   ```ts
+   await MqttQuic.connect({ host: 'your-server.com', port: 8884, clientId: 'web-client' });
+   ```
+   The plugin will use `wss://your-server.com:8884`.
+
+2. **Proxy/gateway**  
+   Run a gateway that listens for WSS (e.g. on 8884) and forwards MQTT to your QUIC server on 1884. The web client then connects to the gateway’s WSS port.
+
+3. **Native or WebTransport**  
+   On **iOS/Android** use the same host and **port 1884** (QUIC). On **web**, if the server supports **WebTransport**, use `webTransportUrl` (see example below) so the browser uses QUIC via WebTransport.
+- **Same events:** `MqttQuic.addListener('connected', ...)`, `addListener('subscribed', ...)`, `addListener('message', (e) => { e.topic, e.payload })`
+- **Build:** The plugin bundles `mqtt`; no extra install in the app.
+
+Example in a browser or PWA:
+
+```ts
+import { MqttQuic } from '@annadata/capacitor-mqtt-quic';
+
+MqttQuic.addListener('message', (e) => console.log(e.topic, e.payload));
+await MqttQuic.connect({ host: 'broker.example.com', port: 8884, clientId: 'web-client' });
+await MqttQuic.subscribe({ topic: 'sensors/#' });
+```
+
+Example with QUIC on web (WebTransport; server must support WebTransport and MQTT over it):
+
+```ts
+await MqttQuic.connect({
+  webTransportUrl: 'https://broker.example.com:443/mqtt-wt',
+  clientId: 'web-quic-client',
+  host: 'broker.example.com',
+  port: 443,
+});
+```
+
+When the server uses path-based routing (like MQTT topics), data is at `.../devices/<deviceId>/<action>/<Path>`. You can pass the base URL and path components; the plugin builds the full URL:
+
+```ts
+await MqttQuic.connect({
+  webTransportUrl: 'https://mqtt.annadata.cloud:443/mqtt-wt',
+  webTransportDeviceId: 'mydevice',
+  webTransportAction: 'subscribe',   // or 'publish', etc.
+  webTransportPath: 'sensors/temp',   // optional; like MQTT topic suffix
+  clientId: 'web-client',
+  host: 'mqtt.annadata.cloud',
+  port: 443,
+});
+// Connects to: https://mqtt.annadata.cloud:443/mqtt-wt/devices/mydevice/subscribe/sensors/temp
+```
 
 ## Compatibility
 
+- **Platforms:** **iOS**, **Android**, **Web (browser / PWA)**
 - **MQTT Protocol:** 3.1.1 and 5.0 (auto-negotiation)
-- **iOS:** 15.0+ (for Network framework)
+- **iOS:** 15.0+
 - **Android:** API 21+ (Android 5.0+)
-- **Web/PWA:** mqtt.js over WSS
+- **Web:** Any modern browser; MQTT over WSS
 - **Capacitor:** 7.0+
-- **QUIC:** ngtcp2 1.21.0+ (when integrated)
+- **QUIC:** ngtcp2 + WolfSSL on native; on web, optional WebTransport (browser's HTTP/3/QUIC) when server supports it
+
+## Author
+
+**Yakub Mohammad**
+
+- yakub@annadata.ai
+- yakub@arusatech.com
+- yakub@arusallc.com
 
 ## License
 

package/android/NGTCP2_BUILD_INSTRUCTIONS.md

@@ -1,6 +1,6 @@
 # Building ngtcp2 for Android
 
-This document provides instructions for building ngtcp2 and OpenSSL for Android to enable real QUIC transport in the MQTT client.
+This document provides instructions for building ngtcp2 and WolfSSL (wolfssl-android) for Android to enable real QUIC transport in the MQTT client. The plugin uses WolfSSL by default; optional QuicTLS/OpenSSL build paths are also documented.
 
 ## Prerequisites
 
@@ -17,29 +17,53 @@ omit `--ndk-path` if your NDK is installed in one of those locations.
 Build scripts then expect dependencies under:
 - `$PROJECT_DIR/ref-code/ngtcp2`
 - `$PROJECT_DIR/ref-code/nghttp3`
-- `$PROJECT_DIR/ref-code/openssl`
+- `$PROJECT_DIR/ref-code/wolfssl` (default) or `$PROJECT_DIR/ref-code/openssl` (optional QuicTLS)
 
 ```bash
-export PROJECT_DIR="/Users/annadata/Project_A/annadata-production/ref-code/capacitor-mqtt-quic"
+export PROJECT_DIR="/path/to/capacitor-mqtt-quic"
 ```
 
-Override with `NGTCP2_SOURCE_DIR`, `NGHTTP3_SOURCE_DIR`, `OPENSSL_SOURCE_DIR`
-if you store sources elsewhere.
+Override with `NGTCP2_SOURCE_DIR`, `NGHTTP3_SOURCE_DIR`, `WOLFSSL_SOURCE_DIR` (or `OPENSSL_SOURCE_DIR` for QuicTLS) if you store sources elsewhere.
 
 ## Quick Start
 
 ### Option 1: Use Pre-built Libraries (Recommended for Development)
 
-If you have access to pre-built ngtcp2, nghttp3, and OpenSSL libraries:
+If you have access to pre-built ngtcp2, nghttp3, and WolfSSL libraries:
 
-1. Place `libngtcp2_client.so` in `android/src/main/jniLibs/<abi>/`
-2. Place `libnghttp3.a` in `android/libs/<abi>/`
-3. Place OpenSSL libraries (`libssl.a`, `libcrypto.a`) in `android/libs/<abi>/`
-4. Update `build.gradle` and `CMakeLists.txt` to link against these libraries
+1. Place ngtcp2/nghttp3 static libs in `android/install/ngtcp2-android/<abi>/` and `android/install/nghttp3-android/<abi>/`
+2. Place WolfSSL (`libwolfssl.a`) in `android/install/wolfssl-android/<abi>/`
+3. Update `CMakeLists.txt` to point at `android/install/` (plugin expects wolfssl-android by default)
 
-### Option 2: Build from Source
+### Option 2: Build from Source (WolfSSL – default)
 
-#### Step 1: Build OpenSSL for Android (QUIC TLS)
+From the **plugin repo root** (not `android/`), run:
+
+```bash
+./build-native.sh --android-only --abi arm64-v8a
+./build-native.sh --android-only --abi armeabi-v7a
+./build-native.sh --android-only --abi x86_64
+```
+
+This builds WolfSSL → nghttp3 → ngtcp2 and installs to:
+- `android/install/wolfssl-android/<abi>/`
+- `android/install/nghttp3-android/<abi>/`
+- `android/install/ngtcp2-android/<abi>/`
+
+**Or** from `android/` use the individual scripts:
+
+```bash
+cd android
+./build-wolfssl.sh --ndk-path ~/Android/Sdk/ndk/25.2.9519653 --platform android-21 --abi arm64-v8a
+./build-nghttp3.sh --ndk-path ~/Android/Sdk/ndk/25.2.9519653 --platform android-21 --abi arm64-v8a
+./build-ngtcp2.sh --abi arm64-v8a --platform android-21
+```
+
+Repeat for `armeabi-v7a` and `x86_64` as needed.
+
+### Option 3: Build from Source (QuicTLS/OpenSSL – optional)
+
+If you need OpenSSL/QuicTLS instead of WolfSSL:
 
 ```bash
 cd android
@@ -52,23 +76,9 @@ cd android
 
 This will:
 - Clone QuicTLS (https://github.com/quictls/quictls) if not present (OpenSSL fork with QUIC API)
-- Build static libraries for Android
 - Install to `android/install/openssl-android/<abi>/`
 
-**Note:** For different ABIs, repeat the build:
-```bash
-# arm64-v8a (64-bit ARM)
-./build-openssl.sh --ndk-path ~/Android/Sdk/ndk/25.2.9519653 --platform android-21 --abi arm64-v8a --quictls
-# ./build-openssl.sh --ndk-path "/Users/annadata/Library/Android/sdk/ndk/29.0.13113456" --abi arm64-v8a --platform android-21 --quictls
-
-# armeabi-v7a (32-bit ARM)
-./build-openssl.sh --ndk-path ~/Android/Sdk/ndk/25.2.9519653 --platform android-21 --abi armeabi-v7a --quictls
-# ./build-openssl.sh --ndk-path "/Users/annadata/Library/Android/sdk/ndk/29.0.13113456" --abi armeabi-v7a --platform android-21 --quictls
-
-# x86_64 (64-bit x86)
-./build-openssl.sh --ndk-path ~/Android/Sdk/ndk/25.2.9519653 --platform android-21 --abi x86_64 --quictls
-# ./build-openssl.sh --ndk-path "/Users/annadata/Library/Android/sdk/ndk/29.0.13113456" --abi x86_64 --platform android-21 --quictls
-```
+**Note:** The plugin’s CMake is configured for **WolfSSL** by default. Use Option 2 for the standard plugin build.
 
 #### Step 2: Build nghttp3 for Android
 
@@ -86,7 +96,7 @@ This will:
 
 - ./build-nghttp3.sh --abi arm64-v8a --platform android-21
 
-#### Step 3: Build ngtcp2 for Android
+#### Step 3: Build ngtcp2 for Android (WolfSSL – default)
 
 ```bash
 cd android
@@ -94,15 +104,16 @@ cd android
   --ndk-path ~/Library/Android/sdk/ndk/<ndk-version> \
   --abi arm64-v8a \
   --platform android-21 \
-  --openssl-path ./install/openssl-android/arm64-v8a \
-  --quictls
+  --wolfssl-path ./install/wolfssl-android/arm64-v8a
 ```
 
 This will:
-- Build ngtcp2 static library
-- Link against OpenSSL
+- Build ngtcp2 static library with WolfSSL crypto
 - Install to `android/install/ngtcp2-android/<abi>/`
-./build-ngtcp2.sh --abi arm64-v8a --platform android-21 --openssl-path ./install/openssl-android --quictls
+
+Example: `./build-ngtcp2.sh --abi arm64-v8a --platform android-21 --wolfssl-path ./install/wolfssl-android/arm64-v8a`
+
+If using QuicTLS/OpenSSL instead: `./build-ngtcp2.sh --abi arm64-v8a --platform android-21 --openssl-path ./install/openssl-android --quictls`
 
 #### Step 4: Build JNI Library
 
@@ -160,13 +171,13 @@ android {
 
 ### Update CMakeLists.txt
 
-Ensure `CMakeLists.txt` points to correct ngtcp2 and OpenSSL paths:
+Ensure `CMakeLists.txt` points to correct ngtcp2 and WolfSSL paths (plugin default):
 
 ```cmake
-# Set paths
-set(NGTCP2_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../ngtcp2")
-set(NGHTTP3_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../nghttp3")
-set(OPENSSL_ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../install/openssl-android")
+# Set paths (WolfSSL default)
+set(NGTCP2_INSTALL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../install/ngtcp2-android/${ANDROID_ABI}")
+set(NGHTTP3_INSTALL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../install/nghttp3-android/${ANDROID_ABI}")
+set(WOLFSSL_INSTALL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../install/wolfssl-android/${ANDROID_ABI}")
 ```
 
 ## TLS Certificate Verification (QUIC)
@@ -251,9 +262,13 @@ await MqttQuic.testHarness({
 
 ## Using Pre-built Libraries
 
-### OpenSSL
+### WolfSSL (default)
+
+Build using `./build-wolfssl.sh` or `./build-native.sh --android-only` (see Option 2 above). Pre-built WolfSSL for Android can also be obtained from the wolfSSL project.
+
+### OpenSSL / QuicTLS (optional)
 
-Download from:
+If building with QuicTLS instead of WolfSSL, download from:
 - https://github.com/leenjewel/openssl_for_ios_and_android
 
 ### ngtcp2
@@ -284,7 +299,13 @@ git clone --recurse-submodules https://github.com/ngtcp2/nghttp3.git
 # Or download from: https://cmake.org/download/
 ```
 
-### OpenSSL Build Fails
+### WolfSSL Build Fails
+
+- Ensure WolfSSL is built for the correct ABI (arm64-v8a, armeabi-v7a, x86_64)
+- Check that NDK path is correct
+- Run `./build-wolfssl.sh` from `android/` or `./build-native.sh --android-only` from plugin root
+
+### OpenSSL/QuicTLS Build Fails (optional path)
 
 - Ensure you're using OpenSSL 3.0+ (required for TLS 1.3)
 - Check that NDK path is correct
@@ -292,15 +313,15 @@ git clone --recurse-submodules https://github.com/ngtcp2/nghttp3.git
 
 ### ngtcp2 Build Fails
 
-- Verify OpenSSL is built and path is correct
+- Verify WolfSSL (or OpenSSL) is built and path is correct (`--wolfssl-path` or `--openssl-path`)
 - Check CMake version: `cmake --version` (must be 3.20+)
 - Ensure Android platform matches (android-21+)
 
 ### Link Errors
 
 - Verify all libraries are built for the same ABI
-- Check that CMakeLists.txt paths are correct
-- Ensure OpenSSL and ngtcp2 are linked in the correct order
+- Check that CMakeLists.txt paths are correct (wolfssl-android for default)
+- Ensure WolfSSL/ngtcp2 and nghttp3 are linked in the correct order
 
 ### JNI Errors
 

package/android/build-openssl.sh

@@ -26,7 +26,7 @@ DEPS_DIR="${PROJECT_DIR}/deps"
 DEFAULT_OPENSSL_SOURCE_DIR="${DEPS_DIR}/openssl"
 OPENSSL_VERSION="${OPENSSL_VERSION:-3.2.0}"
 USE_QUICTLS="${USE_QUICTLS:-1}"
-QUICTLS_BRANCH="${QUICTLS_BRANCH:-main}"
+QUICTLS_BRANCH="${QUICTLS_BRANCH:-openssl-3.2}"
 ANDROID_NDK="${ANDROID_NDK:-}"
 ANDROID_ABI="${ANDROID_ABI:-arm64-v8a}"
 ANDROID_PLATFORM="${ANDROID_PLATFORM:-android-21}"