Quick Start Guide

Project Code：https://github.com/hyperlane-dev/hyperlane

Welcome to hyperlane — a lightweight, high-performance, cross-platform Rust HTTP server library built on top of Tokio. This guide will walk you through everything you need to know to get your first hyperlane server up and running in minutes.

What is Hyperlane?

Hyperlane is a Rust HTTP server framework designed for speed, simplicity, and developer productivity. Built on the battle-tested Tokio async runtime, it provides a clean and intuitive API for building web services, APIs, and real-time applications. Whether you're building a simple REST API or a complex microservice architecture, hyperlane gives you the tools you need with minimal overhead.

Key highlights:

• Lightweight: Minimal dependencies and a small footprint.
• High Performance: Benchmarks show hyperlane competing with and often surpassing popular frameworks like Rocket and Gin.
• Cross-Platform: Works seamlessly on Linux, macOS, and Windows.
• Attribute Macros: Reduce boilerplate with powerful derive and attribute macros.
• WebSocket & SSE: Built-in support for real-time communication patterns.

Installation

Getting started with hyperlane is as simple as adding it to your Rust project's dependencies. Open your terminal and run:

cargo add hyperlane

This command adds the latest version of hyperlane to your Cargo.toml file. Make sure you have the Tokio runtime available, as hyperlane depends on it for async execution.

Your First Server

Let's create the simplest possible hyperlane server. Create a new Rust project if you haven't already:

cargo new my-hyperlane-app
cd my-hyperlane-app
cargo add hyperlane

Now, replace the contents of src/main.rs with the following code:

#[tokio::main]
async fn main() {
    let mut server: Server = Server::default();
    let server_control_hook: ServerControlHook = server.run().await.unwrap_or_default();
    server_control_hook.wait().await;
}

Let's break down what each line does:

1. #[tokio::main] — This attribute macro initializes the Tokio async runtime, which hyperlane relies on for handling concurrent connections.
2. Server::default() — Creates a new server instance with default configuration (listens on 0.0.0.0:80).
3. server.run().await — Starts the server asynchronously and returns a ServerControlHook.
4. server_control_hook.wait().await — Blocks the main thread until the server is shut down, keeping your application alive.

Run the server with:

cargo run

Congratulations! You now have a hyperlane server running. While it doesn't handle any routes yet, the server is fully operational and ready to be configured.

Configuring Your Server

Hyperlane provides flexible configuration options. You can configure the server using ServerConfig:

let mut config: ServerConfig = ServerConfig::default();
config.set_address("0.0.0.0:80");
config.set_nodelay(Some(true));
config.set_ttl(Some(128));

This configures the server to listen on all interfaces at port 80, enables TCP TCP_NODELAY for reduced latency, and sets the IP TTL to 128.

You can also create a server directly from a ServerConfig:

let server_config: ServerConfig = ServerConfig::default();
let mut server: Server = Server::from(server_config);

Alternatively, you can configure the server using JSON:

let config_json = r#"{ "address": "0.0.0.0:80", "nodelay": true, "ttl": 64 }"#;
let mut server = Server::default();
server.config_from_json(config_json);

This is particularly useful when loading configuration from environment variables or configuration files.

Configuring Request Handling

Hyperlane also allows you to configure how incoming requests are parsed and buffered via RequestConfig:

let request_config_json = r#"{ "buffer_size": 8192, "max_path_size": 8192, "max_header_count": 100, "max_header_key_size": 8192, "max_header_value_size": 8192, "max_body_size": 2097152, "read_timeout_ms": 6000 }"#;
let request_config = RequestConfig::from_json(request_config_json).unwrap();

This configuration controls:

Parameter	Description	Default
buffer_size	Read buffer size in bytes	8192
max_path_size	Maximum URL path length	8192
max_header_count	Maximum number of headers per request	100
max_header_key_size	Maximum header key size	8192
max_header_value_size	Maximum header value size	8192
max_body_size	Maximum request body size	2097152
read_timeout_ms	Read timeout in milliseconds	6000

You can create a server from a RequestConfig as well:

let request_config: RequestConfig = RequestConfig::default();
let mut server: Server = Server::from(request_config);

Using Attribute Macros

One of hyperlane's most powerful features is its attribute macro system, which can significantly reduce boilerplate code. Instead of manually creating and configuring the server in main(), you can use the #[hyperlane] attribute macro:

#[hyperlane(server: Server)]
#[hyperlane(server_config: ServerConfig)]
#[tokio::main]
async fn main() {
    server.server_config(server_config);
    let server_control_hook = server.run().await.unwrap_or_default();
    server_control_hook.wait().await;
}

With this approach, the server and server_config variables are automatically generated and injected by the macro. You can then configure them directly in the function body. This pattern is especially useful when combined with other attribute macros for routes, middleware, and request handling.

Adding Your First Route

A server without routes isn't very useful. Let's add a simple route:

#[route("/test/{text}")]
struct Route;

This creates a route that matches paths like /test/hello or /test/world. The {text} part is a dynamic path parameter that you can access in your route handler.

Register the route with the server:

server.route::<Route>("/test");
server.route::<Route>("/test/{text}");
server.route::<Route>("/test/{number:\\d+}");

The third example shows a regex-constrained parameter — {number:\\d+} only matches paths where the parameter consists of one or more digits.

Performance at a Glance

Hyperlane is designed for speed. Here are some benchmark comparisons:

• Without Keep-Alive: hyperlane QPS 51031, Tokio 49555, Rocket 49345, Gin 40149
• With Keep-Alive: Tokio 340130, hyperlane 334888, Rocket 298945, Gin 242570
• ab test (1 million requests): hyperlane 316211 QPS (Keep-Alive), Tokio 308596

These numbers demonstrate that hyperlane delivers competitive performance across different scenarios.

Next Steps

Now that you have a basic understanding of hyperlane, here are some topics to explore next:

• Routing Basics — Learn about dynamic routes, route parameters, and route filters.
• Middleware System — Understand how to use middleware for cross-cutting concerns like authentication and logging.
• Request Handling — Dive deep into parsing request bodies, headers, and query parameters.
• Response Building — Master the art of constructing HTTP responses with proper headers and status codes.
• WebSocket and SSE — Build real-time features with WebSocket and Server-Sent Events.
• Error Handling and Graceful Shutdown — Learn how to handle errors gracefully and shut down your server cleanly.

Hyperlane's combination of performance, ergonomics, and powerful macros makes it an excellent choice for building modern web applications in Rust. Happy coding!

---

Project Code：https://github.com/hyperlane-dev/hyperlane