url

package
v1.166.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (

	// IsPathParameter validates OpenAPI-style path parameter segments such as
	// `{id}`.
	IsPathParameter = validation.NewStringRuleWithError(isPathParameter, errPathParameterInvalid)

	// IsURI validates URI strings and byte slices.
	//
	// The rule accepts full URLs handled by `is.URL` as well as other valid URI
	// forms accepted by `net/url.ParseRequestURI`, such as `mailto:` URIs and
	// request-target-style relative URI references.
	IsURI = validation.NewStringRuleWithError(isURI, errURIInvalid)
)

Section 3.3 of RFC3986 details valid characters for path segments (see https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)

Functions

func BasicEqualityPathSegmentMatcher 

func BasicEqualityPathSegmentMatcher(segmentA, segmentB string) (match bool, err error)

BasicEqualityPathSegmentMatcher is a PathSegmentMatcherFunc that performs direct string comparison of two path segments.

func BasicEqualityPathSegmentWithParamMatcher 

func BasicEqualityPathSegmentWithParamMatcher(segmentA, segmentB string) (match bool, err error)

BasicEqualityPathSegmentWithParamMatcher is a PathSegmentMatcherFunc that is similar to BasicEqualityPathSegmentMatcher but accounts for path parameter segments.

func Compare added in v1.166.0 

func Compare(url1, url2 string, options ...NormalisationOption) (result int, err error)

Compare canonicalises both URLs with the same normalisation options and returns an ordering result equivalent to strings.Compare.

Example: 

result, err := Compare("https://www.example.com/path", "https://example.com/path", RemoveWWW())
// result == 0

result, err = Compare("https://api.example.com/v1/users", "/v1/users", IgnoreScheme(), IgnoreHost())
// result == 0

References:

func CompareForSorting added in v1.166.0 

func CompareForSorting(options ...NormalisationOption) func(left, right string) int

CompareForSorting adapts Compare to the callback shape expected by slices.SortFunc. If either URL cannot be normalised, it falls back to comparing the original strings directly.

Example: 

slices.SortFunc(urls, CompareForSorting(RemoveWWW(), IgnoreScheme()))

func CompareURLs added in v1.166.0 

func CompareURLs(url1, url2 string, options ...NormalisationOption) (match bool, err error)

CompareURLs canonicalises both URLs with the same normalisation options and reports whether the resulting forms are equal.

Reference:

func HasMatchingPathSegments 

func HasMatchingPathSegments(pathA, pathB string) (match bool, err error)

HasMatchingPathSegments checks whether two path strings match based on their segments by doing a simple equality check on each path segment pair.

func HasMatchingPathSegmentsWithParams 

func HasMatchingPathSegmentsWithParams(pathA, pathB string) (match bool, err error)

HasMatchingPathSegmentsWithParams is similar to HasMatchingPathSegments but also considers segments as matching if at least one of them contains a path parameter. 

HasMatchingPathSegmentsWithParams("/some/{param}/path", "/some/{param}/path") // true
HasMatchingPathSegmentsWithParams("/some/abc/path", "/some/{param}/path") // true
HasMatchingPathSegmentsWithParams("/some/abc/path", "/some/def/path") // false

func MatchesPathParameterSyntax 

func MatchesPathParameterSyntax(parameter string) bool

