feat: add TCP keep-alive and connect delay for upstream connection

- Enable TCP keep-alive (30s) for connection health monitoring
- Add MODBUS_CONNECT_DELAY for post-connection settling time (default: 0)
- Use custom dialer with net.Dialer for keep-alive support

Author: tma

README.md

@@ -35,6 +35,7 @@ All configuration is via environment variables:
 | `MODBUS_READONLY` | Read-only mode: `false`, `true`, `deny` | `true` |
 | `MODBUS_TIMEOUT` | Upstream connection timeout | `10s` |
 | `MODBUS_REQUEST_DELAY` | Delay after each upstream request | `0` (disabled) |
+| `MODBUS_CONNECT_DELAY` | Silent period after connecting to upstream | `0` (disabled) |
 | `MODBUS_SHUTDOWN_TIMEOUT` | Graceful shutdown timeout | `30s` |
 | `LOG_LEVEL` | Log level: `INFO`, `DEBUG` | `INFO` |
 
@@ -76,6 +77,7 @@ services:
       MODBUS_READONLY: "true"
       MODBUS_TIMEOUT: "10s"
       MODBUS_REQUEST_DELAY: "0"
+      MODBUS_CONNECT_DELAY: "0"
       MODBUS_SHUTDOWN_TIMEOUT: "30s"
       LOG_LEVEL: "INFO"
     restart: unless-stopped

SPEC.md

@@ -43,6 +43,8 @@ Many Modbus devices (inverters, meters, battery systems) have limited polling ca
 - Support clients requesting different slave IDs through the proxy
 - Auto-reconnect on connection failure (unlimited retries, no backoff)
 - Request pacing: configurable delay between upstream requests to prevent overwhelming slow devices
+- TCP keep-alive enabled (30s interval) for connection health monitoring
+- Connect delay: optional silent period after establishing connection for device settling
 
 ### 3. In-Memory Cache
 
@@ -102,6 +104,7 @@ Three modes:
 | `MODBUS_READONLY` | Read-only mode | `true` | `false`, `true`, `deny` |
 | `MODBUS_TIMEOUT` | Upstream connection timeout | `10s` | `5s`, `30s` |
 | `MODBUS_REQUEST_DELAY` | Delay after each upstream request | `0` (disabled) | `100ms`, `500ms` |
+| `MODBUS_CONNECT_DELAY` | Silent period after connecting to upstream | `0` (disabled) | `500ms`, `2s` |
 | `MODBUS_SHUTDOWN_TIMEOUT` | Graceful shutdown timeout | `30s` | `10s`, `60s` |
 | `LOG_LEVEL` | Log level | `INFO` | `INFO`, `DEBUG` |
 
@@ -195,6 +198,7 @@ level=DEBUG msg="cache hit" slave_id=1 func=0x03 addr=0 qty=10
 level=DEBUG msg="cache miss" slave_id=1 func=0x03 addr=0 qty=10
 level=DEBUG msg="upstream request completed" slave_id=1 func=0x03 addr=0 qty=10 duration=15ms
 level=DEBUG msg="applying request delay" delay=100ms
