Package org.microproxy

Class Http3Options.Builder

java.lang.Object

org.microproxy.Http3Options.Builder

Enclosing class:

Http3Options

public static final class Http3Options.Builder
extends Object

Builds Http3Options.

Method Summary

Modifier and Type	Method	Description
Http3Options.Builder	altSvc(boolean advertise)	Whether a reverse proxy serving HTTP/3 adds Alt-Svc: h3=":<port>" to the responses it sends over TCP (default on), so that clients find its HTTP/3 listener.
Http3Options.Builder	altSvcMaxAge(Duration maxAge)	How long clients may remember the proxy's HTTP/3 advertisement (the ma parameter, default 24 hours).
Http3Options	build()	Creates the configured HTTP/3 options.
Http3Options.Builder	connectionReceiveWindow(long bytes)	QUIC's flow-control window per connection (default 1 MiB), for all its streams together.
Http3Options.Builder	connectUdpIdleTimeout(Duration timeout)	How long a CONNECT-UDP flow lives without a datagram in either direction (default 60 s), after which the proxy closes its socket and ends the client's stream.
Http3Options.Builder	connectUdpInterceptQuic(boolean intercept)	Whether QUIC inside CONNECT-UDP flows is decided on as transparent QUIC is (default false: relayed as any UDP).
Http3Options.Builder	connectUdpMaxFlows(int total, int perConnection)	The CONNECT-UDP flows the proxy relays at once (default 4096), and that one client connection may have open (default 64); each has a UDP socket of its own.
Http3Options.Builder	connectUdpQueue(int datagrams, long bytes)	The datagrams (default 128) and bytes (default 512 KiB) a CONNECT-UDP flow queues in each direction while the other side is not ready for them (a client that does not read its stream, so that the capsules to it wait for flow control, a target socket that does not keep up).
Http3Options.Builder	connectUdpQuicPorts(int... ports)	The target ports of the CONNECT-UDP flows whose QUIC connectUdpInterceptQuic decides on (default 443); none for every port.
Http3Options.Builder	connectUdpReleaseWait(Duration wait)	How long a CONNECT-UDP request that finds the proxy's bound on flows (connectUdpMaxFlows) full waits for a place, while flows that are already ending still hold theirs (default 250 ms; zero refuses at once).
Http3Options.Builder	connectUdpTemplate(String template)	The URI template that CONNECT-UDP requests (MASQUE, RFC 9298) name their target with, on a forward proxy's HTTP/3 listener and, over HTTP/2 and HTTP/1.1, its TCP listener (HttpProxyServerBootstrap.withConnectUdp(boolean)): by default the well-known /.well-known/masque/udp/{target_host}/{target_port}/.
Http3Options.Builder	maxConcurrentStreams(int n)	Request streams a client may have open at once (default 100): QUIC's limit on the bidirectional streams it may open, which the transport enforces and raises as streams end.
Http3Options.Builder	maxFieldSectionSize(long bytes)	The largest field section the proxy accepts, counted as HTTP/3 counts it (names and values plus 32 octets per field), advertised as SETTINGS_MAX_FIELD_SECTION_SIZE.
Http3Options.Builder	maxRapidResets(int n)	Requests a client may cancel (reset) before their response completes, per window (default 100), against the Rapid Reset attack; more is a connection error H3_EXCESSIVE_LOAD.
Http3Options.Builder	maxUnknownFrames(int n)	Frames of unknown and reserved types (which HTTP/3 says to ignore), and empty DATA frames, a peer may send per window, on all its streams together (default 1000); more is a connection error H3_EXCESSIVE_LOAD.
Http3Options.Builder	maxUnknownStreams(int n)	Unidirectional streams of unknown and reserved types (which HTTP/3 says to abandon) a peer may open per window (default 100); more is a connection error H3_EXCESSIVE_LOAD.
Http3Options.Builder	qlogDirectory(Path directory)	Writes a qlog file for each of the proxy's QUIC connections, to clients and to servers, into directory (made if missing): JSON-SEQ (.sqlog) in the qlog main schema's format, named after the connection's original Destination Connection ID and whether the proxy was its server or its client.
Http3Options.Builder	qlogMaxFileBytes(long max)	The largest a qlog file grows (default 64 MiB): past it, the connection's later events are left out.
Http3Options.Builder	qlogMaxFiles(int max)	How many qlog files the directory keeps (default 1000): past it, the oldest the proxy wrote are deleted.
Http3Options.Builder	qpackBlockedStreams(int n)	Streams whose field sections may wait for the peer's QPACK encoder stream at once (default 16), advertised as SETTINGS_QPACK_BLOCKED_STREAMS.
Http3Options.Builder	qpackMaxTableCapacity(long bytes)	The QPACK dynamic table (default 4096 bytes): the most the proxy keeps for a peer's field sections, advertised as SETTINGS_QPACK_MAX_TABLE_CAPACITY, and the most it uses for its own. 0 turns the dynamic table off: field sections are encoded with the static table and literals only.
Http3Options.Builder	quicCongestionControl(Http3Options.QuicCongestionControl control)	The congestion controller of the proxy's QUIC connections, those its HTTP/3 and transparent QUIC listeners accept and those it opens to servers (default CUBIC).
Http3Options.Builder	rateWindow(Duration window)	The window the rate limits below count events in (default 10 s).
Http3Options.Builder	retry(boolean retry)	Whether the HTTP/3 listener answers a client's first packet with a QUIC Retry, so that only clients that can receive at their address cost it a handshake (default off: it costs every client a round trip).
Http3Options.Builder	streamReceiveWindow(long bytes)	QUIC's flow-control window per stream (default 256 KiB): the most a peer sends on a stream before the proxy has read it, request bodies from clients and response bodies from servers alike.
Http3Options.Builder	transparentMaxBufferedBytes(long bytes)	The bytes of datagrams the transparent QUIC listener holds for all its new clients together (default 8 MiB); each one may hold 16 datagrams at most.
Http3Options.Builder	transparentMaxPending(int total, int perSource)	The new clients (half-open QUIC flows: Initials whose ClientHello is being read or decided on) the transparent QUIC listener holds at once (default 1024), and from one IP address (default 32).
Http3Options.Builder	transparentMaxRelayFlows(int total, int perSource)	The QUIC flows the transparent QUIC listener relays at once (default 4096), and for one IP address (default 256); each has a UDP socket to its server.
Http3Options.Builder	transparentPendingTimeout(Duration timeout)	How long the transparent QUIC listener holds a new client's datagrams (default 5 s) for its ClientHello to complete and the proxy to decide on it; a client still pending then is forgotten, its datagrams dropped.
Http3Options.Builder	transparentRelayIdleTimeout(Duration timeout)	How long a QUIC flow that the transparent QUIC listener relays untouched (an ignored host, a client offering no HTTP/3) lives without a datagram in either direction (default 60 s), after which its socket to the server is closed.
Http3Options.Builder	upstreamFailureTimeout(Duration timeout)	How long a server whose QUIC handshake failed or timed out is reached over TCP only (default 5 minutes), before HTTP/3 is tried again.
Http3Options.Builder	upstreamHandshakeTimeout(Duration timeout)	How long a QUIC handshake with a server may take (default 1 s) before the request goes over TCP instead; the server then stays on TCP for the upstreamFailureTimeout.
Http3Options.Builder	upstreamZeroRtt(boolean enabled)	Whether the proxy sends requests to HTTP/3 servers as 0-RTT early data when it resumes a session with them (default on).
Http3Options.Builder	zeroRtt(boolean enabled)	Whether the HTTP/3 listeners (--http3 and the clients the transparent QUIC listener intercepts) accept 0-RTT early data (default off).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

