Introduce attempt and total timouts

Author: danischm

README.md

@@ -88,7 +88,8 @@ client, err := netconf.NewClient(
     netconf.Password("secret"),
     netconf.Port(830),
     netconf.MaxRetries(5),
-    netconf.OperationTimeout(120*time.Second),
+    netconf.AttemptTimeout(60*time.Second),
+    netconf.TotalTimeout(5*time.Minute),
 )
 
 // Connection established automatically on first operation

client.go

@@ -54,8 +54,9 @@ const (
 	DefaultBackoffMaxDelay    = 60 * time.Second
 	DefaultBackoffDelayFactor = 2
 	DefaultLockReleaseTimeout = 120 * time.Second
-	DefaultConnectTimeout     = 30 * time.Second
-	DefaultOperationTimeout   = 60 * time.Second
+	DefaultConnectTimeout     = 10 * time.Second
+	DefaultAttemptTimeout     = 30 * time.Second
+	DefaultTotalTimeout       = 2 * time.Minute
 	DefaultPrettyPrintLogs    = true
 )
 
@@ -150,7 +151,8 @@ type Client struct {
 	BackoffDelayFactor float64
 	LockReleaseTimeout time.Duration
 	ConnectTimeout     time.Duration
-	OperationTimeout   time.Duration
+	AttemptTimeout     time.Duration // Timeout for a single operation attempt (scrapligo timeout)
+	TotalTimeout       time.Duration // Total timeout across all retry attempts
 
 	// Capability tracking
 	Capabilities []string
@@ -219,7 +221,7 @@ func (c *Client) buildScrapligoOptions() []util.Option {
 		options.WithAuthPassword(c.password),
 		options.WithPort(c.Port),
 		options.WithTimeoutSocket(c.ConnectTimeout),
-		options.WithTimeoutOps(c.OperationTimeout),
+		options.WithTimeoutOps(c.AttemptTimeout),
 		options.WithTransportType(transport.StandardTransport),
 	}
 
@@ -248,7 +250,8 @@ func NewClient(host string, opts ...func(*Client)) (*Client, error) {
 		BackoffDelayFactor: DefaultBackoffDelayFactor,
 		LockReleaseTimeout: DefaultLockReleaseTimeout,
 		ConnectTimeout:     DefaultConnectTimeout,
-		OperationTimeout:   DefaultOperationTimeout,
+		AttemptTimeout:     DefaultAttemptTimeout,
+		TotalTimeout:       DefaultTotalTimeout,
 		logger:             &NoOpLogger{},
 		prettyPrintLogs:    DefaultPrettyPrintLogs,
 		redactionPatterns:  defaultRedactionPatterns,
@@ -1348,7 +1351,7 @@ func (c *Client) sendRPC(ctx context.Context, req *Req) (Res, error) {
 	// Apply timeout with proper priority:
 	// 1. Request-specific timeout (highest priority)
 	// 2. Context deadline (if already set)
-	// 3. Default operation timeout (fallback)
+	// 3. Default total timeout (fallback - spans all retry attempts)
 	if req.Timeout > 0 {
 		// Request-specific timeout takes precedence
 		var cancel context.CancelFunc
@@ -1357,7 +1360,7 @@ func (c *Client) sendRPC(ctx context.Context, req *Req) (Res, error) {
 	} else if _, hasDeadline := ctx.Deadline(); !hasDeadline {
 		// Only apply default if no deadline already set
 		var cancel context.CancelFunc
-		ctx, cancel = context.WithTimeout(ctx, c.OperationTimeout)
+		ctx, cancel = context.WithTimeout(ctx, c.TotalTimeout)
 		defer cancel()
 	}
 

client_test.go

@@ -38,7 +38,8 @@ func TestClientDefaultConfiguration(t *testing.T) {
 			BackoffDelayFactor: 1.2,
 			LockReleaseTimeout: 120 * time.Second,
 			ConnectTimeout:     30 * time.Second,
-			OperationTimeout:   60 * time.Second,
+			AttemptTimeout:     30 * time.Second,
+			TotalTimeout:       2 * time.Minute,
 		}
 
 		// Apply options
@@ -148,7 +149,8 @@ func TestClientOpen(t *testing.T) {
 			username:          "test",
 			password:          "test",
 			ConnectTimeout:    1 * time.Second,
-			OperationTimeout:  1 * time.Second,
+			AttemptTimeout:    1 * time.Second,
+			TotalTimeout:      5 * time.Second,
 			logger:            &NoOpLogger{},
 			prettyPrintLogs:   false,
 			redactionPatterns: defaultRedactionPatterns,
@@ -176,7 +178,8 @@ func TestClientOpen(t *testing.T) {
 			BackoffDelayFactor: 3.0,
 			LockReleaseTimeout: 240 * time.Second,
 			ConnectTimeout:     45 * time.Second,
-			OperationTimeout:   90 * time.Second,
+			AttemptTimeout:     60 * time.Second,
+			TotalTimeout:       5 * time.Minute,
 			logger:             &NoOpLogger{},
 			prettyPrintLogs:    true,
 			redactionPatterns:  defaultRedactionPatterns,
@@ -231,7 +234,8 @@ func TestClientOpen(t *testing.T) {
 			password:          "test",
 			driver:            nil, // Simulate closed state
 			ConnectTimeout:    1 * time.Second,
-			OperationTimeout:  1 * time.Second,
+			AttemptTimeout:    1 * time.Second,
+			TotalTimeout:      5 * time.Second,
 			logger:            &NoOpLogger{},
 			prettyPrintLogs:   false,
 			redactionPatterns: defaultRedactionPatterns,

docs/concurrency.md

@@ -368,7 +368,7 @@ func NewNetconfManager(host, username, password string) (*NetconfManager, error)
     readClient, err := netconf.NewClient(host,
         netconf.Username(username),
         netconf.Password(password),
-        netconf.OperationTimeout(30*time.Second))
+        netconf.TotalTimeout(1*time.Minute))
     if err != nil {
         return nil, err
     }
@@ -377,7 +377,8 @@ func NewNetconfManager(host, username, password string) (*NetconfManager, error)
     writeClient, err := netconf.NewClient(host,
         netconf.Username(username),
         netconf.Password(password),
-        netconf.OperationTimeout(5*time.Minute),
+        netconf.AttemptTimeout(60*time.Second),
+        netconf.TotalTimeout(10*time.Minute),
         netconf.MaxRetries(5))
     if err != nil {
         readClient.Close()

docs/error-handling.md

@@ -571,7 +571,7 @@ Configure timeouts based on operation:
 ```go
 // Quick operations
 client, _ := netconf.NewClient("192.168.1.1",
-    netconf.OperationTimeout(30*time.Second))
+    netconf.TotalTimeout(1*time.Minute))
 
 // Long-running operations
 res, err := client.Commit(ctx, netconf.Timeout(5*time.Minute))
@@ -648,9 +648,10 @@ client, err := netconf.NewClient("192.168.1.1",
 
 **Solutions:**
 ```go
-// Increase global timeout
+// Increase timeouts
 client, _ := netconf.NewClient("192.168.1.1",
-    netconf.OperationTimeout(120*time.Second))
+    netconf.AttemptTimeout(60*time.Second),   // Per-attempt timeout
+    netconf.TotalTimeout(5*time.Minute))      // Total timeout across retries
 
 // Increase per-operation timeout
 res, err := client.Get(ctx, filter, netconf.Timeout(5*time.Minute))
@@ -775,7 +776,8 @@ func main() {
         netconf.Username("automation"),
         netconf.SSHKey("/path/to/key"),
         netconf.MaxRetries(5),
-        netconf.OperationTimeout(2*time.Minute),
+        netconf.AttemptTimeout(60*time.Second),
+        netconf.TotalTimeout(5*time.Minute),
         netconf.LockReleaseTimeout(3*time.Minute),
         netconf.BackoffMinDelay(2*time.Second),
         netconf.BackoffMaxDelay(60*time.Second),

docs/operations.md

@@ -735,8 +735,9 @@ res, err := client.Get(ctx, filter, netconf.Timeout(30*time.Second))
 
 **Notes:**
 - Request-specific timeout takes precedence over context deadline
-- If no timeout is specified, uses the client's `OperationTimeout` (default: 60s)
+- If no timeout is specified, uses the client's `TotalTimeout` (default: 2min)
 - Useful for operations that may take longer than the default timeout
+- This timeout spans all retry attempts
 
 ### DefaultOperation
 
@@ -951,7 +952,7 @@ if err != nil {
 
 ### Best Practices
 
-- **Configure appropriate timeouts**: Set `OperationTimeout` based on expected operation duration
+- **Configure appropriate timeouts**: Set `AttemptTimeout` for per-operation timeout and `TotalTimeout` for total retry duration
 - **Use context deadlines**: Combine with context timeouts for request-level control
 - **Monitor retry counts**: High retry counts may indicate systemic issues
 - **Handle non-transient errors**: Not all errors are retryable - implement proper error handling

docs/quickstart.md

@@ -382,8 +382,9 @@ func main() {
         "192.168.1.1",
         netconf.Username("admin"),
         netconf.Password("secret"),
-        netconf.ConnectTimeout(30*time.Second),
-        netconf.OperationTimeout(60*time.Second),
+        netconf.ConnectTimeout(15*time.Second),
+        netconf.AttemptTimeout(45*time.Second),
+        netconf.TotalTimeout(3*time.Minute),
         netconf.MaxRetries(5),
     )
     if err != nil {
@@ -439,8 +440,9 @@ func main() {
         "192.168.1.1",
         netconf.Username("admin"),
         netconf.Password("secret"),
-        netconf.ConnectTimeout(30*time.Second),
-        netconf.OperationTimeout(2*time.Minute),
+        netconf.ConnectTimeout(15*time.Second),
+        netconf.AttemptTimeout(60*time.Second),
+        netconf.TotalTimeout(5*time.Minute),
         netconf.MaxRetries(5),
         netconf.LockReleaseTimeout(2*time.Minute),
     )

operations_test.go

@@ -91,13 +91,13 @@ func TestContextTimeout(t *testing.T) {
 	// that the code path exists and is syntactically correct
 
 	client := &Client{
-		OperationTimeout: 60,
+		TotalTimeout: 60,
 	}
 
 	ctx := context.Background()
 	// Verify that client has timeout configured
-	if client.OperationTimeout == 0 {
-		t.Error("expected OperationTimeout to be set")
+	if client.TotalTimeout == 0 {
+		t.Error("expected TotalTimeout to be set")
 	}
 
 	// Context should respect the timeout

options.go

@@ -46,10 +46,19 @@ func ConnectTimeout(duration time.Duration) func(*Client) {
 	}
 }
 
-// OperationTimeout sets the operation timeout (default: 60s)
-func OperationTimeout(duration time.Duration) func(*Client) {
+// AttemptTimeout sets the timeout for a single operation attempt (default: 30s)
+// This timeout is enforced by scrapligo for each individual RPC call.
+func AttemptTimeout(duration time.Duration) func(*Client) {
 	return func(c *Client) {
-		c.OperationTimeout = duration
+		c.AttemptTimeout = duration
+	}
+}
+
+// TotalTimeout sets the total timeout across all retry attempts (default: 2min)
+// This timeout spans all retry attempts including backoff delays.
+func TotalTimeout(duration time.Duration) func(*Client) {
+	return func(c *Client) {
+		c.TotalTimeout = duration
 	}
 }
 

options_test.go

@@ -61,11 +61,20 @@ func TestClientOptions(t *testing.T) {
 			},
 		},
 		{
-			name:   "OperationTimeout option",
-			option: OperationTimeout(120 * time.Second),
+			name:   "AttemptTimeout option",
+			option: AttemptTimeout(45 * time.Second),
 			validate: func(t *testing.T, c *Client) {
-				if c.OperationTimeout != 120*time.Second {
-					t.Errorf("expected OperationTimeout 120s, got %v", c.OperationTimeout)
+				if c.AttemptTimeout != 45*time.Second {
+					t.Errorf("expected AttemptTimeout 45s, got %v", c.AttemptTimeout)
+				}
+			},
+		},
+		{
+			name:   "TotalTimeout option",
+			option: TotalTimeout(3 * time.Minute),
+			validate: func(t *testing.T, c *Client) {
+				if c.TotalTimeout != 3*time.Minute {
+					t.Errorf("expected TotalTimeout 3min, got %v", c.TotalTimeout)
 				}
 			},
 		},
@@ -219,7 +228,8 @@ func TestMultipleOptions(t *testing.T) {
 		Port(8830),
 		MaxRetries(3),
 		ConnectTimeout(20 * time.Second),
-		OperationTimeout(90 * time.Second),
+		AttemptTimeout(45 * time.Second),
+		TotalTimeout(3 * time.Minute),
 		BackoffMinDelay(2 * time.Second),
 		BackoffMaxDelay(90 * time.Second),
 		BackoffDelayFactor(1.5),
@@ -246,8 +256,11 @@ func TestMultipleOptions(t *testing.T) {
 	if client.ConnectTimeout != 20*time.Second {
 		t.Errorf("expected ConnectTimeout 20s, got %v", client.ConnectTimeout)
 	}
-	if client.OperationTimeout != 90*time.Second {
-		t.Errorf("expected OperationTimeout 90s, got %v", client.OperationTimeout)
+	if client.AttemptTimeout != 45*time.Second {
+		t.Errorf("expected AttemptTimeout 45s, got %v", client.AttemptTimeout)
+	}
+	if client.TotalTimeout != 3*time.Minute {
+		t.Errorf("expected TotalTimeout 3min, got %v", client.TotalTimeout)
 	}
 	if client.BackoffMinDelay != 2*time.Second {
 		t.Errorf("expected BackoffMinDelay 2s, got %v", client.BackoffMinDelay)