1 2SOAP/XML over HTTP message router. 3 4Supports many HTTP message routing scenarios. 5 6Command-line options: 7 -a<action> action value override (SOAP Action) 8 -c connect directly to endpoint if routing table redirect fails 9 -e<URL> endpoint URL 10 -g<URL get content (instead of HTTP POST with -e) 11 -p<port> start stand-alone router on port 12 -r<file> routing table XML file 13 -t<sec> timeout 14 15Forwarding of messages to a service 16----------------------------------- 17 18router [-c] [-e<endpoint> | -g<endpoint>] [-a<SOAPAction>] [-r<routingfile>] [-t<timeout>] [<msgfile>] 19 20Examples: 21 221. 23router -c request.soap 24Sends the request message stored in file request.soap and returns 25response to stdout where file request.soap contains a SOAP request with 26HTTP header and SOAP/XML/DIME body. If the SOAPAction in the message is 27present and matches one or more keys in the routing table, the 28alternative service endpoints in the table will be tried first until 29one service endpoint is found to accept the connection. If no 30SOAPAction is given or the SOAPAction does not match any key, then the 31endpoint in the HTTP header in request.soap is searched in the routing 32table. If the endoint matches one or more keys in the routing table, 33the alternative endpoints will be tried first until one endpoint is 34found to accept the connection. Finally, the endpoint in the HTTP 35header of request.soap is used to establish a connection if all other 36service endpoints in the table failed and if option -c is enabled. 37 382. 39router -c -ehttp://domain/path request.soap 40Sends request message to http://domain/path and returns the service 41response to stdout. If http://domain/path matches one or more keys in 42the routing table, then the alternative service endpoints in the table 43will be tried first until one service endpoint is found to accept the 44connection. The http://domain/path endpoint is tried last when all 45other service endpoints in the table failed. File request.soap MAY 46contain an HTTP header but MUST of course contain a body. 47 48To try this, compile the 'calc' client (samples/calc). Edit the 49'calc.add.req.xml' SOAP/XML request file and replace <a> and <b> values. Then 50run: 51router -ehttp://www.cs.fsu.edu/~engelen/calcserver.cgi -a"" calc.add.req.xml 52The SOAP/XML response is returned. 53 543. 55router -aSOAPAction request.soap 56When SOAPAction matches one or more keys in the routing table, then the 57alternative endpoints in the table will be tried first until one 58endpoint is found to accept the connection. When all endpoints fail, 59or when SOAPAction does not match a key, the router fails. File 60request.soap MAY contain an HTTP header but MUST of course contain a 61body. 62 634. 64router -c -rroutingtable.xml request.soap 65Same as 1. but uses routingtable.xml as the routing table after 66checking keys in the internal routing table. The XSD schema of 67routingtable.xml is generated as t.xsd. The default routing table file 68is router.xml. 69 705. 71router -c -t5 request.soap 72Same as 1. but searches the routing table for an endpoint that takes 73less than 5 seconds to connect to. Use negative timeouts to specify a 74timeout value in microseconds. The timeout also specifies the message 75receive timeout AFTER the connection was established. 76 776. 78cat request.soap | router -ehttp://domain/path | more 79When request.soap does not contain an HTTP header, the router computes 80the HTTP content length by buffering the entire request message which 81allows you to use it as a filter as in this example. (fstat() is 82generally tried first to determine file length.) 83 847. 85router -ghttp://domain/path/file.html 86Sends an HTTP GET request to the host and copies the response to stdout. 87 88CGI-based relay server 89---------------------- 90 91Install the router as CGI application. The CGI-based relay service uses 92SOAPActions in the messages and HTTP query strings to index the routing 93table. 94 95Examples: 96 97Messages addressed to "http://domain/cgi-bin/router?key" will be routed 98by the router to the service endpoint associated with the key in the 99routing table. When messages use SOAPActions, the SOAPActions will be 100used to find service endpoints instead of a query string. 101 102To tunnel SOAP through firewals to stateful stand-alone Web services: 103run a stand-alone gSOAP Web service on a port, e.g. 18000. Add the 104key-endpoint pair "myservice", "http://localhost:18000" to the router 105table. After installing the router, all requests for endpoint 106http://domain/cgi-bin/router?myservice will be tunneled to the 107stand-alone Web service. 108 109To add backup services: add multiple key-endpoint pairs to the routing 110table with the same key. Given a key (e.g. SOAPAction or Query string) 111the router will check the endpoints in sequence until it can connect. 112If one or more of the backup services are down, an active service 113endpoint will be selected. 114 115Multi-threaded stand-alone relay server 116--------------------------------------- 117 118router -p<port> [-r<routingfile>] [-t<timeout>] & 119 120Examples: 121 122router -p18000 -rtable.xml -t5 & 123Runs a stand-alone router on port 18000 using table.xml as the external 124routing table for lookup. Service endpoints are selected from 125alternative endpoints that take less than 5 seconds to connect to. 126 127Clients connect to the router with a service endpoint such as 128"http://machine:<port>/path" where the endpoint "http://machine/path" 129(note the absence of the port) will be used as a key in the routing 130table to find an endpoint when no SOAPAction is present. For example, a 131stand-alone Web service called "quote" runs on a machine named "zulu" 132port 18080. To address this service through the router, add key 133"http://zulu/quote" and endpoint "http://zulu:18080" to the routing 134table. Run the router on port 18000. Router requests with endpoint 135"http://zulu:18000/quote" will be relayed to zulu:18080 136 137Gateway keeper 138-------------- 139 140When the routing table contains userid and passwd information, the 141client requests are only tunnelled when the proper HTTP Authorization 142userid and passwd are provided in the client request message. It is 143possible to provide different service endpoint in the table depending 144on the client's HTTP Authorization information. 145 146Notes 147----- 148 149* Table lookup algorithm: 150 SOAPActions (if provided) are used first to match routing table keys. 151 Next, HTTP query string in the endpoint URL (CGI only) is used to 152 match routing table keys. 153 Next, the service endpoint is checked to match routing table keys. 154 Finally, if the -c option is set the service endpoint URL itself is 155 used to connect. 156* Keys in routing table may contain * (multi-char) and - (single-char) 157 wildcards to match multiple SOAPActions and endpoints. 158* When a match is found but the endpoint is NULL in the table, the 159 search is terminated. This can be used to prevent searches in the 160 routing file for specific patterns. 161* Optional HTTP Authorization userid and passwd are checked if present 162 in the routing table. The userid and passwd may be patterns with '*' 163 and '-' wildcards. An endpoint in the table is selected for which 164 the userid and passwd match. 165* <timeout> is TCP connect and I/O timeout for router-server connection 166 in seconds (use negative value for timeout in microseconds). 167* When an external routing table is once read by a stand-alone router, 168 it will be cached to optimize speed. But this also means that 169 changing the contents of the routing table file does not affect the 170 actual routing while the stand-alone router is running. 171* HTTP POST and HTTP GET styles of SOAP messaging is supported 172 (but CGI-based router does not support HTTP GET) 173* Supports any type of messages (e.g. DIME) 174* HTTP cookies are not handled and will be deleted from the HTTP header 175* Keep-alive support has not been tested and might not work 176