@annadata/capacitor-mqtt-quic 0.1.0

package/android/src/main/kotlin/ai/annadata/mqttquic/mqtt/MQTTProtocol.kt

@@ -0,0 +1,249 @@
+package ai.annadata.mqttquic.mqtt
+
+import java.nio.ByteBuffer
+import java.nio.charset.StandardCharsets
+
+/**
+ * MQTT 3.1.1 encode/decode. Matches MQTTD mqttd/protocol.py.
+ */
+object MQTTProtocol {
+
+    const val PROTOCOL_NAME = "MQTT"
+
+    /**
+     * Encode remaining length (1–4 bytes). Max 268_435_455.
+     */
+    fun encodeRemainingLength(length: Int): ByteArray {
+        if (length < 0 || length > 268_435_455) {
+            throw IllegalArgumentException("Invalid remaining length: $length")
+        }
+        val enc = mutableListOf<Byte>()
+        var n = length
+        do {
+            var b = (n % 128).toByte()
+            n /= 128
+            if (n > 0) b = (b.toInt() or 0x80).toByte()
+            enc.add(b)
+        } while (n > 0)
+        return enc.toByteArray()
+    }
+
+    /**
+     * Decode remaining length. Returns Pair(length, bytesConsumed).
+     */
+    fun decodeRemainingLength(data: ByteArray, offset: Int = 0): Pair<Int, Int> {
+        var mul = 1
+        var len = 0
+        var i = offset
+        repeat(4) {
+            if (i >= data.size) throw IllegalArgumentException("Insufficient data for remaining length")
+            val b = data[i].toInt() and 0xFF
+            len += (b and 0x7F) * mul
+            i++
+            if ((b and 0x80) == 0) return@repeat
+            mul *= 128
+        }
+        return len to (i - offset)
+    }
+
+    fun encodeString(s: String): ByteArray {
+        val utf8 = s.toByteArray(StandardCharsets.UTF_8)
+        if (utf8.size > 0xFFFF) throw IllegalArgumentException("String too long")
+        return byteArrayOf(
+            (utf8.size shr 8).toByte(),
+            (utf8.size and 0xFF).toByte()
+        ) + utf8
+    }
+
+    fun decodeString(data: ByteArray, offset: Int): Pair<String, Int> {
+        if (offset + 2 > data.size) throw IllegalArgumentException("Insufficient data for string length")
+        val strLen = ((data[offset].toInt() and 0xFF) shl 8) or (data[offset + 1].toInt() and 0xFF)
+        val start = offset + 2
+        if (start + strLen > data.size) throw IllegalArgumentException("Insufficient data for string content")
+        val sub = data.copyOfRange(start, start + strLen)
+        val s = String(sub, StandardCharsets.UTF_8)
+        return s to (start + strLen)
+    }
+
+    /**
+     * Returns Triple(messageType, remainingLength, bytesConsumed).
+     */
+    fun parseFixedHeader(data: ByteArray): Triple<Byte, Int, Int> {
+        if (data.size < 2) throw IllegalArgumentException("Insufficient data for fixed header")
+        val msgType = data[0]
+        val (rem, consumed) = decodeRemainingLength(data, 1)
+        return Triple(msgType, rem, 1 + consumed)
+    }
+
+    fun buildConnect(
+        clientId: String,
+        username: String? = null,
+        password: String? = null,
+        keepalive: Int = 60,
+        cleanSession: Boolean = true
+    ): ByteArray {
+        val variableHeader = mutableListOf<Byte>()
+        variableHeader.addAll(encodeString(PROTOCOL_NAME).toList())
+        variableHeader.add(MQTTProtocolLevel.V311)
+        var flags = 0
+        if (cleanSession) flags = flags or MQTTConnectFlags.CLEAN_SESSION
+        if (username != null) flags = flags or MQTTConnectFlags.USERNAME
+        if (password != null) flags = flags or MQTTConnectFlags.PASSWORD
+        variableHeader.add(flags.toByte())
+        variableHeader.add((keepalive shr 8).toByte())
+        variableHeader.add((keepalive and 0xFF).toByte())
+
+        val payload = mutableListOf<Byte>()
+        payload.addAll(encodeString(clientId).toList())
+        username?.let { payload.addAll(encodeString(it).toList()) }
+        password?.let { payload.addAll(encodeString(it).toList()) }
+
+        val remLen = variableHeader.size + payload.size
+        val fixed = mutableListOf<Byte>()
+        fixed.add(MQTTMessageType.CONNECT)
+        fixed.addAll(encodeRemainingLength(remLen).toList())
+
+        return (fixed + variableHeader + payload).toByteArray()
+    }
+
+    fun buildConnack(returnCode: Int = MQTTConnAckCode.ACCEPTED): ByteArray {
+        return byteArrayOf(
+            MQTTMessageType.CONNACK,
+            *encodeRemainingLength(2),
+            0x00,
+            returnCode.toByte()
+        )
+    }
+
+    /**
+     * Parse CONNACK variable header. Returns Pair(sessionPresent, returnCode).
+     */
+    fun parseConnack(data: ByteArray, offset: Int = 0): Pair<Boolean, Int> {
+        if (offset + 2 > data.size) throw IllegalArgumentException("Insufficient data for CONNACK")
+        val flags = data[offset].toInt() and 0xFF
+        val rc = data[offset + 1].toInt() and 0xFF
+        return ((flags and 0x01) != 0) to rc
+    }
+
+    fun buildPublish(
+        topic: String,
+        payload: ByteArray,
+        packetId: Int? = null,
+        qos: Int = 0,
+        retain: Boolean = false
+    ): ByteArray {
+        var msgType = MQTTMessageType.PUBLISH.toInt()
+        if (qos > 0) msgType = msgType or (qos shl 1)
+        if (retain) msgType = msgType or 0x01
+
+        val vh = mutableListOf<Byte>()
+        vh.addAll(encodeString(topic).toList())
+        if (qos > 0 && packetId != null) {
+            vh.add((packetId shr 8).toByte())
+            vh.add((packetId and 0xFF).toByte())
+        }
+        val vhArr = vh.toByteArray()
+        val pl = vhArr + payload
+        val remLen = pl.size
+        return byteArrayOf(
+            msgType.toByte(),
+            *encodeRemainingLength(remLen),
+            *pl
+        )
+    }
+
+    fun buildPuback(packetId: Int): ByteArray {
+        return byteArrayOf(
+            MQTTMessageType.PUBACK,
+            *encodeRemainingLength(2),
+            (packetId shr 8).toByte(),
+            (packetId and 0xFF).toByte()
+        )
+    }
+
+    fun parsePuback(data: ByteArray, offset: Int = 0): Int {
+        if (offset + 2 > data.size) throw IllegalArgumentException("Insufficient data for PUBACK")
+        return ((data[offset].toInt() and 0xFF) shl 8) or (data[offset + 1].toInt() and 0xFF)
+    }
+    
+    /**
+     * Parse PUBLISH payload (after fixed header).
+     * Returns (topic, packetId?, payload, newOffset). packetId only for QoS > 0.
+     */
+    fun parsePublish(data: ByteArray, offset: Int, qos: Int): Triple<String, Int?, ByteArray, Int> {
+        var off = offset
+        val (topic, next) = decodeString(data, off)
+        off = next
+        var pid: Int? = null
+        if (qos > 0) {
+            if (off + 2 > data.size) throw IllegalArgumentException("Insufficient data for PUBLISH packet ID")
+            pid = ((data[off].toInt() and 0xFF) shl 8) or (data[off + 1].toInt() and 0xFF)
+            off += 2
+        }
+        val payload = data.copyOfRange(off, data.size)
+        return Triple(topic, pid, payload, data.size)
+    }
+
+    fun buildSubscribe(packetId: Int, topic: String, qos: Int = 0): ByteArray {
+        val vh = byteArrayOf((packetId shr 8).toByte(), (packetId and 0xFF).toByte())
+        val pl = encodeString(topic) + byteArrayOf((qos and 0x03).toByte())
+        val rem = vh.size + pl.size
+        return byteArrayOf(
+            (MQTTMessageType.SUBSCRIBE.toInt() or 0x02).toByte(),
+            *encodeRemainingLength(rem),
+            *vh,
+            *pl
+        )
+    }
+
+    fun buildSuback(packetId: Int, returnCode: Int = 0): ByteArray {
+        return byteArrayOf(
+            MQTTMessageType.SUBACK,
+            *encodeRemainingLength(3),
+            (packetId shr 8).toByte(),
+            (packetId and 0xFF).toByte(),
+            returnCode.toByte()
+        )
+    }
+
+    fun parseSuback(data: ByteArray, offset: Int = 0): Triple<Int, Int, Int> {
+        if (offset + 3 > data.size) throw IllegalArgumentException("Insufficient data for SUBACK")
+        val pid = ((data[offset].toInt() and 0xFF) shl 8) or (data[offset + 1].toInt() and 0xFF)
+        val rc = data[offset + 2].toInt() and 0xFF
+        return Triple(pid, rc, offset + 3)
+    }
+
+    fun buildUnsubscribe(packetId: Int, topics: List<String>): ByteArray {
+        val vh = byteArrayOf((packetId shr 8).toByte(), (packetId and 0xFF).toByte())
+        val plList = topics.flatMap { encodeString(it).toList() }
+        val pl = ByteArray(plList.size) { plList[it] }
+        val rem = vh.size + pl.size
+        return byteArrayOf(
+            (MQTTMessageType.UNSUBSCRIBE.toInt() or 0x02).toByte(),
+            *encodeRemainingLength(rem),
+            *vh,
+            *pl
+        )
+    }
+
+    fun buildUnsuback(packetId: Int): ByteArray {
+        return byteArrayOf(
+            MQTTMessageType.UNSUBACK,
+            *encodeRemainingLength(2),
+            (packetId shr 8).toByte(),
+            (packetId and 0xFF).toByte()
+        )
+    }
+
+    fun buildPingreq(): ByteArray {
+        return byteArrayOf(MQTTMessageType.PINGREQ, *encodeRemainingLength(0))
+    }
+
+    fun buildPingresp(): ByteArray {
+        return byteArrayOf(MQTTMessageType.PINGRESP, *encodeRemainingLength(0))
+    }
+
+    fun buildDisconnect(): ByteArray {
+        return byteArrayOf(MQTTMessageType.DISCONNECT, *encodeRemainingLength(0))
+    }
+}

