.. include:: ./macros.inc
.. index:: tcp, tcps, SSL, authenticating users, transports

.. _#ug-transports:

18. Transports
===============

In order to send and receive messages, an AMPS server must allow
incoming connections. *Transports* configure incoming
connections to AMPS. Transports are configured in the ``Transports``
element of the AMPS configuration file.

AMPS provides two distinct kinds of incoming connections:

-  *Client connections*, for use by the AMPS clients to support external
   applications

-  *Replication connections*, to receive replicated messages from other AMPS instances

Each transport controls how authentication and entitlements are enforced
for that transport. The transport can either accept the defaults for the
instance as a whole, or choose settings unique to that transport.

Client Connections
------------------

To accept connections from publishers or subscribers, an AMPS instance
must have at least one ``Transport`` configured for client connections.
The transport must specify:

-  The network protocol used for the transport, called the transport
   *type*

-  The network address, such as IP address and port, that the AMPS
   server will listen to for incoming connections

-  Optionally, the AMPS command header format, called the *protocol*.
   The ``amps`` protocol is the default if no protocol is provided
   and is the protocol used by most applications.
   Websocket connections use the ``websocket`` protocol.

A transport can *optionally* set other parameters on the transport. This
includes setting the authentication and entitlements that apply to
connections for this transport, setting slow client parameters for the
transport, and so forth.

TCP Connections
^^^^^^^^^^^^^^^^

This is the most commonly used connection type for AMPS clients.

With this option, communication occurs over a standard TCP/IP
connection.

SSL Connections
^^^^^^^^^^^^^^^^

AMPS supports SSL connections between clients and servers. To enable SSL
on a transport, you must:

-  Specify a Transport type of ``tcp`` or ``tcps``, *and*

-  Provide a certificate and private key for the connection

You can optionally set other parameters for SSL connections, as
described in the |configref|.

.. caution::

   60East recommends using the ``tcps`` transport type for SSL      
   connections for clarity. However, AMPS uses SSL connections for  
   a ``tcp`` connection whenever a PrivateKey and Certificate are   
   provided for a Transport, regardless of whether the transport    
   ``Type`` is specified as ``tcp`` or ``tcps``.                    
                                                                    
   AMPS clients require that the connection string use ``tcps`` for 
   SSL connections, even if the AMPS Transport configuration uses   
   ``tcp``.                                                         

IPv6 Connections
^^^^^^^^^^^^^^^^
Starting with version 5.3.3, AMPS supports connections over both
IPv4 and IPv6 IP protocols if the host has IPv6 support enabled.

Both IPv4 and IPv6 IP address formats are fully supported for use
with specifying the network address of a transport.
The IP protocol version used for a transport is determined by the
network address format specified for the transport.
If only a port is specified and the host supports IPv6, AMPS will
listen for incoming connections over both IPv4 and IPv6 protocols. 

For outgoing connections, such as Replication Connections, AMPS fully
supports both IPv4 and IPv6 IP address formats. 
AMPS will prefer to resolve a URI to IPv4 addresses by default. 
The DNS resolution behavior can be specified as part of the configuration
of the Replication Destination.

Specific parameters and behavior related to IPv4 vs IPv6 connections
are described in the |configref|.

Unix Domain Sockets
^^^^^^^^^^^^^^^^^^^^

AMPS provides transports that use unix domain sockets for applications
that run on the same system as the AMPS server and require extremely
low-latency messaging. Unix domain sockets are not supported by all AMPS
clients, since some programming environments do not support these
sockets.

With this transport type, many of the configuration settings that apply
to TCP/IP sockets are not relevant. Instead, the transport requires the
name of a file on the local filesystem as the location at which to
create the socket.

WebSocket Protocol Connections
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _AMPS Command Reference: ../../../command-reference/html/index.html

To allow AMPS to be used directly from within
browser-based applications, the AMPS server supports
communication over WebSockets. An AMPS client
``Transport`` that uses ``tcp`` or ``tcps`` as the
underlying ``Type`` can be configured to use
the websocket ``Protocol`` for communication.
The AMPS JavaScript client library supports ``websocket``
protocol connections to AMPS (while the other client
libraries support ``amps`` protocol connections).

When a transport is configured to use the ``websocket``
protocol, a client that connects to that transport
sends an HTTP upgrade header indicating
that further communication should use the WebSocket
protocol. The AMPS server returns a response
indicating that it is switching protocols to WebSocket,
and further communication between the client and server
uses the proprietary AMPS protocol exchanged within
WebSocket frames. The contents of the frames are
AMPS messages, as described in the `AMPS Command Reference`_.
There is no difference in capability between connections
that use the ``websocket`` protocol and connections that
use the AMPS protocol. The commands exchanged between
the AMPS server and client are the same, although the
"on wire" format within which the commands are
exchanged is different.

A WebSocket connection to AMPS is a persistent,
full-duplex connection to the server. A
WebSocket connection is not a RESTful interface to
AMPS, nor does the connection support HTTP
beyond the initial upgrade request.


Replication Connections
------------------------

