feat: add MODBUS_REQUEST_DELAY for upstream request pacing

Add configurable delay between upstream Modbus requests to prevent
overwhelming slow devices. The delay is only applied after successful
requests and is logged at DEBUG level.

Author: tma

README.md

@@ -34,6 +34,7 @@ All configuration is via environment variables:
 | `MODBUS_CACHE_SERVE_STALE` | Serve stale data on upstream error | `false` |
 | `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_SHUTDOWN_TIMEOUT` | Graceful shutdown timeout | `30s` |
 | `LOG_LEVEL` | Log level: `INFO`, `DEBUG` | `INFO` |
 
@@ -74,6 +75,7 @@ services:
       MODBUS_CACHE_SERVE_STALE: "false"
       MODBUS_READONLY: "true"
       MODBUS_TIMEOUT: "10s"
+      MODBUS_REQUEST_DELAY: "0"
       MODBUS_SHUTDOWN_TIMEOUT: "30s"
       LOG_LEVEL: "INFO"
     restart: unless-stopped

SPEC.md

@@ -42,6 +42,7 @@ Many Modbus devices (inverters, meters, battery systems) have limited polling ca
 - Support multiple slave IDs through single connection
 - 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
 
 ### 3. In-Memory Cache
 
@@ -71,6 +72,13 @@ type CacheEntry struct {
 - Second request arriving while first is pending will wait for and share the first's response
 - Prevents thundering herd on cache miss
 
+### Request Pacing
+- Configurable delay after each successful upstream request
+- Protects slow Modbus devices that cannot handle rapid-fire requests
+- Delay is context-aware: cancelled if the request context is cancelled
+- Only applied after successful requests (not during error recovery/reconnection)
+- Logged at DEBUG level when applied
+
 ### 4. Read-Only Mode
 Three modes:
 - `false`: Full read/write passthrough
@@ -93,6 +101,7 @@ Three modes:
 | `MODBUS_CACHE_SERVE_STALE` | Serve stale data on upstream error | `false` | `true`, `false` |
 | `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_SHUTDOWN_TIMEOUT` | Graceful shutdown timeout | `30s` | `10s`, `60s` |
 | `LOG_LEVEL` | Log level | `INFO` | `INFO`, `DEBUG` |
 
@@ -185,6 +194,7 @@ level=INFO msg="starting proxy" listen=:5502 upstream=192.168.1.100:502
 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 read" slave_id=1 func=0x03 addr=0 qty=10 duration=15ms
+level=DEBUG msg="applying request delay" duration=100ms
 level=WARN msg="upstream error, serving stale" slave_id=1 error="timeout"
 level=INFO msg="shutting down"
 ```

internal/config/config.go

@@ -27,6 +27,7 @@ type Config struct {
 	CacheServeStale bool
 	ReadOnly        ReadOnlyMode
 	Timeout         time.Duration
+	RequestDelay    time.Duration
 	ShutdownTimeout time.Duration
 	LogLevel        string
 }
@@ -41,6 +42,7 @@ func Load() (*Config, error) {
 		CacheServeStale: false,
 		ReadOnly:        ReadOnlyOn,
 		Timeout:         10 * time.Second,
+		RequestDelay:    0,
 		ShutdownTimeout: 30 * time.Second,
 		LogLevel:        getEnv("LOG_LEVEL", "INFO"),
 	}
@@ -95,6 +97,15 @@ func Load() (*Config, error) {
 		cfg.Timeout = d
 	}
 
+	// Parse request delay
+	if s := os.Getenv("MODBUS_REQUEST_DELAY"); s != "" {
+		d, err := time.ParseDuration(s)
+		if err != nil {
+			return nil, fmt.Errorf("invalid MODBUS_REQUEST_DELAY: %w", err)
+		}
+		cfg.RequestDelay = d
+	}
+
 	// Parse shutdown timeout
 	if s := os.Getenv("MODBUS_SHUTDOWN_TIMEOUT"); s != "" {
 		d, err := time.ParseDuration(s)

internal/config/config_test.go

@@ -47,6 +47,9 @@ func TestLoad_Defaults(t *testing.T) {
 	if cfg.Timeout != 10*time.Second {
 		t.Errorf("expected 10s timeout, got %v", cfg.Timeout)
 	}
+	if cfg.RequestDelay != 0 {
+		t.Errorf("expected 0 request delay, got %v", cfg.RequestDelay)
+	}
 	if cfg.ShutdownTimeout != 30*time.Second {
 		t.Errorf("expected 30s shutdown timeout, got %v", cfg.ShutdownTimeout)
 	}
@@ -72,6 +75,7 @@ func TestLoad_CustomValues(t *testing.T) {
 	os.Setenv("MODBUS_CACHE_SERVE_STALE", "true")
 	os.Setenv("MODBUS_READONLY", "false")
 	os.Setenv("MODBUS_TIMEOUT", "5s")
+	os.Setenv("MODBUS_REQUEST_DELAY", "100ms")
 	os.Setenv("MODBUS_SHUTDOWN_TIMEOUT", "60s")
 	os.Setenv("LOG_LEVEL", "DEBUG")
 
@@ -83,6 +87,7 @@ func TestLoad_CustomValues(t *testing.T) {
 		os.Unsetenv("MODBUS_CACHE_SERVE_STALE")
 		os.Unsetenv("MODBUS_READONLY")
 		os.Unsetenv("MODBUS_TIMEOUT")
+		os.Unsetenv("MODBUS_REQUEST_DELAY")
 		os.Unsetenv("MODBUS_SHUTDOWN_TIMEOUT")
 		os.Unsetenv("LOG_LEVEL")
 	}()
@@ -110,6 +115,9 @@ func TestLoad_CustomValues(t *testing.T) {
 	if cfg.Timeout != 5*time.Second {
 		t.Errorf("expected 5s timeout, got %v", cfg.Timeout)
 	}
+	if cfg.RequestDelay != 100*time.Millisecond {
+		t.Errorf("expected 100ms request delay, got %v", cfg.RequestDelay)
+	}
 	if cfg.ShutdownTimeout != 60*time.Second {
 		t.Errorf("expected 60s shutdown timeout, got %v", cfg.ShutdownTimeout)
 	}
@@ -166,7 +174,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_SHUTDOWN_TIMEOUT"}
+	tests := []string{"MODBUS_CACHE_TTL", "MODBUS_TIMEOUT", "MODBUS_REQUEST_DELAY", "MODBUS_SHUTDOWN_TIMEOUT"}
 	for _, envVar := range tests {
 		os.Setenv(envVar, "invalid")
 		_, err := Load()

internal/modbus/client.go

@@ -13,21 +13,23 @@ import (
 
 // Client wraps a Modbus TCP client with auto-reconnect capability.
 type Client struct {
-	address string
-	timeout time.Duration
-	logger  *slog.Logger
+	address      string
+	timeout      time.Duration
+	requestDelay time.Duration
+	logger       *slog.Logger
 
 	mu     sync.Mutex
 	client modbus.Client
 	conn   *modbus.TCPClientHandler
 }
 
 // NewClient creates a new Modbus TCP client.
-func NewClient(address string, timeout time.Duration, logger *slog.Logger) *Client {
+func NewClient(address string, timeout, requestDelay time.Duration, logger *slog.Logger) *Client {
 	return &Client{
-		address: address,
-		timeout: timeout,
-		logger:  logger,
+		address:      address,
+		timeout:      timeout,
+		requestDelay: requestDelay,
+		logger:       logger,
 	}
 }
 
@@ -102,6 +104,16 @@ func (c *Client) Execute(ctx context.Context, req *Request) ([]byte, error) {
 		}
 	}
 
+	// Apply request delay if configured (only after successful requests)
+	if c.requestDelay > 0 {
+		c.logger.Debug("applying request delay", "duration", c.requestDelay)
+		select {
+		case <-time.After(c.requestDelay):
+		case <-ctx.Done():
+			// Context cancelled during delay - still return the successful result
+		}
+	}
+
 	return resp, 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, logger),
+		client: modbus.NewClient(cfg.Upstream, cfg.Timeout, cfg.RequestDelay, logger),
 		cache:  cache.New(cfg.CacheTTL),
 	}