net.transport

A proxy protocol such as VLESS or VMess says what the first bytes of a connection mean. It does not say how the connection itself is made, and that is the part a censor looks at: is it plain TCP, TLS to which name, a WebSocket on which path, under which Host header. net.transport is that layer. It turns "connect to this host and port with these settings" into a Conn that is read and written the same way whatever is underneath.

The package has four jobs:

• Carriers. Dial and Listen work over plain TCP, TLS, WebSocket (alone or inside TLS) and a bare HTTP upgrade. FromStream and AsStream let any net.tunnel stream carry a protocol too, so a protocol can run inside another one.
• Looking like something else. The TLS server name (sni) and the HTTP Host header are separate settings, so a client can connect to a CDN front name while asking for another site. The WebSocket path works as a shared secret: a request for any other path gets a fake nginx 404 page.
• ClientHello fragmentation. fragment sends the first bytes of the TLS handshake in small pieces with a pause between them, which defeats some filters that read the server name from the first packet.
• Shared plumbing. Bytes is the growable buffer the protocol packages build headers in, and Addr is a target address that knows its wire form.

Which carrier a Settings value selects

Every dial and listen call takes a Settings value. Its zero value is plain TCP.

Any other network text is not rejected here: the connection is simply plain. The link parsers of the protocol packages refuse unsupported types before they get this far.

What trips people up

• Accept hands each new connection to a worker. TLS and the WebSocket upgrade run in a worker with a time limit (handshake_timeout_ms, 10 seconds) and at most max_handshakes (128) run at once; a client that stalls is dropped and a connection over the limit is closed at once. Accept then returns the next finished connection, or a closed one whose err says why a handshake failed. AcceptRaw and Upgrade still exist for a loop of your own.
• sni is not host. sni is the name in the TLS handshake and the name the certificate is checked against; host is the Host header inside the upgrade request. Behind a CDN they usually differ.
• The ALPN setting is one string. Offer "h2" or "http/1.1", not a list. Over WebSocket use "http/1.1", because the upgrade is an HTTP/1.1 feature.
• fingerprint changes nothing. The field is kept so links that carry fp=chrome round-trip, but the TLS handshake is this library's own, not a copy of a browser's. A filter that recognizes the handshake shape is not fooled.
• timeout_ms covers the connect only. For an established connection set read_timeout_ms and write_timeout_ms: a read or write that waits that long ends with 0 or less. They are idle limits, so leave them 0 for a tunnel that may sit quiet.
• Buffers are manual. NewBytes allocates and FreeBytes frees; nothing collects them.
• No XHTTP, QUIC or plain HTTP/2 transport. gRPC (network = "grpc"), Reality (security = "reality") and Mux.Cool are here; see the sections below.

Buffers and addresses

A Bytes value is a pointer, a length and a capacity. The Put functions append (and grow it), At and Peek16 read back, and ToHex shows the content. A target address is a Addr: NewAddr looks at the text and decides between an IPv4 address, an IPv6 address and a domain name, and PutAddr writes it in the order the VLESS and VMess headers use (port, type, address). ParseUUID turns the usual 36 character text into the 16 bytes a user id is on the wire and sets bad when the text is not a UUID.

import net.transport

func main:
    mut b := transport.NewBytes(16)
    transport.Put8(b, 0x7f)
    transport.Put16(b, 443)
    transport.PutStr(b, "hi")
    println transport.ToHex(b), b.len
    println transport.Peek16(b, 1), transport.At(b, 3) as int
    transport.FreeBytes(b)

    a := transport.NewAddr("example.com", 443)
    println a.host, a.port, a.kind == transport.AddrDomain
    println transport.NewAddr("192.168.1.9", 80).kind == transport.AddrIPv4
    println transport.NewAddr("2001:db8::1", 8080).kind == transport.AddrIPv6

    mut wire := transport.NewBytes(32)
    transport.PutAddr(wire, a)
    println transport.ToHex(wire)
    mut back := transport.Addr {}
    used := transport.ReadAddr(wire, 0, back)
    println used, back.host, back.port
    transport.FreeBytes(wire)

    id := transport.ParseUUID("b831381d-6324-4d53-ad4f-8cda48b30811")
    println id.bad, id.len, transport.FormatUUID(id)
    println transport.ParseUUID("not a uuid").bad
