v1.0 Roadmap - consolidate built-in wrappers and implement API and DX improvements.

[Southclaws]

It's been about a year that this library has been in production use in multiple real-world revenue-generating products and I've got a good handle on the improvements I want to make and the direction this library is taking.

So, to mark this, I'd like to bundle the existing wrappers into a single package for a few reasons:

• remove the individual packages: fctx, fmsg, ftag and combine them into one
• introduce all the improvements listed in
  • Support arbitrary value type in fctx metadata #38
    • you'll be able to pass anything as a value, like stdlib slog.
  • Play nicely with multierror libraries #9
    • multi-error libraries will no longer cause confusion when unwrapping trees of errors
  • Support Unwrap for multiple errors #25
    • add support for the new Go standard Unwrap() []error interface
  • Redesign fmsg to be less verbose and more useful. #32
    • the "fmsg" (Fault message) library will only be concerned with end-user messages, not fmt.Errorf style internal messages
  • Pass ...Wrapper list to New constructor  #31
    • No more Wrap(New(...), wrappers...) just New("msg", wrappers...) 🥳
• settle on the API designs for v1 and commit to compatibility going forward

I'd like to use a single nice short package name for all the built-in wrappers, I'm thinking of just fault/f or fault/w. Mostly just for aesthetics, similar to how Zap and other log aggregators work:

Settled on wrap for context, tags and user-friendly error message reference wrappers

return fault.Wrap(err,
        wrap.Ctx(ctx),
        wrap.Tag(fault.TagNotFound),
        wrap.Msg("There was a technical error while retrieving your account"),
)

Previous ideas:

return fault.Wrap(err,
        f.WithCtx(ctx), // decorate the error with key-value metadata from context
        f.WithTag(ftag.NotFound), // categorise the error as a "not found"
        f.WithMsg("There was a technical error while retrieving your account"), // provide an end-user message
)

Or with:

return fault.Wrap(err,
        with.Ctx(ctx), // decorate the error with key-value metadata from context
        with.Tag(ftag.NotFound), // categorise the error as a "not found"
        with.Msg("There was a technical error while retrieving your account"), // provide an end-user message
)

Or just w

toqueteos pointed out this would be a bad idea as single letter symbols are often used for variable and parameter names.

return fault.Wrap(err,
        w.Ctx(ctx), // decorate the error with key-value metadata from context
        w.Tag(ftag.NotFound), // categorise the error as a "not found"
        w.Msg("There was a technical error while retrieving your account"), // provide an end-user message
)

Any ideas for this are welcome though! cc @matdurand @the-goodies @semihbkgr @toqueteos (just tagging folks who have contributed in case you have ideas or reservations around this!)

[toqueteos]

Hi! Thanks for the ping

I'd advise against single letter imports as those are usually taken by variables (n for counters, f for *os.File handles, w for io.Writers, i for loops, ...).

Why not just go all-in and get rid of the subpackage entirely? Just create some functional options that may or not be passed into fault.Wrap(err, ...).

Example:

return fault.Wrap(err,
        fault.WithCtx(ctx), // decorate the error with key-value metadata from context
        fault.WithTag(fault.TagNotFound), // categorise the error as a "not found"
        fault.WithMsg("There was a technical error while retrieving your account"), // provide an end-user message
)

fault is almost there already, it's a matter of just moving some code up to the root.

This would only increase the API surface from 7 to 10+ symbols + the leftover types from those subpackages that are needed (like ftag.Kind and the consts over there).

[Southclaws]

One of the main reasons I wanted to keep the wrappers separate was to emphasise that Fault itself is standalone and the real value it provides is the func (error) error interface - on which you can build your own wrappers specific to your organisation or product. That's the fundamental sell of Fault as a library, then the wrappers like fctx/ftag are effectively reference implementations or examples of how to implement them as such.

I agree with the single letter point though, that's something I didn't consider!

Brevity has its pros and cons, too short and the meaning is lost, too long and it becomes arduous to use and read.

Perhaps wrap is a logical package name for these:

return fault.Wrap(err,
        wrap.Ctx(ctx),
        wrap.Tag(fault.TagNotFound),
        wrap.Msg("There was a technical error while retrieving your account"),
)

[matdurand]

Just my 2 cents, but if we're talking about 1.0 then I would consider the following. fmsg and ftag are packages used to store metadata about errors. There is obviously other types of metadata, for example, in my project, I basically copied ftag to make an ErrorCode concept that my http error handler is using to produce a response.

It seems to me that we could provide more generic version of ftag and fmsg, called for example fmeta to enable to storage of any metadata types on top of errors. Then we could rewrite ftag and even fmsg using this generic fmeta package. Obviously we would probably need to involve golang Generics at this point.

I feel it would provide far greater possibility for customizing fault for specific use cases.

If you think this is something worth pursuing, I could give it a try and come up with a first draft an a possible API and we could iterate on it.

[josephbuchma]

@Southclaws I have forked fault into https://github.com/flourishsoftware/libfault and added an API to allow using fault as a "backend" for your own errors package. It definitely needs some polish, but I believe providing such API is a step in the right direction, and it aligns very well with your own rationale (from readme):

The reason Fault came into existence was because I found nesting calls to various Wrap APIs was really awkward to write and read. The Golang errors ecosystem is diverse but unfortunately, composing together many small error related tools remains awkward due to the simple yet difficult to extend patterns set by the Golang standard library and popular error packages.

I like the flexibility of Wrapper pattern, but I would personally rather avoid having multiple packages like fmsg, fctx, ftag etc, especially if we don't even need some of them in our project. On the other hand, we do have some custom Wrappers that we need, and I'd like all of those to be in a single package we own, which makes the API very easy to use.

Our internal "fault" Wrap func has following signature:

func Wrap(err error, opts ...erropt.Wrapper) error

This makes it very easy and intuitive to use, as all the "wrappers" are in the erropt package, and you are getting autocomplete right away for free, without having to remember the fmsg, ftag and so on.