Host

Host names and unresolved host and port endpoints.

A Host is either a numeric IP address, an IPv6 literal with a zone such as fe80::1%eth0, or a DNS domain name. Numeric addresses are parsed directly into NetAddress values. The AddressResolver service turns a HostPort into internet addresses, looking up domain names with the Dns service.

31 exports Since v4.0.0 Source

Constructors

domainNameFromInput

Since v4.0.0

Converts a DomainNameInput to a domain name, parsing and normalizing it like domainNameFromString.

Details

Domain names are strings, so every input is parsed.

Signature

declare function domainNameFromInput(input: DomainNameInput): Result<DomainName, NetAddressError>

hostFromInput

Since v4.0.0

Converts a HostInput to a host, parsing strings like hostFromString and converting other inputs like NetAddress.ipFromInput.

Signature

declare function hostFromInput(input: HostInput): Result<Host, NetAddressError>

hostPort

Since v4.0.0

Creates a checked host and port.

Signature

declare function hostPort(host: Host, port: number): Result<HostPort, NetAddressError>

hostPortFromInput

Since v4.0.0

Converts a HostPortInput to an endpoint, parsing strings like hostPortFromString, converting parts like hostPort, and returning endpoints unchanged.

Signature

declare function hostPortFromInput(input: HostPortInput): Result<HostPort, NetAddressError>

Converting

toFullyQualified

Since v4.0.0

Appends the trailing dot to a domain name, unless it is already fully qualified.

Signature

declare function toFullyQualified(self: DomainName): DomainName

toRelative

Since v4.0.0

Removes the trailing dot of a fully qualified domain name, except from the root name ..

Signature

declare function toRelative(self: DomainName): DomainName

Decoding

domainNameFromString

Since v4.0.0

Parses and normalizes a domain name.

Details

ASCII names are lowercased. Names containing non-ASCII characters are converted to their ASCII (xn--) form using the WHATWG URL host parser, then validated with the same rules as ASCII names. A trailing dot is preserved.

Signature

declare function domainNameFromString(input: string): Result<DomainName, NetAddressError>

Example Normalizing domain names

import { Result } from "effect"
import { Host } from "effect/net"

Result.getOrThrow(Host.domainNameFromString("Example.COM")) // => "example.com"
Result.getOrThrow(Host.domainNameFromString("bücher.example")) // => "xn--bcher-kva.example"
Result.isFailure(Host.domainNameFromString("1.2.3.4")) // => true

hostFromString

Since v4.0.0

Parses a host as a numeric IP address, a scoped IPv6 literal, or a domain name, in that order.

Signature

declare function hostFromString(input: string): Result<Host, NetAddressError>

Example Parsing hosts

import { Result } from "effect"
import { Host, NetAddress } from "effect/net"

NetAddress.isIpAddress(Result.getOrThrow(Host.hostFromString("10.0.0.5"))) // => true
Result.getOrThrow(Host.hostFromString("fe80::1%eth0")) // => "fe80::1%eth0"
Result.getOrThrow(Host.hostFromString("DB.internal")) // => "db.internal"

hostPortFromString

Since v4.0.0

Parses host:port, [IPv6]:port, or [IPv6%zone]:port.

Details

IPv6 hosts must be bracketed and other hosts must not be. The port is required and must be an unpadded decimal integer from 0 through 65535. A zone follows the % directly; the percent-encoded %25 separator of RFC 6874 URLs is not decoded, because [fe80::1%253]:80 would be ambiguous.

See

formatHostPort for the inverse operation

Signature

declare function hostPortFromString(input: string): Result<HostPort, NetAddressError>

Example Parsing host and port strings

import { Result } from "effect"
import { Host } from "effect/net"

const endpoint = Result.getOrThrow(Host.hostPortFromString("DB.internal:5432"))
endpoint.host // => "db.internal"
endpoint.port // => 5432
Host.formatHostPort(Result.getOrThrow(Host.hostPortFromString("[::1]:80"))) // => "[::1]:80"

parseHostsFile

Since v4.0.0

Parses a hosts file into the addresses of each host name. Invalid entries are skipped.

Signature

declare function parseHostsFile(text: string): HostsTable

Example Parsing a hosts file

import { Host, NetAddress } from "effect/net"

const hosts = Host.parseHostsFile(`
127.0.0.1 localhost
::1       localhost ip6-localhost # loopback
`)
hosts.get(Host.domainNameFromStringUnsafe("localhost"))?.map(NetAddress.formatIp) // => ["127.0.0.1", "::1"]

Encoding

formatHost

Since v4.0.0

Formats a host without brackets.

Signature

declare function formatHost(self: Host): string

formatHostPort

Since v4.0.0

Formats a host and port, bracketing IPv6 hosts.

See

hostPortFromString for the inverse operation

Signature

declare function formatHostPort(self: HostPort): string

declare function isHostPort(u: unknown): u is HostPort

Models

DomainName

type

Since v4.0.0

A syntactically valid DNS domain name in lowercase ASCII form.

Details

Names follow the rules used by Go's resolver: at most 253 characters, labels of 1 to 63 letters, digits, hyphens, or underscores, and no label starting or ending with a hyphen. Underscores are allowed so that service names such as _http._tcp.example.com are valid. The last label must not be numeric, which keeps IPv4-like strings out. A trailing dot marks a fully qualified name and is preserved. The root name . is valid.

Internationalized names are stored in their ASCII (xn--) form.

See

domainNameFromString for parsing and normalizing domain names

Signature

type DomainName = Brand.Branded<string, "~effect/net/Host/DomainName">

DomainNameInput

type

Since v4.0.0

A domain name or a string to parse and normalize.

Signature

type DomainNameInput = DomainName | string

Host

type

Since v4.0.0

A host as written in configuration or a URL authority: a numeric IP address, a scoped IPv6 literal, or a domain name.

See

hostFromString for parsing hosts

Signature

type Host = NetAddress.IpAddress | NetAddress.ScopedIpv6Literal | DomainName

HostInput

type

Since v4.0.0

A host, or a string or any IpAddressInput to convert to one.

Signature

type HostInput = Host | NetAddress.IpAddressInput

HostPort

interface

Since v4.0.0

An unresolved host and port.

See

hostPortFromString for parsing host:port strings
formatHostPort for formatting host:port strings

Signature

interface HostPort extends Equal, Hash, Inspectable {
  readonly _tag: "HostPort";
  readonly "~effect/net/Host": "~effect/net/Host";
  readonly host: Host;
  readonly port: number;
}

HostPortInput

type

Since v4.0.0

An endpoint, or a host:port string or parts to convert to one.

Signature

type HostPortInput = HostPort | string | HostPortParts

HostPortParts

interface

Since v4.0.0

The host and port of an endpoint.

See

hostPort for the checked constructor

Signature

interface HostPortParts {
  readonly host: HostInput;
  readonly port: number;
}

HostsTable

type

Since v4.0.0

The addresses of host names, as read from a hosts file.

See

parseHostsFile for reading a hosts file

Signature

type HostsTable = ReadonlyMap<DomainName, Arr.NonEmptyReadonlyArray<NetAddress.IpAddress>>

Predicates

isFullyQualified

Since v4.0.0

Returns true when a domain name ends with a dot, which excludes it from resolver search domains.

Signature

declare function isFullyQualified(self: DomainName): boolean

declare function hostPortUnsafe(host: Host, port: number): HostPort