Support HTTP request trailers

[jnbdz]

Fixes #5253. Two commits: the server reading request trailers, and the client sending them.

HttpServerRequest has no way to read trailers, while HttpClientResponse exposes trailers() and getTrailer(). The trailers do arrive — Netty parses them — but the server drops them, and the code already marked both spots:

• Http1ServerConnection.onContent: //TODO chunk trailers
• Http2ServerConnectionImpl.onHeadersRead: // Http server request trailer - not implemented yet (in api)

HttpServerRequestImpl.handleTrailers(MultiMap) was already receiving the trailers and discarding them.

Change

HttpServerRequest gains getTrailer(String) and trailers(), declared exactly as on HttpClientResponse (@Nullable on the former, @CacheReturn on the latter). Before the request has ended, and for requests without trailers, trailers() returns an empty map rather than null — matching the client side.

• HTTP/1.1 — Http1ServerConnection passes LastHttpContent.trailingHeaders() down, and Http1ServerRequest writes them into the inbound message queue rather than setting a field directly, so they cannot be observed before the preceding data has been delivered. This mirrors Http1ClientConnection.onEnd(LastHttpContent).
• HTTP/2 (codec) — the trailing HEADERS frame is forwarded via stream.onTrailers(headers) instead of signalling empty trailers, mirroring Http2ClientConnectionImpl.
• HTTP/2 (multiplex), HTTP/3, QUIC — already forwarded trailers correctly; unchanged.
• HttpServerRequestWrapper gains the two delegating overrides.

Setting the trailers uses the same escape-safe merge as HttpClientResponseImpl.handleTrailers: if the caller already obtained the lazily-allocated empty map, it is updated in place instead of replaced.

Tests

Covering all three protocols:

• HTTP/1.1 — Http1xTest.testRequestTrailers / testRequestNoTrailers, driven over a raw socket since the client cannot send trailers.
• HTTP/2 — Http2ServerTest.testRequestTrailers / testRequestNoTrailers, sending a trailing HEADERS frame via the Netty test client. Because Http2MultiplexServerTest extends Http2ServerTest, these run against both the codec and multiplex connection implementations.
• HTTP/3 — Http3ServerTest.testTrailers already sent request trailers but could only note // No API to get client trailers; it now asserts them.

Http1xTest (504) and Http2Test (359) pass. Each new assertion was checked by reverting the corresponding production change: dropping the HTTP/1 plumbing fails Http1xTest.testRequestTrailers, and dropping stream.onTrailers(...) in the HTTP/2 codec fails Http2ServerTest.testRequestTrailers.

Note: five testUpgradeToClearText* / testPriorKnowledge cases in Http2ServerTest fail on my machine with BindException: Address already in use on port 8080, identically on unmodified master — a local port conflict, unrelated to this change.

Second commit — client sending

HttpClientRequest gains trailers() and the four putTrailer overloads, declared exactly as on HttpServerResponse.

Trailers ride on the terminating chunk, so a request carrying them is always sent chunked — Netty silently discards trailing headers under Content-Length framing, which would yield a request that looks correct and arrives without its trailers. HttpClientRequestImpl drops Content-Length, forces Transfer-Encoding, writes the body with end=false and emits the trailers as the terminating write, mirroring HttpServerResponseImpl.

HttpClientStream gains writeHeaders(MultiMap, boolean) — the counterpart of the method HttpServerStream already had. HTTP/2 needs no new wire code (DefaultHttp2Stream already implements it, covering codec and multiplex); HTTP/3 reuses the server adapter; HTTP/1 is the only new wire path. HttpClientConnection gains newHttpTrailers() so the protocol-agnostic request can obtain a suitably backed map.

Because the client can now send trailers, the new tests live in HttpTest and therefore run under Http1xTest, Http2Test and Http3Test: trailers with a body, trailers without a body, and a request with none. Removing the chunked coercion fails testRequestTrailers rather than passing silently.

The raw-socket and raw-Netty tests from the first commit are kept on purpose — they show the server accepts trailers from a non-Vert.x client, which a test driving our own client cannot demonstrate.

Full run across the affected classes: 1200 tests, 0 failures. (Two BindException errors on my machine come from an unrelated process holding port 8080; they reproduce on unmodified master.)

Concurrency and async

Nothing here blocks — no await, executeBlocking, latch or synchronous result access is introduced on either side.

• In HttpClientRequestImpl.doWrite, the trailers reference is captured inside the existing synchronized block, alongside the other values used after it (chunked, writeEnd, writeHead), so it is safely published to whichever thread performs the write.
• The trailers write is composed onto the body write rather than issued independently: the future returned by end() completes only once the trailers are on the wire, and a failed body write short-circuits so trailers are never emitted onto a broken stream.
• The new HTTP/1 writeTrailers goes through the connection's outbound MessageWrite queue like an ordinary body write, so back-pressure behaviour is unchanged, and every path — stream reset, cancel, successful write — completes the promise. (A missed path there would hang a request rather than fail it.)
• Http2UpgradeClientConnection.UpgradingStream.writeHeaders re-dispatches to the event loop when invoked from another thread and still fires SEND_BUFFERED_MESSAGES_EVENT on end, mirroring writeChunk.
• On the server side, trailers travel through the request's inbound message queue rather than being assigned to a field directly, so they cannot be observed ahead of the data that preceded them under pause/resume.

The synchronized (conn) usage follows the existing idiom in these classes: short critical sections with no I/O performed under the lock.

I also have this backported to 4.x if a maintenance backport is wanted.

[vietj]

we need a test for HTTP/2 and HTTP/3 as well

[jnbdz]

Thanks — those are in now; the review landed just before I pushed them.

HTTP/2 — Http2ServerTest.testRequestTrailers / testRequestNoTrailers, sending a trailing HEADERS frame. Since Http2MultiplexServerTest extends Http2ServerTest these run against both the codec and multiplex connection implementations.

HTTP/3 — Http3ServerTest.testTrailers already sent request trailers and carried a // No API to get client trailers comment; it now asserts them and the comment is gone.

A second commit adds the client side (HttpClientRequest.putTrailer), which let me put cross-protocol tests in HttpTest — so testRequestTrailers, testRequestTrailersWithoutBody and testRequestNoTrailers also run under Http1xTest, Http2Test and Http3Test.

The raw-socket and raw-Netty tests are kept deliberately: they show the server accepts trailers from a non-Vert.x client.

Happy to split the client side into its own PR if you would rather review them separately.

[vietj]

Comments

[jnbdz]

@vietj a scope question for a possible follow-up, not for this PR:

With request trailers in, Vert.x carries the trailer fields in every direction, but neither side ever touches the Trailer header (RFC 9110 §6.6.2) that declares which fields will arrive as trailers — putTrailer doesn't add it, and it isn't read on receipt. Today that declaration is left to the application, which on HTTP/1.1 has to set it before the headers are committed, i.e. know the trailer names up front.

Would you want Vert.x to emit Trailer: <names> itself when putTrailer has been called on an HTTP/1.1 response (or request) before the headers are written, and leave an explicitly set Trailer header alone? It is a SHOULD in the RFC and Netty doesn't do it either, so it's equally defensible to keep it application-level — I'd rather know which way you lean before writing anything.