Server Configuration

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

Introduction

Proper server configuration is essential for building production-ready web applications. Hyperlane provides a comprehensive configuration system that allows you to fine-tune both server-level and request-level settings. In this article, we'll explore ServerConfig, RequestConfig, and the JSON-based configuration approach that Hyperlane offers.

ServerConfig Overview

ServerConfig controls the behavior of the HTTP server itself — things like the listening address, TCP socket options, and connection settings. Here's how to create and configure a 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));

Address Configuration

The set_address method specifies the IP address and port that the server will listen on. You can bind to all network interfaces with "0.0.0.0:80" or restrict to localhost with "127.0.0.1:8080". This gives you flexibility in deployment scenarios — bind to all interfaces for production servers or restrict to localhost for development environments.

TCP Nodelay (Nagle's Algorithm)

The set_nodelay method controls Nagle's algorithm on the TCP socket. When enabled (Some(true)), Nagle's algorithm is disabled, which means small packets are sent immediately rather than being buffered and combined. This reduces latency at the expense of network efficiency. For most web applications, enabling nodelay is recommended to ensure responsive request handling:

config.set_nodelay(Some(true));

Setting nodelay to Some(false) enables Nagle's algorithm, which can improve throughput for applications that send many small messages but may introduce noticeable latency.

TTL (Time to Live)

The set_ttl method sets the IP TTL (Time to Live) field for outgoing packets. This value determines how many network hops a packet can traverse before being discarded:

config.set_ttl(Some(128));

A value of 128 is suitable for most applications. Lower values limit the packet's reach, while higher values allow it to traverse more network hops.

RequestConfig Overview

While ServerConfig controls server-level behavior, RequestConfig defines limits and settings for individual HTTP requests. This is crucial for preventing resource exhaustion and protecting against malicious or malformed requests.

Creating RequestConfig from JSON

Hyperlane allows you to define request configuration using a JSON string, which is convenient for loading configuration from files or environment variables:

let request_config_json: &'static str = 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 = RequestConfig::from_json(request_config_json).unwrap();

Let's examine each configuration parameter:

Parameter	Value (Example)	Description
buffer_size	8192	The size of the read buffer in bytes
max_path_size	8192	Maximum allowed URL path length
max_header_count	100	Maximum number of headers per request
max_header_key_size	8192	Maximum size of a single header key
max_header_value_size	8192	Maximum size of a single header value
max_body_size	2097152 (2MB)	Maximum allowed request body size
read_timeout_ms	6000 (6s)	Timeout for reading request data

These limits are important security measures. Without them, an attacker could send extremely large headers or paths to exhaust server memory. The max_body_size is particularly important for preventing denial-of-service attacks through oversized request bodies.

Using RequestConfig with a Server

Once you've created a RequestConfig, you can create a server from it:

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

This creates a server that applies the request configuration to all incoming connections.

JSON-Based Server Configuration

For scenarios where you want to configure the entire server from a single JSON source, Hyperlane provides the config_from_json method. This is particularly useful when loading configuration from environment variables, configuration files, or container orchestration systems:

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

The JSON format accepts the following fields:

Field	Type	Description
address	String	The bind address (e.g., "0.0.0.0:80")
nodelay	Boolean	Whether to disable Nagle's algorithm
ttl	Number	The IP TTL value

This approach is ideal for containerized deployments where configuration is often passed via environment variables. You can load the JSON from a file at startup or from an environment variable, making your application more flexible and easier to deploy across different environments.

Complete Configuration Example

Let's put everything together in a complete example that demonstrates both ServerConfig and RequestConfig:

use hyperlane::*;

#[tokio::main]
async fn main() {
    // Configure server-level settings
    let mut config: ServerConfig = ServerConfig::default();
    config.set_address("0.0.0.0:80");
    config.set_nodelay(Some(true));
    config.set_ttl(Some(128));

    // Create server with configuration
    let mut server: Server = Server::from(config);
    let server_control_hook: ServerControlHook = server.run().await.unwrap_or_default();
    server_control_hook.wait().await;
}

In this example, we:

1. Create a ServerConfig with default values
2. Set the bind address to all interfaces on port 80
3. Enable nodelay for low-latency responses
4. Set TTL to 128
5. Create a server from the configuration
6. Run and wait for the server

Default Values

When you use ServerConfig::default() or RequestConfig::default(), Hyperlane applies sensible defaults:

• ServerConfig: Binds to a default address with standard TCP settings
• RequestConfig: Applies reasonable limits on headers, paths, and body sizes

These defaults are designed to work well for most applications while still providing basic protection against resource exhaustion. You only need to override the settings that matter for your specific use case.

Best Practices

Here are some configuration best practices for production deployments:

1. Use JSON configuration for deployment flexibility: Store your server configuration in JSON format so it can be easily loaded from environment variables or config files.

2. Set appropriate request limits: Configure max_body_size based on your application's needs. If you only serve JSON APIs, 2MB is usually more than enough. For file upload endpoints, adjust accordingly.

3. Enable nodelay for API servers: If your application serves APIs where latency matters, enable nodelay with set_nodelay(Some(true)).

4. Set reasonable read timeouts: The read_timeout_ms setting prevents slow clients from holding connections open indefinitely. 6000ms (6 seconds) is a good starting point.

5. Bind to specific interfaces in production: Instead of 0.0.0.0, consider binding to specific interfaces when you know which network your server should be accessible from.

Conclusion

Hyperlane's configuration system is designed to be both powerful and easy to use. Whether you prefer programmatic configuration through Rust code or declarative configuration through JSON, the library provides the flexibility to configure your server exactly as you need it. The two-tier configuration approach — ServerConfig for server-level settings and RequestConfig for request-level limits — gives you fine-grained control over your server's behavior.

In the next article, we'll explore how to create and run a server in more detail, including multi-server setups and graceful shutdown.

---

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