61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
# NixMsg JavaScript / TypeScript SDK
|
||
|
||
包名 `@nixevol/nixmsg`。支持 Node.js ≥ 20 与浏览器；发布 ESM 与 CJS。
|
||
|
||
## 安装
|
||
|
||
在 `.npmrc` 中：
|
||
|
||
```ini
|
||
@nixevol:registry=https://git.asio.asia/api/packages/nixevol/npm/
|
||
```
|
||
|
||
然后：
|
||
|
||
```bash
|
||
npm install @nixevol/nixmsg
|
||
```
|
||
|
||
许可证字段为 `SEE LICENSE IN LICENSE`（专有），包内附带仓库根目录 `LICENSE` 副本。
|
||
|
||
## 最小示例
|
||
|
||
见 [`example/minimal.mjs`](./example/minimal.mjs)：
|
||
|
||
```js
|
||
import { Client, register } from "@nixevol/nixmsg";
|
||
|
||
const c = new Client();
|
||
c.onSessionHandler((tok) => console.log("session", tok));
|
||
c.onMessageHandler((msg) => console.log("msg", msg.from, msg.body.data));
|
||
await c.connect("ws://127.0.0.1:7443/mqtt", "device-1", { password: "secret" });
|
||
await c.send(
|
||
{ kind: "endpoint", id: "device-2" },
|
||
{ enc: "utf8", data: "hello" },
|
||
{ delayMs: 0 },
|
||
);
|
||
await c.close();
|
||
```
|
||
|
||
浏览器页面与服务器不同源时，注册接口已回 `Access-Control-Allow-Origin: *`，WebSocket `/mqtt` 不校验 Origin，可直接连接。
|
||
|
||
## 行为约定
|
||
|
||
四种 SDK 同一套对外语义，详见仓库 `docs/DEVELOPMENT.md` 第 9 节附录「SDK 行为约定」。要点：
|
||
|
||
- 首次连接默认 30 秒内未握手则停止重连，`connect()` 返回 `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。不要用「attempt 与 base 同时翻倍」。
|
||
- `rate_limited` 与断线重交：每次重新生成 `rid` 并重新序列化；消息 `id`、正文、`send_at_ms` 不变。
|
||
- `logout` 请求失败返回给应用；本地仍停止重连、清空令牌、结束队列并发 `offline`。
|
||
- 时长与时间戳用 64 位整数。`sendAt` 与 `delay` 同时给时本地 `bad_request`。停止重连后再 `send` 立即失败。
|
||
- 取消尚未发出的条目即出队；已发出的返回 `result_unknown`，应用应以同一消息号重试。
|
||
|
||
## 打包试运行
|
||
|
||
```bash
|
||
npm pack --dry-run
|
||
```
|
||
|
||
不要对本仓库执行 `npm publish`（发布由阶段 3 总控完成）。
|