Major refactoring for better error handling

middleware/middleware.go

@@ -10,8 +10,32 @@ type (
 
 	// Middleware is the middle layer which represents the traditional
 	// idea of middleware: it is passed the next HandlerFunc in the chain
-	// and returns the inner layer, which is the actual HandlerFunc.
-	Middleware func(http.HandlerFunc) http.HandlerFunc
+	// and returns the inner layer, which is the actual Handler.
+	Middleware func(HandlerFunc) HandlerFunc
+
+	// HandlerFunc is like http.HandlerFunc except it returns a status code
+	// and an error. It is the inner-most layer which serves individual
+	// requests. The status code is for the client's benefit, the error
+	// value is for the server's benefit. The status code will be sent to
+	// the client while the error value will be logged privately. Sometimes,
+	// an error status code (4xx or 5xx) may be returned with a nil error
+	// when there is no reason to log the error on the server.
+	//
+	// If a HandlerFunc returns an error (status < 400), it should not write
+	// to the response. This philosophy is what makes middleware.HandlerFunc
+	// different from http.HandlerFunc. The error handling should happen
+	// at the application layer or in a dedicated error-handling middleware
+	// rather than an "every middleware for itself" paradigm. The error handling
+	// logic should make sure that the client is properly responded to according
+	// to the status code, but should probably not reveal the error message. The
+	// error message should be logged instead, for example.
+	HandlerFunc func(http.ResponseWriter, *http.Request) (int, error)
+
+	// Handler is like http.Handler except ServeHTTP returns a status code
+	// and an error. See HandlerFunc documentation for more information.
+	Handler interface {
+		ServeHTTP(http.ResponseWriter, *http.Request) (int, error)
+	}
 
 	// A Control provides structured access to tokens from a configuration file
 	// and also to properties of the server being configured. Middleware generators