@cnhongwei/react-native-mqtt 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 cnhongwei
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @cnhongwei/react-native-mqtt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native MQTT 3.1.1 and MQTT 5 client for React Native on Android and iOS.
+The package uses the New Architecture TurboModule and does not support Web.
+
+MQTT 3.1 (`protocolVersion: 3`) is **not supported** on either platform.
+Protocol levels `4` and `5` mean MQTT 3.1.1 and MQTT 5.0, respectively.
+
+## Installation
+
+```sh
+npm install @cnhongwei/react-native-mqtt
+```
+
+Install native dependencies with the normal React Native workflow, then
+rebuild the application. Native changes are not delivered by Metro or OTA.
+
+## Basic usage
+
+```ts
+import { createMqttClient, decodeUtf8 } from '@cnhongwei/react-native-mqtt';
+
+const client = createMqttClient({
+  host: 'test.mosquitto.org',
+  port: 1883,
+  protocolVersion: 4,
+  clientId: 'example-client',
+});
+
+const listener = client.onMessage((message) => {
+  console.log(message.topic, decodeUtf8(message.bytes));
+});
+
+try {
+  const ack = await client.connect();
+  console.log(ack.sessionPresent);
+  const subscription = await client.subscribe('demo/status');
+  await client.publishText('demo/status', 'hello');
+  await client.ready();
+  await subscription.unsubscribe();
+} finally {
+  listener.remove();
+  await client.dispose();
+}
+```
+
+`createMqttClient` is synchronous and performs no Native I/O. `connect()` is
+lazy and deduplicated for same-turn callers. `ready()` waits for the captured
+subscription intent and does not connect implicitly. Always call `dispose()` in
+a `finally` block; `Symbol.asyncDispose` is installed when the runtime provides
+it.
+
+## Options
+
+`protocolVersion` is `4` (MQTT 3.1.1, the default) or `5`.
+Passing `3` (MQTT 3.1, not MQTT 3.0) throws `ERR_INVALID_OPTIONS` before native I/O.
+Paho Java can support MQTT 3.1, but this wrapper does not expose it; the locked
+CocoaMQTT 2.4.0 backend implements MQTT 3.1.1/5, not MQTT 3.1.
+
+### Testing protocols in the example
+
+Both RN and Expo examples offer MQTT 3.1.1 (4) / MQTT 5.0 (5) selection
+(example default: 5; SDK default: 4). Disconnect before switching versions.
+For each connection profile and version, connect, run **Test QoS 0/1/2**, then
+disconnect. The test checks actual payload/QoS round trips and unsubscribes its
+unique test topic. In version 5, **Test v5 properties** also checks Content Type
+and ordered, duplicate-key User Properties received from the broker.
+The UI reports PASS/FAIL, including timeouts, and disables the v5 test in version 4.
+These checks are interactive smoke tests, not full protocol conformance tests;
+see [example testing instructions](example/README.md) for the remaining matrix.
+
+| Option                                                                           | Meaning and default                                                                                                                                        |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`, `port`                                                                   | Required host and integer port `1..65535`.                                                                                                                 |
+| `transport`, `path`                                                              | `tcp`, `tls`, `ws`, or `wss`; `path` applies only to WS/WSS and defaults to `/mqtt`.                                                                       |
+| `clientId`                                                                       | Optional MQTT UTF-8 string; an ID is generated when omitted.                                                                                               |
+| `username`, `password`                                                           | Optional UTF-8 credentials; password requires username.                                                                                                    |
+| `keepAliveSeconds`                                                               | `0..65535`, default `60`; `0` disables protocol heartbeat.                                                                                                 |
+| `connectTimeoutMs`                                                               | Positive safe integer, default `30000`.                                                                                                                    |
+| `operationTimeoutMs`                                                             | Positive safe integer, default `30000`.                                                                                                                    |
+| `disconnectTimeoutMs`                                                            | Positive safe integer, default `5000`.                                                                                                                     |
+| `reconnect`                                                                      | `enabled: true`, `initialDelayMs: 1000`, `maxDelayMs: 30000`, `jitterRatio: 0.2`.                                                                          |
+| `tls`                                                                            | Optional DER CA / PKCS#12 Base64 and explicit `insecure`; only TLS/WSS. Default verifies system trust and hostname.                                        |
+| `will`                                                                           | MQTT will `{ topic, payloadBase64, qos?, retained? }`.                                                                                                     |
+| `cleanSession`                                                                   | MQTT 3.1.1 only.                                                                                                                                           |
+| `cleanStart`, `sessionExpiryIntervalSeconds`, `receiveMaximum`, `userProperties` | MQTT 5 only; user properties preserve order and duplicate keys.                                                                                            |
+| `delivery`                                                                       | Queue defaults `1024` messages / `8 MiB` / `1 MiB` per message; batches default `64` messages / `256 KiB`, ACK watchdog `15000 ms`, overflow `disconnect`. |
+
+Subscribe filters support `+` and a terminal `#`, preserve empty levels, and
+do not support `$share/`. Publish topics are topic names and reject wildcards.
+Use `publishBytes` for arbitrary bytes and `publishBase64` for canonical RFC
+4648 Base64; neither converts binary payloads to text.
+
+## Public surface
+
+- `connect`, `disconnect`, `dispose`, `ready`, and `getSnapshot` manage one
+  in-memory session.
+- `subscribe(filter, options)` returns a reference-counted handle. Equal
+  options share one broker subscription; conflicting options are rejected.
+- `publishText`, `publishBytes`, and `publishBase64` publish QoS `0..2`.
+- `onStateChange`, `onMessage`, and `onDiagnostic` return removable listeners.
+- `encodeUtf8`/`decodeUtf8` and `encodeBase64`/`decodeBase64` are strict helpers.
+
+`Message.bytes` and `ConnAck.userProperties` are the lossless wire-facing
+forms. `onMessage` is delivery acknowledgement to the bridge, not MQTT or
+business acknowledgement.
+
+### Android MQTT backend and QoS 2
+
+Android uses the direct Eclipse Paho MQTT Java 1.2.5 clients for MQTT 3.1.1
+(`org.eclipse.paho.client.mqttv3`) and MQTT 5
+(`org.eclipse.paho:org.eclipse.paho.mqttv5.client`); Paho Android Service is
+not used. MQTT 5 QoS 2 publish completion must reach `PUBCOMP`. The dedicated
+Android `PUBREC` → `PUBCOMP` success, timeout, disconnect, duplicate, and
+negative-path behavior has been verified with the repository-controlled Paho
+tests. This does not imply that the incomplete public RN/Expo matrix is
+complete.
+
+## Errors and platform limits
+
+Operations reject with `MqttError` containing `code` and `message`. The fixed
+codes are `ERR_INVALID_OPTIONS`, `ERR_INVALID_PAYLOAD`,
+`ERR_NATIVE_UNAVAILABLE`, `ERR_CONTRACT_MISMATCH`, `ERR_NOT_CONNECTED`,
+`ERR_DISPOSED`, `ERR_OPERATION_IN_PROGRESS`, `ERR_OPERATION_SUPERSEDED`,
+`ERR_CONNECT_TIMEOUT`, `ERR_OPERATION_TIMEOUT`, `ERR_CONNECTION_REFUSED`,
+`ERR_CONNECTION_LOST`, `ERR_SUBSCRIPTION_CONFLICT`, `ERR_SUBSCRIBE_FAILED`,
+`ERR_UNSUBSCRIBE_FAILED`, `ERR_PUBLISH_FAILED`, `ERR_TLS`,
+`ERR_CLEANUP_FAILED`, and `ERR_UNKNOWN`. `outcome` distinguishes
+`not-sent`, `rejected`, and `unknown` where known.
+
+This release is foreground, in-memory operation. It does not promise a
+persistent offline outbox, guaranteed background execution, Doze/process-death
+keep-alive, or Expo Go support. Expo requires a development or release build;
+native changes require a new build.
+
+For Android `ws://` connections, the consuming application must explicitly
+allow cleartext traffic for the build variant that uses them. The example
+application does this for Release because its public smoke matrix includes
+plaintext WebSocket listeners; `wss://` does not require this opt-in.
+
+## Development verification
+
+```sh
+yarn typecheck
+yarn lint
+yarn test
+yarn codegen
+yarn build
+yarn test:package
+yarn verify
+```
+
+Android and iOS native commands require their respective SDK/toolchain; see
+`example/android` and `example/ios`. The public Mosquitto matrix is configured
+under `test/mosquitto`; public service availability is not a substitute for
+fault-injection or performance evidence.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/README.zh-CN.md

