URI

This module defines the URI and RequestTarget types that represent and manipulate components of URIs as defined by RFC 3986. It provides parsing, rendering, and normalization utilities for working with URIs and request targets in HTTP messages.

References:

• https://www.rfc-editor.org/rfc/rfc3986.html
• https://www.rfc-editor.org/rfc/rfc9112.html#section-3.3

@[inline]

def Std.Http.RequestTarget.parse? (string : String) : Option RequestTarget

Attempts to parse a RequestTarget from the given string.

Equations

• Std.Http.RequestTarget.parse? string = ((Std.Http.URI.Parser.parseRequestTarget <* Std.Internal.Parsec.eof).run string.toUTF8).toOption

@[inline]

def Std.Http.RequestTarget.parse! (string : String) : RequestTarget

Parses a RequestTarget from the given string. Panics if parsing fails. Use parse? if you need a safe option-returning version.

Equations

• One or more equations did not get rendered due to their size.

@[inline]

def Std.Http.RequestTarget.originForm! (path : String) : RequestTarget

Creates an origin-form request target from a path string. The path should start with '/' (e.g., "/api/users" or "/search?q=test"). Panics if the string is not a valid origin-form request target.

Equations

• One or more equations did not get rendered due to their size.

def Std.Http.RequestTarget.pathOrRoot : RequestTarget → URI.Path

Returns the path component of the request target, defaulting to the root path / when the target carries no path (asterisk-form or authority-form). Unlike RequestTarget.path, the fallback is the absolute root rather than an empty relative path — used by clients that need a well-formed absolute path for cookie matching or logging.

Equations

• (Std.Http.RequestTarget.originForm p query).pathOrRoot = p
• (Std.Http.RequestTarget.absoluteForm uri).pathOrRoot = uri.path
• x✝.pathOrRoot = { segments := #[], absolute := true }

def Std.Http.RequestTarget.setQueryParam (target : RequestTarget) (key value : String) : RequestTarget

Inserts or appends a query parameter on this target, preserving its form. Origin-form and absolute-form targets gain the parameter on their existing query; authority-form and asterisk-form targets are returned unchanged because they do not carry a query.

Equations

• One or more equations did not get rendered due to their size.
• (Std.Http.RequestTarget.originForm p query).setQueryParam key value = Std.Http.RequestTarget.originForm p (some ((query.getD Std.Http.URI.Query.empty).insert key value))
• target.setQueryParam key value = target

@[inline]

def Std.Http.URIReference.parse? (string : String) : Option URIReference

Attempts to parse a URIReference from the given string.

Accepts both complete URIs (with scheme) and relative references (without scheme), per RFC 3986 §4.1. Relative references include protocol-relative (//host/path), absolute-path (/path), path-noscheme (../other, foo/bar), query-only (?q=1), fragment-only (#sec), and empty.

Equations

• Std.Http.URIReference.parse? string = ((Std.Http.URI.Parser.parseURIReference <* Std.Internal.Parsec.eof).run string.toUTF8).toOption

@[inline]

def Std.Http.URIReference.parse! (string : String) : URIReference

Parses a URIReference from the given string. Panics if parsing fails. Use parse? if you need a safe option-returning version.

Equations

• One or more equations did not get rendered due to their size.

def Std.Http.URI.port (uri : URI) : UInt16

Extracts the numeric port this URI addresses. When the authority omits the port (or parses as empty) the scheme's default port is returned (80 for http, 443 for https).

Equations

• uri.port = match uri.authority with | some auth => match auth.port with | Std.Http.URI.Port.value p => p | x => uri.scheme.defaultPort | none => uri.scheme.defaultPort

def Std.Http.URI.host? (uri : URI) : Option Host

The host this URI addresses, or none when the URI carries no authority.

A URI without an authority cannot identify an origin to connect to, so callers that need to dispatch a request should treat none as malformed input rather than substituting a default host.

Equations

• uri.host? = Option.map (fun (x : Std.Http.URI.Authority) => x.host) uri.authority

def Std.Http.URI.originTarget (uri : URI) : RequestTarget

Returns the origin-form request target corresponding to this URI, dropping the scheme, authority, user-info, and fragment while preserving the query component.

Reference: https://httpwg.org/specs/rfc9112.html#section-3.2.1

Equations

• uri.originTarget = Std.Http.RequestTarget.originForm uri.path uri.query

@[inline]

def Std.Http.URI.parse? (string : String) : Option URI

Attempts to parse a URI from the given string.

Equations

• Std.Http.URI.parse? string = ((Std.Http.URI.Parser.parseURI <* Std.Internal.Parsec.eof).run string.toUTF8).toOption

@[inline]

def Std.Http.URI.parse! (string : String) : URI

Parses a URI from the given string. Panics if parsing fails. Use parse? if you need a safe option-returning version.

Equations

• Std.Http.URI.parse! string = match Std.Http.URI.parse? string with | some res => res | none => panicWithPosWithDecl "Std.Http.Data.URI" "Std.Http.URI.parse!" 157 12 "invalid URI"

@[inline]

def Std.Http.URI.Path.parse? (s : String) : Option Path

Attempts to parse a URI path from the given string. Returns none if the string is not a valid path.

Equations

• Std.Http.URI.Path.parse? s = ((Std.Http.URI.Parser.parsePath { } true true <* Std.Internal.Parsec.eof).run s.toUTF8).toOption

@[inline]

def Std.Http.URI.Path.parseOrRoot (s : String) : Path

Parses a URI path from the given string. Returns the root path "/" if parsing fails.

Equations

• Std.Http.URI.Path.parseOrRoot s = (Std.Http.URI.Path.parse? s).getD { segments := #[], absolute := true }