njs-modbus 3.4.0 → 4.0.0

package/README.md

@@ -1,476 +1,412 @@
 # njs-modbus
 
-English | [简体中文](./README.zh-CN.md)
+[![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/)
 
-A pure JavaScript implementation of Modbus for Node.js, optimized for throughput and low GC pressure.
+**English** | [中文](README.zh-CN.md)
 
-<!-- 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 -->
+> 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.
 
-## Highlights
+`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.
 
-- **Protocols** — Modbus TCP, RTU, ASCII
-- **Transports** — Serial, TCP client/server, UDP client/server, plus pluggable custom layers
-- **Performance-first** — Parallel FIFO queues, lazy-deletion timer heap, inline BE reads/writes, zero-allocation hot paths
-- **Master** — FIFO or pipelined concurrent requests (TCP only)
-- **Slave** — Per-connection FIFO or concurrent processing (TCP only)
-- **Custom function codes** with pluggable framing
-- **Broadcasting** (`unit = 0`)
-- **Full TypeScript**
-- **Zero runtime dependencies** (peer-depends on `serialport` for serial)
+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.
 
-## Supported Function Codes
+---
 
-| 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 |
+## Table of Contents
 
-## Installation
+- [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)
 
-Requires **Node.js ≥ 18.19**.
+---
 
-```bash
-npm install njs-modbus
-```
+## What is njs-modbus?
 
-For serial transport, also install the peer dependency:
+`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.
 
-```bash
-npm install serialport
+```
+┌─────────────────────────────────────────────┐
+│  Application: ModbusMaster / ModbusSlave    │
+├─────────────────────────────────────────────┤
+│  Protocol framing: TCP / RTU / ASCII        │
+├─────────────────────────────────────────────┤
+│  Pipeline: AbstractPipelineAdapter          │
+├─────────────────────────────────────────────┤
+│  Physical transport: TCP / UDP / TLS /      │
+│  Serial / WebSocket / custom                │
+└─────────────────────────────────────────────┘
 ```
 
-## Quick Start
+- **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.
 
-### TCP Master
+---
 
-```typescript
-import { ModbusMaster } from 'njs-modbus';
+## Why njs-modbus?
 
-const master = new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },
-});
+| 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. |
 
-await master.open({ port: 502, host: '192.168.1.10' });
+---
 
-const res = await master.readHoldingRegisters(1, 0, 10);
-console.log(res.data);
+## Feature Matrix
 
-await master.close();
-```
+| Capability | TCP | RTU | ASCII |
+| --- | :---: | :---: | :---: |
+| Master / client | ✅ | ✅ | ✅ |
+| Slave / server | ✅ | ✅ | ✅ |
+| Concurrent pipelining | ✅ | — | — |
+| Broadcast (`unit === 0`) | ✅ | ✅ | ✅ |
+| Custom function codes | ✅ | ✅* | ✅ |
+| Streaming frame recovery | ✅ | ✅ | ✅ |
 
-### TCP Slave
+\* RTU custom function codes require a `determineFrameLength` callback so the framing state machine can know the frame length without buffering.
 
-```typescript
-import { ModbusSlave } from 'njs-modbus';
+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.
 
-const slave = new ModbusSlave({
-  physical: { type: 'TCP_SERVER' },
-  protocol: { type: 'TCP' },
-});
+---
 
-slave.add({
-  unit: 1,
-  readHoldingRegisters: (address, length) => {
-    return Array.from({ length }, (_, i) => address + i);
-  },
-});
+## Installation
 
-await slave.open({ port: 502 });
+```bash
+npm install njs-modbus
 ```
 
