pattern

Documentation

Overview

Package pattern contains utilities for parsing Go routing patterns as defined for net/http.ServeMux. See the Go documentation for details.

Example (ParseRequest)

package main

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

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET example.invalid/buckets/{id}/value", func(_ http.ResponseWriter, r *http.Request) {
		// Parse the pattern matching this request.
		p := pattern.MustParse(r.Pattern)
		fmt.Printf("method: %q, host: %q, path: %q\n", p.Method, p.Host, p.Path)
	})

	mux.ServeHTTP(httptest.NewRecorder(),
		httptest.NewRequest(http.MethodGet, "http://example.invalid/buckets/1234/value", nil))
}

Output:
method: "GET", host: "example.invalid", path: "buckets/{id}/value"

Index

• Variables
• type Pattern
  • func MustParse(pattern string) Pattern
  • func Parse(pattern string) (Pattern, error)
  • func (p Pattern) IsZero() bool
  • func (p Pattern) Join(other Pattern) Pattern
  • func (p Pattern) LogValue() slog.Value
  • func (p Pattern) Match(other Pattern) bool
  • func (p Pattern) String() string

Examples

• Package (ParseRequest)
• MustParse
• Parse
• Pattern.IsZero
• Pattern.Join
• Pattern.LogValue
• Pattern.Match
• Pattern.String (Full)
• Pattern.String (NoMethod)

Variables

var ErrInvalidPattern = errors.New("invalid pattern")

ErrInvalidPattern is returned by this package when an invalid pattern is encountered.

Types

type Pattern

type Pattern struct {
	// Method contains the routed HTTP methods.
	// It matches all methods when not set.
	Method string

	// Host contains the routed HTTP host.
	// It matches all hosts when not set.
	Host string

	// Path contains the routed HTTP path.
	// Paths ending with a '/' match all routes starting with that path.
	// It matches all paths when not set.
	Path string
}

Pattern represents a routing pattern as implemented by net/http.ServeMux:

[METHOD ][HOST]/[PATH]

func MustParse

func MustParse(pattern string) Pattern

MustParse parses the given pattern and returns the parsed result. It panics when the pattern is not valid. See net/http.ServeMux for valid routing patterns.

Example

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	p := pattern.MustParse("GET example.com/b/{bucket}/o/{objectname...}")
	fmt.Printf("method: %q, host: %q, path: %q\n", p.Method, p.Host, p.Path)

}

Output:
method: "GET", host: "example.com", path: "b/{bucket}/o/{objectname...}"

func Parse

func Parse(pattern string) (Pattern, error)

Parse parses the given pattern and returns the parsed result. It returns ErrInvalidPattern when the pattern is not valid. See net/http.ServeMux for valid routing patterns.

Example

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	printFn := func(p pattern.Pattern) {
		fmt.Printf("method: %q, host: %q, path: %q\n", p.Method, p.Host, p.Path)
	}

	p, _ := pattern.Parse("/")
	printFn(p)

	p, _ = pattern.Parse("/index.html")
	printFn(p)

	p, _ = pattern.Parse("GET /static/")
	printFn(p)

	p, _ = pattern.Parse("example.com/")
	printFn(p)

	p, _ = pattern.Parse("example.com/{$}")
	printFn(p)

	p, _ = pattern.Parse("/b/{bucket}/o/{objectname...}")
	printFn(p)

	p, _ = pattern.Parse("GET\t/static/")
	printFn(p)

	p, _ = pattern.Parse("GET    /static/")
	printFn(p)

}

Output:
method: "", host: "", path: ""
method: "", host: "", path: "index.html"
method: "GET", host: "", path: "static/"
method: "", host: "example.com", path: ""
method: "", host: "example.com", path: "{$}"
method: "", host: "", path: "b/{bucket}/o/{objectname...}"
method: "GET", host: "", path: "static/"
method: "GET", host: "", path: "static/"

func (Pattern) IsZero

func (p Pattern) IsZero() bool

IsZero returns true if this pattern is the zero value. The zero value matches all methods, hosts and paths.

Example

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	printFn := func(p pattern.Pattern) {
		fmt.Printf("%s: %t\n", p, p.IsZero())
	}

	printFn(pattern.Pattern{})
	printFn(pattern.MustParse("/"))
	printFn(pattern.MustParse("/index.html"))
}

Output:
/: true
/: true
/index.html: false

func (Pattern) Join

func (p Pattern) Join(other Pattern) Pattern

Join merges the current pattern with another pattern and returns the result. If the method or host must match if set.

Example

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	a := pattern.MustParse("GET /a")
	b := pattern.MustParse("example.invalid/static/")
	c := a.Join(b)

	fmt.Printf("method: %q, host: %q, path: %q\n", c.Method, c.Host, c.Path)
}

Output:
method: "GET", host: "example.invalid", path: "a/static/"

func (Pattern) LogValue

func (p Pattern) LogValue() slog.Value

LogValue implements slog.LogValuer.

Example

package main

import (
	"log/slog"
	"os"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	// Create a logger without timestamps for this example.
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey && len(groups) == 0 {
				return slog.Attr{}
			}

			return a
		},
	}))

	logger.Info("Request", "pattern",
		pattern.MustParse("GET example.com/b/{bucket}"))
}

Output:
level=INFO msg=Request pattern.method=GET pattern.host=example.com pattern.path=b/{bucket}

func (Pattern) Match

func (p Pattern) Match(other Pattern) bool

Match returns true if the given path matches.

Example

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	printFn := func(a, b string) {
		pA := pattern.MustParse(a)
		pB := pattern.MustParse(b)

		fmt.Printf("%q vs %q -> %t\n", pA, pB, pA.Match(pB))
	}

	printFn("/", "/")
	printFn("GET example.com/index.html", "/index.html")
	printFn("GET example.com/index.html", "POST /index.html")
	printFn("GET example.com/index.html", "GET example.com/index.html")
	printFn("GET example.com/index.html", "GET example.com/index2.html")
}

Output:
"/" vs "/" -> true
"GET example.com/index.html" vs "/index.html" -> true
"GET example.com/index.html" vs "POST /index.html" -> false
"GET example.com/index.html" vs "GET example.com/index.html" -> true
"GET example.com/index.html" vs "GET example.com/index2.html" -> false

func (Pattern) String

func (p Pattern) String() string

String returns the representation of the Pattern as used by net/http.ServeMux.

Example (Full)

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	orig := "GET example.com/b/{bucket}"
	parsed := pattern.MustParse(orig)

	fmt.Printf("orig:   %q\nparsed: %q\n", orig, parsed)
}

Output:
orig:   "GET example.com/b/{bucket}"
parsed: "GET example.com/b/{bucket}"

Example (NoMethod)

package main

import (
	"fmt"

	"go.hofstra.dev/httputil/mux/pattern"
)

func main() {
	orig := "/static/"
	parsed := pattern.MustParse(orig)

	fmt.Printf("orig:   %q\nparsed: %q\n", orig, parsed)
}

Output:
orig:   "/static/"
parsed: "/static/"