maxConcurrentStreams

public Http3Options.Builder maxConcurrentStreams(int n)

Request streams a client may have open at once (default 100): QUIC's limit on the bidirectional streams it may open, which the transport enforces and raises as streams end. Each runs its own exchange.

Parameters:

n - the maximum streams open at once

Returns:

this builder

streamReceiveWindow

public Http3Options.Builder streamReceiveWindow(long bytes)

QUIC's flow-control window per stream (default 256 KiB): the most a peer sends on a stream before the proxy has read it, request bodies from clients and response bodies from servers alike.

Parameters:

bytes - the stream window, at least 16384 bytes

Returns:

this builder

connectionReceiveWindow

public Http3Options.Builder connectionReceiveWindow(long bytes)

QUIC's flow-control window per connection (default 1 MiB), for all its streams together.

Parameters:

bytes - the connection window, at least 16384 bytes

Returns:

this builder

maxFieldSectionSize

public Http3Options.Builder maxFieldSectionSize(long bytes)

The largest field section the proxy accepts, counted as HTTP/3 counts it (names and values plus 32 octets per field), advertised as SETTINGS_MAX_FIELD_SECTION_SIZE. A larger request is answered 431, a larger response fails its exchange. 0 (the default) derives it from the HTTP/1 limits: withMaxHeaderSize plus withMaxInitialLineLength.