package/android/src/main/kotlin/ai/annadata/mqttquic/mqtt/MQTTTypes.kt

@@ -0,0 +1,47 @@
+package ai.annadata.mqttquic.mqtt
+
+/**
+ * MQTT packet types and constants. Matches MQTTD protocol.py / protocol_v5.py.
+ */
+
+object MQTTMessageType {
+    const val CONNECT: Byte = 0x10
+    const val CONNACK: Byte = 0x20
+    const val PUBLISH: Byte = 0x30
+    const val PUBACK: Byte = 0x40
+    const val PUBREC: Byte = 0x50
+    const val PUBREL: Byte = 0x62
+    const val PUBCOMP: Byte = 0x70
+    const val SUBSCRIBE: Byte = 0x82
+    const val SUBACK: Byte = 0x90
+    const val UNSUBSCRIBE: Byte = 0xA2
+    const val UNSUBACK: Byte = 0xB0
+    const val PINGREQ: Byte = 0xC0
+    const val PINGRESP: Byte = 0xD0
+    const val DISCONNECT: Byte = 0xE0
+}
+
+object MQTTConnectFlags {
+    const val USERNAME: Int = 0x80
+    const val PASSWORD: Int = 0x40
+    const val WILL_RETAIN: Int = 0x20
+    const val WILL_QOS1: Int = 0x08
+    const val WILL_QOS2: Int = 0x18
+    const val WILL_FLAG: Int = 0x04
+    const val CLEAN_SESSION: Int = 0x02
+    const val RESERVED: Int = 0x01
+}
+
+object MQTTConnAckCode {
+    const val ACCEPTED: Int = 0x00
+    const val UNACCEPTABLE_PROTOCOL: Int = 0x01
+    const val IDENTIFIER_REJECTED: Int = 0x02
+    const val SERVER_UNAVAILABLE: Int = 0x03
+    const val BAD_USERNAME_PASSWORD: Int = 0x04
+    const val NOT_AUTHORIZED: Int = 0x05
+}
+
+object MQTTProtocolLevel {
+    const val V311: Byte = 0x04
+    const val V5: Byte = 0x05
+}

