# net

> Networking — TCP, UDP, TLS, DNS, and an HTTP client, using integer connection handles.

# net

Low-level networking: TCP and UDP sockets, TLS, DNS lookups, and an embedded HTTP client. Import it with `import net`.

Connections, listeners, and UDP sockets are referenced by integer handles returned from `connect`, `listen`, and `accept`. A handle of `-1` means the operation failed. Close handles with the matching `close` function when done.

## net.tcp

| Function | Signature | Description |
| --- | --- | --- |
| `connect` | `net.tcp.connect(host: string, port: int) → int` | Dial a TCP connection; returns a handle or `-1` |
| `connectTLS` | `net.tcp.connectTLS(host: string, port: int) → int` | Dial a TLS connection |
| `listen` | `net.tcp.listen(host: string, port: int) → int` | Open a listener; returns a listener handle |
| `listenTLS` | `net.tcp.listenTLS(host: string, port: int, certPEM: string, keyPEM: string) → int` | Open a TLS listener with the given cert and key |
| `accept` | `net.tcp.accept(listenerId: int) → int` | Accept the next connection; returns a connection handle |
| `send` | `net.tcp.send(id: int, data: string) → bool` | Write data to a connection |
| `recv` | `net.tcp.recv(id: int, maxBytes: int) → string` | Read up to `maxBytes` (empty string on EOF/error) |
| `close` | `net.tcp.close(id: int) → bool` | Close a connection or listener |
| `setNoDelay` | `net.tcp.setNoDelay(id: int, noDelay: bool) → bool` | Toggle TCP_NODELAY |
| `setKeepAlive` | `net.tcp.setKeepAlive(id: int, keepAlive: bool) → bool` | Toggle TCP keep-alive |

`net.socket` is an alias for `net.tcp` with the same API.

## net.udp

| Function | Signature | Description |
| --- | --- | --- |
| `connect` | `net.udp.connect(host: string, port: int) → int` | Open a connected UDP socket |
| `listen` | `net.udp.listen(host: string, port: int) → int` | Open a UDP socket bound to an address |
| `send` | `net.udp.send(id: int, data: string) → bool` | Send a datagram |
| `recv` | `net.udp.recv(id: int, maxBytes: int) → string` | Receive up to `maxBytes` |
| `close` | `net.udp.close(id: int) → bool` | Close the socket |

## net.dns

| Function | Signature | Description |
| --- | --- | --- |
| `resolve` | `net.dns.resolve(host: string) → string` | First resolved address (empty on failure) |
| `resolveAll` | `net.dns.resolveAll(host: string) → string[]` | All resolved addresses |
| `lookupMX` | `net.dns.lookupMX(host: string) → string[]` | MX records as `"host pref"` strings |
| `lookupTXT` | `net.dns.lookupTXT(host: string) → string[]` | TXT records |
| `lookupNS` | `net.dns.lookupNS(host: string) → string[]` | NS record hostnames |
| `reverse` | `net.dns.reverse(ip: string) → string` | Reverse-DNS the IP to a hostname |

## net.http

An HTTP client. `get`, `post`, `put`, `patch`, `delete`, and `request` return the response body; `head` and `status` return the status code. See the dedicated [`http`](/docs/stdlib/http) module for the same client surface.

| Function | Signature | Description |
| --- | --- | --- |
| `get` | `net.http.get(url: string) → string` | GET, returns body |
| `post` | `net.http.post(url: string, body: string) → string` | POST with JSON body |
| `put` | `net.http.put(url: string, body: string) → string` | PUT with JSON body |
| `patch` | `net.http.patch(url: string, body: string) → string` | PATCH with JSON body |
| `delete` | `net.http.delete(url: string) → string` | DELETE, returns body |
| `head` | `net.http.head(url: string) → int` | HEAD, returns status code |
| `status` | `net.http.status(url: string) → int` | GET, returns status code only |
| `request` | `net.http.request(method: string, url: string, body: string, headers: string[]) → string` | Generic request with custom `"Key: Value"` headers |

## Top-level shortcuts

`net` also exposes flat helpers operating on the same handle registry.

| Function | Signature | Description |
| --- | --- | --- |
| `connect` | `net.connect(host: string, port: int) → int` | Dial a TCP connection |
| `connectTLS` | `net.connectTLS(host: string, port: int) → int` | Dial a TLS connection |
| `listen` | `net.listen(host: string, port: int) → int` | Open a TCP listener |
| `accept` | `net.accept(listenerId: int) → int` | Accept a connection |
| `send` | `net.send(id: int, data: string) → bool` | Write data |
| `sendLine` | `net.sendLine(id: int, line: string) → bool` | Write data followed by CRLF |
| `recv` | `net.recv(id: int, maxBytes: int) → string` | Read up to `maxBytes` |
| `recvLine` | `net.recvLine(id: int) → string` | Read one CRLF-terminated line (trimmed) |
| `recvTimeout` | `net.recvTimeout(id: int, ms: int, maxBytes: int) → string` | Read with a millisecond deadline |
| `setTimeout` | `net.setTimeout(id: int, ms: int) → bool` | Set a read/write deadline (`0` clears it) |
| `close` | `net.close(id: int) → bool` | Close a connection, listener, or UDP socket |
| `localAddr` | `net.localAddr(id: int) → string` | Local address of the handle |
| `remoteAddr` | `net.remoteAddr(id: int) → string` | Remote address of a connection |
| `connectUDP` | `net.connectUDP(host: string, port: int) → int` | Open a connected UDP socket |
| `listenUDP` | `net.listenUDP(host: string, port: int) → int` | Bind a UDP socket |
| `sendUDP` | `net.sendUDP(id: int, data: string) → bool` | Send a datagram |
| `recvUDP` | `net.recvUDP(id: int, maxBytes: int) → string` | Receive a datagram |
| `resolve` | `net.resolve(host: string) → string` | First resolved address |
| `resolveAll` | `net.resolveAll(host: string) → string[]` | All resolved addresses |

## Example

```goost
import net

// simple TCP client
let conn = net.tcp.connect("example.com", 80)
if conn != -1 {
  net.sendLine(conn, "GET / HTTP/1.0")
  net.sendLine(conn, "Host: example.com")
  net.sendLine(conn, "")
  let line = net.recvLine(conn)   // first response line
  print(line)
  net.tcp.close(conn)
}

// DNS lookup
print(net.dns.resolve("example.com"))
```