-### Serial RTU Master
-
-```typescript
-const master = new ModbusMaster({
-  physical: {
-    type: 'SERIAL',
-    opts: { path: '/dev/ttyUSB0', baudRate: 9600 },
-  },
-  protocol: { type: 'RTU' },
-});
+Serial support is provided through an optional peer dependency:
 
-await master.open();
-const res = await master.readHoldingRegisters(1, 0, 10);
-await master.close();
+```bash
+npm install serialport
 ```
 
-### RTU over TCP
+Requires Node.js `>=18.19`.
 
-```typescript
-const master = new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'RTU' },
-});
-```
+---
 
-## Architecture
+## Quick Start
 
-The library follows a strict two-layer design:
+### TCP Master
 
-```
-┌─────────────────────────────────────────┐
-│         ModbusMaster / ModbusSlave        │  ← User API, session/queue management
-├─────────────────────────────────────────┤
-│      TcpApplicationLayer                │  ← Protocol framing (MBAP / CRC16 / LRC)
-│      RtuApplicationLayer                │
-│      AsciiApplicationLayer              │
-├─────────────────────────────────────────┤
-│      AbstractPhysicalConnection         │  ← Per-connection I/O
-├─────────────────────────────────────────┤
-│      AbstractPhysicalLayer              │  ← Resource ownership (port/socket/server)
-│      ├── TcpClientPhysicalLayer         │
-│      ├── TcpServerPhysicalLayer         │
-│      ├── UdpClientPhysicalLayer         │
-│      ├── UdpServerPhysicalLayer         │
-│      └── SerialPhysicalLayer            │
-└─────────────────────────────────────────┘
-```
+```typescript
+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();
+  }
+});
 
-Every transport is modeled as connection-oriented: physical layers emit `'connect'` with an `AbstractPhysicalConnection`, and a dedicated application layer instance is created per connection.
+physical.open({ host: '127.0.0.1', port: 502 }, (err) => {
+  if (err) {
+    console.error('failed to connect:', err.message);
+    process.exit(1);
+  }
+});
+```
 
-## Physical Layer
+### TCP Slave
 
-All physical layers expose `open()` / `close()`, a `state` property, and the events documented in [Events](#events).
+```typescript
+import { ModbusSlave, TcpServerPhysicalLayer } from 'njs-modbus';
 
-| Type | `open(...)` Args | Description |
-|------|-----------------|-------------|
-| `SERIAL` | `()` | Serial port via `serialport` package |
-| `TCP_CLIENT` | `SocketConnectOpts` | TCP client socket |
-| `TCP_SERVER` | `ListenOptions` | TCP server |
-| `UDP_CLIENT` | `{ port?, address? }` | UDP client |
-| `UDP_SERVER` | `BindOptions` | UDP server |
-| `CUSTOM` | *(user-defined)* | User-provided `AbstractPhysicalLayer` instance |
+const physical = new TcpServerPhysicalLayer();
 
