Clean http handlers in Go

Introduction

For this blog post we are going to take a look at the http.HandlerFunc type and how we can improve it to make more elegant and clean handlers. Following the idioms of Go and staying compatible with the standard library.

Handlers

In Go A Handler is a type which responds to an HTTP request.

type Handler interface {

        ServeHTTP(http.ResponseWriter, *http.Request)

}

Any structure implementing the ServeHTTP method from the interface can be used to handle http requests. This is very powerful and flexible. It is easy to add http handling capabilities to any structure in your program.

Altough most of the time this is not the way a lot of people do it. It is still limited to the fact that you need to implement it on a structure which is not always what you would like. A single function would be easier to use than implementing an interface. Luckily Go has an solution for this.

Say Hi to the http.HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request)

The HandlerFunc is basically an adapter for the Handler interface. Because the HandlerFunc is a type it can implement methods on that type. Note that the type is actually a function so any function containing the same signature as the HandlerFunc can be easily casted to this type. When passing it as a parameter this happens implicitly and you wont even know the difference.

Ok cool, so here we are we’ve seen how the Handler and HandlerFunc works, but how can we actually extend them? And why do we even need to extend them, they are already powerfull aren’t they?

If you have ever written more complex http request handlers in Go you probably know that they can grow really big because of the verbose error handling and early returns.

func IndexHandler(w http.ResponseWriter, r *http.Request) {

  // Do something

  v, err := ...

  // check for err

  if err != nil {

    w.WriteHeader(http.StatusInternalServerError)

    w.Write([]byte(err.Error()))

    return

  }

  // More code

  // ...

}

This is common code and because the functions returns void we have to terminate the function early if we wan’t to stop the function from writing more to the given io.Writer. Ofcourse an else would be possible here aswell but that would just decrease the readability, because statements will be more and more nested and harder to follow.

But most of the functions in Go returns errors when something failed instead of notifying through an given pointer in the parameters (after all we aren’t programming in C right)?

So how can we change this and still make use of the great integration with the standard library and the http.Handler interface. For this we are going to take the idea of http.HandlerFunc and create our own adapter for the Handler interface which can work with return types.

But first we need to find the perfect return types for our functions. Only an error would not be sufficient because we still have to set the status code on the ResponseWriter. We could make a generic struct which can contain most of the information we would like to send to the caller, this would look like this:

// Map of string to string where the key is the key for the header

// And the value is the value for the header

type Headers map[string]string

// Generic response object for our handlers

type Response struct {

	// StatusCode

	Status int

	// Content Type to writer

	ContentType string

	// Content to be written to the response writer

	Content io.Reader

	// Headers to be written to the response writer

	Headers Headers

}

The same as how the HandlerFunc works we create a type alias for our function definition. The type will return the new created response object by us.

type Action func(r *http.Request) *Response

We omitted the response writer as paramater because we don’t need it in our functions. We won’t be writing to the response writer from inside our function (this breaks the paradigm we want to accomplish). The response struct is the way for us to write content to the response writer. Now we need to make our Action type compatible with thehttp.Handler interface by implementing the ServeHTTP method on it.

func (a Action) ServeHTTP(rw http.ResponseWriter, r *http.Request) {

	if response := a(r); response != nil {

		if response.ContentType != "" {

			rw.Header().Set("Content-Type", response.ContentType)

		}

		for k, v := range response.Headers {

			rw.Header().Set(k, v)

		}

		rw.WriteHeader(response.Status)

		_, err := io.Copy(rw, response.Content)

		if err != nil {

			rw.WriteHeader(http.StatusInternalServerError)

		}

	} else {

		rw.WriteHeader(http.StatusOK)

	}

}

A few things going on here. First we declare the method on the function and we call the type Action which is in essence just a plain function. So every function with the same type signature as the Action can be converted to this Action type. As we know our Action type gave back a pointer to a Response struct. For this to work correctly we need to check if the pointer is not nil. Otherwise the program would panic when calling the Status and Message property on them. By using a pointer it gives us also the extra benefit of that we can return nil in our functions and nothing will be done (the default value of 200 OK will be send to the caller). We still have the same flexibility of the regular http.HandlerFunc and we are in control of when something will be written to the response writer.

Ok cool, with this in place we have some nice functions to work with. We can now return in our handlers and everything will be fine. We can now write some wrapper functions so we don’t have to manually create our Response struct.

