<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		<emphasis>RabbitMQ</emphasis>
		(<ulink url='http://www.rabbitmq.com/'>http://www.rabbitmq.com/</ulink>) 
		is an open source messaging server. It's purpose is to
		manage received messages in queues, taking advantage of
		the flexible AMQP protocol.
	</para>
	<para>
		Using this module you can send AMQP messages to a RabbitMQ server.
		Messages can be easily customized according to the AMQP specifications,
		as well the RabbitMQ extensions.
	</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
			The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>tls_mgm</emphasis> if <xref linkend="param_use_tls"/> is enabled.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>librabbitmq-dev</emphasis>
			</para>
			</listitem>
			</itemizedlist>
	</section>
	
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_server_id" xreflabel="server_id">
		<title><varname>server_id</varname> (string)</title>
		<para>
			Specify configuration for a RabbitMQ server. It contains a set
			of parameters used to customize the connection to the server,
			as well as to the messages sent. The format of the parameter is
			<emphasis>[id_name] param1=value1; param2=value2;</emphasis>.
			The <emphasis>uri</emphasis> parameter is mandatory.
		</para>
		<para>
			This parameter can be set multiple times, for each RabbitMQ
			server.
		</para>
		<para>
			The following parameters can be used:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>uri</emphasis> - Mandatory parameter - a full
				<emphasis>amqp</emphasis> URI as described
				<ulink url='https://www.rabbitmq.com/uri-spec.html'>here</ulink>.
				Missing fields in the URI will receive default values,
				such as: <emphasis>user: guest</emphasis>,
				<emphasis>password: guest</emphasis>,
				<emphasis>host: localhost</emphasis>,
				<emphasis>vhost: /</emphasis>,
				<emphasis>port: 5672</emphasis>. TLS connections are specified
				using an <emphasis>amqps</emphasis> URI.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>frames</emphasis> - the maximum size of an AMQP
				frame. Optional parameter, default size is 131072.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>retries</emphasis> - the number of retries in case
				a connection is down. Optional parameter, default is disabled
				(do not retry).
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>exchange</emphasis> - exchange used to send AMQP
				messages to. Optional parameter, default is <emphasis>""</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>heartbeat</emphasis> - interval in seconds used
				to send heartbeat messages. Optional parameter, default is
				disabled.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>immediate</emphasis> - indicate to the broker that
				the message MUST be delivered to a consumer immediately.
				Optional parameter, default is not immediate.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>mandatory</emphasis> - indicate to the broker that
				the message MUST be routed to a queue. Optional parameter,
				default is not mandatory.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>non-persistent</emphasis> - indicates that the
				message should not be persistent in case the RabbitMQ
				server restarts. Optional parameter, default is persistent.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tls_domain</emphasis> - indicates which TLS domain (as
				defined using the <emphasis>tls_mgm</emphasis> module) to use for
				this connection. This must be an <emphasis>amqps</emphasis> URI and the
				<xref linkend="param_use_tls"/> module parameter must be enabled.
			</para>
			</listitem>
			</itemizedlist>
		</para>
		<example>
		<title>Set <varname>server_id</varname> parameter</title>
		<programlisting format="linespecific">
...
# connection to a RabbitMQ server on localhost, default port
modparam("rabbitmq", "server_id","[ID1] uri = amqp://127.0.0.1")
...
# connection with a 5 seconds interval for heartbeat messages
modparam("rabbitmq", "server_id","[ID2] uri = amqp://127.0.0.1;
heartbeat = 5")
...
# TLS connection
modparam("rabbitmq", "server_id","[ID3] uri = amqps://127.0.0.1; tls_domain=rmq")
...
		</programlisting>
		</example>
	</section>

	<section id="param_use_tls" xreflabel="use_tls">
		<title><varname>use_tls</varname> (integer)</title>
		<para>
		Setting this parameter will allow you to use TLS for broker connections.
		In order to enable TLS for a specific connection, you can use the
		"tls_domain=<emphasis>dom_name</emphasis>" parameter in the configuration
		specified through the <xref linkend="param_server_id"/> module parameter.
		</para>
		<para>
		When using this parameter, you must also ensure that
		<emphasis>tls_mgm</emphasis> is loaded and properly configured. Refer to
		the the module for additional info regarding TLS client domains.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis role='bold'>0</emphasis> (not enabled)
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>use_tls</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("tls_mgm", "client_domain", "rmq")
modparam("tls_mgm", "certificate", "[rmq]/etc/pki/tls/certs/rmq.pem")
modparam("tls_mgm", "private_key", "[rmq]/etc/pki/tls/private/rmq.key")
modparam("tls_mgm", "ca_list",     "[rmq]/etc/pki/tls/certs/ca.pem")
...
modparam("rabbitmq", "use_tls", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_connect_timeout" xreflabel="connect_timeout">
		<title><varname>connect_timeout</varname> (integer)</title>
		<para>
		The maximally allowed duration (in milliseconds) for the establishment
		of a TCP connection with a RabbitMQ server.
		</para>
		<para>
		<emphasis>
			Default value is <quote>500</quote> (milliseconds).
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>connect_timeout</varname> parameter</title>
		<programlisting format="linespecific">

aram("rabbitmq", "connect_timeout", 1000)

</programlisting>
		</example>
	</section>

	<section id="param_timeout" xreflabel="timeout">
		<title><varname>timeout</varname> (integer)</title>
		<para>
		Indicates the timeout (in milliseconds) of any command (i.e. publish)
		sent to the RabbitMQ server.
		</para>
		<para>
		<emphasis>NOTE</emphasis> that this parameter is available only starting with
		RabbitMQ library version <emphasis>0.9.0</emphasis>; setting it when using an
		earlier version will have no effect, and the publish command will run in
		blocking mode.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis role='bold'>0</emphasis> (no timeout - blocking mode)
		</emphasis>
		</para>
		<example>
		<title>Set the <varname>timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rabbitmq", "timeout", 1000) # timeout after 1s
...
</programlisting>
		</example>
	</section>

	</section>
	

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<section id="func_rabbitmq_publish" xreflabel="rabbitmq_publish()">
			<title>
				<function moreinfo="none">rabbitmq_publish(server_id, routing_key, message 
					[, [content_type [, headers, headers_vals]]])</function>
			</title>
			<para>
				Sends a publish message to a RabbitMQ server.
			</para>
			<para>
				This function also allows you to attach AMQP headers and values
				in the AMQP message. This is done by specifying a set of headers
				names (in the <emphasis>headers</emphasis> parameter) and the
				corresponding values (in the <emphasis>headers_vals</emphasis>
				parameter). The number of AVP values in the
				<emphasis>headers</emphasis> must be the same as the one in the
				<emphasis>headers_vals</emphasis>.
			</para>
			<para>
				This function can be used from any route.
			</para>
			<para>
			The function has the following parameters:
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis>server_id</emphasis> (string) - the id of the RabbitMQ server.
						Must be one of the parameters defined in the
						<emphasis>server_id</emphasis> modparam.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>routing_key</emphasis> (string) - routing key used to
						deliver the AMQP message.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>message</emphasis> (string) - the body of the message.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>content_type</emphasis> (string, optional) - content type
						of the message sent. By default it is <emphasis>none</emphasis>.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>headers</emphasis> (string, optional) - an AVP containing
						the names of the headers within the AMQP message. If set,
						<emphasis>headers_vals</emphasis> parameter must also be specified.
					</para>
				</listitem>
				<listitem>
					<para>
						<emphasis>headers_vals</emphasis> (string, optional) - an AVP containing
						the corresponding values of the AMQP headers. If set,
						<emphasis>headers</emphasis> parameter must also be specified.
					</para>
				</listitem>
			</itemizedlist>
			<example>
			<title><function>rabbitmq_publish()</function> function usage</title>
			<programlisting format="linespecific">
	...
	rabbitmq_publish("ID1", "call", "$fU called $rU");
	...
	rabbitmq_publish("ID1", "call", "{ \'caller\': \'$fU\',
					\'callee\; \'$rU\'", "application/json");
	...
	$avp(hdr_name) = "caller";
	$avp(hdr_value) = $fU;
	$avp(hdr_name) = "callee";
	$avp(hdr_value) = $rU;
	rabbitmq_publish("ID2", "call", $rb, , $avp(hdr_name), $avp(hdr_value));
	...
	</programlisting>
			</example>
		</section>
	</section>

</chapter>
