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(port: int, host: String = "127.0.0.1") -> boolfree_port(from: int = 0, host: String = "127.0.0.1") -> int, Errresolve(host: String) -> String, Errresolve_async(host: String) -> await String, Errdial_tcp(host: String, port: int, opts: Dictionary = { }) -> GDTCPConn, Errdial_tcp_async(host: String, port: int, opts: Dictionary = { }) -> await GDTCPConn, Errdial_tls(host: String, port: int, opts: Dictionary = { }) -> GDTCPConn, Errdial_tls_async(host: String, port: int, opts: Dictionary = { }) -> await GDTCPConn, Errlisten_tcp(host: String = "127.0.0.1", port: int = 0) -> GDTCPListener, Errlisten_udp(host: String = "127.0.0.1", port: int = 0, buffer: int = 0) -> GDUDPPacketConn, Erris_free_async(port: int, host: String = "127.0.0.1") -> await boolfree_port_async(from: int = 0, host: String = "127.0.0.1") -> await int, Errlocal_addresses() -> PackedStringArray, Errlocal_addresses_async() -> await PackedStringArray, Erris_ip(text: String) -> boolsplit_host(text: String, default_port: int = 80) -> Dictionary
is_free
is_free(port: int, host: String = "127.0.0.1") -> boolCheck whether a host port is available for listening.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
host | String | "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, ErrLet the kernel choose for zero, or search from the specified positive port.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
from | int | 0 | Starting port to search; zero asks the OS to select a free port. |
host | String | "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, ErrResolve a hostname outside the event loop.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | Required | Hostname 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, ErrResolve a hostname outside the event loop.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | Required | Hostname 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, ErrOpen a TCP connection while suspending only the caller during connection setup.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | Required | Hostname or IP address used for connecting or binding. |
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
opts | Dictionary | { } | 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, ErrOpen a TCP connection while suspending only the caller during connection setup.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | Required | Hostname or IP address used for connecting or binding. |
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
opts | Dictionary | { } | 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, ErrOpen 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
| Name | Type | Default | Description |
|---|---|---|---|
host | String | Required | Hostname or IP address used for connecting or binding. |
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
opts | Dictionary | { } | 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, ErrOpen a verified TLS connection while suspending only the caller during setup.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | Required | Hostname or IP address used for connecting or binding. |
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
opts | Dictionary | { } | 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, ErrOpen TCP listeners and UDP packet connections.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | "127.0.0.1" | Hostname or IP address used for connecting or binding. |
port | int | 0 | Network 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, ErrBind a UDP socket to the requested local host and port with the supplied receive-buffer size.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
host | String | "127.0.0.1" | Hostname or IP address used for connecting or binding. |
port | int | 0 | Network port number. A listening port of zero lets the OS select a port. |
buffer | int | 0 | Requested 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 boolDispatch port checks and discovery to I/O workers.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
port | int | Required | Network port number. A listening port of zero lets the OS select a port. |
host | String | "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, ErrLet the kernel choose for zero, or search from the specified positive port.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
from | int | 0 | Starting port to search; zero asks the OS to select a free port. |
host | String | "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, ErrEnumerate 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, ErrEnumerate 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) -> boolCheck whether text is an IP address.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
text | String | Required | Text 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) -> DictionarySplit a host and port.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
text | String | Required | Text to inspect, decode or transform; the input is not modified in place. |
default_port | int | 80 | Port 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.