@@ -0,0 +1,100 @@
+# @cnhongwei/react-native-mqtt
+
+面向 React Native Android/iOS 的 MQTT 3.1.1 与 MQTT 5 原生客户端，使用新架构 TurboModule，不支持 Web。
+
+Android/iOS 均**不支持 MQTT 3.1（`protocolVersion: 3`）**。
+协议级别 `4` 对应 MQTT 3.1.1，`5` 对应 MQTT 5.0；`3` 不是 MQTT 3.0。
+
+## 安装
+
+```sh
+npm install @cnhongwei/react-native-mqtt
+```
+
+按普通 React Native 流程安装原生依赖并重新构建应用；Metro 或 OTA 不会交付原生变更。
+
+## 基本用法
+
+```ts
+import { createMqttClient, decodeUtf8 } from '@cnhongwei/react-native-mqtt';
+
+const client = createMqttClient({
+  host: 'test.mosquitto.org',
+  port: 1883,
+  protocolVersion: 4,
+});
+
+const listener = client.onMessage((message) => {
+  console.log(message.topic, decodeUtf8(message.bytes));
+});
+
+try {
+  await client.connect();
+  const subscription = await client.subscribe('demo/status');
+  await client.publishText('demo/status', 'hello');
+  await client.ready();
+  await subscription.unsubscribe();
+} finally {
+  listener.remove();
+  await client.dispose();
+}
+```
+
+`createMqttClient` 同步返回且不执行 Native I/O；`connect()` 惰性执行，同一轮调用会合并。`ready()` 不会隐式连接，只等待调用时捕获的订阅意图。请在 `finally` 中调用 `dispose()`。
+
+## 选项
+
+`protocolVersion` 为 `4`（MQTT 3.1.1，默认）或 `5`。
+传入 `3` 会在 Native I/O 前抛出 `ERR_INVALID_OPTIONS`。Paho Java 本身支持
+MQTT 3.1，但本库未开放；锁定的 CocoaMQTT 2.4.0 实现仅支持 MQTT 3.1.1/5。
+
+RN/Expo 示例支持选择 MQTT 3.1.1（4）或 MQTT 5.0（5），示例默认 5，SDK 默认 4。
+断开后可切换版本；连接后运行 `Test QoS 0/1/2` 检查实际消息回环，选择 5 时还可运行
+`Test v5 properties` 检查 Content Type 和重复 key 的有序 User Properties。
+结果显示 PASS/FAIL（含超时），测试会取消其独立 topic 的订阅。这是交互冒烟测试，
+不代表完整协议一致性验收；完整操作与剩余测试范围见 [示例说明](example/README.md)。
+
+- `host`、`port`：必填，端口为 `1..65535` 整数。
+- `transport`：`tcp`、`tls`、`ws`、`wss`；WS/WSS 的 `path` 默认 `/mqtt`。
+- `clientId`、`username`、`password`：可选 MQTT UTF-8 字符串；password 必须配合 username。
+- `keepAliveSeconds`：`0..65535`，默认 `60`。
+- `connectTimeoutMs` / `operationTimeoutMs` / `disconnectTimeoutMs`：默认分别为 `30000`、`30000`、`5000`。
+- `reconnect`：默认启用，初始延迟 `1000`、最大延迟 `30000`、抖动比例 `0.2`。
+- `tls`：可选 CA、PKCS#12 Base64 与显式 `insecure`；仅 TLS/WSS 可用，默认校验证书链和主机名。
+- MQTT 3.1.1 使用 `cleanSession`；MQTT 5 使用 `cleanStart`、会话过期、`receiveMaximum` 和有序（允许重复 key）`userProperties`。
+- `delivery` 默认队列为 `1024` 条/`8 MiB`、单条 `1 MiB`；batch 默认 `64` 条/`256 KiB`，ACK watchdog `15000 ms`，溢出策略 `disconnect`。
+
+订阅 filter 支持 `+` 和末尾独占层级 `#`，保留空层级，不支持 `$share/`。发布 topic name 不允许通配符。二进制请使用 `publishBytes` 或严格 RFC 4648 的 `publishBase64`。
+
+## API、错误与限制
+
+客户端提供 `connect`、`disconnect`、`dispose`、`ready`、`getSnapshot`、`subscribe`、`publishText`、`publishBytes`、`publishBase64`，以及 `onStateChange`、`onMessage`、`onDiagnostic`。订阅 handle 是引用计数的；相同选项共享 Native 订阅，冲突会拒绝。
+
+### Android MQTT 后端与 QoS 2
+
+Android 使用直连的 Eclipse Paho MQTT Java 1.2.5：MQTT 3.1.1 使用
+`org.eclipse.paho.client.mqttv3`，MQTT 5 使用
+`org.eclipse.paho:org.eclipse.paho.mqttv5.client`，不使用 Paho Android
+Service。MQTT 5 QoS 2 发布必须完成到 `PUBCOMP`；Android 对
+`PUBREC` → `PUBCOMP` 的成功、超时、断开、重复包和负路径已通过仓库受控
+Paho 测试验证。但这不代表 RN/Expo 公共矩阵已经全部完成。
+
+错误通过 `MqttError` 返回，固定 code 包括：`ERR_INVALID_OPTIONS`、`ERR_INVALID_PAYLOAD`、`ERR_NATIVE_UNAVAILABLE`、`ERR_CONTRACT_MISMATCH`、`ERR_NOT_CONNECTED`、`ERR_DISPOSED`、`ERR_OPERATION_IN_PROGRESS`、`ERR_OPERATION_SUPERSEDED`、`ERR_CONNECT_TIMEOUT`、`ERR_OPERATION_TIMEOUT`、`ERR_CONNECTION_REFUSED`、`ERR_CONNECTION_LOST`、`ERR_SUBSCRIPTION_CONFLICT`、`ERR_SUBSCRIBE_FAILED`、`ERR_UNSUBSCRIBE_FAILED`、`ERR_PUBLISH_FAILED`、`ERR_TLS`、`ERR_CLEANUP_FAILED`、`ERR_UNKNOWN`。
+
+当前为前台、进程内存操作，不保证磁盘离线 outbox、后台持续运行、Doze/进程终止后的保活，也不支持 Expo Go。Expo 需要 development/release build。
+
+Android 使用 `ws://` 时，宿主应用必须为实际使用该传输的构建变体显式允许明文流量。示例应用因公共 smoke 矩阵包含明文 WebSocket 监听器，已为 Release 打开该配置；`wss://` 不需要此明文许可。
+
+## 开发验证
+
+```sh
+yarn typecheck
+yarn lint
+yarn test
+yarn codegen
+yarn build
+yarn test:package
+yarn verify
+```
+
+不编写旧 API 迁移指南；本项目没有旧 API 兼容目标。