package/android/src/main/kotlin/ai/annadata/mqttquic/quic/NGTCP2Client.kt

@@ -0,0 +1,184 @@
+package ai.annadata.mqttquic.quic
+
+import android.util.Log
+import kotlinx.coroutines.delay
+
+/**
+ * ngtcp2-based QUIC client implementation for Android.
+ * Replaces QuicClientStub when ngtcp2 is built and linked via JNI.
+ *
+ * Build Requirements:
+ * - ngtcp2 native library (libngtcp2_client.so)
+ * - nghttp3 static library (libnghttp3.a)
+ * - OpenSSL 3.0+ or BoringSSL for TLS 1.3
+ * - Android NDK r25+
+ * - Android API 21+ (Android 5.0+)
+ */
+class NGTCP2Client : QuicClient {
+    
+    companion object {
+        private const val TAG = "NGTCP2Client"
+        private var nativeAvailable: Boolean = false
+
+        init {
+            nativeAvailable = try {
+                System.loadLibrary("ngtcp2_client")
+                true
+            } catch (e: UnsatisfiedLinkError) {
+                false
+            } catch (e: Exception) {
+                false
+            }
+
+            if (!nativeAvailable) {
+                Log.w(TAG, "ngtcp2_client native library not available")
+            }
+        }
+
+        fun isAvailable(): Boolean = nativeAvailable
+    }
+    
+    // Native methods (implemented in ngtcp2_jni.cpp)
+    private external fun nativeCreateConnection(host: String, port: Int): Long
+    private external fun nativeConnect(connHandle: Long): Int
+    private external fun nativeOpenStream(connHandle: Long): Long
+    private external fun nativeWriteStream(connHandle: Long, streamId: Long, data: ByteArray): Int
+    private external fun nativeReadStream(connHandle: Long, streamId: Long): ByteArray?
+    private external fun nativeClose(connHandle: Long)
+    private external fun nativeIsConnected(connHandle: Long): Boolean
+    internal external fun nativeCloseStream(connHandle: Long, streamId: Long): Int
+    internal external fun nativeGetLastError(connHandle: Long): String
+    
+    // Connection state
+    private var connHandle: Long = 0
+    private var isConnected: Boolean = false
+    private val streams = mutableMapOf<Long, NGTCP2Stream>()
+    
+    override suspend fun connect(host: String, port: Int) {
+        if (!isAvailable()) {
+            throw IllegalStateException("ngtcp2 native library is not loaded")
+        }
+        if (isConnected) {
+            throw IllegalStateException("Already connected")
+        }
+        
+        // Create native connection
+        connHandle = nativeCreateConnection(host, port)
+        if (connHandle == 0L) {
+            throw IllegalStateException("Failed to create QUIC connection")
+        }
+        
+        // Connect to server
+        val result = nativeConnect(connHandle)
+        if (result != 0) {
+            throw Exception("QUIC connection failed: ${nativeGetLastError(connHandle)}")
+        }
+        isConnected = true
+    }
+    
+    override suspend fun openStream(): QuicStream {
+        if (!isConnected) {
+            throw IllegalStateException("Not connected")
+        }
+        
+        val streamId = nativeOpenStream(connHandle)
+        if (streamId < 0L) {
+            throw IllegalStateException("Failed to open QUIC stream: ${nativeGetLastError(connHandle)}")
+        }
+        
+        val stream = NGTCP2Stream(connHandle, streamId, this)
+        streams[streamId] = stream
+        
+        return stream
+    }
+    
+    override suspend fun close() {
+        if (!isConnected) {
+            return
+        }
+        
+        // Close all streams
+        streams.values.forEach { stream ->
+            try {
+                stream.close()
+            } catch (e: Exception) {
+                // Ignore errors during stream close
+            }
+        }
+        streams.clear()
+        
+        // Close native connection
+        nativeClose(connHandle)
+        connHandle = 0
+        
+        isConnected = false
+    }
+    
+    /**
+     * Internal method called by NGTCP2Stream to write data
+     */
+    internal suspend fun writeStreamData(streamId: Long, data: ByteArray): Int {
+        if (!isConnected) {
+            throw IllegalStateException("Not connected")
+        }
+        return nativeWriteStream(connHandle, streamId, data)
+    }
+    
+    /**
+     * Internal method called to read data from stream
+     */
+    internal suspend fun readStreamData(streamId: Long): ByteArray? {
+        if (!isConnected) {
+            throw IllegalStateException("Not connected")
+        }
+        return nativeReadStream(connHandle, streamId)
+    }
+}
+
+/**
+ * ngtcp2-based QUIC stream implementation
+ */
+internal class NGTCP2Stream(
+    private val connHandle: Long,
+    override val streamId: Long,
+    private val client: NGTCP2Client
+) : QuicStream {
+    
+    private var isClosed: Boolean = false
+    
+    override suspend fun read(maxBytes: Int): ByteArray {
+        if (isClosed) {
+            throw IllegalStateException("Stream is closed")
+        }
+
+        while (!isClosed) {
+            val data = client.readStreamData(streamId)
+            if (data != null && data.isNotEmpty()) {
+                return data
+            }
+            delay(5)
+        }
+        return ByteArray(0)
+    }
+    
+    override suspend fun write(data: ByteArray) {
+        if (isClosed) {
+            throw IllegalStateException("Stream is closed")
+        }
+        
+        // Write data to native stream
+        val result = client.writeStreamData(streamId, data)
+        if (result != 0) {
+            throw Exception("Failed to write to stream: ${client.nativeGetLastError(connHandle)}")
+        }
+    }
+    
+    override suspend fun close() {
+        if (isClosed) {
+            return
+        }
+
+        client.nativeCloseStream(connHandle, streamId)
+        isClosed = true
+    }
+}

