feat(wait): add human-readable String() methods to all wait strategies (docker#119)

mdelapenya · claude · web-flow · commit c1a5f755e7d5 · 2025-11-03T11:41:54.000+01:00
* feat(wait): add human-readable String() methods to all wait strategies Add String() method to all wait strategy types to provide human-readable descriptions that are displayed in container lifecycle logs. This improves the user experience by showing clear wait conditions instead of raw struct output. Changes: - Add String() method to HTTPStrategy, HealthStrategy, LogStrategy, HostPortStrategy, FileStrategy, ExecStrategy, ExitStrategy, waitForSQL, MultiStrategy, NopStrategy, and TLSStrategy - Update lifecycle logging to use strategy String() output - Each strategy provides contextual information (ports, paths, conditions) Example output changes: Before: Waiting for: &{timeout:<nil> deadline:0x140001c7190 Strategies:[0x1400032e1d0]} After: Waiting for container to be ready strategy="HTTP GET request on port 8080 path /health" 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: use switch * chore: wrap URL path * fix(wait): address linter feedback for String() methods - Use switch statement instead of if-else chain in HostPortStrategy - Quote path in HTTPStrategy output for clarity - Use Port.Port() method instead of string cast for nat.Port 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(wait): prevent sensitive data exposure in ExecStrategy String() Only show command name and argument count instead of full command with arguments, which may contain passwords, tokens, or other credentials. Example: "exec command \"mysql\" with 4 argument(s)" instead of ["mysql", "-u", "root", "-pSecretPass", "mydb"] 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(wait): always show MultiStrategy wrapper in String() output Always include "all of:" prefix even when there's only one strategy after filtering out nils, to make it clear that a MultiStrategy wrapper is being used. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(wait): use proper singular/plural grammar in ExecStrategy String() Use "argument" (singular) when argCount is 1, and "arguments" (plural) otherwise for grammatically correct output. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/container/lifecycle.create.go b/container/lifecycle.create.go
@@ -96,8 +96,13 @@ var defaultReadinessHook = func() LifecycleHooks {
 
 				// if a Wait Strategy has been specified, wait before returning
 				if waiter.WaitingFor() != nil {
-					c.Logger().Info("Waiting for container to be ready", "containerID", c.ShortID(), "image", c.Image())
-					if err := waiter.WaitingFor().WaitUntilReady(ctx, waiter); err != nil {
+					strategy := waiter.WaitingFor()
+					strategyDesc := "unknown strategy"
+					if s, ok := strategy.(fmt.Stringer); ok {
+						strategyDesc = s.String()
+					}
+					c.Logger().Info("Waiting for container to be ready", "containerID", c.ShortID(), "image", c.Image(), "strategy", strategyDesc)
+					if err := strategy.WaitUntilReady(ctx, waiter); err != nil {
 						return fmt.Errorf("wait until ready: %w", err)
 					}
 				}
diff --git a/container/wait/all.go b/container/wait/all.go
@@ -3,7 +3,9 @@ package wait
 import (
 	"context"
 	"errors"
+	"fmt"
 	"reflect"
+	"strings"
 	"time"
 )
 
@@ -44,6 +46,29 @@ func (ms *MultiStrategy) Timeout() *time.Duration {
 	return ms.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ms *MultiStrategy) String() string {
+	if len(ms.Strategies) == 0 {
+		return "all of: (none)"
+	}
+
+	var strategies []string
+	for _, strategy := range ms.Strategies {
+		if strategy == nil || reflect.ValueOf(strategy).IsNil() {
+			continue
+		}
+		if s, ok := strategy.(fmt.Stringer); ok {
+			strategies = append(strategies, s.String())
+		} else {
+			strategies = append(strategies, fmt.Sprintf("%T", strategy))
+		}
+	}
+
+	// Always include "all of:" prefix to make it clear this is a MultiStrategy
+	// even when there's only one strategy after filtering out nils
+	return "all of: [" + strings.Join(strategies, ", ") + "]"
+}
+
 func (ms *MultiStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	var cancel context.CancelFunc
 	if ms.deadline != nil {
diff --git a/container/wait/exec.go b/container/wait/exec.go
@@ -2,6 +2,7 @@ package wait
 
 import (
 	"context"
+	"fmt"
 	"io"
 	"time"
 
@@ -76,6 +77,22 @@ func (ws *ExecStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *ExecStrategy) String() string {
+	if len(ws.cmd) == 0 {
+		return "exec command"
+	}
+	// Only show the command name and argument count to avoid exposing sensitive data
+	argCount := len(ws.cmd) - 1
+	if argCount == 0 {
+		return fmt.Sprintf("exec command %q", ws.cmd[0])
+	}
+	if argCount == 1 {
+		return fmt.Sprintf("exec command %q with 1 argument", ws.cmd[0])
+	}
+	return fmt.Sprintf("exec command %q with %d arguments", ws.cmd[0], argCount)
+}
+
 func (ws *ExecStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	timeout := defaultTimeout()
 	if ws.timeout != nil {
diff --git a/container/wait/exit.go b/container/wait/exit.go
@@ -59,6 +59,11 @@ func (ws *ExitStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *ExitStrategy) String() string {
+	return "container to exit"
+}
+
 // WaitUntilReady implements Strategy.WaitUntilReady
 func (ws *ExitStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	if ws.timeout != nil {
diff --git a/container/wait/file.go b/container/wait/file.go
@@ -61,6 +61,14 @@ func (ws *FileStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *FileStrategy) String() string {
+	if ws.matcher != nil {
+		return fmt.Sprintf("file %q to exist and match condition", ws.file)
+	}
+	return fmt.Sprintf("file %q to exist", ws.file)
+}
+
 // WaitUntilReady waits until the file exists in the container and copies it to the target.
 func (ws *FileStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	timeout := defaultTimeout()
diff --git a/container/wait/health.go b/container/wait/health.go
@@ -60,6 +60,11 @@ func (ws *HealthStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *HealthStrategy) String() string {
+	return "container to become healthy"
+}
+
 // WaitUntilReady implements Strategy.WaitUntilReady
 func (ws *HealthStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	timeout := defaultTimeout()
diff --git a/container/wait/host_port.go b/container/wait/host_port.go
@@ -113,6 +113,28 @@ func (hp *HostPortStrategy) Timeout() *time.Duration {
 	return hp.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (hp *HostPortStrategy) String() string {
+	port := "first exposed port"
+	if hp.Port != "" {
+		port = fmt.Sprintf("port %s", hp.Port)
+	}
+
+	var checks string
+	switch {
+	case hp.skipInternalCheck && hp.skipExternalCheck:
+		checks = " to be mapped"
+	case hp.skipInternalCheck:
+		checks = " to be accessible externally"
+	case hp.skipExternalCheck:
+		checks = " to be listening internally"
+	default:
+		checks = " to be listening"
+	}
+
+	return fmt.Sprintf("%s%s", port, checks)
+}
+
 // detectInternalPort returns the lowest internal port that is currently bound.
 // If no internal port is found, it returns the zero nat.Port value which
 // can be checked against an empty string.
diff --git a/container/wait/http.go b/container/wait/http.go
@@ -163,6 +163,21 @@ func (ws *HTTPStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *HTTPStrategy) String() string {
+	proto := "HTTP"
+	if ws.UseTLS {
+		proto = "HTTPS"
+	}
+
+	port := "default"
+	if ws.Port != "" {
+		port = ws.Port.Port()
+	}
+
+	return fmt.Sprintf("%s %s request on port %s path %q", proto, ws.Method, port, ws.Path)
+}
+
 // WaitUntilReady implements Strategy.WaitUntilReady
 func (ws *HTTPStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	timeout := defaultTimeout()
diff --git a/container/wait/log.go b/container/wait/log.go
@@ -123,6 +123,21 @@ func (ws *LogStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *LogStrategy) String() string {
+	logType := "log message"
+	if ws.IsRegexp {
+		logType = "log pattern"
+	}
+
+	occurrence := ""
+	if ws.Occurrence > 1 {
+		occurrence = fmt.Sprintf(" (occurrence: %d)", ws.Occurrence)
+	}
+
+	return fmt.Sprintf("%s %q%s", logType, ws.Log, occurrence)
+}
+
 // WaitUntilReady implements Strategy.WaitUntilReady
 func (ws *LogStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error {
 	timeout := defaultTimeout()
diff --git a/container/wait/nop.go b/container/wait/nop.go
@@ -34,6 +34,11 @@ func (ws *NopStrategy) Timeout() *time.Duration {
 	return ws.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *NopStrategy) String() string {
+	return "custom wait condition"
+}
+
 func (ws *NopStrategy) WithTimeout(timeout time.Duration) *NopStrategy {
 	ws.timeout = &timeout
 	return ws
diff --git a/container/wait/sql.go b/container/wait/sql.go
@@ -61,6 +61,21 @@ func (w *waitForSQL) Timeout() *time.Duration {
 	return w.timeout
 }
 
+// String returns a human-readable description of the wait strategy.
+func (w *waitForSQL) String() string {
+	port := "default"
+	if w.Port != "" {
+		port = w.Port.Port()
+	}
+
+	query := ""
+	if w.query != defaultForSQLQuery {
+		query = fmt.Sprintf(" with query %q", w.query)
+	}
+
+	return fmt.Sprintf("SQL database on port %s using driver %q%s", port, w.Driver, query)
+}
+
 // WaitUntilReady repeatedly tries to run "SELECT 1" or user defined query on the given port using sql and driver.
 //
 // If it doesn't succeed until the timeout value which defaults to 60 seconds, it will return an error.
diff --git a/container/wait/tls.go b/container/wait/tls.go
@@ -6,6 +6,7 @@ import (
 	"crypto/x509"
 	"fmt"
 	"io"
+	"strings"
 	"time"
 )
 
@@ -99,6 +100,25 @@ func (ws *TLSStrategy) TLSConfig() *tls.Config {
 	return ws.tlsConfig
 }
 
+// String returns a human-readable description of the wait strategy.
+func (ws *TLSStrategy) String() string {
+	var parts []string
+
+	if len(ws.rootFiles) > 0 {
+		parts = append(parts, fmt.Sprintf("root CAs %v", ws.rootFiles))
+	}
+
+	if ws.certFiles != nil {
+		parts = append(parts, fmt.Sprintf("cert %q and key %q", ws.certFiles.certPEMFile, ws.certFiles.keyPEMFile))
+	}
+
+	if len(parts) == 0 {
+		return "TLS certificates"
+	}
+
+	return strings.Join(parts, " and ")
+}
+
 // WaitUntilReady implements the [Strategy] interface.
 // It waits for the CA, client cert and key files to be available in the container and
 // uses them to setup the TLS config.
