matcher

README

GO HTTP Matcher

Provide a common http request matcher, and some implementations, requiring Go 1.22+.

Documentation

Overview

Package matcher provides a http request matcher and some implementations.

Index

• Constants
• Variables
• func RemoveParentheses(s string) string
• func Sort(ms []Matcher)
• type MatchFunc
  • func (f MatchFunc) Match(r *http.Request) bool
• type Matcher
  • func And(ms ...Matcher) Matcher
  • func ClientIP(ips ...string) (Matcher, error)
  • func Header(key, value string) Matcher
  • func Headerm(headerm map[string]string) Matcher
  • func Host(hosts ...string) Matcher
  • func Method(methods ...string) Matcher
  • func New(prio int, desc string, match MatchFunc) Matcher
  • func Or(ms ...Matcher) Matcher
  • func Path(paths ...string) Matcher
  • func PathPrefix(pathPrefixes ...string) Matcher
  • func Query(key, value string) Matcher
  • func Querym(querym map[string]string) Matcher
  • func ServerIP(ips ...string) (Matcher, error)

Constants

const (
	PriorityQuery      = 1
	PriorityHeader     = 4
	PriorityClientIP   = 20
	PriorityServerIP   = 20
	PriorityMethod     = 40
	PriorityPathPrefix = 50
	PriorityPath       = 500
	PriorityHost       = 5000
)

Variables

var (
	// AlwaysTrue is a match function that always reutrns true.
	AlwaysTrue = MatchFunc(func(*http.Request) bool { return true })

	// AlwaysFalse is a match function that always reutrns false.
	AlwaysFalse = MatchFunc(func(*http.Request) bool { return false })
)

var GetClientIP = func(r *http.Request) netip.Addr {
	return parseip("matcher.GetClientIP", r.RemoteAddr)
}

GetClientIP is used to customize the client ip.

var GetHost = func(r *http.Request) string {
	if r.TLS != nil && r.TLS.ServerName != "" {
		return strings.ToLower(r.TLS.ServerName)
	}
	return strings.ToLower(extracthost(r.Host))
}

GetHost is used to customize the host, which must be lower case.

var GetPath = func(r *http.Request) (path string) {
	if path = strings.TrimRight(r.URL.Path, "/"); path == "" {
		path = "/"
	}
	return
}

GetPath is used to customize the path.

var GetServerIP = func(r *http.Request) netip.Addr {
	addr := r.Context().Value(http.LocalAddrContextKey).(net.Addr)
	switch v := addr.(type) {
	case *net.TCPAddr:
		return ip2addr(v.IP)

	case *net.UDPAddr:
		return ip2addr(v.IP)

	default:
		return parseip("matcher.GetServerIP", v.String())
	}
}

GetServerIP is used to customize the server ip.

Functions

func RemoveParentheses

func RemoveParentheses(s string) string

RemoveParentheses tries to remove the leading '(' and trailling ')'.

If failing, return the original s.

func Sort

func Sort(ms []Matcher)

Sort sorts the matchers by the priority from high to low.

Types

type MatchFunc

type MatchFunc func(r *http.Request) bool

MatchFunc is a match function.

func (MatchFunc) Match

func (f MatchFunc) Match(r *http.Request) bool

Match implements the interface Matcher#Match.

type Matcher

type Matcher interface {
	Match(*http.Request) bool
	Priority() int
	fmt.Stringer
}

Matcher is used to match a http request.

func And

func And(ms ...Matcher) Matcher

And returns a new matcher based on AND from a set of matchers, which checks whether all the matchers match the request.

If no matchers, the returned mathcer does not match any request.

func ClientIP

func ClientIP(ips ...string) (Matcher, error)

ClientIP returns a new matcher that checks whether the client ip, that's remote address ip, is one of the specified ips.

If ips is empty, return (nil, nil) instead of an error.

func Header

func Header(key, value string) Matcher

Header returns a new matcher that checks whether the headers has the specified key-value argument.

The key is the case-insensitive match, but, the value is the exact match. If value is empty, it matches all the requests that has the header key and ignores the header value.

If key is empty, return nil instead of an error.

func Headerm

func Headerm(headerm map[string]string) Matcher

Headerm returns a new matcher that checks whether the headers has all the specified key-value arguments.

The keys are the case-insensitive match, but, the values are the exact match. If value is empty, it matches all the requests that has the header key and ignores the header value.

If headerm is empty, return nil instead of an error.

func Host

func Host(hosts ...string) Matcher

Host returns a new matcher that checks whether the host is one of the specified hosts, which supports the exact or wildcard domain, such as "www.example.com" or "*.example.com".

If hosts is empty, return nil instead of an error.

func Method

func Method(methods ...string) Matcher

Method returns a new matcher that checks whether the method is one of the specified methods.

If methods is empty, return nil instead of an error.

func New

func New(prio int, desc string, match MatchFunc) Matcher

New returns a request matcher.

func Or

func Or(ms ...Matcher) Matcher

Or returns a new matcher based on OR from a set of matchers, which checks whether any matcher matches the request.

If no matchers, the returned mathcer will match any request.

func Path

func Path(paths ...string) Matcher

Path returns a new matcher that checks whether the path is one of the specified paths.

If paths is empty, return nil instead of an error.

func PathPrefix

func PathPrefix(pathPrefixes ...string) Matcher

PathPrefix returns a new matcher that checks whether the path has the prefix that is in the specified path prefixes.

If pathPrefixes is empty, return (nil, nil) instead of an error.

func Query

func Query(key, value string) Matcher

Query returns a new matcher that checks whether the query has the specified key-value argument.

Both key and value are the exact match. If value is empty, it matches all the requests that has the query key and ignores the query value.

If key is empty, return nil instead of an error.

func Querym

func Querym(querym map[string]string) Matcher

Querym returns a new matcher that checks whether the query has all the specified key-value arguments.

Both keys and values are the exact match. If value is empty, it matches all the requests that has the query key and ignores the query value.

If querym is empty, returnnil instead of an error.

func ServerIP

func ServerIP(ips ...string) (Matcher, error)

ServerIP returns a new matcher that checks whether the server ip, that's local address ip, is one of the specified ips.

If ips is empty, return (nil, nil) instead of an error.