Guides / Compute

Run a TCP service

A program receives Ethernet frames, not sockets. To serve TCP to the members of a VPC, use the IPv6 TCP stack in the SDK, which turns those frames into listeners and connections. In this guide you build an echo server with it.

How the stack works

etorm_guest::net::Stack runs inside your program, on one interface. You feed it the frames and timers you receive. It sends its replies with cx.send and arms one timer of its own for retransmissions. Nothing blocks. After each call you read what arrived, write replies, and call flush.

What you call on the stack

CallWhat it does
Stack::new(cx, interface, StackConfig)Creates the stack on an interface index. Fails with NoInterface if there is none.
stack.listen(port)Listens on a port, on every address of the interface. Returns a Listener.
stack.accept(&listener)Returns a new established connection as a small copyable Conn handle, or None.
stack.readable(c), stack.writable(c)Bytes ready to read; room in the send buffer.
stack.read(c, &mut buf), stack.write(c, &data)Return how many bytes were taken. write may accept less than you gave it.
stack.eof(c), stack.is_open(c)The peer has finished sending; the connection is still in use.
stack.close(c), stack.abort(c), stack.release(c)Close gracefully; reset; free the handle once the connection is closed.
stack.connect(remote, local_port)Opens an outbound connection to a SocketAddr.
stack.on_frames(cx, frames), stack.on_timer(cx, id), stack.flush(cx)Feed frames and timers; send what is queued.
stack.announce(cx)Tells the VPC where the process is, after a restore.

1. Write the server

Set the crate up as in Write a program in Rust (same Cargo.toml and build.rs, named tcp-echo). src/lib.rs:

use etorm_guest::net::{Conn, Listener, Stack, StackConfig};
use etorm_guest::{program, Cx, Frame, Program, StartReason};

#[derive(Default)]
struct Echo {
    stack: Option<Stack>,
    listener: Option<Listener>,
    conns: Vec<Conn>,
}

impl Echo {
    fn serve(&mut self, cx: &mut Cx) {
        let (Some(stack), Some(listener)) = (self.stack.as_mut(), self.listener.as_ref()) else { return };
        while let Some(c) = stack.accept(listener) {
            self.conns.push(c);
        }
        let mut buf = [0u8; 2048];
        self.conns.retain(|&c| {
            loop {
                let room = stack.writable(c).min(buf.len());
                if room == 0 || stack.readable(c) == 0 {
                    break;
                }
                let n = stack.read(c, &mut buf[..room]);
                stack.write(c, &buf[..n]);
            }
            if stack.eof(c) {
                stack.close(c);
                if !stack.is_open(c) {
                    stack.release(c);
                    return false;
                }
            }
            true
        });
        stack.flush(cx);
    }
}

impl Program for Echo {
    fn start(&mut self, cx: &mut Cx, why: StartReason) {
        if self.stack.is_none() {
            let cfg = StackConfig { send_buffer: 8 * 1024, recv_buffer: 8 * 1024, backlog: 2, max_sockets: 16, ..StackConfig::default() };
            match Stack::new(cx, 0, cfg) {
                Ok(mut s) => {
                    self.listener = s.listen(7).ok();
                    self.stack = Some(s);
                }
                Err(e) => cx.log_error(&format!("no stack: {e}")),
            }
        }
        if why == StartReason::Restored {
            if let Some(s) = self.stack.as_mut() {
                s.announce(cx);
            }
        }
        self.serve(cx);
    }

    fn frames(&mut self, cx: &mut Cx, frames: &[Frame]) {
        if let Some(s) = self.stack.as_mut() {
            s.on_frames(cx, frames);
        }
        self.serve(cx);
    }

    fn timer(&mut self, cx: &mut Cx, id: u32) {
        if let Some(s) = self.stack.as_mut() {
            s.on_timer(cx, id);
        }
        self.serve(cx);
    }
}

program!(Echo);

The stack is created once, in start, on interface 0, with room for at most 16 sockets. On every wake-up the server reads what each connection has received, writes it back, and closes the connection when the peer does.

2. Build and run it

Build it and register it as the program tcp-echo, as in the previous guide. The module comes to about 100 KB. Then start a process and read its VPC address:

cargo build --release --target wasm32-unknown-unknown
kubectl apply -f - <<EOF
apiVersion: compute.etorm.com/v1alpha1
kind: Process
metadata: {name: tcp-echo}
spec:
  programRef: {name: tcp-echo}
  interfaces:
    - {name: eth0, vpcRef: {name: lan}}
  residency: Resident
  resources: {memoryPower: 5}
EOF
kubectl get process tcp-echo -o jsonpath='{.status.interfaces[0].ipv6Address}{"\n"}'
# fdf9:a95a:7907:0:e8:ff:fe00:2

Run it as a resident process. The stack and its connections are ordinary memory of the program, so an ephemeral process would lose them at every wake-up.

3. Reach it from a VPC member

The service is on the VPC, not on the internet. Connect from anything on the same VPC, such as a machine joined through a gateway (Connect a Linux machine to a VPC), using the address from status.interfaces:

printf 'hello\n' | nc -6 -w 2 fdf9:a95a:7907:0:e8:ff:fe00:2 7
# hello

The link-local address works only on the same link and needs the interface name (fe80::...%eth0). Use the VPC address.

Hibernate without dropping connections

Because the stack lives in the program's memory, a hibernated and restored process keeps its connections. The peer sees a pause, and TCP carries on. The program needs only to call announce when start is called with Restored, as the server above does. See Hibernate and resume a process.

Limits

Clean up

kubectl delete process tcp-echo
kubectl delete program tcp-echo

Next

Hibernate and resume a process.