Parameters:

bytes - the limit, or zero to derive it from the HTTP/1 limits

Returns:

this builder

qpackMaxTableCapacity

public Http3Options.Builder qpackMaxTableCapacity(long bytes)

The QPACK dynamic table (default 4096 bytes): the most the proxy keeps for a peer's field sections, advertised as SETTINGS_QPACK_MAX_TABLE_CAPACITY, and the most it uses for its own. 0 turns the dynamic table off: field sections are encoded with the static table and literals only.

Parameters:

bytes - the table capacity, 0 or more

Returns:

this builder

qpackBlockedStreams

public Http3Options.Builder qpackBlockedStreams(int n)

Streams whose field sections may wait for the peer's QPACK encoder stream at once (default 16), advertised as SETTINGS_QPACK_BLOCKED_STREAMS. One more is a connection error QPACK_DECOMPRESSION_FAILED; each waits at most the idle timeout.

Parameters:

n - the limit, 0 or more

Returns:

this builder

rateWindow

public Http3Options.Builder rateWindow(Duration window)

The window the rate limits below count events in (default 10 s).

Parameters:

window - the counting window

Returns:

this builder

maxUnknownFrames

public Http3Options.Builder maxUnknownFrames(int n)

Frames of unknown and reserved types (which HTTP/3 says to ignore), and empty DATA frames, a peer may send per window, on all its streams together (default 1000); more is a connection error H3_EXCESSIVE_LOAD.

Parameters:

n - the maximum per window

Returns:

this builder

maxUnknownStreams

public Http3Options.Builder maxUnknownStreams(int n)

Unidirectional streams of unknown and reserved types (which HTTP/3 says to abandon) a peer may open per window (default 100); more is a connection error H3_EXCESSIVE_LOAD.

Parameters:

n - the maximum per window

Returns:

this builder

maxRapidResets

public Http3Options.Builder maxRapidResets(int n)

Requests a client may cancel (reset) before their response completes, per window (default 100), against the Rapid Reset attack; more is a connection error H3_EXCESSIVE_LOAD.

Parameters:

n - the maximum per window

Returns:

this builder

retry

public Http3Options.Builder retry(boolean retry)

Whether the HTTP/3 listener answers a client's first packet with a QUIC Retry, so that only clients that can receive at their address cost it a handshake (default off: it costs every client a round trip). The transparent QUIC listener sends Retry only to the clients it intercepts: a relayed client's server would refuse the token.

Parameters:

retry - whether to send Retry

Returns:

this builder

zeroRtt

public Http3Options.Builder zeroRtt(boolean enabled)

Whether the HTTP/3 listeners (--http3 and the clients the transparent QUIC listener intercepts) accept 0-RTT early data (default off). The listeners always send session tickets and resume sessions, which saves a client the certificate exchange; with 0-RTT on, a resuming client may also send its first requests before the handshake completes, saving a round trip.

Early data can be replayed: an attacker who captures a client's first flight can send it again (RFC 8446 section 8). The QUIC layer accepts a ticket's early data once, and only while the client's ticket age matches the proxy's, within one process. On top of that the proxy treats a request any part of which arrived as early data as RFC 8470 says: it answers 425 Too Early unless the method is safe to repeat (GET, HEAD or OPTIONS, without a body), and forwards the rest with Early-Data: 1, so the server can answer 425 itself. Filters see FlowContext.isEarlyData() (Starlark ctx.early_data) and may answer 425 to requests they deem unsafe; a client sends them again once its handshake completes.

Parameters:

enabled - whether to accept 0-RTT

Returns:

this builder

upstreamZeroRtt

public Http3Options.Builder upstreamZeroRtt(boolean enabled)

Whether the proxy sends requests to HTTP/3 servers as 0-RTT early data when it resumes a session with them (default on). Only requests safe to repeat go early: GET, HEAD and OPTIONS without a body (RFC 8470 section 2.1); others wait for the handshake. A server that answers 425 Too Early gets the request again after the handshake, unless the request itself arrived as early data, whose client gets the 425. The proxy keeps session tickets per server for as long as it runs.