end

Quick start: a client and a server

Listen binds a port (0 picks a free one, and ListenerPort says which), Accept waits for a client, and Read and Write move bytes. Read returns 0 or less when the other side has closed. Check Ok after a dial, and read err when it is false. This program runs the server in a thread and talks to it over the loopback address.

import mem
import sync
import net.transport

mut port := 0
mut ready := sync.NewWaitGroup()

func echo_once():
    settings := transport.Settings {}
    l := transport.Listen(0, settings)
    port = transport.ListenerPort(l)
    sync.Done(ready)
    mut c := transport.Accept(l)
    buf := mem.Allocate(4096 as u64)
    n := transport.Read(c, buf, 4096)
    if n > 0:
        transport.Write(c, buf, n)
    end
    mem.Free(buf)
    transport.Close(c)
    transport.CloseListener(l)
end

func main:
    sync.Add(ready, 1 as i64)
    t := spawn(echo_once)
    sync.Wait(ready)

    mut c := transport.Dial("127.0.0.1", port, transport.Settings {})
    if not transport.Ok(c):
        println "dial failed:", c.err
        ret
    end
    mut msg := transport.FromStr("hello transport")
    transport.WriteBytes(c, msg)
    buf := mem.Allocate(4096 as u64)
    n := transport.Read(c, buf, 4096)
    println "echo of", n, "bytes:", (buf as str).substr(0, n)
    mem.Free(buf)
    transport.FreeBytes(msg)
    transport.Close(c)
    join(t)
end

WebSocket, and why Accept is not enough

Set network = "ws", a path and optionally a host on both sides. The client sends a normal-looking GET with a browser User-Agent. The server checks the path and, when host is set, the Host header; a mismatch is answered with an nginx style 404 Not Found page and the connection is closed, so a probe for a different path sees an ordinary web server.

The program below does the server side the careful way: AcceptRaw only takes the TCP connection (and the TLS handshake when tls is on), and Upgrade then reads the request. In a real server the Upgrade call and everything after it go into a worker thread per connection, so a client that stalls cannot hold up the others. The second half shows a wrong path being refused.

import mem
import sync
import net.transport

mut port := 0
mut ready := sync.NewWaitGroup()
mut seen_path := ""
mut seen_host := ""

func settings(): transport.Settings:
    mut s := transport.Settings {}
    s.network = "ws"
    s.path = "/tunnel"
    s.host = "cdn.example.com"
    ret s
end

func worker():
    s := settings()
    l := transport.Listen(0, s)
    port = transport.ListenerPort(l)
    sync.Done(ready)
    mut c := transport.AcceptRaw(l)
    if transport.Upgrade(c, s):
        seen_path = c.request_path
        seen_host = c.request_host
        buf := mem.Allocate(4096 as u64)
        n := transport.Read(c, buf, 4096)
        transport.Write(c, buf, n)
        mem.Free(buf)
    end
    transport.Close(c)
    transport.CloseListener(l)
end

func main:
    sync.Add(ready, 1 as i64)
    t := spawn(worker)
    sync.Wait(ready)

    mut c := transport.Dial("127.0.0.1", port, settings())
    mut msg := transport.FromStr("inside a websocket")
    transport.WriteBytes(c, msg)
    buf := mem.Allocate(4096 as u64)
    n := transport.Read(c, buf, 4096)
    println (buf as str).substr(0, n)
    mem.Free(buf)
    transport.FreeBytes(msg)
    transport.Close(c)
    join(t)
    println "server saw path", seen_path, "and host", seen_host

    mut wrong := settings()
    wrong.path = "/other"
    sync.Add(ready, 1 as i64)
    t2 := spawn(worker)
    sync.Wait(ready)
    bad := transport.Dial("127.0.0.1", port, wrong)
    println "wrong path accepted:", transport.Ok(bad)
    println bad.err
    join(t2)
end

early_data is the Xray style "0-RTT" trick: the first payload bytes ride in the Sec-WebSocket-Protocol header of the upgrade request. Pass them to DialEarly, and set early_data to the largest size you allow on both sides. The server hands those bytes back through the first Read.

VLESS or VMess over WebSocket and TLS behind a CDN