MatchesPathParameterSyntax checks whether the parameter string matches the syntax for a path parameter as described by the OpenAPI spec (see https://spec.openapis.org/oas/v3.0.0.html#path-templating).

func MatchingPathSegments 

func MatchingPathSegments(pathA, pathB string, matcherFn PathSegmentMatcherFunc) (match bool, err error)

MatchingPathSegments checks whether two path strings match based on their segments using the provided matcher function.

func NormaliseURL added in v1.166.0 

func NormaliseURL(rawURL string, options ...NormalisationOption) (normalised string, err error)

NormaliseURL canonicalises rawURL according to the supplied options.

The behaviour is inspired by github.com/PuerkitoBio/purell.

Example: 

normalised, err := NormaliseURL("https://www.example.com:443/path?a=1&b=2", RemoveWWW())
// normalised == "https://example.com/path?a=1&b=2"

normalised, err = NormaliseURL("https://api.example.com/v1/users", IgnoreScheme(), IgnoreHost())
// normalised == "/v1/users"

References:

func SplitPath 

func SplitPath(p string) []string

SplitPath returns a slice containing the individual segments that make up the path string p. It looks for the default forward slash path separator when splitting.

func ValidatePathParameter 

func ValidatePathParameter(parameter string) error

ValidatePathParameter checks whether a path parameter is valid. An error is returned if it is invalid. Version 3.1.0 of the OpenAPI spec provides some guidance for path parameter values (see https://spec.openapis.org/oas/v3.1.0.html#path-templating)

Types

type NormalisationOption added in v1.166.0 

type NormalisationOption func(*NormalisationOptions) *NormalisationOptions

NormalisationOption configures NormalisationOptions.

func CaseSensitive added in v1.166.0 

func CaseSensitive() NormalisationOption

CaseSensitive preserves the original scheme and host casing.

func IgnoreDefaultPort added in v1.166.0 

func IgnoreDefaultPort() NormalisationOption

IgnoreDefaultPort removes the default port for recognised schemes.

func IgnoreFragment added in v1.166.0 

func IgnoreFragment() NormalisationOption

IgnoreFragment removes the fragment from the canonical form.

func IgnoreHost added in v1.166.0 

func IgnoreHost() NormalisationOption

IgnoreHost removes the URL host from the canonical form.

func IgnoreQuery added in v1.166.0 

func IgnoreQuery() NormalisationOption

IgnoreQuery removes the query string from the canonical form.

func IgnoreScheme added in v1.166.0 

func IgnoreScheme() NormalisationOption

IgnoreScheme removes the URL scheme from the canonical form.

func RemoveTrailingSlash added in v1.166.0 

func RemoveTrailingSlash() NormalisationOption

RemoveTrailingSlash strips trailing slashes from non-root paths.

func RemoveUserInfo added in v1.166.0 

func RemoveUserInfo() NormalisationOption

RemoveUserInfo removes any user info from the canonical form.

func RemoveWWW added in v1.166.0 

func RemoveWWW() NormalisationOption

RemoveWWW removes a leading `www.` label from the URL host.

func WithClean added in v1.166.0 

func WithClean() NormalisationOption

WithClean applies a clean-up pass broadly equivalent to purell's `FlagRemoveUnnecessaryHostDots`, `FlagRemoveDotSegments`, `FlagRemoveDuplicateSlashes`, `FlagUppercaseEscapes`, `FlagDecodeUnnecessaryEscapes`, `FlagEncodeNecessaryEscapes`, `FlagRemoveEmptyQuerySeparator`, and `FlagRemoveEmptyPortSeparator`, plus removal of empty query values.

func WithDecode added in v1.166.0 

func WithDecode() NormalisationOption

WithDecode applies a decode-oriented pass roughly equivalent to purell's `FlagUppercaseEscapes`, `FlagDecodeUnnecessaryEscapes`, and `FlagEncodeNecessaryEscapes`.

func WithLowercaseHost added in v1.166.0 

func WithLowercaseHost() NormalisationOption

WithLowercaseHost lower-cases the URL host in the canonical form.

func WithLowercaseScheme added in v1.166.0 

func WithLowercaseScheme() NormalisationOption

WithLowercaseScheme lower-cases the URL scheme in the canonical form.

func WithSortQuery added in v1.166.0 

func WithSortQuery() NormalisationOption

WithSortQuery sorts query parameters in the canonical form.

func WithoutClean added in v1.166.0 

func WithoutClean() NormalisationOption

WithoutClean disables the clean-up pass enabled by default.

func WithoutDecode added in v1.166.0 

func WithoutDecode() NormalisationOption

WithoutDecode disables the decode-oriented pass enabled by default.

func WithoutIgnoringDefaultPort added in v1.166.0 

func WithoutIgnoringDefaultPort() NormalisationOption

WithoutIgnoringDefaultPort preserves explicit default ports.

func WithoutIgnoringFragment added in v1.166.0 

func WithoutIgnoringFragment() NormalisationOption

WithoutIgnoringFragment preserves the fragment in the canonical form.

func WithoutIgnoringHost added in v1.166.0 

func WithoutIgnoringHost() NormalisationOption

WithoutIgnoringHost preserves the URL host in the canonical form.

func WithoutIgnoringQuery added in v1.166.0 

func WithoutIgnoringQuery() NormalisationOption

WithoutIgnoringQuery preserves the query string in the canonical form.

func WithoutIgnoringScheme added in v1.166.0 

func WithoutIgnoringScheme() NormalisationOption

WithoutIgnoringScheme preserves the URL scheme in the canonical form.

func WithoutLower added in v1.166.0 

func WithoutLower() NormalisationOption

WithoutLower preserves the original scheme and host casing.

func WithoutLowercaseHost added in v1.166.0 

func WithoutLowercaseHost() NormalisationOption

WithoutLowercaseHost preserves the original host casing.

func WithoutLowercaseScheme added in v1.166.0 

func WithoutLowercaseScheme() NormalisationOption

WithoutLowercaseScheme preserves the original scheme casing.

func WithoutSortQuery added in v1.166.0 

func WithoutSortQuery() NormalisationOption

WithoutSortQuery preserves the original query parameter order.

type NormalisationOptions added in v1.166.0 

type NormalisationOptions struct {
	Clean               bool
	Decode              bool
	IgnoreHost          bool
	IgnoreScheme        bool
	IgnoreQuery         bool
	IgnoreFragment      bool
	IgnoreTrailingSlash bool
	IgnoreDefaultPort   bool
	LowercaseScheme     bool
	LowercaseHost       bool
	RemoveWWW           bool
	SortQuery           bool
	RemoveUserInfo      bool
}

NormalisationOptions controls how a URL is canonicalised before comparison.

The available switches are loosely inspired by the purell library.

References:

func DefaultCanonicalForm added in v1.166.0 

func DefaultCanonicalForm() *NormalisationOptions

DefaultCanonicalForm returns the package's default URL canonical form.

The defaults are aligned broadly with goware/urlx's normalisation behaviour: schemes and host names are lower-cased, default ports are removed, query parameters are sorted, escape sequences are normalised, and the URL is passed through the package's clean-up pass.

Reference:

func WithCanonicalOptions added in v1.166.0 

func WithCanonicalOptions(options ...NormalisationOption) *NormalisationOptions

WithCanonicalOptions materialises the effective canonical-form options after applying the supplied functional options to the package defaults.

Example: 

options := WithCanonicalOptions(WithoutClean(), IgnoreFragment(), RemoveWWW())
// options.Clean == false, options.IgnoreFragment == true, options.RemoveWWW == true

type PathSegmentMatcherFunc 

type PathSegmentMatcherFunc = func(segmentA, segmentB string) (match bool, err error)

PathSegmentMatcherFunc defines the signature for path segment matcher functions.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.