httputil

httputil

Package httputil provides utility helpers for working with net/http, adding sensible defaults, bootstrapping, and eliminating boilerplate code commonly required when building web services. This package aims to streamline the development of HTTP-based applications by offering a cohesive set of tools for HTTP server configuration, request handling, error management, and more.

• Features
  • HTTP Server with Sensible Defaults
  • Handler Framework
  • Error Handling
  • Request Parameter Processing
  • Testing Utilities
• Installation
• Usage
  • Basic JSON Handler
  • JSON Handler Request/Response
  • JSON Handler With Params
  • Basic net/http Handler
• Server Configuration Options
• Design Choices

Features

HTTP Server with Sensible Defaults

• Configurable HTTP server with secure, production-ready defaults
• Graceful shutdown handling
• Customizable timeouts (idle, read, write, shutdown)
• Request body size limits to prevent abuse

Handler Framework

• Easy conversion between different handler types
• Support for standard http.Handler interfaces
• JSON request/response handling with automatic marshaling/unmarshaling
• Request interception and middleware support

Error Handling

• RFC 7807 compliant problem details for HTTP APIs
• Standardized error formatting
• Predefined error constructors for common HTTP status codes

Request Parameter Processing

• Safe and convenient parameter extraction from different sources (URL, query, headers, body)
• Validation support

Testing Utilities

• JSON comparison tools for testing HTTP responses
• Helper functions to reduce test boilerplate

Installation

go get github.com/nickbryan/httputil

Usage

Basic JSON Handler

package main

import (
    "context"
    "net/http"

    "github.com/nickbryan/slogutil"

    "github.com/nickbryan/httputil"
)

func main() {
    logger := slogutil.NewJSONLogger()  
    server := httputil.NewServer(logger)
	
    server.Register(
        httputil.Endpoint{
            Method: http.MethodGet, 
            Path:   "/greetings", 
            Handler: httputil.NewJSONHandler(
                func(_ httputil.RequestEmpty) (*httputil.Response, error) {
                    return httputil.OK([]string{"Hello, World!", "Hola Mundo!"})
                }, 
            ),
        }, 
    )

    server.Serve(context.Background())

    // curl localhost:8080/greetings
    // ["Hello, World!","Hola Mundo!"]
}

JSON Handler Request/Response

package main

import (
    "context"
    "net/http"

    "github.com/nickbryan/slogutil"

    "github.com/nickbryan/httputil"
)

func main() {
    logger := slogutil.NewJSONLogger()
    server := httputil.NewServer(logger)

    server.Register(newGreetingsEndpoint())

    server.Serve(context.Background())

    // curl -iS -X POST -H "Content-Type: application/json" -d '{"name": "Nick"}' localhost:8080/greetings                                                                               7 ↵
    // HTTP/1.1 201 Created
    // Content-Type: application/json
    // Date: Sat, 29 Mar 2025 17:12:40 GMT
    // Content-Length: 26
    //
    // {"message":"Hello Nick!"}
}

func newGreetingsEndpoint() httputil.Endpoint {
    type (
        request struct {
            Name string `json:"name" validate:"required"`
        }
        response struct {
            Message string `json:"message"`
        }
    )

    return httputil.Endpoint{
        Method: http.MethodPost,
        Path:   "/greetings",
        Handler: httputil.NewJSONHandler(func(r httputil.RequestData[request]) (*httputil.Response, error) {
            return httputil.Created(response{Message: "Hello " + r.Data.Name + "!"})
        }),
    }
}

JSON Handler With Params

package main

import (
    "context"
    "net/http"

    "github.com/nickbryan/slogutil"

    "github.com/nickbryan/httputil"
)

func main() {
    logger := slogutil.NewJSONLogger()
    server := httputil.NewServer(logger)

    server.Register(newGreetingsEndpoint())

    server.Serve(context.Background())

    // curl localhost:8080/greetings/Nick
    // ["Hello, Nick!","Hola Nick!"]
}

func newGreetingsEndpoint() httputil.Endpoint {
    type params struct {
        Name string `path:"name" validate:"required"`
    }

    return httputil.Endpoint{
        Method: http.MethodGet,
        Path:   "/greetings/{name}",
        Handler: httputil.NewJSONHandler(func(r httputil.RequestParams[params]) (*httputil.Response, error) {
            return httputil.OK([]string{"Hello, " + r.Params.Name + "!", "Hola " + r.Params.Name + "!"})
        }),
    }
}

Basic net/http Handler

package main

import (
    "context"
    "net/http"

    "github.com/nickbryan/slogutil"

    "github.com/nickbryan/httputil"
)

func main() {
    logger := slogutil.NewJSONLogger()
    server := httputil.NewServer(logger)

    server.Register(
        httputil.Endpoint{
            Method: http.MethodGet,
            Path:   "/greetings",
            Handler: httputil.NewNetHTTPHandlerFunc(
                func(w http.ResponseWriter, _ *http.Request) {
                    _, _ = w.Write([]byte(`["Hello, World!","Hola Mundo!"]`))
                },
            ),
        },
    )

    server.Serve(context.Background())
	
    // curl localhost:8080/greetings
    // ["Hello, World!","Hola Mundo!"]
}

Server Configuration Options

The httputil.Server can be configured with the following options:

Design Choices

RFC 7807 Problem Details

Error responses follow the RFC 7807 standard for Problem Details for HTTP APIs, providing consistent, readable error information.

Middleware Architecture

Middleware can be applied at both the server and endpoint level, providing a flexible way to implement cross-cutting concerns like logging, authentication, and metrics.

Handler Interfaces

The package provides a consistent interface for handlers while supporting multiple styles (standard http.Handler, functional handlers, and JSON-specific handlers).