amps-python-client 5.3.4.1__zip

amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/transports.rst.txt

@@ -0,0 +1,291 @@
+.. include:: ../macros.inc
+
+.. index:: tcp, tcps, SSL, authenticating users, transports
+
+.. _#ug-transports:
+
+.. _transports:
+
+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: 
+
+.. list-table:: *Transport Filters*
+     :header-rows: 1
+
+     * - 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>
+
+
+