Documentation
¶
Overview ¶
Package nodeurl ports the Node URL host/path handling and fileURLToPath semantics used by PiG.
Index ¶
- func DecodeURIComponent(s string) (string, error)
- func DomainToUnicode(host string) string
- func FileHost(server string) (string, error)
- func FileURLToPath(raw string, windows bool) (string, error)
- func FormURLEncode(value string) string
- func PathToFileURL(path string, windows bool) string
- func PrepareInput(raw string) string
- func RequestURL(serialized string) (*url.URL, error)
- func ResolveDirectoryPath(raw, relativePath string) (string, error)
- func SearchPairs(query string) [][2]string
- func SearchParams(query string) url.Values
- func SpecialHost(server string) (string, error)
- func SpecialPath(pathname string, file bool) string
- type Error
- type HTTPHref
- type HTTPURL
- type URL
- func (u URL) Href() string
- func (u URL) Origin() string
- func (u URL) ResolveAbsolutePath(path string) (string, error)
- func (u URL) ResolveRelativePath(ref string) (URL, error)
- func (u URL) String() string
- func (u URL) WithPathname(path string) string
- func (u URL) WithPort(port string) URL
- func (u URL) WithQuery(query string) URL
- func (u URL) WithSearch(query string) string
- func (u URL) WithSearchParam(name, value string) string
- func (u URL) WithoutCredentials() URL
- func (u URL) WithoutFragment() URL
- func (u URL) WithoutHash() URL
- func (u URL) WithoutQuery() URL
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeURIComponent ¶
DecodeURIComponent is JavaScript's decodeURIComponent: every %XX becomes its byte, and a malformed escape or invalid UTF-8 is a URIError.
func DomainToUnicode ¶
DomainToUnicode is Node's url.domainToUnicode for a host FileHost returned: an IP address is unchanged, and a domain's IDNA labels become Unicode. As in ada's to_unicode, which never fails, a label that starts with "xn--" is decoded only when it is ASCII, decodes as Punycode to a non-empty non-ASCII label that is stable under mapping and normalization and is a valid label; any other label is kept as it is.
func FileHost ¶
FileHost is the WHATWG host parser's result for a file URL's host: an IPv6 address in brackets, a dotted IPv4 address, or a lowercase ASCII domain, where localhost is empty. The input is percent-decoded first, as the parser does.
func FileURLToPath ¶
FileURLToPath converts raw as Node's url.fileURLToPath(raw, {windows}) does: raw is parsed as a WHATWG URL, and a Windows host names a UNC server in Unicode. It returns the Error Node throws for a URL that does not parse, is not a file URL, encodes a path separator, has a host on POSIX, or on Windows has neither a host nor a drive letter.
func FormURLEncode ¶
FormURLEncode is the application/x-www-form-urlencoded byte serializer that `URLSearchParams.toString()` uses: ASCII alphanumerics and "*-._" stay, a space becomes "+", and every other byte is percent-encoded.
func PathToFileURL ¶
PathToFileURL is Node 24.19.0's url.pathToFileURL(path, { windows }).href. It resolves path as path.posix or path.win32 does, keeps a trailing separator, and percent-encodes what Node's encodePathChars and the WHATWG path state encode: C0 controls, space, `"#%<>?[\]^` + "`{|}~", DEL and every non-ASCII byte. A Windows UNC path names the URL's host.
func PrepareInput ¶
PrepareInput applies the URL parser's C0/space trimming and tab/newline removal.
func RequestURL ¶
RequestURL represents an already-resolved WHATWG URL without net/url rewriting its serialized spelling. Opaque retains path characters and malformed percent escapes that Go's RawPath cannot represent; Host and Path still identify the request destination.
func ResolveDirectoryPath ¶
ResolveDirectoryPath is `const base = new URL(raw); base.pathname = base.pathname.replace(/\/+$/u, "") + "/"; new URL(relativePath, base).toString()` for a path-relative reference: the base path becomes a directory (the pathname setter's encoding and dot-segment rules apply), the base query and fragment are dropped, and a base that is not a valid URL, or whose path is opaque, fails as the constructors do.
func SearchPairs ¶
SearchPairs is the list `new URLSearchParams(query)` holds for a query without its leading "?": the decoded name and value of each pair, in order, with repeated names kept.
func SearchParams ¶
SearchParams is `new URLSearchParams(query)` for a query without its leading "?": the application/x-www-form-urlencoded parser. Unlike url.ParseQuery it keeps a pair containing ";" and a malformed percent escape, which it leaves as written, and it decodes each name and value as UTF-8 with replacement.
func SpecialHost ¶
SpecialHost parses the host of a WHATWG special URL. Unlike FileHost, localhost remains a hostname.
func SpecialPath ¶
SpecialPath resolves dot segments in a special URL pathname. File URLs additionally preserve and normalize a leading Windows drive letter.
Types ¶
type Error ¶
Error is an error Node's url.fileURLToPath throws, with its code. URIError comes from decodeURIComponent and has no code.
func (*Error) Thrown ¶
Thrown is String(e) of the error Node throws: its name, code and message, `TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute`, or `URIError: URI malformed` for the decodeURIComponent failure, which has no code. A program that does not catch it reports this headline.
type HTTPHref ¶
type HTTPHref struct {
HTTPURL
// Href is the serialized URL and Origin its origin, as `new URL(raw).href` and `.origin` give them: dot segments
// resolved, the path, query and fragment percent-encoded, the default port and an empty path normalized.
Href string
Origin string
// The embedded Pathname is `new URL(raw).pathname`.
// Username and Password are the percent-encoded userinfo. Query and Fragment are the encoded text after "?" and
// "#", with HasQuery and HasFragment telling an empty one from an absent one.
Username, Password string
Query, Fragment string
HasQuery bool
HasFragment bool
}
HTTPHref is an http or https URL with the serialization of `new URL(raw)`.
func ParseHTTPHref ¶
ParseHTTPHref is ParseHTTPURL with the serialized URL, origin, pathname, userinfo, query and fragment.
type HTTPURL ¶
type HTTPURL struct {
Protocol string
Hostname string
Port string
Pathname string
Search string
Hash string
}
HTTPURL is the part of a WHATWG http or https URL that Node's `new URL(value)` exposes as protocol, hostname, port, pathname, search and hash. Pathname is Node's: dot segments (including "%2e") and backslashes are resolved and the path percent-encode set is applied. Search and Hash keep the raw query and fragment after the "?" or "#": the parser's percent-encoding is not applied, so they equal Node's values only in being empty or not.
func ParseHTTPURL ¶
ParseHTTPURL is `URL.canParse(raw)` and `new URL(raw)` for an http or https URL without a base. It fails for a URL the parser rejects and for any other scheme, which the callers treat alike: they accept only `http:` and `https:`.
type URL ¶
type URL struct {
Protocol string
Username string
Password string
Hostname string
// Port is the serialized port: "" when absent or the default of a special scheme.
Port string
// Pathname is the serialized path: "/..." for a special URL or any URL with a leading slash, the opaque text after "scheme:" for a URL without
// an authority or leading slash, and "" for a host with no path.
Pathname string
// Hash is "#" and the percent-encoded fragment, or "" when the fragment is absent or empty.
Hash string
// Query is the percent-encoded text after "?", as `url.search` gives it without the "?"; `new URLSearchParams(url.search)` and SearchParams(Query) hold the same pairs.
Query string
// contains filtered or unexported fields
}
URL is the part of a WHATWG URL that Node's `new URL(value)` exposes as protocol, username, password, hostname, pathname and hash, for any scheme the parser can read without a base.
func ParseURL ¶
ParseURL is `new URL(raw)` without a base, for every scheme. The special schemes other than file (http, https, ws, wss, ftp) go through the WHATWG special parser, file through the file URL parser, and every other scheme is a non-special URL: "//" starts an authority whose host is opaque (not lowercased, forbidden code points rejected, a bracketed IPv6 address allowed), a leading "/" starts a path, and anything else is an opaque path. It fails where Node throws: a missing or invalid scheme, an invalid host, a port that is not digits or is above 65535, or credentials or a port without a host.
func ResolveURL ¶
ResolveURL is `new URL(input, base)` for a base with a special scheme other than file (http, https, ws, wss, ftp). An input naming another scheme, or a different special one, is parsed on its own with ParseURL; an input naming the base's scheme without an authority is relative to the base. A relative input resolves as the parser's relative state does: "//" and "\\" start an authority, "/" a path, "?" and "#" replace the query or the fragment, and anything else replaces the base path's last segment.
func (URL) Origin ¶
Origin is `url.origin`: scheme, host and port of a special URL other than file; for a blob URL, the origin of the http or https URL its path holds; and "null" for every other URL, file included, whose origin is opaque.
func (URL) ResolveAbsolutePath ¶
ResolveAbsolutePath is `new URL(path, base).toString()` for a path that starts with a single "/" and is already in its serialized form (no dot segments, nothing the path percent-encode set changes): the scheme, userinfo and host of the base, the path, no query and no fragment. A file base whose first path segment starts with a drive letter ("C:", exactly two characters as in ada 4, Node 24.22.1 and 26.12.1; Node 22.19 and 24.19 test only a segment's first two) keeps that segment unless the path starts with a drive letter itself. It fails where the constructor throws: a base whose path is opaque (no authority and no leading slash) cannot be a base.
func (URL) ResolveRelativePath ¶
ResolveRelativePath is `new URL(ref, base)` for a relative path reference, one that has no scheme and does not start with "/", "?" or "#": the base's path up to and including its last "/" followed by ref, parsed again as a URL (dot segments, percent-encoding), with the base's query and fragment dropped. A base whose path is opaque cannot be a base. An empty path counts as "/". A file base whose only path segment is a letter and ":" keeps that segment, as the parser's path shortening does for a Windows drive letter (ada 4, Node 24.22.1 and 26.12.1, take exactly two characters; Node 22.19 and 24.19 take any segment that starts with them).
func (URL) WithPathname ¶
WithPathname is `url.pathname = path; url.toString()`: the href with its path replaced. The path is used as given, as setting it would encode. The setter does nothing to a URL with an opaque path (no authority, and a path that does not start with "/"), so its href is unchanged.
func (URL) WithPort ¶
WithPort is `url.port = port` for a port given as decimal digits: the default port of a special scheme is dropped, and a URL without a host, or a file URL, cannot have one.
func (URL) WithQuery ¶
WithQuery is `url.search = "?" + query` for a query already percent-encoded: the URL with that query.
func (URL) WithSearch ¶
WithSearch is `url.search = query; url.toString()`: the setter removes the query for "", otherwise drops one leading "?" and then every tab and newline (an empty query then serializes as "?"), applies the query percent-encode set (the special one for http, https, ws, wss, ftp and file), and keeps the path and the fragment.
func (URL) WithSearchParam ¶
WithSearchParam is `url.searchParams.set(name, value); url.toString()`: the existing pairs are parsed in order, the first pair named name takes the value and later ones are removed (or the pair is appended), and the query becomes the form serialization of the list. Setting a pair never leaves an empty query.
func (URL) WithoutCredentials ¶
WithoutCredentials is `url.username = ""; url.password = ""`: the URL without its userinfo. A URL that has none, such as every file URL, is unchanged.
func (URL) WithoutFragment ¶
WithoutFragment is `url.hash = ""`: the URL without its fragment, an empty one ("#") included.
func (URL) WithoutHash ¶
WithoutHash is `url.hash = ""`: the URL without its fragment.
func (URL) WithoutQuery ¶
WithoutQuery is `url.search = ""`: the URL without its query, so its href has no "?".