Documentation

Configuration

Complete reference for the Linux amd64 Config struct, covering networking, TLS, io_uring worker sizing, limits, compression, and debugging.

Getting Started Benchmarks Routing Middleware Request & Response WebSocket Reverse Proxy TLS & ACME Rate Limiting Streaming & Files Configuration

Quick Reference

Minimal config to get started on Linux amd64:

Zero values are not always the runtime values you will see in logs. For example, WorkerCount and Listeners both default to 0 in config and are derived later by the Linux io_uring runtime.

go 
s := core.New(core.Config{Addr: ":8080", PlainHTTP: true})

s := core.New(core.Config{
    Addr:        ":443",
    TLSCertFile: "cert.pem",
    TLSKeyFile:  "key.pem",
})

s := core.New(core.Config{
    Addr:     ":443",
    HTTPAddr: ":80",
    ACME: &core.ACMEConfig{
        Email:   "you@example.com",
        Domains: []string{"example.com"},
    },
})

Network

Field Type Default Description
Addr string ":8443" Listen address (e.g. :443, 0.0.0.0:8080)
HTTPAddr string "" (auto :80 when Addr is :443) HTTP listen address for ACME challenges & HTTPS redirect
ServerName string "ALOS" Value for the Server response header
TrustedProxies []string nil IP ranges to trust for X-Forwarded-For / X-Real-IP

TLS & Certificates

Field Type Default Description
TLSCertFile string "" Path to PEM certificate file
TLSKeyFile string "" Path to PEM private key file
Certs []CertConfig nil Multi-domain certs (Domain, CertFile, KeyFile per entry)
DefaultDomain string "" Fallback cert domain for unknown SNI
ACME *ACMEConfig nil ACME / Let's Encrypt auto-certificate config

CertConfig

Field Type Description
Domain string SNI hostname to match
CertFile string Path to PEM certificate
KeyFile string Path to PEM private key

ACMEConfig

Field Type Default Description
Email string "" ACME account email
Domains []string nil Domains to obtain certificates for
CacheDir string "/etc/letsencrypt" Directory to cache certificates
ACMENode string "" Proxy ACME challenges to this address (e.g. "10.0.0.5:80")

Timeouts

Field Type Default Description
ReadTimeout time.Duration 0 (none) Max time to read entire request (0 = no timeout)
WriteTimeout time.Duration 0 (none) Max time to write entire response (0 = no timeout)
IdleTimeout time.Duration 120s Keep-alive idle connection timeout
HandshakeTimeout time.Duration 30s Max time for TLS handshake
ShutdownTimeout time.Duration 30s Graceful shutdown deadline

Size Limits

Field Type Default Description
MaxBodySize int64 0 (unlimited) Maximum request body size (0 = unlimited)
MaxReadSize int64 0 Max read size per request (0 = unlimited)
MaxWriteSize int64 0 Max write size per response (0 = unlimited)
MaxHeaderSize int 8 KB Maximum total header size

Bandwidth

Bandwidth limits use the BandwidthConfig struct with separate upload/download rates and burst size:

Field Type Default Description
ConnBandwidth BandwidthConfig {} Per-connection bandwidth limits
GlobalBandwidth BandwidthConfig {} Server-wide bandwidth limits

BandwidthConfig

Field Type Description
MaxUploadRate int64 Max upload speed in Mbps (0 = unlimited)
MaxDownloadRate int64 Max download speed in Mbps (0 = unlimited)
BurstSize int64 Burst allowance in Mbps before throttling
go 
s := core.New(core.Config{
    Addr: ":443",
    ConnBandwidth: core.BandwidthConfig{
        MaxDownloadRate: 40,
        BurstSize:       16,
    },
    GlobalBandwidth: core.BandwidthConfig{
        MaxDownloadRate: 4000,
        BurstSize:       800,
    },
})

Compression

Field Type Default Description
EnableCompress bool false Enable gzip/deflate response compression
CompressLevel int 6 Compression level (1–9, higher = smaller)
CompressMinSize int 256 Minimum response body size to compress

You can also enable compression via the Compress() middleware instead of config, which gives more control over the minimum size threshold.

Connection Limits

Field Type Default Description
MaxRequestsPerIP int64 0 (unlimited) Max concurrent requests from a single IP
MaxConcurrentReqs int64 0 (unlimited) Max concurrent requests server-wide
go 
s := core.New(core.Config{
    Addr:             ":443",
    MaxRequestsPerIP: 100,
    MaxConcurrentReqs: 10000,
})

Workers & Listeners

Field Type Default Description
WorkerCount int 0 Linux amd64 io_uring worker count. 0 lets ALOS size workers automatically.
Listeners int 0 Number of SO_REUSEPORT listeners. 0 lets ALOS derive the count; effectively one listener on non-Linux platforms.

Miscellaneous

Field Type Default Description
PlainHTTP bool false Run without TLS (plain HTTP mode)
Debug bool false Enable debug logging (connections, TLS, errors)
LogRequests bool true Log every request (method, path, status, duration)

Full Example

A production-ready configuration using most available options:

go 
s := core.New(core.Config{
    Addr:       ":443",
    HTTPAddr:   ":80",
    ServerName: "my-app",

    ACME: &core.ACMEConfig{
        Email:    "admin@example.com",
        Domains:  []string{"example.com", "api.example.com"},
        CacheDir: "/etc/alos/certs",
    },

    ReadTimeout:         15 * time.Second,
    WriteTimeout:        30 * time.Second,
    IdleTimeout:         120 * time.Second,
    HandshakeTimeout:    5 * time.Second,
    ShutdownTimeout:     30 * time.Second,

    MaxBodySize:   10 * 1024 * 1024,
    MaxHeaderSize: 16 * 1024,

    MaxRequestsPerIP:  100,
    MaxConcurrentReqs: 10000,

    ConnBandwidth: core.BandwidthConfig{
        MaxDownloadRate: 40,
        BurstSize:       16,
    },
    GlobalBandwidth: core.BandwidthConfig{
        MaxDownloadRate: 4000,
        BurstSize:       800,
    },

    EnableCompress: true,
    CompressLevel:   6,
    CompressMinSize: 1024,

    WorkerCount: 8,

    TrustedProxies: []string{"10.0.0.0/8", "172.16.0.0/12"},

    Debug:       false,
    LogRequests: true,
})
ESC