Rtr
(message router) is used to pass transactions to servers connected to remote Orbs.
The router is a server connected to it's local Orb.
Any client requiring a service on a remote Orb sends a router (
RTR) request to it's local Orb where the request will be
assigned to the local router.
A path field in the message will provide the path the request must take to reach the remote router.
This path string is changed by each router until the message arrives at the end of the path where the "type" and "code" fields are changed and the message is sent to the local Orb for execution.
The two fields, "execType" and "execCode" are used as "type" and "code" fields when passed to the Orb at the destination.
Upon completion of the execution, the result is returned from the local Orb to the attached router where the "type" is changed back to RTRFWD and sent in the reverse direction back up the "path".
Currently, the router is single stream, that is, it can only handle one request at a time, hence each request will "lock up" all the routers handling it until the last response packet had been delivered.
The router waits a configuarble time for an operation to end.
If an optional integer field "rtrWatTim" is added to the first record of the message it will override the configured wait time (or timeout).
The "rtrWatTim" is in milliseconds.
A router is considered as a "Node" in a tree shaped network.
Routers must be told about lower (remote) nodes (Rtr s attached to an Orb), in their configuration files.
In essence, a router only knows about lower level nodes.
SinceOrbs don't speak directly to each other nor do routers, each time a message is routed to a remote host the local router sends the message to the remote Orb where it is assigned to that Orb's local router.
If that router is not the ultimate destination it forwards the message to another remote Orb.
The destination router substitutes execType for type and execCode for code then sends the request message to it's Orb.
When the response arrives, it is converted back to a router type with response code and passes the message back to the requesting router.
By using only the Orb's external address, we limit the number of exposed ports on any system.
Please see How CGI executes remote programs
A special interface (rtrMakReq) and other additions have been added to the msg layer to facilitate using Rtr.
The msg (messaging) interface layer is required for all servers and
clients who also use routing. The special fields used by the Orb
are:
"type" "code" "status" and "reqId"
The router adds 3 more fields:
"rtrPath" "execType" and "execCode"
An initial request, with type OSRVRTR and type RTRFWD will be assigned
by your local Orb to it's attached Rtr which will route it to a
remote server and return the response. The initial request requires
all seven of the above fields. Initially, "type" and "code"
are OSRVRTR and RTRFWD, respectively. The field "rtrPath"
contains a string representing the routing path ("Fred>Kate>Sam"
the execType and execCode contain the type and code for the end
service. The path "Fred>Kate>Sam" will route the message
to Fred, then Kate, then Sam. When the message arrives at Sam, it
will find there are no more forward pointers in the path and execute
it via his local Orb. Routed messages always start at the local
Orb. Multi-packet, big string requests & responses are allowed.
Router configuration keywords:
NODENAME
Sets the router's logical nodename used when routing. If this entry is
not in the config file, the logical process name is used as the NodeName.
SUBNODE Adds a sub-node the the router's list of known nodes.
int
rtrMakReq( char *dest, char *path, int xType, int xCode )
Create a new request message that will be routed to a server connected to a
remote Orb. The "path" consists of router names connected by
greater than symbols: "Fred>Kate>Sam" This "path"
controls the flow to the destination router "Sam" "xType"
and "xCode" will be used as Orb "type" and "code" at the
destination. One of these messages will contain the following
fields:
type
10
// Router service
code
5
// Forward
status
0
reqId
0
rtrPath
"Fred>Kate>Sam"
// Path to Sam where the request will be executed.
execType
11
// MoMo request type
execCode
4
// Some MoMo request for service.
As the message is passed from router to router the "rtrPath" field
content is changed but the overall length remains the same. An
initial rtrPath might look like this “Fred>Kate>Sam” and
route the message to Fred, then Kate, then Sam. Fred (the local
router) will change it to "Kate>Sam<Fred" and send it to
the router Kate. Kate will change rtrPath to "Sam<Kate<Fred"
and send it to Sam. Sam will request the service and change
"rtrPath" to "Kate>Fred<Sam" and send it to Kate.
Router's "code"s are defined in rtr.h. They are:
RTRLIST (4),
RTRFWD (5), and
RTRADDNODE (7).
RTRLIST
Requests the router to list it's own name ("nodeName" and
the list of the sub nodes it has been configured for ("nameList"
This may be used, along with RTRFWD, to "discover" the entire
tree of routers. The initial RTRLIST may have the rtrPath = "."”
which is understood by the message layer to be the local Orb and
router. One additional field is supplied, "“deviceType"” which
contains whatever was in /etc/gdg.conf: devicetype=xxx on the target
router's host.
RTRFWD
Causes the router to forward the message along the provided "rtrPath" for execution at the terminus of the path.
RTRADDNODE
Adds a sub-node the the router's list of known nodes. The field
"nodeName" contains the node to add in the form "4200 Blowfish
testme"
NOTE:
If you want to get multi-packet responses, you MUST create the request
using rtrMakReq() or at msgMakReq() and add your own "rtrPath"
"execType" "execCode" This adds the "questor" field
which the Orb must use for martialing. The "questor" field is a
string containing "
processName@hostName
" and is relatively unique.
