Improve and extend Secure Session API docs #380
Conversation
Write module-level docs based on description on Wiki. Describe API flavors of Secure Session and update the method descriptions as well.
Rename the constructor to just "new()" and make it panic instead of returning a Result. There are no user-preventable errors which can be avoided to not cause a panic. A construction failure usually means either an out-of-memory condition, or some serious failure in Secure Session invariants or crypto backend usage by Secure Session. We'd better abort in this case. As you can see in the tests, we never handle the error and just expect the construction to always succeed. The user will not get any value out of error checks like that.
Group callback API and buffer-oriented API together in rustdoc output. This makes navigation a bit easier.
Use the same naming as other language wrappers do: - connect_request, wrap, unwrap for buffer-oriented API - connect, send, receive for callback API Other wrappers do not have a separate method for negotiation so we have to invent something here. Keep the naming consistent.
Replace explicit templates with impl Trait which makes code a bit easier to read.
why panic? usually, secure session will be created in runtime (not at compile time). how users can to handle errors from constructor without abort of program? |
|
@Lagovas, I have decided to use panics to not bother users with errors which they are unlikely to be able to handle in any meaningful way. Rust wrapper uses Rust type system to prevent a number of errors possible with the underlying C API:
It is not possible for the user of Secure Session to compile a program which passes invalid arguments to the constructor. Basically, the only errors that left are:
OOM is (currently) indicated by panics in Rust and there is no way to handle it. The other two cases are programming bugs in Secure Session. The users of Secure Session cannot handle these conditions. There is no meaningful action to perform for an error indication returned from the constructor other than cease usage of Secure Session in the whole application. |
|
It turns out that I was mistaken about errors during Secure Session construction. There is one possible error which is not prevented by the type system: the client ID must be non-empty. Therefore I'll (partially) revert the commit which replaced Result with panic. The constructor will still return a Result. |
This partially reverts commit aa4b50b. It turned out that Secure Sesssion construction can fail due to preventable errors. On of them is invalid client ID which must be non-empty. Revert back to returning an Err instead of panicking, but keep the new name of the constructor.
Secure Session is not able to negotiate connection if the client ID is empty so do an early check and return an error to the user if the provided client ID is invalid. Using expect_err() with Result revealed tha SecureSession does not have a Debug impl. All public types should have one so invent something.
I'm closing in on the API of Secure Session which looks okay for me. This PR adds more information on how to use Secure Session to API docs, and updates the interface. You can view the docs by running
Some notable changes:
SecureSession::new()and it panics instead of returning a Resultconnect,negotiate,send,receiveconnect_request,negotiate_reply,wrap,unwrapThe docs currently refer to nonexistent examples of Secure Session usage. They are currently cooking in a separate branch and will be added later in a separate pull request.