njs-modbus 3.3.0 → 4.0.0

package/README.md

@@ -1,430 +1,412 @@
 # njs-modbus
 
-English | [简体中文](./README.zh-CN.md)
-
-A pure JavaScript implementation of Modbus for Node.js.
-
-<!-- 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 -->
-
-## Features
-
-- **Protocols:** Modbus TCP, RTU, ASCII
-- **Transports:** Serial, TCP client/server, UDP client/server
-- **Master:** FIFO or pipelined concurrent requests (protocol must be TCP)
-- **Slave:** Per-connection FIFO or concurrent processing (protocol must be TCP)
-- **Custom function codes** with pluggable framing
-- **Broadcasting** (unit = 0)
-- **Full TypeScript**
-- **Zero runtime dependencies** (peer-depends on `serialport` for serial)
-
-| Code | Name |
-|------|------|
-| 01 | Read Coils |
-| 02 | Read Discrete Inputs |
-| 03 | Read Holding Registers |
-| 04 | Read Input Registers |
-| 05 | Write Single Coil |
-| 06 | Write Single Register |
-| 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 |
+[![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/)
 
-## Installation
+**English** | [中文](README.zh-CN.md)
+
+> A production-grade, zero-GC Modbus protocol stack for Node.js — TCP, RTU, and ASCII over TCP, UDP, TLS, serial, or any custom transport you can model as a byte pipeline.
+
+`njs-modbus` is written in strict TypeScript and targets Node.js `>=18.19`. Its design is heavily informed by industrial field conditions: deterministic latency, streaming frame recovery, programmable access control, and audit logging are built in from the start.
+
+Licensed under the **Business Source License 1.1 (BSL 1.1)**. Free for development, testing, and production use by individuals, educational institutions, non-profits, and companies with annual gross revenue below US$1M. A proprietary commercial license is available for larger organizations. Every version transitions to **Apache-2.0** on its Change Date.
+
+---
+
+## Table of Contents
 
-Requires **Node.js ≥ 18.19**.
+- [What is njs-modbus?](#what-is-njs-modbus)
+- [Why njs-modbus?](#why-njs-modbus)
+- [Feature Matrix](#feature-matrix)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [TCP Master](#tcp-master)
+  - [TCP Slave](#tcp-slave)
+  - [RTU over Serial](#rtu-over-serial)
+- [Architecture](#architecture)
+- [Core Capabilities](#core-capabilities)
+- [Supported Function Codes](#supported-function-codes)
+- [Benchmarks](#benchmarks)
+- [Security & Compliance](#security--compliance)
+- [Commercial Support & License](#commercial-support--license)
+
+---
+
+## What is njs-modbus?
+
+`njs-modbus` is a layered Modbus protocol library for Node.js. The protocol layer speaks only in buffers and knows nothing about the underlying physical device. That means the same master/slave logic runs over TCP, UDP, TLS, serial, WebSocket, an in-memory mock, or any other transport — you implement the wire once behind the `AbstractPipelineAdapter` interface and reuse the full protocol stack unchanged.
+
+```
+┌─────────────────────────────────────────────┐
+│  Application: ModbusMaster / ModbusSlave    │
+├─────────────────────────────────────────────┤
+│  Protocol framing: TCP / RTU / ASCII        │
+├─────────────────────────────────────────────┤
+│  Pipeline: AbstractPipelineAdapter          │
+├─────────────────────────────────────────────┤
+│  Physical transport: TCP / UDP / TLS /      │
+│  Serial / WebSocket / custom                │
+└─────────────────────────────────────────────┘
+```
+
+- **Strict TypeScript** — generic protocol literals (`'TCP' | 'RTU' | 'ASCII'`) and typed Promise APIs catch integration mistakes at compile time.
+- **Zero-GC decode hot paths** — explicit finite-state-machine framing avoids allocating objects or buffers on the JS heap during steady-state operation.
+- **Transport-agnostic** — one adapter interface, any wire.
+
+---
+
+## Why njs-modbus?
+
+| Concern | What you get |
+| --- | --- |
+| **Deterministic latency** | GC-free decode paths, low-allocation encode, and sub-microsecond P50 codec latency. No garbage-collection pauses on the hot path. |
+| **Production-hardened framing** | Streaming state machines recover from garbage bytes, sticky frames, truncation, cross-boundary chunks, and corrupted CRC/LRC — without leaking invalid data into adjacent frames. |
+| **Type safety** | Strict TypeScript with typed Promise APIs; most integration mistakes surface at compile time. |
+| **Access control & audit** | Policy hooks at unit, address, and runtime gates, plus structured `accessAudit` events on the slave for compliance and forensics. |
+| **Transport freedom** | TCP, UDP, TLS, serial, or custom transports via `AbstractPipelineAdapter`. The protocol logic never changes. |
+| **Commercial clarity** | BSL 1.1: free for individuals, non-profits, and small companies; commercial license available for larger organizations; Apache-2.0 after the Change Date. |
+
+---
+
+## Feature Matrix
+
+| Capability | TCP | RTU | ASCII |
+| --- | :---: | :---: | :---: |
+| Master / client | ✅ | ✅ | ✅ |
+| Slave / server | ✅ | ✅ | ✅ |
+| Concurrent pipelining | ✅ | — | — |
+| Broadcast (`unit === 0`) | ✅ | ✅ | ✅ |
+| Custom function codes | ✅ | ✅* | ✅ |
+| Streaming frame recovery | ✅ | ✅ | ✅ |
+
+\* RTU custom function codes require a `determineFrameLength` callback so the framing state machine can know the frame length without buffering.
+
+Because the protocol layer is transport-agnostic, any protocol (TCP / RTU / ASCII) can run over any transport for which you provide a pipeline adapter. Built-in transports include TCP, UDP, TLS (over TCP), and serial; the WebSocket example demonstrates a custom adapter.
+
+---
+
+## Installation
 
 ```bash
 npm install njs-modbus
 ```
 
-For serial transport, also install the peer dependency:
+Serial support is provided through an optional peer dependency:
 
 ```bash
 npm install serialport
 ```
 
+Requires Node.js `>=18.19`.
+
+---
+
 ## Quick Start
 
 ### TCP Master
 
 ```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 Slave
 
 ```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');
+});
 ```
 
-### Serial RTU Master
+### RTU over Serial
 
 ```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 });
 ```
 
-## Physical Layers
+See [`examples/`](https://github.com/xiejay97/njs-modbus/tree/main/examples) for runnable master/slave pairs, including access control, audit logging, TLS, and custom transports such as WebSocket.
 
-All physical layers expose `open()` / `close()`, a `state` property, and events: `'open'`, `'connect'`, `'close'`, `'error'`.
+---
 
-| Type | Class | `open(...)` args |
-|------|-------|-----------------|
-| `SERIAL` | `SerialPhysicalLayer` | none |
-| `TCP_CLIENT` | `TcpClientPhysicalLayer` | `SocketConnectOpts` |
-| `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
-| `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
-| `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
-| `CUSTOM` | *(user-provided)* | *(user-defined)* |
+## Architecture
 
-### Server options
+The library is organized into four layers. Each layer is independent, testable in isolation, and replaceable.
 
-```typescript
-const slave = new ModbusSlave({
-  physical: {
-    type: 'TCP_SERVER',
-    opts: {
-      whitelist: ['192.168.1.10', '10.0.0.5'], // IPv4-mapped IPv6 normalized automatically
-      maxConnections: 10,
-      idleTimeout: 30000, // evict inactive connections, 0 = disable
-    },
-  },
-  protocol: { type: 'TCP' },
-});
-```
+| Layer | Responsibility | Public Contract |
+| --- | --- | --- |
+| **Physical** | Open/close the wire and emit a pipeline per connection. | `AbstractPhysicalLayer` |
+| **Pipeline** | Move raw bytes, handle back-pressure, and expose a `write(data)` + `data` event surface. | `AbstractPipelineAdapter` / `AbstractPipelineLayer` |
+| **Protocol** | Parse frames, validate CRC/LRC/MBAP, and emit complete ADUs. | `TcpProtocolLayer` / `RtuProtocolLayer` / `AsciiProtocolLayer` |
+| **Application** | Orchestrate transactions, queues, access control, and expose the public Promise API. | `ModbusMaster` / `ModbusSlave` |
 
-### Physical layer options
+This separation is what makes custom transports trivial. The WebSocket example in [`examples/websocket/`](https://github.com/xiejay97/njs-modbus/tree/main/examples/websocket) implements a full pipeline layer in under 150 lines.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `whitelist` | `string[]` | Allowed client IPs. `::ffff:` prefix is stripped automatically. |
-| `maxConnections` | `number` | Max concurrent connections. New connections are silently dropped when exceeded. |
-| `idleTimeout` | `number` | Idle timeout in ms before evicting a connection. Default `30000`. Pass `0` to disable. |
-| `socketOpts` / `serverOpts` | `object` | Forwarded to Node.js `createSocket()` / `createServer()`. |
+---
 
-## Custom Physical Layer
+## Core Capabilities
 
-Any byte-oriented transport can be used by implementing `AbstractPhysicalLayer` and `AbstractPhysicalConnection`, then passing `{ type: 'CUSTOM', layer: yourLayer }`.
+### Low-Allocation Codec Hot Paths
 
-```typescript
-import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
+The protocol framing layers for TCP, RTU, and ASCII are implemented as explicit finite state machines. Decode paths avoid allocating objects or buffers on the JavaScript heap during steady-state operation by using pre-allocated residual buffers and zero-copy views, which removes garbage-collection jitter from the protocol hot path. Encode paths perform a single bounded `Buffer.allocUnsafe()` per frame.
 
-class MyPhysicalLayer extends AbstractPhysicalLayer { /* open / close */ }
-class MyConnection extends AbstractPhysicalConnection { /* write / destroy, emit 'data' */ }
+### Streaming Frame Recovery
 
-const master = new ModbusMaster({
-  physical: { type: 'CUSTOM', layer: new MyPhysicalLayer() },
-  protocol: { type: 'TCP' },
-});
-```
+The framing layers parse incoming bytes as a stream. They recover from:
 
-See [`examples/websocket`](./examples/websocket) for a complete **Modbus TCP over WebSocket** implementation — client/server physical layers with a working demo.
+- Garbage bytes injected on the wire.
+- Multiple valid frames concatenated in one read (`sticky` frames).
+- Truncated frames followed by valid frames.
+- Cross-boundary chunks split across multiple reads.
+- Corrupted CRC (RTU) or LRC (ASCII).
 
-See [`examples/bluetooth`](./examples/bluetooth) for a **Modbus TCP over BLE** implementation using the Nordic UART Service (NUS) — includes a loopback test that runs without real BLE hardware.
+Valid frames are emitted; invalid data is discarded without corrupting adjacent frames.
 
-## Master API
+### Queue Strategies
 
-```typescript
-new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
-  timeout?: 1000,                     // per-request timeout (ms)
-  concurrent?: false,                 // pipelined mode (protocol: TCP only)
-})
-```
+Both `ModbusMaster` and `ModbusSlave` support four queue strategies:
 
-RTU framing options:
+| Strategy | Behavior | Best for |
+| --- | --- | --- |
+| `fifo` | Strict first-in-first-out execution. | Serial lines, deterministic ordering. |
+| `drop-stale` | New requests clear all pending, unexecuted requests. | Telemetry collectors where only the latest value matters. |
+| `deduplicate` | Pending requests with the same ADU fingerprint are dropped. | Polling loops that may overlap. |
+| `concurrent` | Requests are dispatched concurrently. | Modbus TCP or multi-link masters/slaves. |
 
-```typescript
-protocol: {
-  type: 'RTU',
-  opts: {
-    // Either a bare number (milliseconds), or `{ unit: 'bit' | 'ms', value: N }`.
-    // Use `0` to disable the timer entirely (useful for lossless transports
-    // such as RTU-over-TCP).
-    intervalBetweenFrames: 20,                          // 20 ms
-    interCharTimeout: { unit: 'bit', value: 10 },       // bit-time, needs baudRate
-    poolSize: 1024,
-  },
-}
-```
+`drop-stale` is the default.
 
-ASCII options:
+### Per-Unit Write Range Lock
 
-```typescript
-protocol: {
-  type: 'ASCII',
-  opts: {
-    lenientHex: true, // accept lowercase hex (a-f). Default: false (strict uppercase per spec)
-  },
-}
-```
+For the slave in `concurrent` mode, `enableWriteRangeLock` (default `true`) ensures that write requests (FC05/06/15/16/22/23) with overlapping address ranges on the same unit are serialized, preventing race conditions. This is critical for maintaining consistency when modifying shared registers or coils from multiple connections simultaneously. Set to `false` only for purely synchronous in-memory slaves that do not need the coordination overhead.
+
+### Access Control and Audit
 
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `open(...args)` | Open the physical layer. Can only be called once; after `close()` the instance is dead. |
-| `close()` | Close immediately. In-flight and queued requests are rejected. |
-| `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?)` | Send a user-defined function code |
-| `addCustomFunctionCode(cfc)` | Register custom FC for framing |
-| `removeCustomFunctionCode(fc)` | Unregister custom FC |
-
-Broadcast (`unit = 0`) resolves `void` — slaves never respond.
-
-## Slave API
+Install an `AccessAuthorizer` on either master or slave to enforce policies at three gates:
+
+- `checkUnit` — authorize the target unit address.
+- `checkAddress` — authorize the address range touched by the request.
+- `checkRuntime` — last-chance authorization immediately before wire I/O.
+
+Each hook may return `true`, `false`, or a numeric Modbus exception `ErrorCode`. On the slave, denied requests emit `accessAudit` events.
 
 ```typescript
-new ModbusSlave({
-  physical: { type: 'TCP_SERVER' },
-  protocol: { type: 'TCP' },
-  concurrent?: false, // per-connection concurrent (protocol: TCP only)
-})
+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);
+});
 ```
 
-### Register a model
+### Custom Function Codes
 
-```typescript
-slave.add({
-  unit: 1,
+Register non-standard function codes on the master or slave. The framing layer learns the request shape, and the application layer receives the raw PDU to parse and respond.
 
-  // Optional: intercept any FC before default dispatch
-  interceptor?: (fc, data) => Buffer | undefined,
+```typescript
+slave.addCustomFunctionCode(
+  { fc: 0x65 },
+  (unit, fc, data, callback) => {
+    // produce response PDU bytes
+    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,
+For RTU (and ASCII when operating over byte-oriented transports), the descriptor must also provide `determineFrameLength` so the framing state machine can determine frame length without buffering.
 
-  writeSingleCoil?: (address, value) => void,
-  writeMultipleCoils?: (address, values) => void,
+---
 
-  writeSingleRegister?: (address, value) => void,
-  writeMultipleRegisters?: (address, values) => void,
+## Supported Function Codes
 
-  maskWriteRegister?: (address, andMask, orMask) => void,
+| FC | Name | Master | Slave |
+| --: | --- | :---: | :---: |
+| 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 },
+---
 
-  // Optional address range validation
-  getAddressRange?: () => ({
-    discreteInputs?: [number, number] | [number, number][];
-    coils?: [number, number] | [number, number][];
-    inputRegisters?: [number, number] | [number, number][];
-    holdingRegisters?: [number, number] | [number, number][];
-  }),
-});
-```
+## Benchmarks
 
-Missing handlers return `ILLEGAL_FUNCTION`. Out-of-range addresses return `ILLEGAL_DATA_ADDRESS`. Handler throws become `SERVER_DEVICE_FAILURE` unless the error is a `ModbusError`.
+All figures below were produced by the benchmark harness in this repository on an **AMD Ryzen 7 9800X3D** workstation running **Node.js v24.16.0**. See [`benchmark/report_presentation.md`](benchmark/report_presentation.md) for the full report, methodology, and reproducibility instructions.
 
-| Method | Description |
-|--------|-------------|
-| `add(model)` | Register a slave model |
-| `remove(unit)` | Remove a slave model |
-| `open(...args)` | Open the physical layer. One-shot: cannot reopen after `close()`. |
-| `close()` | Close immediately |
-| `addCustomFunctionCode(cfc)` | Register a custom FC |
-| `removeCustomFunctionCode(fc)` | Unregister a custom FC |
+### Codec Micro-Benchmark
 
-## Custom Function Codes
+Pure CPU encode/decode, no network I/O. Each op completes in sub-microsecond time, so `Ops/sec` and `CPU (µs/op)` are the reliable indicators; per-op latency at this scale is dominated by `process.hrtime` overhead and is omitted.
 
-`predictRequestLength` / `predictResponseLength` receive a shared pool buffer and byte offsets (`start`, `end`). Use `end - start` for bounds checks rather than `buffer.length`.
+| Suite | Ops/sec | CPU (µs/op) |
+| --- | ---: | ---: |
+| TCP request encode | 9.37 M | 0.11 |
+| TCP response encode | 7.83 M | 0.13 |
+| TCP request decode | 8.83 M | 0.11 |
+| TCP response decode | 8.90 M | 0.11 |
+| RTU request encode | 9.12 M | 0.11 |
+| RTU response encode | 1.91 M | 0.53 |
+| RTU request decode | 8.53 M | 0.12 |
+| RTU response decode | 1.98 M | 0.51 |
+| ASCII request encode | 8.83 M | 0.11 |
+| ASCII response encode | 2.44 M | 0.42 |
+| ASCII request decode | 7.84 M | 0.13 |
+| ASCII response decode | 2.53 M | 0.4 |
 
-```typescript
-import type { CustomFunctionCode } from 'njs-modbus';
+All codec suites report `0` ns/op of GC pressure because the decode hot paths do not allocate on the JavaScript heap during steady-state operation.
 
-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]]);
-  },
-};
+### End-to-End Transport Throughput
 
-// Slave: framing + dispatch
-slave.addCustomFunctionCode(cfc);
+FC 03 (read 50 holding registers) over loopback TCP and a 115200-baud `socat` PTY pair for serial transports.
 
-// Master: framing only
-master.addCustomFunctionCode(cfc);
-const response = await master.sendCustomFC(1, 0x50, [0xab, 0xcd]);
-```
+| Transport | Library | Ops/sec | P50 (µs) | P99 (µs) |
+| --- | --- | ---: | ---: | ---: |
+| TCP sequential | **njs-modbus** | **94.81 k** | **8.7** | **43.9** |
+| TCP sequential | jsmodbus | 59.59 k | 13.6 | 65.7 |
+| TCP sequential | modbus-serial | 867 | 1,150.5 | 1,244.5 |
+| TCP 8 connections | **njs-modbus** | **109.23 k** | **60.7** | **179.8** |
+| TCP 8 connections | jsmodbus | 63.84 k | 102.6 | 299.7 |
+| TCP 8 connections | modbus-serial | 6.37 k | 1,241.3 | 1,437.6 |
+| RTU sequential | **njs-modbus** | **104** | **514.5** | **852.8** |
+| RTU sequential | jsmodbus | 104 | 546.4 | 927.3 |
+| RTU sequential | modbus-serial | 31 | 31,903.6 | 32,219.3 |
+| ASCII sequential | **njs-modbus** | **51** | **556.1** | **947.9** |
 
-## Error Handling
+### Chaos Resilience
 
-```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];
-  },
-});
-```
+The chaos suite injects corrupted, fragmented, sticky, and garbage-contaminated frames into live Modbus servers and verifies that valid frames are recovered without leakage.
 
-## Performance
+| Protocol | Scenarios passed |
+| --- | ---: |
+| TCP | 12 / 12 |
+| RTU | 12 / 12 |
+| ASCII | 14 / 14 |
 
-Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) and [modbus-serial](https://github.com/yaacov/node-modbus-serial).
+Re-run the full suite locally:
 
-| Metric | njs-modbus | jsmodbus | modbus-serial |
-|--------|-----------|----------|---------------|
-| TCP Throughput | **70,544 ops/sec** | 39,827 (0.56x) | 786 (0.01x) |
-| TCP P99 Latency | **53 µs** | 98 µs (1.83x) | 2,331 µs (43.7x) |
-| Concurrent (8 conn) | **75,810 ops/sec** | 41,754 (0.55x) | 5,620 (0.07x) |
-| RTU Serial (115200 baud) | **44 ops/sec** | 44 ops/sec | 45 ops/sec |
-| TCP Response Encode | **6.57M ops/sec** | 1.22M (0.19x) | 1.18M (0.18x) |
-| TCP Response Decode | **6.78M ops/sec** | 1.94M (0.29x) | 0.67M (0.10x) |
-| FC01 Read Coils | **85,170 ops/sec** | 617 (0.01x) | 861 (0.01x) |
+```bash
+npm run benchmark:full
+```
 
-<details>
-<summary>Full benchmark results</summary>
+---
 
-Node.js v24.16.0 · AMD Ryzen 7 9800X3D · linux x64 · 3 runs × 120 s · [full report](./benchmark/RESULTS.md)
+## Security & Compliance
 
-### TCP Throughput (Single Connection)
+`njs-modbus` is a pure Modbus protocol stack. For regulated environments, it provides a protocol-level policy enforcement point through `AccessAuthorizer` and an auditable trail through `accessAudit` events on `ModbusSlave`:
 
-```
-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` — authorize the target unit address.
+- `checkAddress` — authorize the address range touched by the request.
+- `checkRuntime` — last-chance authorization immediately before wire I/O.
 
-### Concurrent (8 Connections)
+Denied requests emit structured `accessAudit` events that can be forwarded to SIEM or audit logs. This helps meet operational-technology (OT) security and compliance requirements without adding external proxies.
 
-```
-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` also ships a built-in **TLS transport plugin** (`TlsClientPhysicalLayer` / `TlsServerPhysicalLayer`) backed by `node:tls`, so encrypted Modbus TCP links and mutual TLS are available when you supply certificates and TLS options. Network identity beyond certificate validation, IP whitelisting, host hardening, and physical security remain the responsibility of the host application and infrastructure.
 
-### RTU Serial (115200 baud via socat PTY)
+- [`SECURITY.md`](SECURITY.md) — vulnerability reporting, coordinated disclosure, and security update policy.
+- [`docs/security/`](https://github.com/xiejay97/njs-modbus/tree/main/docs/security) — access control, audit events, TLS usage, deployment compensating controls, and 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
-```
+See `examples/security/` for runnable master/slave examples, including TLS and transport-layer security options.
 