package/ReactNativeMqtt.podspec

@@ -0,0 +1,28 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeMqtt"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.swift_version = "5.7"
+  s.source       = { :git => "https://github.com/cnhongwei/react-native-mqtt.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.exclude_files = "ios/Tests/**/*"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+  s.dependency "CocoaMQTT/WebSockets", "2.4.0"
+
+  s.test_spec "NativeSessionScenarios" do |test_spec|
+    test_spec.source_files = "ios/Tests/**/*.swift"
+    test_spec.requires_app_host = false
+  end
+end

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+This project owns only the source code in this repository, licensed under MIT.
+
+The native MQTT implementation dependencies are kept as external dependencies:
+
+- CocoaMQTT 2.4.0 — MIT.
+- MqttCocoaAsyncSocket 1.0.8 — dual public-domain/MIT-style terms in its
+  `LICENSE.txt`.
+- Starscream 4.0.8 — Apache-2.0.
+- Eclipse Paho MQTT Java 1.2.5 (`org.eclipse.paho.client.mqttv3` and
+  `org.eclipse.paho.mqttv5.client`) — EPL-2.0 / EDL-1.0; each artifact's
+  upstream license terms apply.
+- Bouncy Castle `bcprov-jdk18on` 1.77 — MIT.
+
+This file records dependency attribution only; it does not claim that either
+transport has passed the capability gate.

package/android/build.gradle

@@ -0,0 +1,70 @@
+buildscript {
+  ext.ReactNativeMqtt = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return ReactNativeMqtt[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+
+if (project.extensions.findByName("kotlin") == null) {
+  apply plugin: "kotlin-android"
+}
+
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.cnhongwei.reactnativemqtt"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  packagingOptions {
+    resources.excludes += [
+      "META-INF/INDEX.LIST",
+      "bundle.properties",
+    ]
+  }
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    consumerProguardFiles "consumer-rules.pro"
+    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.5"
+  implementation "org.eclipse.paho:org.eclipse.paho.mqttv5.client:1.2.5"
+  implementation "org.bouncycastle:bcprov-jdk18on:1.77"
+  testImplementation "junit:junit:4.13.2"
+  androidTestImplementation "androidx.test:runner:1.6.2"
+  androidTestImplementation "androidx.test.ext:junit:1.2.1"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,10 @@
+# Paho selects its logger implementation by class name.
+-keep class com.cnhongwei.reactnativemqtt.PahoLogger { public <init>(); *; }
+-keep class org.eclipse.paho.client.mqttv3.logging.** { *; }
+-keep class org.eclipse.paho.mqttv5.client.logging.** { *; }
+
+# TLS providers and the explicitly selected insecure TrustManagerFactory are
+# instantiated by name/provider registration.
+-keep class com.cnhongwei.reactnativemqtt.InsecureTrustManagerFactorySpi { public <init>(); }
+-keep class org.bouncycastle.jce.provider.BouncyCastleProvider { *; }
+-keep class org.bouncycastle.jcajce.provider.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/cnhongwei/reactnativemqtt/MqttOptionsParser.kt

@@ -0,0 +1,176 @@
+package com.cnhongwei.reactnativemqtt
+
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableArray
+
+internal fun isValidMqttUtf8(value: String): Boolean {
+  var index = 0
+  while (index < value.length) {
+    val character = value[index]
+    if (character == '\u0000') return false
+    if (character.isHighSurrogate()) {
+      if (index + 1 >= value.length || !value[index + 1].isLowSurrogate()) return false
+      index += 2
+    } else {
+      if (character.isLowSurrogate()) return false
+      index += 1
+    }
+  }
+  return true
+}
+
+internal data class ParsedMqttOptions(
+  val host: String,
+  val port: Int,
+  val protocolVersion: Int,
+  val transport: String,
+  val clientId: String = "rn-${java.util.UUID.randomUUID().toString().replace("-", "").take(21)}",
+  val username: String? = null,
+  val password: String? = null,
+  val willTopic: String? = null,
+  val willPayloadBase64: String? = null,
+  val willQos: Int = 0,
+  val willRetained: Boolean = false,
+  val keepAliveSeconds: Int = 60,
+  val cleanSession: Boolean = true,
+  val cleanStart: Boolean = true,
+  val sessionExpiryIntervalSeconds: Long = 0,
+  val userProperties: List<Pair<String, String>> = emptyList(),
+  val path: String = if (transport == "ws" || transport == "wss") "/mqtt" else "",
+  val connectTimeoutMs: Long = 30_000,
+  val operationTimeoutMs: Long = 30_000,
+  val disconnectTimeoutMs: Long = 5_000,
+  val reconnectEnabled: Boolean = true,
+  val reconnectInitialDelayMs: Long = 1_000,
+  val reconnectMaxDelayMs: Long = 30_000,
+  val reconnectJitterRatio: Double = 0.2,
+  val tlsCaBase64: String? = null,
+  val tlsP12Base64: String? = null,
+  val tlsP12Password: String? = null,
+  val tlsInsecure: Boolean = false,
+  val tlsAllowInvalidHostnameForTesting: Boolean = false,
+  val receiveMaximum: Int = 65535,
+  val maxQueuedMessages: Int = 1024,
+  val maxQueuedBytes: Long = 8L * 1024 * 1024,
+  val maxMessageBytes: Int = 1024 * 1024,
+  val batchMaxMessages: Int = 64,
+  val batchMaxBytes: Int = 256 * 1024,
+  val batchAckTimeoutMs: Long = 15_000,
+  val overflowPolicy: String = "disconnect",
+)
+
+internal object MqttOptionsParser {
+  fun parse(options: ReadableMap): Result<ParsedMqttOptions> = runCatching {
+    val allowed = setOf(
+      "host", "port", "protocolVersion", "transport", "path", "clientId", "username", "password",
+      "keepAliveSeconds", "connectTimeoutMs", "operationTimeoutMs", "disconnectTimeoutMs", "reconnectEnabled",
+      "reconnectInitialDelayMs", "reconnectMaxDelayMs", "reconnectJitterRatio", "tlsCaBase64", "tlsP12Base64",
+      "tlsP12Password", "tlsInsecure", "tlsAllowInvalidHostnameForTesting", "willTopic", "willPayloadBase64", "willQos", "willRetained",
+      "cleanSession", "cleanStart", "sessionExpiryIntervalSeconds", "receiveMaximum", "userProperties",
+      "maxQueuedMessages", "maxQueuedBytes", "maxMessageBytes", "batchMaxMessages", "batchMaxBytes",
+      "batchAckTimeoutMs", "overflowPolicy"
+    )
+    val iterator = options.keySetIterator()
+    while (iterator.hasNextKey()) {
+      val key = iterator.nextKey()
+      require(key in allowed) { "unsupported option: $key" }
+    }
+    val host = options.getString("host")
+      ?: throw IllegalArgumentException("host must be a non-empty string")
+    require(host.isNotEmpty()) { "host must be a non-empty string" }
+    val port = options.getDouble("port").toInt().also {
+      require(options.getDouble("port") == it.toDouble() && it in 1..65535) {
+        "port must be an integer in 1..65535"
+      }
+    }
+    val protocolVersion = if (options.hasKey("protocolVersion")) {
+      options.getDouble("protocolVersion").toInt().also {
+        require(options.getDouble("protocolVersion") == it.toDouble() && it in 4..5) {
+          "protocolVersion must be 4 or 5"
+        }
+      }
+    } else 4
+    val transport = if (options.hasKey("transport")) {
+      options.getString("transport") ?: throw IllegalArgumentException("transport must be a string")
+    } else "tcp"
+    require(transport in setOf("tcp", "tls", "ws", "wss")) { "transport is invalid" }
+    val hasPath = options.hasKey("path") && !options.isNull("path")
+    require(!hasPath || transport == "ws" || transport == "wss") { "path is only valid for ws/wss" }
+    val path = if (hasPath) options.getString("path") else if (transport == "ws" || transport == "wss") "/mqtt" else ""
+    require(path != null && (transport == "tcp" || transport == "tls" || (path.isNotEmpty() && path.startsWith("/")))) { "path must start with /" }
+    val clientId = if (options.hasKey("clientId") && !options.isNull("clientId")) {
+      options.getString("clientId") ?: throw IllegalArgumentException("clientId must be a string")
+    } else "rn-${java.util.UUID.randomUUID().toString().replace("-", "").take(21)}"
+    require(isValidMqttUtf8(clientId) && (clientId.isNotEmpty() || (protocolVersion == 5 && readBoolean(options, "cleanStart", true))) && clientId.toByteArray(Charsets.UTF_8).size <= 65535) { "clientId is invalid" }
+    val username = if (options.hasKey("username") && !options.isNull("username")) options.getString("username") else null
+    val password = if (options.hasKey("password") && !options.isNull("password")) options.getString("password") else null
+    require(username == null || (isValidMqttUtf8(username) && username.toByteArray(Charsets.UTF_8).size <= 65535)) { "username is invalid" }
+    require(password == null || (isValidMqttUtf8(password) && password.toByteArray(Charsets.UTF_8).size <= 65535)) { "password is invalid" }
+    require(password == null || username != null) { "password requires username" }
+    val willTopic = readString(options, "willTopic")
+    val willPayloadBase64 = readString(options, "willPayloadBase64")
+    require((willTopic == null) == (willPayloadBase64 == null)) { "willTopic and willPayloadBase64 must be provided together" }
+    require(willTopic == null || (isValidMqttUtf8(willTopic) && willTopic.isNotEmpty() && !willTopic.contains('+') && !willTopic.contains('#') && willTopic.toByteArray(Charsets.UTF_8).size <= 65535)) { "willTopic is invalid" }
+    willPayloadBase64?.let { require(isStrictBase64Shape(it)) { "willPayloadBase64 is invalid" } }
+    val willQos = readInt(options, "willQos", 0, 0, 2)
+    val willRetained = readBoolean(options, "willRetained", false)
+    val keepAlive = readInt(options, "keepAliveSeconds", 60, 0, 65535)
+    val cleanSession = readBoolean(options, "cleanSession", true)
+    val cleanStart = readBoolean(options, "cleanStart", true)
+    require(protocolVersion != 4 || !hasNonNull(options, "cleanStart", "sessionExpiryIntervalSeconds", "receiveMaximum", "userProperties")) {
+      "MQTT5 options are not valid for protocolVersion 4"
+    }
+    require(protocolVersion != 5 || !hasNonNull(options, "cleanSession")) {
+      "cleanSession is not valid for protocolVersion 5"
+    }
+    val expiry = readLong(options, "sessionExpiryIntervalSeconds", 0, 0, 4294967295L)
+    val receiveMaximum = readInt(options, "receiveMaximum", 65535, 1, 65535)
+    val userProperties = if (options.hasKey("userProperties") && !options.isNull("userProperties")) {
+      val array: ReadableArray = options.getArray("userProperties") ?: throw IllegalArgumentException("userProperties must be an array")
+      (0 until array.size()).map { index ->
+        val pair = array.getMap(index) ?: throw IllegalArgumentException("userProperties[$index] must be an object")
+        val key = pair.getString("key") ?: throw IllegalArgumentException("userProperties[$index].key must be a string")
+        val value = pair.getString("value") ?: throw IllegalArgumentException("userProperties[$index].value must be a string")
+        require(isValidMqttUtf8(key) && key.toByteArray(Charsets.UTF_8).size <= 65535) { "userProperties[$index].key is invalid" }
+        require(isValidMqttUtf8(value) && value.toByteArray(Charsets.UTF_8).size <= 65535) { "userProperties[$index].value is invalid" }
+        key to value
+      }
+    } else emptyList()
+    val connectTimeout = readLong(options, "connectTimeoutMs", 30_000, 1, Long.MAX_VALUE)
+    val operationTimeout = readLong(options, "operationTimeoutMs", 30_000, 1, Long.MAX_VALUE)
+    val disconnectTimeout = readLong(options, "disconnectTimeoutMs", 5_000, 1, Long.MAX_VALUE)
+    val reconnectInitial = readLong(options, "reconnectInitialDelayMs", 1_000, 1, Long.MAX_VALUE)
+    val reconnectMax = readLong(options, "reconnectMaxDelayMs", 30_000, 1, Long.MAX_VALUE)
+    require(reconnectMax >= reconnectInitial) { "reconnectMaxDelayMs must be >= reconnectInitialDelayMs" }
+    val jitter = readDouble(options, "reconnectJitterRatio", 0.2)
+    require(jitter in 0.0..1.0) { "reconnectJitterRatio must be in 0..1" }
+    val tlsFields = listOf("tlsCaBase64", "tlsP12Base64", "tlsP12Password", "tlsInsecure", "tlsAllowInvalidHostnameForTesting")
+    require(transport == "tls" || transport == "wss" || !hasNonNull(options, *tlsFields.toTypedArray())) { "tls options are only valid for tls/wss" }
+    val p12 = readString(options, "tlsP12Base64")
+    val p12Password = readString(options, "tlsP12Password")
+    require(p12Password == null || p12 != null) { "tlsP12Password requires tlsP12Base64" }
+    val maxQueuedMessages = readInt(options, "maxQueuedMessages", 1024, 1, 1_000_000)
+    val maxQueuedBytes = readLong(options, "maxQueuedBytes", 8L * 1024 * 1024, 1, Long.MAX_VALUE)
+    val maxMessageBytes = readInt(options, "maxMessageBytes", 1024 * 1024, 1, Int.MAX_VALUE)
+    val batchMaxMessages = readInt(options, "batchMaxMessages", 64, 1, 64)
+    val batchMaxBytes = readInt(options, "batchMaxBytes", 256 * 1024, 1, 256 * 1024)
+    val batchAckTimeout = readLong(options, "batchAckTimeoutMs", 15_000, 1, Long.MAX_VALUE)
+    val overflowPolicy = readString(options, "overflowPolicy") ?: "disconnect"
+    require(overflowPolicy == "disconnect" || overflowPolicy == "drop-newest") { "overflowPolicy is invalid" }
+    ParsedMqttOptions(host, port, protocolVersion, transport, clientId, username, password, willTopic, willPayloadBase64, willQos, willRetained, keepAlive, cleanSession, cleanStart, expiry, userProperties,
+      path ?: "", connectTimeout, operationTimeout, disconnectTimeout, readBoolean(options, "reconnectEnabled", true), reconnectInitial,
+      reconnectMax, jitter, readString(options, "tlsCaBase64"), p12, p12Password, readBoolean(options, "tlsInsecure", false), readBoolean(options, "tlsAllowInvalidHostnameForTesting", false), receiveMaximum,
+      maxQueuedMessages, maxQueuedBytes, maxMessageBytes, batchMaxMessages, batchMaxBytes, batchAckTimeout, overflowPolicy)
+  }
+
+  private fun hasNonNull(options: ReadableMap, vararg keys: String): Boolean = keys.any { options.hasKey(it) && !options.isNull(it) }
+  private fun readString(options: ReadableMap, key: String): String? = if (options.hasKey(key) && !options.isNull(key)) options.getString(key) else null
+  private fun readBoolean(options: ReadableMap, key: String, default: Boolean): Boolean = if (options.hasKey(key) && !options.isNull(key)) options.getBoolean(key) else default
+  private fun readDouble(options: ReadableMap, key: String, default: Double): Double = if (options.hasKey(key) && !options.isNull(key)) options.getDouble(key) else default
+  private fun readLong(options: ReadableMap, key: String, default: Long, min: Long, max: Long): Long {
+    val value = readDouble(options, key, default.toDouble())
+    require(value.isFinite() && value == value.toLong().toDouble() && value >= min && value <= max) { "$key must be an integer in $min..$max" }
+    return value.toLong()
+  }
+  private fun readInt(options: ReadableMap, key: String, default: Int, min: Int, max: Int): Int = readLong(options, key, default.toLong(), min.toLong(), max.toLong()).toInt()
+}