HTTP proxy development

Local setup is a work in progress

The local run steps below are not fully verified. Ask the team if a step fails.

The HTTP proxy has two parts. OpenResty and Lua serve public traffic from local route maps. A Python control daemon validates route changes and copies them to other nodes. Atlas creates the proxy VMs and writes their configuration. Read the service overview before you change a request path.

Find the owner

Change	Read first	Code
Public request path	OpenResty routes	HTTP Lua, TLS Lua
Route API or authorization	Control daemon	API, authentication
Cluster membership or replication	High availability	Cluster
Node configuration or install	Install	Configuration, Atlas setup

Read the component specification for interfaces and ownership. The code map links this service to the rest of Atlas.

Source layout

control/
  proxy_control/
    main.py                 FastAPI map API and startup wiring.
    config.py               Read /etc/atlas/proxy-control.toml.
    apply.py                The proxy-control command.
    auth.py                 JWKS bearer token authentication.
    certificates.py         Validate and install wildcard certificates.
    client.py               Send HTTP requests through the Unix socket.
    cluster.py              Leader election and route replication.
    mappings.py             Read and change route maps.
    server.py               Start the IPv4 and IPv6 daemon listeners.
  tests/                    Unit tests for the control daemon.
  pyproject.toml            Python package and the proxy-control command.

nginx/
  setup.sh                  Install the proxy on Ubuntu.
  nginx.conf                Main OpenResty configuration.
  lua/http/                 HTTP routes, maps, and map storage.
  lua/stream/               TLS SNI routes and the SNI bridge.
  pages/                    HTML error pages.
  systemd/                  OpenResty and daemon systemd units.

tests/
  test_proxy.py             Site route tests.
  test_custom_domain_proxy.py  Custom-domain tests.
  test_build.py             Image and install tests.
  test_latency.py           Route and map size tests.

Make a change

Change the matching file for API, cluster, configuration, authentication, map, or certificate changes:

• main.py, cluster.py, config.py, apply.py, auth.py, mappings.py, or certificates.py

When you add a configuration key, update config.py, the install guide, and atlas/service/core/proxy/configuration.py. Atlas writes the installed configuration.

Change nginx/lua/http/admin.lua when you change map storage or the private OpenResty API.

Change nginx/lua/http/router.lua or nginx/lua/http/plain_router.lua for HTTP routing.

Change nginx/lua/stream for custom-domain TLS routing. Change both HTTP and stream code for custom-domain map changes.

Change nginx/setup.sh for installed files, packages, users, paths, or systemd units. Keep the install tests in sync when setup files move.

Change PYTHON_VERSION in nginx/setup.sh, requires-python in control/pyproject.toml, target-version in ruff.toml, and the CI Python version together.

Run the proxy locally

Run these commands from services/http-proxy/. Create a virtual environment and install the control package with its test dependencies:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --editable 'control[test]'

Start the control daemon with its default configuration:

python -m proxy_control.main

The daemon listens on port 9000. Install OpenResty with Setup before you use the readiness or map endpoints.

Run the tests

Run the control daemon tests from the service root:

python -m pip install --editable 'control[test]'
python -m pytest -q control/tests

Run a focused test for one area:

python -m pytest -q control/tests/test_config.py
python -m pytest -q control/tests/test_auth.py
python -m pytest -q control/tests/test_apply.py
python -m pytest -q control/tests/test_cluster.py

Check a change

bash -n nginx/setup.sh
python3 -m compileall -q control/proxy_control control/tests
git diff --check

Files that the proxy writes

OpenResty writes route maps below /var/lib/nginx. The control daemon writes cluster-state.json in the same directory. Do not edit these files while the services run.

The proxy-control command writes the region file and the wildcard certificate files. Change /etc/atlas/proxy-control.toml and run the command again. Do not edit its output files.