@annadata/capacitor-mqtt-quic 0.1.6 → 0.1.7

package/docs/ARCHITECTURAL_ANALYSIS.md

@@ -0,0 +1,710 @@
+# Architectural Analysis: capacitor-mqtt-quic
+## Senior Architect Review - iOS, Android & Web (PWA) Support
+
+**Date:** 2025-01-24  
+**Reviewer:** Senior Architect  
+**Scope:** Complete line-by-line analysis for production readiness, segfault prevention, and cross-platform support
+
+---
+
+## Executive Summary
+
+**Current Status:** ✅ MQTT protocol layer complete, ⚠️ Critical issues identified, ❌ Web/PWA not implemented
+
+**Critical Issues Found:**
+1. **Memory Management:** Race conditions, potential use-after-free, missing cleanup
+2. **Thread Safety:** Unsafe concurrent access to shared state
+3. **Resource Leaks:** Streams, tasks, and connections not properly cleaned up
+4. **Error Handling:** Incomplete error recovery, missing null checks
+5. **Web Support:** Completely unimplemented (returns false for all operations)
+6. **State Management:** Race conditions between state transitions
+
+**Risk Level:** 🔴 **HIGH** - Current implementation has multiple segfault/crash risks
+
+---
+
+## 1. Critical Memory Management Issues
+
+### 1.1 iOS: MQTTClient.swift
+
+#### Issue: Race Condition in State Management
+**Location:** `MQTTClient.swift:26-36, 48-147`
+
+**Problem:**
+```swift
+private var state: State = .disconnected
+private var quicClient: QuicClientProtocol?
+private var stream: QuicStreamProtocol?
+private var reader: MQTTStreamReaderProtocol?
+private var writer: MQTTStreamWriterProtocol?
+private var messageLoopTask: Task<Void, Error>?
+```
+
+**Issues:**
+1. **State accessed without lock in `getState()`** - but other methods check state without lock
+2. **Partial lock coverage** - `connect()` locks state but not all related fields
+3. **Message loop task cancellation** - Task may outlive client instance
+4. **Reader/Writer accessed after nil assignment** - `disconnect()` sets to nil but may still be in use
+
+**Segfault Risk:** 🔴 **HIGH**
+- If `messageLoopTask` accesses `reader` after `disconnect()` sets it to nil
+- If `publish()`/`subscribe()` access `writer` after it's been deallocated
+
+**Fix Required:**
+```swift
+// All state access must be locked
+private func getState() -> State {
+    lock.lock()
+    defer { lock.unlock() }
+    return state
+}
+
+// Ensure messageLoopTask is cancelled and awaited before cleanup
+public func disconnect() async throws {
+    messageLoopTask?.cancel()
+    try? await messageLoopTask?.value  // Wait for cancellation
+    messageLoopTask = nil
+    
+    lock.lock()
+    let w = writer
+    let version = activeProtocolVersion
+    // Clear all references
+    quicClient = nil
+    stream = nil
+    reader = nil
+    writer = nil
+    state = .disconnected
+    activeProtocolVersion = 0
+    lock.unlock()
+    
+    // Use writer after unlock
+    if let w = w {
+        // ... send disconnect packet
+    }
+}
+```
+
+#### Issue: Use-After-Free in Message Loop
+**Location:** `MQTTClient.swift:268-315`
+
+**Problem:**
+```swift
+private func startMessageLoop() {
+    messageLoopTask = Task {
+        guard let r = reader else { return }  // ⚠️ Captured weakly?
+        while !Task.isCancelled {
+            // Uses r, but reader may be set to nil in disconnect()
+        }
+    }
+}
+```
+
+**Segfault Risk:** 🔴 **HIGH**
+- `reader` is captured by value, but may be deallocated while task is running
+- Task continues after `disconnect()` sets `reader = nil`
+
+**Fix Required:**
+```swift
+private func startMessageLoop() {
+    messageLoopTask = Task { [weak self] in  // Weak capture
+        guard let self = self else { return }
+        while !Task.isCancelled {
+            let r: MQTTStreamReaderProtocol?
+            self.lock.lock()
+            r = self.reader
+            self.lock.unlock()
+            
+            guard let r = r else { break }  // Exit if reader is nil
+            
+            // Use r safely
+            do {
+                let fixed = try await r.readexactly(2)
+                // ...
+            } catch {
+                if Task.isCancelled { break }
+                // Handle error
+            }
+        }
+    }
+}
+```
+
+#### Issue: Packet ID Overflow
+**Location:** `MQTTClient.swift:261-266`
+
+**Problem:**
+```swift
+private func nextPacketIdUsed() -> UInt16 {
+    let pid = nextPacketId
+    nextPacketId = nextPacketId &+ 1  // ⚠️ Unsafe overflow
+    if nextPacketId == 0 { nextPacketId = 1 }
+    return pid
+}
+```
+
+**Issue:** Not thread-safe. Multiple concurrent publishes/subscribes can generate duplicate packet IDs.
+
+**Fix Required:**
+```swift
+private func nextPacketIdUsed() -> UInt16 {
+    lock.lock()
+    defer { lock.unlock() }
+    let pid = nextPacketId
+    nextPacketId = nextPacketId &+ 1
+    if nextPacketId == 0 { nextPacketId = 1 }
+    return pid
+}
+```
+
+### 1.2 Android: MQTTClient.kt
+
+#### Issue: Coroutine Scope Leak
+**Location:** `MQTTClient.kt:51`
+
+**Problem:**
+```kotlin
+private val scope = CoroutineScope(Dispatchers.Default)
+```
+
+**Issue:** Scope is never cancelled. If `MQTTClient` is deallocated, coroutines continue running.
+
+**Fix Required:**
+```kotlin
+private val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
+
+suspend fun disconnect() {
+    messageLoopJob?.cancel()
+    messageLoopJob?.join()  // Wait for cancellation
+    messageLoopJob = null
+    
+    // Cancel scope when client is destroyed
+    scope.cancel()
+    // ...
+}
+```
+
+#### Issue: Race Condition in Message Loop
+**Location:** `MQTTClient.kt:270-313`
+
+**Problem:**
+```kotlin
+private fun startMessageLoop() {
+    messageLoopJob = scope.launch {
+        val r = lock.withLock { reader } ?: return@launch
+        while (isActive) {
+            // Uses r, but reader may be set to null in disconnect()
+        }
+    }
+}
+```
+
+**Segfault Risk:** 🟡 **MEDIUM**
+- Reader captured once, but may become null during loop
+- Should re-check reader on each iteration
+
+**Fix Required:**
+```kotlin
+private fun startMessageLoop() {
+    messageLoopJob = scope.launch {
+        while (isActive) {
+            val r = lock.withLock { reader } ?: break  // Re-check each iteration
+            
+            try {
+                val fixed = r.readexactly(2)
+                // ...
+            } catch (e: Exception) {
+                if (!isActive) break
+                // Handle error
+            }
+        }
+    }
+}
+```
+
+#### Issue: Blocking Call in onMessage
+**Location:** `MQTTClient.kt:255-261`
+
+**Problem:**
+```kotlin
+fun onMessage(topic: String, callback: (ByteArray) -> Unit) {
+    kotlinx.coroutines.runBlocking {  // ⚠️ Blocks thread
+        lock.withLock {
+            subscribedTopics[topic] = callback
+        }
+    }
+}
+```
+
+**Issue:** `runBlocking` blocks the calling thread. Should be suspend or use non-blocking lock.
+
+**Fix Required:**
+```kotlin
+suspend fun onMessage(topic: String, callback: (ByteArray) -> Unit) {
+    lock.withLock {
+        subscribedTopics[topic] = callback
+    }
+}
+```
+
+### 1.3 Plugin Bridge Issues
+
+#### iOS: MqttQuicPlugin.swift
+
+**Issue:** Client Recreated on Every Connect
+**Location:** `MqttQuicPlugin.swift:14, 36`
+
+**Problem:**
+```swift
+private var client = MQTTClient(protocolVersion: .auto)
+
+// In connect():
+client = MQTTClient(protocolVersion: protocolVersion)  // ⚠️ Old client not cleaned up
+```
+
+**Issue:** Previous client instance is not disconnected/cleaned up before creating new one.
+
+**Fix Required:**
+```swift
+@objc func connect(_ call: CAPPluginCall) {
+    // ... validation ...
+    
+    Task {
+        do {
+            // Clean up existing client
+            if case .connected = client.getState() {
+                try? await client.disconnect()
+            }
+            
+            // Create new client
+            let newClient = MQTTClient(protocolVersion: protocolVersion)
+            // ... connect logic ...
+            client = newClient
+        } catch {
+            call.reject("\(error)")
+        }
+    }
+}
+```
+
+**Issue:** Missing Error Handling for UInt8Array Payload
+**Location:** `MqttQuicPlugin.swift:73-104`
+
+**Problem:**
+```swift
+let payload = call.getString("payload") ?? ""  // ⚠️ Only handles string
+let data = Data(payload.utf8)
+```
+
+**Issue:** TypeScript interface allows `string | Uint8Array`, but plugin only handles string.
+
+**Fix Required:**
+```swift
+let payload: Data
+if let payloadStr = call.getString("payload") {
+    payload = Data(payloadStr.utf8)
+} else if let payloadArray = call.getArray("payload") as? [UInt8] {
+    payload = Data(payloadArray)
+} else {
+    call.reject("payload must be string or Uint8Array")
+    return
+}
+```
+
+#### Android: MqttQuicPlugin.kt
+
+**Same Issues as iOS:**
+- Client recreated without cleanup
+- Payload only handles string, not ByteArray
+- Missing validation
+
+---
+
+## 2. Thread Safety Issues
+
+### 2.1 iOS: NSLock Usage
+
+**Issues:**
+1. **Inconsistent locking** - Some methods lock, others don't
+2. **Lock ordering** - Potential deadlock if multiple locks acquired
+3. **Lock held too long** - Lock held during async operations
+
+**Recommendations:**
+- Use `actor` for Swift 5.5+ (better than NSLock)
+- Or ensure all state access is consistently locked
+- Never hold lock during `await` calls
+
+### 2.2 Android: Mutex Usage
+
+**Issues:**
+1. **`runBlocking` in `onMessage`** - Blocks thread
+2. **Lock held during suspend** - Mutex.withLock should not hold during suspend operations
+
+**Recommendations:**
+- Use `Mutex` correctly (it's suspend-aware)
+- Remove `runBlocking` from `onMessage`
+- Consider using `Flow` or `Channel` for message callbacks
+
+---
+
+## 3. Resource Leak Issues
+
+### 3.1 Stream Cleanup
+
+**Issue:** Streams not properly closed on error paths
+
+**Fix Required:**
+```swift
+// iOS
+public func connect(...) async throws {
+    var stream: QuicStreamProtocol?
+    do {
+        stream = try await quic.openStream()
+        // ... use stream ...
+    } catch {
+        try? await stream?.close()  // Cleanup on error
+        throw error
+    }
+}
+```
+
+### 3.2 Task Cleanup
+
+**Issue:** Tasks not properly awaited before deallocation
+
+**Fix Required:**
+```swift
+// iOS
+deinit {
+    messageLoopTask?.cancel()
+    // Note: Can't await in deinit, but can set flag
+}
+```
+
+---
+
+## 4. Error Handling Gaps
+
+### 4.1 Network Errors
+
+**Missing:**
+- Timeout handling
+- Connection retry logic
+- Network reachability checks
+- TLS handshake errors
+
+### 4.2 Protocol Errors
+
+**Missing:**
+- Malformed packet handling
+- Invalid reason code handling
+- Packet size limits
+- Keepalive timeout
+
+### 4.3 State Machine Errors
+
+**Missing:**
+- Operations on disconnected client
+- Concurrent connect attempts
+- Disconnect during operation
+
+---
+
+## 5. Web/PWA Support - CRITICAL GAP
+
+### 5.1 Current State
+
+**Location:** `src/web.ts`
+
+**Problem:**
+```typescript
+export class MqttQuicWeb {
+  async connect(_options: MqttQuicConnectOptions): Promise<{ connected: boolean }> {
+    return { connected: false };  // ⚠️ Always fails
+  }
+  // All methods return false/empty
+}
+```
+
+**Impact:** ❌ **Web/PWA completely non-functional**
+
+### 5.2 Required Implementation
+
+**Solution:** Use `mqtt.js` or `paho-mqtt` for WebSocket fallback
+
+**Implementation Plan:**
+```typescript
+// src/web.ts
+import mqtt from 'mqtt';
+
+export class MqttQuicWeb {
+  private client: mqtt.MqttClient | null = null;
+  private subscriptions: Map<string, mqtt.ClientSubscribeCallback> = new Map();
+
+  async connect(options: MqttQuicConnectOptions): Promise<{ connected: boolean }> {
+    return new Promise((resolve, reject) => {
+      const url = `wss://${options.host}:${options.port || 8884}/mqtt`;
+      const connectOptions: mqtt.IClientOptions = {
+        clientId: options.clientId,
+        username: options.username,
+        password: options.password,
+        clean: options.cleanSession ?? true,
+        keepalive: options.keepalive ?? 60,
+        protocolVersion: options.protocolVersion === '5.0' ? 5 : 4,
+        // MQTT 5.0 properties
+        properties: options.protocolVersion === '5.0' ? {
+          sessionExpiryInterval: options.sessionExpiryInterval,
+        } : undefined,
+      };
+
+      this.client = mqtt.connect(url, connectOptions);
+
+      this.client.on('connect', () => {
+        resolve({ connected: true });
+      });
+
+      this.client.on('error', (error) => {
+        reject(error.message);
+      });
+
+      this.client.on('message', (topic, message) => {
+        // Emit to Capacitor event system
+        // See Capacitor Web plugin event handling
+      });
+    });
+  }
+
+  async publish(options: MqttQuicPublishOptions): Promise<{ success: boolean }> {
+    if (!this.client || !this.client.connected) {
+      throw new Error('Not connected');
+    }
+
+    return new Promise((resolve, reject) => {
+      const publishOptions: mqtt.IClientPublishOptions = {
+        qos: options.qos ?? 0,
+        retain: options.retain ?? false,
+        properties: options.protocolVersion === '5.0' ? {
+          messageExpiryInterval: options.messageExpiryInterval,
+          contentType: options.contentType,
+          responseTopic: options.responseTopic,
+          correlationData: options.correlationData,
+          userProperties: options.userProperties,
+        } : undefined,
+      };
+
+      this.client!.publish(options.topic, options.payload, publishOptions, (error) => {
+        if (error) {
+          reject(error.message);
+        } else {
+          resolve({ success: true });
+        }
+      });
+    });
+  }
+
+  async subscribe(options: MqttQuicSubscribeOptions): Promise<{ success: boolean }> {
+    if (!this.client || !this.client.connected) {
+      throw new Error('Not connected');
+    }
+
+    return new Promise((resolve, reject) => {
+      const subscribeOptions: mqtt.IClientSubscribeOptions = {
+        qos: options.qos ?? 0,
+        properties: options.protocolVersion === '5.0' ? {
+          subscriptionIdentifier: options.subscriptionIdentifier,
+        } : undefined,
+      };
+
+      this.client!.subscribe(options.topic, subscribeOptions, (error, granted) => {
+        if (error) {
+          reject(error.message);
+        } else {
+          this.subscriptions.set(options.topic, granted);
+          resolve({ success: true });
+        }
+      });
+    });
+  }
+
+  async unsubscribe(options: { topic: string }): Promise<{ success: boolean }> {
+    if (!this.client || !this.client.connected) {
+      throw new Error('Not connected');
+    }
+
+    return new Promise((resolve, reject) => {
+      this.client!.unsubscribe(options.topic, (error) => {
+        if (error) {
+          reject(error.message);
+        } else {
+          this.subscriptions.delete(options.topic);
+          resolve({ success: true });
+        }
+      });
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.client) {
+        this.client.end(() => {
+          this.client = null;
+          this.subscriptions.clear();
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+}
+```
+
+**Package.json Addition:**
+```json
+{
+  "dependencies": {
+    "mqtt": "^5.3.0"
+  }
+}
+```
+
+---
+
+## 6. Edge Cases Not Handled
+
+### 6.1 Connection Edge Cases
+
+1. **Rapid connect/disconnect** - State machine may get confused
+2. **Connect while already connecting** - No guard
+3. **Disconnect during connect** - Race condition
+4. **Network change during connection** - No handling
+5. **App backgrounding** - Connections not paused/resumed
+
+### 6.2 Message Edge Cases
+
+1. **Large payloads** - No size limits, may cause memory issues
+2. **Malformed packets** - Parser may crash on invalid data
+3. **QoS 2** - Not fully implemented (only QoS 0/1)
+4. **Retained messages** - Not handled on subscribe
+5. **Will messages** - Not implemented in connect
+
+### 6.3 Protocol Edge Cases
+
+1. **Protocol version negotiation failure** - Auto-fallback may loop
+2. **Keepalive timeout** - No handling
+3. **Server disconnect** - No reconnection logic
+4. **Packet ID reuse** - Possible with concurrent operations
+5. **Topic alias** - MQTT 5.0 feature not implemented
+
+---
+
+## 7. Recommendations by Priority
+
+### 🔴 **P0 - Critical (Segfault Prevention)**
+
+1. **Fix message loop weak capture** (iOS/Android)
+2. **Fix state management race conditions** (iOS/Android)
+3. **Add proper cleanup in disconnect** (iOS/Android)
+4. **Fix packet ID thread safety** (iOS/Android)
+5. **Add null checks before use** (iOS/Android)
+
+### 🟡 **P1 - High (Stability)**
+
+6. **Implement Web/PWA support** (TypeScript)
+7. **Add error recovery** (iOS/Android)
+8. **Fix resource leaks** (iOS/Android)
+9. **Add timeout handling** (iOS/Android)
+10. **Fix client recreation without cleanup** (iOS/Android)
+
+### 🟢 **P2 - Medium (Features)**
+
+11. **Add reconnection logic** (iOS/Android)
+12. **Implement QoS 2** (iOS/Android)
+13. **Add will messages** (iOS/Android)
+14. **Handle app lifecycle** (iOS/Android)
+15. **Add connection state events** (iOS/Android/Web)
+
+---
+
+## 8. Testing Requirements
+
+### 8.1 Unit Tests Needed
+
+- State machine transitions
+- Packet ID generation (thread safety)
+- Message loop cancellation
+- Error handling paths
+- Protocol parsing edge cases
+
+### 8.2 Integration Tests Needed
+
+- Connect/disconnect cycles
+- Rapid connect/disconnect
+- Network interruption
+- Large payload handling
+- Concurrent operations
+
+### 8.3 Stress Tests Needed
+
+- Memory leak detection
+- Long-running connections
+- High message throughput
+- Multiple concurrent clients
+
+---
+
+## 9. Code Quality Improvements
+
+### 9.1 Swift
+
+- Use `actor` instead of `NSLock` (Swift 5.5+)
+- Add `@MainActor` where appropriate
+- Use structured concurrency properly
+- Add `Sendable` conformance
+
+### 9.2 Kotlin
+
+- Use `Flow` for message callbacks
+- Remove `runBlocking` usage
+- Use `sealed class` for state
+- Add proper cancellation handling
+
+### 9.3 TypeScript
+
+- Add proper type guards
+- Implement Web support
+- Add event emission for messages
+- Handle WebSocket reconnection
+
+---
+
+## 10. Documentation Gaps
+
+1. **Error codes** - No documentation of error scenarios
+2. **State transitions** - No state diagram
+3. **Threading model** - No documentation of concurrency
+4. **Memory management** - No lifecycle documentation
+5. **Web limitations** - No documentation of WebSocket fallback
+
+---
+
+## Conclusion
+
+**Current Risk Assessment:** 🔴 **HIGH**
+
+The plugin has a solid MQTT protocol implementation but has **critical memory safety and thread safety issues** that can lead to segfaults and crashes. Web/PWA support is completely missing.
+
+**Estimated Fix Time:**
+- P0 fixes: 2-3 weeks
+- P1 fixes: 2-3 weeks
+- P2 features: 4-6 weeks
+
+**Recommendation:** Address P0 issues immediately before production use. Implement Web support (P1) for complete cross-platform coverage.
+
+---
+
+**Next Steps:**
+1. Create detailed fix implementation plan
+2. Prioritize fixes by risk level
+3. Implement fixes with comprehensive testing
+4. Add Web/PWA support
+5. Document all edge cases and error scenarios