+level=DEBUG msg="applying connect delay" delay=500ms
 level=WARN msg="upstream error, serving stale" slave_id=1 error="timeout"
 level=INFO msg="shutting down"
 ```

internal/config/config.go

@@ -28,6 +28,7 @@ type Config struct {
 	ReadOnly        ReadOnlyMode
 	Timeout         time.Duration
 	RequestDelay    time.Duration
+	ConnectDelay    time.Duration
 	ShutdownTimeout time.Duration
 	LogLevel        string
 }
@@ -43,6 +44,7 @@ func Load() (*Config, error) {
 		ReadOnly:        ReadOnlyOn,
 		Timeout:         10 * time.Second,
 		RequestDelay:    0,
+		ConnectDelay:    0,
 		ShutdownTimeout: 30 * time.Second,
 		LogLevel:        getEnv("LOG_LEVEL", "INFO"),
 	}
@@ -106,6 +108,15 @@ func Load() (*Config, error) {
 		cfg.RequestDelay = d
 	}
 
+	// Parse connect delay
+	if s := os.Getenv("MODBUS_CONNECT_DELAY"); s != "" {
+		d, err := time.ParseDuration(s)
+		if err != nil {
+			return nil, fmt.Errorf("invalid MODBUS_CONNECT_DELAY: %w", err)
+		}
+		cfg.ConnectDelay = d
+	}
+
 	// Parse shutdown timeout
 	if s := os.Getenv("MODBUS_SHUTDOWN_TIMEOUT"); s != "" {
 		d, err := time.ParseDuration(s)

internal/config/config_test.go

@@ -50,6 +50,9 @@ func TestLoad_Defaults(t *testing.T) {
 	if cfg.RequestDelay != 0 {
 		t.Errorf("expected 0 request delay, got %v", cfg.RequestDelay)
 	}
+	if cfg.ConnectDelay != 0 {
+		t.Errorf("expected 0 connect delay, got %v", cfg.ConnectDelay)
+	}
 	if cfg.ShutdownTimeout != 30*time.Second {
 		t.Errorf("expected 30s shutdown timeout, got %v", cfg.ShutdownTimeout)
 	}
@@ -76,6 +79,7 @@ func TestLoad_CustomValues(t *testing.T) {
 	os.Setenv("MODBUS_READONLY", "false")
 	os.Setenv("MODBUS_TIMEOUT", "5s")
 	os.Setenv("MODBUS_REQUEST_DELAY", "100ms")
+	os.Setenv("MODBUS_CONNECT_DELAY", "200ms")
 	os.Setenv("MODBUS_SHUTDOWN_TIMEOUT", "60s")
 	os.Setenv("LOG_LEVEL", "DEBUG")
 
@@ -88,6 +92,7 @@ func TestLoad_CustomValues(t *testing.T) {
 		os.Unsetenv("MODBUS_READONLY")
 		os.Unsetenv("MODBUS_TIMEOUT")
 		os.Unsetenv("MODBUS_REQUEST_DELAY")
+		os.Unsetenv("MODBUS_CONNECT_DELAY")
 		os.Unsetenv("MODBUS_SHUTDOWN_TIMEOUT")
 		os.Unsetenv("LOG_LEVEL")
 	}()
@@ -118,6 +123,9 @@ func TestLoad_CustomValues(t *testing.T) {
 	if cfg.RequestDelay != 100*time.Millisecond {
 		t.Errorf("expected 100ms request delay, got %v", cfg.RequestDelay)
 	}
+	if cfg.ConnectDelay != 200*time.Millisecond {
+		t.Errorf("expected 200ms connect delay, got %v", cfg.ConnectDelay)
+	}
 	if cfg.ShutdownTimeout != 60*time.Second {
 		t.Errorf("expected 60s shutdown timeout, got %v", cfg.ShutdownTimeout)
 	}
@@ -174,7 +182,7 @@ func TestLoad_InvalidDuration(t *testing.T) {
 	os.Setenv("MODBUS_UPSTREAM", "localhost:502")
 	defer os.Unsetenv("MODBUS_UPSTREAM")
 
-	tests := []string{"MODBUS_CACHE_TTL", "MODBUS_TIMEOUT", "MODBUS_REQUEST_DELAY", "MODBUS_SHUTDOWN_TIMEOUT"}
+	tests := []string{"MODBUS_CACHE_TTL", "MODBUS_TIMEOUT", "MODBUS_REQUEST_DELAY", "MODBUS_CONNECT_DELAY", "MODBUS_SHUTDOWN_TIMEOUT"}
 	for _, envVar := range tests {
 		os.Setenv(envVar, "invalid")
 		_, err := Load()

internal/modbus/client.go

@@ -5,6 +5,7 @@ import (
 	"encoding/binary"
 	"fmt"
 	"log/slog"
+	"net"
 	"sync"
 	"time"
 
@@ -16,6 +17,7 @@ type Client struct {
 	address      string
 	timeout      time.Duration
 	requestDelay time.Duration
+	connectDelay time.Duration
 	logger       *slog.Logger
 
 	mu     sync.Mutex
@@ -24,11 +26,12 @@ type Client struct {
 }
 
 // NewClient creates a new Modbus TCP client.
-func NewClient(address string, timeout, requestDelay time.Duration, logger *slog.Logger) *Client {
+func NewClient(address string, timeout, requestDelay, connectDelay time.Duration, logger *slog.Logger) *Client {
 	return &Client{
 		address:      address,
 		timeout:      timeout,
 		requestDelay: requestDelay,
+		connectDelay: connectDelay,
 		logger:       logger,
 	}
 }
@@ -46,16 +49,28 @@ func (c *Client) connectLocked(ctx context.Context) error {
 		c.conn.Close()
 	}
 
-	handler := modbus.NewTCPClientHandler(c.address)
+	// Custom dialer with TCP keep-alive for connection health monitoring
+	dialer := &net.Dialer{
+		Timeout:   c.timeout,
+		KeepAlive: 30 * time.Second,
+	}
+
+	handler := modbus.NewTCPClientHandler(c.address, modbus.WithDialer(dialer.DialContext))
 	handler.Timeout = c.timeout
 	handler.IdleTimeout = c.timeout
+	handler.ConnectDelay = c.connectDelay
 
 	if err := handler.Connect(ctx); err != nil {
 		return fmt.Errorf("connect to %s: %w", c.address, err)
 	}
 
 	c.conn = handler
 	c.client = modbus.NewClient(handler)
+
+	if c.connectDelay > 0 {
+		c.logger.Debug("applying connect delay", "delay", c.connectDelay)
+	}
+
 	c.logger.Info("connected to upstream", "address", c.address)
 	return nil
 }

internal/proxy/proxy.go

@@ -27,7 +27,7 @@ func New(cfg *config.Config, logger *slog.Logger) (*Proxy, error) {
 	p := &Proxy{
 		cfg:    cfg,
 		logger: logger,
-		client: modbus.NewClient(cfg.Upstream, cfg.Timeout, cfg.RequestDelay, logger),
+		client: modbus.NewClient(cfg.Upstream, cfg.Timeout, cfg.RequestDelay, cfg.ConnectDelay, logger),
 		cache:  cache.New(cfg.CacheTTL),
 	}