gdDocumentation0.8.0

API reference

GD.net

Network entry for TCP and TLS streams, listeners, UDP packets, name resolution, and address checks. TLS verifies the certificate chain and server name by default; waiting operations suspend only their caller.

Methods

is_free

is_free(port: int, host: String = "127.0.0.1") -> bool

Check whether a host port is available for listening.

Parameters

NameTypeDefaultDescription
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.

Return value

bool

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

free_port

free_port(from: int = 0, host: String = "127.0.0.1") -> int, Err

Let the kernel choose for zero, or search from the specified positive port.

Parameters

NameTypeDefaultDescription
fromint0Starting port to search; zero asks the OS to select a free port.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.

Return value

int, Err

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Port 0 is accepted for listening and as the search start. Connection targets and is_free() take 1..65535. The result is a momentary check, not a reservation.

resolve

resolve(host: String) -> String, Err

Resolve a hostname outside the event loop.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.

Return value

String, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Returns the first address chosen by the OS and keeps no name cache.

resolve_async

resolve_async(host: String) -> await String, Err

Resolve a hostname outside the event loop.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.

Return value

await String, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Returns the first address chosen by the OS and keeps no name cache.

dial_tcp

dial_tcp(host: String, port: int, opts: Dictionary = {  }) -> GDTCPConn, Err

Open a TCP connection while suspending only the caller during connection setup.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

GDTCPConn, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

dial_tcp_async

dial_tcp_async(host: String, port: int, opts: Dictionary = {  }) -> await GDTCPConn, Err

Open a TCP connection while suspending only the caller during connection setup.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

await GDTCPConn, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

dial_tls

dial_tls(host: String, port: int, opts: Dictionary = {  }) -> GDTCPConn, Err

Open a verified TLS connection while suspending only the caller during setup.

Dial a verified TLS connection. Options include timeout, server_name, insecure_skip_verify, ca_file, paired cert_file/key_file for client authentication, and next_protos as an array of ALPN strings. File access is permission checked on a worker. Failed authentication never falls back to plaintext.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

GDTCPConn, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

dial_tls_async

dial_tls_async(host: String, port: int, opts: Dictionary = {  }) -> await GDTCPConn, Err

Open a verified TLS connection while suspending only the caller during setup.

Parameters

NameTypeDefaultDescription
hostStringRequiredHostname or IP address used for connecting or binding.
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
optsDictionary{ }Named options for this operation. Omitted entries use their documented defaults.

Return value

await GDTCPConn, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

listen_tcp

listen_tcp(host: String = "127.0.0.1", port: int = 0) -> GDTCPListener, Err

Open TCP listeners and UDP packet connections.

Parameters

NameTypeDefaultDescription
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.
portint0Network port number. A listening port of zero lets the OS select a port.

Return value

GDTCPListener, Err

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

listen_udp

listen_udp(host: String = "127.0.0.1", port: int = 0, buffer: int = 0) -> GDUDPPacketConn, Err

Bind a UDP socket to the requested local host and port with the supplied receive-buffer size.

Parameters

NameTypeDefaultDescription
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.
portint0Network port number. A listening port of zero lets the OS select a port.
bufferint0Requested socket receive-buffer size in bytes.

Return value

GDUDPPacketConn, Err

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

buffer=0 keeps the OS receive buffer as it is; only a positive value requests a change.

is_free_async

is_free_async(port: int, host: String = "127.0.0.1") -> await bool

Dispatch port checks and discovery to I/O workers.

Parameters

NameTypeDefaultDescription
portintRequiredNetwork port number. A listening port of zero lets the OS select a port.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.

Return value

await bool

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

free_port_async

free_port_async(from: int = 0, host: String = "127.0.0.1") -> await int, Err

Let the kernel choose for zero, or search from the specified positive port.

Parameters

NameTypeDefaultDescription
fromint0Starting port to search; zero asks the OS to select a free port.
hostString"127.0.0.1"Hostname or IP address used for connecting or binding.

Return value

await int, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Port 0 is accepted for listening and as the search start. Connection targets and is_free() take 1..65535. The result is a momentary check, not a reservation.

local_addresses

local_addresses() -> PackedStringArray, Err

Enumerate this machine's IP addresses.

Parameters

No parameters.

Return value

PackedStringArray, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

An empty list and an OS failure are distinct results. On failure, e.info carries syscall, source, and source_code.

local_addresses_async

local_addresses_async() -> await PackedStringArray, Err

Enumerate this machine's IP addresses.

Parameters

No parameters.

Return value

await PackedStringArray, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

An empty list and an OS failure are distinct results. On failure, e.info carries syscall, source, and source_code.

is_ip

is_ip(text: String) -> bool

Check whether text is an IP address.

Parameters

NameTypeDefaultDescription
textStringRequiredText to inspect, decode or transform; the input is not modified in place.

Return value

bool

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

split_host

split_host(text: String, default_port: int = 80) -> Dictionary

Split a host and port.

Parameters

NameTypeDefaultDescription
textStringRequiredText to inspect, decode or transform; the input is not modified in place.
default_portint80Port used when the input does not include an explicit port.

Return value

Dictionary

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.