node-red-contrib-rpc-toolkit 2.2.4

JSON-RPC 2.0 client and server nodes for Node-RED with Safe Mode support

npm install node-red-contrib-rpc-toolkit

node-red-contrib-rpc-toolkit

JSON-RPC 2.0 client and server nodes for Node-RED, with optional RPC Toolkit Safe Mode interoperability.

The package is designed to connect Node-RED flows with RPC Toolkit endpoints such as rpc-express-toolkit, rpc-php-toolkit, rpc-dotnet-toolkit, and rpc-arduino-toolkit.

Status

• Published on npm as node-red-contrib-rpc-toolkit.
• Requires Node.js 18 or newer.
• Tested locally with Node-RED 5.0.0 in unit tests and Node-RED 4.1.0 in the Docker interoperability harness.
• npm audit is clean for runtime and development dependencies.
• Node-RED Flow Library visibility may lag behind npm publication. If the package is not visible in Palette Manager yet, install it from npm in the Node-RED user directory.

Nodes

• rpc-server - configuration node that mounts a JSON-RPC HTTP endpoint on the Node-RED HTTP server.
• rpc-method - registers a flow-backed JSON-RPC method on an rpc-server.
• rpc-response - completes a pending request started by an rpc-method.
• rpc-client - calls a remote JSON-RPC HTTP endpoint.
• rpc-request - parses an incoming JSON-RPC request from an existing HTTP flow.

Implemented Features

• JSON-RPC 2.0 calls, errors, notifications, and batch requests.
• Flow-backed method registration.
• Built-in introspection through __rpc.listMethods, __rpc.describe, __rpc.describeAll, __rpc.version, and __rpc.capabilities.
• Per-method JSON Schema validation when a method schema is configured.
• Optional RPC Toolkit Safe Mode over HTTP.
• Strict Safe Mode header handling on the server when Safe Mode is enabled.
• CORS support on the server node.
• Optional Authorization header passthrough on the client node.
• Client editor helper for loading remote methods through introspection.

Not currently implemented by this package:

• Server-side JWT authentication middleware.
• Server-side rate limiting configuration.
• WebSocket transport.
• A dedicated visual batch node. Batch requests are supported by the JSON-RPC endpoint, but not exposed as a separate Node-RED node.

Installation

Node-RED User Directory

cd ~/.node-red
npm install node-red-contrib-rpc-toolkit

Restart Node-RED after installing from the command line.

Palette Manager

When the package is visible in the Node-RED Flow Library:

1. Open Node-RED.
2. Go to Menu > Manage palette.
3. Open the Install tab.
4. Search for node-red-contrib-rpc-toolkit.
5. Click Install.

Quick Start

Create a simple RPC server method:

[RPC Method: "ping"] -> [Function: return "pong"] -> [RPC Response]

Configure an rpc-server config node with endpoint /rpc, then configure the rpc-method node to use that server and method name ping. Safe Mode is enabled by default.

Function node:

msg.payload = 'pong';
return msg;

Raw HTTP test:

curl -X POST http://localhost:1880/rpc \
  -H "Content-Type: application/json" \
  -H "X-RPC-Safe-Enabled: true" \
  -d '{"jsonrpc":"2.0","method":"ping","id":1}'

Raw Safe Mode response:

{"jsonrpc":"2.0","id":1,"result":"S:pong"}

The S: prefix is expected for raw HTTP clients when Safe Mode is enabled. RPC Toolkit clients decode Safe Mode values automatically.

If Safe Mode is disabled on the rpc-server config node, the same request can be sent without the Safe Mode header and the response is standard JSON-RPC:

curl -X POST http://localhost:1880/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"ping","id":1}'

{"jsonrpc":"2.0","id":1,"result":"pong"}

Node Details

RPC Server

Creates a JSON-RPC endpoint under the Node-RED HTTP server.

Configuration:

• Endpoint - HTTP path, for example /rpc.
• CORS - enables CORS headers, including X-RPC-Safe-Enabled.
• Safe Mode - enabled by default for RPC Toolkit interoperability. Disable it to expose a standard JSON-RPC 2.0 endpoint.

