muxpatterns

README

muxpatterns

This repo holds a sample implementation of the enhanced http.ServeMux routing patterns that are being discussed at https://github.com/golang/go/discussions/60227.

Documentation

Overview

Package muxpatterns is a sample implementation of enhanced http.ServeMux routing patterns. See https://github.com/golang/go/discussions/60227.

The API in this package is for experimentation only. It is likely that none of it will be in the proposal.

Index

• func DescribeRelationship(pat1, pat2 string) string
• type Pattern
  • func Parse(s string) (*Pattern, error)
  • func (p1 *Pattern) ConflictsWith(p2 *Pattern) bool
  • func (p1 *Pattern) HigherPrecedence(p2 *Pattern) bool
  • func (p *Pattern) Method() string
  • func (p *Pattern) String() string
• type PatternSet
  • func (s *PatternSet) Match(method, host, path string) (*Pattern, map[string]string)
  • func (s *PatternSet) MatchRequest(req *http.Request) (*Pattern, map[string]string)
  • func (s *PatternSet) Register(p *Pattern) error
• type Server
  • func (s *Server) Handle(pattern string, handler http.Handler)
  • func (s *Server) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

Functions

func DescribeRelationship

func DescribeRelationship(pat1, pat2 string) string

DescribeRelationship returns a string that describes how pat1 and pat2 are related, in terms of the paths they match.

Types

type Pattern

type Pattern struct {
	// contains filtered or unexported fields
}

A Pattern is something that can be matched against an HTTP request.

func Parse

func Parse(s string) (*Pattern, error)

Parse parses a string into a Pattern. The string's syntax is

[METHOD] [HOST]/[PATH]

where:

• METHOD is the uppercase name of an HTTP method
• HOST is a hostname
• PATH consists of slash-separated segments, where each segment is either a literal or a wildcard of the form "{name}", "{name...}", or "{$}".

METHOD, HOST and PATH are all optional; that is, the string can be "/". If METHOD is present, it must be followed by a single space. Wildcard names must be valid Go identifiers. The "{$}" and "{name...}" wildcard must occur at the end of PATH. PATH may end with a '/'. Wildcard names in a path must be distinct.

func (*Pattern) ConflictsWith

func (p1 *Pattern) ConflictsWith(p2 *Pattern) bool

ConflictsWith reports whether p1 conflicts with p2, that is, whether there is a request that both match but where neither is higher precedence than the other.

func (*Pattern) HigherPrecedence

func (p1 *Pattern) HigherPrecedence(p2 *Pattern) bool

HigherPrecedence reports whether p1 has higher precedence than p2. If p1 and p2 both match a request, then p1 will be chosen.

Precedence is defined by these rules:

1. Patterns with a host win over patterns without a host.
2. Patterns with a method win over patterns without a method.
3. Patterns whose path is more specific win. One path pattern is more specific than another if the second matches all the paths of the first and more.

func (*Pattern) Method

func (p *Pattern) Method() string

func (*Pattern) String

func (p *Pattern) String() string

type PatternSet

type PatternSet struct {
	// contains filtered or unexported fields
}

A PatternSet is a set of non-conflicting patterns. The zero value is an empty PatternSet, ready for use.

func (*PatternSet) Match

func (s *PatternSet) Match(method, host, path string) (*Pattern, map[string]string)

Match matches the method, host and path against the patterns in the PatternSet. It returns the highest-precedence matching pattern and a map from wildcard names to matching path segments. Match returns (nil, nil, nil) if there is no matching pattern.

func (*PatternSet) MatchRequest

func (s *PatternSet) MatchRequest(req *http.Request) (*Pattern, map[string]string)

MatchRequest calls Match with the request's method, host and path.

func (*PatternSet) Register

func (s *PatternSet) Register(p *Pattern) error

Register adds a Pattern to the set. If returns an error if the pattern conflicts with an existing pattern in the set.

type Server

type Server struct {
	// contains filtered or unexported fields
}

func (*Server) Handle

func (s *Server) Handle(pattern string, handler http.Handler)

func (*Server) HandleFunc

func (s *Server) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes a PatternSet implement the http.Handler interface. This is just for benchmarking with github.com/julienschmidt/go-http-routing-benchmark.