core.net

DnsRecord : struct {
    address : SocketAddress
    family : AddressFamily
    socket_type : SocketType
    protocol : Protocol
}

DnsHints : struct {
    family : AddressFamily = AddressFamily.Unspecified
    socket_type : SocketType = SocketType.Stream
    protocol : Protocol = Protocol.Default
    passive : bool = false
    numeric_host : bool = false
    numeric_service : bool = false
}

IPAddress : struct {
    family : AddressFamily
    bytes  : [16]u8
}

SocketAddress : struct {
    inline IPAddress
    port : u16
}

Socket : struct {
    handle : posix.SocketHandle = cast<posix.SocketHandle>(-1)
    family : AddressFamily
    socket_type : SocketType
    protocol : Protocol
}

TcpListener : struct {
    socket : Socket
    address : SocketAddress
    backlog : i32
}

dns_resolve : func(host : string, port : u32, allocator : ^Allocator) -> [containers.ArrayList<DnsRecord>, DnsStatus]

Resolves a host and numeric port into connect-ready DNS records.

Parameters:
  host      : string     - DNS name or numeric address. Must not be empty.
  port      : u32        - port in host byte order.
  allocator : ^Allocator - allocator used by the returned ArrayList.

Returns:
  [ArrayList<DnsRecord>, DnsStatus]
    - On success: one or more DNS records and DnsStatus.Ok.
    - On failure: an empty or partial list and the matching DnsStatus.

Notes:
  - The caller owns the returned list and should call DeinitArrayList(&records) when done.
  - Use the service overload when a named service such as "https" is needed.

dns_resolve : func(host : string, service : string, hints : DnsHints, allocator : ^Allocator) -> [containers.ArrayList<DnsRecord>, DnsStatus]

Resolves a host and service using explicit DNS hints.

Parameters:
  host      : string     - DNS name or numeric address. Must not be empty
                           unless DnsHints.passive is true.
  service   : string     - service name or numeric service, such as "443".
  hints     : DnsHints   - address family, socket type, protocol, and flags.
  allocator : ^Allocator - allocator used by the returned ArrayList.

Returns:
  [ArrayList<DnsRecord>, DnsStatus]
    - On success: one or more DNS records and DnsStatus.Ok.
    - On failure: an empty or partial list and the matching DnsStatus.

Notes:
  - The caller owns the returned list and should call DeinitArrayList(&records) when done.

dns_resolve_ip : func(host : string, allocator : ^Allocator) -> [containers.ArrayList<IPAddress>, DnsStatus]

Resolves a host into IP addresses.

Parameters:
  host      : string     - DNS name or numeric address. Must not be empty.
  allocator : ^Allocator - allocator used by the returned ArrayList.

Returns:
  [ArrayList<IPAddress>, DnsStatus]
    - On success: one or more IP addresses and DnsStatus.Ok.
    - On failure: an empty or partial list and the matching DnsStatus.

Notes:
  - The caller owns the returned list and should call DeinitArrayList(&ips) when done.

connect_socket : func(record : DnsRecord) -> [Socket, NetStatus]

Opens and connects a socket using a DNS record.

Parameters:
  record : DnsRecord - DNS result containing address, socket type, and protocol.

Returns:
  [Socket, NetStatus]
    - On success: connected Socket and NetStatus.Ok.
    - On failure: empty Socket and the matching NetStatus.

Notes:
  - The caller owns the returned socket and should call close when done.

dns_connect : func(host : string, port : u32, allocator : ^Allocator) -> [Socket, NetStatus]

Resolves a host and connects to the first reachable DNS record.

Parameters:
  host      : string     - DNS name or numeric address. Must not be empty.
  port      : u32        - port in host byte order.
  allocator : ^Allocator - allocator used for the temporary DNS record list.

Returns:
  [Socket, NetStatus]
    - On success: connected Socket and NetStatus.Ok.
    - On failure: empty Socket and the matching NetStatus.

Notes:
  - The temporary DNS record list is released before returning.
  - The caller owns the returned socket and should call close when done.

parse_ip : func(str : string) -> [IPAddress, NetStatus]

Parses a numeric IPv4 or IPv6 string into an IPAddress.

Parameters:
  str : string - address text, such as "127.0.0.1", "::1", or
                 "2001:db8::1".

Returns:
  [IPAddress, NetStatus]
    - On success: parsed IPAddress and NetStatus.Ok.
    - On failure: empty IPAddress and NetStatus.InvalidAddress.

