silk.url.host.

When to use#

Use UrlHost.parse to check and normalize a host name outside a full URL, such as the Host of a request. silk.url.url calls it for every URL.

Details#

A host of a special URL, such as http, is percent-decoded and converted with UTS #46 (see silk.text.idna). A domain that ends in a number is an IPv4 address, which can be written in decimal, octal, or hexadecimal parts. A host in brackets is an IPv6 address. The host of a URL that is not special is opaque: it is only checked and percent-encoded.

Examples#

Normalize hosts#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.core.option { Option }
import silk.collections.bytes { Bytes }
import silk.url.host { UrlHost, UrlHostKind }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut output = Bytes.make()
  let kind = run UrlHost.parse(b"0x7f.1", false, &mut output)
    |> Effect.provideMut<Allocator>(&mut allocator)
  let ipv4 = match kind {
    Option<UrlHostKind>.Some { value } => value == UrlHostKind.Ipv4
    Option<UrlHostKind>.None => false
  }
  if !ipv4 || Bytes.asSlice(&output) != b"127.0.0.1" {
    return 1
  }
  return 0
}

Import as UrlHost with import silk.url.host { UrlHost }.

Public declarations: 2.

UrlHostKind#

pub enum UrlHostKind

The kind of the host of a URL.

Absent#

Absent

The URL has no host, such as mailto:a@example.com.

Domain#

Domain

A domain, in ASCII: example.com.

Ipv4#

Ipv4

An IPv4 address, serialized in dotted decimal: 127.0.0.1.

Ipv6#

Ipv6

An IPv6 address, serialized in brackets: [::1].

Opaque#

Opaque

The host of a URL that is not special, percent-encoded: host in git://host/repo.

Empty#

Empty

An empty host, such as the host of file:///tmp.

UrlHost#

pub struct UrlHost

Functions that parse and serialize URL hosts.

Implementation UrlHost#

impl UrlHost

Associated function parse#

pub effect fn parse(input: &[u8], opaque: bool, output: &mut Bytes) -> Option<UrlHostKind>
    ! OutOfMemoryError
    ? &mut Allocator

Parses input as the host of a URL and appends its serialization to output. Returns the kind of the host, or None if input is not a valid host.

Details#

opaque is true for the host of a URL that is not special. Then input is checked for forbidden host code points and percent-encoded, unless it is an IPv6 address in brackets. Otherwise input is percent-decoded, converted to ASCII, and read as an IPv4 address when it ends in a number. An empty input gives Empty only when opaque is true. On failure, output can hold a part of the result.

Errors#

• OutOfMemoryError if the Allocator fails.

Associated function domainToAscii#

pub effect fn domainToAscii(domain: string, output: &mut Bytes) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Converts domain to ASCII as the URL Standard's domain to ASCII does, and appends it to output. Returns false if domain is not a valid domain.

Details#

ASCII input is only lowercased. Other input goes through UTS #46 ToASCII with the bidi and joiner checks. An empty result, or one with a forbidden domain code point, is not valid. On failure, output can hold a part of the result.

Errors#

• OutOfMemoryError if the Allocator fails.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.