error redesign?

[rorycl]

Hi @mnako

Thanks very much for the useful library, which I used to parse a lot of .eml files on disk that other libraries wouldn't handle.

One issue I had is that some of those .eml files had invalid reply-to entries, for example

cannot parse headers: letters.parsers.parseHeaders: cannot parse Reply-To header:
   letters.parsers.parseAddressListHeader:
      cannot parse address list header "Vodafone": mail: missing '@' or angle-addr

I had to wrap that error and check the err.Error() string contents to skip this particular error. Maybe that is fine, but it might be worth considering making a set of sentinel errors for different error cases so that the user of the library can catch those errors more easily.

Perhaps something like this:

    var ErrHeaderParseNonFatal error = errors.New("header parse non-fatal error")
    
    decodedHeader, err := decodeHeader(normalizedS)
    if err != nil {
        return addresses, errors.Join(
             fmt.Errorf("letters.parsers.parseAddressListHeader: cannot decode address list header %q: %w",
            s,  err),
            ErrHeaderParseNonFatal,
            )
    }

This will allow using errors.Is to detect non-fatal errors.

Alternatively, using an error struct to report the error type and details would also be good, which would allow catching with errors.As.

It might also be good if the parser took options allowing the user to ignore errors for certain non-critical issues.

[rorycl]

Thinking about this further I wonder if a combination of sentinel and struct ("object") errors might work ok for the sort of "error but continue when not fatal" situation I've been trying to describe.

For example, and with reference to https://stackoverflow.com/a/72308155, maybe something like this could work?

package main

import (
    "errors"
    "fmt"
)

// HeaderError reports error details
type HeaderError struct {
    detail string
}

// Error fulfills the error interface
func (s HeaderError) Error() string {
    return s.detail
}

// ErrorHeaderUnparseable is a sentinel error
var ErrHeaderUnparseable error = errors.New("sentinel unparseable error")

// generate errors
func errorGenerator() error {
    err := HeaderError{
        detail: "struct system unavailable",
    }
    return errors.Join(ErrHeaderUnparseable, err)
}

func main() {
    err := errorGenerator()
    // catch sentinel error
    if errors.Is(err, ErrHeaderUnparseable) {
        fmt.Println("got ErrHeaderUnparseable")
    }
    // catch struct error
    var syserr HeaderError
    if errors.As(err, &syserr) {
        fmt.Println("got HeaderError")
    }
    // report error
    fmt.Printf("error:\n%s", err)
}

This gives:

got ErrHeaderUnparseable
got HeaderError
error:
sentinel unparseable error
struct system unavailable

The sentinel error could be used for coarse-grained error catching, for example for Address parsing, while the struct errors could give the context and details for more precise error reporting.