Production Settings

This guide covers the server configuration options available in Zigmund for production deployments, including network settings, timeouts, TLS, and security middleware.

ServerConfig Reference

The ServerConfig struct controls the low-level behavior of the HTTP server. All fields have sensible defaults; override only what your deployment requires.

Production Example

A typical production configuration:

try app.serve(.{
    .host = "0.0.0.0",
    .port = 8080,
    .worker_count = 4,
    .max_connections = 10000,
    .max_header_bytes = 32 * 1024,
    .max_body_bytes = 4 * 1024 * 1024,
    .header_timeout_ms = 5_000,
    .body_timeout_ms = 15_000,
    .write_timeout_ms = 15_000,
    .idle_timeout_ms = 60_000,
    .shutdown_grace_period_ms = 30_000,
    .recv_buffer_size = 32 * 1024,
    .send_buffer_size = 64 * 1024,
    .overload_retry_after_seconds = 5,
});

Worker Count

When worker_count is set to 0 (the default), Zigmund calls std.Thread.getCpuCount() to detect the number of available CPU cores and spawns that many workers. In containerized environments, set this explicitly to match your CPU limit:

.worker_count = 4,

A single-threaded mode is used when the resolved worker count is 1.

Connection Limits

The max_connections field limits concurrent connections across all workers. When the limit is reached, new connections receive a 503 Service Unavailable response with a Retry-After header. This protects the server from resource exhaustion under load spikes.

Buffer Sizes

The recv_buffer_size and send_buffer_size fields control per-connection I/O buffers allocated on the hot path. Larger buffers reduce system calls for large payloads but increase per-connection memory usage:

• API workloads (small JSON payloads): 16 KB is sufficient.
• File uploads or large responses: increase to 64 KB or 128 KB.
• Memory-constrained environments: reduce to 8 KB.

TLS Configuration

Zigmund supports native TLS via OpenSSL. Configure TLS by providing a TlsConfig to the tls field of ServerConfig.

TlsConfig Reference

TLS Example

try app.serve(.{
    .host = "0.0.0.0",
    .port = 443,
    .worker_count = 4,
    .tls = .{
        .cert_pem_path = "/etc/ssl/certs/server.pem",
        .key_pem_path = "/etc/ssl/private/server-key.pem",
        .min_version = .tls_1_2,
        .client_auth = .none,
    },
});

Mutual TLS (mTLS)

For services that require client certificate verification:

.tls = .{
    .cert_pem_path = "/etc/ssl/certs/server.pem",
    .key_pem_path = "/etc/ssl/private/server-key.pem",
    .min_version = .tls_1_3,
    .client_auth = .required,
    .client_ca_pem_path = "/etc/ssl/certs/client-ca.pem",
},

TLS Protocol Versions

• .tls_1_2 -- TLS 1.2. Widely supported; recommended as the minimum version.
• .tls_1_3 -- TLS 1.3. Improved security and performance. Use as minimum when all clients support it.

Setting min_version to .tls_1_3 with max_version set to null enforces TLS 1.3 only. The server returns TlsProtocolVersionRangeInvalid if max_version is set to a version lower than min_version.

Graceful Shutdown

Zigmund supports graceful shutdown through a callback mechanism. When a shutdown signal is received:

1. The server stops accepting new connections.
2. New connections that arrive during shutdown receive a 503 Service Unavailable response with the message "server shutting down".
3. Active requests are allowed to complete.
4. After shutdown_grace_period_ms elapses, remaining connections are forcibly terminated.

The shutdown_grace_period_ms setting controls how long the server waits for in-flight requests. Set this to a value that covers your longest expected request:

.shutdown_grace_period_ms = 30_000, // 30 seconds

Set to 0 to shut down immediately without waiting for active connections.

Logging Configuration

Zigmund provides structured logging through the AppConfig settings:

const app = try Zigmund.init(allocator, .{
    .title = "My API",
    .version = "1.0.0",
    .structured_access_logs = true,
    .structured_telemetry_logs = true,
    .structured_trace_logs = true,
    .structured_metrics_logs = true,
    .structured_audit_logs = true,
    .structured_log_redaction_text = "[redacted]",
    .structured_log_redact_remote_addr = true,
    .structured_log_redact_user_agent = true,
});

Rate Limiting

The built-in rate limiting middleware protects your API from abuse. It uses a sliding window counter keyed by client IP:

const rate_limit = @import("zigmund").middleware.rate_limit;
app.addMiddleware(rate_limit, .{
    .max_requests = 100,
    .window_seconds = 60,
});

HTTPS Redirect Middleware

Redirect all HTTP traffic to HTTPS. Use this when TLS is terminated at the application level or when you want to enforce HTTPS even behind a proxy that sets X-Forwarded-Proto:

const https_redirect = @import("zigmund").middleware.https_redirect;
app.addMiddleware(https_redirect, .{
    .redirect_status = .temporary_redirect, // 307
    .https_port = null,                     // default 443
});

Trusted Host Middleware

Prevent host header attacks by validating the Host header against a whitelist:

const trusted_host = @import("zigmund").middleware.trusted_host;
app.addMiddleware(trusted_host, .{
    .allowed_hosts = &.{ "api.example.com", ".example.com" },
    .allow_missing_host = false,
});

Compression Middleware

Compress responses automatically using gzip when the client supports it:

const compression = @import("zigmund").middleware.compression;
compression.configure(.{
    .min_size = 1024,
    .level = 6,
    .compressible_types = &.{
        "text/",
        "application/json",
        "application/xml",
        "application/javascript",
        "application/xhtml+xml",
        "image/svg+xml",
    },
});

Full Production Configuration Example

Combining server settings with security middleware:

const std = @import("std");
const Zigmund = @import("zigmund");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();

    var app = try Zigmund.init(allocator, .{
        .title = "Production API",
        .version = "1.0.0",
        .structured_access_logs = true,
        .structured_audit_logs = true,
        .request_id_enabled = true,
    });

    // Security middleware
    const trusted_host = @import("zigmund").middleware.trusted_host;
    app.addMiddleware(trusted_host, .{
        .allowed_hosts = &.{ "api.example.com" },
    });

    const rate_limit = @import("zigmund").middleware.rate_limit;
    app.addMiddleware(rate_limit, .{
        .max_requests = 200,
        .window_seconds = 60,
    });

    const compression = @import("zigmund").middleware.compression;
    compression.configure(.{
        .min_size = 512,
        .level = 4,
    });

    // Register routes...

    try app.serve(.{
        .host = "0.0.0.0",
        .port = 8080,
        .worker_count = 4,
        .max_connections = 10000,
        .max_header_bytes = 32 * 1024,
        .max_body_bytes = 4 * 1024 * 1024,
        .header_timeout_ms = 5_000,
        .body_timeout_ms = 15_000,
        .write_timeout_ms = 15_000,
        .idle_timeout_ms = 60_000,
        .shutdown_grace_period_ms = 30_000,
        .tls = .{
            .cert_pem_path = "/etc/ssl/certs/server.pem",
            .key_pem_path = "/etc/ssl/private/server-key.pem",
            .min_version = .tls_1_2,
        },
    });
}