proxyfile

HAProxy

proxyfile render --target haproxy writes haproxy.cfg, a whole HAProxy configuration, from the same proxyfile as Envoy's, and beside it proxyfile.lua, a script the configuration loads (below). It is written for HAProxy 3.2 and 3.4: line 2 names the script, lines 3 to 5 stop an older HAProxy, and scripts/validate-haproxy.sh loads every haproxy.cfg the examples commit, with its script, with haproxy -c on HAProxy 3.2.26 and 3.4.7, the two images scripts/haproxy-images pins, a warning counted as an error. proxyfile check compares both files.

HAProxy's column in Portability says, for each key, whether this version writes it and how, and for a key or a form it refuses, what to write instead. A render refuses such a key where the file writes it, so a file that needs one is never rendered as if the key were not there. A key HAProxy has a directive of its own for is written with that directive, the file's values and HAProxy's defaults for the rest: the sections from Limits and timeouts on name each directive. The auth check says how it asks a check service.

Running the file

The official HAProxy image runs haproxy -f /usr/local/etc/haproxy/haproxy.cfg, so the file goes at that path, mounted or copied into the image, with proxyfile.lua beside it: the configuration reads the script from its own folder (default-path config) and does not load without it. With tls, HAProxy reads the certificate, its key and the clients CA at the paths the tls keys give, and refuses the file when one is missing; the image runs HAProxy as the user haproxy, which must be able to read them. The admin port is bound on 127.0.0.1 alone. Measured on HAProxy 3.2.26 and 3.4.7: each image, given examples/minimal/yaml/haproxy.cfg in /usr/local/etc/haproxy and no command of its own, printed Loading success. and answered requests on the file's port, and haproxy -c refused examples/tls/yaml/haproxy.cfg on HAProxy 3.4.7 with no certificate at its path (cannot open the file '/etc/gateway/tls/certificate.pem').

The versions

HAProxy 3.0.30 stops at the file's version guard, before it reads the script: haproxy -c prints proxyfile writes this file for HAProxy 3.2 and 3.4; this HAProxy is older, so it stops here and exits 1.

The path rules below are HAProxy's normalize-uri actions, which its manual calls an experimental technical preview. The file turns them on with expose-experimental-directives, without which HAProxy 3.2.26 and 3.4.7 refuse it ('normalize-uri' action is experimental, must be allowed via a global 'expose-experimental-directives'). HAProxy's manual says such features "may break during the maintenance cycle", so a maintenance release of 3.2 or 3.4 may change how a path is normalised; the images scripts/haproxy-images pins are the ones this version was checked on.

The script beside the file

proxyfile.lua holds what HAProxy's own configuration cannot write, for HAProxy's Lua 5.4.7, which both images carry, loaded by every thread (lua-load-per-thread). Line 1 is the same header as the configuration's, so proxyfile check fails on a hand edit of either file. Its bytes are the same for every file: what differs from one file to another, each pattern's program, is written in the configuration, so two files rendered into one folder share the script and proxyfile check finds each current.

A request the script did not finish with, headers it did not join, a path it did not escape or a pattern it did not finish matching, is answered 400, so a failed run never reads as no match.

What a pattern route costs

pf_route is an action, which HAProxy runs in steps, letting the other requests of its thread run between them; a sample fetch, which the first form of this file used, runs at once. With 24 pattern routes such as /api/.*[0-9a-f]{20}\.js1 and a path of 14,000 bytes, that fetch held a thread past HAProxy's watchdog, which stopped HAProxy 3.2.26 and 3.4.7 (PANIC! Thread 1 is about to kill the process, exit 134); Envoy 1.40.2 answered in 2.6 ms. Measured on an arm64 Mac, with HAProxy's 12 threads:

The auth check

With auth.ask the file asks your check service about a request before it goes on to the route's service, and passes an asked request on only when the check lets it through. Auth says what the check does and what it is told; this section says how HAProxy asks it and where its answers differ from the Envoy output's. The file asks with pf_auth, an action in proxyfile.lua, which connects to the relay, a TCP listen section at the end of haproxy.cfg that passes the connection on to the check service. For the auth block of Your own service, with listen: 8000 and accounts at 10.0.0.7, proxyfile render --target haproxy writes this call:

