Document NIOSSLError.uncleanShutdown

[weissi]

The docs for NIOSSLError.uncleanShutdown are non-existent today. But understanding when uncleanShutdown is and when it's not a security issue (truncation attack) is quite important. So I think we should document it.

This contains some information: swift-server/async-http-client#238 (comment)

---

Particularly interesting would be examples of protocols where this matters and where it doesn't. E.g.

• HTTP/2: safe to ignore (always framed)
• WebSocket: safe to ignore (always framed)
• HTTP/1.1 with content-length or chunked encoding: safe to ignore (framed)
• HTTP/1 with EOF framing: NOT safe to ignore
• ...

[glbrntt]

I wonder if, as an extension to this, NIOSSL shouldn't emit the error if it knows via ALPN that an unclean shutdown is safe. That might just boil down to "is this h2" though.

[Lukasa]

I suspect that might be a bit too clever. Certainly adding some documentation would be very helpful.