ssl: Refactor to avoid confusion of what is the API #6565
Conversation
CT Test Results 2 files 64 suites 44m 40s ⏱️ Results for commit 82a4931. ♻️ This comment has been updated with latest results. To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass. See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally. Artifacts// Erlang/OTP Github Action Bot |
8b0656e to
4e0d1e3
Compare
|
I rewrote it to be behavior compatible even if it was not documented. Although I still do not want to specify all possible error reasons as they should never be matched and can not be reliably specified. Some errors are partially documented with special atoms that may be matched, but they are documented by the functions returning them and not here. |
kikofernandez
left a comment
There was a problem hiding this comment.
I have one comment to consider about the typing.
I think we need to start thinking if we want to have more explicit and verbose types or types that work because they are possibly quite general, so we over-specify.
Verbosity comes at the price of longer documentation, and over-specification comes at the price of leaving users to have to dig into the source code to understand what can be expected.
Choose your poison :)
lib/ssl/src/ssl.erl
Outdated
|
|
||
| %%--------------------------------------------------------------- | ||
| -spec format_error({error, Reason}) -> string() when | ||
| -spec format_error({error, Reason} | Reason) -> string() when |
There was a problem hiding this comment.
I think the type is semantically correct but maybe too general?
Essentially, as a user who has never used this function, I would need to read the source code to see what I can put as input argument. I am not sure if this is the intended case. If not, I think the following type specs could "help", although they are a bit verbose:
-spec format_error({error, ErrorReason} | Reason) -> string() when
Reason :: string()
| closed
| {tls_alert, {_, Description :: string()}}
| {options, Options :: term()}
| {options, {socket_options, Option :: term()}}
| {options, {socket_options, Option :: term(), Error}}
| {options, {FileType, File :: string(), Error}}
| InetError,
FileType :: cacertfile | certfile | keyfile | dhfile,
Error :: {error, ErrorReason} | ErrorReason,
InetError :: inet:posix()| system_limit,
ErrorReason :: term().and also:
-spec do_format_error( string()
| closed
| {tls_alert, {_, Description :: string()}}
| {options, Options :: term()}
| {options, {socket_options, Option :: term()}}
| {options, {socket_options, Option :: term(), Error}}
| {options, {FileType, File :: string(), Error}}
| InetError) -> string()
when
FileType :: cacertfile | certfile | keyfile | dhfile,
Error :: {error, ErrorReason} | ErrorReason,
ErrorReason :: term(),
InetError :: inet:posix() | system_limit.There was a problem hiding this comment.
Well, the purpose of this function is for the user to be able to provide a logging string from any error reason returned by any of the ssl API functions that may return {error, Reason}. For a legacy reason, the input can even be the tagged error tuple. The whole point is that the user should not need to know what the error looks like but they want something that they can print in an error log. The reason may for instance include stack trace information for debugging purposes. The user will never need to create the input, it should be a matched Reason. We might want to spec the internal function for our own benefit, but I think that the documented value should be general.
4e0d1e3 to
b9e6008
Compare
Add reason without tag for backwards comparability even though it was not documented! Closes erlang#6506
b9e6008 to
82a4931
Compare
Closes #6506