In MockServer, which class carries withDropConnection, and why is it not on ConnectionOptions?

## What a broken connection is, and why it is not a status code A stubbed status code, however unusual, still arrives as a well-formed HTTP message. The client's parser succeeds, a response object exists, and the branch that runs is the one that inspects a code. A broken connection produces no such object at all: the client's HTTP library raises whatever it raises for a socket that died, and the code that runs is the exception handler — the retry guard, the fallback, the circuit breaker. Those are usually written by different people at different times from the status-handling code, and only a transport-level surface reaches them. That is exactly why MockServer models a broken connection as a separate **action** rather than as a strange kind of response: it genuinely is a different thing happening. ## An expectation is a matcher plus exactly one action Every MockServer expectation is assembled the same way. `when(<request matcher>)` selects the traffic, and the chain it returns is completed by **one** action: - `respond(HttpResponse)` writes a real HTTP reply — status code, headers, body. - `forward(...)` sends the request onward to another host. - `error(HttpError)` acts on the transport underneath the reply; nothing HTTP is written. - the callback forms hand the request to your own code. That structure decides where the connection-breaking controls can live. "Drop the connection" is not a property of a reply, because in that case there is no reply. ## HttpError carries withDropConnection The class is `HttpError` and its static factory is `error()`. Its surface is small and worth memorising: - `error()` — the factory that starts one - `withDropConnection(Boolean)` — write nothing, tear the socket down - `withResponseBytes(byte[])` — write exactly these bytes, then close - `withStreamError(long)`, `withStreamError(StreamErrorCode)` and `withStreamErrorCodeName(String)` So a cattle-auction bid endpoint that must die on the wire is written as `client.when(request().withMethod("POST").withPath("/auctions/v1/lots/48/bids")).error(error().withDropConnection(true))`. The request still matches; it is the answer that never happens. ## ConnectionOptions decorates a reply that exists `ConnectionOptions` is a property of an `HttpResponse`, attached with `response().withConnectionOptions(connectionOptions()...)`. Because it can only exist beside a reply that is being written, it cannot express "write nothing". Its complete set of settings is eight: - `withSuppressContentLengthHeader` - `withContentLengthHeaderOverride` - `withSuppressConnectionHeader` - `withChunkSize` - `withChunkDelay` - `withKeepAliveOverride` - `withCloseSocket` - `withCloseSocketDelay` `withDropConnection` is **not** in that list, and looking for it there is the commonest mistake made about this API. What `ConnectionOptions` does offer is `withCloseSocket(true)`: the reply is written in full and the socket is then closed rather than left available, with `withCloseSocketDelay` governing when that close lands relative to the reply. ## The probability form lives on a third class There is a probabilistic variant, and it is on neither class above: `withDropConnectionProbability(Double)` belongs to `HttpChaosProfile`. This deserves saying out loud, because it is a correction to a correction. People who learn that `withDropConnection` is not on `ConnectionOptions` very often move the probability method onto `HttpError` in the same breath, and that is wrong too. | MockServer class | connection control | what the client sees | |---|---|---| | `HttpError` | `withDropConnection(true)` | no bytes at all; the socket dies | | `HttpError` | `withResponseBytes(byte[])` | your bytes, then a close | | `ConnectionOptions` | `withCloseSocket(true)` | the full reply, then a dead connection | | `HttpChaosProfile` | `withDropConnectionProbability(...)` | a proportion of connections dropped | ## Choosing the right surface, and naming it correctly 1. If the bidding client must take its transport-failure branch — the code that runs when there is no response object — use `error().withDropConnection(true)`. 2. If it must parse a valid bid response and only then find the connection gone, use `response().withConnectionOptions(connectionOptions().withCloseSocket(true))`. 3. If it must read something that is not valid HTTP at all, use `error().withResponseBytes(...)`. Both `withDropConnection` and `withCloseSocket` are real MockServer identifiers, so a search that only asks whether a name exists cannot tell a correct sentence from an incorrect one — only the class named beside the method carries the fact. The trap runs across products too: in WireMock the equivalent control is a decoration on the reply builder, `aResponse().withFault(Fault.CONNECTION_RESET_BY_PEER)`, so a snippet copied from one server to the other is not merely differently spelled, it is differently shaped. Name the class as well as the method — `HttpError.withDropConnection(true)`, `ConnectionOptions.withCloseSocket(true)` — and the ambiguity disappears from your code review as well as from your answer.