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

• 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) Match(method, host, path string) (bool, []string)
  • func (p *Pattern) Method() string
  • func (p *Pattern) String() string
• type PatternSet
  • func (s *PatternSet) Match(method, host, path string) (*Pattern, map[string]string, error)
  • func (s *PatternSet) MatchRequest(req *http.Request) (*Pattern, map[string]string, error)
  • func (s *PatternSet) Register(p *Pattern) error

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 '/'.

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) Match

func (p *Pattern) Match(method, host, path string) (bool, []string)

Match reports whether p matches the method, host and path. The method and host may be empty. The path must start with a '/' If the first return value is true, the second is the list of wildcard matches, in the order the wildcards occur in p.

A wildcard other than "$" that does not end in "..." matches a non-empty path segment. So "/{x}" matches "/a" but not "/".

A wildcard that ends in "..." can match the empty string, or a sequence of path segments. So "/{x...}" matches the paths "/", "/a", "/a/" and "/a/b". In each case, the string associated with "x" is the path with the initial slash removed.

The wildcard "{$}" matches the empty string, but only after a final slash.

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, error)

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, error)

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.