HTTP

server.HTTPConfig configures HTTP and HTTPS access, allowed methods, compression, and trusted proxies.

var Config = server.HTTPConfig{
    Host: "localhost",
    Port: 3000,

    TLS: server.TLSConfig{
        Enabled: false,
        Type: "auto",
        Domains: []string{},
        RedirectHTTP: true,
    },

    MethodsAllowed: []string{
        "GET",
        "HEAD",
        "POST",
        "OPTIONS",
    },

    Compression: server.CompressionConfig{
        Enabled: true,
        OrderPriority: []string{
            "zstd",
            "gzip",
            "brotli",
            "deflate",
        },
        Zstd: server.CompressionAlgorithmConfig{
            Enabled: true,
            Level:   1,
        },
        Gzip: server.CompressionAlgorithmConfig{
            Enabled: true,
            Level:   3,
        },
        Brotli: server.CompressionAlgorithmConfig{
            Enabled: true,
            Level:   3,
        },
        Deflate: server.CompressionAlgorithmConfig{
            Enabled: true,
            Level:   3,
        },
    },
}

Structure

HTTPConfig {
    Host string
    Port int
    TLS server.TLSConfig
    MethodsAllowed []string
    Compression server.CompressionConfig
    ResolverIPForwarded server.ResolverIPForwardedConfig
}

The methods are normalized to capital letters. Empty, duplicated or unsupported values are ignored; if no valid method remains, GOX uses the default list.

HTTP Protocols

GOX supports HTTP / 1.1, HTTP / 2 and HTTP / 3 transparently. By activating HTTPS, the three protocols are available and each client can use the one that is compatible with their connection.

You do not need to set up anything additional or adapt your pages. Your routes, sessions and components maintain the same behavior, regardless of the protocol used. WebSocket also retains its usual operation.

HTTPS and certificates

Configure TLS to offer your application via HTTPS. You can let GOX get and renew the certificates or use your own files.

HTTPS is disabled when Enabled it is false. To activate it, it establishes Enabled: true and configure the way you want to use.

Automatic configuration

TLS: server.TLSConfig{
    Enabled: true,
    Type: "auto",
    Domains: []string{"example.com", "www.example.com"},
    RedirectHTTP: true,
},

GOX automatically obtains and renews the certificates with Let's Encrypt. Type: "auto", GOX chooses the domain validation method. If you configure a DNS provider, use DNS-01. Activate the automatic mode accepts the service terms of Let's Encrypt. Email is an optional ACME contact.

The values distinguish capital letters. Automatic modes require at least one domain, do not support CertFile / KeyFile and only allow wildcard with DNS. Domains the names with which you will access your application.

DNS Providers

Configure DNS with the supplier that manages your domain. This option allows you to validate wildcard domains, such as *.example.com. Example with Cloudflare:

import (
    os "os"
    server "github.com/gox-lang/gox/server"
    cloudflare "github.com/libdns/cloudflare"
)

var Config = server.HTTPConfig{
    Host: "0.0.0.0",
    Port: 80,
    TLS: server.TLSConfig{
        Enabled: true,
        Type: "auto",
        Domains: []string{"example.com", "*.example.com"},
        DNS: &cloudflare.Provider{
            APIToken: os.Getenv("CLOUDFLARE_API_TOKEN"),
        },
        RedirectHTTP: true,
    },
}

Install the supplier package by gox get and configure your credentials. For this example:

gox get github.com/libdns/cloudflare

Use a version compatible with DNSProvider (libdns v1). Provides the credentials using environment variables, without including them in the code.

DNS validation does not require opening ports 80 or 443. For visitors to access your application via HTTPS, port 443 must be available.

Manual certificates

TLS: server.TLSConfig{
    Enabled: true,
    Type: "manual",
    CertFile: "certificates/fullchain.pem",
    KeyFile: "certificates/privatekey.pem",
    RedirectHTTP: true,
},

The files must contain the certificate string and its private key in PEM. Relative routes start from the project root; absolute routes are allowed. The pair must be compatible and the certificate must be within its validity period. This mode does not support DNS or Email ACME.

