NixMsg/sdk/java/README.md

NixMsg Java / Android SDK

坐标：asia.asio.nixmsg:nixmsg-sdk
包名：asia.asio.nixmsg
字节码目标：Java 8（maven.compiler.release=8）
接口：CompletableFuture

Android

最低 API 24。MQTT 长连接由应用自行放入前台服务，SDK 不创建也不托管服务生命周期。

依赖

Maven / Gradle 仓库：

https://git.asio.asia/api/packages/nixevol/maven

<dependency>
  <groupId>asia.asio.nixmsg</groupId>
  <artifactId>nixmsg-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

HiveMQ MQTT Client（WebSocket：webSocketConfig + netty-codec-http）。

最小示例

Client c = new Client();
c.onSession(token -> { /* 应用保存 */ });
c.onMessage(msg -> System.out.println(msg.id + " " + msg.body.data));
c.connect("ws://127.0.0.1:7443/mqtt", "device-1", "secret", null)
    .thenCompose(v -> {
        Types.SendOptions opt = new Types.SendOptions();
        opt.delayMs = 0L;
        return c.send(new Types.Target("endpoint", "device-2"), new Types.Body("hello"), opt);
    })
    .join();
c.close();

命令行示例类：asia.asio.nixmsg.examples.MinimalExample。

行为约定

四种 SDK 同一套对外语义，详见仓库 docs/DEVELOPMENT.md 第 9 节附录「SDK 行为约定」。要点：

• 首次连接默认 30 秒内未握手则停止重连，以 not_connected 失败；Client 可再次 connect。
• 顶号原因一律 taken_over；DISCONNECT 0x8B 可重试；CONNECT 不带 Receive Maximum；心跳默认 30 秒。
• 重连退避只维护一个计数 n：第 n 次等待 min(1s×2^(n-1), 30s)×随机(0.7,1.3)。仅 connect 后第一次可不等待；断线后首次重连也约 1 秒；在线不足 60 秒断开则 n+1，稳定 60 秒后断开 n=1。
• rate_limited 与断线重交：每次重新生成 rid 并重新序列化；消息 id、正文、send_at_ms 不变。
• logout 请求失败时 future 以异常完成；本地仍停止重连、清空令牌、结束队列并发 offline。
• 时长与时间戳用 long / Long（含 updateSelf 的 defaultDelayMs）。sendAt 是本机时间（epoch 毫秒或 java.util.Date，入队时加偏差）；sendAtMs 是服务器时间。两者与 delayMs 同时给时本地 bad_request。停止重连后再 send 立即失败。
• 取消尚未发出的条目即出队；已发出的返回 result_unknown，应用应以同一消息号重试。

打包（不发布）

mvn package -DskipTests
# 产物 target/nixmsg-sdk-0.1.0.jar；勿部署到 Maven 仓库；正式发布由总控在阶段 3 执行

确认字节码为 8：javap -v target/classes/asia/asio/nixmsg/Client.class | findstr major（应为 52）。

测试

mvn test

含假传输单元测试与 DEVELOPMENT 第 9 节接入清单（会编译并启动真实 nixmsg）。可用环境变量 NIXMSG_BIN 指定已编译二进制。跳过仅 JS 的跨域项。

许可证

见 LICENSE（Proprietary）。