Net Module

The std/net module provides TCP and TLS networking primitives for building network clients and servers. It’s the foundation for implementing wire protocols like PostgreSQL, Redis, SMTP, and more.

Import

import { TcpConnection, TlsConnection, TcpServer, resolve } from "std/net"

TCP Client

new TcpConnection(host: string, port: int)

Creates a new TCP connection to the specified host and port.

import { TcpConnection } from "std/net"
import { Buffer } from "std/buffer"

var conn = new TcpConnection("localhost", 5432)
println(conn.remoteAddr()) // "127.0.0.1:5432"

// Send data
var data = Buffer.fromString("HELLO\n")
conn.writeAll(data)

// Receive data
var response = conn.read(1024)
println(response.toString("utf8"))

conn.close()

Connection Methods

Method	Returns	Description
write(buf: Buffer)	int	Writes buffer data, returns bytes written
writeAll(buf: Buffer)	void	Writes all data, handling partial writes
read(maxBytes: int)	Buffer	Reads up to maxBytes, returns buffer (empty on EOF)
readExact(length: int)	Buffer	Reads exactly length bytes (blocks until complete)
close()	void	Closes the connection
remoteAddr()	string	Returns remote address (e.g., "127.0.0.1:5432")
localAddr()	string	Returns local address
isTLS()	bool	Returns whether this is a TLS connection
setDeadline(ms: int)	void	Sets read/write deadline in milliseconds
setReadDeadline(ms: int)	void	Sets read-only deadline
setWriteDeadline(ms: int)	void	Sets write-only deadline
upgradeToTLS(host: string)	void	Upgrades a plain TCP connection to TLS (STARTTLS)

TLS Client

new TlsConnection(host: string, port: int)

Creates a TLS-encrypted TCP connection.

import { TlsConnection } from "std/net"
import { Buffer } from "std/buffer"

var conn = new TlsConnection("example.com", 443)
println(conn.isTLS()) // true

var request = Buffer.fromString("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")
conn.writeAll(request)

var response = conn.read(4096)
println(response.toString("utf8"))
conn.close()

STARTTLS Upgrade

Some protocols (like PostgreSQL) start with a plain TCP connection and upgrade to TLS after an initial handshake.

var conn = new TcpConnection("db.example.com", 5432)
// ... initial handshake ...
conn.upgradeToTLS("db.example.com")
println(conn.isTLS()) // true
// ... now all traffic is encrypted ...

TCP Server

new TcpServer(host: string, port: int)

Creates a TCP server that listens for incoming connections.

import { TcpServer, TcpConnection } from "std/net"
import { Buffer } from "std/buffer"

var server = new TcpServer("0.0.0.0", 8080)
println("Listening on " + server.addr())

// Accept connections in a loop
while (true) {
    var client: TcpConnection = server.accept()
    println("New connection from " + client.remoteAddr())

    // Handle request
    var data = client.read(1024)
    println("Received: " + data.toString("utf8"))

    // Send response
    var response = Buffer.fromString("OK\n")
    client.writeAll(response)
    client.close()
}

Server Methods

Method	Returns	Description
accept()	TcpConnection	Blocks until a client connects, returns the connection
addr()	string	Returns the server’s listening address
close()	void	Stops listening and closes the server

DNS Resolution

resolve(host: string): string

Resolves a hostname to an IP address.

import { resolve } from "std/net"

var ip = resolve("localhost")
println(ip) // "127.0.0.1"

Timeouts & Deadlines

You can set timeouts on connections to prevent blocking indefinitely.

var conn = new TcpConnection("localhost", 5432)

// Set a 5-second deadline for all operations
conn.setDeadline(5000)

// Or set separate read/write deadlines
conn.setReadDeadline(3000)  // 3 seconds for reads
conn.setWriteDeadline(5000) // 5 seconds for writes

Complete Example: Echo Server

import { TcpServer, TcpConnection } from "std/net"
import { Buffer } from "std/buffer"

async function handleClient(client: TcpConnection) {
    println("Client connected: " + client.remoteAddr())
    while (true) {
        var data = client.read(4096)
        if (data.length() == 0) {
            println("Client disconnected")
            break
        }
        // Echo back
        client.writeAll(data)
    }
    client.close()
}

async function main() {
    var server = new TcpServer("0.0.0.0", 9000)
    println("Echo server listening on " + server.addr())

    while (true) {
        var client = server.accept()
        spawn handleClient(client)
    }
}

Complete Example: Simple HTTP Client

import { TlsConnection } from "std/net"
import { Buffer } from "std/buffer"

function httpGet(host: string, path: string): string {
    var conn = new TlsConnection(host, 443)
    var request = Buffer.fromString(
        "GET " + path + " HTTP/1.1\r\n" +
        "Host: " + host + "\r\n" +
        "Connection: close\r\n\r\n"
    )
    conn.writeAll(request)

    var body = ""
    while (true) {
        var chunk = conn.read(4096)
        if (chunk.length() == 0) {
            break
        }
        body = body + chunk.toString("utf8")
    }
    conn.close()
    return body
}

var response = httpGet("example.com", "/")
println(response)