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 replicate to 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 AMPS command header format, called the protocol
  • The network address, such as IP address and port, that the AMPS server will listen to for incoming connections

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 AMPS Configuration Reference.

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.

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.

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 High Availability and the AMPS Configuration Reference 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  
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>

Table 18.1: Transport filters