package/android/src/main/kotlin/ai/annadata/mqttquic/quic/QuicClientStub.kt

@@ -0,0 +1,54 @@
+package ai.annadata.mqttquic.quic
+
+import ai.annadata.mqttquic.transport.MockStreamBuffer
+import ai.annadata.mqttquic.transport.MockStreamReader
+import ai.annadata.mqttquic.transport.MockStreamWriter
+
+/**
+ * Stub QUIC stream. Phase 2: replace with ngtcp2-backed implementation.
+ */
+class QuicStreamStub(
+    override val streamId: Long,
+    private val buffer: MockStreamBuffer
+) : QuicStream {
+
+    private val reader = MockStreamReader(buffer)
+    private val writer = MockStreamWriter(buffer)
+
+    override suspend fun read(maxBytes: Int): ByteArray = reader.read(maxBytes)
+
+    override suspend fun write(data: ByteArray) {
+        writer.write(data)
+    }
+
+    override suspend fun close() {
+        writer.close()
+    }
+}
+
+/**
+ * Stub QUIC client. connect() succeeds without network; openStream() returns stub stream.
+ * Phase 2 proper: ngtcp2 + JNI, DatagramSocket for UDP.
+ * Pass initialReadData (e.g. CONNACK) to simulate server response for testing.
+ */
+class QuicClientStub(private val initialReadData: List<Byte> = emptyList()) : QuicClient {
+
+    private var buffer: MockStreamBuffer? = null
+    private var streamId = 0L
+
+    override suspend fun connect(host: String, port: Int) {
+        buffer = MockStreamBuffer(initialReadData.toByteArray())
+        streamId = 0L
+    }
+
+    override suspend fun openStream(): QuicStream {
+        val buf = buffer ?: error("Not connected")
+        val s = QuicStreamStub(streamId, buf)
+        streamId++
+        return s
+    }
+
+    override suspend fun close() {
+        buffer = null
+    }
+}

