node-red-contrib-octocore/README.md

OctoCore implementation for node-red

# node-red-contrib-octocore

[![NPM version](https://badge.fury.io/js/node-red-contrib-octocore.svg)](http://badge.fury.io/js/node-red-contrib-octocore)

A Node-RED module to communicate with the OctoCore platform from Octotronic.

## Overview

This Node-RED module provides nodes to publish and subscribe to messages on the OctoCore platform using NATS. It includes the following nodes:

**Core Nodes:**
- `uns-publish`: Publish messages to the OctoCore platform with advanced features (buffering, batching, rate limiting).
- `uns-subscribe`: Subscribe to messages from the OctoCore platform with automatic JSON parsing.
- `uns-request`: Send requests to the OctoCore platform and receive responses.
- `uns-server`: Configure the NATS server connection with enhanced security (TLS, JWT, NKey authentication).

## Installation

To install the module, run the following command in your Node-RED user directory (typically `~/.node-red`):

```sh
npm install node-red-contrib-octocore
```

### Development Setup

For development, clone the repository and install dependencies:

```sh
git clone https://git.octotronic.com/manufacturinghub/node-red-contrib-octocore.git
cd node-red-contrib-octocore
npm install
```

### Available Scripts

- `npm test` - Run tests with Jest
- `npm run lint` - Run ESLint for code quality checks
- `npm run lint:fix` - Fix ESLint issues automatically
- `npm run format` - Format code with Prettier

### Makefile Commands

For convenience, you can also use the provided Makefile:

```bash
make help          # Show all available commands
make dev-setup     # Setup development environment
make dev-cycle     # Run development cycle (format, lint, test)
make docker-up     # Start Node-RED with Docker
make docker-logs   # Show Docker logs
```

See [docs/makefile-usage.md](docs/makefile-usage.md) for complete documentation.

## Nodes

### NATS Server Configuration

#### `uns-server`

This node is used to configure the connection to the NATS server with comprehensive security features.

**🔐 Enhanced Security & Authentication:**
- **Authentication Methods** (Dropdown Selection):
  - **No Authentication**: For local development or unsecured servers
  - **Username/Password**: Traditional authentication (default, backward compatible)
  - **Token Authentication**: Single authentication token for NATS server
  - **JWT Authentication**: NATS 2.x JSON Web Token with NKey seed
  - **NKey Authentication**: Cryptographic authentication using NKey seed
- **TLS/SSL Encryption Support**:
  - Enable/disable TLS encryption with checkbox
  - **CA Certificate**: Server verification with custom CA certificate file
  - **Client Certificate**: Mutual TLS (mTLS) with client certificate
  - **Client Key**: Client private key for mTLS authentication
  - **Verify Server Certificate**: Optional certificate verification (enabled by default)
- **Security Features**:
  - All credentials stored encrypted in Node-RED's secure credentials system
  - Automatic security warnings for production connections without TLS
  - JWT validation ensures both JWT token and NKey seed are provided
  - File-based certificate loading with path validation
  - Debug logging shows auth method and TLS status (with masked credentials)

**Connection Settings:**
- **Server**: The URL of the NATS server.
- **Max Reconnect Attempts**: Maximum number of reconnection attempts (default: 10).
- **Reconnect Wait Time**: Time to wait between reconnection attempts in milliseconds (default: 1000).
- **Connection Timeout**: Connection timeout in milliseconds (default: 10000).
- **Ping Interval**: Interval between ping messages in milliseconds (default: 30000).
- **Max Ping Outs**: Maximum number of ping timeouts before disconnect (default: 3).

**Connection Status:**
- **Connected**: Shows connection status
- **Disconnected**: Shows reconnect attempts
- **Connecting**: Shows current attempt
- **Failed**: Shows when connection fails

**Security Best Practices:**
- Always use TLS/SSL for production environments
- Use JWT or NKey authentication for enhanced security
- Keep "Verify Server Certificate" enabled in production
- All credentials are encrypted and never visible in flow exports

### Publish Node

#### `uns-publish`

This node is used to publish messages to the OctoCore platform with advanced features.

**Core Features:**
- **Name**: The name of the node.
- **Server**: The NATS server configuration to use.
- **Dataformat**: The format of the data to publish (`UNS Value`, `UNS Event`, `UNS Reply`, `Specific Topic`).
- **Datapoint / Subject**: The datapoint or subject to publish to.
- **Debug**: Optional debug logging (enable via checkbox)

**🔧 Advanced Features:**
- **Message Buffering**: Queue messages when connection is lost
  - **Buffer Limit Types**: Message count (max: 10,000) or buffer size in bytes (max: 100 MB)
  - **Buffer Modes**: Drop oldest (FIFO), drop newest, or reject on full
  - **Buffer Persistence**: None (RAM), Context Storage, File System, or Both
  - **Auto-Save**: Automatic periodic saving (5-300 seconds, default: 30s)
  - **Timestamp Preservation**: Original timestamps preserved when buffered messages are flushed
  - **Parallel Transmission**: All buffered messages sent simultaneously when connection is restored (~10x faster)
- **Manual UNS Datatype Override**: Force specific datatype (Integer, Float, Boolean, String, Object) with strict validation
- **Batch Publishing**: Group multiple messages for efficient transmission
  - **Batch Size**: Number of messages per batch (default: 100, range: 1-1000)
  - **Batch Interval**: Time window in milliseconds (default: 1000ms, range: 100-60000ms)
  - **Batch Modes**:
    - **Size Only**: Publish only when batch is full (recommended for high-throughput scenarios)
    - **Hybrid**: Publish when batch is full OR interval expires (whichever comes first)
    - **Time Only**: Publish at regular intervals regardless of batch size
  - **Status Display**: Shows current queue state `batching (X/Y)` where X = queued messages, Y = batch size
  - **Timestamp Preservation**: Original message creation timestamps are preserved when batching
  - **Parallel Transmission**: All batch messages sent simultaneously (~10x faster than sequential)
- **Auto-Reply Handler**: Process request-reply patterns with configurable timeout and output port
  - **Note**: The output port is only used when Auto-Reply Handler is enabled. When disabled, messages are published directly without forwarding to the output.
- **Rate Limiting**: Token bucket algorithm to prevent message flooding (configurable rate, burst, actions: drop, delay)
- **Connection Pooling**: Shared connections for resource efficiency

**Output Properties** (only used when Auto-Reply Handler is enabled):
- `msg.payload`: The message payload
- `msg.topic`: The NATS subject used
- `msg._buffered`: Indicates if message was buffered during disconnect
- `msg._batched`: Indicates if message was part of a batch
- `msg._rateLimited`: Indicates if message was rate limited
- `msg._originalTimestamp`: Original timestamp when message was buffered (preserved during flush)

The payload of the message to publish can be set via the `msg.payload` property.

### Subscribe Node

#### `uns-subscribe`

This node is used to subscribe to messages from the OctoCore platform with automatic parsing and connection pooling.

**Core Features:**
- **Name**: The name of the node.
- **Server**: The NATS server configuration to use.
- **Dataformat**: The format of the data to subscribe to (`UNS Value`, `UNS Command`, `UNS Event`, `Specific Subject`).
- **Datapoint / Subject**: The datapoint or subject to subscribe to.
- **Topic Field**: Select what value to use for msg.topic (`NATS Subject`, `Datapoint ID`, `Datapoint Name`, `Data Type`).

**🔧 Advanced Features:**
- **Automatic JSON Parsing**: For `Specific Subject` format, automatically attempts JSON parsing with fallback to string
- **Connection Pooling**: Shared connections for resource efficiency
- **Format Detection**: Adds `_format` property ('json' or 'string') for downstream processing

**Output Properties:**
- `msg.payload`: Only the value of the datapoint (for UNS Value format)
- `msg.topic`: The topic field value based on configuration
- `msg.datatype`: Data type of the UNS value (only for UNS Value format)
- `msg.id`: Datapoint ID (only for UNS Value format)
- `msg.name`: Datapoint name (only for UNS Value format)
- `msg.timestamp`: Timestamp of the message (only for UNS Value format)
- `msg._format`: Format indicator ('json' or 'string') for Specific Subject

**UNS Event Properties:**
- `msg.id`: Event ID (only for UNS Event format)
- `msg.type`: Event type (only for UNS Event format)
- `msg.startTime`: Event start time (only for UNS Event format)
- `msg.endTime`: Event end time (only for UNS Event format)

**Data Type Handling:**
- **datatype 1 (Integer)**: String converted to Integer
- **datatype 2 (Float)**: String converted to Float
- **datatype 3 (Boolean)**: String converted to Boolean
- **datatype 4 (String)**: Remains as String
- **datatype 5 (Unix Timestamp)**: Unix timestamp in milliseconds
- **datatype 6 (Object)**: String parsed to JSON object

### Request Node

#### `uns-request`

This node is used to send requests to the OctoCore platform and receive responses.

- **Name**: The name of the node.
- **Server**: The NATS server configuration to use.
- **Dataformat**: The format of the data (`UNS Command`, `Specific Subject`).
- **Subject**: The subject to send the request to.
- **Timeout**: Timeout in milliseconds for the request (default: 1000ms).
- **Handle Timeout as Message**: If enabled, timeout errors are sent as regular messages instead of node errors.

**Output Properties:**

- `msg.payload`: The response data (or error object if timeout/service unavailable)
- `msg.status`: "success", "timeout", or "service_unavailable"
- `msg.topic`: The NATS subject used
- `msg.error`: Error details (only present when status is "timeout" or "service_unavailable")

**Node Status Indicators:**
- 🟢 **Grey "ready"**: Node ready for requests
- 🟡 **Yellow "requesting..."**: Request in progress
- 🟠 **Orange "timeout"**: Request timed out
- 🟠 **Orange "no service"**: Service unavailable (503)
- 🟠 **Orange "error"**: Other errors
- 🔴 **Red**: Server connection problem

The payload of the request can be set via the `msg.payload` property.


## Security

### 🔐 Enhanced Security Features

The OctoCore module includes comprehensive security features for production environments:

**Authentication Methods:**
- **No Authentication**: For local development
- **Username/Password**: Traditional authentication (backward compatible)
- **Token Authentication**: Single authentication token
- **JWT Authentication**: NATS 2.x JSON Web Token with NKey seed
- **NKey Authentication**: Cryptographic authentication

**TLS/SSL Encryption:**
- Enable/disable TLS encryption
- CA certificate verification
- Mutual TLS (mTLS) with client certificates
- Certificate verification options

**Security Best Practices:**
- All credentials stored encrypted in Node-RED's secure credentials system
- Automatic security warnings for production connections without TLS
- File-based certificate loading with path validation
- Debug logging with masked credentials

For detailed security documentation, see [SECURITY.md](SECURITY.md).

## Examples

### Comprehensive Example Flow

A complete example flow is included in the `examples/` directory. The flow demonstrates all OctoCore nodes with real-world use cases.

To use the example flow:
1. Import `examples/flows.json` into Node-RED
2. Or view it in the repository: [examples/flows.json](examples/flows.json)

See [examples/README.md](examples/README.md) for detailed documentation.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.


## Testing

Run the test suite:

```sh
npm test
```

For coverage reports:

```sh
npm test -- --coverage
```

## Links

- [Octotronic Website](https://www.octotronic.com)
- [Node-RED Documentation](https://nodered.org/docs/)
- [NATS Documentation](https://docs.nats.io/)



### Basic Example Flow

Here is a basic example flow that demonstrates how to use the `uns-publish`, `uns-subscribe`, and `uns-request` nodes:

```json
[
    {
        "id": "publish-node",
        "type": "uns-publish",
        "z": "0b30cc47ed4855ca",
        "name": "Publish to OctoCore",
        "server": "uns-server-config",
        "dataformat": "uns_value",
        "datapointid": "example.datapoint",
        "x": 1900,
        "y": 1100,
        "wires": []
    },
    {
        "id": "subscribe-node",
        "type": "uns-subscribe",
        "z": "0b30cc47ed4855ca",
        "name": "Subscribe from OctoCore",
        "server": "uns-server-config",
        "dataformat": "uns_value",
        "datapointid": "example.datapoint",
        "x": 1890,
        "y": 1140,
        "wires": [
            [
                "debug-node"
            ]
        ]
    },
    {
        "id": "request-node",
        "type": "uns-request",
        "z": "0b30cc47ed4855ca",
        "name": "Request from OctoCore",
        "server": "uns-server-config",
        "subject": "example.subject",
        "x": 1890,
        "y": 1200,
        "wires": [
            [
                "debug-node"
            ]
        ]
    },
    {
        "id": "debug-node",
        "type": "debug",
        "z": "0b30cc47ed4855ca",
        "name": "Debug",
        "active": true,
        "console": "false",
        "complete": "false",
        "x": 2210,
        "y": 1160,
        "wires": []
    },
    {
        "id": "fc641d9a3139e434",
        "type": "inject",
        "z": "0b30cc47ed4855ca",
        "name": "",
        "props": [
            {
                "p": "payload"
            },
            {
                "p": "topic",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "testtring",
        "payloadType": "str",
        "x": 1650,
        "y": 1100,
        "wires": [
            [
                "publish-node"
            ]
        ]
    },
    {
        "id": "6da3165904b618b3",
        "type": "inject",
        "z": "0b30cc47ed4855ca",
        "name": "",
        "props": [
            {
                "p": "payload"
            },
            {
                "p": "topic",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "10",
        "payloadType": "num",
        "x": 1650,
        "y": 1200,
        "wires": [
            [
                "request-node"
            ]
        ]
    },
    {
        "id": "uns-server-config",
        "type": "uns-server",
        "server": "nats://localhost:4222",
        "user": "username",
        "pass": "password"
    },
    {
        "id": "4a72a6bb1c07bac1",
        "type": "global-config",
        "env": [],
        "modules": {
            "node-red-contrib-octocore": "0.0.16"
        }
    }
]

```