# Cybus::Node

A **Cybus::Node** resource describes a single data point managed by a [Cybus::Server](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/cybus-server). External clients can read values from a node or write values to it.

In a service definition, nodes are typically mapped via a [Cybus::Mapping](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/cybus-mapping) resource to application-specific MQTT topics. These MQTT topics reflect either:

* Data provided by the server to clients, or
* Data received by the server from connected external clients.

## Node Properties

| Property                          | Type       | Required     |
| --------------------------------- | ---------- | ------------ |
| [parent](#parent)                 | `string`   | **Required** |
| [operation](#operation)           | `string`   | Optional     |
| [transaction](#transaction)       | `object`   | Optional     |
| [rules](#rules-experimental)      | `object[]` | Optional     |
| [qos](#qos-experimental)          | `integer`  | Optional     |
| [retain](#retain-experimental)    | `boolean`  | Optional     |
| [targetState](#targetstate)       | `enum`     | Optional     |
| [topic](#topic)                   | `string`   | Optional     |
| [inputBuffering](#inputbuffering) | `object`   | Optional     |

### parent

Reference to another [Cybus::Node](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/cybus-node) which is the parent of this node, so that these relations define the hierarchical tree structure of the data points. For the top-most nodes of the tree, this property must refer to the [Cybus::Server](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/cybus-server) resource instead of a node resource.

* **Required**
* Type: `string`

### operation

For nodes which provide or receive data from an external client, this property defines the direction of the data flow.

* Type: `string`
* The value of this property **must** be one of:
  * `serverProvides`
  * `serverReceives`
  * `serverProvidesAndReceives`
  * `transaction`

The `transaction` value of the `operation` property only supports HTTP and OPC UA. For more information, see [FlowSync](https://docs.cybus.io/2-0-6/documentation/services/flowsync).

### transaction

This property is only available if `operation` is set to `transaction`. For more information on the `operation` property, see [operation](#operation).

The `transaction` property only supports HTTP and OPC UA. For more information, see [FlowSync](https://docs.cybus.io/2-0-6/documentation/services/flowsync).

* **Optional**
* Type: `object`
* Property values:
  * `timeout` (**Optional**)
    * Specifies the maximum duration to wait for a response in milliseconds.
    * **Default**: `10000` (10 seconds)
    * **Type**: `integer`
  * `timeoutErrorCode` (**Optional**)
    * Protocol specific error or status code that is returned when a transaction times out. The value and meaning depend on the configured protocol.
    * **Default**:
      * HTTP: `504` (Gateway Timeout)
      * OPC UA: `2156199936` (BadRequestTimeout)
    * **Type**: `integer`
  * `timeoutErrorMessage` (**Optional**)
    * A custom message to return when the timeout occurs.
    * **Type**: `string`
    * **Default**: `Flow did not finish in time`

For an example configuration using the `transaction` operation, see [Example 4 - Node with Timeout Error Code and Error Message (HTTP)](https://docs.cybus.io/2-0-6/documentation/services/flowsync/flowsync-example-4).

### rules (experimental)

* **Optional**
* Type: `array` of [Rule Engine](https://docs.cybus.io/2-0-6/documentation/services/rule-engine/data-processing-rules)

You may specify rules to your payload here before providing it to or after having received it from an external client.

### qos (experimental)

MQTT Quality of Service for the internal messaging between the data node of the server and the internal MQTT broker.

* **Optional**
* Type: `integer`
* Allowed values:
  * `0`
  * `1`
  * `2`
* Default: `0`

### retain (experimental)

Whether the last message should be retained (last-value-cached) on the internal MQTT broker.

* **Optional**
* Type: `boolean`
* Allowed values:
  * `true`
  * `false`
* Default: `false`

### targetState

The state this resource should be in after startup.

* **Optional**
* Type: `enum`
* Allowed values:
  * `enabled`
  * `disabled`
* Default: `enabled`

### topic

Explicit topic name to which this node’s MQTT address should be mapped.

The provided topic name is prefixed with the value of the [Cybus::MqttRoot](https://docs.cybus.io/2-0-6/documentation/services/parameters#cybusmqttroot) global parameter. This global parameter by default has the value `services/<serviceId>` where `<serviceId>` is replaced with the actual [ServiceID](https://docs.cybus.io/2-0-6/documentation/services/serviceid) of the current service. Hence, in the default case, the full node topic will expand to:

`services/<serviceId>/<topic>`

See the explanation at [Cybus::MqttRoot](https://docs.cybus.io/2-0-6/documentation/services/parameters#cybusmqttroot) if alternative topic structures are needed.

Providing a custom topic and avoiding an additional mapping resource improves overall performance as the message has to travel one hop less. Nodes with custom topics can still be mapped using a regular mapping (see [Cybus::Mapping](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/cybus-mapping)).

* **Optional**
* Type: `string`

### inputBuffering

Each node is internally subscribing to the MQTT broker in order to receive data from the broker and present it as the server node. This MQTT subscription can optionally be managed through an individual input buffer (also called input queue) to establish fine-grained control for high data rate behavior. By default, this input buffering is disabled and instead all input data is handled on the global event queue, which works fine as long as there is no risk of out-of-memory exceptions due to unexpected slow data processing or forwarding.

When enabling the individual input buffer, the buffer properties determine the behavior in situations when the input buffer is filling up. The buffer is filling up when the message arrival rate is larger than the processing data rate or the forwarding (publishing) data rate. Or, in other words, the input buffer is filling up if the messages arrive faster than how they can be processed or be forwarded (published). If this situation happens for longer time durations, the input buffer will reach its configured capacity limits and arriving messages will be dropped, so that the system will not run into an uncontrollable out-of-memory exception. This is a fundamental and unavoidable property of distributed systems due to its finite resources. But the actual behavior of the input buffer can be adapted to the actual application scenario by setting the properties in the `inputBuffering` section (optional).

Supported properties are (all **Optional**):

* `enabled` (**Type**: `boolean`, **Default**: `false`): Enable or disable input buffering.
* `maxInputBufferSize` (**Type**: `integer`, **Default**: `5000`): Maximum number of input messages that are queued in the input buffer. Exceeding messages will be discarded. Adjust this to a higher value if you are handling bursty traffic.
* `maxConcurrentMessages` (**Type**: `integer`, **Default**: `2`): Maximum number of concurrently processed messages as long as the input buffer queue is non-empty.
* `waitingTimeOnEmptyQueue` (**Type**: `integer`, **Default**: `10`): Waiting time in milliseconds after the input buffer queue ran empty and before checking again for newly queued input messages. Regardless of this value, on non-empty input buffer queue all messages will be processed without waiting time in between until the queue is empty again.

## Custom Node Properties

Depending on the protocol type of the node, additional custom properties are available:

* [Cybus::Node::Opcua](https://docs.cybus.io/2-0-6/industry-protocol-details/opc-ua/opc-ua-server#custom-node-properties)