http-request lua.pf_auth 'abns@proxyfile-8000-check' '/check' 2000 deny 'cookie' 'x-user-id,x-user-roles' 0 if { var(txn.pf_ask) -m bool }

Its words are the relay's address, the path of ask, timeout in milliseconds, when_unavailable, the send names, the accept names and send_request as 1 or 0; a name that ends in * is a prefix, and - stands for no name. The script reads nothing else of the proxyfile, so its bytes are the same for every file. A request is never sent to the check twice, and an answer is used for its own request alone: each call opens a socket of its own.

Which requests are asked

The check is asked about a request when all of these hold, which the file writes once, as the variable txn.pf_ask:

A request whose path still holds a dot segment with a ; parameter is asked whatever its route, as the Envoy output asks it: the route that refuses such a path is checked too (A route with auth: off). The check comes after the file's refusals of an unknown host, of a request no route takes, of an upgrade other than WebSocket and of an origin the environment does not admit, and before its 400 for a dot segment, as the Envoy output asks after CORS and before the route that answers a dot segment. A request one of those refusals answered is not asked.

What the check is sent

The script sends the check one HTTP/1.1 request, to the path of ask, on a connection of its own that the check closes after its answer. It holds:

A value that holds CR, LF or NUL is answered 400: HAProxy's parser refuses such a request first, and the script checks again.

The RPC question. For each method with an action or reports, the file sets x-gateway-action and x-gateway-reports (the names joined by commas) on a request for that method's path, before the check, and removes both right after it, so a service sees neither. A method with neither gets no line, and a client's own copies of both are removed first.

What the service receives

When the check answers 200 and the script reads the answer whole, the request goes on with each header an accept name covers, set in the order of the check's answer; a name the check sent twice keeps its last value, as in Envoy. The script reads each header back after it sets it: HAProxy drops a header that does not fit in its request buffer without an error, so a request whose accepted header did not fit is answered 403, and the service never receives it without the identity.

A request the accepted headers take past 100 header fields is answered 500 with no body, a gRPC call 200 with grpc-status 2, each with an admitted origin's CORS answer, as Envoy 1.40.2 answers it. The script counts the fields as Envoy counts the request it passes on: each header line the request holds once the accepted headers are set, Host as :authority, with :method, :path and :scheme. By then the file has removed Connection and a client's own copies of the headers it sets, and joined the lines of each header Envoy joins, as Envoy has before it counts. The x-request-id and x-forwarded-proto the file sets count, and with client_address: connection the x-forwarded-for and x-envoy-external-address too. A chunked request's Transfer-Encoding line is not counted, and over HTTP/2 a host field beside :authority is one line, as for Envoy (measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2, with 100 and 101 fields). A te or a transfer-encoding the check's answer holds under an accept name counts as one field each, though the script sets neither, as Envoy sets each and counts it; a host takes the place of :authority and adds none (measured). The script counts only when the check's answer held a header an accept name covers other than keep-alive, as Envoy does: a 200 with none, or with keep-alive alone, is served up to the 100 header lines HAProxy reads, and one with host alone is counted (measured).

The check's answer never sets content-length, transfer-encoding, host, te, connection, upgrade or keep-alive on the request; naming one of the first six in full is refused, and Envoy never sets keep-alive either. HAProxy frames or routes a request by the first six, so a check service can never change how the request it passes on is framed.

The file removes a client's own copies of the accept names, of the two question headers and of x-envoy-auth-failure-mode-allowed before any rule reads them, so a client cannot forge them. With when_unavailable: allow and no answer from the check, the request goes on with x-envoy-auth-failure-mode-allowed: true and none of the accepted headers.

What the client receives when the check refuses