This is the usual way to run a proxy that has to survive: the real server hides behind a CDN, the connection to the CDN is ordinary HTTPS, and the CDN forwards WebSocket requests for one secret path to the server.

1. Put a domain on the CDN and point it at the server. Turn the proxy (orange cloud) on and turn WebSockets on. Use a port the CDN accepts for HTTPS, such as 443, 2053, 2083, 2087 or 2096.
2. Let the CDN terminate TLS. Choose its "Full" mode with an origin certificate, or run the server with tls = true and a certificate and key through cert_file and key_file. If you do not want the origin to speak TLS at all, listen with plain ws on a local port behind your own reverse proxy.
3. On the server, Listen with network = "ws", a long random path and host set to your domain. Anything that asks for another path gets the nginx 404.
4. On the client, dial the front name (any name that resolves to the CDN) with tls = true, sni set to the front name, host set to your own domain and the same path. The network between you and the CDN sees TLS to the front name only.
5. Use alpn = "http/1.1". Set early_data only when the CDN passes the Sec-WebSocket-Protocol header through.

import net.transport

func client_settings(): transport.Settings:
    mut s := transport.Settings {}
    s.network = "ws"
    s.tls = true
    s.sni = "front.example.net"
    s.host = "vpn.example.org"
    s.path = "/ws-8f3a"
    s.alpn = "http/1.1"
    s.early_data = 2048
    s.timeout_ms = 8000
    ret s
end

func server_settings(): transport.Settings:
    mut s := transport.Settings {}
    s.network = "ws"
    s.path = "/ws-8f3a"
    s.host = "vpn.example.org"
    ret s
end

func main:
    c := transport.Dial("front.example.net", 443, client_settings())
    println transport.Ok(c), c.err
    l := transport.Listen(10000, server_settings())
    println transport.ListenerOk(l)
    transport.CloseListener(l)
end

The program is checked but not run by the site, because it needs your server. See the VLESS and VMess pages for the same setup on top of a protocol, and the tunnel page to wire it into a local proxy. A CDN sees all your traffic in clear text between its two TLS legs: it terminates TLS for you, and the protocol inside (VMess) or the lack of one (VLESS with encryption=none) is all that is left. Prefer VMess with SecAES128GCM or SecChaCha20Poly1305 when you do not trust the CDN with your payload.

Fragmenting the TLS ClientHello

Some national filters, Iran's among them, read the server name out of the first packet of a TLS connection and cut the connection when the name is on a list. They often do this without reassembling TCP or TLS records, so a ClientHello that arrives in pieces is not matched. fragment = true does this on the client, in the TLS record layer, with no helper threads or sockets. fragment_mode chooses what is split:

• "tcp" (the default): the hello record is written in several TCP segments of fragment_min to fragment_max random bytes, fragment_delay_ms apart.
• "tls": the ClientHello record itself is split into several TLS records (each with its own header), which a server reassembles. The records go out one per segment.
• "both": the record is split and the result is also cut into TCP segments.

fragment_sni = true adds a cut in the middle of the server name, so that no piece and no record holds it whole; with fragment_min and fragment_max both 0 it is the only cut. fragment_writes says how many of the first handshake writes are fragmented (1 is the ClientHello). The server sees the same handshake bytes either way; the tests show that a real TLS server completes the handshake, and that a sink sees the records reassemble to the identical ClientHello.

FragmentSizes is the function that picks the sizes. It is public so you can see what a setting produces: every piece but the last is within the range, and they add up to the total.

import net.transport

func main:
    sizes := transport.FragmentSizes(517, 5, 20)
    mut total := 0
    mut in_range := true
    repeat sizes.len() in i:
        n := sizes.get(i)
        total += n
        if i < sizes.len() - 1 and (n < 5 or n > 20):
            in_range = false
        end
    end
    println "pieces add up to", total
    println "every piece but the last is 5 to 20 bytes:", in_range
    println "more than 25 pieces:", sizes.len() > 25
    println "one piece when min and max cover the whole message:", transport.FragmentSizes(10, 50, 60).len()
end

To turn it on for a TLS dial:

import net.transport

