🦎 scaly.io

Scaly's HTTP stack

The http package of Scaly's standard library and its siblings, used the way an application uses them — the entry scaly in HttpArena.

Scaly is a compiled language whose memory lives in regions the compiler infers: there is no garbage collector and no borrow checker. A server written in it looks like this:

• One scheduler per core, each with its own io_uring and, on Linux, its own listener on the port (SO_REUSEPORT): the kernel spreads the connections, and each scheduler accepts and serves its own.
• A connection is a fiber with a region of its own. Each request is handled in a region that is freed, all at once, when the handler returns.
• HTTP/1.1 with a parser that resumes at any byte; every complete request in a read is answered, and the answers leave in one write.
• HTTP/2 of the package's own, over TLS and by prior knowledge; WebSocket; gRPC framing.
• A router with path parameters and middleware before and after the handler; responses declared in one call (res.respond(404, "text/plain", "no such item"), res.send_json(value)); response compression switched on at the router, which answers text and JSON in gzip where the client takes it.
• From the sibling packages: json (a two-stage parser and a writer), pg (a Postgres pool with a prepared statement per connection), tls and https (TLS 1.3), h3 (HTTP/3), compress (gzip).
• Every one of them is a published package — http 0.2.0 and its siblings, in the Scaly repository — and comes with the toolchain.

A handler takes the request and the response; the router maps paths to handlers. From the entry:

; baseline: a + b, plus the body when there is one.
procedure baseline(req: ref[Request], mutable res: ref[Response])
{
    var sum parse_int_prefix(req.query_param("a")) + parse_int_prefix(req.query_param("b"))
    if req.body.length > 0
        sum := sum + parse_int_prefix(trim(req.body))
    res.send_int(sum)
}

; async: waits ms without holding a thread, then answers the number.
procedure delay(req: ref[Request], mutable res: ref[Response])
{
    let ms parse_int_prefix(req.param("ms"))
    if ms > 0
        Scheduler.sleep(ms)
    res.send_int(ms)
}

var app Router.create(Page.allocate_page())
app.any("/baseline11", &baseline)
app.get("/delay/{ms}", &delay)
app.get("/json/{count}", &json_items)          ; serializes with the json package's writer
app.compress("", "gzip", &gzip_compress)      ; text and JSON in gzip where the client takes it
serve(app, 8080)

The whole entry is three files, arena.scaly (the routes and the core handlers), db.scaly (Postgres) and stack.scaly (the production stack behind a gateway); the directory has its Dockerfile and a table of how each profile is served. A procedure names what it writes (mutable res); the compiler checks it.

• The cryptography, QUIC and compression are C libraries: OpenSSL, ngtcp2 and libdeflate. HTTP, HTTP/2, the HTTP/3 framing, WebSocket, gRPC, JSON and the Postgres protocol above them are Scaly.
• Nothing is tuned beyond the defaults: no flags for the kernel, the rings or the sockets.
• There is no template engine, so the entry does not run the fortunes profile.
• gRPC is framed by the package and the protobuf fields are read and written by number: there is no code generator for .proto files.
• Compression is gzip alone, at level 1 (nginx's default); no Brotli.
• The build is profile-guided: an instrumented build, a training run under the request shapes of the profiles, then the final build with that profile. That is the production build the documentation describes, and SCALY_PGO=0 builds without it.
• On macOS and Windows the same code runs over kqueue and I/O completion ports, with one acceptor handing connections to the schedulers; a listener per scheduler is Linux only.

With HttpArena itself, which builds the entry's image (the released toolchain at the version its Dockerfile names, as anyone installs it) and runs every profile the entry subscribes to:

git clone https://github.com/MDA2AV/HttpArena && cd HttpArena
./scripts/validate.sh scaly
./scripts/benchmark.sh scaly

Or the server alone, in the entry's directory, on Linux with OpenSSL 3.5, ngtcp2 and libdeflate installed (the Dockerfile shows how):

curl -fsSL https://scaly.io/install.sh | sh
scaly build arena.scaly --release -o arena
./arena                                        # :8080, TLS :8081, HTTP/2 :8443, h2c :8082
curl 'http://localhost:8080/baseline11?a=1&b=2'  # 3

The numbers are HttpArena's, measured on its machine against every other entry: www.http-arena.com.