Feature Request: Matchable errors for jwt.Token.Get

[MB175]

Feature Request: Matchable errors for jwt.Token.Get

Abstract

In lestrrat-go/jwx/jwt, methods like Token.Get(name, dst) return generic errors with messages such as:

return fmt.Errorf("field %q not found", name)
return fmt.Errorf("failed to assign value to dst: %w", err)

This makes it hard for users to differentiate between a missing claim, a type conversion failure, or other errors. The proposal is to introduce matchable errors (sentinels or typed errors) for clearer, idiomatic handling.

Proposed solution

Introduce exported sentinel errors:

var (
    ErrFieldNotFound = errors.New("field not found")
    ErrAssignFailed  = errors.New("failed to assign value")
)

Update Get to wrap them:

if t.claims[name] == nil {
    return fmt.Errorf("%w: %q", ErrFieldNotFound, name)
}
if err := blackmagic.AssignIfCompatible(dst, t.claims[name]); err != nil {
    return fmt.Errorf("%w: %w", ErrAssignFailed, err)
}

Alternatively, use typed errors:

type FieldNotFoundError struct {
    Field string
}
func (e FieldNotFoundError) Error() string {
    return fmt.Sprintf("field %q not found", e.Field)
}

Example usage:

var fnf jwt.FieldNotFoundError
if errors.As(err, &fnf) {
    log.Printf("missing claim: %s", fnf.Field)
}

[lestrrat]

@MB175 Is it imperative that you can access the field name from the error object? I'm trying my hardest not to introduce user-visible API on these objects, and would rather have you use them as an opaque errors. Your final example would just be:

err := tok.Get(....)
if errors.Is(err, jwt.ClaimNotFoundError()) {
   log.Printf("missing claim: %s", err) // `missing claim: field "..." not found`
}

[lestrrat]

@MB175 Also, when you say "Get and similar methods" which methods are you talking about?

[lestrrat]

@MB175 I made a PR. Please take a look if this is what you wanted.

[MB175]

@lestrrat thanks a lot for the super quick implementation, Get is enough for my use case!

I’m curious though, earlier you mentioned you wanted to avoid exposing user-visible API on the error objects and keep them opaque. What made you decide to add the errors in the end?

[lestrrat]

@MB175 By opaque, I meant that you (the user) can't access anything in the error. So for my library something like os.PathError is a no-no, because I'd have to expose (1) its concrete type, and (2) its exported fields. The current implementation adds errors, yes, but you can't do anything (like access its fields) with them other than treat them as generic error objects

[MB175]

@lestrrat ah okay that makes total sense. I’m happy with the new implementation you did, since it lets me reliably distinguish between an assign error and a missing field. Thanks a lot for the super quick addition.

Issue can be closed.

[lestrrat]

FYI I'll merge this soon, but please note that it won't be released for at least a few days, if not longer, as I tend to find something that needs to be fixed only after the dust settles. If you are in a hurry, please use the commit ID to pin the dependency.