func main:
    mut s := transport.Settings {}
    s.tls = true
    s.sni = "example.com"
    s.fragment = true
    s.fragment_min = 3
    s.fragment_max = 30
    s.fragment_delay_ms = 5
    s.timeout_ms = 8000
    mut c := transport.Dial("example.com", 443, s)
    println transport.Ok(c), c.err
    transport.Close(c)
end

Start with pieces of 3 to 30 bytes and 5 to 10 milliseconds. Smaller pieces and longer pauses fool more filters and make the handshake slower; if the connection starts failing or timing out, grow the pieces or shorten the pause. Fragmentation applies to the client only, and only when tls = true. The ClientHello of the TLS 1.3 server in this library can be read from several records. It has to be tried where you are: a filter that reassembles the stream, or one that blocks on the IP address or on something other than the server name, is not affected, and what works changes over time. Fragmentation hides the name from the filter; it does not hide that you are using a proxy, and it does not change the shape of the handshake itself (see fingerprint above).

gRPC (gun and multi)

network = "grpc" carries the bytes in an HTTP/2 stream of gRPC messages, the V2Ray "gun" form: the client POSTs to /serviceName/Tun and each message holds one protobuf field with the data. grpc_mode = "multi" uses /serviceName/TunMulti. With tls = true the ALPN is h2 by default; without TLS it is cleartext HTTP/2. Set service_name on both sides (links carry it as serviceName); a request for another name is answered with a gRPC error and no connection is produced. The HTTP/2 framing is written in this package, with HPACK from net.http2, because the connection must be read and written from two threads at once. A server handles several streams on one HTTP/2 connection, and each becomes one connection from Accept. This is checked against itself only; it has not been run against a real Xray gRPC peer.

Mux.Cool

NewMuxClient and NewMuxServer multiplex sessions over one stream, in the framing V2Ray and Xray use for CmdMux: MuxOpen opens a session to a target and returns a stream, and MuxAccept on the other side returns each opened session with its target. vless.MuxClient and vmess.MuxClient (and MuxServer) wrap this for a connection made with CmdMux. There is no flow control between sessions, as in the original, so one stalled session can hold up the others, and the XUDP extensions (global ids, per-packet addresses) are not implemented. A UDP session carries one datagram per write; Xray drops the whole Mux connection when one is larger than 8192 bytes, so MuxMaxPacket is enforced: a larger write is refused (it returns -1) and the session stays open. Against Xray a UDP session works up to 8192 bytes, against sing-box up to 16000 were measured.

Reality

With security = "reality" a client runs the Reality handshake of net.reality in place of TLS (set reality with the public key and short id) and a listener does the server side from reality_server; a connection that does not authenticate is relayed to the cover site. Everything after the handshake is the same as for TLS.

Limits and security

• Certificates are checked by default. allow_insecure = true turns the check off, which lets anyone on the path read and change the connection. Use it for a test against a self-signed certificate, or give the CA to ca_file instead.
• Fragmentation touches only the first writes. Later TLS records are sealed and are never split; fragment_writes above 1 only matters for handshakes that send more than one flight.
• The fake 404 is the whole disguise. A visitor with the right path and no WebSocket handshake gets 400 Bad Request in the same nginx style. Nothing else about the server is made to look like a website; if you need that, put a real reverse proxy in front.
• A listener binds the loopback address by default. Listen uses bind (127.0.0.1); to accept connections from other machines call ListenAll or ListenAt with "0.0.0.0". Stalled clients are dropped by the handshake time limit; set read_timeout_ms for the idle ones.
• No live comparison with Xray or V2Ray was run. The package is tested against itself and against byte vectors; whether a given CDN or a given Xray build accepts its requests has to be tried on your side.

Types

struct Settings

struct Conn

struct Listener

struct MuxIncoming

struct Mux

struct Addr

struct Bytes

Constants and variables

const MuxMaxPacket: i32 = 8192

const AddrIPv4: i32 = 1

const AddrDomain: i32 = 2

const AddrIPv6: i32 = 3

Functions

func FragmentSizes(total: int, min: int, max: int): Vector<int>

func Ok(c: Conn): bool

func Read(c &: Conn, buf: void*, max: int): int

func ReadFull(c &: Conn, buf: void*, n: int): bool

func Write(c &: Conn, p: void*, n: int): bool

func WriteBytes(c &: Conn, b: Bytes): bool

