Get started with giong

Requirements

kernel

Linux 6.0 or newer, 6.1+ recommended. Developed and tested on 6.18.

rust

1.80 or newer for the libraries.

elsewhere

giong does not build on Windows or macOS. Use WSL2 with a 6.x kernel or a Linux virtual machine.

docker

Docker's default seccomp profile blocks io_uring. docs/DEPLOYMENT.md shows how to allow it in Docker, Compose and Kubernetes without turning seccomp off.

license

MIT OR Apache-2.0, at your option.

Install

The crates are on crates.io. Add the runtime and the layers you need; giong-http takes --features tls for HTTPS and --features client for its client.

cargo add giong
cargo add giong-http          # or giong-web for routing, middleware and JSON

A first server

Put this in src/main.rs. Every worker binds its own SO_REUSEPORT listener on the same port, and the kernel spreads connections across cores.

use std::time::Duration;
use giong::net::TcpListener;
use giong_http::{Request, Response, Server};

async fn handler(req: Request) -> Response {
    match (req.method(), req.path()) {
        ("GET", "/health") => Response::text("ok"),
        ("POST", "/echo") => Response::new(200).body(req.body().to_vec()),
        _ => Response::new(404),
    }
}

fn main() -> std::io::Result<()> {
    giong::Builder::new()
        .shutdown_on_signals(true)                  // Ctrl-C / SIGTERM stop it gracefully
        .shutdown_grace(Duration::from_secs(10))    // requests in progress are answered
        .build()?
        .run(|_worker| async {
            let listener = TcpListener::bind("0.0.0.0:8080").expect("bind");
            Server::new().serve(listener, handler).await;
        })
}

Then run it:

cargo run --release          # listens on port 8080
curl localhost:8080/health   # ok

Examples

Each one runs from a clone of the repository; the crates' READMEs have more. examples/

cargo run --release --example echo
nc 127.0.0.1 7000

cargo run --release --example http
curl localhost:3006/json

cargo run --release --example udp_echo
echo hello | nc -u -w1 127.0.0.1 7001

cargo run --release --example cat -- Cargo.toml

API reference

Every public item is documented, with an example where it helps.

Error codes

Every error giong raises starts with a code, says what went wrong and how to fix it, and links to its page. 81 codes so far. Match on giong::error::code(&err), never on the message.

GIONG-E0102: no address found for db.internal. Fix: check the spelling of the name,
/etc/hosts, and the DNS servers in /etc/resolv.conf (in a container, the network it is
attached to). See https://github.com/giong-run/Giong/blob/main/docs/errors/E0102.md

Generated from docs/errors/README.md

When giong is the wrong choice

Questions people ask

Work on giong

Read CONTRIBUTING.md first; coding agents have AGENTS.md. Open an issue before anything larger than a fix.

git clone https://github.com/giong-run/Giong.git && cd Giong
cargo test --workspace --all-features   # the whole suite, every crate