In MockServer, what does connectionOptions().withCloseSocket(true) do to a bid reply?

## A reply that arrives, and a connection that does not survive it There are two quite different ways a stub server can be hostile. It can refuse to answer at all, or it can answer perfectly well and then take the connection away. `ConnectionOptions.withCloseSocket(true)` is MockServer's expression of the second. The bid reply is written in full — status code, headers, body — the client parses it successfully, and only then is the socket closed rather than left available for the next call. That distinction matters because it decides which client code you are testing. A client that never gets a reply exercises its exception handlers. A client that gets a good reply and then finds the connection gone exercises everything *after* a successful parse, plus whatever it does when it next tries to use that connection. ## Where ConnectionOptions attaches `ConnectionOptions` is not an action and cannot stand alone. It is a property of an `HttpResponse`, attached with `response().withConnectionOptions(connectionOptions()...)`, produced by the static factory `connectionOptions()`. Everything it can do therefore presupposes a reply that is being written. This single structural fact answers most questions people have about the class: - it cannot express "write nothing", because there is always a reply; - it cannot be used with `error(...)`, because an error action has no `HttpResponse` to decorate; - it takes effect after matching, at the moment the reply is serialised onto the socket. ## The eight settings, and what each family does `ConnectionOptions` has exactly eight `with*` settings, and they fall into three groups: - **How the length is declared** — `withSuppressContentLengthHeader`, `withContentLengthHeaderOverride`. - **How the reply is written out** — `withSuppressConnectionHeader`, `withChunkSize`, `withChunkDelay`, `withKeepAliveOverride`. - **Whether the connection survives** — `withCloseSocket`, `withCloseSocketDelay`. Only the last pair takes the connection away. The other six change what the client reads or how the bytes are framed, but leave it with something it can read to the end. If a colleague expects `withSuppressConnectionHeader(true)` to break a connection, that is the misunderstanding to correct: suppressing a header changes what the reply advertises, not what the socket does. ## withCloseSocket versus withDropConnection These two are constantly confused, and they are not on the same class. | call | class | reply written? | client sees | |---|---|---|---| | `withCloseSocket(true)` | `ConnectionOptions` | yes, in full | a good reply, then a dead connection | | `withDropConnection(true)` | `HttpError` | no | no bytes at all; a transport failure | The rule of thumb is simple: if a status code should still reach the client, you want `ConnectionOptions`; if it should not, you want `HttpError`. Anyone hunting for `withDropConnection` among the eight settings above will not find it, and that absence is by design rather than an oversight. ## When a cattle-auction test wants this shape Some realistic reasons to reach for `withCloseSocket(true)` on `GET /auctions/v1/lots/48/bids/current`: 1. The bidding client keeps connections around between polls, and you want the next poll to discover the connection is unusable rather than the current one to fail. 2. You are testing code that runs *after* a successful response — a cache write, a state transition, an event emitted — and you want to confirm it still happens when the connection is subsequently lost. 3. You want a failure the client's status handling cannot see, without giving up the ability to assert on the body that arrived first. In all three cases a dropped connection would be the wrong tool, because it destroys the reply you are relying on. ## The mistake to avoid, and how to write it so nobody makes it The single most common error is reaching for the wrong class, and it is easy to avoid by naming the class in the code and in the review comment: write `ConnectionOptions.withCloseSocket(true)` and `HttpError.withDropConnection(true)` in prose rather than the bare method names. The names are similar, both are genuine MockServer identifiers, and a search that only asks whether a method exists will happily approve a sentence that attaches it to the wrong class. For orientation, WireMock has no equivalent split: its transport failures all arrive through one decoration on the reply builder, `aResponse().withFault(...)`, so a reviewer moving between the two servers should expect the shape to change, not just the spelling.