New Error Constructors: code.Error(msg) and code.Errorf(msg, a...)

[marioizquierdo]

Build Twirp Errors from the Code

The standard error constructor twirp.NewError(twirp.ErrorCode, msg) stutters and is a bit verbose.

Since the code constants are already defined at the top level of the twirp package, they can be used to build all the error types. It is easier to read and consistent for all codes:

twirp.Internal.Error("oops")
twirp.NotFound.Error("resource not found")
twirp.PermissionDenied.Error("thou shall no pass")

Errorf to format and wrap other errors

The signature Errorf is a well-known idiom in Go and could be used to format errors exactly as it would be expected:

twirp.Internal.Errorf("oops: %w", err) // wrapping another error
twirp.NotFound.Errorf("resource with id: %d", id) // interpolation
twirp.PermissionDenied.Errorf("user %q with id %d not allowed: %w", login, id, err) // all of the above

Wrapping errors with "%w" is specially useful to prefix internal errors. APIs that use middleware to report errors often need to unwrap those errors to know the originals, but having a prefix in front of them is useful for debugging. Example:

record, err := s.DB.LoadRecord(ctx, resourceID)
if err != nil {
    return nil, twirp.Internal.Errorf("failed to load resource %q: %w", resourceID, err)
}

Existing constructors enhanced

Existing constructors still apply and are consistent with the new ones. An Errorf version of those constructors was also added for consistency.

twirp.InternalError("oops")
twirp.InternalErrorf("oops: %w", err)
twirp.InternalErrorWith(err)

twirp.NotFoundError("resource not found")
twirp.NewError(twirp.NotFound, "resource not found")

twirp.InvalidArgumentError("arg", "is invalid")
twirp.InvalidArgument.Error("arg is invalid").WithMeta("argument", "arg")
twirp.NewError(twirp.InvalidArgument, "arg is invalid").WithMeta("argument", "arg")

Usage Example

Let's see how the new constructors look like on an example endpoint implementation:

func (s *MyService) MyMethod(ctx context.Context, req *mysvc.MyRequest) (*mysvc.MyResponse, error) {
  if req.UserId == "" {
    return nil, twirp.InvalidArgument.Error("user_id is required")
  }
  
  user, err := s.DB.LoadUser(ctx, req.UserId)
  if err != nil {
    return nil, twirp.Internal.Errorf("failed to load user %q: %w", req.UserId, err)
  }
  if user == nil {
    return nil, twirp.NotFound.Errorf("user %q not found", req.UserId)
  }

  if !auth.Check(ctx, req.UserId) {
    return nil, twirp.PermissionDenied.Error("authorization check")
  }

  return &mysvc.MyResponse{UserName: user.Name}, nil
}

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[wmatveyenko]

Thanks for the contribution.