To receive replicated messages from other AMPS instances, an AMPS
instance must have a transport configured as Type ``amps-replication``.

Replication connections accept any message type, and can service
multiple upstream AMPS instances.

Replication connections are configured as part of an overall High
Availability plan. See :ref:`High Availability <#common-ha-overview>` and the |configref| for details.


Transport Filters
-----------------

AMPS provides the ability for incoming commands to be modified, or *filtered*.

When one or more transport filters are specified, AMPS provides each incoming
command to those filters as soon as the header for the message is parsed. Each 
filter can modify the message data or a subset of the headers, and can choose
to have AMPS stop processing the command (or can request that AMPS disconnect
the connection that submitted the command).

The filters for a ``Transport``, if any, are defined in the configuration for
the transport.  When more than one filter is specified, AMPS runs each filter
in the order in which they appear in the configuration file.

Transport filters are implemented as extension modules. To create an extension
module, contact AMPS support for the server SDK.

AMPS loads the following transport filters by default: 

+-----------------------------------------+------------------------------------------------------+
| Module                                  | Description                                          |
+=========================================+======================================================+
| ``amps-topic-translator``               | Translates topic names on incoming commands.         |
|                                         |                                                      |
|                                         | This module requires one or more of the following    |
|                                         | options:                                             |
|                                         |                                                      |
|                                         | ``Topic``                                            |
|                                         |                                                      |
|                                         | Specifies the translation to use. This option        |
|                                         | takes the following format:                          |
|                                         | *original* ``:`` *translated*.                       |
|                                         |                                                      |
|                                         | The *original* parameter can be a literal topic      |
|                                         | name or a PCRE regex. Any topic on any command that  |
|                                         | matches that parameter will be converted to the      |
|                                         | translated topic.                                    |
|                                         |                                                      |
|                                         | For example, to convert the topic ``legacy`` to the  |
|                                         | topic ``new``, you would specify the following       |
|                                         | option::                                             |
|                                         |                                                      |
|                                         |     <Options>                                        |
|                                         |       <Topic>legacy:new</Topic>                      |
|                                         |     </Options>                                       |
|                                         |                                                      |
|                                         | To translate any topic beginning with                |
|                                         | ``/orders/northamerica`` to  ``NAorders``, you would |
|                                         | specify the following option::                       |
|                                         |                                                      |
|                                         |     <Options>                                        |
|                                         |       <Topic>^/orders/northamerica:NAorders</Topic>  |
|                                         |     </Options>                                       |
|                                         |                                                      |
+-----------------------------------------+------------------------------------------------------+
| ``amps-conflated-topic-translator``     | Translates an incoming ``subscribe``,                |
|                                         | ``sow_and_subscribe``, ``delta_subscribe``, or       |
|                                         | ``sow_and_delta_subscribe`` command for a specific   |
|                                         | topic name as follows:                               |
|                                         |                                                      |
|                                         | * Translates the topic name on the command to a      |
|                                         |   different topic name.                              |
|                                         |                                                      |
|                                         | * Adds a conflation interval to the command, if      |
|                                         |   there is no conflation interval specified on the   |
|                                         |   incoming command.                                  |
|                                         |                                                      |
|                                         | This module can be useful for removing a conflated   |
|                                         | topic that is infrequently-used, or for which        |
|                                         | subscribers only monitor a small number of           |
|                                         | messages out of the overall topic.                   |
|                                         |                                                      |
|                                         | This module requires one or more of the following    |
|                                         | options:                                             |
|                                         |                                                      |
|                                         | ``Topic``                                            |
|                                         |                                                      |
|                                         | Specifies the translation to use. This option        |
|                                         | takes the following format:                          |
|                                         | *original* ``:`` *translated* ``:`` *interval*       |
|                                         |                                                      |
|                                         | The *interval* specifies the conflation interval to  |
|                                         | apply to the translated commands if one is not       |
|                                         | provided.                                            |
|                                         |                                                      |
|                                         | For example, to convert all subscriptions to the     |
|                                         | topic ``orders-C`` to the topic ``orders``, and      |
|                                         | guarantee that each translated subscription has a    |
|                                         | conflation specified, with a 500 millisecond default |
|                                         | for conflation, you would use the following          |
|                                         | options::                                            |
|                                         |                                                      |
|                                         |     <Options>                                        |
|                                         |       <Topic>orders-C:orders:500ms</Topic>           |
|                                         |     </Options>                                       |
|                                         |                                                      |
|                                         | To convert all subscriptions to the topics           |
|                                         | ``slowUpdates`` and ``verySlowUpdates`` to           |
|                                         | the topic ``updates`` and guarantee that each        |
|                                         | translated subscription has a conflation specified,  |
|                                         | with a 2 second default for conflation, you would    |
|                                         | use the following options::                          |
|                                         |                                                      |
|                                         |     <Options>                                        |
|                                         |       <Topic>slowUpdates:updates:2s</Topic>          |
|                                         |       <Topic>verySlowUpdates:updates:2s</Topic>      |
|                                         |     </Options>                                       |
+-----------------------------------------+------------------------------------------------------+

**Table 18.1:** *Transport Filters*

