Thruster Documentation

Thruster provides two mechanisms to protect against the BREACH attack, which targets secrets in compressed, encrypted traffic:

1. Random Jitter (Default): Thruster adds random padding to the size of compressed responses. This is controlled by the GZIP_COMPRESSION_JITTER environment variable (default is 32 bytes). Setting this to 0 disables jitter.
2. Compression Guard (Recommended for high security): You can disable compression entirely for requests that contain sensitive authentication headers (Cookie, Authorization, or X-Csrf-Token). This eliminates the side-channel for sensitive traffic.

To enable the Compression Guard, set: GZIP_COMPRESSION_DISABLE_ON_AUTH=true

To use Thruster, prefix your application's startup command with thrust. Thruster acts as a wrapper that manages the Puma process for you, making it ideal for containerized environments where you want a single CMD to handle both the proxy and the web server.

Basic Usage (HTTP only)

Run your server normally, prefixed with thrust:

$ thrust bin/rails server

Usage with Automatic TLS

To enable automatic TLS certificate management via Let's Encrypt, you must set the TLS_DOMAIN environment variable to your domain name:

$ TLS_DOMAIN=myapp.example.com thrust bin/rails server

Thruster is distributed as a Ruby gem. Because the core is written in Go, the gem automatically fetches the appropriate platform-specific binary for your system during installation.

To install it in your Rails application, add it to your Gemfile:

gem 'thruster'

Alternatively, you can install it globally on your system using the gem command.

The Server type is the primary entrypoint for running the Thruster proxy. It manages both HTTP and HTTPS listeners, handles TLS certificate management via ACME (autocert), and supports automatic HTTP-to-HTTPS redirection.

To use the server, call NewServer with a *Config and an http.Handler (the backend application or proxy logic), then call Start() to begin listening for requests. Use Stop() to perform a graceful shutdown with a 5-second timeout.

// Example usage of the Server
server := internal.NewServer(config, myHandler)

if err := server.Start(); err != nil {
	log.Fatal(err)
}

// ... run application ...

server.Stop()

The thrust command is the primary entrypoint for the Thruster service. When executed, it initializes a configuration from the environment, sets up a JSON logger at the configured log level, and starts the Thruster service. The service runs and will exit with a non-zero status code if it encounters a fatal error.

# The command is typically invoked via the compiled binary
./thrust

The Start() method initializes the network listeners and starts the HTTP and HTTPS servers in separate goroutines.

• If TLS is configured (config.HasTLS() is true): It sets up an autocert.Manager for automatic certificate acquisition, configures an HTTP redirect handler to force HTTPS, and starts both HTTP and HTTPS listeners.
• If TLS is not configured: It only starts an HTTP server on the configured HttpPort using the provided handler.

func (s *Server) Start() error

The NewServer function initializes a Server struct with the provided configuration and the HTTP handler that will process incoming requests.

func NewServer(config *Config, handler http.Handler) *Server

The Stop() method performs a graceful shutdown of both the HTTP and HTTPS servers. It uses a background context with a 5-second timeout to allow active connections to complete before closing.

func (s *Server) Stop()