-### Frame Encode / Decode (CPU Micro-benchmark)
+---
 
-```
-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
-```
+## Commercial Support & License
 
-### Per-Function-Code TCP Throughput (Normal Payload)
+`njs-modbus` is released under the [Business Source License 1.1 (BSL 1.1)](LICENSE).
 
-| Function Code | njs-modbus | jsmodbus | modbus-serial |
-|---------------|-----------|----------|---------------|
-| FC01 Read Coils | **85,170** 🏆 | 617 (0.01x) | 861 (0.01x) |
-| FC02 Read Discrete Inputs | **85,570** 🏆 | 525 (0.01x) | 861 (0.01x) |
-| FC03 Read Holding Registers | **75,344** 🏆 | 40,081 (0.53x) | 852 (0.01x) |
-| FC04 Read Input Registers | **75,757** 🏆 | 49,524 (0.65x) | 866 (0.01x) |
-| FC05 Write Single Coil | **92,852** 🏆 | 53,521 (0.58x) | 871 (0.01x) |
-| FC06 Write Single Register | **92,864** 🏆 | 53,684 (0.58x) | 872 (0.01x) |
-| FC15 Write Multiple Coils | **86,434** 🏆 | 319 (0.00x) | 869 (0.01x) |
-| FC16 Write Multiple Registers | **76,053** 🏆 | 39,356 (0.52x) | 852 (0.01x) |
-| FC17 Report Server ID | **74,697** 🏆 | — | — |
-| FC22 Mask Write Register | **90,717** 🏆 | — | — |
-| FC23 Read/Write Multiple Registers | **85,652** 🏆 | — | — |
-| FC43 Read Device Identification | **78,030** 🏆 | — | 865 (0.01x) |
+- **Free production use** is granted for individuals, educational institutions, non-profit organizations, and companies with annual gross revenue below US$1,000,000.
+- **Change Date**: 2029-06-24. On that date, this version transitions to the Apache License, Version 2.0.
+- **Commercial license**: For OEMs, system integrators, and commercial products that need a predictable licensing path, guaranteed support, or cannot satisfy the BSL free-use conditions, we offer a separate proprietary commercial license.
 
-> FC17 / FC22 / FC23 are not supported by jsmodbus or modbus-serial.
+A commercial license removes BSL restrictions for your product and our support offerings help you ship with confidence:
 
-</details>
+- **Product integration license** — use `njs-modbus` in closed-source commercial products without copyleft obligations.
+- **Professional technical support** — troubleshooting, performance tuning, migration guidance, and upgrade planning.
+- **Enterprise support options** — response SLAs, long-term maintenance releases, priority bug fixes, and custom development.
 
-## License
+For licensing terms, pricing, and support options, please contact us:
 
-[![license](https://img.shields.io/github/license/xiejay97/njs-modbus?style=flat-square)](/LICENSE)
+- Email: [xiejay97@gmail.com](mailto:xiejay97@gmail.com)
+- GitHub Issues: [https://github.com/xiejay97/njs-modbus/issues](https://github.com/xiejay97/njs-modbus/issues)