it's hard to figure out when a connection has been truncated

The TLS specification defines the close_notify alert “in order to avoid a truncation attack”. This is to say, if you have a protocol which says something like

DELETE FROM USERS

sometimes it's really, really important that you also include the last part of the connection

WHERE USER = 'hax0r';

because the meaning of the message is significantly different if all you get is the first half.

Therefore it is very important to effectively communicate the distinction between “received an authoritative, signed close_notify” and “the connection disappeared, I don’t know what happened”. The recent PR, #225, addressed one such failure mode when calling shutdown, but you can notice the underlying connection has disappeared in recv, or in do_handshake, or in send, and probably in a couple of other places I’m not remembering right now, and it may look like any one of a number of random I/O errors.

However, at some point, you should always be shutting down the connection. Right now, shutdown documents 2 return codes: False, for “you might need to check some future error codes”, and True, for “the connection was properly shut down”.

In the actually implemented behavior, there is a third, undocumented option, of “raise an OpenSSL.SSL.Error indicating some I/O failure” which, depending on context, but always in BIO mode, means “the connection was truncated”. You can also get an OpenSSL.SSL.WantRead, which means that you’ve called shutdown once, but your peer has not yet replied one way or another yet, and you’re in non-blocking mode.

There should be a clearly specified third option which unambiguously means “the connection was truncated”; possibly just raising a new error type, “Truncated”, to indicate that the connection has definitely been truncated without a close_notify.

Start by reading the existing shutdown behavior and its documented return codes, then trace how recv, do_handshake, send, and BIO mode expose OpenSSL.SSL.Error or OpenSSL.SSL.WantRead. Compare those paths with the close_notify distinction described here. Done means truncated connections are communicated through a clearly specified, unambiguous API outcome across the relevant paths.