Removing function names from errors (PR 9058)

[Richard Levitte]

On Thu, 13 Jun 2019 11:16:38 +0200,
Matt Caswell wrote:
> 
> I agree with everything Richard just said. I just have some additional thoughts
> inserted below.
> 
> On 13/06/2019 10:00, Richard Levitte wrote:
> > If we look at it from the perspective of the application author,
> > what's most often needed are reliable error/reason codes (to check and
> > to react appropriatly to) and associated reason strings (for display).
> > For the application author, it would normally be completely
> > uninteresting exactly which function the error happened in (think
> > about it, when's the last time you wanted to know exactly which
> > internal function in libc raised the EAGAIN you just got?).  For the
> > application author, the interesting bit is usually "what went wrong?"
> > (reason) and "what did I call?" (they already know that).
> > 
> > 
> > If we look at *our* needs as library writers, then the exact location
> > that raised the error is interesting, of course!  But then, is it
> > interesting in the form of codes, or are we rather interested in the
> > text form?  I dunno about you, but I don't give a damn about the
> > actual library and function codes, I look at the displayed library
> > names and function names.  (and yet, they aren't necessarily enough
> > without knowing the OpenSSL version).
> > 
> > 
> > Finally, if we look at it from a provider author's perspective,
> > dealing with all these different codes is quite hard.  Ideally, a
> > provider author should just need to deal with their own reason codes
> > and associated strings, and that's about it.
> 
> I think you missed another important perspective, i.e. that of the end user.
> 
> Note that this is slightly different to the needs of the application author. An
> application author will typically do one of two things if an error occurs:
> 
> 1) Try and figure out the cause of the error and recover from it, e.g. if I get
> reason code x then I'll retry the operation with slightly different parameters
> but if I get y then I'll just ignore this failure and carry on anyway.
> 
> or
> 
> 2) If its an error they don't know how to handle then give up and display
> whatever error details are available to the end user (or log them, or whatever)
> 
> So the application author is going to want a small number of reason codes that
> they can handle. If its not in the small set they know about, then give up.
> 
> The end user OTOH doesn't care about reason codes at all and wants as detailed
> an explanation of the error (in text form) as is possible. Potentially that
> might mean different text for every point in the code where we raise an error.
> Ideally they might want information about the context that led up to the error,
> i.e. what particular operation was being attempted at the time. I'm thinking
> that there is some relationship here between the information available from the
> trace API, and the error API.

Good point, but note that there is no conflict with what I wrote.  The
additional information you're talking about is something we currently
provide the ERR_add_error_data() function for, and that together with
the reason text (derived from the reason code) is the data the end
user can reasonably get.  It's up to whoever writes the error raising
code to provide enough useful information.

Incidently, I did mention thinking about a new (better, I hope) error
raising function on github, and might as well repeat it here:

    int ERR_raise_error(int reason, const char *fmt, ...);

To allow for debugging information (like I mentioned, some sensible
combination of __FILE__, __LINE__, __FUNC__, and possibly git commit
id), one might imagine this:

    int ERR_add_debug_info(const char *file, size_t line,
                           const char *func, const char *commitid);

or a combo of both:

    int ERR_raise_error_debug(int reason,
                              const char *file, size_t line,
                              const char *func, const char *commitid,
                              const char *fmt, ...);

Note that this doesn't have to conflict with the current error raising
code, all we need to do is to convert whatever input ERR_put_error()
gets into the new form.

Cheers,
Richard

-- 
Richard Levitte         levitte at openssl.org
OpenSSL Project         http://www.openssl.org/~levitte/