All Classes and Interfaces
Class
Description
Decides which finished exchanges and flows an access log writes, with the semantics of Envoy's
access-log filters:
AccessLogFilter.statusCode(org.microproxy.extras.AccessLogFilter.Comparison, int), AccessLogFilter.duration(org.microproxy.extras.AccessLogFilter.Comparison, long), AccessLogFilter.notHealthCheck(), AccessLogFilter.responseFlag(org.microproxy.ResponseFlag...), AccessLogFilter.header(java.lang.String), AccessLogFilter.runtime(double) sampling, and the AccessLogFilter.allOf(org.microproxy.extras.AccessLogFilter...) and AccessLogFilter.anyOf(org.microproxy.extras.AccessLogFilter...) combinators.An access-log line format, compatible with Envoy's access-log command operators: a format string
such as
[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"
%RESPONSE_CODE% %RESPONSE_FLAGS%, or a JSON dictionary whose values are format strings.Where an
ActivityLogger writes its lines: a file it appends to, or standard output.State of the QUIC ACK frequency extension, as quinn implements it: the
max_ack_delay the
peer uses (its transport parameter, or what we last asked for in an ACK_FREQUENCY frame once it
is acknowledged) and the one we use (ours, or what the peer asked for).An
ActivityTracker that writes one access-log line per finished exchange
or flow (ActivityTracker.flowEnded(org.microproxy.FlowRecord)), in an AccessLogFormat: one of
the LogFormat presets, or an Envoy-compatible format string or JSON dictionary.Builds an
ActivityLogger.Observes proxy activity, e.g. for metrics or access logs.
An
ActivityTracker that ignores everything; extend it and override what you need.Removes the request headers that let a server answer
304 Not Modified (
If-None-Match and If-Modified-Since), as mitmproxy's anticache, so that clients
get whole responses, which other addons and recorders can then see.Reassembles STREAM or CRYPTO frame data that arrives out of order, duplicated or overlapping,
into the stream's bytes (RFC 9000 section 2.2).
What a
ProxyAuthenticator decided about a request.The client may use the proxy.
The client may not use the proxy.
A BBR congestion controller, experimental as in quinn: it models the path's bottleneck bandwidth
and minimum RTT instead of reacting to loss, aiming at less buffer bloat and better throughput on
paths with a high bandwidth-delay product. quinn's port, which this follows, is based on a BBRv1
sender (
bbr_sender.cc) and draft-cardwell-iccrg-bbr-congestion-control.BBR's modes.
Configuration of the
Bbr controller.Blocks requests, as mitmproxy's
block_list: the first rule whose filter matches answers
the request with an empty response of its status, without contacting the server.Builds
BlockList.One rule: requests the filter matches get an empty response with
status, or none.A
TokenLog of bounded memory.A stored response: status, header fields and body as received, the request header values its
Vary named, and when it was requested and received (for the age calculation of RFC 9111
section 4.2.3).Where
HttpCache keeps responses.A certificate authority that issues server certificates on the fly.
A
MitmManager that impersonates servers with certificates issued on demand by a CertificateAuthority.Builds and signs X.509 v3 certificates with nothing but the JDK, which has no public
certificate-generation API.
A certificate chain, end-entity certificate first, and the private key for that certificate:
what a server, or a client asked for a certificate, presents and signs with.
An upstream proxy that requests are forwarded through.
Base
ChainedProxy implementation.Chooses upstream proxies for each request.
The protocol spoken to an upstream (chained) proxy.
A run of received stream or CRYPTO data and its offset in the stream.
A read in progress on one stream, from
StreamsState.read(io.github.mahmoudimus.quic.connection.StreamId, boolean, io.github.mahmoudimus.quic.connection.Retransmits).The TLS 1.3 cipher suites QUIC can use (RFC 9001 section 5.3), with what packet protection needs
to know about each: its HKDF hash, AEAD and key length.
Whether a server asks clients for a certificate (RFC 8446 section 4.3.2).
How a client connects: its TLS configuration (trust, server name, ALPN, 0-RTT), the transport
settings, the QUIC version and the
SessionCache that keeps session tickets and NEW_TOKEN
tokens between connections.Builds a
ClientConfig.What the proxy knows about a client: its address and, once authenticated, its user name.
A client's TLS
ClientHello, the first message of a handshake, as the proxy read it before
deciding whether to intercept a connection: after a CONNECT is accepted, and first thing
on a connection to a transparent listener.What a server's certificate and ALPN selectors see of a ClientHello.
Sends recorded requests again, as mitmproxy's
client_replay: each goes to the proxy's own
listener as an ordinary client request, so every filter, addon, script, cache and recorder of the
proxy applies to it, and the proxy reaches the server (over TLS for https:// URLs).Configures a
ClientReplay.What a replay did.
A bounded, in-memory
ClientSessionStore: up to a number of servers, each with up to
8 tickets.Where a client keeps session tickets between connections, by server.
Limits how many exchanges run at once per key: per client address by default, or per user,
per target host, or anything else a key function derives from the
request and its client connection.
Configures a
ConcurrencyLimiter.One key's state.
Called for every request over the limit, refused or (in shadow mode) let through.
Makes the answer to a refused request;
null sends the default 429.The limiter's state at one moment.
One QUIC connection (RFC 9000, 9001, 9002) as a sans-I/O state machine, after quinn-proto's
Connection.Why a connection ended.
What ended a connection.
What a
Connection tells its application, through Connection.pollEvent().The handshake completed: streams and datagrams can flow.
The connection ended; this is the last event.
One or more DATAGRAM frames arrived; read them with
Connection.receiveDatagram().The handshake is confirmed (RFC 9001 section 4.1.2).
The handshake has progressed far enough that the ALPN protocol and, on a server, the client's
server name are known.
A client's probe of a new path got no PATH_RESPONSE in time: the connection stays on its
path.
The path packets are sent on changed: the server followed the client to a new address (and
validates it), went back to the previous path after a failed validation, or the client
switched to a path it probed (
Connection.probePath(long, java.net.InetSocketAddress), or the server's preferred
address).Something happened on a stream.
A QUIC connection ID (RFC 9000 section 5.1): 0 to 20 opaque bytes with value semantics.
Generates the connection IDs an endpoint issues.
Turns a message body into readable text: protobuf as YAML with field numbers, gRPC message by
message, msgpack, form data, GraphQL, and so on.
What a view knows about a body besides its bytes.
A set of
ContentViews, and the choice among them.A body rendered by a view.
A congestion controller (RFC 9002 section 7): decides how many ack-eliciting bytes may be in
flight.
Builds congestion controllers, one per path.
Congestion controller metrics.
A count that only goes up, such as
downstream_rq_total.The CUBIC congestion controller (RFC 9438), counting the window in bytes: slow start, then the
cubic window function
W_cubic(t) = C * (t - K)^3 + W_max with the Reno-friendly
estimate W_est, fast convergence, and a multiplicative decrease of beta_cubic =
0.7.Configuration of the
Cubic controller.Data that a decoder or
ContentView cannot make sense of: malformed protobuf, a
truncated gRPC frame, an unknown compression, invalid msgpack, JSON or multipart data.A sliding-window detector of duplicate packet numbers, in the style of RFC 4303: a 128-bit
field, one bit per packet number below the highest authenticated one.
A complete request with its body.
A complete response with its body.
Resolves host names with
InetAddress.getByName(java.lang.String).A piece of message body.
Mutable
HttpRequest head.Mutable
HttpResponse head.The last piece of a message body, with optional trailers.
Delivery rate estimation as draft-cheng-iccrg-delivery-rate-estimation describes it, the
sampler BBR is built on.
Whether a stream carries data in both directions or only from its initiator (RFC 9000 section 2.1).
The keys that protect packets in one direction at one encryption level: a header protection
key and a packet (payload) key.
Keeps responses as files in a directory, so the cache survives restarts (and can serve while
offline).
A DNS message (RFC 1035 section 4.1): its header, questions and resource records, decoded from
the wire format and encoded back.
An address, the data of A (IPv4) and AAAA (IPv6) records.
The data of an MX record.
A domain name, the data of NS, CNAME, PTR and DNAME records.
RDATA of a type without a typed view, kept as bytes.
A question: the name, type and class asked about.
The RDATA of a record, read as its type.
A resource record.
The data of an SOA record.
The data of an SRV record (RFC 2782).
The data of a TXT record: its character strings, read as UTF-8 (use
DnsMessage.ResourceRecord.rdata() for strings of other bytes).A
HostResolver that validates answers with DNSSEC, the replacement for LittleProxy's
dnssec4j-based DnsSecServerResolver.Configures a
DnssecHostResolver.What to accept.
The result of a lookup.
DNS data failed DNSSEC validation ("bogus"): a signature did not verify, a chain of trust was
broken, or signed data was missing its signatures or denial proofs.
Sends a DNS query message to a recursive resolver and returns the raw response.
How a draining proxy (
HttpProxyServer.drain(java.time.Duration)) tells its clients to go elsewhere, as
Envoy's --drain-strategy: each new request may be answered with Connection:
close (HTTP/1) or make the proxy send GOAWAY (HTTP/2, HTTP/3) on its connection.A resuming client's offer of 0-RTT data, as an
EarlyDataPolicy sees it.Decides, on a server, whether to accept the 0-RTT data a resuming client offers.
The four QUIC encryption levels (RFC 9001 section 4), each with its own keys.
The connections of one UDP socket, as a sans-I/O state machine after quinn-proto's
Endpoint: it routes incoming datagrams to connections by Destination Connection ID, whatever
address they come from, so that a connection follows a peer that migrates (or by the peer's
address when local IDs are zero-length, which rules migration out), creates server connections from Initial packets,
and answers what no connection should see: Version Negotiation for unknown versions, Retry for
address validation, stateless resets for unknown connection IDs, and CONNECTION_CLOSE for refused
attempts.What to do with a datagram.
The datagram belongs to a connection: pass it to
Connection.handleDatagram(long, java.net.InetSocketAddress, int, java.nio.ByteBuffer).A client's first Initial created a server connection: start driving it, then pass it the
datagram.
Send this datagram back to the datagram's sender (Version Negotiation, Retry, stateless
reset or CONNECTION_CLOSE).
Settings shared by every connection of an endpoint: how local connection IDs are made, the key
stateless reset tokens derive from, the QUIC versions accepted, and the stateless reset rate
limit.
Builds an
EndpointConfig.The connection issued a local connection ID; packets for it must reach the connection.
The peer retired a local connection ID; it no longer routes to the connection.
The connection is gone and holds no state the endpoint must keep; this is the last event.
The peer's current stateless reset token, which lets a reset with a random connection ID reach
the connection.
What a QUIC endpoint answered itself, without a connection: from
QuicServer.endpointStats() and QuicClient.endpointStats().The error codes of RFC 9113 §7, carried by RST_STREAM and GOAWAY frames.
Makes the proxy's own answer when a request fails (
ProxyFailure), e.g. to send branded
error pages or JSON instead of the default plain-text body.One field of a decoded header block (HTTP/2 HPACK, HTTP/3 QPACK): a name, which is lower case
on the wire and starts with
: for a pseudo-header, and a value.A decoded field section is larger than the decoder's SETTINGS_MAX_FIELD_SECTION_SIZE (RFC 9114
§4.2.2).
Information about the client side of a proxied flow.
Flow-control accounting for one connection (RFC 9113 §5.2, §6.9): the connection windows and a
send and a receive window for each open stream.
One HTTP/2 flow-control window (RFC 9113 §5.2, §6.9): of a stream, or of the connection when
FlowControlWindow.streamId() is 0.A flow filter expression, in the syntax of mitmproxy's filters, which the addons (
MapLocal, MapRemote, ModifyBody, ModifyHeaders, BlockList,
AntiCache, StickyCookie, HarRecorder) take to choose the exchanges they
act on.An exchange as filters see it: the request, the response once there is one, and the bodies
when they have been buffered.
What an access log needs to know about one finished exchange or flow, handed to
ActivityTracker.flowEnded(org.microproxy.FlowRecord) once it is over: an HTTP exchange once its response has been written
(or it was abandoned), a CONNECT tunnel, a SOCKS client's tunnel, a WebSocket session, a
tunnel seen by the TCP hooks, a CONNECT-UDP flow, and a QUIC flow the transparent QUIC listener
relayed or intercepted stream by stream, each when it closes.Builds a
FlowRecord; unset values are unknown.What kind of exchange or flow a record is about;
%MP_FLOW% renders its FlowRecord.Kind.label().When the phases of one request/response exchange happened, from
FlowContext.timings().The distributed trace of one exchange, made by a
FlowTracer when the request head
arrives: its trace and span ids, which FlowContext.trace(), access logs (
%TRACE_ID%, %SPAN_ID%) and scripts (ctx.trace_id) show, and the calls through
which the proxy reports each attempt to reach the server and asks for the headers that carry the
trace to it.A span
FlowTrace.startSpan(java.lang.String) started, used by one thread at a time.Traces the proxy's exchanges and flows: given with
HttpProxyServerBootstrap.withTracer(org.microproxy.FlowTracer),
it is asked for a FlowTrace when each request head arrives, and handed each exchange's
and flow's FlowRecord when it is over.One HTTP/2 frame (RFC 9113 §6).
A QUIC frame (RFC 9000 section 19, RFC 9221 and the ACK frequency extension).
An ACK frame (types 0x02 and 0x03).
An ACK_FREQUENCY frame (type 0xaf) of the QUIC ACK frequency extension, as quinn implements
it.
An inclusive range of acknowledged packet numbers.
A CONNECTION_CLOSE frame for an application error (type 0x1d), allowed only in 0-RTT and
1-RTT packets.
A CONNECTION_CLOSE frame for a transport error (type 0x1c).
CONTINUATION (§6.10).
A CRYPTO frame (type 0x06), carrying TLS handshake bytes.
DATA (§6.1): part of a stream's content.
A DATA_BLOCKED frame (type 0x14).
A DATAGRAM frame (RFC 9221; 0x30 without and 0x31 with a Length field).
The ECN counts of an ACK frame of type 0x03 (RFC 9000 section 19.3.2).
GOAWAY (§6.8).
A HANDSHAKE_DONE frame (type 0x1e).
HEADERS (§6.2).
An IMMEDIATE_ACK frame (type 0x1f) of the QUIC ACK frequency extension.
A MAX_DATA frame (type 0x10).
A MAX_STREAM_DATA frame (type 0x11).
A MAX_STREAMS frame (0x12 bidirectional, 0x13 unidirectional).
A NEW_CONNECTION_ID frame (type 0x18).
A NEW_TOKEN frame (type 0x07), with a token for future connections.
A run of PADDING frames (type 0x00), each a single zero byte.
A PATH_CHALLENGE frame (type 0x1a).
A PATH_RESPONSE frame (type 0x1b).
PING (§6.7).
A PING frame (type 0x01).
PRIORITY (§6.3): parsed and otherwise ignored.
The RFC 7540 priority signal carried by PRIORITY frames and HEADERS frames with the PRIORITY
flag.
PUSH_PROMISE (§6.6), with its complete field block.
A RESET_STREAM frame (type 0x04).
A RETIRE_CONNECTION_ID frame (type 0x19).
RST_STREAM (§6.4).
SETTINGS (§6.5).
A STOP_SENDING frame (type 0x05).
A STREAM frame (types 0x08 to 0x0f).
A STREAM_DATA_BLOCKED frame (type 0x15).
A STREAMS_BLOCKED frame (0x16 bidirectional, 0x17 unidirectional).
A frame of a type this codec does not know (an extension).
WINDOW_UPDATE (§6.9) for a stream, or for the connection when
streamId is 0.Where an intercepted frame travels, and a way to add frames next to it.
Decodes the frames of a decrypted packet payload.
Where a frame is going, as a
FrameInterceptor sees it.A connection error caused by a received frame, carrying the frame type for the Frame Type field
of the CONNECTION_CLOSE frame that reports it (RFC 9000 section 19.19).
Inspects, edits, drops and adds HTTP/2 and HTTP/3 frames on live connections, and HTTP/3 frames
in an
Http3FramePipeline.The protocol of an intercepted frame.
Reads HTTP/2 frames from a blocking stream, one call per frame, validating everything that can
be checked from a frame on its own (RFC 9113 §4, §6).
Frame type codes (RFC 9113 §6) and frame flags.
The QUIC frame types (RFC 9000 section 19 and Table 3), with the type codes each covers and
the packet types it may appear in.
Writes HTTP/2 frames to a blocking stream.
A
FlowContext that also knows the server side of the flow.A complete HTTP message: head and whole body in one object.
A complete HTTP request.
A complete HTTP response.
A value that goes up and down, such as
downstream_cx_active.How
HttpFilters.proxyToClientResponse(org.microproxy.http.HttpObject) treats the responses the proxy answers with
itself, rather than relaying a server's: its own error responses (the 502 for a server
it cannot reach, the 504 for one that does not answer, a 400 for a bad request,
the FailureResponder's and HttpFilters.proxyToServerFailure(org.microproxy.ProxyFailure)'s answers, ...),
and the short-circuit responses a filter returned from an earlier hook (HttpFilters.clientToProxyRequest(org.microproxy.http.HttpObject), HttpFilters.proxyToServerRequest(org.microproxy.http.HttpObject)), the HttpCache's answers included.gRPC's message framing: a body is a sequence of messages, each a compressed flag (one byte), a
length (four bytes, big-endian) and that many bytes of payload, compressed with the coding the
grpc-encoding header names when the flag is set.One entry of a status's details: a
google.protobuf.Any.One framed message, as it is on the wire.
A
google.rpc.Status, as servers send it in grpc-status-details-bin.Records exchanges as an HTTP Archive (HAR 1.2), as mitmproxy's
hardump /
save.har do, for browsers' developer tools, HAR viewers and ServerReplay.Configures a
HarRecorder.@stdlib//jhashlib: the JDK's message digests and MACs for hashlib.star and
hmac.star (starlarky built these on BouncyCastle).A hashlib hash object.
An hmac HMAC object.
One header or trailer field (a name and a value) as HPACK carries it.
One header or trailer field (a name and a value) as QPACK carries it.
A header protection key (RFC 9001 section 5.4): masks the low bits of the first byte and the
packet number with five bytes derived from a 16-byte sample of the ciphertext.
Where an encoded header's fields sit in the packet buffer, so that protection can fill in the
Length field and mask the packet number once the payload is written.
A decoded field section is larger than the decoder's SETTINGS_MAX_HEADER_LIST_SIZE.
A distribution of recorded values in fixed buckets, such as
downstream_rq_time: one
LongAdder per bucket, plus the sum and the count of the
values, so recording takes no lock and allocates nothing.The counts of a histogram at one moment.
HKDF (RFC 5869) over an HMAC, and the
HKDF-Expand-Label of TLS 1.3 (RFC 8446 section 7.1)
that QUIC uses for its secrets and keys (RFC 9001 section 5.1).Resolves server host names.
Decodes HPACK field blocks (RFC 7541).
Encodes field sections into HPACK field blocks (RFC 7541).
Builds the
ProtocolPolicy of HTTP/1.x clients (HttpProxyServerBootstrap.onHttp1(java.util.function.Consumer<org.microproxy.Http1PolicyBuilder>)):
the fields every protocol has, and HTTP/1-specific fields such as Http1PolicyBuilder.requestHeadTimeout(java.time.Duration)
and Http1PolicyBuilder.allowChunkedLength(boolean).A violation of HTTP/2 or HPACK by the peer (or a limit it exceeded), with the error code to send
back and the scope of the error (RFC 9113 §5.4).
An HTTP/2 frame (RFC 9113 section 6) as a
FrameInterceptor sees it: decoded, with header
blocks as field lists (Field).DATA (section 6.1).
GOAWAY (section 6.8).
HEADERS (section 6.2), with its whole decoded header block.
PING (section 6.7); its 8 opaque octets as a big-endian long.
PRIORITY (section 6.3), deprecated by RFC 9113; the proxy ignores it and never sends one.
PUSH_PROMISE (section 6.6).
RST_STREAM (section 6.4).
SETTINGS (section 6.5): the identifiers and values the frame carries, in order.
A frame of an extension type (section 5.5), such as ALTSVC (10) or PRIORITY_UPDATE (16).
WINDOW_UPDATE (section 6.9), for a stream or the connection (stream 0).
HTTP semantics of HTTP/2 field sections (RFC 9113 §8.2, §8.3): validating decoded header lists
into
RequestHeaders and ResponseHeaders, and building header lists from
HTTP/1-style messages.Limits for HTTP/2 client connections (
HttpProxyServerBootstrap.withHttp2(boolean)).Builds
Http2Options.The SETTINGS parameters of one endpoint (RFC 9113 §6.5.2).
Builds
Http2Settings, starting from the protocol's initial values.The HTTP/3 error codes (RFC 9114 §8.1), the QPACK error codes (RFC 9204 §6) and
H3_DATAGRAM_ERROR (RFC 9297 §5.2).
A violation of HTTP/3 or QPACK by the peer (or a limit it exceeded), with the error code to send
back and the scope of the error (RFC 9114 §8).
One HTTP/3 frame (RFC 9114 §7.2).
An HTTP/3 frame (RFC 9114 section 7.2) as a
FrameInterceptor sees it, decoded, with
header sections as field lists (Field) decoded through QPACK.CANCEL_PUSH (§7.2.3), on the control stream.
CANCEL_PUSH (section 7.2.3), on the control stream.
DATA (§7.2.1): part of a message's content.
DATA (section 7.2.1).
GOAWAY (§7.2.6), on the control stream.
GOAWAY (section 7.2.6), on the control stream: from a server, the first client-initiated
request stream it will not process; from a client, a push id.
HEADERS (§7.2.2): a QPACK-encoded field section, decoded with
QpackDecoder.HEADERS (section 7.2.2), with its field section decoded.
MAX_PUSH_ID (§7.2.7), sent by a client on the control stream.
MAX_PUSH_ID (section 7.2.7), from a client on the control stream.
PUSH_PROMISE (§7.2.5): a promised request's QPACK-encoded field section, on a request stream.
PUSH_PROMISE (section 7.2.5), from a server on a request stream.
SETTINGS (§7.2.4), the first frame on each control stream and sent once.
SETTINGS (section 7.2.4), the first frame of the control stream.
A frame of any other type: an extension, or a reserved type (0x1f * N + 0x21) used for
greasing.
A frame of an extension or reserved type, such as a grease frame (type
0x1f * N +
0x21) or PRIORITY_UPDATE (RFC 9218).Runs a
FrameInterceptor over HTTP/3 traffic given as the bytes of its streams: it reads
frames from a request stream or a control stream, shows each to the interceptor as an Http3Frame (HEADERS decoded through QPACK), and writes what comes back to an output stream.Options for
Http3FramePipeline.Reads HTTP/3 frames from one QUIC stream's bytes, one call per frame, validating everything that
can be checked from a frame on its own (RFC 9114 §7).
HTTP/3 frame type codes (RFC 9114 §7.2, §11.2.1).
Writes HTTP/3 frames to one QUIC stream.
HTTP semantics of HTTP/3 field sections (RFC 9114 §4.2, §4.3): validating decoded field lists
into
RequestHeaders and ResponseHeaders.Limits and timers for HTTP/3 (
HttpProxyServerBootstrap.withHttp3(boolean) and HttpProxyServerBootstrap.withHttp3Upstream(boolean)).Builds
Http3Options.The congestion controllers of the proxy's QUIC connections (see
Http3Options.Builder.quicCongestionControl).The SETTINGS parameters of one endpoint (RFC 9114 §7.2.4).
Builds
Http3Settings, starting from the defaults.The types of unidirectional streams (RFC 9114 §6.2, RFC 9204 §4.2): each such stream starts
with its type as a variable-length integer.
Checks which frames the peer may send on one stream, and in what order (RFC 9114 §4.1, §6.2.1,
§7.2).
The kind of stream a validator checks.
Which end of the connection this endpoint is.
The peer's unidirectional streams (RFC 9114 §6.2, RFC 9204 §4.2): at most one control
stream, one QPACK encoder stream and one QPACK decoder stream, and push streams only from a
server.
Reads and rewrites the bodies of buffered messages (
FullHttpMessage) in filters,
taking care of Content-Encoding and charsets so filters don't have to.A shared HTTP cache (RFC 9111) that can also keep a site usable offline.
A response made by the cache: a stored response, or its own
504.Options for
HttpCache.Counters since the cache was created.
A piece of an HTTP message body.
Hooks into the life of a single request/response exchange.
Convenience base class for
HttpFilters that keeps the original request and context.Builds
HttpFilters from lambdas, one per hook, instead of a class that overrides the
hooks it needs:The streams a built filter inspects piece by piece.
Filters made by
HttpFiltersBuilder.Runs several filters sources as one, in order.
The filters of several sources for one request.
Creates the
HttpFilters for each request.A
HttpFiltersSource that applies no filtering and no buffering unless overridden.Common header names.
An ordered, case-insensitive multimap of header fields.
Logs whole requests and responses for debugging and audits, like OkHttp's
HttpLoggingInterceptor or a mitmproxy flow dump.Configures an
HttpLogger.How messages are written.
How much of each message to log.
The head of an HTTP message: protocol version and headers.
An HTTP request method.
Base type of everything that flows through
HttpFilters: a message head
(HttpRequest / HttpResponse), a piece of body (HttpContent), the end of a
body (LastHttpContent), or a whole message (FullHttpRequest / FullHttpResponse).A running proxy.
Configures and starts a
HttpProxyServer.The head of an HTTP request.
The head of an HTTP response.
An HTTP status code and reason phrase.
Helpers for connection-management and framing headers.
An HTTP protocol version such as
HTTP/1.1.What the token in a client's first Initial packet establishes.
A local connection ID issued to the peer, to be sent in a NEW_CONNECTION_ID frame.
@stdlib//json: the interpreter's json module (Json, the same one scripts
have predeclared), with Python's names dumps and loads, and Python's refusal to
encode bytes and sets.Receives TLS traffic secrets in the NSS key log format (
SSLKEYLOGFILE), which Wireshark
reads to decrypt QUIC packets.A certificate chain and the private key of its first certificate: what a TLS server presents.
The packet protection keys of one encryption level, from one endpoint's point of view:
local protects what it sends and remote removes protection from what it receives.An
SslContextSource for the proxy's own TLS listener, presenting the certificate of a key
store entry (PKCS#12 or JKS): the HTTPS and HTTP/2 listener (withSslContextSource), and,
through KeyStoreSslContextSource.getKeyMaterial(java.lang.String), the HTTP/3 listener of a reverse proxy.The final piece of an HTTP message body, optionally carrying trailer fields.
Command-line entry point.
Adds command-line options to
Launcher.The connection IDs this endpoint issued to its peer (RFC 9000 section 5.1.1): sequence numbers,
stateless reset tokens derived from a static key, retirement by the peer, and periodic rotation
through
retire_prior_to when IDs have a lifetime.The outcome of a RETIRE_CONNECTION_ID.
Named access-log formats for
ActivityLogger, each a preset of AccessLogFormat:
an Envoy-compatible format string (or JSON dictionary) shown on each constant.Answers requests from local files, as mitmproxy's
map_local.Builds
MapLocal.One rule: requests the filter selects whose URL contains a match of
pattern are
answered from path.Sends requests to another URL, as mitmproxy's
map_remote: each rule replaces every match
of a regular expression in the request's absolute URL, and the request goes to the result.Builds
MapRemote.One rule: requests the filter matches have every match of
pattern in their URL
replaced.Keeps responses in memory, evicting the least recently used URLs beyond a size limit.
Finds the messages of a protocol in the bytes of a QUIC stream, so that
QuicInterceptor.streamMessage(org.microproxy.quic.QuicMessage, org.microproxy.quic.QuicStreamContext) sees whole messages rather than whatever each read returned (see
QuicFraming, which chooses a framer for each connection).What kind of metric a
Metric is.Entry point:
MicroProxy.bootstrap().withPort(8080).start().Enables man-in-the-middle interception of CONNECT tunnels.
When the proxy runs its TLS handshake with the server for a
CONNECT it intercepts:
after answering the CONNECT and reading the client's ClientHello, or before answering.Replaces text in request and response bodies, as mitmproxy's
modify_body: every match of
a regular expression in the decoded body becomes the replacement, in the messages a rule's filter
selects.Builds
ModifyBody.One rule: a regular expression to replace in the bodies a filter selects.
Sets and removes headers, as mitmproxy's
modify_headers.One rule: a header to replace on the messages a filter matches.
Datagram packetization layer path MTU discovery (DPLPMTUD, RFC 8899): probes larger packets in
the application data space by binary search, and detects MTU black holes from the pattern of
lost packets.
Configuration of DPLPMTUD, packetization layer path MTU discovery (RFC 8899, RFC 9000 section
14.3).
The (EC)DHE groups the handshake offers and accepts for key exchange (RFC 8446 section 4.2.7).
A monotonic clock in nanoseconds, injected into the connection layer so that timers can be
driven deterministically in tests.
The NewReno congestion controller of RFC 9002 section 7: slow start, then congestion avoidance
growing the window by one datagram per window acknowledged (Appropriate Byte Counting, RFC
3465), and a multiplicative decrease once per recovery period.
Configuration of the
NewReno controller.Hosts that bypass the upstream proxy, in the comma-separated
NO_PROXY syntax used by
curl and most HTTP clients:
* matches every host;
example.com, .example.com and *.example.com match the domain and
all its subdomains;
an IP literal matches that address, and CIDR notation (10.0.0.0/8,
fd00::/8) matches a range; addresses are compared only when the request names an IP
literal (no DNS lookups);
any entry may end in :port to apply to that port only.The ORIGIN frame (RFC 8336): a server names the origins it is authoritative for on the
connection, such as
https://b.example.com or https://b.example.com:8443, so a
client may send requests for them there without consulting DNS.Adds
--otel and its options to the command line when this module is on the class path.A token-bucket pacer (RFC 9002 section 7.7).
A packet with protection removed: its full header and its plaintext payload of frames.
Builds a datagram of one or more coalesced packets: write a header, fill the frame space, then
pad and protect.
A packet header that cannot be decoded.
A decoded QUIC packet header (RFC 9000 section 17), or one to encode.
A Handshake packet header (RFC 9000 section 17.2.4).
An Initial packet header (RFC 9000 section 17.2.2).
A header of a protected packet, with a packet number.
A Retry packet (RFC 9000 section 17.2.5): the whole packet, since it has no payload beyond
the token and the integrity tag.
A short (1-RTT) packet header (RFC 9000 section 17.3.1).
A Version Negotiation packet (RFC 9000 section 17.2.1): the whole packet.
A 0-RTT packet header (RFC 9000 section 17.2.3).
The AEAD key and IV that protect packet payloads in one direction (RFC 9001 section 5.3).
Packet number truncation and recovery (RFC 9000 section 17.1 and appendix A).
Mitigates optimistic ACK attacks (RFC 9000 section 21.4) by occasionally skipping a packet
number in the application data space: an ACK of a skipped number proves the peer acknowledges
packets it never received.
Applies packet protection (RFC 9001 section 5) to an encoded packet in place: fills in the
Length field, seals the payload and then masks the header.
One packet number space (RFC 9000 section 12.3, RFC 9002 appendix A): its keys, the packets
received and to acknowledge, the next packet number, the packets sent and not yet acknowledged
or lost, the frames waiting to be sent, the CRYPTO stream, and the loss detection state that
Recovery keeps per space.What a space has to send.
The QUIC packet types (RFC 9000 section 17).
One network path of a connection (RFC 9000 section 9): the peer's address, the local address the
connection uses on it, and what is measured per path: the RTT, the congestion controller, the
pacer, MTU discovery, the delivery rate, the bytes in flight, and the anti-amplification counts
until the path is validated (RFC 9000 section 8).
The packets of one space waiting to be acknowledged, and when an ACK must go out (RFC 9000
section 13.2): after more than
ack_eliciting_threshold ack-eliciting packets (one, by
default, so every second one is acknowledged at once), on reordering, or once
max_ack_delay has passed since the first unacknowledged ack-eliciting packet.A snapshot of the shared server connection pool.
The server's
preferred_address transport parameter (RFC 9000 section 18.2): an address
to migrate to after the handshake, with a connection ID and reset token for it.Reads a trace context from request headers and writes one onto them, in one format: W3C Trace
Context (
Propagators.TRACE_CONTEXT), B3 in its single-header and multi-header forms
(Propagators.B3, Propagators.B3_MULTI) or Jaeger's uber-trace-id (Propagators.JAEGER).The propagators, by the names
OTEL_PROPAGATORS uses: tracecontext (W3C Trace
Context: traceparent and tracestate), b3 (B3's single b3
header), b3multi (B3's X-B3-* headers) and jaeger (
uber-trace-id).A packet whose unprotected header fields are parsed but whose packet number and payload are
still protected: quinn's
PartialDecode.Decodes and encodes protobuf messages without generated code, and usually without a schema:
How the proxy behaves, where it can behave in more than one way, for the exchanges of clients
that speak one protocol: HTTP/1.x, HTTP/2 or HTTP/3 (the protocol the client speaks to the
proxy,
FlowContext.getHttpVersion()).Builds a
ProtocolPolicy.One field of a decoded protobuf message, as it appeared on the wire.
A fixed-width protobuf value in a script: what
protobuf.decode gives for a field with
wire type fixed32 or fixed64 (without a schema it could be an integer or a float), and what
protobuf.fixed32(x) and protobuf.fixed64(x) make.A protobuf group (proto2's deprecated wire types 3 and 4) in a script: what
protobuf.decode gives for one, and what protobuf.group(fields) makes.A decoded protobuf message: its fields in the order they appeared on the wire.
Protobuf type definitions, read from a
FileDescriptorSet (what protoc
--descriptor_set_out=types.desc --include_imports writes), so that messages decode with field
names, enum names and declared types instead of guesses, and gRPC calls decode with their
method's input and output types:An enum type.
A field of a message type.
A message type: its full name and fields.
An RPC method of a service.
The types a field can be declared with, as numbered in
descriptor.proto.One value of a protobuf field: what its wire type says, plus how a length-delimited value was
understood.
Length-delimited bytes (wire type 2) that are neither text nor a message, or that a schema
declares as
bytes.Four bytes (wire type 5):
fixed32, sfixed32 or float.Eight bytes (wire type 1):
fixed64, sfixed64 or double.A group (wire types 3 and 4), proto2's deprecated way of nesting a message.
A nested message (wire type 2).
A packed repeated scalar field (wire type 2): several
ProtoValue.Varint, ProtoValue.Fixed32 or
ProtoValue.Fixed64 values in one length-delimited value.Length-delimited UTF-8 text (wire type 2): a
string, or bytes that read as text.A varint (wire type 0):
int32, int64, uint32, uint64,
sint32, sint64, bool or an enum.Decides which clients may use the proxy.
Why the proxy has to answer a request itself instead of relaying the server's response.
The proxy refuses the request: an origin-form request without
HttpProxyServerBootstrap.withAllowRequestToOriginServer(boolean), an https:// request without
HttpProxyServerBootstrap.withTlsOrigination(boolean), or a CONNECT target that is not
host:port.The server's response was malformed, or the server closed the connection or failed before
the response head (or a body the filters asked to buffer) was complete.
No connection could be made to the server or any chained proxy offered for it: refused,
unreachable, timed out, a chained proxy whose own name did not resolve, or a chained proxy
that refused the
CONNECT or SOCKS request.The shared connection
pool had no connection to spare within the connect timeout.
There is nowhere to send the request: it names no host (
hostAndPort is null), or the
ChainedProxyManager offered no route.The request body is larger than the filters asked to buffer (
maxBytes).The server did not answer within the idle timeout.
The TLS handshake with the server (when intercepting) or with a TLS chained proxy failed or
did not finish within
HttpProxyServerBootstrap.withTlsHandshakeTimeout(java.time.Duration) (or the
request's HttpFilters.proxyToServerTlsHandshakeTimeout()), e.g. because its
certificate is not trusted.Why a TLS handshake failed, read from the exception's cause chain: the certificate checks
first, then an alert from the peer, a timeout, or anything else.
The server's name did not resolve (direct connections).
Which address a PROXY protocol header the proxy sends to a server (
HttpProxyServerBootstrap.withSendProxyProtocol(boolean)) names as its destination, when the client's
connection did not bring a header of its own (whose destination is passed on as it is).Whether client connections start with a PROXY protocol header (v1 or v2, as HAProxy defines
them), which names the client a load balancer in front of the proxy connected for.
Receives qlog-style connection events, for debugging: packets sent, received and lost, recovery
metrics, key updates and state changes.
Decodes QPACK field sections (RFC 9204) and keeps the dynamic table in step with the peer's
encoder.
Encodes field sections with QPACK (RFC 9204).
A QUIC client endpoint on one UDP socket, from which any number of connections can be made.
A QUIC connection with a blocking API made for virtual threads: open and accept streams, read and
write them as
InputStreams and OutputStreams, send and receive
datagrams.Learns of an endpoint's connections as they open, complete their handshakes and close, for
statistics: set with
QuicServer.observe(io.github.mahmoudimus.quic.QuicConnection.Observer) or QuicClient.observe(io.github.mahmoudimus.quic.QuicConnection.Observer).Connection statistics.
A blocking operation failed because its connection ended, or could not be established.
One intercepted QUIC connection, as a
QuicInterceptor sees it: who the client is, where
the connection goes, what was negotiated, and a way to add datagrams.One datagram's payload (RFC 9221) of an intercepted QUIC connection, as a
QuicInterceptor
sees it.A QUIC connection error (RFC 9000 section 20), carrying the error code a
CONNECTION_CLOSE
frame sends to the peer.Which
MessageFramer cuts the streams of an intercepted QUIC connection into messages, for
a QuicInterceptor that overrides QuicInterceptor.streamMessage(org.microproxy.quic.QuicMessage, org.microproxy.quic.QuicStreamContext); the limit on a
message's size; and the error code a stream is reset with when a message is too large or
malformed.Sees, rewrites, drops and adds the stream data and datagrams of QUIC connections the proxy
terminates without speaking their protocol: the QUIC counterpart of
TcpInterceptor.One whole message of a stream of an intercepted QUIC connection, as
QuicInterceptor.streamMessage(org.microproxy.quic.QuicMessage, org.microproxy.quic.QuicStreamContext) sees it: the payload a MessageFramer cut out of the stream
(without its length prefix or delimiter), which side sent it, on which stream, and when it was
complete.A QUIC server on one UDP socket.
Sees the datagrams a server receives that none of its connections claims (by Destination
Connection ID) before its endpoint does: a client's first Initial, packets of unknown
versions, packets for connections the server does not know.
Where an unbound server's datagrams go: the transport it runs over
instead of a socket.
One stream of an intercepted QUIC connection, as a
QuicInterceptor sees it: the
connection's details (QuicContext), which stream it is, who opened it, and a way to add
bytes.A stream operation failed because the peer abandoned the stream: it reset the stream (RESET_STREAM,
seen by a reader) or asked this side to stop sending (STOP_SENDING, seen by a writer).
How the peer abandoned the stream.
Bytes the proxy read from one side of a stream of an intercepted QUIC connection, as a
QuicInterceptor sees them.QUIC variable-length integers (RFC 9000 §16), which HTTP/3 uses for frame types, lengths,
settings, stream types, push IDs and error codes.
The QUIC versions this module speaks: version 1 (RFC 9000) and version 2 (RFC 9369).
Generates random connection IDs of a fixed length, 8 bytes by default.
@stdlib//jrandom: randomness from SecureRandom, for random.star and
uuid.star (starlarky's came from BouncyCastle's registrar).A set of non-negative
long values stored as disjoint, non-adjacent half-open ranges, for
long runs with random insertion and removal: received packet numbers, ACK ranges, received and
acknowledged stream offsets.A half-open range
[start, end).A delivery rate sample (draft-cheng-iccrg-delivery-rate-estimation), taken when an ACK
acknowledges packets that were in flight.
A recorded exchange, read from a HAR file (as
HarRecorder, browsers and mitmproxy write
them) or a WARC file (as WarcRecorder writes them), for ServerReplay and ClientReplay.Loss detection and congestion control of one connection (RFC 9002): the three packet number
spaces, the in-flight counts, the RTT estimator, the congestion controller, the pacer, MTU
discovery and the probe timeout.
Receives acknowledged and lost packets.
Configuration of loss detection, congestion control, pacing and MTU discovery.
Builds a
RecoveryConfig.The states of the receiving part of a stream (RFC 9000 section 3.2, figure 3).
The connection IDs the peer issued to this endpoint (RFC 9000 section 5.1.2): a window of at
most
limit IDs, our active_connection_id_limit, starting with the one in use.Signals that an ID could not be stored; see
RemoteCidQueue.InsertError.Sequence numbers to retire, and the reset token of the ID now in use.
A validated HTTP/2 request header section: the control data from the pseudo-header fields and
the remaining fields, as
Http2Headers.toRequest(int, java.util.List<io.github.mahmoudimus.http2.HeaderField>) produces it.A validated HTTP/3 request header section: the control data from the pseudo-header fields and
the remaining fields, as
Http3Headers.toRequest(long, java.util.List<io.github.mahmoudimus.http3.HeaderField>) produces it.Why an exchange or a flow ended the way it did, in the vocabulary of Envoy's access-log response
flags: each constant has Envoy's short code (
UF, UT, ...) and long name, so logs
read by tools made for Envoy keep their meaning.A validated HTTP/2 response header section, as
Http2Headers.toResponse(int, java.util.List<io.github.mahmoudimus.http2.HeaderField>) produces it.A validated HTTP/3 response header section, as
Http3Headers.toResponse(long, java.util.List<io.github.mahmoudimus.http3.HeaderField>) produces it.Where a response sent to the client came from; see
ActivityTracker.responseSentToClient(FlowContext, HttpResponse, ResponseSource).Control frames waiting to be sent in one packet number space, and, attached to a
SentPacket, the control frames that packet carried, to queue again if it is lost.A RESET_STREAM to send.
How long the proxy waits before trying the next route after a connection attempt failed: the
next chained proxy, or the direct fallback, that the
ChainedProxyManager offered.The Retry Integrity Tag (RFC 9001 section 5.8, RFC 9369 section 3.3.3): AES-128-GCM with a
fixed per-version key and nonce over the Retry pseudo-packet, which is the original Destination
Connection ID (with its length byte) followed by the Retry packet without its tag.
Reverse proxy mode: every request on the listener goes to one fixed upstream server, whatever
its target, as a server of its own rather than a forward proxy.
Declarative request/response rewriting: an ordered list of
RewriteRules.Rules, each matching URLs by
regular expression and editing headers and textual response bodies.Builds
RewriteRules.One rewrite rule: a URL pattern plus edits.
Round-trip time estimation for one network path (RFC 9002 section 5): the latest sample, the
smoothed RTT and its variance (RFC 6298), and the minimum RTT.
Decides whether a new trace, or the proxy's part of a trace that came with the request, is
sampled: recorded and exported.
Sees every call into a script's hooks (with the optional Starlark module): when it starts, and
how it ended, with the interpreter steps it ran, about how many bytes of values it created, how
long it took and why it failed.
A client's TLS
ClientHello, as on_client_hello and ctx.client_hello see
it: a read-only view of a ClientHello.Per-request context: who the client is,
vars, a dict that lives as long as the request
so on_request can leave notes for on_response, timings, a snapshot of the
exchange's timings taken when it is read, client_hello, the TLS ClientHello that
started the client's intercepted session (None before it is read, and for plain HTTP),
forwarded_via, the session's server that the request is forwarded through as the
client's proxy (host:port: an intercepted HTTPS proxy, or an HTTP proxy whose session is
plain HTTP), or None, socks_version, the SOCKS version the client reached the
proxy with (5, or 4 for SOCKS4 and 4a), or None for an HTTP client,
transparent_quic, whether the client's QUIC came to the transparent QUIC listener, and
script_stats, what the calls into scripts for the exchange added up to so far (calls,
time, interpreter steps and bytes of values created; see ScriptUsageValue),
early_data, whether the HTTP/3 request arrived as 0-RTT early data, which may be a
replay: a hook may answer it 425 (Too Early) for its client to send again after the
handshake, protocol, the protocol the client speaks to the proxy ("http1",
"http2" or "http3", whose protocol policy applies), or None where the
hook gets no flow.Drives the proxy from a Starlark script.
Options for
ScriptedProxy.A Starlark script failed to parse, compile or run its top-level statements.
Why the proxy has to answer a request itself, as
on_failure sees it: a read-only view
of a ProxyFailure.A WebSocket frame as
on_websocket_frame sees it.Where a frame
on_frame sees travels: the protocol, the client connection and stream,
the client and the server.The headers of a request or response, or the header block of an HTTP/2 or HTTP/3 frame.
An HTTP/2 or HTTP/3 frame as
on_frame sees it, or as h2.data(...) and the like
make it.An intercepted QUIC connection, or one of its streams, as
on_quic_start,
on_quic_stream_data, on_quic_message, on_quic_datagram and on_quic_end
see it: the client, the server (host, port, server, and address,
where the proxy connected to), the sni and alpn both sides use, whether the QUIC
came inside a CONNECT-UDP flow (masque), vars, a dict that lives as long as the
connection (its streams share it), and error, why the connection failed (None
until then, and for one that ended normally).Bytes of an intercepted QUIC connection, as
on_quic_stream_data (bytes read from one side
of a stream), on_quic_message (one whole message of a framed stream, without its length
prefix or delimiter) and on_quic_datagram (one datagram) see them: data,
text (None when the bytes are not valid UTF-8, as a character split between two reads is
not), from_client, stream_id (on the client's connection; None for a
datagram) and timestamp (seconds since the epoch).A request as scripts see it.
A response as scripts see it: from the server in
on_response, or made by
response().The
stats module: a script's own metrics, kept in the proxy's StatsRegistry as
script.<name> next to the proxy's (and shown wherever they are: Prometheus, statsd).A counter of a script.
A gauge of a script.
A histogram of a script.
A raw TCP tunnel, as
on_tcp_start, on_tcp_message and on_tcp_end see
it: the client, the target, whether the proxy decrypted the client's TLS (tls) with its
sni and alpn, vars, a dict that lives as long as the tunnel, and
error, why the tunnel failed (None until then, and for one that ended normally).Bytes read from one side of a raw TCP tunnel, as
on_tcp_message sees them: data,
text (None when the bytes are not valid UTF-8, as a character split between two
messages is not), from_client and timestamp (seconds since the epoch).ctx.timings: a read-only snapshot of the exchange's FlowTimings, in milliseconds
as floats, each None when that phase has not happened (yet) or did not happen at all.The
trace module: the distributed trace of the exchange a hook runs for (see
microproxy-otel), whose span a script can add attributes and events to:
trace.set_attribute("tenant", "acme"), trace.add_event("rule.matched", {"rule": "r1"}).A UDP flow (CONNECT-UDP), as
on_udp_start, on_udp_message and on_udp_end
see it: the client, the target (host, port, server, and address,
what its name resolved to), and vars, a dict that lives as long as the flow.One datagram of a UDP flow (CONNECT-UDP), as
on_udp_message sees it: data,
text (None when the payload is not valid UTF-8), from_client and
timestamp (seconds since the epoch).What the calls into scripts for one exchange added up to, as
FlowContext.scriptStats()
gives it: how many calls, how long they took, how many interpreter steps they ran and about how
many bytes of values they created (an estimate of what was made, not of what stayed in memory).ctx.script_stats: what the calls into scripts for the exchange added up to before the
call reading it (FlowContext.scriptStats()), read when it is: calls,
time_ms (a float), steps and alloc_bytes (an estimate of the bytes of values the
calls created, not of what stayed in memory).A whole WebSocket message as
on_websocket_message sees it, or one a script made with
websocket_message(...).The traffic secrets for one encryption level, as the TLS handshake hands them to packet
protection: one secret per direction and the cipher suite they are for.
Filters that say which streams they inspect piece by piece.
An
SslContextSource backed by a self-signed certificate generated in memory for
localhost, 127.0.0.1 and ::1 (or the names given).The outgoing data of one stream that is not yet acknowledged: what the application wrote, what
has been sent, what was deemed lost and must be sent again, and which ranges the peer has
acknowledged.
The range
SendBuffer.pollTransmit(int) chose to send next.The states of the sending part of a stream (RFC 9000 section 3.1, figure 2).
What loss recovery remembers about a sent packet until it is acknowledged or deemed lost (RFC
9002 appendix A.1.1).
The sent packets of one packet number space that are neither acknowledged nor lost, by packet
number.
How a server accepts connections: its TLS configuration (certificates, possibly selected per SNI,
ALPN, session tickets and 0-RTT), the transport settings, Retry-based address validation, the
NEW_TOKEN tokens that let returning clients skip the Retry, the connection cap, whether clients
may migrate, and a preferred address.
Builds a
ServerConfig.Implementations of the shared server connection pool.
Answers requests from recorded responses instead of contacting servers, as mitmproxy's
server_replay.Configures a
ServerReplay.What happens to requests without a recording, as mitmproxy's
server_replay_extra.A response answered from a recording, which the proxy reports as
ResponseSource.REPLAY.Where a proxy is in its life (
HttpProxyServer.state()), with the names Envoy's admin
/ready answers and the numbers its server.state gauge shows.What a client remembers about servers between connections: TLS session tickets, for resumption
and 0-RTT (each ticket also carries the server's transport parameters, which 0-RTT data must keep
within), and NEW_TOKEN tokens, which let a server skip its Retry round trip.
A session ticket a client received in a NewSessionTicket message (RFC 8446 section 4.6.1),
with what it needs to resume the session: the pre-shared key derived from the resumption master
secret, the cipher suite, the ticket age obfuscation, and for 0-RTT the ALPN protocol and the
server's QUIC transport parameters, which a client must remember and use for its early data
(RFC 9000 section 7.4.1).
The role of an endpoint in a connection.
The signature schemes (RFC 8446 section 4.2.3) the handshake knows.
Byte loops on the proxy's hot paths, with an optional SIMD implementation.
The operations, in scalar and SIMD flavours.
The three packet number spaces (RFC 9000 section 12.3).
What a propagator carries between processes: a 128-bit trace id, a 64-bit span id, the trace
flags (bit 0: sampled) and the W3C
tracestate, as OpenTelemetry's SpanContext.Bounds on what one span (or log record) keeps, so that attributes a script or a request supplies
cannot grow it without limit: past them, attributes and events are dropped and counted as
dropped in the export, and longer string values are cut.
Small factory methods for
SSLContexts.Supplies TLS configuration for one side of a connection.
Adds
--script to the command line when this module is on the class path.A compiled Starlark file whose top-level statements have run.
Bounds on each call into a script (and on running its top level).
A 16-byte stateless reset token (RFC 9000 section 10.3), as carried in NEW_CONNECTION_ID
frames, the
stateless_reset_token transport parameter and the tail of a Stateless Reset.Pushes a registry's metrics to a statsd server over UDP, every flush interval (5 seconds by
default, as Envoy), from a virtual thread: counters as the increase since the last flush (
|c), gauges as their value (|g), by their flat names after the registry's prefix (envoy.cluster.direct.upstream_rq_total:3|c).Settings for a
StatsdSink.Renders a registry's metrics as Envoy's admin endpoint does: Prometheus's text exposition
format, the plain
/stats dump and its JSON form.The proxy's metrics, by Envoy's flat stat names (
http.<prefix>.downstream_rq_total,
cluster.<name>.upstream_cx_connect_ms, ...), each with the tags its name carries (TagExtractor), for StatsFormatter and StatsdSink to show.Settings for a
StatsRegistry.What happens to a new cluster once
StatsRegistry.Builder.maxClusters clusters have stats.Metrics named
<prefix>.<name> whose names come from outside the proxy, such as a
script's (script.<name>), and of which there may be at most a fixed number: past it, new
names get metrics that do nothing (and a warning is logged once), so their number stays bounded
whatever names are asked for.The Python-compatible standard library ported from starlarky, for
load() in scripts:
load("@stdlib//urllib/parse", "parse"), load("@vendor//option/result", "Ok").Bounds on running a module's top-level statements.
Remembers the cookies servers set and sends them with later requests, as mitmproxy's
stickycookie, so that a session started in one client carries over to others (a browser and a
command-line tool, or replayed requests).Application events about streams, polled from
StreamsState.poll().The peer raised the stream limit, so at least one more stream of this directionality may be
opened.
A finished stream's data, FIN included, has all been acknowledged.
The peer opened one or more streams, which
StreamsState.accept(Dir) now returns.A stream probably has data, its end or a reset waiting to be read.
The peer sent STOP_SENDING: it no longer wants the stream's data.
A stream that could not take more data might take some now, or was stopped.
An application-level stream operation that cannot proceed.
Why the operation failed.
A stream ID (RFC 9000 section 2.1): the two low bits give the initiator and direction, the rest
the stream's index among the streams of that type.
What a sent STREAM frame carried, without its data, which stays in the stream's
SendBuffer: kept with the sent packet to acknowledge or retransmit the range.The streams of one connection (RFC 9000 sections 2 to 4): opening and accepting streams,
stream and connection flow control, the send and receive state machines, RESET_STREAM and
STOP_SENDING, priorities, and the control and STREAM frames they produce.
A value taken out of a metric's flat name, which Prometheus shows as a label.
Takes tag values out of flat stat names, once, when a metric is registered, as Envoy's tag
extraction does:
cluster.direct.upstream_rq_2xx becomes cluster.upstream_rq_xx
with the tags envoy_cluster_name="direct" and envoy_response_code_class="2".A name with its tags taken out.
One rule.
One raw TCP tunnel, as a
TcpInterceptor sees it: where it goes, whether the proxy
decrypted it, and a way to add bytes.Sees, rewrites, drops and adds the bytes of raw TCP tunnels: mitmproxy's
tcp_start,
tcp_message, tcp_end and tcp_error hooks.Bytes the proxy read from one side of a raw TCP tunnel, as a
TcpInterceptor sees them.OpenTelemetry for the proxy, with nothing but the JDK: context propagation (W3C Trace Context,
and B3 and Jaeger when configured), an
X-Request-Id per request, a SERVER span per
exchange (HTTP/1, HTTP/2 and HTTP/3) with a CLIENT span per attempt to reach the server, an
INTERNAL span per tunnel or flow (CONNECT, SOCKS, WebSocket, CONNECT-UDP, QUIC), and the
export over OTLP/HTTP, as protobuf or JSON, of those spans, of the proxy's stats as metrics, and of its access-log records as log records.Configures a
Telemetry; every setting has OpenTelemetry's default.How OTLP is sent:
http/protobuf or http/json.What happens to a request's
X-Request-Id.What goes upstream when the proxy strips tracing headers (
HttpProxyServerBootstrap.withoutTracingHeadersUpstream()).A stateless session ticket encrypter for a server (RFC 8446 section 4.6.1, RFC 5077 section 4):
the session state is sealed into the ticket with AES-256-GCM under a server key, so the server
keeps nothing per session.
The timers of a connection, kept in a
TimerTable.The TLS alert descriptions (RFC 8446 section 6) the handshake raises.
Configuration for TLS 1.3 handshakes in QUIC, shared by any number of
TlsSessions.Builds a
TlsConfig.TLS client fingerprints of a
ClientHello, as access logs show them (
%TLS_JA3_FINGERPRINT%, %TLS_JA4_FINGERPRINT%): JA3, the MD5 of the hello's version,
cipher suites, extensions, groups and point formats, and JA4, a readable prefix and two
truncated SHA-256 hashes of the sorted cipher suites and extensions.Who the proxy expects at the other end of a TLS connection to a server, when that is not simply
the request's host: the server name it sends in the ClientHello (SNI, RFC 6066 section 3) and
the host name the server's certificate is verified against (HTTPS endpoint identification, RFC
9110 section 4.3.4).
A TLS 1.3 handshake for QUIC (RFC 9001), as a sans-I/O state machine modelled on quinn's
crypto::Session.An address validation token: a payload and a random nonce.
The server's secret for sealing address validation tokens, as quinn does it: an HKDF-SHA256
pseudorandom key from a master key, from which each token derives a one-time AES-256-GCM key
using its random nonce as the HKDF info.
Limits the reuse of NEW_TOKEN tokens, which attackers could replay to use the server as an
amplifier (RFC 9000 section 8.1.4).
A bounded, in-memory
TokenStore: up to a number of server names, each with a queue of up
to a number of tokens.What an address validation token says, encrypted so that only the server can read it.
A token sent in a Retry packet (RFC 9000 section 8.1.2), bound to the client's address and
port, and short-lived since the client returns it at once.
A token sent in a NEW_TOKEN frame (RFC 9000 section 8.1.3), for a later connection.
Where a client keeps the address validation tokens servers send in NEW_TOKEN frames (RFC 9000
section 8.1.3), by server name, to present in the first Initial of a later connection so the
server can skip its Retry round trip.
Issues and checks a server's address validation tokens (RFC 9000 section 8.1): Retry tokens,
bound to the client's address and port and valid for
retryTokenLifetime, and NEW_TOKEN
tokens, bound to its IP address, valid for validationTokenLifetime and logged against
reuse.A datagram a
Connection wants sent: usually to the peer's address on the current path,
but a PATH_CHALLENGE or PATH_RESPONSE may go to another address, or (on a client probing a new
path, Connection.probePath(long, java.net.InetSocketAddress)) from another local address.The transport settings of a connection, the same for both sides: flow-control windows, stream
limits, timeouts, loss detection, congestion control, MTU discovery, DATAGRAM support and the
debugging aids.
Builds a
TransportConfig.The congestion controllers this module provides.
QUIC transport parameters (RFC 9000 section 18), with the extensions
max_datagram_frame_size (RFC 9221), grease_quic_bit (RFC 9287),
version_information (RFC 9368) and the ACK frequency draft's min_ack_delay.Builds
TransportParameters, starting from the defaults.Trusts every certificate and host name.
One UDP flow, as a
UdpInterceptor sees it: where it goes, and a way to add datagrams.Sees, rewrites, drops and adds the datagrams of UDP flows the proxy relays: the UDP counterpart
of
TcpInterceptor, as mitmproxy's udp_message hooks.One datagram's payload in a UDP flow the proxy relays, as a
UdpInterceptor sees it.A transport parameter this module does not interpret, kept as received: a reserved (GREASE)
parameter or an extension.
A long header packet of a version this endpoint does not speak.
A
ChainedProxyManager configured like command-line HTTP clients: an upstream proxy URL
for plain HTTP, one for HTTPS (CONNECT), and NoProxyRules for hosts reached directly.QUIC variable-length integers (RFC 9000 section 16): values below 262, encoded in 1,
2, 4 or 8 bytes with the length in the two most significant bits of the first byte.
The
version_information transport parameter (RFC 9368 section 3), which authenticates
version negotiation.Reads WARC records (versions 1.0 and 1.1) one after another, as
WarcRecorder writes them
and as other archiving tools do: plain .warc files, or .warc.gz files with one
gzip member per record (or one for the whole file).One WARC record: its version line, named fields and block.
Records the traffic between the proxy and servers as WARC 1.1 files (ISO 28500), the format web
archives use, so captures can be replayed with tools such as pywb or inspected with warcio.
Options for
WarcRecorder.Appends WARC 1.1 records to files in a directory, starting a new file (each opened by a
warcinfo record) when one reaches its size limit.A WebSocket frame (RFC 6455 section 5.2).
A whole WebSocket message (RFC 6455 section 5.4): the payloads of a text or binary frame and its
continuation frames, joined, and inflated when the connection uses permessage-deflate (RFC
7692).
The kind of data a message carries (its first frame's opcode).
Decodes Zstandard data (RFC 8878).
Options for
ZstdDecompressor.A dictionary for frames compressed with one (RFC 8878 section 5): either a formatted dictionary,
as made by
zstd --train, with its own ID, entropy tables and starting offsets, or raw
content with ID 0.The input is not valid Zstandard data, or needs more than the decoder is allowed to use.
Decompresses Zstandard data read from another stream.