nathelper: port add_contact_alias() and handle_ruri_alias()

Those are slightly better version of the fix_nated_contact()
originating from Kamailio.

The problem with fix_nated_contact() is that it could cause
RURI for in-dialog requests contain a different IP address as
compared to the Contact in the initial INVITE.

Most endpoints are fine with that, however tere are some,
notably MS Teams, which would reject such request with:

SIP/2.0 500 Internal Server Error
Reason: Q.850;cause=47;text="76a7afc3-d033-4988-9000-f70b41e4db1b;RURI in request has invalid FQDN value"

The full exchange when using fix_nated_contact() is as follows:

UA->OpenSIPS (initial INVITE):

opensips[42757]: RECEIVED message from 10.2.80.32:5060:
INVITE sip:[...]
Contact: <sip:[...]@10.2.80.22:5060>
                    ^^^^^^^^^^

OpenSIPS->UA:

SIP/2.0 100 Giving it a try

SIP/2.0 200 OK

UA->OpenSIPS:

ACK sip:[...]

OpenSIPS->UA (re-INVITE):

opensips[42759]: SENDING message to 10.2.80.32:5060:
INVITE sip:[...]@10.2.80.32:5060 SIP/2.0
                 ^^^^^^^^^^

UA->OpenSIPS:

SIP/2.0 500 Internal Server Error

Author: sobomax

modules/nathelper/README

@@ -43,6 +43,8 @@ nathelper Module
               1.5.3. add_rcv_param([flag]),
               1.5.4. fix_nated_register()
               1.5.5. nat_uac_test(flags)
+              1.5.6. add_contact_alias([ip_addr, port, proto])
+              1.5.7. handle_ruri_alias()
 
         1.6. Exported MI Functions
 
@@ -91,7 +93,9 @@ nathelper Module
    1.22. add_rcv_paramer usage
    1.23. fix_nated_register usage
    1.24. nat_uac_test usage
-   1.25. nh_enable_ping usage
+   1.25. add_contact_alias usage
+   1.26. handle_ruri_alias usage
+   1.27. nh_enable_ping usage
 
 Chapter 1. Admin Guide
 
@@ -595,6 +599,46 @@ if (nat_uac_test("private-contact,private-sdp"))
         xlog("SIP message is NAT'ed (Call-ID: $ci)\n");
 ...
 
+1.5.6.  add_contact_alias([ip_addr, port, proto])
+
+   Adds a standards-compliant “;alias=” parameter to the Contact URI
+   containing the signalling source IP, port and transport protocol
+   when they differ from the advertised Contact address.
+
+   Meaning of the parameters is as follows:
+     * ip_addr (string, optional) - IP to encode inside the alias. If
+       omitted, the message source IP is used.
+     * port (string, optional) - port to encode inside the alias. If
+       omitted, the message source port is used.
+     * proto (string, optional) - transport protocol to encode inside
+       the alias (for example “udp”, “tcp”, “tls”, “sctp”, “ws” or
+       “wss”). If omitted, the transport used to receive the message is
+       used.
+
+   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
+   BRANCH_ROUTE and FAILURE_ROUTE.
+
+   Example 1.25. add_contact_alias usage
+...
+        if (!add_contact_alias("$si", "$sp", "tcp")) {
+                xlog("[NAT] cannot create alias\n");
+        }
+...
+
+1.5.7.  handle_ruri_alias()
+
+   If the Request URI contains an “alias” parameter, the destination
+   URI is set based on its encoded IP, port and transport, and the
+   parameter is removed from the URI.
+
+   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
+   LOCAL_ROUTE.
+
+   Example 1.26. handle_ruri_alias usage
+...
+        handle_ruri_alias();
+...
+
 1.6. Exported MI Functions
 
 1.6.1. nh_enable_ping
@@ -607,7 +651,7 @@ if (nat_uac_test("private-contact,private-sdp"))
        parameter value greater than 0 or disables natping if
        parameter value is 0.
 
-   Example 1.25. nh_enable_ping usage
+   Example 1.27. nh_enable_ping usage
 ...
 $ opensips-cli -x mi nh_enable_ping
 Status:: 1

modules/nathelper/doc/nathelper_admin.xml

@@ -833,6 +833,55 @@ fix_nated_register();
 if (nat_uac_test("private-contact,private-sdp"))
 	xlog("SIP message is NAT'ed (Call-ID: $ci)\n");
 ...
+</programlisting>
+		</example>
+	</section>
+	<section id="nathelper.f.add_contact_alias">
+		<title>
+			<function moreinfo="none">add_contact_alias([ip_addr, port, proto])</function>
+		</title>
+		<para>
+			Adds an “alias” URI parameter to the Contact address that encodes the
+			signalling source IP, port and transport protocol when they differ from
+			the advertised Contact address.
+		</para>
+		<itemizedlist>
+			<listitem><para><emphasis>ip_addr</emphasis> (string, optional) - IP to encode
+			inside the alias. If omitted, the source IP of the SIP message is used.</para></listitem>
+			<listitem><para><emphasis>port</emphasis> (string, optional) - port to encode inside
+			the alias. If omitted, the source port of the SIP message is used.</para></listitem>
+			<listitem><para><emphasis>proto</emphasis> (string, optional) - transport protocol to
+			encode inside the alias (e.g. “udp”, “tcp”, “tls”, “sctp”, “ws” or “wss”). If omitted,
+			the transport used to receive the message is used.</para></listitem>
+		</itemizedlist>
+			<para>This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and
+			FAILURE_ROUTE.</para>
+		<example>
+		<title><function>add_contact_alias</function> usage</title>
+		<programlisting format="linespecific">
+...
+if (!add_contact_alias("$si", "$sp", "tcp")) {
+	xlog("[NAT] cannot create alias\n");
+}
+...
+</programlisting>
+		</example>
+	</section>
+	<section id="nathelper.f.handle_ruri_alias">
+		<title>
+			<function moreinfo="none">handle_ruri_alias()</function>
+		</title>
+		<para>
+			Parses an “alias” parameter from the Request URI, sets the destination URI based on its
+			contents and removes the parameter from the Request URI.
+		</para>
+		<para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.</para>
+		<example>
+			<title><function>handle_ruri_alias</function> usage</title>
+			<programlisting format="linespecific">
+...
+handle_ruri_alias();
+...
 </programlisting>
 		</example>
 	</section>