.. _user/protocols/kafka:

*****
Kafka
*****

Overview
========

Apache Kafka is a software framework for stream-processing of large amounts of
data. It is an open-source software platform developed by the Apache Software
Foundation, written in Scala and Java. The project aims to provide a unified,
high-throughput, low-latency platform for handling real-time data feeds.

This protocol implementation allows to send the data from the Connectware to an
Apache Kafka broker for message processing or to subscribe to a particular topic
to receive data.

Currently, the protocol supports authentification by means of SASL and compression of produced
messages by using GZIP.

.. _user/protocols/kafka/messages:

Message assembly
================

The endpoints in this protocol are available for the ``write`` and ``subscribe`` operations only.
To transmit messages to the Kafka broker, a JSON message with the payload as
``value`` needs to be sent to the respective endpoint. The message may look as
follows when producing messages to the broker:

.. code-block:: javascript

    {
      "id": 123321,
      "topic": "some_test_topic",
      "acks": 1,
      "timeout": 3000,
      "compression": "None",
      "value": [
        {
          "key": "sample-key 1",
          "value": "sample message #1",
          "partition": 0,
          "headers": {
            "foo": "bar"
          },
          "timestamp": 1633425301000
        },
        {
          "key": "sample-key 2",
          "value": "sample message #2",
          "partition": 1,
          "headers": {
            "foo": "bar"
          },
          "timestamp": 1633425301001
        }
      ]
    }

Which upon successful delivery, the following message will be generated on the ``/res`` topic:

.. code-block:: javascript

  {
    "id": 123321,
    "timestamp": 1633425302878,
    "result": {
      "value": [
        {
          "topicName": "some_test_topic",
          "partition": 0,
          "errorCode": 0,
          "baseOffset": "0",
          "logAppendTime": "-1",
          "logStartOffset": "0"
        },
        {
          "topicName": "some_test_topic",
          "partition": 1,
          "errorCode": 0,
          "baseOffset": "0",
          "logAppendTime": "-1",
          "logStartOffset": "0"
        }
      ]
    }
  }

And when delivery is unsuccessful, you will get the following message explaining what happened:

.. code-block:: javascript

  {
    "id": 123321,
    "timestamp": 1633425495764,
    "error": {
      "code": -1,
      "message": "Connection error: connect ECONNREFUSED 192.168.0.1:9092"
    }
  }

Upon subscription you will get messages like this:

.. code-block:: javascript

  {
    "timestamp": 1649046618574,
    "value": {
      "topic": "some_test_topic",
      "partition": 0,
      "key": "totally optional msg key",
      "headers": {
      },
      "message": "test 123 test msg body"
    }
  }

Commissioning File Specifics
============================

The Endpoints for the Kafka connections may only be of the type ``write`` or ``subscribe``.

Special care must be taken when configuring the connection properties since connections can only
take all write endpoints or all subscribe endpoints. But not both at the same time.

To choose the type of connection you are planning to use, you will need to configure the property ``clientType`` on the connection resource.

Further configuration options are listed below:

.. _user/protocols/kafka_connection:

.. include:: ../protocolSchemas/KafkaConnection.rst

.. _user/protocols/kafka_endpoint:

.. include:: ../protocolSchemas/KafkaEndpoint.rst

Sample Commissioning File
=========================

Download producer example: :download:`kafka-example-producer.yml`

.. literalinclude:: kafka-example-producer.yml
  :language: yaml
  :linenos:

Download consumer example: :download:`kafka-example-consumer.yml`

.. literalinclude:: kafka-example-consumer.yml
  :language: yaml
  :linenos: