chore(deps): update dependency org.mock-server:mockserver-netty-no-dependencies to v9

[renovate]

Note

This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Change	Age	Confidence
org.mock-server:mockserver-netty-no-dependencies (source)	8.0.0 → 9.0.0

---

Release Notes

mock-server/mockserver-monorepo (org.mock-server:mockserver-netty-no-dependencies)

v9.0.0

This release delivers a sustained performance and memory programme alongside data-integrity fixes under load, plus a large set of LLM-provider correctness fixes, dashboard improvements, and client-library parity work. Headline numbers from the single-load-generator benchmark on the same six-core rig (builds 420 and 464): the healthy ceiling rises from 39,033 to 57,149 req/s and the peak from 43,671 to 59,905 req/s, with p95 at 32,000 req/s falling from 56.6 ms to 0.44 ms on the new ZGC default in the Docker images; event-log retained heap at 20,000 entries falls from 429 MB to 61 MB; Docker image download shrinks ~23%; and instance shutdown drops from ~107 ms to near zero. 22 BREAKING changes affect HTTP/3, DNS mocking, binary (non-HTTP) proxying and binary expectation matching while proxying, template-failure response codes, maxLoggedMatchFailures's default, initialisation-file id conflicts, the Node client's TypeScript typings and exports map, LOG_ENTRIES log output, control-plane error handling and mTLS, the Rust client's enums, verification-failure wording, response statusCode validation, AsyncAPI and response/OpenAPI verification, GenAI trace span names, the Node client's recorded-request typings, and the Go client/Testcontainers module's /v9 module paths — see Upgrading from 8.0.0 and the BREAKING entries under Changed. For a per-change migration list, see the upgrade guide at https://www.mock-server.com/mock_server/upgrading_to_9.html.

Metric	Before	After
Throughput, healthy ceiling / peak (req/s, 6 cores)	39,033 / 43,671	57,149 / 59,905
p95 latency at 32,000 / 48,000 req/s offered	56.6 ms / 82.4 ms	0.44 ms / 12.0 ms
Event-log heap (20,000 entries)	429 MB	61 MB
Docker image download (linux/arm64, standard image)	~167 MB	~129 MB
Instance shutdown time	~107 ms	~0 ms

"Before" is perf build 420 (commit d568695, 2026-09-24, JDK 17.0.20, G1 collector), measured nine days after the 8.0.0 tag and already carrying some of this release's own work, since 8.0.0 itself was never measured on this rig. "After" is perf build 464 (commit efdc522, 2026-09-27, JDK 25, ZGC), the performance page's single-load-generator figures; the page's headline is now a different, multi-generator measurement (see Changed). Both are comparable with each other but not with any benchmark published after this release.

Upgrading from 8.0.0

• Go client and Go Testcontainers module users: both modules move to /v9 module paths (the Go module proxy refused their 8.0.0 tags) — run go get github.com/mock-server/mockserver-monorepo/mockserver-client-go/v9 (and the Testcontainers module's /v9 path if you use it) and change your
  imports from the /v7/unsuffixed paths to the /v9 ones; see Changed.
• HTTP/3 users (http3Port set): the QUIC native library now ships separately — use the -jar-with-dependencies-http3 jar or the mockserver/mockserver:<version>-http3 Docker image (latest-http3, snapshot-http3; Helm: image.variant=http3), and a server that cannot serve HTTP/3 (missing
  native, or the port unusable) now refuses to start instead of silently falling back.
• DNS mocking users (dnsEnabled=true): MockServer now refuses to start if its dnsPort cannot be bound, instead of logging a warning and running without DNS. Leave dnsPort at its default of 0 to let the OS pick a free port, or set dnsEnabled=false.
• TypeScript users of mockserver-client/llm: the deep-import typings no longer declare a default export; import from mockserver-client itself, use import llm = require(...)/import * as llm from ..., or turn on esModuleInterop (see Changed).
• Binary (non-HTTP) proxy users: a client connection now always keeps one upstream connection for its whole life — forwarding one message per upstream connection is removed, along with its forwardBinaryRequestsWithoutWaitingForResponse setting (a value still set is ignored, with a warning); remove it from your configuration.
• Anyone reading a request or response body from message/arguments of LOG_ENTRIES output (including the MCP retrieve_logs/raw_retrieve tools): read it from the entry's httpRequest/httpResponse instead — message/arguments now refer to that request/response by a short form
  such as "POST /orders" or "201".
• Anyone treating a control-plane 400 as any failure, or catching the Java client's IllegalArgumentException for non-input failures: an unexpected server-side fault is now a 500 with a generic message and correlation id; 400 is now reserved for requests MockServer genuinely rejects. The
  Java client's retrieveLogsByCorrelationId and retrieveActiveExpectations(requestDefinition, format) now throw instead of returning the error's text.
• Anyone importing a path inside mockserver-client/mockserver-node other than the package or a documented module: both packages now have an exports map, so an unlisted path (.d.ts files, tasks/mockServer.js, etc.) now fails to resolve — resolve <package>/package.json and join a file's
  path to that directory if you need one by location.
• Control-plane mTLS, Java client: the client now trusts only controlPlaneTLSMutualAuthenticationCAChain for MockServer's certificate; add MockServer's own CA to that chain if it signs the server certificate.
• Control-plane mTLS, server: MockServer now accepts only client certificates signed by controlPlaneTLSMutualAuthenticationCAChain; add MockServer's own CA to the chain if it signs your client certificates (or use your own CA if it's the bundled default), and MockServer now refuses to start with
  mTLS required, no chain set, and the bundled default CA — set the chain or configure your own CA with certificateAuthorityCertificate/certificateAuthorityPrivateKey.
• Rust client users who match on its enums: every public enum is now #[non_exhaustive] (add a wildcard arm), and server-sent enums (ResponseMode, BinaryUpstream, CrossProtocolTrigger, the Load* enums) gain an Unknown variant that cannot be sent back; LoadThresholdMetric also gains
  CheckFailureRate.
• Anyone asserting the exact text of an over-count verification failure (never(), exactly, atMost, between, verifyZeroInteractions): the message now reads "found … but should have been found …" instead of "not found".
• Anyone with a response statusCode of 0 or outside 100–999 (most likely from a blank 8.0.0 dashboard status field): it is now rejected at creation with a 400, or skipped with a WARN (naming it) when loaded from an initialization/persisted-expectations file, with the file backed up first.
• AsyncAPI verification users (PUT /mockserver/asyncapi/verify, or the Java client's verifyAsyncMessage): put atLeast/atMost/exactly inside count, not at the top level — the endpoint now answers 400 for unknown fields instead of ignoring them.
• Anyone verifying a response body with a regex, JSON path, JSON Schema, XPath, XML Schema, form, multipart, fuzzy, GraphQL, JSON-RPC, WASM or allOf matcher: that matcher is now actually applied, where it was previously ignored (verification passed whenever any recorded response had a JSON object
  body).
• Anyone verifying requests with an OpenAPI matcher: only requests for the matched operationId now count, instead of every recorded request (verifySequence was unaffected).
• Anyone selecting LLM completions by gen_ai.operation.name == "chat": Gemini calls are now generate_content, and prompt-string completions (legacy /v1/completions, Mistral FIM, Ollama /api/generate, prompt-based Bedrock InvokeModel models) are now text_completion — update to match
  chat, generate_content and text_completion together.
• TypeScript users of the Node client's retrieveRecordedRequests/retrieveRecordedRequestsById: now typed Promise<RequestDefinition[]> instead of Promise<HttpResponse[]>; narrow each result to HttpRequest before reading HTTP-specific fields.
• Anyone proxying binary (non-HTTP) traffic while binary expectations are registered on the same MockServer: a message matching a binary expectation is now answered by it and not forwarded, by default (matchBinaryExpectationsWhenProxying); set it to false to always forward as in 8.0.0.
• Anyone relying on every "didn't match" comparison being logged: the new maxLoggedMatchFailures property now defaults to 50, so at INFO only the first 50 "didn't match" entries per request are logged; set maxLoggedMatchFailures=-1 to keep logging every comparison.
• Anyone with expectations in an initializationJsonPath file whose ids repeat: the file now keeps the last expectation for each repeated id, not the first; remove the repeated ids, or put the one you want last.
• Anyone relying on a failed template answering 404/502: a response/forward template that fails, or whose output isn't valid, now answers 500 by default (templateFailureAsServerError); set it to false to keep the 8.0.0 answers.

Also worth checking, though none is a breaking change: if you override the standard Docker images' ENTRYPOINT or copy the jar out of them, /mockserver-netty-jar-with-dependencies.jar is now split into /mockserver.jar and /mockserver-deps.jar — use -cp /mockserver.jar:/mockserver-deps.jar:/libs/* (java -jar /mockserver.jar still runs, but without the CDS start-up archive, so it starts more slowly); with forwardProxyBlockPrivateNetworks on, a request that matches no expectation and whose Host header names MockServer itself by a name it doesn't recognise as its own (a Docker Compose or Kubernetes service name, for example) now gets 502 Bad Gateway instead of 404 Not Found, because that name resolves to a private address — add the name to noProxyHosts, or set attemptToProxyIfNoMatchingExpectation=false if MockServer isn't used as a proxy, to get the 404 back; and if you set localBoundIP, it now also keeps the DNS and HTTP/3 ports on that address — a DNS query or HTTP/3 request sent to another address of the host is no longer answered, so send them to the localBoundIP address, or leave localBoundIP unset.

Security

• Velocity templates now have a time limit (mockserver.velocityTemplateExecutionTimeout, default 5000 ms, same as JavaScript templates). A runaway #foreach, recursive macro or chained #define block could previously hold a template thread until restart; it now fails with a timeout error at
  its next loop iteration, macro call or #parse/#evaluate. A single slow Java call inside a template is not interrupted, and the limit does not cap memory. Set the property to 0 to remove it.
• Netty upgraded from 4.2.17.Final to 4.2.19.Final, and BouncyCastle from 1.85 to 1.86, a security release whose advisories in the parts of Netty MockServer uses cover HTTP/1.1 request/response smuggling (including improper CRLF neutralization) and an origin validation error, unbounded
  resource consumption in the HTTP/1.1, HTTP/2, HTTP/3 and DNS codecs and the base codec, input misinterpretation in the SOCKS codec, and an SNI routing bypass and an improper access control in the handler module. Two visible changes: an HTTP/2 client whose SETTINGS_INITIAL_WINDOW_SIZE change would
  overflow a stream's flow-control window now has its connection closed with FLOW_CONTROL_ERROR, as RFC 9113 requires, instead of having that one stream reset; and in a multipart/form-data request, a file part whose Content-Type is not a plausible media type (for example text) is now read as
  application/octet-stream, so a partContentTypes matcher for such a part must name application/octet-stream. Netty 4.2.18 also tightened its HTTP/2 frame decoder to validate header values as well as names; unvalidated inbound frames (a leading space, an embedded DEL 0x7F, other control
  characters in a header value) are a shape MockServer is used to record, so inbound frame validation is now disabled on the multiplex codec, keeping that leniency for HTTP/2 requests on the multiplex path (this also disables inbound header-name validation there, since Netty folds both under one
  flag); outbound names and HTTP/2-forbidden connection-specific headers (Connection, Transfer-Encoding) remain validated.
• The binary launchers (Node, Python, Ruby, Go, Rust, .NET, PHP) no longer start MockServer through a shell, or no longer let a shell misread their arguments, on Windows; the Node launcher never uses a shell at all.
  • The Node launcher no longer starts MockServer through a shell. On Windows, runBinary and the mockserver command ran the bundle's mockserver.bat under cmd.exe, so %NAME% in an argument or in the cache directory path was replaced with an environment variable's value, and a line break cut
    the command short. On every platform they now run the bundle's own Java runtime directly, with the JVM options the launcher script applies, and pass each argument separately with no shell in between, so no shell can read %, &, $ or ; in an argument or path as a variable or a command.
    MOCKSERVER_JAVA_OPTS is split on whitespace with quoted text kept together, so -Dx="a b" sets x to a b on Linux and macOS too. A shell option passed in spawnOptions is now ignored.
  • The Python client's binary launcher no longer starts MockServer through a shell on Windows. start() ran the mockserver.bat launcher with shell=True, so cmd.exe could treat characters in the launcher path or in extra_args as commands rather than text. It now runs cmd.exe itself with
    every argument quoted, so characters such as &, | and ^ reach MockServer unchanged. start() raises ValueError if the launcher path or an extra_args entry contains a double quote, a line break or NUL, or if together they contain more than one %, which cmd.exe would expand as an
    environment variable. Linux and macOS are unchanged and still use no shell.
  • The Ruby client's binary launcher now quotes every argument it passes to cmd.exe on Windows. BinaryLauncher.start let Ruby quote the arguments for cmd.exe, which follows different rules, so characters in the launcher path or in extra_args could be read as commands. It now builds the
    cmd.exe command line itself and raises MockServer::Error if the launcher path or an extra_args entry contains ", <, >, |, &, a line break or NUL, or if together they contain more than one %. On Windows it needs a native Ruby (mswin or mingw, such as RubyInstaller). On Linux and
    macOS it now never uses a shell, even with no arguments.
  • The Go, Rust and .NET clients' binary launchers now quote the launcher path they pass to cmd.exe on Windows. They ran mockserver.bat through cmd.exe with the standard argument quoting, which cmd.exe does not follow, so characters in the launcher path (from MOCKSERVER_BINARY_CACHE or the
    user's cache folder) could be read as commands. Each now builds the cmd.exe command line itself, quoting every part, and refuses a launcher path that contains a double quote, a line break or NUL, or more than one %.
  • The PHP client's binary launcher now quotes every argument it passes to cmd.exe on Windows. BinaryLauncher::start() let PHP quote the launcher path and $extraArgs for cmd.exe, which follows different rules, so characters in them could be read as commands. It now builds the cmd.exe
    command line itself and throws BinaryInstallException if the launcher path or an extra argument contains a double quote, a line break or NUL, or if together they contain more than one %.
  • A long MOCKSERVER_BINARY_BASE_URL made of repeated / no longer takes the Node launcher seconds to process.
• Dependency security upgrades: Jackson 2.22.2 → 2.22.3 (three Snyk-reported vulnerabilities); dashboard dependency KaTeX 0.16.47 → 0.18 (low-severity prototype-pollution bypass of its trust restrictions); dashboard dependency dompurify resolves to 3.4.16 (DOM XSS via IN_PLACE sanitize with a
  node-removing hook, Dependabot alert 593); dashboard npm overrides pins lodash-es to 4.18.1 (_.template/_.unset/_.omit advisories; the affected functions are tree-shaken from the built dashboard anyway); the Node Testcontainers module's own development lockfile resolves newer undici,
  brace-expansion and @grpc/grpc-js (Dependabot alerts 581, 582, 584, 586, 591, 592 — the published package is unaffected, since it ships only dist).
• A zstd request or streamed compressed upstream response can no longer exhaust MockServer's memory. A zstd frame declares its decompressed size, and MockServer previously allocated that much up front (17 bytes claiming 1.5 GB threw OutOfMemoryError on a 256 MB heap) — now decompressed in
  64 KB pieces, with maxRequestBodySize/maxResponseBodySize enforced as for any other coding.
  • A streamed response (SSE and similar; on by default) was never body-size-limited at all, so a single network read's worth of compressed bytes could decompress to gigabytes (a 256 MB zstd stream, 8 KB on the wire, exhausted a 256 MB heap); such a stream is now capped at
    maxResponseBodySize (50 MB by default) of data waiting to be written to the client, ending incomplete past that point rather than looking finished.
  • A legitimate slow client is unaffected: MockServer reads more of the upstream only once the client has taken nearly all of what is waiting, so a slow client holds back the upstream rather than filling memory, and only a response that decompresses to nearly the limit or more from a single
    network read is stopped; the wait doesn't count towards streamIdleTimeoutSeconds (which now measures only an upstream that sends nothing while MockServer is reading it — a client that pauses keeps its stream, with at most the limit waiting for it, until it reads on, disconnects or takes
    nothing for responseWriteStallTimeoutMillis).
  • A stream that times out, or whose upstream closes, fails or sends invalid chunk framing part-way through, now ends incomplete, where before it ended with a normal final chunk and looked complete; a stream whose upstream simply ends by closing its connection still completes normally. When the
    client goes away, MockServer now also closes the upstream, where before it kept reading an endless stream forever.
  • A stream through a CONNECT tunnel is limited the same way, but by maxRequestBodySize (10 MB by default) — the limit that tunnel already applied to a response it collected whole, not maxResponseBodySize; through such a tunnel this backpressure is new for a streamed response, which before
    was queued in memory as fast as it arrived.
• A chunked HTTP/1.1 request can no longer make MockServer buffer an endless chunk-size line. Each chunk of a chunked request body starts with a line giving its size, which may carry extra parameters (chunk extensions), and the body may end with trailer headers. MockServer limited that line
  only by maxInitialLineLength and the trailers only by maxHeaderSize, which were both unlimited by default, so MockServer kept buffering a line its client never ended, up to 2 GB or until its network memory ran out. MockServer now answers 400 and closes the connection once more than 8 KB of
  one chunk-size line, or of the final 0 line and its trailers counted together, is waiting to be read, on requests sent to it directly and through a CONNECT or SOCKS tunnel. The limit is fixed: real uploads use about 100 bytes per line, and 8 KB is what Tomcat allows. Anything within the
  limit, the request line, headers and body sizes are unaffected, and a lower maxInitialLineLength or maxHeaderSize still applies. HTTP/2 and HTTP/3 have no chunk-size lines.
• The request line and headers of an HTTP/1.1 request are now limited by default, and a request MockServer cannot read is refused instead of answered. maxInitialLineLength (64 KB) and maxHeaderSize (256 KB) were previously unlimited; set either to 2147483647 to remove the limit. A longer
  request line now gets 414, larger headers 431, and any other unreadable request (an invalid header, a chunked body with an invalid chunk size) 400, with the connection then closed — where before such a request was logged as an ERROR and matched/answered from whatever had been read (a request
  line over the limit, for example, as GET /bad-request). This also applies through CONNECT/SOCKS tunnels. A request is also now unreadable, and gets 400, when the request before it on the same connection left bytes behind — for example a client that writes a GET body with neither
  Content-Length nor chunked encoding, as Node's http.request does — where it used to get 404 for GET /bad-request. HTTP/2 and HTTP/3 now take their header limit from maxHeaderSize too (see Changed); the limits apply only to requests MockServer receives — a mocked response with larger
  headers is still sent intact.
• A client can no longer make the server hold far more memory than the request it is sending. Over HTTP/2, small DATA frames mixed into a large read could pin up to ~6.7 GB across a connection's 100 streams at the default body-size limit; similarly for small HTTP/1.1 chunk-extension-padded chunks.
  Held network-read buffers are now copied once a request's retained pieces use less than half of the read they arrived in, cutting held memory 6× to over 2,000× in the cases measured.
• Control-plane mTLS now trusts and accepts only the configured CA chain, not MockServer's own CA as well (BREAKING; see Changed and Upgrading from 8.0.0). The Java client's callback and breakpoint WebSockets, which previously trusted any server certificate and presented no client certificate
  over TLS, now use the same trust and client-certificate settings as the client's HTTP requests.
• forwardProxyBlockPrivateNetworks now also blocks carrier-grade NAT addresses (100.64.0.0/10). This shared address range (RFC 6598) is used by carrier-grade NAT and by overlay networks such as Tailscale to reach machines that are not on the public internet, so with the setting on a forward
  or proxied request could still reach them. A target in that range, including written as an IPv4-mapped IPv6 address such as ::ffff:100.64.0.1, is now refused like a private-network address (with a 502 for HTTP); if you turn the setting on and forward to a Tailscale or other
  100.64.0.0/10 address on purpose, leave the setting off to keep those forwards working.
  • forwardProxyBlockPrivateNetworks now also applies to the MCP tools that send requests to a URL you give them. With the setting enabled, 8.0.0 let run_contract_test, run_resiliency_test and run_mcp_contract_test send requests to loopback, private-network and cloud-metadata addresses
    unchecked. Each tool now checks the URL's host before sending anything: a refused target is sent nothing, the tool returns an error naming the blocked address, and one warning is logged. Each request is checked again as it is sent, and with the setting enabled these tools no longer follow
    redirects, which could lead to an address that was never checked. A spec path that does not start with / is now always sent to the base URL's host.
  • forwardProxyBlockPrivateNetworks now checks the address MockServer actually connects to, and OpenAPI spec fetches. With the setting on, a forward, a proxied request, a webhook, a load scenario request, a drift alert or a WebSocket relay that MockServer connects to directly now goes to the
    exact address that passed the check, so a host name whose DNS answer changes between the check and the connection can no longer reach a blocked address. Every fetch of an OpenAPI spec from a URL (until now checked only for traffic validation), each remote $ref in a spec, and each redirect
    followed while fetching them are now checked too; a refused fetch makes the spec fail to load with a message naming the blocked address. Each MockServer applies its own setting to every spec it loads, so a server with the setting on in its own configuration checks them even when the global
    property is off; a spec loaded by a server with the setting off is fetched again, with the check, by a server that has it on. To see those fetches MockServer wraps the JVM's default ProxySelector the first time it loads a spec with the setting on; the wrapper stays for the life of the
    JVM, and a ProxySelector your code sets at the same moment can be lost, so set your own before MockServer loads a spec. A forward refused because the address looked up to connect to is blocked is neither retried nor counted by the forward circuit breaker.
  • forwardProxyBlockPrivateNetworks now also applies to requests MockServer sends itself. With the setting enabled, 8.0.0 still sent these to loopback, private-network and cloud-metadata addresses unchecked: before-action, after-action and step webhooks, load scenario requests, and drift alert
    webhooks. Each is now checked as a forward is, and a refused one is not sent and is logged once as a warning naming the blocked address. A refused blocking webhook with the FAIL_FAST failure policy makes the response a 502 Bad Gateway (with BEST_EFFORT the response goes ahead), a refused
    load scenario request is counted as a failed request of kind blocked (one warning for the run). proxyRemoteHost is checked although it is set in configuration, as it is for proxied requests; only the upstream proxies MockServer sends through (forwardHttpProxy, forwardHttpsProxy,
    forwardSocksProxy) are not checked.
  • forwardProxyBlockPrivateNetworks now applies to every forwarded and proxied request. With the setting enabled, 8.0.0 checked only httpForward actions. Overridden forwarded requests (forwardOverriddenRequest), class and object forward callbacks, binary forwarding, and requests that
    matched no expectation and were proxied on did not apply the check, so an expectation, or an unmatched proxied request, could reach loopback, private-network and cloud-metadata addresses. All of them now apply it, as forward actions do: an HTTP request gets 502 Bad Gateway, a binary
    connection is closed, and a warning names the blocked address. A request sent through forwardHttpProxy also has its Host header checked, as that proxy is sent it as the address to go to. With the setting enabled, a request that matches no expectation and whose Host header names MockServer
    itself by a name it does not recognise as its own (a Docker Compose or Kubernetes service name, for example) now gets 502 Bad Gateway and a warning instead of 404 Not Found, because that name resolves to a private address — see Upgrading from 8.0.0.
• Configuration changes made through PUT /mockserver/configuration now take effect for every way of starting MockServer, and all at once. A server started without a configuration object (command line, Docker, Maven plugin) previously held two copies of its configuration, so a PUT that reported
  success (including enabling control-plane authentication, or lowering maxLogEntries/maxEventLogSizeInBytes, or enabling redactSecretsInLog) left request handling on the old, insecure or unenforced values; settings given at startup, and servers started through ClientAndServer, the JUnit
  integrations or Spring, were not affected. A PUT that changes authentication or TLS settings is now also applied atomically: control-plane authentication/authorization and the server TLS settings (tlsMutualAuthenticationRequired and its certificate chain) switch from all-old to all-new with
  nothing in between — closing a sub-millisecond window where a PUT switching from mTLS to JWT/OIDC could briefly require no authentication at all, or a TLS connection opened mid-change could keep using the old setup. A rejected PUT (an invalid certificate path, a negative
  globalResponseDelayMillis) now answers 400 having changed nothing, where fields ahead of the invalid one used to stay applied. An MCP tool call is now also authorized with the settings it was authenticated with, rather than possibly a later PUT's. Outbound TLS connections now cache their TLS
  setup only under the exact settings it was built from, so a PUT changing forwardProxyTLSX509CertificatesTrustManagerType mid-build can no longer leave a stale trust-all setup cached under the old settings; turning http2Enabled off at runtime now also stops outbound TLS connections offering
  HTTP/2.
• redactSecretsInLog now masks credentials everywhere the event log is shown or retrieved, including the console/retrieved curl rendering of a proxied or forwarded request, JSON log message/arguments/expectation fields, the separate cookie list, HAR and format=CURL exports, match-failure
  explanations, error log entries, failed response verifications, and — newly — the bytes of a binary (non-HTTP) message in a "matched"/"didn't match" log entry (shown as ***REDACTED***, where the "received binary request" message already masked them); redactSecretsInRecordedExpectations now also
  masks cookie values. Masking now applies even to entries recorded before the setting was switched on, since redaction happens when an entry is shown or retrieved, not when it's written; what's not retroactively fixed is anything captured by MockServer before this release — treat logs, exports
  and recordings captured pre-upgrade as still containing those values in full.
• /mockserver/generateExpectation and LLM drift analysis now redact credentials from the prompt sent to an external LLM backend, unconditionally — sensitive headers, credential-shaped query parameters and JSON fields, OAuth codes, JWT-shaped tokens, and embedded URL credentials are replaced with
  ***REDACTED*** before the prompt leaves MockServer, independent of redactSecretsInLog. The same unconditional redaction covers the new narration field on PUT /mockserver/explain/explainUnmatched (see Added): credential values are masked whether or not redactSecretsInLog is on. The
  explain_request, explainUnmatched and other MCP/REST diagnostic output, by contrast, is redacted the same way the event log is — i.e. only when redactSecretsInLog is enabled — except diagnose_config, which always masks credential values. Treat any credentials sent through
  generateExpectation/drift analysis with a backend configured as previously exposed to that LLM service.

Added

• AI-assisted debugging: ask MockServer why a request matched or didn't, fix near-misses, and dry-run templates — via REST, the dashboard and new MCP tools.
  • Ask why one request matched the expectation it did, and why a higher-priority one lost: PUT /mockserver/explain?correlationId=<id>. Give it the correlation ID of a recorded request (from PUT /mockserver/retrieve?type=LOGS&format=LOG_ENTRIES or the dashboard) and MockServer checks that
    request again against your current expectations, in the order it evaluates them. The answer names the expectation that would serve the request now, gives a reason for every expectation checked before it (different fields; another namespace; used up or expired; waiting for another scenario
    state; served only a percentage of the time; LLM conversation mismatch; a not(...) request matcher that excludes the request), lists lower-priority expectations that also match but are never reached, and reports how the request was handled when it arrived, including, when MockServer forwarded
    the request and the forward failed with a 502, the expectation that forwarded it (or that it was proxied without one) and the reason the forward failed. At most 500 expectations are checked per call. The route has no bare /explain alias, so a mock of your own on PUT /explain keeps working.
    In the dashboard, every group of log messages for a request has an Explain button that shows the same answer, and the Java client has a typed explain(correlationId) method returning a RequestExplanation.
  • AI assistants can now ask MockServer why a request matched the expectation it did, and which settings are in effect, through two new MCP tools. explain_request takes the correlation ID of a request MockServer has received and returns the same answer as PUT /mockserver/explain. An unknown
    or evicted correlation ID comes back as a tool error. diagnose_config lists the configuration settings changed from their default, with the value and where each came from (system property, properties file, environment variable or runtime setter), or looks up one setting by name in any form
    (maxExpectations, mockserver.maxExpectations, MOCKSERVER_MAX_EXPECTATIONS or max-expectations), showing a setting at its default with the default's value, and suggests the setting you probably meant when nothing matches. It also lists each mockserver.* / MOCKSERVER_* key you set
    that MockServer does not recognise, with the setting it was probably meant to be (by name only, never its value). Both are read-only, so a principal with only the READ role can call them when control-plane authorization is on. Their output is redacted: diagnose_config always masks
    credentials, and explain_request masks credentials quoted from your traffic when redactSecretsInLog is enabled, as the event log does.
  • Every client can now ask why a request matched, or did not, and get a typed answer back. The JavaScript (Node), Python, Ruby, Go, Rust, .NET and PHP clients gain typed explain, debugMismatch and explainUnmatched calls (explain, debug_mismatch and explain_unmatched in Python, Ruby and
    Rust; Explain, DebugMismatch and ExplainUnmatched in Go and .NET, which also has Async versions), joining the Java client's typed explain. explain takes the
    correlation ID of a recorded request and returns which expectation would serve it now, why each expectation checked before it was passed over, which lower-priority ones it hides, and how the request was handled when it arrived; debugMismatch compares a request you describe with every active
    expectation, field by field; explainUnmatched lists the closest expectations for recent unmatched requests, optionally with a suggested JSON patch for each. An unknown or evicted correlation ID fails with the server's reason.
  • Fix an almost-matching expectation from the dashboard's Explain Unmatched view. Next to each close expectation, Preview Fix shows the smallest change that would make it match the unmatched request (for example the path, one header's value, or one field of a JSON body) and the request
    matcher before and after; Apply Fix updates the expectation only when you select it, and refuses if anything it would change was edited in the meantime. Over REST, add "suggestFixes": true to PUT /mockserver/explainUnmatched to get each suggestion as a standard JSON Patch. Values the
    log redacts, and bodies the log kept only part of, are never copied into a fix.
  • Find expectations that can never match before you debug a 404: expectation lint. PUT /mockserver/lint checks your active expectations, or the expectations you send in the body without storing them, and mockserver lint expectations.json checks files with no server running. It reports an
    expectation that another one evaluated earlier always matches first (shadowed), times, timeToLive or percentage of 0, a path without a leading /, a misspelt method or header name, and STRICT JSON matching of a body with arrays, among other checks. Creating expectations with PUT /mockserver/expectation now runs the quick per-expectation checks too: the expectations are still stored, and any problems are counted in an x-mockserver-lint-warnings response header and logged as a WARN. Expectations loaded from an initializationJsonPath file are checked too, each
    time the file loads. Lint is advisory and never rejects an expectation. In the dashboard, a Lint button on the Active Expectations panel lists the findings with their severity, rule and message.
  • AI assistants can now ask MockServer why a forward failed, how to fix a near-miss expectation, which expectations can never match, and what a template renders, through four new MCP tools: explain_forward_failure, suggest_expectation_fix (the same guarded JSON Patch as
    explainUnmatched's "suggestFixes": true), lint_expectations (returning at most maxIssues issues, default 100), and test_template. The first three are read-only, so a principal with only the READ role can call them when control-plane authorization is on; test_template runs the
    template code it is sent, so, like its REST endpoint, it needs the mutate role. Output is redacted as the event log is when redactSecretsInLog is enabled, and a forward failure's reason is cut at 2,048 characters.
  • Try a response or forward template without creating an expectation: PUT /mockserver/template/test. Send a Velocity, Mustache or JavaScript template and an optional sample request, and MockServer renders it with the same engines, security settings and time limits it uses when serving. It
    returns the rendered response (or the request, for a forward template), or the reason it failed with the line and column in your template. Output that is not a valid response comes back with what is wrong with it and the raw text; serving it would answer with a 500 (a 404, or a 502 for a
    forward template, with templateFailureAsServerError=false). Warnings point to each Velocity reference that did not resolve, to each Mustache variable that did not resolve and so rendered as empty text, and to each scenario.set(...) call, which a dry run reports rather than applies; a dry
    run never changes scenario state or appears in the event log. A JavaScript or
    Velocity template is always stopped after its time limit, even when that limit is 0 (then after 5 seconds); a Mustache template, or a Velocity template busy inside one long Java call, cannot be stopped, so the dry run answers once the limit plus 5 seconds has passed; at most two dry runs run
    at once, and a third gets a 429. When control-plane authorisation is on, a dry run needs the mutate role. The route has no bare /template/test alias, so a mock of your own on that path keeps working.
  • A failing JavaScript template now says where in your template it failed. GraalJS counts lines from the wrapper MockServer puts around your template, so a syntax error named a line two below the real one. The error in the log now ends with at template line 2, column 29, counted from your
    template's first line, and a hint when the cause is an undefined variable, a field read from a missing value, or an unclosed bracket or quote. Velocity and Mustache errors already gave the line, and are unchanged.
  • PUT /mockserver/explain and PUT /mockserver/explainUnmatched can add a plain-language summary from your own LLM. When the new llmExplainNarrationEnabled property is on (default false), a runtime LLM backend is configured (llmProvider, or a provider API-key environment variable)
    and the caller adds ?narrate=true, the response gains a narration field, labelled as AI-generated, beside the unchanged deterministic explanation. A backend configured for other features is not enough on its own, and nothing is sent while a request is being served. Credential values from
    the request and your expectations are replaced with ***REDACTED*** before the explanation leaves MockServer, whether or not redactSecretsInLog is on. The call runs off the request thread and is bounded by llmRequestTimeoutMillis plus two seconds. When narration is turned off, no backend
    is configured, the LLM fails or times out, or two summaries are already running, narration says why it is unavailable instead of returning an error.
  • Three more built-in MCP prompts walk your assistant through the commonest failures. why_did_verify_fail, fix_my_expectation and why_forward_failed tell your own assistant which MockServer tools to call, in which order, and what each result means; MockServer still calls no language
    model for these three. fix_my_expectation changes an expectation only after you agree, and replaces it in place, starting from the fix MockServer suggests with suggest_expectation_fix; why_forward_failed starts from the reason explain_forward_failure reports, falling back to comparing
    fields or reading the logs only when MockServer has no fix, cannot name the cause or recorded no failed forward.
• MySQL, Redis, PostgreSQL and length-prefixed binary protocols can now be framed and matched as whole messages, and binary proxying gained several capabilities. binaryMessageFraming (default RAW, unchanged) now also takes MYSQL, REDIS, POSTGRESQL and LENGTH_PREFIX (the last configured
  via binaryMessageLengthPrefixBytes (1, 2, 4 or 8, default 4), binaryMessageLengthPrefixByteOrder (default BIG_ENDIAN), binaryMessageLengthPrefixOffset (bytes before the field, default 0) and binaryMessageLengthIncludesPrefix (whether the length counts the whole message, default
  false), which fits protocols such as Thrift's framed transport, MongoDB's wire protocol and DNS over TCP. As with POSTGRESQL, a message may be at most maxRequestBodySize bytes, a connection that declares a longer one or sends bytes the framing does not allow is closed, and an unrecognised
  value set as a property is logged once and read as the default. To proxy MySQL, whose server speaks first, also set forwardBinaryServerFirstWaitMillis on a connection with a forward target (port forwarding, transparent proxy or PROXY protocol); mocking MySQL with no upstream server is not
  possible, as MockServer cannot send the server's greeting. A TLS handshake on a MySQL connection is recognised only straight after an SSLRequest.
  • A binary expectation on a proxied PostgreSQL connection can now forward the message too, and drop or replace the server's reply. Set the binary response's new upstream field (Java: binaryResponse(bytes).withUpstream(BinaryResponse.Upstream....)): ANSWER_ONLY (the default, unchanged)
    answers and does not forward; ANSWER_AND_FORWARD answers, forwards the
    message so the real server still sees it, and drops the server's reply; FORWARD_AND_REPLACE forwards the message and writes the binary response in place of the server's reply once that reply has ended (with a delay, the server's later replies wait behind it, so the client gets them in
    order). Both need matchBinaryExpectationsWhenProxying (on by default) and binaryMessageFraming set to POSTGRESQL, which tells MockServer where a reply ends; without that framing the expectation answers as ANSWER_ONLY and one warning is logged per connection. The field is in the JSON schema,
    the OpenAPI spec and every client library.
  • A protocol in which the server speaks first, such as MySQL, SMTP or FTP, can now be proxied, with the new forwardBinaryServerFirstWaitMillis. Set it (for example to 250) and a port-forwarded, transparently proxied or PROXY-protocol connection whose client sends nothing for that long is
    taken as binary: MockServer opens its upstream connection and relays the greeting, and the rest of the session. It is off (0) by default, because a client that opens a connection and sends HTTP only after the wait would then be relayed to the upstream rather than matched against your
    expectations.
  • A binaryProxyListener can be told what the upstream server sends unprompted: the new onUpstreamMessage method is called for every read from the upstream server that is not a message's response — bytes it sent unprompted, and the rest of a response that arrived in more than one read. It
    is a default method that does nothing, so existing listeners, lambdas included, are unaffected and are not called for these reads. A listener that overrides it and falls more than 64 calls behind slows the upstream server down, except while a message is waiting for its response.
  • Separately, matchBinaryExpectationsWhenProxying (on by default; set false to always forward) lets a binary expectation answer some messages on an otherwise-proxied connection relayed on one upstream connection, matched only when its bytes equal the expectation's exactly, so a test can use a real server for most
    of a session and fake one part of it, such as a canned result for one PostgreSQL query. The upstream never sees an answered message, so the canned reply must suit the session's real state.
• A configuration setting you have changed now shows the built-in default it replaced. --print-config ends the setting's line with (default: ...), GET /mockserver/config and the MCP diagnose_config tool add a default field, and the dashboard's Server Info tab shows the default beside
  the value. A default worked out from the JVM heap size, such as maxExpectations, shows the value worked out now. A credential's default is always shown as ***REDACTED***, and default is left out when MockServer cannot work it out.
  • --print-config, GET /mockserver/config and the dashboard's Server Info tab also now list the configuration MockServer ignored: after the properties in effect they list each unrecognised mockserver.* / MOCKSERVER_* key with its suggested correction (name only, never the value it was set
    to), and GET /mockserver/config?nonDefault=true lists only the properties not at their built-in default, which is everything you have changed. A property at its built-in default now shows that default's value instead of (default); a default worked out from another property, such as
    ringBufferSize, shows the value worked out now. Credentials are still shown only as ***REDACTED***, including at their default.
  • Eight new event-log gauges on /mockserver/metrics: four for the in-flight ring (mock_server_event_log_ring_occupancy, _ring_capacity, _in_flight_bytes, _max_in_flight_bytes) and four for the retained deque (mock_server_event_log_retained_entries, _retained_bytes,
    _max_retained_entries, _max_retained_bytes).
  • Expectation-store and accept-queue metrics: mock_server_expectations_bytes reports live memory held by the store; mock_server_max_expectations_bytes the byte budget in force (0 when maxExpectationsSizeInBytes is off); mock_server_expectations_byte_evicted_total counts byte-driven
    evictions. mock_server_accept_queue_backlog_configured reports the configured accept-queue depth; on Linux, mock_server_accept_queue_backlog_effective reports the kernel-capped value.
  • New JVM-level metrics: jvm_runtime_info (gauge, always 1, reports the running JVM/GC in labels), jvm_memory_allocated_bytes (a monotonic gauge of cumulative bytes allocated across all threads), jvm_buffer_pool_used_bytes/jvm_buffer_pool_used_buffers (NIO buffer pools), and
    netty_direct_memory_used_bytes (Netty's own direct-memory tracking).
  • Two new histograms: mock_server_request_read_to_decode_duration_seconds (from MockServer reading the first bytes of a request to it having decoded the headers) and mock_server_request_transport_duration_seconds (from reading a request's headers to the last byte of its response being
    written, including delays — unlike the existing mock_server_request_duration_seconds, which stops when a response is handed off for writing).
  • mock_server_inbound_connections_open, mock_server_inbound_connections_rejected_total and mock_server_inbound_connections_idle_closed_total (see maxInboundConnections below).
  • mock_server_scheduler_queued_tasks and mock_server_template_action_queued_tasks show the depth of the action and template-render queues, which are deliberately not limited because their work must not be dropped.
• New safety limits for stored expectations, pending work and connections, each configurable and each off or generous by default. maxExpectationsSizeInBytes (default 0 = off) caps stored-expectation memory by byte budget alongside the existing maxExpectations count.
  maxPendingDelayedResponses and maxQueuedTemplateActions (both sized from heap, capped at 100,000, or 1,000 when the JVM reports no heap limit; 0 restores the old unbounded behaviour) bound requests waiting on a delay or a template thread, answering 503 Service Unavailable with Retry-After: 1 past the limit instead of growing memory without bound (a refused request still counts as a match; delayed side actions are dropped, not refused, once their own equal-sized budget is full; a forwarded response skips its chaos latency rather than being refused); delayed WebSocket replies get the
  same budget, closing the WebSocket with status 1013 (Try Again Later) once full, and reads pause at 128 waiting replies per connection (a fixed constant, no setting) so a fast-sending client is slowed by TCP flow control instead of growing memory; reply frames are now sent strictly in delay order.
  maxInboundConnections (default 0 = no limit) caps open client connections: a connection beyond the limit is reset at once instead of being accepted, a warning is logged at most every 10 seconds, and new connections are accepted again as soon as one closes. A CONNECT/SOCKS tunnel to MockServer
  itself uses two slots, and if its second is refused the client now gets a 502 instead of waiting forever. mockserver.soBacklog (default 1024, previously hard-coded) makes the TCP accept-queue depth configurable; the effective depth is still capped by the kernel (net.core.somaxconn on
  Linux, kern.ipc.somaxconn on macOS).
• New Linux-only standalone jars and an HTTP/3 Docker image variant. -jar-with-dependencies-linux-x86_64.jar and -jar-with-dependencies-linux-aarch_64.jar are ~13 MB smaller by carrying only their own architecture's natives. mockserver/mockserver:<version>-http3 (also
  mockserver-<version>-http3, latest-http3, and snapshot-http3/mockserver-snapshot-http3 for master builds; Helm image.variant=http3) is the standard image plus the QUIC native, needed to actually serve HTTP/3 (see Upgrading from 8.0.0).
• Dashboard: template dry-run, log-history tuning, and status-ranged breakpoints. The Mocks view's response/forward template steps gain a Test Template button (see above). The dashboard WebSocket now accepts ?logLimit=N (up to 500, default 100) for more log/request rows per update. The
  Breakpoints form gains Min status/Max status fields and a status: scope-box syntax, limited to the Response phase.
• A template error body now gives the template line and column and a hint for common mistakes, when the engine gives them, following the engine's error message, so a template bug is easy to tell apart from a request that matched no expectation (see the BREAKING 500-by-default entry under
  Changed for the response shape and migration).
• A byte budget for memory the OpenAI Responses API mock keeps for previous_response_id/GET /v1/responses/{id} (maxOpenAiResponsesSizeInBytes, default a twentieth of the heap; 0 limits by count only).
• A startup warning for each insecure default a future major release will change (forwardProxyBlockPrivateNetworks to become true, localBoundIP to become 127.0.0.1, attemptToProxyIfNoMatchingExpectation to become false, and the HTTP parsing limits
  maxInitialLineLength/maxHeaderSize/maxChunkSize to become 8192/16384/16384 bytes), once per JVM; setting the property yourself silences its warning, so you can choose now and not be surprised when the defaults change. No default changes in this release. Misspelt mockserver.*/MOCKSERVER_* properties now get a "did you mean" suggestion at startup, in the
  form you used (MOCKSERVER_METRICS_ENABLE suggests MOCKSERVER_METRICS_ENABLED, mockserver.max_expectations suggests mockserver.maxExpectations), naming the property only, never the value (see the --print-config/GET /mockserver/config sub-bullet above for where else ignored keys and
  defaults are listed).
• A failed verification now ends with a short summary of what MockServer actually saw (detailedVerificationFailures, default on): the expected vs. actual count, the closest non-matching requests/responses with their differing fields, and — for a sequence — which step failed. The block is
  appended, so code that checks the start of the message is unaffected; set detailedVerificationFailures=false to drop it.