-### TCP Server options
+physical.on('connect', (pipeline) => {
+  const slave = new ModbusSlave({
+    pipelineAdapter: pipeline,
+    protocol: { type: 'TCP' },
+    queueStrategy: 'drop-stale',
+  });
 
-```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
+  slave.addUnit(1, {
+    readHoldingRegisters: (address, length, callback) => {
+      const values = Array.from({ length }, (_, i) => (address + i) & 0xffff);
+      callback(null, values);
     },
-  },
-  protocol: { type: 'TCP' },
+    writeSingleRegister: (address, value, callback) => {
+      console.log(`write ${value} to ${address}`);
+      callback(null);
+    },
+  });
 });
-```
 
-### Physical layer option reference
+physical.open({ port: 502 }, (err) => {
+  if (err) {
+    console.error('failed to listen:', err.message);
+    process.exit(1);
+  }
+  console.log('slave listening on port 502');
+});
+```
 
-| 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()`. |
+### RTU over Serial
 
-## Protocol Layer
+```typescript
+import { ModbusMaster, SerialPhysicalLayer } from 'njs-modbus';
 
-| Protocol | Options | Description |
-|----------|---------|-------------|
-| `TCP` | none | Modbus TCP with MBAP header |
-| `RTU` | `RtuProtocolOptions` | Modbus RTU with CRC16 |
-| `ASCII` | `AsciiApplicationLayerOptions` | Modbus ASCII with LRC |
+const physical = new SerialPhysicalLayer();
 
-### RTU options
+physical.on('connect', async (pipeline) => {
+  const master = new ModbusMaster({
+    pipelineAdapter: pipeline,
+    protocol: { type: 'RTU' },
+    queueStrategy: 'fifo',
+    timeout: 500,
+  });
 
-```typescript
-protocol: {
-  type: 'RTU',
-  opts: {
-    // t3.5 inter-frame silence.
-    // Either a bare number (ms) or { unit: 'bit' | 'ms', value: N }.
-    // Use 0 to disable (useful for lossless transports like RTU-over-TCP).
-    intervalBetweenFrames: 20,
-
-    // t1.5 inter-character timeout (opt-in).
-    interCharTimeout: { unit: 'bit', value: 10 },
-
-    // Discard frames with t1.5 timing violations.
-    strictTiming: true,
-  },
-}
-```
+  const res = await master.readHoldingRegisters(1, 0, 10);
+  console.log('registers:', res.data);
 
-### ASCII options
+  master.destroy();
+  physical.close();
+});
 
-```typescript
-protocol: {
-  type: 'ASCII',
-  opts: {
-    lenientHex: true, // accept lowercase hex (a-f). Default: false (strict uppercase per spec)
-  },
-}
+physical.open({ path: '/dev/ttyUSB0', baudRate: 115200 });
 ```
 
-## Master API
+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.
 
-### Constructor
+---
 
-```typescript
-new ModbusMaster({
-  physical: { type: 'TCP_CLIENT' },
-  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
-  timeout?: 1000,                     // per-request timeout (ms)
-  concurrent?: false,                 // pipelined mode (TCP only)
-})
-```
+## Architecture
 
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `open(...args)` | Open the physical layer. One-shot: cannot reopen after `close()`. |
-| `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
-
-### Constructor
+The library is organized into four layers. Each layer is independent, testable in isolation, and replaceable.
 
-```typescript
-new ModbusSlave({
-  physical: { type: 'TCP_SERVER' },
-  protocol: { type: 'TCP' },
-  concurrent?: false, // per-connection concurrent (TCP only)
-})
-```
+| 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` |
 
-### Register a model
+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.
 
-```typescript
-slave.add({
-  unit: 1,
+---
 
-  // Optional: intercept any FC before default dispatch
-  interceptor?: (fc, data) => Buffer | undefined,
+## Core Capabilities
 
-  readCoils?: (address, length) => Uint8Array,
-  readDiscreteInputs?: (address, length) => Uint8Array,
-  readHoldingRegisters?: (address, length) => number[] | Uint16Array,
-  readInputRegisters?: (address, length) => number[] | Uint16Array,
+### Low-Allocation Codec Hot Paths
 
-  writeSingleCoil?: (address, value) => void,
-  writeMultipleCoils?: (address, values) => void,
+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.
 
-  writeSingleRegister?: (address, value) => void,
-  writeMultipleRegisters?: (address, values) => void,
+### Streaming Frame Recovery
 
-  maskWriteRegister?: (address, andMask, orMask) => void,
+The framing layers parse incoming bytes as a stream. They recover from:
 
-  reportServerId?: () => ServerId,
-  readDeviceIdentification?: () => { [index: number]: string },
+- 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).
 
-  // 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][];
-  }),
-});
-```
+Valid frames are emitted; invalid data is discarded without corrupting adjacent frames.
 
-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`.
+### Queue Strategies
 
-### Methods
+Both `ModbusMaster` and `ModbusSlave` support four queue strategies:
 
-| Method | Description |
-|--------|-------------|
-| `add(model)` | Register a slave model |
-| `remove(unit)` | Remove a model |
-| `open(...args)` | Open and begin accepting connections. One-shot. |
-| `close()` | Close immediately |
-| `addCustomFunctionCode(cfc)` | Register custom FC |
-| `removeCustomFunctionCode(fc)` | Unregister custom FC |
+| 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. |
 
-## Events
+`drop-stale` is the default.
 
-Both `ModbusMaster` and `ModbusSlave` are `EventEmitter`s. All events are typed.
+### Per-Unit Write Range Lock
 
-### Physical layer events
+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.
 