Any status but 200 from the check is a refusal. The client receives the check's status, a 2xx other than 200 as 403, with every header of the answer but content-length, transfer-encoding, connection, keep-alive, upgrade and proxy-connection, and the check's body, with content-type: text/plain when the check sent a body and no type. The Envoy output passes te, trailer and a header the check's Connection names, and so does the file. A refusal to a request from a listed origin carries that origin's CORS answer, Access-Control-Allow-Origin and, when cors.expose_headers is written, Access-Control-Expose-Headers, as the Envoy output's does (measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2).

A request whose content-type is application/grpc alone, or application/grpc followed by +, compared as written, is a gRPC call, and its refusal is answered in gRPC's form, where a plain HTTP 401 reaches a gRPC client as a transport error: 200 with content-type: application/grpc, grpc-status from the check's status (400 gives 13, 401 gives 16, 403 gives 7, 404 gives 12, 429, 502, 503 and 504 give 14, any other gives 2), the check's other headers, and the check's body in grpc-message, percent-encoded: every byte outside printable ASCII and % is written %XX, so a body of no entry: 100% sure é, a line feed and next line reaches the client as no entry: 100%25 sure %C3%A9%0Anext line.

HAProxy writes content-length: 0 on a 304 and on an HTTP/2 gRPC refusal, where Envoy writes none, and the file removes it there; over HTTP/1.1 both write content-length: 0.

How the answer is read

The script passes a request only on a 200 it reads whole as RFC 9112 writes it: a status line of HTTP/1.0 or HTTP/1.1, one space, three digits and then nothing or a space and a reason; header lines of a token name, a colon and a value with no control byte but a tab; at most one Content-Length, digits only and never beside Transfer-Encoding; and a Transfer-Encoding of chunked alone, each chunk size plain hexadecimal on a line that ends in CR LF, where Envoy 1.40.2 reads a bare LF at the end of every other line. It skips 1xx answers before the final one and joins a folded header line to the value before it by one space, where Envoy keeps the spaces and tabs of both lines. It reads each head of the answer, from the status line to the empty line with their line ends, a 1xx head included, and the trailer section, to 81,920 bytes, the most Envoy 1.40.2 reads (measured to the byte). An answer it cannot read that way is not a pass: it is answered 403 under deny, as Envoy answers every such form measured. Under allow it depends on the answer: the six cases below go on with the mark, and the note on auth.when_unavailable below lists the others, which HAProxy answers 403 where Envoy serves the request with the unchecked mark.

A check counts as unanswered, as it does for Envoy 1.40.2, in these six cases:

when_unavailable decides. With allow, the request goes on with the mark. With deny, HAProxy answers an unanswered check as Envoy does: 403, with the body Invalid CORS request when the request carries an Origin, and for a gRPC call 200 with grpc-status 7 and, with an Origin, grpc-message Invalid CORS request.

Every other answer the script cannot read whole is not an unanswered check: a header line, a chunk-size line or a trailer line that breaks off, an answer that RFC 9112 does not write and an answer past the script's size bounds are answered 403 under allow too. The notes on auth.ask and auth.when_unavailable say what Envoy does with each.

The relay

The script's own connect is not bounded by its socket's timeout: to an address that never answered, it took 303 s on HAProxy 3.4.7 and 6.0 s on 3.2.26 against a timeout of 1.5 s. So it connects to the relay, a listen section in mode tcp with a defaults section of its own. For the example above:

# the relay to the check service
defaults
  mode tcp

listen check
  bind abns@proxyfile-8000-check
  timeout connect 2000ms
  timeout client 2000ms
  timeout server 2000ms
  retries 0
  option nolinger
  server accounts1 10.0.0.7:7070

HAProxy opens one connection to the check for each check, and the check closes it after its answer, where Envoy keeps a pool of connections to the check. Held for 120 s at 1,000 and at 2,000 checked requests a second over 50 client connections (one run of each proxy alone, Envoy 1.40.2, HAProxy 3.2.26 and 3.4.7, on an Apple M5 Max with Docker 29.9.3 and 12 CPUs), every request was answered 200, and the check and the service each counted as many requests as were sent, 120,000 and 240,000. The median at 2,000 a second was 0.43 ms on Envoy, 0.61 ms on 3.2.26 and 0.58 ms on 3.4.7, and the 99th percentile 0.80, 1.25 and 1.08 ms.