Notes:
  - This parses numeric addresses only. DNS names should go through a DNS
    resolver API.

SocketAddress : func(address : IPAddress, port : u32) -> [SocketAddress, NetStatus]

Builds a socket address from an IP address and port.

Parameters:
  address : IPAddress - IPv4 or IPv6 address.
  port    : u32       - port in host byte order.

Returns:
  [SocketAddress, NetStatus]
    - On success: the address and NetStatus.Ok.
    - On failure: an empty address and NetStatus.InvalidAddress.

connect_socket : func(address : IPAddress, port : u32, socket_type : SocketType, protocol : Protocol) -> [Socket, NetStatus]

Opens and connects a native socket to the given IP address and port.

Parameters:
  address     : IPAddress  - remote IP address.
  port        : u32        - remote TCP or UDP port in host byte order.
  socket_type : SocketType - stream or datagram socket.
  protocol    : Protocol   - protocol hint; Protocol.Default lets the OS choose.

Returns:
  [Socket, NetStatus]
    - On success: the connected Socket and NetStatus.Ok.
    - On failure: an empty Socket and the matching NetStatus.

Notes:
  - This is the client-side convenience helper. Use Socket.open when you need
    an unconnected socket.
  - The caller owns the returned socket and should call close when done.

open : func(self : ^TcpListener, address : ^IPAddress, port : u32, backlog : i32) -> NetStatus

Opens, binds, and listens on a TCP socket.

Parameters:
  address : ^IPAddress - local IPv4 or IPv6 address to bind.
  port    : u32        - local port in host byte order. Use 0 to ask the
                         OS for an ephemeral port.
  backlog : i32        - listen backlog passed to the native socket API.

Returns:
  NetStatus.Ok on success, or the matching NetStatus on failure.

Notes:
  - Address reuse is enabled before binding.
  - The caller owns the listener and should call close when done.

is_open : func(self : ^TcpListener) -> bool

Reports whether this listener currently owns a native socket handle.

accept : func(self : ^TcpListener) -> [Socket, SocketAddress, NetStatus]

Accepts the next incoming TCP connection.

Returns:
  [Socket, SocketAddress, NetStatus]
    - On success: accepted client socket, peer address, and NetStatus.Ok.
    - On failure: empty values and the matching NetStatus.

close : func(self : ^TcpListener) -> NetStatus

Closes the listener socket.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  listener, or NetStatus.SocketFailed when native close fails.

open : func(self : ^Socket, address : IPAddress, socket_type : SocketType, protocol : Protocol) -> NetStatus

Opens this Socket using the family stored in `address`.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidAddress for an unspecified
  address family, NetStatus.InvalidSocket for a null receiver, or
  NetStatus.SocketFailed when the native socket call fails.

close : func(self : ^Socket) -> NetStatus

Closes this socket handle.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or already
  invalid socket, or NetStatus.SocketFailed when the native close fails.

is_open : func(self : ^Socket) -> bool

Reports whether this Socket currently owns a native handle.

connect : func(self : ^Socket, address : IPAddress, port : u32) -> NetStatus

Connects this socket to an IP address and port.

Parameters:
  self    : ^Socket   - open socket to connect.
  address : IPAddress - remote IP address.
  port    : u32       - remote TCP or UDP port in host byte order.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, NetStatus.InvalidAddress for an unsupported address family or
  family mismatch, or NetStatus.ConnectFailed when native connect fails.

connect : func(self : ^Socket, address : SocketAddress) -> NetStatus

Connects this socket to a socket address.

Parameters:
  self    : ^Socket       - open socket to connect.
  address : SocketAddress - remote address and port. The port is in host
                            byte order and is converted before calling
                            the native API.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, NetStatus.InvalidAddress for an unsupported address family or
  family mismatch, or NetStatus.ConnectFailed when native connect fails.

set_reuse_address : func(self : ^Socket, enabled : bool) -> NetStatus

Enables or disables address reuse on this socket.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, or NetStatus.SocketFailed when the native option call fails.

bind : func(self : ^Socket, address : IPAddress, port : u32) -> NetStatus

Binds this socket to an IP address and port.

Parameters:
  address : IPAddress - local IPv4 or IPv6 address.
  port    : u32       - local port in host byte order. Use 0 to ask the
                        OS for an ephemeral port.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, NetStatus.InvalidAddress for invalid address data, or
  NetStatus.BindFailed when native bind fails.

