doc/src/library/rt_tables.xfm

   1 .if false
   2 ==================================================================================
   3    Copyright (c) 2020 Nokia
   4    Copyright (c) 2020 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic:       rt_tables.xfm
  22         Abstract:       An overview of route tables in RMR.
  23         Date:           25 February 2020
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 .** constants
  28 .dv MT_REQ_TABLE 21
  29 .dv MT_TABLE_STATE      22
  30 .dv MT_TABLE_DATA 20
  31
  32 .dv RTMGR ^&ital(Route Manager)
  33
  34 .** -------------------------------------------------------------------------------
  35
  36 .** force setup to generate a title and to reverse title/subtitle for rst docs
  37 .dv GEN_TITLE 1
  38 .dv doc_title RIC Message Router -- RMR
  39 .dv doc_subtitle Route Table Guide
  40 .dv reverse_titles 1
  41
  42
  43 .dv textfont Helvetica
  44 .dv textsize 10p
  45 .dv index_snare_file index_snatch.im
  46 .dv orig_date 30 April 2020
  47
  48 .gv e XFM_PASS pass
  49
  50 .** setup will do the right thing with the index configuration; a common snatch
  51 .** file is used for all documents in this directory.
  52 .**
  53 .dv index_snare_file index_snatch.im
  54 .im setup.im
  55
  56
  57 &line_len( &line_size )
  58 .** -------------------------------------------------------------------------------
  59
  60 &h1(Overview)
  61 Messages sent via the RIC Message Router (RMR) are routed to an endpoint (another application)
  62 based on a combination of the &ital(message type) (MT) and &ital(subscription ID) (SID)
  63 supplied in the message.
  64 RMR determines the endpoint by matching the MT and SID combination to an entry in a route table
  65 which has been supplied dynamically by a &RTMGR service, or as a static table loaded
  66 during RMR initialisation.
  67 It is also possible to route messages directly to an endpoint which is the &ital(managed entity)
  68 "owner," using the &ital(managed entity ID) (MEID).
  69
  70 &space
  71 For most xAPP developers the format of the RMR route table is not important beyond understanding
  72 how to create a static table for local testing.
  73 For developers of a &RTMGR service, the need is certainly a requirement.
  74 This document describes the overall syntax of a route table and the interface between the
  75 &RTMGR service and RMR.
  76
  77
  78 &h1(Contents of a Route Table)
  79 The table consists of a start record, one or more entry records, and an end record.
  80 Each entry record defines one message type, with an optional sender application, and the endpoint(s) which
  81 accept the indicated message type.
  82 All table records contain fields separated with vertical bars (|), and allow for trailing comments with the
  83 standard shell comment symbol (hash, #) provided that the start of the comment is separated from the last
  84 token on the record by one or more spaces.
  85 Leading and trailing white space in each field is ignored.
  86 .gv fig
  87 Figure &_fig illustrates a very basic route table with two message types, 1000 and 2000, and two
  88 subscription IDs for message type 1000.
  89 &half_space
  90
  91 &ex_start
  92   newrt | start | rt-0928
  93   rte   | 2000  | logger:30311
  94   mse   | 1000  | 10 | forwarder:43086
  95   mse   | 1000  | 21 | app0:43086,app1:43086
  96   newrt | end   | 3
  97 &ex_end
  98 &fig(A basic route table.)
  99
 100
 101
 102 &h2(Entry record syntax)
 103 Two types of table entries are supported for compatibility with the original RMR implementation, but only the &ital(mse)
 104 entry type is needed and that should be the entry used when creating new tables.
 105 The following shows the syntax for both entry types:
 106 &space
 107
 108 &ex_start
 109  rte | <msg-type>[,<sender-endpoint>] | <endpoint-group>[;<endpoint-group>;...]
 110  mse | <msg-type>[,<sender-endpoint>] | <sub-id> | <endpoint-group>[;<endpoint-group>;...]
 111 &ex_end
 112 &space
 113
 114 Where:
 115 &half_space
 116
 117 &indent
 118 &beg_dlist( 1i : Helvetica-bold : 25,70 )
 119 &ditem(mse, rte)
 120         is the table entry type
 121
 122 &ditem(<msg-type>)
 123         is the integer message type
 124
 125 &ditem(<sender-endpoint>)
 126         is the endpoint description of the message sender; only that sender will read the entry from the table,
 127         so a single table may be used for all senders when a common message type is delivered to varying endpoints based on senders.
 128         If the sender endpoint is omitted from the entry, then the entry will be used by all applications.
 129
 130 &ditem(<sub-id>)
 131         is the subscription id (integer) for subscription-based messages, or -1 if the message type is not subscription-based.
 132         An &ital(mse) entry with a sub-id of -1 is the &bold(same) as an &ital(rte) entry with the same message type.
 133
 134 &ditem(<endpoint-group>)
 135         is one or more, comma separated, endpoint descriptions.
 136 &end_dlist
 137 &uindent
 138 &space
 139
 140 When an application sends a message with the indicated type, the message will be sent to one endpoint in the group in a
 141 round-robin ordering.
 142 If multiple endpoint groups are given, then the message is sent to a member selected from each group; 3 groups, then three
 143 messages will be sent.
 144 The first group is required.
 145
 146 &h3(Line separation)
 147 Table entries &bold(must) end with a record termination sequence which may be one of the following
 148 three sequences:
 149 &half_space
 150 &indent
 151 &beg_list(&lic1)
 152 &li a single newline (&{backslant}n)
 153 &li a DOS style CRLF pair (&{backslant}r&{backslant}n)
 154 &li a single carriage return (&{backslant}r)
 155 &end_list
 156 &uindent
 157
 158 &space
 159
 160 Care must be taken when manually editing a static table; some editors do &bold(not) add
 161 a final record termination sequence to the last line of a file.
 162 RMR expects the final record to have a termination sequence to ensure that the
 163 record was not truncated (especially important when receiving dynamic tables).
 164
 165 &h2(Table framing)
 166 The route table parser within RMR assumes that route table entries are sent via RMR messages as a
 167 stream.
 168 To ensure synchronisation and prevent malformed tables because of broken sessions or lost packets,
 169 each table must begin and end with an &ital(newrt) record.
 170 Each &ital(newrt) record has one of two possible syntax layouts as described below.
 171
 172 &half_space
 173 &ex_start
 174   newrt | begin [| table-id-string]
 175   newrt | end  [| record-count]
 176 &ex_end
 177 &fig(Illustration of the newrt records in the table.)
 178 &space
 179
 180 The &ital(table-id-string) is an optional string which is used by RMR when sending an acknowledgement
 181 back to the &RTMGR service (see the &ital(Route Manager Interface) section for more details).
 182 If a &ital(record-count) is given as the final field on the &ital(end) record, RMR will verify that the
 183 number of &ital(mse) and &ital(rte) entries in the table matches the count; if there is a mismatch in
 184 values the table is not used.
 185
 186
 187 &h2(Comments, spaces, and blank lines)
 188 Comments may be placed to the right of any table entry line using the standard
 189 shell comment symbol (#).
 190 The start of a comment must be separated from any previous record content by at least one space or tab.
 191 Complete lines are treated as comments when the first non-whitespace character of a line is a comment symbol.
 192 Blank lines are also ignored.
 193
 194 &space
 195 Fields on table records are separated using the vertical bar (|) character.
 196 Any white space (tabs or spaces) which appear immediately before or after a separator are ignored.
 197
 198
 199 &h2(Endpoint Description)
 200 The endpoint description is either the hostname or IP address followed by a port number; the two are separated by a single colon.
 201 The illustration below assumes that host names (e.g. forwarder and app1) are defined;
 202 they also make the tables easier to read.
 203 The port number given is the port number that the user application provides to RMR when the RMR initialisation function is
 204 invoked (and thus is the port that RMR is listening on).
 205
 206
 207 &h1(Table Mechanics)
 208 Creating a table from the two entry types is fairly simple,
 209 however there are some subtleties which should be pointed out to avoid unexpected behaviour.
 210 For this discussion the following complete table will be used.
 211
 212 .cc 20
 213
 214 &space
 215 &beg_table_nb( 75,10  : 4.5i .3i)
 216 &row
 217 &ex_start
 218   newrt | start | rt-0928
 219   rte | 2000 | logger:30311
 220   mse | 1000 | 10 | forwarder:43086
 221   mse | 1000,forwarder:43086 | 10 | app2:43086
 222   mse | 1000 | -1 | app0:43086,app1:43086; logger:20311
 223   newrt | end | 4
 224 &ex_end
 225 &col
 226 &ex_start
 227 (1)
 228 (2)
 229 (3)
 230 (4)
 231 (5)
 232 (6)
 233 &ex_end
 234 &end_table
 235
 236 .gv fig
 237 .dv table_fig &_fig
 238 &fig( A complete RMR routing table (line numbers to the right for reference). )
 239
 240 &h2(Table Entry Ordering)
 241 Whether a table is read from a file on disk, or is received from a &RTMGR service,
 242 RMR parses the records to build an internal route table keeping only the relevant information.
 243 Entries are read in the order they appear (from the file or in messages received), and
 244 RMR will use only one entry for each MT/SID pair.
 245 &space
 246
 247 For most tables, the ordering of entries is not important, but when there are entries
 248 which duplicate the MT/SID pair ordering becomes significant.
 249 RMR will use the &bold(last) valid entry for a MT/SID pair that it encounters.
 250 An entry is considered valid if there is no sender identified with the message type (line 3),
 251 and when the sender (host and port) match the the applications' location and the port provided
 252 to RMR for listening.
 253 &space
 254
 255 Using the table in figure &table_fig as an example, there are two entries which match the
 256 MT/SID pair of 1000/10.
 257 When this table is parsed on any host, RMR will recognise and add the first entry (line 3)
 258 to the internal representation; this entry is valid for all applications.
 259 The second 1000/10 entry (line 4) is valid when the table is parsed on the &ital(forwarder) host, and
 260 only by the application which is listening on port 43086.
 261 For this application the entry will override the more generic entry for the MT/SID combination.
 262
 263 &space
 264 As a rule, the ordering of entries for a given MT/SID pair should be from most generic to
 265 most specific.
 266
 267
 268
 269 &h1(Route Manager Communications)
 270 During initialisation RMR will use the value of the  &cw(RMR_RTG_SVC) environment variable to
 271 connect to  the &RTMGR service in order to request a route table.
 272 The connection between RMR and the &RTMGR is also an RMR session and thus
 273 RMR messages will be used to exchange requests and responses.
 274
 275 &h2(Table Request)
 276 During initialisation, RMR will establish a wormhole connection to the &RTMGR and sends
 277 a message type of &MT_REQ_TABLE to request a new table.
 278 RMR will continue to send table requests until a table is received and accepted; in other
 279 words it is fine for the &RTMGR to ignore the requests if it is not ready to respond.
 280
 281 &h2(Sending Tables To RMR)
 282 Table entry data is expected to arrive via RMR message with a message type of &MT_TABLE_DATA.
 283 The message may contain one or more entries provided that the entries are newline separated.
 284 Current versions of RMR support very large messages, however to ensure compatibility with
 285 an xAPP built using an older version of RMR (pre 3.8), messages should be limited to 4 KiB.
 286
 287 &h2(Table Acceptance and Acknowledgement)
 288 When RMR receives the table end entry (newrt|end), it will send a state message back to
 289 the &RTMGR to indicate the state of the received table.
 290 The message type is &MT_TABLE_STATE and the payload will contain UTF-8 tokens which indicate the state.
 291 The second token will be the &ital(table ID) supplied on the start record, or the string "<id-missing>."
 292 When the state is an error state, RMR might add a final set of tokens which contain the reason
 293 for the failure.
 294 &space
 295
 296 Upon receipt of a status message which indicates an "OK" response, the &RTMGR can assume that
 297 the table has been installed and is in use.
 298 Any other response indicates that RMR did not use the table and has dropped it; the previous
 299 table is still in use.
 300
 301
 302
 303
 304 &h1(Providing A Static Table)
 305 For testing, or possibly bootstrapping purposes, a static route table can be supplied.
 306 During initialisation, RMR will check the &cw(RMR_SEED_RT) environment variable.
 307 If it exists, and references a file, RMR will open and read the file expecting to find
 308 a static route table.
 309 This route table is used until an update is received from a &RTMGR.
 310 Normally, when the RMR initialisation function is invoked, a listener is started to receive route table information from a route
 311 manager process.
 312 During testing it is often useful to supply a static table which is available should no route management process exist,
 313 or to provide a seed table to use before the first table is delivered.
 314 The environment variable &cw(RMR_SEED_RT)  can be set to provide the RMR initialisation function with the name
 315 of the static table to use.
 316 If a static table is provided, it will be loaded only once, and will be overlaid if
 317 a dynamically delivered table is received.
 318
 319
 320
 321 &h1(Routing Using MEID)
 322 Starting with version 1.13.0, RMR provides the ability to select the endpoint for a message based on the MEID (managed entity ID)
 323 in the message, rather than selecting the endpoint from the round-robin list for the matching route table entry.
 324 When the MEID is used, the message is sent to the endpoint which &ital(owns,) or is responsible for the managed entity.
 325 Should the &ital(owner) change messages will be routed to the new owner when the route table is updated.
 326 To make use of MEID routing, there must be one or more route table entries which list the special endpoint name &cw(%meid)
 327 instead of providing a round robin list.
 328 As an example, consider the following route table entry:
 329 &space
 330
 331 &ex_start
 332   mse| 1000,forwarder:43086 | 10 | %meid
 333 &ex_end
 334 &fig( Sample route entry with the meid flag.)
 335 &space
 336
 337 The final field of the entry doesn't specify a round-robin group which means that when an application attempts to send a message
 338 with type 1000, and the subscription ID of 10, the MEID in the message will be used to select the endpoint.
 339
 340
 341
 342 &h2(MEID endpoint selection)
 343 To select an endpoint for the message based on the MEID in a message, RMR must know which endpoint owns the MEID.
 344 This information, known as an MEID map,  is provided by the &RTMGR over the same communication path as the route
 345 table is supplied.
 346 The following is the syntax for an MEID map.
 347 &half_space
 348
 349
 350 &ex_start
 351   meid_map | start | <table-id>
 352   mme_ar | <owner-endpoint> | <meid> [<meid>...]
 353   mme_del | <meid> [<meid>...]
 354   meid_map | end | <count> [| <md5sum> ]
 355 &ex_end
 356 &fig( Meid map table.)
 357 &space
 358
 359 The mme_ar records are add/update records and allow for the list of MEIDs to be associated with (owned by) the indicated endpoint.
 360 The <owner-endpoint> is the hostname:port, or IP address and port, of the application which owns the MEID and thus should
 361 receive any messages which are routed based on a route table entry with %meid as the round-robin group.
 362  The mme_del records allow  for MEIDs to be deleted from RMR's view.
 363 Finally, the <count> is the number of add/replace and delete records which were sent; if RMR does not match the <count> value
 364 to the number of records, then it will not add the data to the table.
 365  Updates only need to list the ownership changes that are necessary; in other words, the &RTMGR does not need to supply
 366 all of the MEID relationships with each update.
 367 &space
 368
 369 The optional <md5sum> field on the end record should be the MD5 hash of all of the records between the start and end records.
 370 This allows for a precise verification that the transmitted data was correctly received.
 371 &space
 372
 373 If a static seed file is being used for the route table, a second section can be given which supplies the MEID map.
 374 The following is a small example of a seed file:
 375 &half_space
 376
 377 &ex_start
 378  newrt|start | id-64306
 379  mse|0|-1| %meid
 380  mse|1|-1|172.19.0.2:4560
 381  mse|2|-1|172.19.0.2:4560
 382  mse|3|-1|172.19.0.2:4560
 383  mse|4|-1|172.19.0.2:4560
 384  mse|5|-1|172.19.0.2:4560
 385  newrt|end
 386
 387  meid_map | start | id-028919
 388  mme_ar| 172.19.0.2:4560 | meid000 meid001 meid002 meid003 meid004 meid005
 389  mme_ar| 172.19.0.42:4560 | meid100 meid101 meid102 meid103
 390  mme_del | meid1000
 391  meid_map | end | 1
 392 &ex_end
 393 &fig( Illustration of both a route table and meid map in the same file. )
 394 &space
 395
 396 The tables above will route all messages with a message type of 0 based on the MEID.
 397 There are 10 meids which are owned by two different endpoints.
 398 The table also deletes the MEID meid1000 from RMR's view.
 399
 400
 401 &h1(Reserved Message Types)
 402 RMR is currently reserving message types in the range of 0 through 99 (inclusive) for its own use.
 403 Please do not use these types in any production or test environment as the results may be undesired.
 404
 405 .** -- appendices ------------------------------
 406
 407 .dv gloss_appendix A
 408 .pa
 409 .im glossary.im
 410
 411 .** ----------- end housekeeping ---------------
 412
 413 .** if pfm and index was setup, include it now
 414 .if index_here
 415         .st 8p
 416         &index_here
 417         .st &textsize
 418 .fi
 419 .pa
 420
 421 .** capture all interesting variables to be used as forward references during pass 2
 422 .ca expand start p1var_setup.ca
 423         .** pass 1 variable settings -- do NOT commit to repo
 424
 425         .** set vars which need to be referenced prior to use, for example:
 426         .** .dv qr_appendix &qr_appendix
 427 .ca end