njs-modbus 3.3.0 → 4.0.0

package/README.zh-CN.md

@@ -1,429 +1,412 @@
 # njs-modbus
 
-[English](./README.md) | 简体中文
-
-Node.js 的纯 JavaScript Modbus 实现。
-
-<!-- prettier-ignore-start -->
-[![npm download](http://img.shields.io/npm/dw/njs-modbus.svg?style=flat-square)](http://www.npm-stats.com/~packages/njs-modbus)
-[![npm latest package](http://img.shields.io/npm/v/njs-modbus/latest.svg?style=flat-square)](https://www.npmjs.com/package/njs-modbus)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/njs-modbus?style=flat-square)](https://bundlephobia.com/package/njs-modbus)
-[![CI](https://img.shields.io/github/actions/workflow/status/xiejay97/njs-modbus/ci.yml?branch=main&style=flat-square)](https://github.com/xiejay97/njs-modbus/actions)
-<!-- prettier-ignore-end -->
-
-## 特性
-
-- **协议：** Modbus TCP、RTU、ASCII
-- **传输：** 串口、TCP 客户端/服务端、UDP 客户端/服务端
-- **主站：** FIFO 或流水线并发请求（协议必须为 TCP）
-- **从站：** 每连接 FIFO 或并发处理（协议必须为 TCP）
-- **自定义功能码**，支持可插拔帧解析
-- **广播**（单元号 = 0）
-- **完整 TypeScript**
-- **零运行时依赖**（仅在使用串口时 peer-depends `serialport`）
-
-| 码值 | 名称 |
-|------|------|
-| 01 | 读取线圈 |
-| 02 | 读取离散输入 |
-| 03 | 读取保持寄存器 |
-| 04 | 读取输入寄存器 |
-| 05 | 写单个线圈 |
-| 06 | 写单个寄存器 |
-| 15 | 写多个线圈 |
-| 16 | 写多个寄存器 |
-| 17 | 报告服务器 ID |
-| 22 | 掩码写寄存器 |
-| 23 | 读/写多个寄存器 |
-| 43/14 | 读取设备标识 |
+[![License](https://img.shields.io/badge/License-BSL%201.1-orange.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Runtime-Node%20%3E%3D18.19-339933.svg?logo=nodedotjs)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178C6.svg?logo=typescript)](https://www.typescriptlang.org/)
+[![Modbus](https://img.shields.io/badge/Modbus-TCP%20%7C%20RTU%20%7C%20ASCII%20%7C%20TLS-555555.svg)](https://modbus.org/)
 
-## 安装
+[English](README.md) | **中文**
+
+> 面向 Node.js 的生产级、热路径零 GC Modbus 协议栈 —— 支持 TCP、RTU、ASCII，可运行在 TCP、UDP、TLS、串口或任何可被建模为字节管道的自定义传输层之上。
+
+`njs-modbus` 使用严格 TypeScript 编写，目标运行时为 Node.js `>=18.19`。其设计充分考虑了工业现场常见的 GC 抖动、静默帧损坏和非受控总线访问等实际约束：确定性时延、流式帧恢复、可编程访问控制与审计日志均内置于核心。
+
+采用 **Business Source License 1.1（BSL 1.1）** 许可。个人、教育机构、非营利组织以及年营收低于 100 万美元的企业，可免费用于开发、测试及生产环境。更大规模组织可购买专有商业许可。每个版本在其 Change Date 之后自动转为 **Apache-2.0** 许可。
+
+---
+
+## 目录
 
-需要 **Node.js ≥ 18.19**。
+- [njs-modbus 是什么？](#njs-modbus-是什么)
+- [为什么选择 njs-modbus？](#为什么选择-njs-modbus)
+- [功能矩阵](#功能矩阵)
+- [安装](#安装)
+- [快速开始](#快速开始)
+  - [TCP 主站](#tcp-主站)
+  - [TCP 从站](#tcp-从站)
+  - [串口 RTU](#串口-rtu)
+- [架构](#架构)
+- [核心能力](#核心能力)
+- [支持的功能码](#支持的功能码)
+- [基准测试](#基准测试)
+- [安全与合规](#安全与合规)
+- [商业支持与许可](#商业支持与许可)
+
+---
+
+## njs-modbus 是什么？
+
+`njs-modbus` 是一个面向 Node.js 的分层 Modbus 协议库。协议层只与 Buffer 打交道，不感知任何底层物理设备。这意味着同一套主站/从站逻辑可以跑在 TCP、UDP、TLS、串口、WebSocket、内存 mock 或任何其他传输层之上 —— 你只需在 `AbstractPipelineAdapter` 接口后实现一次传输层，即可无需改动地复用完整协议栈。
+
+```
+┌─────────────────────────────────────────────┐
+│  应用层：ModbusMaster / ModbusSlave          │
+├─────────────────────────────────────────────┤
+│  协议帧层：TCP / RTU / ASCII                 │
+├─────────────────────────────────────────────┤
+│  管道层：AbstractPipelineAdapter             │
+├─────────────────────────────────────────────┤
+│  物理传输层：TCP / UDP / TLS /               │
+│  串口 / WebSocket / 自定义                   │
+└─────────────────────────────────────────────┘
+```
+
+- **严格 TypeScript** —— 协议类型字面量（`'TCP' | 'RTU' | 'ASCII'`）与类型化 Promise API，可在编译期发现大多数集成错误。
+- **热路径零 GC 解码** —— 显式有限状态机帧同步，在稳态运行期间不在 JavaScript 堆上分配对象或 Buffer。
+- **传输层无关** —— 一个适配器接口，任意物理链路。
+
+---
+
+## 为什么选择 njs-modbus？
+
+| 关注点 | 你能获得什么 |
+| --- | --- |
+| **确定性性能** | 解码路径零 GC、编码路径低分配，编解码 P50 时延低于 1 微秒，热路径无垃圾回收停顿。 |
+| **生产级帧同步** | 流式状态机可从脏数据、粘包、残帧、跨边界分片以及 CRC/LRC 损坏中自愈，不会把无效数据泄漏到相邻帧。 |
+| **类型安全** | 严格 TypeScript + 类型化 Promise API，多数集成错误在编译期即可发现。 |
+| **访问控制与审计** | unit、地址、运行时三道闸门策略钩子，以及从站结构化 `accessAudit` 事件，满足合规与溯源需求。 |
+| **传输层自由** | TCP、UDP、TLS、串口或自定义传输，统一通过 `AbstractPipelineAdapter` 接入，协议逻辑始终不变。 |
+| **商业许可清晰** | BSL 1.1：个人、非营利机构及小企业免费使用；大型组织可购买商业许可；Change Date 后自动转为 Apache-2.0。 |
+
+---
+
+## 功能矩阵
+
+| 能力 | TCP | RTU | ASCII |
+| --- | :---: | :---: | :---: |
+| 主站 / 客户端 | ✅ | ✅ | ✅ |
+| 从站 / 服务端 | ✅ | ✅ | ✅ |
+| 并发流水线 | ✅ | — | — |
+| 广播（`unit === 0`） | ✅ | ✅ | ✅ |
+| 自定义功能码 | ✅ | ✅* | ✅ |
+| 流式帧恢复 | ✅ | ✅ | ✅ |
+
+\* RTU 自定义功能码需要提供 `determineFrameLength` 回调，以便帧状态机在不缓冲的情况下确定帧长度。
+
+由于协议层与传输层解耦，任意协议（TCP / RTU / ASCII）都可以运行在任意提供管道适配器的传输层之上。内置传输包括 TCP、UDP、TLS（基于 TCP）和串口；WebSocket 示例展示了一套自定义适配器。
+
+---
+
+## 安装
 
 ```bash
 npm install njs-modbus
 ```
 
-使用串口传输时，还需安装 peer dependency：
+串口支持通过可选的对等依赖提供：
 
 ```bash
 npm install serialport
 ```
 
+需要 Node.js `>=18.19`。
+
+---
+
 ## 快速开始
 
 ### TCP 主站
 
 ```typescript
-import { ModbusMaster } from 'njs-modbus';
-
-const master = new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },
+import { ModbusMaster, TcpClientPhysicalLayer } from 'njs-modbus';
+
+const physical = new TcpClientPhysicalLayer();
+
+physical.on('connect', async (pipeline) => {
+  const master = new ModbusMaster({
+    pipelineAdapter: pipeline,
+    protocol: { type: 'TCP' },
+    queueStrategy: 'concurrent',
+    timeout: 1000,
+  });
+
+  try {
+    const response = await master.readHoldingRegisters(1, 0, 10);
+    console.log('registers:', response.data);
+  } catch (err) {
+    console.error('request failed:', (err as Error).message);
+  } finally {
+    master.destroy();
+    physical.close();
+  }
 });
 
-await master.open({ port: 502, host: '192.168.1.10' });
-
-const res = await master.readHoldingRegisters(1, 0, 10);
-console.log(res.data);
-
-await master.close();
+physical.open({ host: '127.0.0.1', port: 502 }, (err) => {
+  if (err) {
+    console.error('failed to connect:', err.message);
+    process.exit(1);
+  }
+});
 ```
 
 ### TCP 从站
 
 ```typescript
-import { ModbusSlave } from 'njs-modbus';
+import { ModbusSlave, TcpServerPhysicalLayer } from 'njs-modbus';
 
-const slave = new ModbusSlave({
-  physical: { type: 'TCP_SERVER' },
-  protocol: { type: 'TCP' },
-});
+const physical = new TcpServerPhysicalLayer();
 
-slave.add({
-  unit: 1,
-  readHoldingRegisters: (address, length) => {
-    return Array.from({ length }, (_, i) => address + i);
-  },
+physical.on('connect', (pipeline) => {
+  const slave = new ModbusSlave({
+    pipelineAdapter: pipeline,
+    protocol: { type: 'TCP' },
+    queueStrategy: 'drop-stale',
+  });
+
+  slave.addUnit(1, {
+    readHoldingRegisters: (address, length, callback) => {
+      const values = Array.from({ length }, (_, i) => (address + i) & 0xffff);
+      callback(null, values);
+    },
+    writeSingleRegister: (address, value, callback) => {
+      console.log(`write ${value} to ${address}`);
+      callback(null);
+    },
+  });
 });
 
-await slave.open({ port: 502 });
+physical.open({ port: 502 }, (err) => {
+  if (err) {
+    console.error('failed to listen:', err.message);
+    process.exit(1);
+  }
+  console.log('slave listening on port 502');
+});
 ```
 
-### 串口 RTU 主站
+### 串口 RTU
 
 ```typescript
-const master = new ModbusMaster({
-  physical: {
-    type: 'SERIAL',
-    opts: { path: '/dev/ttyUSB0', baudRate: 9600 },
-  },
-  protocol: { type: 'RTU' },
-});
+import { ModbusMaster, SerialPhysicalLayer } from 'njs-modbus';
 
-await master.open();
-const res = await master.readHoldingRegisters(1, 0, 10);
-await master.close();
-```
+const physical = new SerialPhysicalLayer();
 
-### RTU over TCP
+physical.on('connect', async (pipeline) => {
+  const master = new ModbusMaster({
+    pipelineAdapter: pipeline,
+    protocol: { type: 'RTU' },
+    queueStrategy: 'fifo',
+    timeout: 500,
+  });
 
-```typescript
-const master = new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'RTU' },
+  const res = await master.readHoldingRegisters(1, 0, 10);
+  console.log('registers:', res.data);
+
+  master.destroy();
+  physical.close();
 });
+
+physical.open({ path: '/dev/ttyUSB0', baudRate: 115200 });
 ```
 
-## 物理层
+[`examples/`](https://github.com/xiejay97/njs-modbus/tree/main/examples) 目录包含可运行的主站/从站示例，涵盖访问控制、审计日志、TLS 以及 WebSocket 等自定义传输层。
 
-所有物理层暴露 `open()` / `close()`、`state` 属性，以及事件：`'open'`、`'connect'`、`'close'`、`'error'`。
+---
 
-| 类型 | 类 | `open(...)` 参数 |
-|------|-------|-----------------|
-| `SERIAL` | `SerialPhysicalLayer` | 无 |
-| `TCP_CLIENT` | `TcpClientPhysicalLayer` | `SocketConnectOpts` |
-| `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
-| `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
-| `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
-| `CUSTOM` | *(用户自定义)* | *(自定义)* |
+## 架构
 
-### 服务端配置
+库体被组织为四层。每层相互独立、可单独测试、可替换。
 
-```typescript
-const slave = new ModbusSlave({
-  physical: {
-    type: 'TCP_SERVER',
-    opts: {
-      whitelist: ['192.168.1.10', '10.0.0.5'], // IPv4-mapped IPv6 自动规范化
-      maxConnections: 10,
-      idleTimeout: 30000, // 驱逐不活跃连接，0 = 禁用
-    },
-  },
-  protocol: { type: 'TCP' },
-});
-```
+| 层级 | 职责 | 公共契约 |
+| --- | --- | --- |
+| **物理层** | 打开/关闭链路，并为每个连接抛出一个管道实例。 | `AbstractPhysicalLayer` |
+| **管道层** | 搬运原始字节、处理背压，暴露 `write(data)` + `data` 事件接口。 | `AbstractPipelineAdapter` / `AbstractPipelineLayer` |
+| **协议层** | 解析帧、校验 CRC/LRC/MBAP，并抛出完整 ADU。 | `TcpProtocolLayer` / `RtuProtocolLayer` / `AsciiProtocolLayer` |
+| **应用层** | 编排事务、队列、访问控制，并对外暴露 Promise API。 | `ModbusMaster` / `ModbusSlave` |
 
-### 物理层选项
+这种分层让自定义传输层变得极为简单。[`examples/websocket/`](https://github.com/xiejay97/njs-modbus/tree/main/examples/websocket) 中的 WebSocket 示例在 150 行内实现了一套完整管道层。
 
-| 选项 | 类型 | 说明 |
-|--------|------|-------------|
-| `whitelist` | `string[]` | 允许的客户端 IP。`::ffff:` 前缀自动剥离。 |
-| `maxConnections` | `number` | 最大并发连接数。超出后新连接静默丢弃。 |
-| `idleTimeout` | `number` | 空闲超时（毫秒），超时后驱逐连接。默认 `30000`，传 `0` 禁用。 |
-| `socketOpts` / `serverOpts` | `object` | 透传给 Node.js `createSocket()` / `createServer()`。 |
+---
 
-## 自定义物理层
+## 核心能力
 
-任何面向字节的传输层都可以通过实现 `AbstractPhysicalLayer` 和 `AbstractPhysicalConnection` 来使用，然后传入 `{ type: 'CUSTOM', layer: yourLayer }`。
+### 低分配编解码热路径
 
-```typescript
-import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
+TCP、RTU、ASCII 的协议帧层均以显式有限状态机实现。解码路径在稳态运行期间不在 JavaScript 堆上分配对象或 Buffer（通过预分配残量缓冲与零拷贝视图实现），从而彻底消除热路径上的 GC 抖动断点。编码路径每帧执行一次有界的 `Buffer.allocUnsafe()` 分配。
 
-class MyPhysicalLayer extends AbstractPhysicalLayer { /* open / close */ }
-class MyConnection extends AbstractPhysicalConnection { /* write / destroy, emit 'data' */ }
+### 流式帧恢复
 
-const master = new ModbusMaster({
-  physical: { type: 'CUSTOM', layer: new MyPhysicalLayer() },
-  protocol: { type: 'TCP' },
-});
-```
+帧层以流式方式解析输入字节，可在以下场景中自愈：
 
-查看 [`examples/websocket`](./examples/websocket) 获取完整的 **WebSocket 承载 Modbus TCP** 实现——包含客户端/服务端物理层及可运行的演示。
+- 线路上注入的脏数据。
+- 一次读取中多个有效帧粘连（`sticky`）。
+- 残帧后接有效帧。
+- 一个帧被拆分到多次读取中（跨边界分片）。
+- CRC（RTU）或 LRC（ASCII）损坏。
 
-查看 [`examples/bluetooth`](./examples/bluetooth) 获取 **BLE 承载 Modbus TCP** 实现（基于 Nordic UART Service），包含无需真实蓝牙硬件即可运行的回环测试。
+有效帧会被正常抛出，无效数据被丢弃，不会污染相邻帧。
 
-## 主站 API
+### 队列策略
 
-```typescript
-new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
-  timeout?: 1000,                     // 单次请求超时（毫秒）
-  concurrent?: false,                 // 流水线模式（协议：仅 TCP）
-})
-```
+`ModbusMaster` 与 `ModbusSlave` 均支持四种队列策略：
 
-RTU 帧选项：
+| 策略 | 行为 | 适用场景 |
+| --- | --- | --- |
+| `fifo` | 严格先进先出执行。 | 串口线路、确定性顺序。 |
+| `drop-stale` | 新请求到达时清空所有未执行的旧请求。 | 只需最新值的遥测采集。 |
+| `deduplicate` | 相同 ADU 指纹的待处理请求会被去重丢弃。 | 可能重叠的轮询循环。 |
+| `concurrent` | 请求并发派发。 | Modbus TCP 或多链路主站/从站。 |
 
-```typescript
-protocol: {
-  type: 'RTU',
-  opts: {
-    // 既可以传裸数字（毫秒），也可以传 `{ unit: 'bit' | 'ms', value: N }`。
-    // 传 `0` 显式禁用该定时器（适用于 RTU-over-TCP 等无丢包传输）。
-    intervalBetweenFrames: 20,                          // 20 毫秒
-    interCharTimeout: { unit: 'bit', value: 10 },       // 按 bit-time，需 baudRate
-    poolSize: 1024,
-  },
-}
-```
+默认策略为 `drop-stale`。
 
-ASCII 选项：
+### 每 unit 写范围锁
 
-```typescript
-protocol: {
-  type: 'ASCII',
-  opts: {
-    lenientHex: true, // 接受小写十六进制 (a-f)。默认：false（按规范仅大写）
-  },
-}
-```
+对于 `concurrent` 模式下的从站，`enableWriteRangeLock`（默认 `true`）确保同一 unit 上地址范围重叠的写请求（FC05/06/15/16/22/23）被序列化，防止竞态条件。这对于在多个连接同时修改共享寄存器或线圈时保持一致性至关重要。仅对于不需要协调开销的纯同步内存从站，才设置为 `false`。
+
+### 访问控制与审计
 
-### 方法
-
-| 方法 | 说明 |
-|--------|-------------|
-| `open(...args)` | 打开物理层。只能调用一次；`close()` 后实例永久失效。 |
-| `close()` | 立即关闭。进行中和队列中的请求会被 reject。 |
-| `readCoils(unit, address, length, timeout?)` | FC 01 |
-| `readDiscreteInputs(unit, address, length, timeout?)` | FC 02 |
-| `readHoldingRegisters(unit, address, length, timeout?)` | FC 03 |
-| `readInputRegisters(unit, address, length, timeout?)` | FC 04 |
-| `writeSingleCoil(unit, address, value, timeout?)` | FC 05 |
-| `writeSingleRegister(unit, address, value, timeout?)` | FC 06 |
-| `writeMultipleCoils(unit, address, values, timeout?)` | FC 15 |
-| `writeMultipleRegisters(unit, address, values, timeout?)` | FC 16 |
-| `reportServerId(unit, serverIdLength?, timeout?)` | FC 17 |
-| `maskWriteRegister(unit, address, andMask, orMask, timeout?)` | FC 22 |
-| `readAndWriteMultipleRegisters(unit, read, write, timeout?)` | FC 23 |
-| `readDeviceIdentification(unit, readDeviceIDCode, objectId, timeout?)` | FC 43/14 |
-| `sendCustomFC(unit, fc, data, timeout?)` | 发送用户自定义功能码 |
-| `addCustomFunctionCode(cfc)` | 注册自定义功能码用于帧解析 |
-| `removeCustomFunctionCode(fc)` | 注销自定义功能码 |
-
-广播（`unit = 0`）resolve `void` — 从站不响应。
-
-## 从站 API
+在主站或从站上安装 `AccessAuthorizer`，可在三道闸门上执行策略：
+
+- `checkUnit` —— 授权目标单元地址。
+- `checkAddress` —— 授权请求触及的地址区间。
+- `checkRuntime` —— 在真正发起写 I/O 前的最后机会检查。
+
+每个钩子可返回 `true`、`false` 或数字形式的 Modbus 异常 `ErrorCode`。在从站上，被拒绝的请求会触发 `accessAudit` 事件。
 
 ```typescript
-new ModbusSlave({
-  physical: { type: 'TCP_SERVER' },
-  protocol: { type: 'TCP' },
-  concurrent?: false, // 每连接并发（协议：仅 TCP）
-})
+slave.setAccessAuthorizer({
+  checkUnit: (unit) => unit === 1,
+  checkAddress: (_unit, table, [start, end]) =>
+    table === 'holdingRegisters' && start >= 0 && end < 100,
+});
+
+slave.on('accessAudit', (event) => {
+  console.log('access denied:', event.type, event.message);
+});
 ```
 
-### 注册模型
+### 自定义功能码
 
-```typescript
-slave.add({
-  unit: 1,
+在主站或从站上注册非标准功能码。帧层会学习请求形状，应用层则拿到原始 PDU 进行解析与响应。
 
-  // 可选：在默认分发前拦截任意功能码
-  interceptor?: (fc, data) => Buffer | undefined,
+```typescript
+slave.addCustomFunctionCode(
+  { fc: 0x65 },
+  (unit, fc, data, callback) => {
+    // 构造响应 PDU 字节
+    callback(null, () => Buffer.from([0x00]));
+  },
+);
+```
 
-  readCoils?: (address, length) => boolean[] | Uint8Array,
-  readDiscreteInputs?: (address, length) => boolean[] | Uint8Array,
-  readHoldingRegisters?: (address, length) => number[] | Uint16Array,
-  readInputRegisters?: (address, length) => number[] | Uint16Array,
+对于 RTU（以及面向字节传输的 ASCII），描述符还需提供 `determineFrameLength`，以便帧状态机在不缓冲的情况下确定帧长度。
 
-  writeSingleCoil?: (address, value) => void,
-  writeMultipleCoils?: (address, values) => void,
+---
 
-  writeSingleRegister?: (address, value) => void,
-  writeMultipleRegisters?: (address, values) => void,
+## 支持的功能码
 
-  maskWriteRegister?: (address, andMask, orMask) => void,
+| FC | 名称 | 主站 | 从站 |
+| --: | --- | :---: | :---: |
+| 01 | Read Coils | ✅ | ✅ |
+| 02 | Read Discrete Inputs | ✅ | ✅ |
+| 03 | Read Holding Registers | ✅ | ✅ |
+| 04 | Read Input Registers | ✅ | ✅ |
+| 05 | Write Single Coil | ✅ | ✅ |
+| 06 | Write Single Register | ✅ | ✅ |
+| 08/00 | Return Query Data | ✅ | ✅ |
+| 15 | Write Multiple Coils | ✅ | ✅ |
+| 16 | Write Multiple Registers | ✅ | ✅ |
+| 17 | Report Server ID | ✅ | ✅ |
+| 22 | Mask Write Register | ✅ | ✅ |
+| 23 | Read/Write Multiple Registers | ✅ | ✅ |
+| 43/14 | Read Device Identification | ✅ | ✅ |
 
-  reportServerId?: () => ServerId,
-  readDeviceIdentification?: () => { [index: number]: string },
+---
 
-  // 可选地址范围校验
-  getAddressRange?: () => ({
-    discreteInputs?: [number, number] | [number, number][];
-    coils?: [number, number] | [number, number][];
-    inputRegisters?: [number, number] | [number, number][];
-    holdingRegisters?: [number, number] | [number, number][];
-  }),
-});
-```
+## 基准测试
 
-缺失的处理器返回 `ILLEGAL_FUNCTION`。越界地址返回 `ILLEGAL_DATA_ADDRESS`。处理器抛出的异常变为 `SERVER_DEVICE_FAILURE`，除非错误是 `ModbusError`。
+以下全部数据由本仓库的基准测试套件在 **AMD Ryzen 7 9800X3D** 工作站上、**Node.js v24.16.0** 环境下测得。完整报告、测试方法与复现说明见 [`benchmark/report_presentation.md`](benchmark/report_presentation.md)。
 
-| 方法 | 说明 |
-|--------|-------------|
-| `add(model)` | 注册从站模型 |
-| `remove(unit)` | 移除从站模型 |
-| `open(...args)` | 打开物理层。一次性：close() 后不可重新打开。 |
-| `close()` | 立即关闭 |
-| `addCustomFunctionCode(cfc)` | 注册自定义功能码 |
-| `removeCustomFunctionCode(fc)` | 注销自定义功能码 |
+### 编解码微基准
 
-## 自定义功能码
+纯 CPU 编解码测试，无网络 I/O。每次操作都在亚微秒级别完成，因此 `Ops/sec` 和 `CPU (µs/op)` 是可靠指标；此量级下的单次时延主要由 `process.hrtime` 开销主导，故省略。
 
-`predictRequestLength` / `predictResponseLength` 接收共享池缓冲区及字节偏移量（`start`、`end`）。边界检查应使用 `end - start` 而非 `buffer.length`。
+| 测试项 | Ops/sec | CPU (µs/op) |
+| --- | ---: | ---: |
+| TCP 请求编码 | 9.37 M | 0.11 |
+| TCP 响应编码 | 7.83 M | 0.13 |
+| TCP 请求解码 | 8.83 M | 0.11 |
+| TCP 响应解码 | 8.90 M | 0.11 |
+| RTU 请求编码 | 9.12 M | 0.11 |
+| RTU 响应编码 | 1.91 M | 0.53 |
+| RTU 请求解码 | 8.53 M | 0.12 |
+| RTU 响应解码 | 1.98 M | 0.51 |
+| ASCII 请求编码 | 8.83 M | 0.11 |
+| ASCII 响应编码 | 2.44 M | 0.42 |
+| ASCII 请求解码 | 7.84 M | 0.13 |
+| ASCII 响应解码 | 2.53 M | 0.4 |
 
-```typescript
-import type { CustomFunctionCode } from 'njs-modbus';
+所有编解码测试项的 `GC (ns/op)` 均为零，因为稳态运行期间解码路径不在 JavaScript 堆上分配内存。
 
-const cfc: CustomFunctionCode = {
-  fc: 0x50,
-  predictRequestLength: (buffer, start, end) => {
-    if (end - start < 2) return null;
-    return 4 + buffer[start + 1];
-  },
-  predictResponseLength: (buffer, start, end) => {
-    if (end - start < 2) return null;
-    return 4 + buffer[start + 1];
-  },
-  handle: async (data, unit) => {
-    return Buffer.from([data[1], data[0]]);
-  },
-};
+### 端到端传输吞吐
 
-// 从站：帧解析 + 分发
-slave.addCustomFunctionCode(cfc);
+FC 03（读取 50 个保持寄存器），TCP 走本地回环，串口通过 115200 波特率的 `socat` PTY 对进行测试。
 
-// 主站：仅帧解析
-master.addCustomFunctionCode(cfc);
-const response = await master.sendCustomFC(1, 0x50, [0xab, 0xcd]);
-```
+| 传输层 | 协议栈 | Ops/sec | P50 (µs) | P99 (µs) |
+| --- | --- | ---: | ---: | ---: |
+| TCP 顺序 | **njs-modbus** | **94.81 k** | **8.7** | **43.9** |
+| TCP 顺序 | jsmodbus | 59.59 k | 13.6 | 65.7 |
+| TCP 顺序 | modbus-serial | 867 | 1,150.5 | 1,244.5 |
+| TCP 8 连接 | **njs-modbus** | **109.23 k** | **60.7** | **179.8** |
+| TCP 8 连接 | jsmodbus | 63.84 k | 102.6 | 299.7 |
+| TCP 8 连接 | modbus-serial | 6.37 k | 1,241.3 | 1,437.6 |
+| RTU 顺序 | **njs-modbus** | **104** | **514.5** | **852.8** |
+| RTU 顺序 | jsmodbus | 104 | 546.4 | 927.3 |
+| RTU 顺序 | modbus-serial | 31 | 31,903.6 | 32,219.3 |
+| ASCII 顺序 | **njs-modbus** | **51** | **556.1** | **947.9** |
 
-## 错误处理
+### 混沌弹性
 
-```typescript
-import { ErrorCode, ModbusError, getErrorByCode } from 'njs-modbus';
-
-// ErrorCode.ILLEGAL_FUNCTION          = 0x01
-// ErrorCode.ILLEGAL_DATA_ADDRESS      = 0x02
-// ErrorCode.ILLEGAL_DATA_VALUE        = 0x03
-// ErrorCode.SERVER_DEVICE_FAILURE     = 0x04
-// ErrorCode.ACKNOWLEDGE               = 0x05
-// ErrorCode.SERVER_DEVICE_BUSY        = 0x06
-// ErrorCode.MEMORY_PARITY_ERROR       = 0x08
-// ErrorCode.GATEWAY_PATH_UNAVAILABLE  = 0x0a
-// ErrorCode.GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 0x0b
-
-slave.add({
-  unit: 1,
-  readHoldingRegisters: (address) => {
-    if (address > 100) {
-      throw getErrorByCode(ErrorCode.ILLEGAL_DATA_ADDRESS);
-    }
-    return [42];
-  },
-});
-```
+混沌套件向真实 Modbus 服务器注入损坏、分片、粘包及脏数据帧，验证有效帧能否在无泄漏的情况下被正确恢复。
 
-## 性能
+| 协议 | 通过场景数 |
+| --- | ---: |
+| TCP | 12 / 12 |
+| RTU | 12 / 12 |
+| ASCII | 14 / 14 |
 
-与 [jsmodbus](https://github.com/Cloud-Automation/node-modbus) 和 [modbus-serial](https://github.com/yaacov/node-modbus-serial) 的对比。
+本地复现完整测试：
 
-| 指标 | njs-modbus | jsmodbus | modbus-serial |
-|------|-----------|----------|---------------|
-| TCP 吞吐量 | **70,544 ops/sec** | 39,827 (0.56x) | 786 (0.01x) |
-| TCP P99 延迟 | **53 µs** | 98 µs (1.83x) | 2,331 µs (43.7x) |
-| 并发 (8 连接) | **75,810 ops/sec** | 41,754 (0.55x) | 5,620 (0.07x) |
-| RTU 串口 (115200 波特率) | **44 ops/sec** | 44 ops/sec | 45 ops/sec |
-| TCP 响应编码 | **6.57M ops/sec** | 1.22M (0.19x) | 1.18M (0.18x) |
-| TCP 响应解码 | **6.78M ops/sec** | 1.94M (0.29x) | 0.67M (0.10x) |
-| FC01 读取线圈 | **85,170 ops/sec** | 617 (0.01x) | 861 (0.01x) |
+```bash
+npm run benchmark:full
+```
 
-<details>
-<summary>完整基准测试结果</summary>
+---
 
-Node.js v24.16.0 · AMD Ryzen 7 9800X3D · linux x64 · 3 次运行 × 120 秒 · [完整报告](./benchmark/RESULTS.md)
+## 安全与合规
 
-### TCP 吞吐量（单连接）
+`njs-modbus` 是一个纯 Modbus 协议栈。面向受监管环境，它通过 `AccessAuthorizer` 提供协议层策略执行点，并通过从站 `accessAudit` 事件提供可审计轨迹：
 
-```
-njs-modbus    │ ██████████████████████████████ 70,544 ops/sec 🏆   p99: 53 µs   CPU: 91 µs/op
-jsmodbus      │ █████████████████░░░░░░░░░░░░░ 39,827 ops/sec (0.56x)  p99: 98 µs   CPU: 161 µs/op
-modbus-serial │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    786 ops/sec (0.01x)  p99: 2,331 µs CPU: 8,176 µs/op
-```
+- `checkUnit` —— 授权目标单元地址。
+- `checkAddress` —— 授权请求触及的地址区间。
+- `checkRuntime` —— 在真正发起写 I/O 前的最后机会检查。
 
-### 并发（8 连接）
+被拒绝的请求会触发结构化 `accessAudit` 事件，可转发至 SIEM 或审计日志。这有助于在不引入外部代理的情况下，满足工业控制（OT）安全与合规要求。
 
-```
-njs-modbus    │ ██████████████████████████████ 75,810 ops/sec 🏆   p99: 258 µs  CPU: 91 µs/op
-jsmodbus      │ █████████████████░░░░░░░░░░░░░ 41,754 ops/sec (0.55x)  p99: 543 µs  CPU: 167 µs/op
-modbus-serial │ ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░  5,620 ops/sec (0.07x)  p99: 3,180 µs CPU: 1,237 µs/op
-```
+`njs-modbus` 同时内置 **TLS 传输插件**（`TlsClientPhysicalLayer` / `TlsServerPhysicalLayer`），基于 `node:tls` 实现，因此在提供证书与 TLS 选项的前提下，可直接建立加密的 Modbus TCP 连接并支持双向 TLS。证书生命周期管理、网络身份、主机加固与物理安全仍由宿主应用和基础设施负责。
 
-### RTU 串口（socat PTY 模拟 115200 波特率）
+- [`SECURITY.md`](SECURITY.md) —— 漏洞报告、协调披露与安全更新策略。
+- [`docs/security/`](https://github.com/xiejay97/njs-modbus/tree/main/docs/security) —— 访问控制、审计事件、TLS 使用、部署补偿控制与 SDL。
 
-```
-njs-modbus    │ 44 ops/sec   p99: 993 µs   CPU: 729 µs/op   GC: 2,613 ns/op
-jsmodbus      │ 44 ops/sec   p99: 1,019 µs  CPU: 694 µs/op   GC: 2,609 ns/op
-modbus-serial │ 45 ops/sec   p99: 3,228 µs  CPU: 765 µs/op   GC: 3,864 ns/op
-```
+`examples/security/` 目录包含可运行的主站/从站示例，包括 TLS 与传输层安全选项。
 
-### 帧编码 / 解码（CPU 微基准测试）
+---
 
-```
-tcpReqEncode:  njs-modbus 6.90M ops/sec 🏆  jsmodbus 0.78x  modbus-serial 0.19x
-tcpResEncode:  njs-modbus 6.57M ops/sec 🏆  jsmodbus 0.19x  modbus-serial 0.18x
-tcpReqDecode:  njs-modbus 6.80M ops/sec 🏆  jsmodbus 0.81x  modbus-serial 0.17x
-tcpResDecode:  njs-modbus 6.78M ops/sec 🏆  jsmodbus 0.29x  modbus-serial 0.10x
-rtuReqEncode:  njs-modbus 7.26M ops/sec 🏆  jsmodbus 0.35x  modbus-serial 0.76x
-rtuReqDecode:  njs-modbus 3.97M ops/sec     jsmodbus 1.21x  modbus-serial 1.78x 🏆
-asciiReqEncode: njs-modbus 5.64M ops/sec 🏆  modbus-serial 0.57x
-asciiReqDecode: njs-modbus 3.37M ops/sec 🏆  modbus-serial 0.34x
-```
+## 商业支持与许可
 
-### 全功能码 TCP 吞吐量（常规负载）
+`njs-modbus` 采用 [Business Source License 1.1（BSL 1.1）](LICENSE) 发布。
 
-| 功能码 | njs-modbus | jsmodbus | modbus-serial |
-|--------|-----------|----------|---------------|
-| FC01 读取线圈 | **85,170** 🏆 | 617 (0.01x) | 861 (0.01x) |
-| FC02 读取离散输入 | **85,570** 🏆 | 525 (0.01x) | 861 (0.01x) |
-| FC03 读取保持寄存器 | **75,344** 🏆 | 40,081 (0.53x) | 852 (0.01x) |
-| FC04 读取输入寄存器 | **75,757** 🏆 | 49,524 (0.65x) | 866 (0.01x) |
-| FC05 写单个线圈 | **92,852** 🏆 | 53,521 (0.58x) | 871 (0.01x) |
-| FC06 写单个寄存器 | **92,864** 🏆 | 53,684 (0.58x) | 872 (0.01x) |
-| FC15 写多个线圈 | **86,434** 🏆 | 319 (0.00x) | 869 (0.01x) |
-| FC16 写多个寄存器 | **76,053** 🏆 | 39,356 (0.52x) | 852 (0.01x) |
-| FC17 报告服务器 ID | **74,697** 🏆 | — | — |
-| FC22 掩码写寄存器 | **90,717** 🏆 | — | — |
-| FC23 读/写多个寄存器 | **85,652** 🏆 | — | — |
-| FC43 读取设备标识 | **78,030** 🏆 | — | 865 (0.01x) |
+- **免费生产使用**：授予个人、教育机构、非营利组织以及年营收低于 100 万美元的企业。
+- **Change Date**：2029-06-24。在该日期，本版本将转为 Apache License, Version 2.0。
+- **商业许可**：面向 OEM、系统集成商以及需要可预测许可路径、有保障支持或无法满足 BSL 免费使用条件的商业产品，我们提供独立的专有商业许可。
 
-> FC17 / FC22 / FC23 不受 jsmodbus 和 modbus-serial 支持。
+商业许可可解除 BSL 对您产品的限制，同时我们的支持服务帮助您安心交付：
 
-</details>
+- **产品集成许可** —— 在闭源商业产品中使用 `njs-modbus`，无需承担 copyleft 义务。
+- **专业技术支持** —— 故障排查、性能调优、迁移指导与升级规划。
+- **企业级支持方案** —— 响应 SLA、长期维护版本、优先 Bug 修复与定制开发。
 
-## 许可证
+具体授权条款、报价及支持方案请联系：
 
-[![license](https://img.shields.io/github/license/xiejay97/njs-modbus?style=flat-square)](/LICENSE)
+- 邮箱：[xiejay97@gmail.com](mailto:xiejay97@gmail.com)
+- GitHub Issues：[https://github.com/xiejay97/njs-modbus/issues](https://github.com/xiejay97/njs-modbus/issues)