bind : func(self : ^Socket, address : SocketAddress) -> NetStatus

Binds this socket to a socket address.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, NetStatus.InvalidAddress for invalid address data, or
  NetStatus.BindFailed when native bind fails.

listen : func(self : ^Socket, backlog : i32) -> NetStatus

Marks this socket as a passive listening socket.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, or NetStatus.ListenFailed when native listen fails.

accept : func(self : ^Socket) -> [Socket, SocketAddress, NetStatus]

Accepts the next incoming connection.

Returns:
  [Socket, SocketAddress, NetStatus]
    - On success: accepted socket, peer address, and NetStatus.Ok.
    - On failure: empty values and the matching socket/address/status.

shutdown : func(self : ^Socket, mode : SocketShutdown) -> NetStatus

Disables receive, send, or both directions on this socket.

Returns:
  NetStatus.Ok on success, NetStatus.InvalidSocket for a null or closed
  socket, or NetStatus.SocketFailed when native shutdown fails.

send : func(self : ^Socket, buffer : []u8) -> [i64, NetStatus]

Sends bytes from `buffer` using SocketSendFlags.None.

Returns:
  [i64, NetStatus] - byte count and status.

send : func(self : ^Socket, buffer : []u8, flags : SocketSendFlags) -> [i64, NetStatus]

Sends bytes from `buffer` using socket flags.

Parameters:
  self   : ^Socket        - socket to write to. Must be open.
  buffer : []u8           - source byte buffer.
  flags  : SocketSendFlags - send behavior. SocketSendFlags.None performs
                            a normal send. SocketSendFlags.OOB sends
                            out-of-band data. SocketSendFlags.DontRoute
                            asks the OS to send without routing tables
                            where supported.

Returns:
  [i64, NetStatus]
    - On success: bytes sent and NetStatus.Ok.
    - On failure: -1 and the matching socket or buffer status.

send_to : func(self : ^Socket, buffer : []u8, address : IPAddress, port : u32) -> [i64, NetStatus]

Sends bytes to an IP address and port.

Returns:
  [i64, NetStatus] - byte count and status.

send_to : func(self : ^Socket, buffer : []u8, address : SocketAddress) -> [i64, NetStatus]

Sends bytes to a socket address using SocketSendFlags.None.

Returns:
  [i64, NetStatus] - byte count and status.

send_to_address : func(self : ^Socket, buffer : []u8, address : SocketAddress, flags : SocketSendFlags) -> [i64, NetStatus]

Sends bytes to a socket address using explicit send flags.

Returns:
  [i64, NetStatus]
    - On success: bytes sent and NetStatus.Ok.
    - On failure: -1 and the matching socket, buffer, address, or send status.

receive : func(self : ^Socket, buffer : []u8) -> [i64, NetStatus]

Receives bytes into `buffer` using SocketReceiveFlags.None.

Returns:
  [i64, NetStatus] - byte count and status.

receive : func(self : ^Socket, buffer : []u8, flags : SocketReceiveFlags) -> [i64, NetStatus]

Receives bytes into `buffer` using socket flags.

Parameters:
  self   : ^Socket           - socket to read from. Must be open.
  buffer : []u8              - destination byte buffer.
  flags  : SocketReceiveFlags - receive behavior. SocketReceiveFlags.None
                               performs a normal receive.
                               SocketReceiveFlags.Peek inspects pending
                               data without consuming it.
                               SocketReceiveFlags.OOB receives
                               out-of-band data.

Returns:
  [i64, NetStatus]
    - On success: bytes received and NetStatus.Ok.
    - On graceful close: 0 and NetStatus.Closed.
    - On failure: -1 and the matching socket or buffer status.

receive_from : func(self : ^Socket, buffer : []u8) -> [i64, SocketAddress, NetStatus]

Receives bytes and returns the source socket address using
SocketReceiveFlags.None.

Returns:
  [i64, SocketAddress, NetStatus] - byte count, source address, and status.

receive_from : func(self : ^Socket, buffer : []u8, flags : SocketReceiveFlags) -> [i64, SocketAddress, NetStatus]

Receives bytes and returns the source socket address using explicit
receive flags.

Returns:
  [i64, SocketAddress, NetStatus]
    - On success: bytes received, source address, and NetStatus.Ok.
    - On graceful stream close: 0, source address, and NetStatus.Closed.
    - On failure: -1, empty address, and the matching status.