middleware: add Discard method to WrapResponseWriter

[patrislav]

The Discard method will cause the WrapResponseWriter to only write to the tee'd writer, while the original http.ResponseWriter would be untouched.

This is useful in situations where the headers or the buffer need to be modified in a middleware after the handler returns. One concrete example is response body signing, e.g.:

func SigningMiddleware(next http.Handler) http.handler {
    return http.HandlerFunc(w http.ResponseWriter, r *http.Request) {
        var buf bytes.Buffer
        ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
        ww.Tee(&buf)
        ww.Discard() // discard writes to the original response writer
        
        next.ServeHTTP(ww, r)

        signature := calculateBodySignature(buf.Bytes())
        w.Header().Set("signature", signature)
        buf.WriteTo(w)
    }
}

[VojtechVitek]

LGTM 🎉

Minor feedback.

[VojtechVitek]

This is technically a breaking API change -- if there's anyone who implemented this interface externally. But I can't think of any use case why would anyone do that. And it's an easy fix.

So, I'm OK with this change if we bump minor version only. I just wanted to call it out for visibility.

[VojtechVitek]

Thinking of this some more, I think we could achieve backward-compatibility by

1. Creating a new private interface wrapResponseWriter that extends the original interface with the new Discard() method.

   type wrapResponseWriter interface {
        WrapResponseWriter
       
        // Discard causes all writes to the original ResponseWriter be discarded instead writing only to the tee'd writer if it's set.
        Discard()
   }

2. Returning it from NewWrapResponseWriter() constructor

   - func NewWrapResponseWriter(w http.ResponseWriter, protoMajor int) WrapResponseWriter {
   + func NewWrapResponseWriter(w http.ResponseWriter, protoMajor int) wrapResponseWriter {

I don't see a reason why we'd need to return a public interface in this case. I don't expect anyone re-implementing wrapResponseWriter externally?

[patrislav]

You're right, I suppose the issue is not people implementing the interface (as they're free to do that) but rather using it to type variables or function arguments. IMO in that case the correct way would rather be to use the http.ResponseWriter or define a custom interface with the methods they need.

Good idea with the private interface, wouldn't it be confusing with the now two similarly named interfaces though?

[VojtechVitek]

FYI: We decided to update the original interface, as we don't expect anyone using it directly for anything.

[VojtechVitek]

LGTM