You can replace the files to update the certificate without reboot GOX. See Reloading.

Ports and redirection

HTTP.Port corresponds to HTTP and uses 3000 when it is zero. TLS.Port corresponds to HTTPS and uses 443 when it is zero. HTTP and HTTPS use HTTP.Host and must have different ports. HTTPS supports TLS 1.2 or later.

For HTTP-01, it allows public access by port 80. HTTP.Port: 80 or, if you use a container, publish its HTTP port as 80. For TLS-ALPN-01, it allows public access by 443 directly to GOX. If another server manages HTTPS in front of GOX, it uses HTTP-01 or DNS-01.

With RedirectHTTP: trueHTTP requests are redirected to HTTPS by code 308, retaining the method, body, route and parameters. The destination is always public HTTPS 443, not including the internal port. A public mapping 443 → internal 8443 does not change that destination. If you expose HTTPS in another public port, disable this redirection and summarize it externally.

The redirection only supports the domains configured or included in your manual certificate. RedirectHTTP does not disable HTTPS or the automatic validation of certificates.

Persistence and deployment

GOX retains the certificates and their keys in <GOX_HOME>/.tls/. If you don't define GOX_HOME, use the directory where GOX is installed.

Keep this folder in reboot. In a container, use persistent storage and allow GOX to write in it to renew the certificates. Do not include the private keys in the repository of your project.

Compression

CompressionConfig allows to order and configure zstd, gzip, brotli and deflate. OrderPriority sets the negotiating order and each algorithm has Enabled and Level.

server.DefaultHTTPCompressionConfig() It is an auxiliary function to enable the four algorithms with the dynamic compression defaults:

Compression: server.DefaultHTTPCompressionConfig(),

You can use the helper when you accept all its values or expand server.CompressionConfig when you need to modify the order, disable an algorithm or choose different levels.

Forwarded IP

ResolverIPForwarded: server.ResolverIPForwardedConfig{
    TrustedProxies: []string{
        "127.0.0.1",
        "10.0.0.0/8",
    },
    Headers: []string{
        "CF-Connecting-IP",
        "X-Real-IP",
        "X-Forwarded-For",
    },
    RequireTrustedProxy: true,
},

TrustedProxies accepts IP addresses and CIDR ranges. GOX only trusts the configured headers when the connection comes from one of those proxies. Headers is empty, uses CF-Connecting-IP, X-Real-IP and X-Forwarded-For.

With RequireTrustedProxy: true, an request that does not come from a reliable proxy is rejected.

TrustedProxies also determines who can communicate HTTPS by X-Forwarded-Proto. Trust depends on the proxy IP that connects to GOX. Only one exact value is accepted https. RequireTrustedProxy: false allows direct connections but does not turn its headers into reliable. The proxy must overwrite that header.

If your proxy receives HTTPS and communicates with GOX by HTTP, configure your IP on TrustedProxies and have him send X-Forwarded-Proto: httpsThus GOX recognizes secure access and avoids repeated redirections.

The resolved IP can be part of the identity used by Rate limit. The compression of Static files uses the same types, but defaults different. HTTP within server.Config is presented in Configuration.

Reloading

MethodsAllowed and Compression apply to post-change requests. Modify host, ports or TLS configuration automatically reboot GOX. Proxies policy may also require reboot when RedirectHTTP During that reboot, WebSocket connections must be reconnected.

If the new configuration is not valid, GOX retains the previous one.

To update a manual certificate, replace your PEM files. You do not need to restart GOX. If the files do not form a valid pair or the certificate is out of effect, the previous certificate is kept and a notice is displayed.

Automatic certificates are renewed without intervention and without GOX reboot. If a recharge creates a new DNS supplier instance, GOX reboot to apply that configuration.

Best practices

• Expon only the methods used by the application.
• It explicitly sets up reliable proxies.
• Do not accept reshipped headers of any origin.
• Adjust the compression according to the cost of CPU and the size of the responses.

See also

• Configuration
• Static files
• Rate limit