Because our response struct works with an io.Reader interface we cannot just simply return the error in there so we need to first create a wrapper for this. We use a io.Reader here because this way we stay flexible, we can return any reader (even a stream reader) in our handlers and it will be streamed to the response writer.

func Error(status int, err error, headers Headers) *Response {

	return &Response{

		Status:  status,

		Content: bytes.NewBufferString(err.Error()),

		Headers: headers,

	}

}

This function pretty much explains itself. We pass in an error and we let the function convert it to an io.Reader with using an internal buffer. We can use it like this:

func Index(r *http.Request) *Response {

	return Error(404, errors.New("not found"), nil)

}

Sweet! that looks way more clear than before. Let’s take it a step further, nowadays a lot of people are making rest api’s which spit out JSON to the caller. We can easily create a function for this.

type errorResponse struct {

	Error string `json:"error"`

}

func ErrorJSON(status int, err error, headers Headers) *Response {

	errResp := errorResponse{

		Error: err.Error(),

	}

	b, err := json.Marshal(errResp)

	if err != nil {

		return Error(http.StatusInternalServerError, err, headers)

	}

	return &Response{

		Status:      status,

		ContentType: "application/json",

		Content:     bytes.NewBuffer(b),

		Headers:     headers,

	}

}

NOTE We can use the ErrorJSON functions again in our handlers. And it will do the conversion to JSON for us.

func Index(r *http.Request) *Response {

	return ErrorJSON(http.StatusNotFound, errors.New("not found"), nil)

}

and it will print:

{

  "error": "not found"

}

With those helper functions we can create responses for every content-type you would like; ErrorXML etc. We’ve seen error handling and how we can elegant create custom responses for our errors. How does this work for returning something else than en error?

We can create a generic functions (same as the error function) for regular data aswell.

func Data(status int, content []byte, headers Headers) *Response {

	return &Response{

		Status:  status,

		Content: bytes.NewBuffer(content),

		Headers: headers,

	}

}

Example usage:

func Index(r *http.Request) *Response {

	return Data(http.StatusOK, []byte("test"), nil)

}

Same as the errors we could take this a step further and implement some helper functions who will do marshalling of data to JSON.

func DataJSON(status int, v interface{}, headers Headers) *Response {

	b, err := json.Marshal(v)

	if err != nil {

		return ErrorJSON(http.StatusInternalServerError, err, headers)

	}

	return &Response{

		Status:      status,

		ContentType: "application/json",

		Content:     bytes.NewBuffer(b),

		Headers:     headers,

	}

}

Here we accept an interface in our method and let the json package take care of the conversion between the incoming v and the byte array. If we encounter some error during marshalling we just return our ErrorJSON function and the caller will be notified with the error (note this should probably be logged instead of returning the actual error to the caller). We do the same trick as in our ErrorJSON method and set the right content type. Usage is the same as all the other methods.

type temp struct {

	Message string `json:"msg"`

}

func Index(r *http.Request) *Response {

	return DataJSON(http.StatusOK, temp{"test"}, nil)

}

We can also create our helper function for the standard io.Reader this way we can return any reader we would like. This could be a external http or anything implementing theio.Reader interface.

func DataWithReader(status int, r io.Reader, headers Headers) *Response {

	return &Response{

		Status:  status,

		Content: r,

		Headers: headers,

	}

}

With this in place we have all the flexibility we would like and can return anything we can even think off. We eliminated the verbose writing to the response writer and made our handlers look way cleaner and easier to follow. Without losing perfomance or flexibility.

Compatibility with the standard library

Because our handlers are still of type http.Handler we can use them anywhere where the http.Handler interface is used.
Lets try it out! We are going to create middleware for loggin the details about a request

func logger(next http.Handler) http.Handler {

	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

		log.Printf("[%s] User agent => %s Remote addr => %s", r.Method, r.UserAgent(), r.RemoteAddr)

		next.ServeHTTP(w, r)

	})

}

We can create a route in main

func main() {

	http.Handle("/test", logger(Action(Index)))

	http.ListenAndServe(":8080", nil)

}

And it all works. We can chain the middleware and use existing middlewares with our new handler types.

Conclusion

The http.Handler interfaces gives a lot of flexibility and by using type aliasing in Go we can easily convert our functions to actual methods which implement the Handler interface. It is even possible to extend our Response object with more options. This is all up to you and you can modify the wrappers to use the new options you define. (Extra headers for example).

the full code can be found here Github Gist. Let me know what you think about it and what could be improved.

Thanks for reading and happy coding! (y)