Skip to content

Add opt-in TCP port readiness check for upstream process #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
le0pard wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add opt-in TCP port readiness check for upstream process #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 27 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,31 +72,33 @@ In most cases, Thruster should work out of the box with no additional
configuration. But if you need to customize its behavior, there are a few
environment variables that you can set.

| Variable Name | Description | Default Value |
|-----------------------------|---------------------------------------------------------|---------------|
| `TLS_DOMAIN` | Comma-separated list of domain names to use for TLS provisioning. If not set, TLS will be disabled. | None |
| `TARGET_PORT` | The port that your Puma server should run on. Thruster will set `PORT` to this value when starting your server. | 3000 |
| `CACHE_SIZE` | The size of the HTTP cache in bytes. | 64MB |
| `MAX_CACHE_ITEM_SIZE` | The maximum size of a single item in the HTTP cache in bytes. | 1MB |
| `GZIP_COMPRESSION_ENABLED` | Whether to enable gzip compression for responses. Set to `0` or `false` to disable. | Enabled |
| `GZIP_COMPRESSION_DISABLE_ON_AUTH` | If set to `true`, disable gzip compression for authenticated requests with `Cookie`, `Authorization`, or `X-Csrf-Token` headers. | `false` |
| `GZIP_COMPRESSION_JITTER` | The amount of random jitter (in bytes) to add to the compressed response size to mitigate BREACH attacks. Set to `0` to disable. | 32 |
| `X_SENDFILE_ENABLED` | Whether to enable X-Sendfile support. Set to `0` or `false` to disable. | Enabled |
| `MAX_REQUEST_BODY` | The maximum size of a request body in bytes. Requests larger than this size will be refused; `0` means no maximum size is enforced. | `0` |
| `STORAGE_PATH` | The path to store Thruster's internal state. Provisioned TLS certificates will be stored here, so that they will not need to be requested every time your application is started. | `./storage/thruster` |
| `BAD_GATEWAY_PAGE` | Path to an HTML file to serve when the backend server returns a 502 Bad Gateway error. If there is no file at the specific path, Thruster will serve an empty 502 response instead. Because Thruster boots very quickly, a custom page can be a useful way to show that your application is starting up. | `./public/502.html` |
| `HTTP_PORT` | The port to listen on for HTTP traffic. | 80 |
| `HTTPS_PORT` | The port to listen on for HTTPS traffic. | 443 |
| `HTTP_IDLE_TIMEOUT` | The maximum time in seconds that a client can be idle before the connection is closed. | 60 |
| `HTTP_READ_TIMEOUT` | The maximum time in seconds that a client can take to send the request headers and body. | 30 |
| `HTTP_WRITE_TIMEOUT` | The maximum time in seconds during which the client must read the response. | 30 |
| `H2C_ENABLED` | Set to `1` or `true` to enable h2c (http/2 cleartext) | Disabled |
| `ACME_DIRECTORY` | The URL of the ACME directory to use for TLS certificate provisioning. | `https://acme-v02.api.letsencrypt.org/directory` (Let's Encrypt production) |
| `EAB_KID` | The EAB key identifier to use when provisioning TLS certificates, if required. | None |
| `EAB_HMAC_KEY` | The Base64-encoded EAB HMAC key to use when provisioning TLS certificates, if required. | None |
| `FORWARD_HEADERS` | Whether to forward X-Forwarded-* headers from the client. | Disabled when running with TLS; enabled otherwise |
| `LOG_REQUESTS` | Log all requests. Set to `0` or `false` to disable request logging | Enabled |
| `DEBUG` | Set to `1` or `true` to enable debug logging. | Disabled |
| Variable Name | Description | Default Value |
|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
Comment on lines +75 to +76
| `TLS_DOMAIN` | Comma-separated list of domain names to use for TLS provisioning. If not set, TLS will be disabled. | None |
Comment on lines +75 to +77
Comment on lines +75 to +77
Comment on lines +75 to +77
| `TARGET_PORT` | The port that your Puma server should run on. Thruster will set `PORT` to this value when starting your server. | 3000 |
| `CACHE_SIZE` | The size of the HTTP cache in bytes. | 64MB |
| `MAX_CACHE_ITEM_SIZE` | The maximum size of a single item in the HTTP cache in bytes. | 1MB |
| `GZIP_COMPRESSION_ENABLED` | Whether to enable gzip compression for responses. Set to `0` or `false` to disable. | Enabled |
| `GZIP_COMPRESSION_DISABLE_ON_AUTH` | If set to `true`, disable gzip compression for authenticated requests with `Cookie`, `Authorization`, or `X-Csrf-Token` headers. | `false` |
| `GZIP_COMPRESSION_JITTER` | The amount of random jitter (in bytes) to add to the compressed response size to mitigate BREACH attacks. Set to `0` to disable. | 32 |
| `X_SENDFILE_ENABLED` | Whether to enable X-Sendfile support. Set to `0` or `false` to disable. | Enabled |
| `MAX_REQUEST_BODY` | The maximum size of a request body in bytes. Requests larger than this size will be refused; `0` means no maximum size is enforced. | `0` |
| `STORAGE_PATH` | The path to store Thruster's internal state. Provisioned TLS certificates will be stored here, so that they will not need to be requested every time your application is started. | `./storage/thruster` |
| `BAD_GATEWAY_PAGE` | Path to an HTML file to serve when the backend server returns a 502 Bad Gateway error. If there is no file at the specific path, Thruster will serve an empty 502 response instead. Because Thruster boots very quickly, a custom page can be a useful way to show that your application is starting up. | `./public/502.html` |
| `HTTP_PORT` | The port to listen on for HTTP traffic. | 80 |
| `HTTPS_PORT` | The port to listen on for HTTPS traffic. | 443 |
| `HTTP_IDLE_TIMEOUT` | The maximum time in seconds that a client can be idle before the connection is closed. | 60 |
| `HTTP_READ_TIMEOUT` | The maximum time in seconds that a client can take to send the request headers and body. | 30 |
| `HTTP_WRITE_TIMEOUT` | The maximum time in seconds during which the client must read the response. | 30 |
| `H2C_ENABLED` | Set to `1` or `true` to enable h2c (http/2 cleartext) | Disabled |
| `WAIT_FOR_TARGET_PORT` | If set to `1` or `true`, Thruster will wait for the upstream application to bind to its port before starting the proxy server. | Disabled |
| `WAIT_FOR_TARGET_PORT_TIMEOUT` | The maximum time in seconds to wait for the upstream port to open. | 60 |
| `ACME_DIRECTORY` | The URL of the ACME directory to use for TLS certificate provisioning. | `https://acme-v02.api.letsencrypt.org/directory` (Let's Encrypt production) |
| `EAB_KID` | The EAB key identifier to use when provisioning TLS certificates, if required. | None |
| `EAB_HMAC_KEY` | The Base64-encoded EAB HMAC key to use when provisioning TLS certificates, if required. | None |
| `FORWARD_HEADERS` | Whether to forward X-Forwarded-* headers from the client. | Disabled when running with TLS; enabled otherwise |
| `LOG_REQUESTS` | Log all requests. Set to `0` or `false` to disable request logging | Enabled |
| `DEBUG` | Set to `1` or `true` to enable debug logging. | Disabled |

To prevent naming clashes with your application's own environment variables,
Thruster's environment variables can optionally be prefixed with `THRUSTER_`.
Expand Down
9 changes: 9 additions & 0 deletions internal/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ const (

defaultGzipCompressionDisableOnAuth = false
defaultGzipCompressionJitter = 32

defaultWaitForTargetPort = false
defaultWaitForTargetPortTimeout = 60 * time.Second
)

type Config struct {
Expand Down Expand Up @@ -70,6 +73,9 @@ type Config struct {

H2CEnabled bool

WaitForTargetPort bool
WaitForTargetPortTimeout time.Duration

ForwardHeaders bool

LogLevel slog.Level
Expand Down Expand Up @@ -114,6 +120,9 @@ func NewConfig() (*Config, error) {

H2CEnabled: getEnvBool("H2C_ENABLED", defaultH2CEnabled),

WaitForTargetPort: getEnvBool("WAIT_FOR_TARGET_PORT", defaultWaitForTargetPort),
WaitForTargetPortTimeout: getEnvDuration("WAIT_FOR_TARGET_PORT_TIMEOUT", defaultWaitForTargetPortTimeout),

LogLevel: logLevel,
LogRequests: getEnvBool("LOG_REQUESTS", defaultLogRequests),
}
Expand Down
10 changes: 10 additions & 0 deletions internal/config_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ func TestConfig_defaults(t *testing.T) {
assert.Equal(t, defaultCacheSize, c.CacheSizeBytes)
assert.Equal(t, slog.LevelInfo, c.LogLevel)
assert.Equal(t, false, c.H2CEnabled)
assert.Equal(t, false, c.WaitForTargetPort)
assert.Equal(t, 60*time.Second, c.WaitForTargetPortTimeout)
}

func TestConfig_override_defaults_with_env_vars(t *testing.T) {
Expand All @@ -121,6 +123,8 @@ func TestConfig_override_defaults_with_env_vars(t *testing.T) {
usingEnvVar(t, "H2C_ENABLED", "true")
usingEnvVar(t, "GZIP_COMPRESSION_DISABLE_ON_AUTH", "true")
usingEnvVar(t, "GZIP_COMPRESSION_JITTER", "64")
usingEnvVar(t, "WAIT_FOR_TARGET_PORT", "true")
usingEnvVar(t, "WAIT_FOR_TARGET_PORT_TIMEOUT", "5")

c, err := NewConfig()
require.NoError(t, err)
Expand All @@ -136,6 +140,8 @@ func TestConfig_override_defaults_with_env_vars(t *testing.T) {
assert.Equal(t, true, c.H2CEnabled)
assert.Equal(t, true, c.GzipCompressionDisableOnAuth)
assert.Equal(t, 64, c.GzipCompressionJitter)
assert.Equal(t, true, c.WaitForTargetPort)
assert.Equal(t, 5*time.Second, c.WaitForTargetPortTimeout)
}

func TestConfig_override_defaults_with_env_vars_using_prefix(t *testing.T) {
Expand All @@ -147,6 +153,8 @@ func TestConfig_override_defaults_with_env_vars_using_prefix(t *testing.T) {
usingEnvVar(t, "THRUSTER_DEBUG", "1")
usingEnvVar(t, "THRUSTER_LOG_REQUESTS", "0")
usingEnvVar(t, "THRUSTER_H2C_ENABLED", "1")
usingEnvVar(t, "THRUSTER_WAIT_FOR_TARGET_PORT", "1")
usingEnvVar(t, "THRUSTER_WAIT_FOR_TARGET_PORT_TIMEOUT", "10")

c, err := NewConfig()
require.NoError(t, err)
Expand All @@ -158,6 +166,8 @@ func TestConfig_override_defaults_with_env_vars_using_prefix(t *testing.T) {
assert.Equal(t, slog.LevelDebug, c.LogLevel)
assert.Equal(t, false, c.LogRequests)
assert.Equal(t, true, c.H2CEnabled)
assert.Equal(t, true, c.WaitForTargetPort)
assert.Equal(t, 10*time.Second, c.WaitForTargetPortTimeout)
}

func TestConfig_prefixed_variables_take_precedence_over_non_prefixed(t *testing.T) {
Expand Down
Loading
Loading