Parameters:

enabled - whether to send 0-RTT data to servers

Returns:

this builder

upstreamHandshakeTimeout

public Http3Options.Builder upstreamHandshakeTimeout(Duration timeout)

How long a QUIC handshake with a server may take (default 1 s) before the request goes over TCP instead; the server then stays on TCP for the upstreamFailureTimeout.

Parameters:

timeout - the handshake timeout

Returns:

this builder

upstreamFailureTimeout

public Http3Options.Builder upstreamFailureTimeout(Duration timeout)

How long a server whose QUIC handshake failed or timed out is reached over TCP only (default 5 minutes), before HTTP/3 is tried again.

Parameters:

timeout - how long a failure is remembered

Returns:

this builder

altSvc

public Http3Options.Builder altSvc(boolean advertise)

Whether a reverse proxy serving HTTP/3 adds Alt-Svc: h3=":<port>" to the responses it sends over TCP (default on), so that clients find its HTTP/3 listener. A response whose server's own Alt-Svc field is left after the h3 stripping keeps it instead, and proxyToClientResponse filters may remove the field.

Parameters:

advertise - whether to advertise HTTP/3

Returns:

this builder

altSvcMaxAge

public Http3Options.Builder altSvcMaxAge(Duration maxAge)

How long clients may remember the proxy's HTTP/3 advertisement (the ma parameter, default 24 hours).

Parameters:

maxAge - the advertisement's lifetime, in whole seconds

Returns:

this builder

transparentRelayIdleTimeout

public Http3Options.Builder transparentRelayIdleTimeout(Duration timeout)

How long a QUIC flow that the transparent QUIC listener relays untouched (an ignored host, a client offering no HTTP/3) lives without a datagram in either direction (default 60 s), after which its socket to the server is closed. Make it at least the QUIC idle timeout of the clients and servers (often 30 s).

Parameters:

timeout - the idle timeout of a relayed flow

Returns:

this builder

See Also:

• HttpProxyServerBootstrap.withTransparentQuicPort(int)

transparentPendingTimeout

public Http3Options.Builder transparentPendingTimeout(Duration timeout)

How long the transparent QUIC listener holds a new client's datagrams (default 5 s) for its ClientHello to complete and the proxy to decide on it; a client still pending then is forgotten, its datagrams dropped.

Parameters:

timeout - the longest a client may stay pending

Returns:

this builder

transparentMaxPending

public Http3Options.Builder transparentMaxPending(int total,
 int perSource)

The new clients (half-open QUIC flows: Initials whose ClientHello is being read or decided on) the transparent QUIC listener holds at once (default 1024), and from one IP address (default 32). Initials of further new clients are dropped, as a full socket buffer would drop them; clients send them again.

Parameters:

total - the most new clients held at once

perSource - the most new clients of one IP address held at once

Returns:

this builder

transparentMaxRelayFlows

public Http3Options.Builder transparentMaxRelayFlows(int total,
 int perSource)

The QUIC flows the transparent QUIC listener relays at once (default 4096), and for one IP address (default 256); each has a UDP socket to its server. A new flow past either limit is dropped.

Parameters:

total - the most relayed flows at once

perSource - the most relayed flows of one IP address at once

Returns:

this builder

transparentMaxBufferedBytes

public Http3Options.Builder transparentMaxBufferedBytes(long bytes)

The bytes of datagrams the transparent QUIC listener holds for all its new clients together (default 8 MiB); each one may hold 16 datagrams at most. Datagrams past it are dropped.

Parameters:

bytes - the most bytes held, at least 65536

Returns:

this builder

connectUdpTemplate

public Http3Options.Builder connectUdpTemplate(String template)

The URI template that CONNECT-UDP requests (MASQUE, RFC 9298) name their target with, on a forward proxy's HTTP/3 listener and, over HTTP/2 and HTTP/1.1, its TCP listener (HttpProxyServerBootstrap.withConnectUdp(boolean)): by default the well-known /.well-known/masque/udp/{target_host}/{target_port}/. A path, optionally with a query, or an absolute URI whose path and query count, with the variables {target_host} and {target_port} once each.

Parameters:

template - the template

Returns:

this builder

Throws:

IllegalArgumentException - if it lacks one of the variables

connectUdpIdleTimeout

public Http3Options.Builder connectUdpIdleTimeout(Duration timeout)

