proxy.start_http_listener

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

proxy.start_http_listener { PARAMS }

Configure and start an HTTP service for the proxy server.

Note

This function is only available to the proxy-server executable.

This function should be called only from inside your proxy_init event handler.

The HTTP listener provides access to Prometheus-compatible metrics for monitoring the proxy server, including connection counts, bytes transferred, and active connections.

local kumo = require 'kumo'
local proxy = require 'proxy'

kumo.on('proxy_init', function()
  -- Start the SOCKS5 proxy
  proxy.start_proxy_listener {
    listen = '0.0.0.0:1080',
  }

  -- Start the HTTP listener for metrics
  proxy.start_http_listener {
    listen = '0.0.0.0:8080',
    trusted_hosts = { '127.0.0.1', '::1' },
  }
end)

Parameters

PARAMS accepts the same keys as kumo.start_http_listener.

Available Endpoints

The HTTP listener exposes the following endpoints:

Endpoint	Description
/metrics	Prometheus-compatible metrics in text format
/metrics.json	Metrics in JSON format
/proxy/status	Simple health check endpoint
/api/admin/set_diagnostic_log_filter/v1	Runtime log filter adjustment
/rapidoc	Interactive API documentation
/api-docs/openapi.json	OpenAPI specification

Metrics

The proxy server exposes Prometheus-compatible metrics for monitoring. All metrics are automatically documented via the declare_metric! macro.

The metrics include: - proxy_connections_accepted_total - Total incoming connections accepted by the proxy - proxy_connections_failed_total - Connections that failed during handshake or proxying - proxy_connections_completed_total - Proxy sessions that completed successfully - proxy_active_connections - Current number of active proxy connections - proxy_bytes_client_to_dest_total - Total bytes transferred from client to destination - proxy_bytes_dest_to_client_total - Total bytes transferred from destination to client - proxy_outbound_connections_total - Outbound connections made to destinations - proxy_tls_handshake_failures_total - TLS handshake failures

Access these metrics via the /metrics endpoint in Prometheus text format or /metrics.json for JSON format.

API Documentation

The HTTP listener automatically provides an OpenAPI specification at /api-docs/openapi.json and interactive documentation at /rapidoc.

You can also generate the OpenAPI spec by running:

proxy-server --dump-openapi-spec > proxy-server.openapi.json