HTTP Preflight- Proxy Play: AMPS Unlocked

Imagine you’re at an exclusive club. To get in, you first check with the bouncer (the HTTP preflight request) to make sure you’re allowed in. Only after approval can you step inside and enjoy the party. That’s exactly how HTTP preflight works when connecting TCP clients to AMPS via an HTTP proxy!

With this feature, TCP clients can seamlessly pass through an HTTP proxy—just like WebSockets—while maintaining AMPS’s high-performance messaging capabilities. Whether you’re working with Python, Java, C++, or C#, this feature opens up new possibilities for flexible and efficient integrations.

What is HTTP Preflight?

Think of the HTTP preflight feature as a clever hack that lets TCP clients sneak into AMPS through an HTTP proxy by mimicking a WebSocket handshake. Not only does this open the door for seamless connections, but it also gives you the flexibility to pass custom HTTP headers.

Real-World Use Case

Consider a financial trading firm that relies on the AMPS Java client for secure messaging over TCPS while also using JavaScript-based view servers that connect via WebSockets. Their challenge? Minimizing open ports on their firewall while still supporting multiple AMPS transports. To address this, we introduced routing based on the URI using an Nginx proxy. This is where HTTP preflight becomes crucial. By leveraging HTTP Upgrade requests, we can allow TCP clients to pass through the same proxy used for WebSockets. This means trading infrastructure can maintain its AMPS-based architecture without exposing multiple ports. The proxy handles all routing, ensuring secure and efficient connectivity.

We initially explored using Server Name Indication (SNI) over SSL/TLS to differentiate between transports. However, the Java Virtual Machine’s session caching behavior introduced unpredictable issues, making debugging difficult. By shifting to HTTP preflight, we eliminate this complexity while keeping the connection streamlined and secure.

How It Works: The Handshake

AMPS now supports HTTP Upgrade preflight requests for TCP/TCPS transports. This allows proxies like nginx to recognize these requests and route both WebSocket and TCP/TCPS connections through a single exposed port.

Client sends an HTTP Upgrade request to initiate the connection:

GET /user/can/put/path/here/amps/json HTTP/1.1  
Host: host  
Connection: upgrade  
Upgrade: tcp

AMPS responds with a 101 Switching Protocols message, allowing the client to proceed with a standard TCP handshake:

HTTP/1.1 101 Switching Protocols  
Upgrade: tcp  
Connection: Upgrade

Client then sends its standard AMPS logon request and begins normal message exchange.

AMPS Server Changes

The AMPS TCP transport has been updated to:

Accept an HTTP GET request containing an Upgrade header.
Verify that the upgrade request is for tcp or tcps.
Respond with:

HTTP/1.1 101 Switching Protocols  
Upgrade: tcp  
Connection: Upgrade

Transition the connection to standard TCP/TCPS processing.

No AMPS configuration changes are required to enable http_preflight! Just set up Nginx reverse proxy.

Client-Side Changes

To enable HTTP preflight, clients must:

Set http_preflight=true (default is false).
Modify the client URI to include /amps/<message-type>?http_preflight=true.

Before:

tcp://host:port/amps/json

After (with HTTP Preflight):

tcp://host:port/user/can/put/path/here/amps/json?http_preflight=true

This signals the proxy to treat the connection as an HTTP Upgrade request.

Ready to Try It Yourself?

First: Set up Nginx

- Install Nginx Proxy

sudo dnf install nginx

- Enable and Start the nginx service

sudo systemctl enable --now nginx    // enable: Configures nginx to start automatically at system boot. 
                                     // --now: Starts the nginx service immediately

- Configure nginx as a reverse proxy

sudo vim /etc/nginx/nginx.conf

The first step in configuring Nginx is setting the number of worker processes. This determines how many processes Nginx will use to handle incoming requests. For small applications, one worker process is usually sufficient. However, in production environments, it is recommended to set this to match the number of CPU cores on your server for better performance. You can determine the number of CPU cores using the command: nproc. Then, set worker_processes to that number.

Next, we define how Nginx handles concurrent connections. This is done inside the events block. The worker_connections directive sets the maximum number of simultaneous connections a worker process can handle. If you expect high traffic, consider increasing this number, but ensure your server has enough resources to handle it.

Next, add HTTP requests in the http block. The include mime.types; directive ensures that Nginx sets the correct Content-Type headers based on file extensions. default_type application/octet-stream; is a fallback for unknown file types. sendfile on; allows Nginx to send files efficiently by reading them directly from disk. keepalive_timeout 65; keeps idle connections open for 65 seconds before closing them.

