Handle custom status code mappings for routing errors (#2101)

* Handle custom status code mappings for routing errors

Not all gRPC error codes and http status codes can have a one to one
mapping. Http can have both a path and a method component, while gRPC
will just have a function that is specific to the combination of method
and path when translating between the two. That means that for gRPC a
missing function simply means "unimplemented", while for the equivalent
REST API it is common to distinguish an unhandled method request on a
known resource as "Method Not Allowed" with the response code 405.

This may not be the only place where expectations of response codes
needed may not align with what is provided by the current mapping
chain http.Status* -> gRPC code.Codes -> http.Status*, where some
information may be lost in the double conversion.

As the error handler accepts an 'error' interface, it should be possible
to provide a custom error structure that can contain the http Status
code to wrap the original error to allow for the expected response code
to be provided without impacting the current function signatures.

* update with goimports

* Restore DefaultRoutingErrorHandler and tests, and update doc strings

Remove the customization from the DefaultRoutingErrorHandler as this is
what should be done by consumers, consequently remove the modifications
to tests affected.

Update doc strings as requested.

* Rename StatusHTTP to HTTPStatus

* Update names and docstrings

* Update customizing your gateway docs

* rework example

* remove newline

Author: electrofelix

docs/docs/mapping/customizing_your_gateway.md

@@ -358,3 +358,31 @@ HTTP statuses and their mappings to gRPC statuses:
 - HTTP `400 Bad Request` -> gRPC `3 INVALID_ARGUMENT`
 
 This method is not used outside of the initial routing.
+
+### Customizing Routing Errors
+
+If you want to retain HTTP `405 Method Not Allowed` instead of allowing it to be converted to the equivalent of the gRPC `12 UNIMPLEMENTED`, which is  HTTP `501 Not Implmented` you can use the following example:
+
+```go
+func handleRoutingError(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, r *http.Request, httpStatus int) {
+	if httpStatus != http.StatusMethodNotAllowed {
+		runtime.DefaultRoutingErrorHandler(ctx, mux, marshaler, writer, request, httpStatus)
+		return
+	}
+
+	// Use HTTPStatusError to customize the DefaultHTTPErrorHandler status code
+	err := &HTTPStatusError{
+		HTTPStatus: httpStatus
+		Err:        status.Error(codes.Unimplemented, http.StatusText(httpStatus))
+	}
+
+	runtime.DefaultHTTPErrorHandler(ctx, mux, marshaler, w , r, err)
+}
+```
+
+To use this routing error handler, construct the mux as follows:
+```go
+mux := runtime.NewServeMux(
+	runtime.WithRoutingErrorHandler(handleRoutingError),
+)
+```

runtime/errors.go

@@ -2,6 +2,7 @@ package runtime
 
 import (
 	"context"
+	"errors"
 	"io"
 	"net/http"
 	"strings"
@@ -20,6 +21,17 @@ type StreamErrorHandlerFunc func(context.Context, error) *status.Status
 // RoutingErrorHandlerFunc is the signature used to configure error handling for routing errors.
 type RoutingErrorHandlerFunc func(context.Context, *ServeMux, Marshaler, http.ResponseWriter, *http.Request, int)
 
+// HTTPStatusError is the error to use when needing to provide a different HTTP status code for an error
+// passed to the DefaultRoutingErrorHandler.
+type HTTPStatusError struct {
+	HTTPStatus int
+	Err        error
+}
+
+func (e *HTTPStatusError) Error() string {
+	return e.Err.Error()
+}
+
 // HTTPStatusFromCode converts a gRPC error code into the corresponding HTTP response status.
 // See: https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
 func HTTPStatusFromCode(code codes.Code) int {
@@ -72,13 +84,22 @@ func HTTPError(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.R
 
 // DefaultHTTPErrorHandler is the default error handler.
 // If "err" is a gRPC Status, the function replies with the status code mapped by HTTPStatusFromCode.
+// If "err" is a HTTPStatusError, the function replies with the status code provide by that struct. This is
+// intended to allow passing through of specific statuses via the function set via WithRoutingErrorHandler
+// for the ServeMux constructor to handle edge cases which the standard mappings in HTTPStatusFromCode
+// are insufficient for.
 // If otherwise, it replies with http.StatusInternalServerError.
 //
 // The response body written by this function is a Status message marshaled by the Marshaler.
 func DefaultHTTPErrorHandler(ctx context.Context, mux *ServeMux, marshaler Marshaler, w http.ResponseWriter, r *http.Request, err error) {
 	// return Internal when Marshal failed
 	const fallback = `{"code": 13, "message": "failed to marshal error message"}`
 
+	var customStatus *HTTPStatusError
+	if errors.As(err, &customStatus) {
+		err = customStatus.Err
+	}
+
 	s := status.Convert(err)
 	pb := s.Proto()
 
@@ -119,6 +140,10 @@ func DefaultHTTPErrorHandler(ctx context.Context, mux *ServeMux, marshaler Marsh
 	}
 
 	st := HTTPStatusFromCode(s.Code())
+	if customStatus != nil {
+		st = customStatus.HTTPStatus
+	}
+
 	w.WriteHeader(st)
 	if _, err := w.Write(buf); err != nil {
 		grpclog.Infof("Failed to write response: %v", err)

runtime/errors_test.go

@@ -60,6 +60,16 @@ func TestDefaultHTTPError(t *testing.T) {
 			contentType: "Custom-Content-Type",
 			msg:         "example error",
 		},
+		{
+			err: &runtime.HTTPStatusError{
+				HTTPStatus: http.StatusMethodNotAllowed,
+				Err:        status.Error(codes.Unimplemented, http.StatusText(http.StatusMethodNotAllowed)),
+			},
+			status:      http.StatusMethodNotAllowed,
+			marshaler:   &runtime.JSONPb{},
+			contentType: "application/json",
+			msg:         "Method Not Allowed",
+		},
 	} {
 		t.Run(strconv.Itoa(i), func(t *testing.T) {
 			w := httptest.NewRecorder()