package/android/src/main/kotlin/ai/annadata/mqttquic/quic/QuicTypes.kt

@@ -0,0 +1,21 @@
+package ai.annadata.mqttquic.quic
+
+/**
+ * QUIC stream: one bidirectional stream per MQTT connection.
+ * Phase 2: ngtcp2 client + single stream.
+ */
+interface QuicStream {
+    val streamId: Long
+    suspend fun read(maxBytes: Int): ByteArray
+    suspend fun write(data: ByteArray)
+    suspend fun close()
+}
+
+/**
+ * QUIC client: connect, TLS handshake, open one bidirectional stream.
+ */
+interface QuicClient {
+    suspend fun connect(host: String, port: Int)
+    suspend fun openStream(): QuicStream
+    suspend fun close()
+}

package/android/src/main/kotlin/ai/annadata/mqttquic/transport/QUICStreamAdapter.kt

@@ -0,0 +1,37 @@
+package ai.annadata.mqttquic.transport
+
+import ai.annadata.mqttquic.quic.QuicStream
+
+/**
+ * MQTTStreamReader over QUIC stream. Mirrors NGTCP2StreamReader.
+ */
+class QUICStreamReader(private val stream: QuicStream) : MQTTStreamReader {
+
+    override suspend fun read(maxBytes: Int): ByteArray = stream.read(maxBytes)
+
+    override suspend fun readexactly(n: Int): ByteArray {
+        val acc = mutableListOf<Byte>()
+        while (acc.size < n) {
+            val chunk = stream.read(n - acc.size)
+            if (chunk.isEmpty()) throw IllegalArgumentException("readexactly")
+            acc.addAll(chunk.toList())
+        }
+        return acc.toByteArray()
+    }
+}
+
+/**
+ * MQTTStreamWriter over QUIC stream. Mirrors NGTCP2StreamWriter.
+ */
+class QUICStreamWriter(private val stream: QuicStream) : MQTTStreamWriter {
+
+    override suspend fun write(data: ByteArray) {
+        stream.write(data)
+    }
+
+    override suspend fun drain() {}
+
+    override suspend fun close() {
+        stream.close()
+    }
+}

