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.

@[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.

@[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.

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.

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.

@[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.

@[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.

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).

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.

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

@[inline]

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

Attempts to parse a URI from the given string.

@[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.

@[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.

@[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.