• Client parity: conditional matchers and per-step load checks. The Python, Go, .NET, Rust and PHP clients can now build a conditional (if/then/else) request matcher and read one back: Python adds ConditionalRequestDefinition (if_request, then_request, else_request, not_condition); Go
  adds If/Then/Else to HttpRequest with ConditionalRequest(...); .NET adds If/Then/Else with HttpRequest.RequestIf(...); Rust and PHP add HttpRequest::conditional(...); the .NET, Rust and PHP request matchers also gain the OpenAPI fields (specUrlOrPayload, operationId,
  contextPathPrefix) a branch can use. The same five clients' load-scenario steps now take per-step checks (LoadCheck: source, headerName, jsonPath, comparator, value, named in each language's style) and a checks list; Go, .NET and Rust also gain a typed CHECK_FAILURE_RATE
  threshold metric, and Rust's LoadStep gains name(...)/label(key, value) and LoadScenario gains label(key, value) (see the "Every client can now ask why a request matched" sub-bullet above for the explain/debugMismatch/explainUnmatched parity).
• Website: a symptom-first Troubleshooting Index, linking a visible symptom (404, forward 502, failed TLS handshake, empty dashboard, LLM mock shape mismatch, container won't start, etc.) to the exact diagnostic to use, and a new "Throughput by hardware size" section on performance.html showing
  healthy/peak request rate, latency and request-history retention from 1 core/512 MB up to 6 cores/2 GB, driven by four load generators per size so the test measures MockServer rather than the generator.
• The DNS port MockServer chose can now be read from every embedded API, not just MockServer.getDnsPort() and the start-up log: also ClientAndServer.getDnsPort() (including on the ClientAndServer the JUnit 5 extension injects), MockServerRule.getDnsPort(), the Spring listener's
  ${mockServerDnsPort} placeholder and @MockServerDnsPort annotation, and the dnsPort field of PUT /mockserver/status's answer (each gives -1, or the field is left out, while DNS mocking is off). @MockServerTest now also accepts mockserver.dnsEnabled and mockserver.dnsPort.

Changed

• BREAKING: binary (non-HTTP) proxying now keeps one upstream connection for a client's whole life; forwarding one message per upstream connection, and forwardBinaryRequestsWithoutWaitingForResponse with it, are removed. The upstream now sees one connection per client connection, held open
  as long as the client's is: everything it sends reaches the client, closing its connection closes the client's too, and a clien

[!IMPORTANT]
✂ PR body was truncated to here.

---

Configuration

📅 Schedule: (UTC)

• Branch creation
  • At any time (no schedule defined)
• Automerge
  • At any time (no schedule defined)

🚦 Automerge: Enabled.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.