docs/kafka-message-dispatcher.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2022 Nordix
   4
   5 .. |nbsp| unicode:: 0xA0
   6    :trim:
   7
   8 .. |nbh| unicode:: 0x2011
   9    :trim:
  10
  11 .. |yaml-icon| image:: ./images/yaml_logo.png
  12                   :width: 40px
  13
  14 ========================
  15 Kafka Message Dispatcher
  16 ========================
  17
  18 API Documentation
  19 =================
  20
  21 The O-RAN SC Kafka Message Dispatcher is a specific implementation of an A1 Simulator ref:`calloutserver`, which further redirects A1 Policy operations to a Kafka message topic, to be consumed by an external function.
  22
  23 A1 Policy are redirected as Kafka messages to a configured Kafka Topic to an external receiver, then responses from the external receiver are collected from another configured Kafka Topic. This provides a Kafka-based request-response abstraction for adding supplemental simulator behavior for particular A1 Policy Types. After a request message is sent, a response message will be expected within some configurable timeout interval (default: 30 sec). The topics to be used for particular A1 Policy Types is configured using a JSON map (Example: `policytype_to_topicmap.json <../near-rt-ric-simulator/test/KAFKA_DISPATCHER/resources/policytype_to_topicmap.json>`
  24
  25 **Note:** As with other A1 Simulator call-out servers, the Kafka message dispatcher functionality is only available for *'STD_2.0.0'* version simulators.
  26
  27 The Kafka message dispatcher exposes a 'Kafka Message Dispatcher' REST API. This internal API is invoked directly by the A1 Simulator, and is not intended to be used by any other client.  This API is documented in `Kafka Message Dispatcher API <./KAFKA_DISPATCHER_api.html>`_ and in OpenAPI YAML format:
  28
  29 .. csv-table::
  30    :header: "API name", "|yaml-icon|"
  31    :widths: 10,5
  32
  33    "Kafka Message Dispatcher API", ":download:`link <../near-rt-ric-simulator/test/KAFKA_DISPATCHER/api/KAFKA_DISPATCHER_api.yaml>`"
  34
  35 The Kafka message dispatcher also exposes an 'Admin API' to manipulate the behavior of the Kafka message dispather itself. The 'Kafka Message Dispatcher Admin API' is documented below:
  36
  37 Admin Functions
  38 ================
  39
  40 Health Check
  41 ------------
  42
  43 GET
  44 +++
  45
  46 Returns the status of the Kafka Message Dispatcher.
  47
  48 **URL path:**
  49  /
  50
  51 **Parameters:**
  52   None.
  53
  54 **Responses:**
  55   200:
  56     OK
  57
  58 **Examples:**
  59
  60 **Call**: ::
  61
  62   curl -X GET "http://localhost:7075/"
  63
  64 **Result**:
  65
  66 200: ::
  67
  68   OK
  69
  70
  71 Response manipulation
  72 ---------------------
  73 It is possible to manipulate the response of all operations on the Kafka Message Dispatcher module
  74
  75 POST
  76 ++++
  77
  78 Force a specific response code for the all (the next) Kafka Message Dispatcher module operations. Unless it is reset, it will always respond the same response code back.
  79
  80 **URL path:**
  81
  82 /dispatcheradmin/forceresponse?code=<http-response-code>
  83
  84 **Parameters:**
  85
  86 code: (*Required*)
  87
  88 The HTTP response code to return.
  89
  90 **Responses:**
  91
  92 200:
  93
  94 Force response code: <expected code> set for all all dispatcher response until it is resetted
  95
  96 **Examples:**
  97
  98 **Call**: ::
  99
 100   curl -X POST "http://localhost:7075/dispatcheradmin/forceresponse?code=500"
 101
 102 **Result**:
 103
 104 200: ::
 105
 106   Force response code: 500 set for all dispatcher response until it is resetted
 107
 108
 109 Reset response-manipulation
 110 ---------------------------
 111 It is possible to reset the response manipulation on the Kafka Message Dispatcher module
 112
 113 POST
 114 ++++
 115
 116 Clears specific response code for all (the next) Kafka Message Dispatcher module operation.
 117
 118 **URL path:**
 119
 120 /dispatcheradmin/forceresponse
 121
 122 **Parameters:**
 123
 124 code: (*Required*)
 125
 126 The HTTP response code to return.
 127
 128 **Responses:**
 129
 130 200:
 131
 132 Force response code has been resetted for dispatcher responses
 133
 134 **Examples:**
 135
 136 **Call**: ::
 137
 138   curl -X POST "http://localhost:7075/dispatcheradmin/forceresponse"
 139
 140 **Result**:
 141
 142 200: ::
 143
 144   Force response code has been resetted for dispatcher responses
 145
 146
 147 Response time manipulation
 148 --------------------------
 149 It is possible to set a period of time to delay response time.
 150
 151 POST
 152 ++++
 153
 154 Force delayed response of all dispatcher responses. The setting will remain until the delay is cleared.
 155
 156 **URL path:**
 157
 158 /dispatcheradmin/forcedelay?delay=<delay-time-seconds>
 159
 160 **Parameters:**
 161
 162 delay: (*Required*)
 163
 164 The time in seconds to delay all responses.
 165
 166 **Responses:**
 167
 168 200:
 169
 170 Force delay: <expected_delay> sec set for all dispatcher responses until it is resetted
 171
 172 **Examples:**
 173
 174 **Call**: ::
 175
 176   curl -X POST "http://localhost:7075/dispatcheradmin/forcedelay?delay=5"
 177
 178 **Result**:
 179
 180 200: ::
 181
 182   Force delay: 5 sec set for all dispatcher responses until it is resetted
 183
 184
 185 Reset response time manipulation
 186 --------------------------------
 187 It is also possible to reset delay response time.
 188
 189 POST
 190 ++++
 191
 192 The setting will clear the delay.
 193
 194 **URL path:**
 195
 196 /dispatcheradmin/forcedelay
 197
 198 **Parameters:**
 199
 200 None.
 201
 202 The time in seconds to delay all responses.
 203
 204 **Responses:**
 205
 206 200:
 207
 208 Force delay has been resetted for all dispatcher responses
 209
 210 **Examples:**
 211
 212 **Call**: ::
 213
 214   curl -X POST "http://localhost:7075/dispatcheradmin/forcedelay"
 215
 216 **Result**:
 217
 218 200: ::
 219
 220   Force delay has been resetted for all dispatcher responses