WebSockets require a persistent connection. To properly handle WebSocket upgrades, add a map directive inside the http block. This checks if the Upgrade header is set in an incoming request. If it is, Nginx will upgrade the connection; otherwise, it will close it. This is necessary for WebSocket applications. If your application consists of multiple services running on different ports, you can define upstream blocks within the http block to manage them efficiently. Each upstream block defines a backend server that Nginx will route requests to. This setup makes it easier to scale your application in the future by adding more servers to each upstream group.

Now, we define the main server block within the http block, which tells Nginx how to handle incoming requests. listen 80; makes Nginx listen for requests on port 80 (HTTP). server_name localhost; means the server will respond to requests sent to localhost. Replace localhost with your domain if hosting publicly. Inside the server block, add location blocks to define how different types of requests should be handled. First, add a block that will proxy connections to http://amps_admin to the backend service running on port 8085, as defined in the upstream amps_admin block earlier. Next, add a block that will proxy connections to http://amps_tcp to the TCP port on the server, which we defined in the upstream amps_tcp block earlier. Since this connection may involve WebSockets, we also include necessary headers to support upgrades. Similarly, we define a location block to handle WebSocket connections. This block will proxy requests from /ws/ to the WebSocket server running on the TCP port we specified in amps_ws.

Nginx Configuration Example:

worker_processes 1;

# Event Handling
events {
    worker_connections 1024;
}

# HTTP Configuration
http {
    include            mime.types;
    default_type       application/octet-stream;
    sendfile            on;
    keepalive_timeout   65; 

	# Websocket Upgrade Mapping
    map $http_upgrade $connection_upgrade {
    	default upgrade;
	'' close;
    }

	# Upstream Server Definitions
	upstream amps_admin {
	    server localhost:8085;
	}

	upstream amps_tcp {
	    server localhost:9007;
	}

	upstream amps_ws {
	    server localhost:9008;
	}

	# Server Block (Handles Incoming Requests)
	server {
	    listen 80;
            server_name localhost;
	
	location /admin/ {
		proxy_pass http://amps_admin/;
	}

	location /client/ {
		proxy_pass http://amps_tcp/;
		proxy_http_version 1.1;
		proxy_set_header Host $host;
		proxy_set_header Connection $connection_upgrade;
		proxy_set_header Upgrade $http_upgrade;
	}

	    location /ws/ {
		proxy_pass http://amps_ws/;
		proxy_http_version 1.1;
		proxy_set_header Host $host;V
		proxy_set_header Connection $connection_upgrade;
		proxy_set_header Upgrade $http_upgrade;
	    }
	}
}

Run following commands:

sudo systemctl restart nginx    // To restart nginx

sudo systemctl status nginx     // Check if nginx is running

sudo systemctl stop nginx       // Stop nginx

sudo systemctl start nginx      // Start nginx

Second: Start AMPS Server

./AMPS-develop-Release-Linux/bin/ampServer config.xml

If you need help installing and starting AMPS, check out the Getting Started With AMPS guide for instructions.

Finally: Connect AMPS Clients to the AMPS Server

Install AMPS Python Client:

pip install --user --break-system-packages amps-python-client

Install AMPS JavaScript Client:

npm i amps

Python Client with HTTP Preflight code sample:

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!')

# Publish messages in a loop
try:
    while True:
        client.publish('test', '{"hello":"world"}')
        time.sleep(1)
except KeyboardInterrupt:
    print("\nStopped by user. Closing connection...")
    client.close()
    print("Connection closed.")

What This Code Does:

Uses http_preflight=true in the connection URI.
Establishes a connection via AMPS and an HTTP proxy.
Publishes JSON messages every second.

JavaScript Client code sample:

const { Client } = require('amps')

async function main() {
    const client = new Client('test')
    await client.connect('ws://localhost/ws/amps/json')
    console.log('connected!')

    await client.subscribe(message => console.log(message.data), 'test')
}
main()

What This Code Does:

It connects to the WebSocket server at ws://localhost/ws/amps/json (note: the default port for WebSocket (ws://) is 80 for non-secure connections).
Subscribe to an AMPS topic called test.

Note: If the clients fail to connect after following the above steps, try running the following command:

setsebool -P httpd_can_network_connect 1

This command modifies a security setting in SELinux (Security-Enhanced Linux) to allow the HTTPD (web server) process to make network connections. It also ensures that this setting persists across system reboots.

Bringing It All Together

With HTTP preflight, TCP clients get access to AMPS through an HTTP proxy. This feature:

Minimizes the number of open ports needed.
Enables flexible routing.
Works with existing WebSocket-compatible infrastructure.

So next time you need to connect your TCP clients to AMPS via an HTTP proxy, just flip the swtich on http_preflight—and let the magic happen!