The deadline and the pass rule

A socket's own timeout counts only the time without data, so a check that sent one byte every 100 ms was read for 10.1 s against a timeout of 1.5 s (measured on HAProxy 3.2.26 and 3.4.7, with the task below switched off). So a task of each thread, started when the script loads, closes every socket whose deadline has passed, and auth.timeout bounds the whole check, as Envoy's does. An answer that ends after the deadline is never used. The task waits on a queue while no check waits (core.queue and its pop_wait, which the Lua API of HAProxy 3.2 and 3.4 both have) and looks every 10 ms while one does. A pass of the task that fails ends alone, with a warning in HAProxy's log, and the task looks again 10 ms later: with its first three passes made to fail, each thread's task still closed a check that answered after 3 s at the timeout of 1.5 s (measured on HAProxy 3.2.26 and 3.4.7).

A runtime error in a Lua action lets HAProxy 3.2.26 and 3.4.7 go on with the next rule, and on 3.4.7 a client that closes its side right after its request aborts the action; either would reach the service unchecked. So the script sets txn.pf_passed only when the request may go on, and the rules right after the action answer every asked request that does not have it with the refusal an unanswered check gets under deny (How the answer is read).

With the check switched off

With auth.enabled: false the file writes no check call, no relay and no question line, and still removes a client's own copies of the accept names, the question headers and x-envoy-auth-failure-mode-allowed. A denying token and a forged x-user-id, x-gateway-action and mark reached the service as 200 with none of the three, and the check was not asked, as through the Envoy output (measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2).

Reloading with checks in flight