When Safe Mode is enabled, the server uses strict Safe Mode header negotiation. Requests without X-RPC-Safe-Enabled are rejected with JSON-RPC error -32600. When Safe Mode is disabled, the endpoint does not require the header and returns raw JSON values without S: or D: prefixes.

RPC Method

Registers a method on an rpc-server.

Configuration:

• Server - target rpc-server config node.
• Method Name - JSON-RPC method name.
• Description - optional introspection text.
• Expose Schema - makes schema metadata visible via __rpc.describe.
• Validate Schema - validates params before invoking the flow.
• Schema - JSON Schema generated by the editor UI or provided manually.

The node sends incoming method params on output 1. The flow must keep msg.rpc intact and pass the final result to an rpc-response node.

RPC Response

Completes a pending request created by an rpc-method.

Input:

• msg.payload - successful result.
• msg.error - optional JSON-RPC error object.
• msg.rpc.id and msg.rpc.methodNodeId - routing metadata from rpc-method.

Example custom error:

msg.error = {
  code: -32042,
  message: 'Domain failure',
  data: {
    reason: 'intentional-test-error'
  }
};
return msg;

RPC Client

Calls a remote JSON-RPC HTTP endpoint.

Configuration:

• Server URL - full endpoint URL, for example http://localhost:3000/api.
• Method - default method name.
• Timeout - request timeout in milliseconds.
• Auth Token - optional token sent as an Authorization header.
• Safe Mode - enabled by default.

Input:

• msg.payload - method params.
• msg.method - optional method override.

Outputs:

• Output 1: successful result in msg.payload.
• Output 2: error object in msg.error.

RPC Request

Parses a JSON-RPC request from an existing HTTP flow. Use this only when you are building a custom HTTP flow instead of the rpc-server config node.

Introspection

The server supports:

• __rpc.listMethods
• __rpc.describe
• __rpc.describeAll
• __rpc.version
• __rpc.capabilities

Example:

curl -X POST http://localhost:1880/rpc \
  -H "Content-Type: application/json" \
  -H "X-RPC-Safe-Enabled: true" \
  -d '{"jsonrpc":"2.0","method":"__rpc.listMethods","id":1}'

Raw Safe Mode response:

{"jsonrpc":"2.0","id":1,"result":["S:ping","S:sum"]}

Safe Mode Notes

Safe Mode is an RPC Toolkit extension for preserving application-level value intent across plain JSON.

• HTTP requests and responses use X-RPC-Safe-Enabled when Safe Mode is enabled.
• The Node-RED server defaults to Safe Mode enabled and strict header negotiation.
• Raw HTTP clients must send X-RPC-Safe-Enabled when calling a Safe Mode server.
• Raw HTTP responses from a Safe Mode server contain encoded string values such as S:hello.
• Disable Safe Mode on the server when generic JSON-RPC clients need unprefixed JSON strings.
• RPC Toolkit clients decode these values automatically.
• Date and BigInt marker handling follows rpc-express-toolkit behavior.

Example Flows

Ready-to-import Node-RED flows are available in examples.

The examples are grouped by test type:

• standard JSON-RPC server
• Safe Mode server
• validation and custom error responses
• standard JSON-RPC client
• Safe Mode client
• client error output
• request parser
• full local server/client loopback

Local Development

git clone https://github.com/n-car/node-red-contrib-rpc-toolkit.git
cd node-red-contrib-rpc-toolkit
npm install
npm test

Useful checks:

npm run audit:runtime
npm run pack:check

Related Projects

• rpc-express-toolkit - Node.js/Express implementation
• rpc-php-toolkit - PHP implementation
• rpc-dotnet-toolkit - .NET implementation
• rpc-arduino-toolkit - Arduino/ESP32 implementation
• rpc-java-toolkit - Java implementation
• rpc-python-toolkit - Python implementation

License

MIT. See LICENSE.