AMPS Connections with AMPS spark CLI

The AMPS spark CLI builds a connection string using the options in the command, then passes that connection string to the underlying AMPS Java client.

Connection strings have a number of elements:

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

• Transport - Set using the -server option in AMPS spark CLI. 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 - Set using the -server option in AMPS spark CLI. 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 - Set using the -proto option in AMPS spark CLI. Defaults to amps if not specified. Sets the format in which AMPS receives commands from the client. This is often omitted, since most installations use the default amps protocol, which sends header information in JSON format. The AMPS spark CLI supports legacy protocols (fix, nvfix, xml) for backward compatibility.

• MessageType - Specifies the message type that this connection uses. This component of the connection string is required unless the transport is configured to accept only a single message type. If the transport is configured to only accept a single message type, this component of the connection string is optional. If omitted, the connection will use the message type specified in the transport.

  Notice that the legacy protocols such as fix, nvfix and xml require a transport to specify a single message type, so use of those protocols does not require or accept a message type in the connection string.

As an example, a set of options to AMPS spark CLI such as:

%> spark ping -server localhost:9007 -type json

Would be interpreted as:

tcp://localhost:9007/amps/json

and 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.

Connection Parameters for AMPS

When specifying a URI for connection to an AMPS server, you may specify a number of transport-specific options using the -uriopts flag.

%> spark ping -server localhost:9007 -type json -uriopts "tcp_nodelay=true&tcp_sndbuf=100000"

The AMPS spark CLI provides the following connect string to the underlying Java client:

tcp://localhost:9007/amps/json?tcp_nodelay=true&tcp_sndbuf=100000

In this example, we have specified the AMPS instance on localhost, port 9007, connecting to a transport that uses the amps protocol and sending JSON messages. We have also set two parameters: tcp_nodelay, a Boolean (true/false) parameter, and tcp_sndbuf, an integer parameter. Multiple parameters may be combined to finely tune settings available on the transport. Normally, you'll want to stick with the defaults on your platform, but there may be some cases where experimentation and fine-tuning will yield higher or more efficient performance.

IPv6 Connections

The AMPS spark CLI (and the underlying AMPS Java client) supports creating connections over both IPv4 and IPv6 protocols if supported by the underlying Operating System.

By default, the AMPS Java client will prefer to resolve host names to IPv4 addresses, but this behavior can be adjusted by supplying the ip_protocol_prefer transport option, described in the table below.

TCP and SSL Transport Options

The following transport options are available for TCP connections:

Option	Description
bind	(IP address) Sets the interface to bind the outgoing socket to. Starting with version 5.3.3.0, both IPv4 and IPv6 addresses are fully supported for use with this parameter.
tcp_connecttimeout	(integer) Sets the connect timeout in milliseconds. This helps enable failover in cases where an attempt to connect to a server is unresponsive without returning a failure.
tcp_rcvbuf	(integer) Sets the socket receive buffer size. This defaults to the system default size. (On Linux, you can find the system default size in /proc/sys/net/core/rmem_default.)
tcp_sndbuf	(integer) Sets the socket send buffer size. This defaults to the system default size. (On Linux, you can find the system default size in /proc/sys/net/core/wmem_default.)
tcp_nodelay	(boolean) Enables or disables the TCP_NODELAY setting on the socket. By default TCP_NODELAY is disabled.
tcp_linger	(integer) Enables and sets the SO_LINGER value for the socket By default, SO_LINGER is enabled with a value of 10, which specifies that the socket will linger for 10 seconds.
tcp_keepalive	(boolean) Enables or disables the SO_KEEPALIVE value for the socket. The default value for this option is true.
ip_protocol_prefer	(string) Influence the IP protocol to prefer during DNS resolution of the host. If a DNS entry of the preferred protocol can not be found, the other non-preferred protocol will then be tried. If this parameter is not set, the default will be to prefer IPv4. If an explicit IPv4 address or IPv6 IP address is provided as the host, the format of the IP address is used to determine the IP protocol used and this setting has no effect. Supported Values: ipv4: Prefer an IPv4 address when resolving the host ipv6: Prefer an IPv6 address when resolving the host This parameter is available starting with version 5.3.3.0.

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.

To request HTTP preflight, add the http_preflight=true option to the connection string. For example:

%> spark ping -server proxy-to-amps-example-com:8020 -type json -uriopts "http_preflight=true"

tcp://proxy-to-amps.example.com:8020/client/amps/json?http_preflight=true

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.

Compress Network Traffic

By default, network traffic between AMPS spark CLI and the AMPS server is not compressed.

Using the AMPS Java client, AMPS spark CLI optionally supports compressing the network connection to and from AMPS. To enable this, add the compression option to the connection string. In this release, the AMPS Java client supports zlib compression to the server.

Notice that compressing and decompressing data performs additional work on both the client and server side to compress and decompress the data. The goal is reducing the bandwidth required for the traffic. If bandwidth is at a premium and the data compresses well, this can produce gains in overall performance. In other situations, the benefit can be negligible or create extra latency.

60East recommends testing with your message data and volumes to determine the effect of compression for your usage.

For example:

%> spark ping -server localhost:9007 -type json -uriopts "compression=zlib"

would produce the connection string:

tcp://amps.example.com:9007/amps/json?compression=zlib

Which will compress traffic to and from AMPS.

AMPS Additional Logon Options

The connection string can also be used to pass logon parameters to AMPS. AMPS supports the following additional logon option:

Option	Description
pretty	Provide formatted representations of binary messages rather than the original message contents.