[bindings] Include errno in errors

[lrstewart]

Resolved issues:

resolves #3400
resolves #3390

Description of changes:

I added errno to all of our s2n-tls Errors, and used that information to turn ErrorType::IOErrors into more useful std::io::Errors.

I could have only added errno to a new Error::IO variant, but in the past the value of errno has sometimes been useful when debugging other error types. Not usually though: only ErrorType::IOError actually promises that errno will be useful. If folks think it might be more confusing than useful, I can remove it.

Call-outs:

I also made some minor documentation updates and fixed a spacing error that annoyed me while I was trying to verify that relying on errno with IOErrors was at least reasonable.

Testing:

I wrote some unit tests to verify the conversion. I also intentionally caused tests to fail and checked that various errors looked reasonable when printed.

IO error:

Error: Error { code: 67108864, name: "S2N_ERR_IO", message: "underlying I/O operation failed, check system errno", kind: IOError, debug: "Error encountered in lib/stuffer/s2n_stuffer_text.c:70", errno: "Socket operation on non-socket" }

Other errors ("errno" field is present, but not meaningful):

Error: Error { code: 335544320, name: "S2N_ERR_ENCRYPT", message: "error encrypting data", kind: ProtocolError, debug: "Error encountered in lib/stuffer/s2n_stuffer_text.c:70", errno: "Operation now in progress" }
Error: Error { code: 34, name: "Internal s2n error", message: "Internal s2n error", kind: NoError, debug: "Error encountered in lib/stuffer/s2n_stuffer_text.c:70", errno: "Resource temporarily unavailable" }
Error: Error { name: "InvalidInput", message: "A parameter was incorrect" }

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[camshaft]

I'm not sure we should have Errno as part of our public API. It might be better to do a new type around both s2n_status_code::Type and Errno, just so we're protected from breaking changes.

[lrstewart]

After some discussion, decided that no details of Error should be public.

So we'll make one breaking change to avoid future breaking changes. Error is now an opaque struct wrapping the original enum, hiding the implementation details. I also gave InvalidInput a kind() (UsageError) so that it can be treated like other errors, and added a source() to more explicitly preserve the original distinction between the two enum variants.

[toidiu]

since we are pre 1.0 why not just change this?

[lrstewart]

I plan to, but in a separate PR. It's a lot of find and replace that would confuse the diff.

[toidiu]

nice, this makes more sense. does it also make sense to add/keep

If the application calls [poll_shutdown] before this method reports "0", then an error will occur.

[lrstewart]

Nope, because that's not true anymore :) I added a check to poll_shutdown a while back so that it returns Pending instead. The error was because that's how the underlying C shutdown method behaves, but now we don't call that method if it would fail due to blinding. I just forgot to update the documentation.