func SwitchDirect(c &: Conn): bool

func SetReadTimeout(c &: Conn, ms: int)

func Close(c &: Conn)

func DialEarly(host: str, port: int, s: Settings, early: Bytes): Conn

func Dial(host: str, port: int, s: Settings): Conn

func ListenAt(host: str, port: int, s: Settings): Listener

func ListenerFrom(server: tcp.Server, s: Settings): Listener

func Listen(port: int, s: Settings): Listener

func ListenAll(port: int, s: Settings): Listener

func ListenerOk(l: Listener): bool

func ListenerPort(l: Listener): int

func CloseListener(l: Listener)

func AcceptRaw(l: Listener): Conn

func Upgrade(c &: Conn, s: Settings): bool

func ShutdownConn(c &: Conn)

import mem
import sync
import net.transport

mut port := 0
mut ready := sync.NewWaitGroup()

func count_then_answer():
    l := transport.Listen(0, transport.Settings {})
    port = transport.ListenerPort(l)
    sync.Done(ready)
    mut c := transport.Accept(l)
    buf := mem.Allocate(4096 as u64)
    mut total := 0
    mut n := transport.Read(c, buf, 4096)
    until n > 0:
        total += n
        n = transport.Read(c, buf, 4096)
    end
    mem.Free(buf)
    mut reply := transport.FromStr("server read " + total + " bytes")
    transport.WriteBytes(c, reply)
    transport.FreeBytes(reply)
    transport.ShutdownConn(c)
    transport.Close(c)
    transport.CloseListener(l)
end

func main:
    sync.Add(ready, 1 as i64)
    t := spawn(count_then_answer)
    sync.Wait(ready)

    mut c := transport.Dial("127.0.0.1", port, transport.Settings {})
    if not transport.Ok(c):
        println "dial failed:", c.err
        ret
    end
    mut msg := transport.FromStr("first part, second part")
    transport.WriteBytes(c, msg)
    transport.FreeBytes(msg)
    transport.CloseWriteConn(c)
    buf := mem.Allocate(4096 as u64)
    n := transport.Read(c, buf, 4096)
    println (buf as str).substr(0, n)
    println "then", transport.Read(c, buf, 4096)
    mem.Free(buf)
    transport.Close(c)
    join(t)
end

func CloseWriteConn(c &: Conn)

func Accept(l: Listener): Conn

func AsStream(c: Conn): dyn tunnel.Stream

func FromStream(s: dyn tunnel.Stream, client: bool): Conn

func NewMuxClient(up: dyn tunnel.Stream): Mux

func NewMuxServer(up: dyn tunnel.Stream): Mux

func MuxOpen(m: Mux, addr: Addr, udp: bool): dyn tunnel.Stream

func MuxAccept(m: Mux, out &: MuxIncoming): bool

func MuxOk(m: Mux): bool

func MuxClose(m: Mux)

func DetectKind(host: str): int

func NewAddr(host: str, port: int): Addr

func PutAddr(b &: Bytes, a: Addr): bool

func FormatIPv6(p: u8*): str

func ReadAddr(b: Bytes, off: int, a &: Addr): int

func ParseUUID(s: str): Bytes

func FormatUUID(b: Bytes): str

func NewBytes(cap0: int): Bytes

func FreeBytes(b &: Bytes)

func ResetBytes(b &: Bytes)

func BytesPtr(b: Bytes, off: int): void*

func Reserve(b &: Bytes, need: int)

func Put8(b &: Bytes, v: int)

func Put16(b &: Bytes, v: int)

func Put32(b &: Bytes, v: i64)

func Put64(b &: Bytes, v: u64)

func PutRaw(b &: Bytes, src: void*, n: int)

func PutBytes(b &: Bytes, src: Bytes)

func PutStr(b &: Bytes, s: str)

func PutZeros(b &: Bytes, n: int)

func At(b: Bytes, i: int): int

func Set8(b &: Bytes, i: int, v: int)

func Peek16(b: Bytes, i: int): int

func Peek32(b: Bytes, i: int): i64

func Consume(b &: Bytes, n: int)

func Equal(a: Bytes, b: Bytes): bool

func ToHex(b: Bytes): str

func FromHex(h: str): Bytes

func FromStr(s: str): Bytes