A reload, SIGUSR2 to HAProxy's master, while checks are in flight loses none and answers none for another request. On HAProxy 3.2.26 and 3.4.7 (one run each, on an Apple M5 Max with Docker 29.9.3 and 12 CPUs) 2,400 checked requests were sent over 60 s on 20 connections, each to its own path, to a check that answered allow after 500 ms. The load was 40 requests a second, which is all that 20 connections carry against a check that answers after 500 ms, so about 20 checks were in flight at each reload. The master was reloaded at 10, 20 and 30 s. Every request was answered 200, the check counted 2,400 checks and the service 2,400 requests, and the x-forwarded-uri the check had been told was the request's own path in all 2,400. Each of the three reloads on each version printed Loading success., and each former worker that the log reaches exited with code 0 after relaying 400 checks (the log of 3.4.7 that was kept ends before the third former worker's exit line).

Where HAProxy answers the check otherwise than the Envoy output

Each difference below is declared on HAProxy's row of its key in Portability, and one alone is on the list of ways HAProxy is less strict: under forwarded the check is told an x-forwarded-proto that is neither http nor https as it arrived, where the Envoy output tells it the connection's scheme, so a check that decides by the scheme it is told reads the word of the client or of the proxy in front. In every case measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2, the service received a request the check was asked about only after the check let it through; each case counted the requests the service and the check received.

A client that sends its request and closes its own side never gets the service's answer, on Envoy or on HAProxy. This is not declared on a key: every file holds option abortonclose, with which HAProxy answers such a client 400 or 403, or nothing, where Envoy only closes. A request the check is asked about reaches no service, and a request it is not asked about may still reach the service, as through Envoy (measured with and without the check on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2). It is not on the list of ways HAProxy is less strict either.

What the check costs

A checked request costs more on HAProxy than on Envoy, which has the check as a filter in the proxy. These figures were measured on an Apple M5 Max (arm64) with Docker 29.9.3 (12 CPUs, 34 GB), on Envoy 1.40.2 (envoyproxy/envoy:distroless-v1.40.2), HAProxy 3.2.26 and HAProxy 3.4.7 (haproxy:3.2.26 and haproxy:3.4.7). One file, with one check service, when_unavailable: deny and only_with_header, was rendered for Envoy and for HAProxy. The check and the service were one throwaway Go stub each, the load came from a container on CPUs 8 to 11, and the proxies were not pinned. "Alone" is 2,000 requests over one connection and "under load" is 20,000 over 50. CPU is the proxy container's own, for each request, from Docker's API.

Each range of the first table is four runs, and each other range two where it does not say. A run started only while no other container used more than 5% of a CPU and no process on the host more than 40%, and was run again when it ended busy; a round taken while the machine was busy was slower for every proxy, Envoy included, and is left out. A few runs give a range and no more, and the figures move with what the machine is doing, so measure your own file and your own check before you rely on them. A machine with fewer CPUs was not measured.

Envoy 1.40.2 HAProxy 3.2.26 HAProxy 3.4.7
alone, checked, median 0.24 to 0.37 ms 0.37 to 0.60 ms 0.37 to 0.55 ms
alone, checked, 99th percentile 0.61 to 0.73 ms 0.69 to 1.15 ms 0.68 to 0.94 ms
alone, CPU a checked request (unchecked in brackets) 108 to 170 µs (65 to 106) 366 to 578 µs (93 to 171) 365 to 526 µs (101 to 149)
under load, checked, requests a second 24,260 to 29,884 10,908 to 18,920 12,035 to 18,603
under load, checked, median 1.44 to 1.82 ms 2.38 to 4.12 ms 2.40 to 3.81 ms
under load, checked, 99th percentile 4.39 to 5.51 ms 6.45 to 11.47 ms 6.95 to 9.73 ms
under load, CPU a checked request 107 to 132 µs 235 to 395 µs 236 to 383 µs
the check service's CPU a check, under load 49 to 62 µs 77 to 127 µs 79 to 122 µs
memory over 20,000 checked requests, at most +4.2 to +4.7 MiB +3.1 to +8.4 MiB +3.3 to +7.9 MiB

Where HAProxy is slower. Under load HAProxy served fewer checked requests a second than Envoy in every run: its best run, 18,920, is below Envoy's worst, 24,260. A checked request had a higher median latency and cost more CPU: a median of 2.38 to 4.12 ms under load against Envoy's 1.44 to 1.82 ms, and 235 to 395 µs of CPU against 107 to 132 µs. Alone, the median is 0.37 to 0.60 ms against 0.24 to 0.37 ms. The check service itself spent more CPU on each check behind HAProxy, 77 to 127 µs against 49 to 62 µs. HAProxy opens a connection for each check, and Envoy keeps a pool.

Connections and ports (20,000 checked requests over 50 client connections; the open and TIME_WAIT counts are one run, the source ports three). Envoy opened 50 connections to the check, the check saw 50 source ports for the 20,000 checks, and the 50 connections were still open right after and 65 s later, with none in TIME_WAIT. HAProxy used 11,249 to 11,330 distinct source ports on 3.2.26 and 11,214 to 11,316 on 3.4.7, none was left on HAProxy's side (option nolinger resets it), and 11,124 (3.2.26) and 10,990 (3.4.7) were in TIME_WAIT on the check's side right after, none 65 s later.

A check that misbehaves (two runs each, each proxy restarted before each kind; while the flood ran, 300 unchecked requests on one connection measured whether other requests were held). Every flood request was answered 403 and every unchecked request meanwhile 200, and no proxy exited or restarted. Each cell gives the median time of the flood's answers, or for the last two rows their rate; the 99th percentile of the unchecked requests meanwhile; and the memory the proxy gained:

The check Envoy 1.40.2 HAProxy 3.2.26 HAProxy 3.4.7
answers after 3 s, 4,000 requests over 1,000 connections 1.50 s; 0.65 to 0.68 ms; +70 to +71 MiB 1.50 s; 0.59 to 0.69 ms; +51 to +53 MiB 1.50 s; 0.58 to 0.83 ms; +51 to +53 MiB
never answers, 2,000 over 1,000 1.50 to 1.51 s; 0.55 to 0.76 ms; +70 to +72 MiB 1.50 to 1.51 s; 0.61 to 0.70 ms; +45 to +46 MiB 1.50 to 1.51 s; 0.64 to 0.65 ms; +46 to +50 MiB
closes at once, 20,000 over 50 26,801 to 30,044 a second; 0.65 to 0.71 ms; +5.2 to +5.7 MiB 20,604 to 21,822 a second; 0.98 to 2.07 ms; +9.6 to +9.8 MiB 22,849 to 23,052 a second; 0.66 to 0.68 ms; +10.3 to +10.8 MiB
answers 200 and sends without end, 1,000 over 50 366 to 383 a second; 24.24 to 31.28 ms; +1,081 to +1,129 MiB 3,302 to 3,451 a second; 0.86 to 1.04 ms; +20.1 to +25.4 MiB 3,448 to 3,958 a second; 0.59 to 0.76 ms; +17.9 to +21.5 MiB

The other rounds gave the same statuses and the same 1.50 to 1.51 s medians, and their rates and memory moved with the machine: over three runs, one of which ended with a busy container, Envoy's rate under the endless 200 ranged from 277 to 565 a second and its memory from +1,100 to +1,217 MiB.

Where HAProxy holds less. After the last flood, the endless 200, both HAProxy versions were at 0% of a CPU from the first half second to the end of the 10 s they were watched, and held 92 MiB (3.2.26) and 101 MiB (3.4.7), flat. Envoy was at 0 to 2% and kept 775 to 790 MiB (701 to 771 MiB in earlier rounds). Idle, with no request for 10 s, Envoy used 0.5 to 0.6% of one CPU and HAProxy 0.0% on both versions, with the check and without it. HAProxy holds more memory idle (two runs): Envoy 22.4 to 23.2 MiB; 3.2.26 80.4 to 81.6 MiB with the check and 81.0 to 83.1 MiB without it; 3.4.7 88.5 to 89.6 MiB with it and 91.2 MiB without it.

The path a route is matched on

The file normalises the path before any rule reads it, as the Envoy output does: the script escapes what Envoy escapes, %2F, %5C and a backslash are read as /, an escaped letter, digit, -, ., _ or ~ is decoded, dot segments are resolved and then repeated slashes merged, so a .. removes an empty segment before it, as through Envoy (/catalog//../products/1 is /catalog/products/1), and the route and the service read that path. Every escape it does not decode reaches the service as written, in the case of its hex digits, and so does an invalid one such as %zz; %00 in a path is answered 400, as by Envoy. A path that still holds a dot segment with a ; parameter, the ; written or escaped once, is answered 400 once its route, its upgrade and its origin are checked, as by Envoy, whose file refuses it by a route of its own (below). Measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2; two differences stay, each named on HAProxy's row of it in Portability:

The request line and the headers

Before any other rule the file answers what Envoy refuses and HAProxy's own parsers pass: every HTTP/1 version but 1.1 with 426, from HTTP/0.0 to HTTP/9.9, and with 400 a method Envoy's HTTP/1 parser does not know (a known one in another letter case too), a QUERY with no Content-Type or with none but empty lines, over HTTP/1.1 and HTTP/2, which Envoy 1.40.2 answers 400 before it picks a route and so before the 404 of an unknown host, the origin check and the auth check, and over HTTP/2 a request past Envoy's 100 header fields. A QUERY with a Content-Type is served, and over HTTP/2 so is query in another letter case, as by Envoy. It removes the headers Envoy removes: Keep-Alive, Proxy-Connection, X-Forwarded-Client-Cert, the 16 x-envoy- headers that steer an Envoy, Connection but a WebSocket upgrade's, and a request's trailers. From a service's answer it removes Keep-Alive, which HAProxy would pass on to an HTTP/1.1 client and Envoy does not. It sends TE: trailers in any letter case on when Connection names te, as Envoy does. HAProxy counts the request line among its 101 header lines, so 100 header lines are served and 101 refused, as by Envoy.

A header value that holds a byte from 0x01 to 0x08, 0x0B, 0x0C, 0x0E to 0x1F or 0x7F is refused before any other rule, as Envoy refuses it: with 400 over HTTP/1.1, and by resetting the stream over HTTP/2, where Envoy closes the connection. HAProxy's own parser refuses 0x00, a line feed and a carriage return in a header or a trailer value, with 400 over HTTP/1.1 and a reset stream over HTTP/2. No fetch reads a request trailer, so a trailer value that holds a control byte is served, an entry of the list below.

The file removes the headers remove_from_clients names, and the names auth.accept lists, from every request before any other rule but that refusal. A prefix leaves Host and Transfer-Encoding, and Transfer-Encoding written in full is left, as Envoy leaves them; what HAProxy cannot remove as Envoy does is refused at render (the differences of the auth check).

HAProxy answers Expect: 100-continue itself, at once, as Envoy does, and passes the header to no service: for a request with a body it sends 100 Continue before it routes the request or asks the check, and lets the request go on at the body's first byte (http-request wait-for-body ... at-least 1), so an upload takes the time and memory it takes without the header (measured on Envoy 1.40.2 beside HAProxy 3.2.26 and 3.4.7, with an upload of 128 MiB).

Measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2, the differences below refuse a request Envoy serves or answer one it refuses with another status. Each is named on HAProxy's row of the request line in Portability. The ones that serve what Envoy refuses, or send a service what Envoy would not, are in the next section.

Where HAProxy is less strict than the Envoy output

These differences are not stricter than the Envoy output: in each, HAProxy serves a request the Envoy output refuses or ends, or sends a service what the Envoy output would not. HAProxy's parsers decide each but the last before any rule of the file reads the request, its timeout counts the time without data, and no fetch reads a request trailer, which option http-drop-request-trailers removes before the service, so the file cannot close them. A header value that holds a control byte is not among them: the file refuses it with a rule, as Envoy does, and the entry on a trailer's value is the one that stays. The last is the file's own: under client_address: forwarded it keeps the X-Forwarded-Proto a request arrived with, as the Envoy output keeps it for the service, and tells the check that header. proxyfile render --target haproxy counts them on standard error after it writes the files, and HAProxy's column in Portability names each on its row. Measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2:

What a file holds to load

HAProxy reads at most 65 words on a line of its file: it refused a line of 66 with too many words, truncating after word 64 (measured on HAProxy 3.2.26 and 3.4.7). The file writes each list of the proxyfile one value a line, as acl lines of one name, which HAProxy joins with or: an environment's hosts, origins, patterns and its own hosts' origins, the rpc entry's paths, and one rule per environment where an environment's lists are read. Each value of an acl line comes after --, the end of the line's flags, so a host the reader admits that starts with - is a host: without it HAProxy 3.4.7 read -f as a flag that names a pattern file and refused the file, and read -i and -n as flags, which left the line no host to match. A file of 600 prefix routes, 50 pattern routes and an environment of 100 hosts, 100 origins and 100 patterns loaded on both and routed a request to its 600th route and its 50th pattern. Generate ends with a scan of every line, so a line of more words is a bug proxyfile reports, never a file HAProxy refuses.

HAProxy read a word of 5,000,000 bytes on both, so no value is refused for its length but one written into a regular expression, which PCRE2 compiles to a size it limits: HAProxy loaded an expression of 32700 letters and refused one of 32800. A host and a pattern of an environment, and the prefix or path of a route with a rewrite, are written into one, and render refuses each, by its key, whose expression is longer than 16384 bytes: a letter takes two bytes compiled, the most of any character those expressions hold. A route's pattern is written as its program, pf_route's argument, and render refuses one whose program is longer than 65,536 bytes: HAProxy loaded an argument of 200,000 bytes, and Envoy 1.40.2 refuses an RE2 program of more than 100 instructions, a pattern far shorter.

A host written with a dot at its start or its end, such as .dot.example.com or dot.example.com., is compared with the Host header as written, as Envoy compares it. A service address with an IPv6 zone is refused (HAProxy's row of services.<service name>.address in Portability).

The browser origins an environment admits

Every file checks the browser origin once a route is picked, as the Envoy output does, with or without cors and lists of origins: a request or a preflight whose Origin an environment neither lists, covers with a pattern nor serves as one of its own hosts is answered 403 with the body Invalid CORS request; an origin on one of the environment's own hosts is admitted with no Access-Control-* header; and every answer carries Vary: Origin. Measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2 with examples/minimal and examples/grpc, and with lists of origins and patterns over HTTP/1.1 and HTTP/2:

With allow_headers: "*", a preflight that asks for no headers gets no Access-Control-Allow-Headers, where Envoy sends the header empty: the difference HAProxy's row of cors.allow_headers names.

An origin an environment admits but that is too long for the file to echo is answered 403, before the check and the service (the differences of the auth check).

TLS

The listener takes TLS 1.2 and 1.3, of TLS 1.2 the ECDHE suites with AES-GCM or ChaCha20 alone, and the key exchange groups X25519MLKEM768, X25519 and P-256 alone, as Envoy 1.40.2 does (ssl-default-bind-ciphers and ssl-default-bind-curves; scanned with openssl s_client one version, suite and group at a time), and answers ALPN h2 and http/1.1. A server name that matches no host, in capitals, with a trailing dot, or no server name, is served with the one certificate; with tls.clients, a Host that names another environment than the server name is served; and plain HTTP to the TLS port has its connection closed, each as by Envoy. With tls.clients, every client certificate Envoy refuses is refused in the handshake: none, one another CA of the same name signed, an expired one, one not valid yet, a self-signed one, one for servers only, and one under an intermediate sent without it. Measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2; two differences stay, named on HAProxy's rows of tls and tls.clients.ca:

The client's address

With client_address: connection the file takes each client for one it faces, as the Envoy output does: the service receives the client's X-Forwarded-For with the peer's address added on the same line, as 1.1.1.1,10.0.0.5, or the peer's address alone when the client sent none or an empty one; x-envoy-external-address, x-forwarded-proto and x-request-id are the file's own; and the headers only a proxy in front may send, x-envoy-decorator-operation, x-envoy-downstream-service-cluster, x-envoy-downstream-service-node, x-envoy-original-host and x-envoy-original-path, are removed. With forwarded those pass, and the client's X-Forwarded-For, X-Forwarded-Proto and request id are kept, each joined into one line when sent on two. A header spelled with underscores, such as x_forwarded_proto, is another header to both proxies and reaches the service as sent. Measured on HAProxy 3.2.26 and 3.4.7 beside Envoy 1.40.2 over HTTP/1.1 and HTTP/2.

Under forwarded, a request is answered 404 when its X-Forwarded-Proto is empty, comes as two empty lines or, over HTTP/1.1, is spaces alone, before the file reads the request's origin, preflight, dot segment or upgrade, as Envoy does. HAProxy's HTTP/2 decoder drops the spaces of a value, so over HTTP/2 spaces alone are answered 404 too, where Envoy serves them. A client's own X-Request-Id that is too long for the room HAProxy keeps for the lines it adds to an answer is answered 400 before the check and the service (the differences of the auth check).

Limits and timeouts

Services found by name

Balance and hash

Each backend of a service takes HAProxy's own balance, and hash-type stays at HAProxy's default, map-based:

The file writes HAProxy's own Which backend takes a request
no balance, or round_robin no line: roundrobin, HAProxy's default the backends in turn
least_requests balance leastconn the one with the fewest connections, one a request here
random balance random(1) one drawn at random, one draw
hash: {header: <name>} balance hdr(<name>) the one the header's value hashes to; without the header, or with it empty, the backends in turn
hash: {client: true} balance source under client_address: connection, balance hash req.hdr_ip(x-forwarded-for,-1) under forwarded the one the client's address hashes to, the last X-Forwarded-For address under forwarded; with no such address, the backends in turn

The check relay of the service auth.ask names takes leastconn and random(1) as its backends do, and goes round robin for a hash: it is a TCP section whose one client is HAProxy itself.

Health checks

Retries

Rate limits

The request log

What HAProxy writes with no key

Each of these is in every file the HAProxy generator writes. Each was measured on HAProxy 3.2.26 and 3.4.7, and Envoy's answers on Envoy 1.40.2, unless it says otherwise.