docs: add TCP half-close broken pipe to common errors

[mikemorris]

Adds an entry to common-errors.html.md describing the context for a broken pipe error when attempting to close a snapshot RPC connection.

This was previously noted in relation to Docker support in consul-containers.html.md, but that page is no longer accessible in the public website documentation.

consul/agent/consul/snapshot_endpoint.go

Lines 224 to 234 in d86efb8

	// Our RPC protocol requires support for a half-close in order to signal
	// the other side that they are done reading the stream, since we don't
	// know the size in advance. This saves us from having to buffer just to
	// calculate the size.
	if hc != nil {
	if err := hc.CloseWrite(); err != nil {
	return nil, fmt.Errorf("failed to half close snapshot connection: %v", err)
	}
	} else {
	return nil, fmt.Errorf("snapshot connection requires half-close support")
	}

Questions

• Should this note be more specific about this behavior occurring during RPC calls from a non-RAFT-leader snapshot leader to the RAFT leader?
• Should this note mention using tcpdump or Wireshark for further insight into the actual TCP messages sent and received?

[hashicorp-cla]

All committers have signed the CLA.

[banks]

Good catch and update - I'm not sure I even knew we had a "common errors" page!

Should this note be more specific about this behavior occurring during RPC calls from a non-RAFT-leader snapshot leader to the RAFT leader?

I think this is OK as is but we could mention that it will only appear on servers. In practice people are likely only here if they've seen it already and it does a good job of explaining to them what is happening and that it's fine.

Should this note mention using tcpdump or Wireshark for further insight into the actual TCP messages sent and received?

I'd suggest not - in production it will all be encrypted anyway and if it's not then you are going to see the entire contents of the state store on the wire as the snapshot is sent. It's hard to know what they could learn from that that we haven't said here.

[mikemorris]

I think this is OK as is but we could mention that it will only appear on servers.

It seems like it could occur on a non-server agent if consul snapshot agent happens to be running there and obtain snapshot leadership? (Guessing this might not be a recommended setup?)

It's hard to know what they could learn from that that we haven't said here.

It would primarily be to observe TCP headers and see the response to an initial FIN from server - whether client ACKs or immediately FIN and close in response, but agree this is likely unnecessary to include here.