Connection Strings for AMPS

The AMPS clients use connection strings to determine the server, port, transport, and protocol to use to connect to AMPS. When the connection point in AMPS accepts multiple message types, the connection string also specifies the precise message type to use for this connection.

Connection strings have a number of elements:

As shown in the figure above, connection strings have the following elements:

• Transport - Defines the network used to send and receive messages from AMPS. In this case, the transport is tcp. For connections to transports that use the Secure Sockets Layer (SSL), use tcps. For connections to AMPS over a Unix domain socket, use unix.

• Host Address - Defines the destination on the network where the AMPS instance receives messages. The format of the address is dependent on the transport. For tcp and tcps, the address consists of a host name and port number. In this case, the host address is localhost:9007. For unix domain sockets, a value for hostname and port must be provided to form a valid URI, but the content of the hostname and port are ignored, and the file name provided in the path parameter is used instead (by convention, many connection strings use localhost:0 to indicate that this is a local connection that does not use TCP/IP).

• Protocol - Sets the format in which AMPS receives commands from the client. Most code uses the default amps protocol, which sends header information in JSON format. AMPS supports the ability to develop custom protocols as extension modules, and AMPS also supports legacy protocols for backward compatibility.

• MessageType - Specifies the message type that this connection uses. This component of the connection string is required if the protocol accepts multiple message types and the transport is configured to accept multiple message types. If the protocol does not accept multiple message types, this component of the connection string is optional, and defaults to the message type specified in the transport.

  Legacy protocols such as fix, nvfix and xml only accept a single message type, and therefore do not require or accept a message type in the connection string.

As an example, a connection string such as:

tcp://localhost:9007/amps/json

would work for programs connecting from the local host to a Transport configured as follows:

<AMPSConfig>
    ...

    <!-- This transport accepts any known message type for the instance: the
         client must specify the message type. -->
    <Transport>
        <Name>any-tcp</Name>
        <Type>tcp</Type>
        <InetAddr>9007</InetAddr>
        <Protocol>amps</Protocol>
    </Transport>

    ...
</AMPSConfig>

See the Configuring Transports section in the AMPS User Guide for more information on configuring transports.

Using HTTP Preflight for Connection Upgrades

Some users need to minimize the number of externally accessible ports while still allowing multiple AMPS transports to be used in environments with strict firewall policies for security reasons.

To address this, AMPS supports an HTTP Preflight mechanism that enables TCP clients to share the same external port used for WebSockets. Instead of requiring a dedicated external TCP port, clients can establish a connection over an existing HTTP endpoint. This reduces the number of open network ports while maintaining full TCP/TCPS functionality.

This feature works by leveraging HTTP Upgrade requests, similar to WebSockets, allowing clients to connect via an initial HTTP request before transitioning to a full TCP/TCPS session. Additionally, the HTTP preflight mechanism enables custom HTTP headers to be included in the initial handshake, making it easier to integrate with reverse proxies.

Sample code snippet:

import AMPS
import time

# Create an AMPS client instance
client = AMPS.Client('test')

# Connect using HTTP preflight
client.connect('tcp://localhost:80/client/amps/json?http_preflight=true')

# Log on to AMPS
client.logon()

print('Connected!')

try:
    while True:
        client.publish('test', '{"hello":"world"}')
        time.sleep(1)
except KeyboardInterrupt:
    print("\nStopped by user. Closing connection...")
    client.close()  # Gracefully close the connection
    print("\nConnection closed.")

To learn more about HTTP Preflight, including how to enable it and configure an NGINX proxy, refer to the HTTP Preflight section in the AMPS User Guide and the HTTP Preflight- Proxy Play: AMPS Unlocked blog.