package/android/src/main/kotlin/ai/annadata/mqttquic/transport/StreamTransport.kt

@@ -0,0 +1,91 @@
+package ai.annadata.mqttquic.transport
+
+import kotlinx.coroutines.delay
+
+/**
+ * StreamReader-like: read(n), readexactly(n).
+ * Phase 2 implements over QUIC stream.
+ */
+interface MQTTStreamReader {
+    suspend fun read(maxBytes: Int): ByteArray
+    suspend fun readexactly(n: Int): ByteArray
+}
+
+/**
+ * StreamWriter-like: write(data), drain(), close().
+ */
+interface MQTTStreamWriter {
+    suspend fun write(data: ByteArray)
+    suspend fun drain()
+    suspend fun close()
+}
+
+/**
+ * In-memory buffer for mock read/write (Phase 1 unit tests).
+ */
+class MockStreamBuffer(initialReadData: ByteArray = ByteArray(0)) {
+    var readBuffer = initialReadData.toMutableList()
+        private set
+    val writeBuffer = mutableListOf<Byte>()
+    var isClosed = false
+        private set
+
+    fun appendRead(data: ByteArray) {
+        readBuffer.addAll(data.toList())
+    }
+
+    fun consumeWrite(): ByteArray {
+        val d = writeBuffer.toByteArray()
+        writeBuffer.clear()
+        return d
+    }
+
+    fun close() {
+        isClosed = true
+    }
+}
+
+/**
+ * Mock reader over MockStreamBuffer.
+ */
+class MockStreamReader(private val buffer: MockStreamBuffer) : MQTTStreamReader {
+
+    override suspend fun read(maxBytes: Int): ByteArray {
+        if (buffer.isClosed && buffer.readBuffer.isEmpty()) return ByteArray(0)
+        val n = minOf(maxBytes, buffer.readBuffer.size)
+        if (n == 0) {
+            delay(1)
+            return read(maxBytes)
+        }
+        val out = buffer.readBuffer.take(n).toByteArray()
+        repeat(n) { buffer.readBuffer.removeAt(0) }
+        return out
+    }
+
+    override suspend fun readexactly(n: Int): ByteArray {
+        val acc = mutableListOf<Byte>()
+        while (acc.size < n) {
+            if (buffer.isClosed) throw IllegalArgumentException("stream closed")
+            val chunk = read(n - acc.size)
+            if (chunk.isEmpty()) throw IllegalArgumentException("readexactly")
+            acc.addAll(chunk.toList())
+        }
+        return acc.toByteArray()
+    }
+}
+
+/**
+ * Mock writer over MockStreamBuffer.
+ */
+class MockStreamWriter(private val buffer: MockStreamBuffer) : MQTTStreamWriter {
+
+    override suspend fun write(data: ByteArray) {
+        buffer.writeBuffer.addAll(data.toList())
+    }
+
+    override suspend fun drain() {}
+
+    override suspend fun close() {
+        buffer.close()
+    }
+}