wren/manual_src/pages/api/net.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "net" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "net"}] %}
{% set prev_page = {"url": "api/tls.html", "title": "tls"} %}
{% set next_page = {"url": "api/dns.html", "title": "dns"} %}

{% block article %}
                <h1>net</h1>

                <p>The <code>net</code> module provides low-level TCP socket and server functionality for network programming. All operations are asynchronous using libuv.</p>

                <pre><code>import "net" for Socket, Server</code></pre>

                <div class="toc">
                    <h4>On This Page</h4>
                    <ul>
                        <li><a href="#socket-class">Socket Class</a></li>
                        <li><a href="#server-class">Server Class</a></li>
                        <li><a href="#examples">Examples</a></li>
                    </ul>
                </div>

                <h2 id="socket-class">Socket Class</h2>

                <div class="class-header">
                    <h3>Socket</h3>
                    <p>TCP socket for client connections</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Socket.connect</span>(<span class="param">host</span>, <span class="param">port</span>) &#8594; <span class="type">Socket</span>
                </div>
                <p>Establishes a TCP connection to a remote server.</p>
                <ul class="param-list">
                    <li><span class="param-name">host</span> <span class="param-type">(String)</span> - Hostname or IP address to connect to</li>
                    <li><span class="param-name">port</span> <span class="param-type">(Num)</span> - Port number</li>
                    <li><span class="returns">Returns:</span> Connected Socket instance</li>
                </ul>
                <pre><code>var socket = Socket.connect("127.0.0.1", 8080)</code></pre>

                <h3>Methods</h3>

                <div class="method-signature">
                    <span class="method-name">write</span>(<span class="param">data</span>) &#8594; <span class="type">Num</span>
                </div>
                <p>Writes data to the socket. Blocks until the data is sent.</p>
                <ul class="param-list">
                    <li><span class="param-name">data</span> <span class="param-type">(String)</span> - Data to send</li>
                    <li><span class="returns">Returns:</span> Number of bytes written</li>
                </ul>
                <pre><code>socket.write("Hello, server!")</code></pre>

                <div class="method-signature">
                    <span class="method-name">read</span>() &#8594; <span class="type">String|null</span>
                </div>
                <p>Reads data from the socket. Blocks until data is available. Returns null when the connection is closed by the remote end.</p>
                <ul class="param-list">
                    <li><span class="returns">Returns:</span> Data received as a string, or null if connection closed</li>
                </ul>
                <pre><code>var data = socket.read()
if (data != null) {
    System.print("Received: %(data)")
}</code></pre>

                <div class="method-signature">
                    <span class="method-name">close</span>()
                </div>
                <p>Closes the socket connection.</p>
                <pre><code>socket.close()</code></pre>

                <h2 id="server-class">Server Class</h2>

                <div class="class-header">
                    <h3>Server</h3>
                    <p>TCP server for accepting client connections</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Server.bind</span>(<span class="param">host</span>, <span class="param">port</span>) &#8594; <span class="type">Server</span>
                </div>
                <p>Creates a TCP server listening on the specified host and port.</p>
                <ul class="param-list">
                    <li><span class="param-name">host</span> <span class="param-type">(String)</span> - Host to bind to (e.g., "0.0.0.0" for all interfaces, "127.0.0.1" for localhost only)</li>
                    <li><span class="param-name">port</span> <span class="param-type">(Num)</span> - Port number to listen on</li>
                    <li><span class="returns">Returns:</span> Bound Server instance</li>
                </ul>
                <pre><code>var server = Server.bind("0.0.0.0", 8080)</code></pre>

                <h3>Methods</h3>

                <div class="method-signature">
                    <span class="method-name">accept</span>() &#8594; <span class="type">Socket|null</span>
                </div>
                <p>Accepts an incoming connection. Blocks until a client connects. Returns a Socket instance for the connected client.</p>
                <ul class="param-list">
                    <li><span class="returns">Returns:</span> Socket for the accepted connection</li>
                </ul>
                <pre><code>var client = server.accept()
System.print("Client connected!")</code></pre>

                <div class="method-signature">
                    <span class="method-name">close</span>()
                </div>
                <p>Stops the server and closes the listening socket.</p>
                <pre><code>server.close()</code></pre>

                <h2 id="examples">Examples</h2>

                <h3>Simple TCP Client</h3>
                <pre><code>import "net" for Socket

var socket = Socket.connect("example.com", 80)

socket.write("GET / HTTP/1.1\r\n")
socket.write("Host: example.com\r\n")
socket.write("Connection: close\r\n")
socket.write("\r\n")

var response = ""
while (true) {
    var chunk = socket.read()
    if (chunk == null) break
    response = response + chunk
}

socket.close()
System.print(response)</code></pre>

                <h3>Echo Server</h3>
                <pre><code>import "net" for Server

var server = Server.bind("0.0.0.0", 8080)
System.print("Echo server listening on port 8080")

while (true) {
    var client = server.accept()
    System.print("Client connected")

    while (true) {
        var data = client.read()
        if (data == null) {
            System.print("Client disconnected")
            break
        }
        System.print("Received: %(data)")
        client.write(data)
    }

    client.close()
}</code></pre>

                <h3>Line-Based Protocol Server</h3>
                <pre><code>import "net" for Server

var server = Server.bind("127.0.0.1", 9000)
System.print("Chat server on port 9000")

while (true) {
    var client = server.accept()
    client.write("Welcome! Type messages and press Enter.\n")

    var buffer = ""
    while (true) {
        var data = client.read()
        if (data == null) break

        buffer = buffer + data
        while (buffer.contains("\n")) {
            var lineEnd = buffer.indexOf("\n")
            var line = buffer[0...lineEnd]
            buffer = buffer[lineEnd + 1..-1]

            if (line == "quit") {
                client.write("Goodbye!\n")
                client.close()
                break
            }

            client.write("You said: %(line)\n")
        }
    }
}</code></pre>

                <h3>Connecting with DNS Resolution</h3>
                <pre><code>import "net" for Socket
import "dns" for Dns

var hostname = "httpbin.org"
var ip = Dns.lookup(hostname)
System.print("Resolved %(hostname) to %(ip)")

var socket = Socket.connect(ip, 80)
socket.write("GET /ip HTTP/1.1\r\nHost: %(hostname)\r\nConnection: close\r\n\r\n")

var response = ""
while (true) {
    var data = socket.read()
    if (data == null) break
    response = response + data
}

socket.close()
System.print(response)</code></pre>

                <h3>Simple Request-Response Client</h3>
                <pre><code>import "net" for Socket

var socket = Socket.connect("127.0.0.1", 8080)

socket.write("PING\n")
var response = socket.read()
System.print("Server responded: %(response)")

socket.write("ECHO Hello World\n")
response = socket.read()
System.print("Server responded: %(response)")

socket.close()</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>The Socket class uses TCP, which is a stream-based protocol. Data may arrive in chunks that do not correspond to message boundaries. For protocols that require message framing, implement appropriate buffering and parsing logic.</p>
                </div>

                <div class="admonition tip">
                    <div class="admonition-title">Tip</div>
                    <p>For secure connections, use the <code>tls</code> module's TlsSocket class instead of Socket. For HTTP/HTTPS requests, the higher-level <code>http</code> module handles protocol details automatically.</p>
                </div>

                <div class="admonition warning">
                    <div class="admonition-title">Warning</div>
                    <p>Both host and port arguments are validated. Providing a non-string host or non-number port will abort the fiber with an error message.</p>
                </div>
{% endblock %}