-| Event | Arguments | Description |
-|-------|-----------|-------------|
-| `open` | `()` | Physical layer is ready to accept connections |
-| `connect` | `(connection)` | A new connection has been established |
-| `close` | `()` | Physical layer has closed |
-| `error` | `(error)` | Physical layer error |
+### Access Control and Audit
 
-### Connection debug events
+Install an `AccessAuthorizer` on either master or slave to enforce policies at three gates:
 
-| Event | Arguments | Description |
-|-------|-----------|-------------|
-| `tx` | `(buffer, connection)` | Raw data written to the wire |
-| `rx` | `(buffer, connection)` | Raw data received from the wire |
+- `checkUnit` — authorize the target unit address.
+- `checkAddress` — authorize the address range touched by the request.
+- `checkRuntime` — last-chance authorization immediately before wire I/O.
 
-### Application layer events
-
-| Event | Arguments | Description |
-|-------|-----------|-------------|
-| `framing` | `(frame, connection)` | A complete frame has been decoded |
-| `framingError` | `(error, connection)` | Framing error (CRC/LRC failure, malformed MBAP, timing violation, etc.) |
+Each hook may return `true`, `false`, or a numeric Modbus exception `ErrorCode`. On the slave, denied requests emit `accessAudit` events.
 
 ```typescript
-master.on('framing', (frame, connection) => {
-  console.log('frame:', frame.unit, frame.fc, frame.transaction);
+slave.setAccessAuthorizer({
+  checkUnit: (unit) => unit === 1,
+  checkAddress: (_unit, table, [start, end]) =>
+    table === 'holdingRegisters' && start >= 0 && end < 100,
 });
 
-master.on('framingError', (error, connection) => {
-  console.log('framing error:', error.message);
+slave.on('accessAudit', (event) => {
+  console.log('access denied:', event.type, event.message);
 });
 ```
 
-## Custom Function Codes
+### Custom Function Codes
 
-`predictRequestLength` / `predictResponseLength` receive a `getByte` accessor and the number of available `length` bytes. Use `length` for bounds checks — do not access the buffer directly.
+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.
 
 ```typescript
-import type { CustomFunctionCode } from 'njs-modbus';
-
-const cfc: CustomFunctionCode = {
-  fc: 0x50,
-  predictRequestLength: (getByte, length) => {
-    if (length < 2) return 0; // need more bytes
-    return 4 + getByte(1);
+slave.addCustomFunctionCode(
+  { fc: 0x65 },
+  (unit, fc, data, callback) => {
+    // produce response PDU bytes
+    callback(null, () => Buffer.from([0x00]));
   },
-  predictResponseLength: (getByte, length) => {
-    if (length < 2) return 0;
-    return 4 + getByte(1);
-  },
-  handle: async (data, unit) => {
-    return Buffer.from([data[1], data[0]]);
-  },
-};
-
-// Slave: framing + dispatch
-slave.addCustomFunctionCode(cfc);
-
-// Master: framing only
-master.addCustomFunctionCode(cfc);
-const response = await master.sendCustomFC(1, 0x50, [0xab, 0xcd]);
+);
 ```
 
-## Error Handling
+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.
 
-```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];
-  },
-});
-```
+---
 
-## Custom Physical Layer
+## Supported Function Codes
 
-Any byte-oriented transport can be used by implementing `AbstractPhysicalLayer` and `AbstractPhysicalConnection`, then passing `{ type: 'CUSTOM', layer: yourLayer }`.
+| 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 | ✅ | ✅ |
+
+---
+
+## Benchmarks
+
+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.
+
+### Codec Micro-Benchmark
+
+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.
+
+| 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 |
+
+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.
+
+### End-to-End Transport Throughput
+
+FC 03 (read 50 holding registers) over loopback TCP and a 115200-baud `socat` PTY pair for serial transports.
+
+| 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** |
+
+### Chaos Resilience
+
+The chaos suite injects corrupted, fragmented, sticky, and garbage-contaminated frames into live Modbus servers and verifies that valid frames are recovered without leakage.
+
+| Protocol | Scenarios passed |
+| --- | ---: |
+| TCP | 12 / 12 |
+| RTU | 12 / 12 |
+| ASCII | 14 / 14 |
+
+Re-run the full suite locally:
 
