proposal: errors/errd: helper package for deferred error handlers

[rsc]

The try proposal (#32437) uses a placeholder fmt.HandleErrorf to annotate errors.
We do not intend that to be the actual function name. It was a blank to be filled in.
Here is one possible way to fill in that blank.

// Package errd provides error-handling functions.
// All of them are meant to be deferred,
// with the address of the function's error result
// as the first argument. For example:
//
//	defer errd.Trace(&err)
//
// All of the functions take action only when err != nil
// (meaning the function in which the defer appears is
// itself returning a non-nil error); they are no-ops when err == nil.
package errd // import "errors/errd"

// Trace prints the error and the current goroutine's stack trace.
// It does nothing when *errp == nil.
//
// Example:
//
//	defer errd.Trace(&err)
//
func Trace(errp *error)

// Apply applies the function f to the error (*errp = f(*errp)).
// It does nothing when *errp == nil.
//
// Example:
//
//	defer errd.Apply(&err, func(err error) error {
//		if err == io.EOF {
//			err = io.ErrUnexpectedEOF
//		}
//	})
//
func Apply(errp *error, f func(err error) error)

// Add adds context to the error.
// The result cannot be unwrapped to recover the original error.
// It does nothing when *errp == nil.
//
// Example:
//
//	defer errd.Add(&err, "copy %s %s", src, dst)
//
// This example is equivalent to:
//
//	defer errd.Apply(&err, func(err error) error {
//		err = fmt.Errorf("copy %s %s: %v", src, dst)
//	})
//
// See Wrap for an equivalent function that allows
// the result to be unwrapped.
func Add(errp *error, format string, args ...interface{})

// Wrap adds context to the error and allows
// unwrapping the result to recover the original error.
//
// Example:
//
//	defer errd.Wrap(&err, "copy %s %s", src, dst)
//
// This example is equivalent to:
//
//	defer errd.Apply(&err, func(err error) error {
//		err = fmt.Errorf("copy %s %s: %w", src, dst)
//	})
//
// See Add for an equivalent function that does not allow
// the result to be unwrapped.
func Wrap(errp *error, format string, args ...interface{})

Thoughts and improvements welcome.

/cc @mpvl @jba @neild

[thepudds]

errd.Tracef might be natural as well, or having the current errd.Trace also take format string, args ...interface{}.

[cespare]

I don't think Apply carries its weight. (It seems helpful here largely to describe how Add and Wrap work.)

The example code isn't quite right; I think you meant:

defer errd.Apply(&err, func(err error) error {
	if err == io.EOF {
		return io.ErrUnexpectedEOF
	}
	return err
})

But if I were going to do that, I would instead write

defer func() {
	// Don't even need a specific nil check in this case.
	if err == io.EOF {
		err = io.ErrUnexpectedEOF
	}
}()

That is clearer and faster: it only need refer to the single err variable; it doesn't need the err != nil check at all since it only cares about io.EOF; it only involves a single function call instead of two; it's lighter on the page; and so on.

If you had a more complicated function to apply, it seems fine to just make it take a *error and do the if *err == nil { return } check itself:

func f() (err error) {
	defer errd.Apply(&err, complexFunc1)
	defer complexFunc2(&err)
	 // ...
}

func complexFunc1(err error) error {
	// lots of stuff
	return err
}

func complexFunc2(errp *error) {
	if *errp == nil {
		return
	}
	// lots of stuff
}

The version without Apply isn't obviously better here, as above, but it's not clearly worse either.

[cespare]

This is probably too bike-shed-y at this early phase, but I wonder if there is a better name than Trace since the concept of "trace" has an unrelated antecedent in the Go library and runtime. Perhaps:

• Print
• Stack
• Dump
• Examine
• Debug

[sonatard]

Following two sample codes missing err in last argument.

//	defer errd.Apply(&err, func(err error) error {
//		err = fmt.Errorf("copy %s %s: %v", src, dst)
//	})

//	defer errd.Apply(&err, func(err error) error {
//		err = fmt.Errorf("copy %s %s: %w", src, dst)
//	})

[eandre]

Thanks @rsc, this looks great to me. Personally this addresses the only remaining concern I had with the main try proposal, which was around how to make it convenient to "do the right thing" with adding context to errors.

[beoran]

Whether or not try() is going to be implemented, this errd package is a great idea, because, I have to admit, that after thinking about it, using defer for error handlers makes sense in many cases, as long as performance is not critical.

Unlike @cespare I think the errd.Apply() is a great idea because it allows to define named and resuable error handlers in advance and then just pass them to errd.Apply(), without having to define an inline lambda. A few common use cases could have predefined error handlers in the standard library. For example, to close a file on an error, we could have a method func (f File) CloseErr(err error) error, which closes the file if err is not nil, and then we could do defer errd.Apply(file.CloseErr) . The CloseErr function could then be implemented for every standard library type that has a Close(), to encourage this pattern.

One use case which seems to be missing is logging the error using the log package. I think and errd.Log() function could be very useful.

However, I think there is one way that would make this even more useful and that would be to make it a "fluid" API, a bit like this:

package errd // import "errors/errd"

type errd  * error

func New(err * error) errd {
   return errd(err)
}

func (e errd) Trace() errd 
func (e errd) Log() errd
func (e errd) Logf(fmt string, args...interface{}) errd
func (e errd) Apply( f func(err error) error) errd
func (e errd) Add(errp *error, format string, args ...interface{}) errd
func (e errd) Wrap(errp *error, format string, args ...interface{}) errd

Then we can easily compose error handlers like this:
defer errd.New(&err).Log().Add("%s", "some context").Handle(file.CloseErr)

[johanbrandhorst]

What is the rationale for the name? errors/errd doesn't say anything to me. Is it supposed to be short for error-defer? What about something like errors/deferred instead? Could still be aliased to errd if deferred isn't an obvious namespace.

[DisposaBoy]

I personally like the idea of try(f(), handler) more, but my only concern with this proposal is the introduction of a new package when we already have the errors helper package.

[mikeschinkel]

Simple question as I am obviously missing something. Why a pointer to error when error is already an interface?

Also, does errd mean "ERRor Defer?" Being able to read abbreviations as if not abbreviated always helps me reason about code.

[jba]

Why do you feel the need for a separate package, rather than putting these in errors? (Aside from the implementation detail of accessing formatting.)

I don't see why Trace is here. It has a few problems:

• It's generally a mistake to both print an error and return it. That typically leads to multiple output lines per error, creating log spam.
• Where does Trace print to? Stdout? Stderr? The log? I usually log errors when I print them, but a command-line tool might prefer stderr. If this package is only going to have one function for this, I don't see an obvious best choice.
• Printing the full stack trace will likely lead to duplicate traces, since the error is being returned up the stack where other Trace calls can get ahold of it. Consider printing just the current frame.

Shouldn't the two formatting functions end in f?

I've seen the name Annotatef for what you're calling Add. That is a bit long, but Notef isn't, and pairs nicely with Wrapf.

[beoran]

I made a quick hack and the results are interesting:

https://gitlab.com/beoran/errd

So now I can handle an error with where closer has a Close method like this:
defer errd.New(&err).Add("closer %v", closer).Close(closer).Log().Do()
The Do() was neccesary to avoid having to wrap everything in a func(){} block. Perhaps even that could be avoided by chaining lambdas in stead of structs. But for the rest, the power is amazing. :)

The potential is limitless, there could even be .If(), .Switch(), so the error handling could get as complex as I would like it to be. But I guess not everyone likes method chaining, so maybe it's better that this remains an alternate package, much like how we have std lib log and logrus.

[rsc]

@jba, I would expect everything in errors to be about errors and not about error pointers. Putting the deferrables in their own package lets them have a different name space. I think that solves one of the big naming problems we had with clunkers like fmt.HandleErrorf.