How long a CONNECT-UDP flow lives without a datagram in either direction (default 60 s), after which the proxy closes its socket and ends the client's stream.

Parameters:

timeout - the idle timeout of a CONNECT-UDP flow

Returns:

this builder

connectUdpMaxFlows

public Http3Options.Builder connectUdpMaxFlows(int total,
 int perConnection)

The CONNECT-UDP flows the proxy relays at once (default 4096), and that one client connection may have open (default 64); each has a UDP socket of its own. A request past either limit is answered 503.

Parameters:

total - the most flows at once

perConnection - the most flows of one client connection at once

Returns:

this builder

connectUdpReleaseWait

public Http3Options.Builder connectUdpReleaseWait(Duration wait)

How long a CONNECT-UDP request that finds the proxy's bound on flows (connectUdpMaxFlows) full waits for a place, while flows that are already ending still hold theirs (default 250 ms; zero refuses at once). A flow's places go back as soon as the proxy reads that its client ended it, so a request that follows the end on the same connection always finds room; a client that ends a flow on one connection and opens one on another may have the new request read first, and this wait covers flows whose end the proxy has seen but not finished. Without such flows a full bound refuses at once.

Parameters:

wait - the longest wait, zero or more

Returns:

this builder

connectUdpQueue

public Http3Options.Builder connectUdpQueue(int datagrams,
 long bytes)

The datagrams (default 128) and bytes (default 512 KiB) a CONNECT-UDP flow queues in each direction while the other side is not ready for them (a client that does not read its stream, so that the capsules to it wait for flow control, a target socket that does not keep up). Datagrams past either bound are dropped, as a network drops what it cannot carry.

Parameters:

datagrams - the most datagrams queued in one direction

bytes - the most bytes queued in one direction, at least 65527 (one datagram)

Returns:

this builder

connectUdpInterceptQuic

public Http3Options.Builder connectUdpInterceptQuic(boolean intercept)

Whether QUIC inside CONNECT-UDP flows is decided on as transparent QUIC is (default false: relayed as any UDP). A flow to one of the QUIC ports whose first datagram from the client is a QUIC Initial has its ClientHello read, then goes through the same rules, with the flow's target as the server: HTTP/3 is served as HTTP/3 (filters and frame hooks see its requests), other protocols through the QUIC hooks, and an ignored or declined host is relayed as before. The ignore and allow host rules then apply to such flows.

Parameters:

intercept - whether to decide on QUIC inside CONNECT-UDP flows

Returns:

this builder

connectUdpQuicPorts

public Http3Options.Builder connectUdpQuicPorts(int... ports)

The target ports of the CONNECT-UDP flows whose QUIC connectUdpInterceptQuic decides on (default 443); none for every port.

Parameters:

ports - the UDP ports, from 1 to 65535

Returns:

this builder

Throws:

IllegalArgumentException - if a port is out of range

quicCongestionControl

public Http3Options.Builder quicCongestionControl(Http3Options.QuicCongestionControl control)

The congestion controller of the proxy's QUIC connections, those its HTTP/3 and transparent QUIC listeners accept and those it opens to servers (default CUBIC). BBR is experimental; it suits paths with a large bandwidth-delay product or random loss.

Parameters:

control - the controller

Returns:

this builder

qlogDirectory

public Http3Options.Builder qlogDirectory(Path directory)

Writes a qlog file for each of the proxy's QUIC connections, to clients and to servers, into directory (made if missing): JSON-SEQ (.sqlog) in the qlog main schema's format, named after the connection's original Destination Connection ID and whether the proxy was its server or its client. Off by default (null); qlog builds an event for every packet, so it is for debugging.

Parameters:

directory - the directory, or null for no qlog

Returns:

this builder

qlogMaxFiles

public Http3Options.Builder qlogMaxFiles(int max)

How many qlog files the directory keeps (default 1000): past it, the oldest the proxy wrote are deleted.

Parameters:

max - the most files

Returns:

this builder

Throws:

IllegalArgumentException - if it is not positive

qlogMaxFileBytes

public Http3Options.Builder qlogMaxFileBytes(long max)

The largest a qlog file grows (default 64 MiB): past it, the connection's later events are left out.

Parameters:

max - the most bytes

Returns:

this builder

Throws:

IllegalArgumentException - if it is not positive

build

public Http3Options build()

Creates the configured HTTP/3 options.

Returns:

the configured HTTP/3 options