TT#91150 document HTTP/WS interfaces

Change-Id: Ie4e70f1756f8f831b75377d52b55116ab42c1336

README.md

@@ -25,6 +25,7 @@ Features
 * Automatic fallback to normal userspace operation if kernel module is unavailable
 * Support for *Kamailio*'s *rtpproxy* module
 * Legacy support for old *OpenSER* *mediaproxy* module
+* HTTP, HTTPS, and WebSocket (WS and WSS) interfaces
 
 When used through the *rtpengine* module (or its older counterpart called *rtpproxy-ng*),
 the following additional features are available:
@@ -1860,3 +1861,47 @@ command. Sample return dictionary:
 	  },
 	  "result": "ok"
 	}
+
+HTTP/WebSocket support
+======================
+
+If enabled in the config, *rtpengine* can handle requests made to it via HTTP,
+HTTPS, or WebSocket (WS or WSS) connections. The supported HTTP URIs and
+WebSocket subprotocols are described below.
+
+Dummy Test Interfaces
+---------------------
+
+For HTTP and HTTPS, the URI `/ping` is provided, which simply responds with
+`pong` if requested via `GET`. For WebSockets, the subprotocol
+`echo.rtpengine.com` is provided, which simply echoes back any messages that
+are sent to it.
+
+CLI Interface
+-------------
+
+This interface supports the same commands as the CLI tool `rtpengine-ctl` that
+comes packaged with `rtpengine`. For HTTP and HTTPS, the command is appended to
+the URI base `/cli/` and the request is made via `GET`, with spaces replaced by
+plus signs as required by HTTP (e.g. `GET /cli/list+totals`). For WebSockets,
+the subprotocol is `cli.rtpengine.com` and each WebSocket message corresponds
+to one CLI command and produces one message in response. The format of each
+response is exactly the same as produced by the CLI tool `rtpengine-ctl` and
+therefore meant for plain text representation.
+
+*ng* Protocol Interface
+-----------------------
+
+This interface can be used to send and receive *ng* protocol messages over HTTP
+or WebSocket connections instead of plain UDP.
+
+For HTTP and HTTPS, the URI `/ng` is used, with the request being made by
+`POST` and the content-type set to `application/x-rtpengine-ng`. The message
+body must be in the same format as the body of an UDP-based *ng* message and
+must therefore consist of a unique cookie string, followed by a single space,
+followed by the message in *bencode* format. Likewise, the response will be in
+the same format, including the unique cookie.
+
+For WebSockets, the subprotocol `ng.rtpengine.com` is used and the protocol
+follows the same format. Messages must consist of a unique cookie and a string
+in bencode format, and responses will also be in the same format.

daemon/rtpengine.pod

@@ -694,6 +694,33 @@ tags, etc are recorded to the log. Every RTCP packet is logged in this way,
 while every 512th RTP packet is logged. Only applies to packets
 forwarded/processed in userspace.
 
+=item B<--listen-http=>[I<IP>|I<HOSTNAME>B<:>]I<PORT>
+
+=item B<--listen-https=>[I<IP>|I<HOSTNAME>B<:>]I<PORT>
+
+Enable listening for HTTP or WebSocket connections, or their TLS-secured
+counterparts HTTPS and WSS. If no interface is specified, then the listening
+socket will be bound to all interfaces.
+
+The HTTP listener supports both HTTP and WS, while the HTTPS listener supports
+both HTTPS and WSS.
+
+If HTTPS/WSS is enabled, a certificate must also be provided using the options
+below.
+
+=item B<--https-cert=>I<FILE>
+
+=item B<--https-key=>I<FILE>
+
+Provide a server certificate and corresponding private key for the HTTPS/WSS
+listener, in PEM format.
+
+=item B<--http-threads=>I<INT>
+
+Number of worker threads for HTTP/HTTPS/WS/WSS. If not specified, then the same
+number as given under B<num-threads> will be used. If no HTTP listeners are
+enabled, then no threads are created.
+
 =back
 
 =head1 INTERFACES