feat: make the backend dial timeout configurable (--backend-dial-timeout) (#570)

Follow-up to #569: replace the fixed 2s backendDialTimeout constant with a --backend-dial-timeout flag (env BACKEND_DIAL_TIMEOUT), defaulting to the same 2s. Operators whose backends are reachable quickly (e.g. on-cluster Kubernetes Services) can lower it so the asleep MOTD / scale-up fallback fires sooner on a scaled-to-zero backend.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: wachirachoomsiri

README.md

@@ -44,6 +44,8 @@ Some other features included:
     	If set, statically-configured backends are scaled up on access and down after idle by POSTing to this URL (env AUTO_SCALE_WEBHOOK_URL)
   -auto-scale-webhook-wake-timeout duration
     	Maximum time to wait for the backend to become reachable after a scale-up webhook (env AUTO_SCALE_WEBHOOK_WAKE_TIMEOUT) (default 1m0s)
+  -backend-dial-timeout duration
+    	Timeout for establishing the TCP connection to a backend. Bounds how long a dial to a scaled-to-zero server's Service (no endpoints) waits before the auto-scale asleep MOTD / scale-up fallback is served; operators with fast on-cluster backends can lower it so that fallback fires sooner (env BACKEND_DIAL_TIMEOUT) (default 2s)
   -clients-to-allow value
     	Zero or more client IP addresses or CIDRs to allow. Takes precedence over deny. (env CLIENTS_TO_ALLOW)
   -clients-to-deny value

server/configs.go

@@ -46,6 +46,7 @@ type Config struct {
 	ApiBinding             string            `usage:"The [host:port] bound for servicing API requests"`
 	CpuProfile             string            `usage:"Enables CPU profiling and writes to given path"`
 	ConnectionRateLimit    int               `default:"1" usage:"Max number of connections to allow per second"`
+	BackendDialTimeout     time.Duration     `default:"2s" usage:"Timeout for establishing the TCP connection to a backend. Bounds how long a dial to a scaled-to-zero server's Service (no endpoints) waits before the auto-scale asleep MOTD / scale-up fallback is served; operators with fast on-cluster backends can lower it so that fallback fires sooner"`
 	InKubeCluster          bool              `usage:"Use in-cluster Kubernetes config"`
 	KubeConfig             string            `usage:"The path to a Kubernetes configuration file"`
 	KubeNamespace          string            `usage:"The namespace to watch or blank for all, which is the default"`

server/connector.go

@@ -30,7 +30,10 @@ const (
 	// before the auto-scale asleep MOTD is served from the dial-failure
 	// fallback below. A healthy backend accepts the TCP connection almost
 	// instantly, so this bound only trips on unreachable/asleep backends.
-	backendDialTimeout = 2 * time.Second
+	// Overridable via --backend-dial-timeout: operators whose backends are
+	// reachable faster (e.g. on-cluster Services) can lower it so the asleep
+	// MOTD / scale-up fallback fires sooner.
+	defaultBackendDialTimeout = 2 * time.Second
 )
 
 var noDeadline time.Time
@@ -89,6 +92,18 @@ func NewConnector(ctx context.Context, routes IRoutes, downScaler IDownScaler, m
 		activeConnections:          NewActiveConnections(),
 		scaleActiveConnections:     NewActiveConnections(),
 		wakingServers:              NewActiveConnections(),
+		backendDialTimeout:         defaultBackendDialTimeout,
+	}
+}
+
+// UseBackendDialTimeout overrides the timeout for establishing the TCP
+// connection to a backend (values <= 0 keep the default). Backends that are
+// reachable quickly — e.g. on-cluster Services — can use a shorter timeout so
+// the asleep-MOTD / scale-up fallback fires promptly on a scaled-to-zero
+// backend instead of waiting the full default.
+func (c *Connector) UseBackendDialTimeout(d time.Duration) {
+	if d > 0 {
+		c.backendDialTimeout = d
 	}
 }
 
@@ -118,6 +133,7 @@ type Connector struct {
 	connectionNotifier         ConnectionNotifier
 	asleepMOTD                 string
 	loadingMOTD                string
+	backendDialTimeout         time.Duration
 }
 
 func (c *Connector) UseConnectionNotifier(notifier ConnectionNotifier) {
@@ -655,7 +671,7 @@ func (c *Connector) findAndConnectBackend(frontendConn net.Conn,
 		Info("Connecting to backend")
 
 	//goland:noinspection GoResourceLeak ownership transferred to pumpConnections and closed with return statements below
-	backendConn, err := net.DialTimeout("tcp", backendHostPort, backendDialTimeout)
+	backendConn, err := net.DialTimeout("tcp", backendHostPort, c.backendDialTimeout)
 	if err != nil {
 		logrus.
 			WithError(err).

server/server.go

@@ -104,6 +104,7 @@ func NewServer(ctx context.Context, config *Config) (*Server, error) {
 
 	connector := NewConnector(ctx, routes, downscaler, metricsBuilder.BuildConnectorMetrics(), config.UseProxyProtocol, config.RecordLogins, autoScaleAllowDenyConfig)
 
+	connector.UseBackendDialTimeout(config.BackendDialTimeout)
 	connector.UseAsleepMOTD(config.AutoScale.AsleepMOTD)
 	connector.UseLoadingMOTD(config.AutoScale.LoadingMOTD)