nupp.io.uri

nupp.io.uri parses one absolute URI into an immutable value and returns its components from the parse rather than from a substring. Reach for it when a program routes, rewrites or inspects a resource identifier.

const uri = nupp.io.uri

local endpoint, reason = uri.newURI("https://user@example.com:8443/api?q=1#top")
assert(endpoint, reason)
assert(endpoint:scheme() == "https")
assert(endpoint:host() == "example.com")
assert(endpoint:port() == 8443)

Two URIs are equal when their normalized text is, so a host or scheme written in another case does not make one URI unequal to an otherwise identical one. Nothing has to be closed.

One specification#

Every provider parses as the WHATWG URL Standard does, which is what browsers and both HTTP transports do. What path() returns is therefore the path the request sends: %2e%2e is a dot segment and is resolved, a special scheme's host is lowercased and an IPv4 address written as 0x7f.1 is 127.0.0.1, an empty password is dropped, and spaces, controls and non-ASCII text are percent-encoded as UTF-8:

const uri = nupp.io.uri

local route = assert(uri.newURI("https://example.com/public/%2e%2e/secret"))
assert(route:path() == "/secret")
assert(assert(uri.newURI("http://0x7f.1/")):host() == "127.0.0.1")

A special-scheme host that is not plain ASCII needs the standard's IDNA mapping. The native provider and a browser page's own URL carry it. A target with neither, such as a hostless portable one, parses without it and returns nil and "internationalized host needs a host URL parser" for such a host, including one already written with an xn-- label, rather than guessing.

URI has no public constructor. Creation goes through uri.newURI, which interns the 1024 most recently used normalized URIs. Repeated parsing and URI-producing operations therefore reuse the same immutable value while retention stays bounded.

Reading components#

scheme and path return a string, and path is empty rather than nil when the URI names none. username is empty when there is no user information. Every other component is optional and returns nil when the URI does not write it:

const uri = nupp.io.uri

local plain = assert(uri.newURI("mailto:someone@example.com"))
assert(plain:host() == nil)
assert(plain:port() == nil)
assert(plain:path() == "someone@example.com")

The remaining accessors are authority, password, userInfo, query and fragment. toString returns the normalized complete URI, and tostring(uri) is the same call.

Validating untrusted text#

uri.newURI returns nil and a reason for malformed input, because bad text is an ordinary answer. uri.validate asks the same question without retaining an object, and uri.isURI separates a URI from a string or a record:

const uri = nupp.io.uri

local ok, why = uri.validate("http://[")
assert(not ok and why)
assert(not uri.isURI("https://example.com"))

Deriving a new URI#

Every with operation returns a new URI and leaves the original unchanged. Supplying a component equal to its current normalized value returns the receiver itself rather than reparsing:

const uri = nupp.io.uri

local endpoint = assert(uri.newURI("https://user:pass@example.com:8443/api?q=1"))
local production = endpoint:withUserInfo(nil):withHost("api.example.com")
assert(production:userInfo() == nil)
assert(production:host() == "api.example.com")
assert(endpoint:host() == "example.com")

The operations are withScheme, withUserInfo, withHost, withPort, withPath, withQuery and withFragment. Passing nil removes an optional component. A port must be an integer from 0 through 65535, and anything else raises. So does text that is more than the component: a scheme holding anything but a scheme, a host holding a : outside IPv6 brackets, or a scheme change that would make the rest of the URI parse with a different host.

concatPath appends path text without interpreting it as a reference:

const uri = nupp.io.uri

local api = assert(uri.newURI("https://api.example.com/v1"))
assert(api:concatPath("users"):path() == "/v1/users")

withEndpoint(endpoint) takes another URI's scheme and authority and keeps the receiver's path, query and fragment, which is what reroutes a request URI through a configured service address.

Resolving a reference#

resolve parses a reference against the URI the way a browser resolves a link against the page it is on, by the same standard. A reference that repeats a special scheme without an authority, such as https:other.html, is relative, and \ separates segments where / does in a special scheme. It returns nil and a reason when the reference cannot be resolved:

const uri = nupp.io.uri

local page = assert(uri.newURI("https://example.com/docs/guide/index.html"))
local image, reason = page:resolve("../images/avatar.png")
assert(image, reason)
assert(image:path() == "/docs/images/avatar.png")

Building from components#

uri.newURI also accepts a nupp.io.uri.Components record, built with new like any record. The components are assembled into text and then parsed, so one grammar decides what is valid:

const uri = nupp.io.uri

local status = assert(uri.newURI(new uri.Components(
    scheme = "https",
    userInfo = "reader:secret",
    host = "example.com",
    path = "/status",
    query = "full=1"
)))
assert(status:userInfo() == "reader:secret")

scheme is required and may not be empty. userInfo, host, path, query and fragment are optional strings, and port is an optional integer from 0 through 65535. Every field is URI text rather than a filesystem name.

record Components ...

scheme: string

userInfo: string?

host: string?

port: integer?

path: string?

query: string?

fragment: string?

record URI ...

toString: function toString(self): string

scheme: function scheme(self): string

authority: function authority(self): string?

username: function username(self): string

password: function password(self): string?

host: function host(self): string?

port: function port(self): integer?

path: function path(self): string

query: function query(self): string?

fragment: function fragment(self): string?

userInfo: function userInfo(self): string?

withScheme: function withScheme(self, value: string): URI

withUserInfo: function withUserInfo(self, value: string?): URI

withHost: function withHost(self, value: string?): URI

withPort: function withPort(self, value: integer?): URI

withPath: function withPath(self, value: string): URI

withQuery: function withQuery(self, value: string?): URI

withFragment: function withFragment(self, value: string?): URI

concatPath: function concatPath(self, value: string): URI

resolve: function resolve(self, reference: string): URI?, string?

local page = assert(newURI("https://example.com/docs/a.html"))
assert(assert(page:resolve("b.html")):toString()
    == "https://example.com/docs/b.html")

withEndpoint: function withEndpoint(self, endpoint: URI): URI

__tostring: function(self): string

__eq: function(self, any): boolean

function isURI(value: any): boolean

function newURI(value: string | Components): URI?, string?

const uri = nupp.io.uri

local address = assert(uri.newURI("https://example.com/a?b=1"))
assert(address:host() == "example.com" and address:query() == "b=1")

local endpoint = assert(uri.newURI(new uri.Components(
    scheme = "https",
    host = "example.com",
    path = "/a",
    query = "b=1"
)))

function validate(value: string): boolean, string?