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.
- The stack speaks IPv6. It answers neighbour discovery and ping, and it has the interface's link-local address and the SLAAC address of its MAC in the VPC prefix (the two addresses in
status.interfaces). You can add more addresses withStackConfig.addresses. IPv4 is off unless you build the SDK with itsipv4feature. - The stack uses the timer ids
0xFFFF_0000to0xFFFF_00FF. Do not use those for your own timers, and pass a timer toon_timeronly ifstack.owns_timer(id)is true. - Each connection has a send and a receive buffer, 32 KiB each by default, and the stack allows up to 256 sockets. All of that comes out of the process's memory allowance, so use small buffers and few sockets in a small process.
- The stack has no TLS. A program that needs TLS brings its own.
What you call on the stack
| Call | What 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
- A program on the same machine as the gateway, reached from a local virtual port on that machine, may see TCP dropped, because such frames carry unfinished checksums. Members that arrive through the VPC tunnel are fine.
- There is no TLS, no UDP socket API, and no DNS or DHCP client in the SDK.
Clean up
kubectl delete process tcp-echo kubectl delete program tcp-echo