-```typescript
-import { AbstractPhysicalLayer, AbstractPhysicalConnection } from 'njs-modbus';
+```bash
+npm run benchmark:full
+```
 
-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' },
-});
-```
+## Security & Compliance
 
-See [`examples/websocket`](./examples/websocket) for a complete **Modbus TCP over WebSocket** implementation.
+`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`:
 
-See [`examples/bluetooth`](./examples/bluetooth) for a **Modbus TCP over BLE** implementation using the Nordic UART Service (NUS).
+- `checkUnit` — authorize the target unit address.
+- `checkAddress` — authorize the address range touched by the request.
+- `checkRuntime` — last-chance authorization immediately before wire I/O.
 
-## Performance
+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.
 
-Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) v4.0.10 and [modbus-serial](https://github.com/yaacov/node-modbus-serial) v8.0.25.
+`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.
 
-Environment: AMD Ryzen 7 9800X3D 8-Core Processor · Node.js v24.16.0 · [full report](./benchmark/report_presentation.md)
+- [`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.
 
-### End-to-end TCP
+See `examples/security/` for runnable master/slave examples, including TLS and transport-layer security options.
 
-| Metric | njs-modbus | jsmodbus | modbus-serial |
-|--------|-----------|----------|---------------|
-| Single connection | **74,964 ops/sec** 🏆 | 55,996 (0.75x) | 853 (0.01x) |
-| 8 concurrent clients | **10,188 ops/sec** 🏆 | 5,918 (0.58x) | 728 (0.07x) |
-| P99 latency (single) | **17 µs** 🏆 | 15 µs (0.88x) | 1,206 µs (70.9x) |
+---
 
-### Frame encode / decode (CPU micro-benchmark)
+## Commercial Support & License
 
-| Benchmark | njs-modbus | jsmodbus | modbus-serial |
-|-----------|-----------|----------|---------------|
-| TCP request encode | **9.61M ops/sec** 🏆 | 6.32M (0.66x) | 0.68M (0.07x) |
-| TCP response encode | **7.51M ops/sec** 🏆 | 1.18M (0.16x) | 0.44M (0.06x) |
-| TCP response decode | **8.55M ops/sec** 🏆 | 2.04M (0.24x) | 0.70M (0.08x) |
-| RTU request encode | **9.42M ops/sec** 🏆 | 3.03M (0.32x) | 6.57M (0.70x) |
-| ASCII request encode | **7.09M ops/sec** 🏆 | — | 4.11M (0.58x) |
-| ASCII request decode | **4.91M ops/sec** 🏆 | — | 1.19M (0.24x) |
+`njs-modbus` is released under the [Business Source License 1.1 (BSL 1.1)](LICENSE).
 
-### Per-function-code TCP throughput (100 coils / 50 registers)
+- **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.
 
-| Function Code | njs-modbus | jsmodbus | modbus-serial |
-|---------------|-----------|----------|---------------|
-| FC01 Read Coils | **75,430** 🏆 | 488 (0.01x) | 859 (0.01x) |
-| FC03 Read Holding Registers | **82,028** 🏆 | 46,596 (0.57x) | 864 (0.01x) |
-| FC06 Write Single Register | **86,110** 🏆 | 51,084 (0.59x) | 871 (0.01x) |
-| FC15 Write Multiple Coils | **78,766** 🏆 | — | 867 (0.01x) |
-| FC17 Report Server ID | **79,185** 🏆 | — | — |
-| FC22 Mask Write Register | **73,060** 🏆 | — | — |
-| FC23 Read/Write Multiple Registers | **68,429** 🏆 | — | — |
-| FC43 Read Device Identification | **62,176** 🏆 | — | 868 (0.01x) |
+A commercial license removes BSL restrictions for your product and our support offerings help you ship with confidence:
 
-> FC17 / FC22 / FC23 / FC43 are not supported by jsmodbus.
+- **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)