Imports #
"errors"
"fmt"
"maps"
"path"
"slices"
"strconv"
"strings"
_ "unsafe"
url
Imports
Constants & Variables
encodeFragment const #
const encodeFragmentencodeHost const #
const encodeHostencodePath const #
const encodePath encoding = *ast.BinaryExprencodePathSegment const #
const encodePathSegmentencodeQueryComponent const #
const encodeQueryComponentencodeUserPassword const #
const encodeUserPasswordencodeZone const #
const encodeZoneupperhex const #
const upperhex = "0123456789ABCDEF"Type Aliases
EscapeError type #
type EscapeError stringInvalidHostError type #
type InvalidHostError stringValues type #
Values maps a string key to a list of values. It is typically used for query parameters and form values. Unlike in the http.Header map, the keys in a Values map are case-sensitive.
type Values map[string][]stringencoding type #
type encoding intStructs
Error struct #
Error reports an error and the operation and URL that caused it.
type Error struct {
Op string
URL string
Err error
}URL struct #
A URL represents a parsed URL (technically, a URI reference). The general form represented is: [scheme:][//[userinfo@]host][/]path[?query][#fragment] URLs that do not start with a slash after the scheme are interpreted as: scheme:opaque[?query][#fragment] The Host field contains the host and port subcomponents of the URL. When the port is present, it is separated from the host with a colon. When the host is an IPv6 address, it must be enclosed in square brackets: "[fe80::1]:80". The [net.JoinHostPort] function combines a host and port into a string suitable for the Host field, adding square brackets to the host when necessary. Note that the Path field is stored in decoded form: /%47%6f%2f becomes /Go/. A consequence is that it is impossible to tell which slashes in the Path were slashes in the raw URL and which were %2f. This distinction is rarely important, but when it is, the code should use the [URL.EscapedPath] method, which preserves the original encoding of Path. The RawPath field is an optional field which is only set when the default encoding of Path is different from the escaped path. See the EscapedPath method for more details. URL's String method uses the EscapedPath method to obtain the path.
type URL struct {
Scheme string
Opaque string
User *Userinfo
Host string
Path string
RawPath string
OmitHost bool
ForceQuery bool
RawQuery string
Fragment string
RawFragment string
}Userinfo struct #
The Userinfo type is an immutable encapsulation of username and password details for a [URL]. An existing Userinfo value is guaranteed to have a username set (potentially empty, as allowed by RFC 2396), and optionally a password.
type Userinfo struct {
username string
password string
passwordSet bool
}Functions
Add method #
Add adds the value to key. It appends to any existing values associated with key.
func (v Values) Add(key string, value string)AppendBinary method #
func (u *URL) AppendBinary(b []byte) ([]byte, error)Del method #
Del deletes the values associated with key.
func (v Values) Del(key string)Encode method #
Encode encodes the values into “URL encoded” form ("bar=baz&foo=quux") sorted by key.
func (v Values) Encode() stringError method #
func (e EscapeError) Error() stringError method #
func (e InvalidHostError) Error() stringError method #
func (e *Error) Error() stringEscapedFragment method #
EscapedFragment returns the escaped form of u.Fragment. In general there are multiple possible escaped forms of any fragment. EscapedFragment returns u.RawFragment when it is a valid escaping of u.Fragment. Otherwise EscapedFragment ignores u.RawFragment and computes an escaped form on its own. The [URL.String] method uses EscapedFragment to construct its result. In general, code should call EscapedFragment instead of reading u.RawFragment directly.
func (u *URL) EscapedFragment() stringEscapedPath method #
EscapedPath returns the escaped form of u.Path. In general there are multiple possible escaped forms of any path. EscapedPath returns u.RawPath when it is a valid escaping of u.Path. Otherwise EscapedPath ignores u.RawPath and computes an escaped form on its own. The [URL.String] and [URL.RequestURI] methods use EscapedPath to construct their results. In general, code should call EscapedPath instead of reading u.RawPath directly.
func (u *URL) EscapedPath() stringGet method #
Get gets the first value associated with the given key. If there are no values associated with the key, Get returns the empty string. To access multiple values, use the map directly.
func (v Values) Get(key string) stringHas method #
Has checks whether a given key is set.
func (v Values) Has(key string) boolHostname method #
Hostname returns u.Host, stripping any valid port number if present. If the result is enclosed in square brackets, as literal IPv6 addresses are, the square brackets are removed from the result.
func (u *URL) Hostname() stringIsAbs method #
IsAbs reports whether the [URL] is absolute. Absolute means that it has a non-empty scheme.
func (u *URL) IsAbs() boolJoinPath method #
JoinPath returns a new [URL] with the provided path elements joined to any existing path and the resulting path cleaned of any ./ or ../ elements. Any sequences of multiple / characters will be reduced to a single /.
func (u *URL) JoinPath(elem ...string) *URLJoinPath function #
JoinPath returns a [URL] string with the provided path elements joined to the existing path of base and the resulting path cleaned of any ./ or ../ elements.
func JoinPath(base string, elem ...string) (result string, err error)MarshalBinary method #
func (u *URL) MarshalBinary() (text []byte, err error)Parse method #
Parse parses a [URL] in the context of the receiver. The provided URL may be relative or absolute. Parse returns nil, err on parse failure, otherwise its return value is the same as [URL.ResolveReference].
func (u *URL) Parse(ref string) (*URL, error)Parse function #
Parse parses a raw url into a [URL] structure. The url may be relative (a path, without a host) or absolute (starting with a scheme). Trying to parse a hostname and path without a scheme is invalid but may not necessarily return an error, due to parsing ambiguities.
func Parse(rawURL string) (*URL, error)ParseQuery function #
ParseQuery parses the URL-encoded query string and returns a map listing the values specified for each key. ParseQuery always returns a non-nil map containing all the valid query parameters found; err describes the first decoding error encountered, if any. Query is expected to be a list of key=value settings separated by ampersands. A setting without an equals sign is interpreted as a key set to an empty value. Settings containing a non-URL-encoded semicolon are considered invalid.
func ParseQuery(query string) (Values, error)ParseRequestURI function #
ParseRequestURI parses a raw url into a [URL] structure. It assumes that url was received in an HTTP request, so the url is interpreted only as an absolute URI or an absolute path. The string url is assumed not to have a #fragment suffix. (Web browsers strip #fragment before sending the URL to a web server.)
func ParseRequestURI(rawURL string) (*URL, error)Password method #
Password returns the password in case it is set, and whether it is set.
func (u *Userinfo) Password() (string, bool)PathEscape function #
PathEscape escapes the string so it can be safely placed inside a [URL] path segment, replacing special characters (including /) with %XX sequences as needed.
func PathEscape(s string) stringPathUnescape function #
PathUnescape does the inverse transformation of [PathEscape], converting each 3-byte encoded substring of the form "%AB" into the hex-decoded byte 0xAB. It returns an error if any % is not followed by two hexadecimal digits. PathUnescape is identical to [QueryUnescape] except that it does not unescape '+' to ' ' (space).
func PathUnescape(s string) (string, error)Port method #
Port returns the port part of u.Host, without the leading colon. If u.Host doesn't contain a valid numeric port, Port returns an empty string.
func (u *URL) Port() stringQuery method #
Query parses RawQuery and returns the corresponding values. It silently discards malformed value pairs. To check errors use [ParseQuery].
func (u *URL) Query() ValuesQueryEscape function #
QueryEscape escapes the string so it can be safely placed inside a [URL] query.
func QueryEscape(s string) stringQueryUnescape function #
QueryUnescape does the inverse transformation of [QueryEscape], converting each 3-byte encoded substring of the form "%AB" into the hex-decoded byte 0xAB. It returns an error if any % is not followed by two hexadecimal digits.
func QueryUnescape(s string) (string, error)Redacted method #
Redacted is like [URL.String] but replaces any password with "xxxxx". Only the password in u.User is redacted.
func (u *URL) Redacted() stringRequestURI method #
RequestURI returns the encoded path?query or opaque?query string that would be used in an HTTP request for u.
func (u *URL) RequestURI() stringResolveReference method #
ResolveReference resolves a URI reference to an absolute URI from an absolute base URI u, per RFC 3986 Section 5.2. The URI reference may be relative or absolute. ResolveReference always returns a new [URL] instance, even if the returned URL is identical to either the base or reference. If ref is an absolute URL, then ResolveReference ignores base and returns a copy of ref.
func (u *URL) ResolveReference(ref *URL) *URLSet method #
Set sets the key to value. It replaces any existing values.
func (v Values) Set(key string, value string)String method #
String reassembles the [URL] into a valid URL string. The general form of the result is one of: scheme:opaque?query#fragment scheme://userinfo@host/path?query#fragment If u.Opaque is non-empty, String uses the first form; otherwise it uses the second form. Any non-ASCII characters in host are escaped. To obtain the path, String uses u.EscapedPath(). In the second form, the following rules apply: - if u.Scheme is empty, scheme: is omitted. - if u.User is nil, userinfo@ is omitted. - if u.Host is empty, host/ is omitted. - if u.Scheme and u.Host are empty and u.User is nil, the entire scheme://userinfo@host/ is omitted. - if u.Host is non-empty and u.Path begins with a /, the form host/path does not add its own /. - if u.RawQuery is empty, ?query is omitted. - if u.Fragment is empty, #fragment is omitted.
func (u *URL) String() stringString method #
String returns the encoded userinfo information in the standard form of "username[:password]".
func (u *Userinfo) String() stringTemporary method #
func (e *Error) Temporary() boolTimeout method #
func (e *Error) Timeout() boolUnmarshalBinary method #
func (u *URL) UnmarshalBinary(text []byte) errorUnwrap method #
func (e *Error) Unwrap() errorUser function #
User returns a [Userinfo] containing the provided username and no password set.
func User(username string) *UserinfoUserPassword function #
UserPassword returns a [Userinfo] containing the provided username and password. This functionality should only be used with legacy web sites. RFC 2396 warns that interpreting Userinfo this way “is NOT RECOMMENDED, because the passing of authentication information in clear text (such as URI) has proven to be a security risk in almost every case where it has been used.”
func UserPassword(username string, password string) *UserinfoUsername method #
Username returns the username.
func (u *Userinfo) Username() stringbadSetPath function #
for linkname because we cannot linkname methods directly
func badSetPath(*URL, string) errorescape function #
func escape(s string, mode encoding) stringgetScheme function #
Maybe rawURL is of the form scheme:path. (Scheme must be [a-zA-Z][a-zA-Z0-9+.-]*) If so, return scheme, path; else return "", rawURL.
func getScheme(rawURL string) (scheme string, path string, err error)ishex function #
func ishex(c byte) boolparse function #
parse parses a URL from a string in one of two contexts. If viaRequest is true, the URL is assumed to have arrived via an HTTP request, in which case only absolute URLs or path-absolute relative URLs are allowed. If viaRequest is false, all forms of relative URLs are allowed.
func parse(rawURL string, viaRequest bool) (*URL, error)parseAuthority function #
func parseAuthority(authority string) (user *Userinfo, host string, err error)parseHost function #
parseHost parses host as an authority without user information. That is, as host[:port].
func parseHost(host string) (string, error)parseQuery function #
func parseQuery(m Values, query string) (err error)resolvePath function #
resolvePath applies special path segments from refs and applies them to base, per RFC 3986.
func resolvePath(base string, ref string) stringsetFragment method #
setFragment is like setPath but for Fragment/RawFragment.
func (u *URL) setFragment(f string) errorsetPath method #
setPath sets the Path and RawPath fields of the URL based on the provided escaped path p. It maintains the invariant that RawPath is only specified when it differs from the default encoding of the path. For example: - setPath("/foo/bar") will set Path="/foo/bar" and RawPath="" - setPath("/foo%2fbar") will set Path="/foo/bar" and RawPath="/foo%2fbar" setPath will return an error only if the provided path contains an invalid escaping. setPath should be an internal detail, but widely used packages access it using linkname. Notable members of the hall of shame include: - github.com/sagernet/sing Do not remove or change the type signature. See go.dev/issue/67401. go:linkname badSetPath net/url.(*URL).setPath
func (u *URL) setPath(p string) errorshouldEscape function #
Return true if the specified character should be escaped when appearing in a URL string, according to RFC 3986. Please be informed that for now shouldEscape does not check all reserved characters correctly. See golang.org/issue/5684.
func shouldEscape(c byte, mode encoding) boolsplitHostPort function #
splitHostPort separates host and port. If the port is not valid, it returns the entire input as host, and it doesn't check the validity of the host. Unlike net.SplitHostPort, but per RFC 3986, it requires ports to be numeric.
func splitHostPort(hostPort string) (host string, port string)stringContainsCTLByte function #
stringContainsCTLByte reports whether s contains any ASCII control character.
func stringContainsCTLByte(s string) boolunescape function #
unescape unescapes a string; the mode specifies which section of the URL string is being unescaped.
func unescape(s string, mode encoding) (string, error)unhex function #
func unhex(c byte) bytevalidEncoded function #
validEncoded reports whether s is a valid encoded path or fragment, according to mode. It must not contain any bytes that require escaping during encoding.
func validEncoded(s string, mode encoding) boolvalidOptionalPort function #
validOptionalPort reports whether port is either an empty string or matches /^:\d*$/
func validOptionalPort(port string) boolvalidUserinfo function #
validUserinfo reports whether s is a valid userinfo string per RFC 3986 Section 3.2.1: userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" It doesn't validate pct-encoded. The caller does that via func unescape.
func validUserinfo(s string) boolGenerated with Arrow