httph

README

httph

HTTP helpers and middleware. H is for helpful!

go get maragu.dev/httph

Made in 🇩🇰 by maragu, maker of online Go courses.

Documentation

Overview

Package httph provides HTTP helpers and middleware compatible with net/http.

Index

• func FormHandler[Req any](h func(http.ResponseWriter, *http.Request, Req)) http.HandlerFunc
• func JSONHandler[Req any, Res any](h func(http.ResponseWriter, *http.Request, Req) (Res, error)) http.HandlerFunc
• func NoClickjacking(next http.Handler) http.Handler
• func VersionedAssets(next http.Handler) http.Handler
• type ContentSecurityPolicyOptions
• type GoGetOptions
• type Middleware
  • func ContentSecurityPolicy(optsFunc func(opts *ContentSecurityPolicyOptions)) Middleware
  • func GoGet(opts GoGetOptions) Middleware

Examples

• FormHandler
• JSONHandler

Functions

func FormHandler

func FormHandler[Req any](h func(http.ResponseWriter, *http.Request, Req)) http.HandlerFunc

FormHandler takes a function that is like a regular http.Handler, except it also receives a struct with values parsed from http.Request.ParseForm. Any parsing errors will result in http.StatusBadRequest. Uses reflection under the hood. If the request struct satisfies the validator interface, also use it to validate the struct.

Example

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"net/url"
	"strings"

	_ "embed"
	"maragu.dev/httph"
)

func main() {
	type Req struct {
		Name string
		Age  int
	}

	h := httph.FormHandler(func(w http.ResponseWriter, r *http.Request, req Req) {
		_, _ = fmt.Fprintf(w, "Hello %v, you are %v years old", req.Name, req.Age)
	})

	w := httptest.NewRecorder()
	vs := url.Values{
		"name": {"World"},
		"age":  {"20"},
	}
	r := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(vs.Encode()))
	r.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	h.ServeHTTP(w, r)

	body, _ := io.ReadAll(w.Result().Body)
	fmt.Println(string(body))
}

Output:

Hello World, you are 20 years old

func JSONHandler

func JSONHandler[Req any, Res any](h func(http.ResponseWriter, *http.Request, Req) (Res, error)) http.HandlerFunc

JSONHandler takes a function that is like a regular http.Handler, except it also receives a struct with values parsed from the request body as JSON. The function also returns a struct that will be encoded as JSON in the response. If either the response struct or error satisfy the statusCodeGiver interface, the given HTTP status code is returned.

Example

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strings"

	_ "embed"
	"maragu.dev/httph"
)

func main() {
	type Req struct {
		Name string
	}

	type Res struct {
		Message string
	}

	h := httph.JSONHandler(func(w http.ResponseWriter, r *http.Request, req Req) (Res, error) {
		return Res{Message: "Hello " + req.Name}, nil
	})

	w := httptest.NewRecorder()
	h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"Name":"World"}`)))

	body, _ := io.ReadAll(w.Result().Body)
	fmt.Println(string(body))
}

Output:

{"Message":"Hello World"}

func NoClickjacking

func NoClickjacking(next http.Handler) http.Handler

NoClickjacking is Middleware which sets headers to disallow frame embedding and XSS protection for older browsers. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection

func VersionedAssets

func VersionedAssets(next http.Handler) http.Handler

VersionedAssets is Middleware to help serve versioned assets without the version. It basically strips the version from the asset path and forwards the request, probably to a static file handler.

Types

type ContentSecurityPolicyOptions

type ContentSecurityPolicyOptions struct {
	ChildSrc       string
	ConnectSrc     string
	DefaultSrc     string
	FontSrc        string
	FrameSrc       string
	ImgSrc         string
	ManifestSrc    string
	MediaSrc       string
	ObjectSrc      string
	ScriptSrc      string
	ScriptSrcElem  string
	ScriptSrcAttr  string
	StyleSrc       string
	StyleSrcElem   string
	StyleSrcAttr   string
	WorkerSrc      string
	BaseURI        string
	Sandbox        string
	FormAction     string
	FrameAncestors string
	ReportTo       string
}

ContentSecurityPolicyOptions for the ContentSecurityPolicy Middleware. The field names match policy directives, and only values should be supplied, so no directive names and delimiters. Only non-experimental, non-deprecated directives are included. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy

type GoGetOptions

type GoGetOptions struct {
	Domain    string   // Domain to serve URLs for, for example: "maragu.dev"
	Modules   []string // Lit of module names, for example: "httph", "foo"
	URLPrefix string   // URL prefix to serve the module from, for example: "https://github.com/maragudk"
}

type Middleware

type Middleware = func(next http.Handler) http.Handler

Middleware is a function that takes an http.Handler and returns an http.Handler. This is a common middleware pattern in net/http.

func ContentSecurityPolicy

func ContentSecurityPolicy(optsFunc func(opts *ContentSecurityPolicyOptions)) Middleware

ContentSecurityPolicy is Middleware to set CSP headers. By default this is a strict policy, disallowing everything but images, styles, scripts, and fonts from 'self'. See https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP See https://infosec.mozilla.org/guidelines/web_security#content-security-policy

func GoGet

func GoGet(opts GoGetOptions) Middleware

GoGet is Middleware to support redirecting go get requests to module VCS URLs, popularly known as vanity URLs. See https://www.maragu.dev/blog/til-http-middleware-for-custom-go-module-paths