Improve custom recipe experience and testing (#379)

- Add recipe flags to `generate` cmd to support conditional recipe
generation
- Add `--retries` flag to `test` command and improve timeout flag usage
- Add `setup` field to custom YAML recipes to setup the environment
first before running the playground - arrives with `--skip-setup` option
- Resolve relative `host_path`s to absolute paths to run local binaries
from custom recipes
- Enable port overriding from the custom recipe

These are improvements made and discovered during the experimentation
with op-rbuilder repo, for running locally and in CI.

Author: canercidam

main.go

@@ -54,12 +54,14 @@ var (
 	contenderArgs     []string
 	contenderTarget   string
 	detached          bool
+	skipSetup         bool
 	prefundedAccounts []string
 	followFlag        bool
 	generateForce     bool
 	testRPCURL        string
 	testELRPCURL      string
 	testTimeout       time.Duration
+	testRetries       int
 	testInsecure      bool
 	portListFlag      bool
 )
@@ -515,6 +517,7 @@ var testCmd = &cobra.Command{
 		cfg.RPCURL = testRPCURL
 		cfg.ELRPCURL = testELRPCURL
 		cfg.Timeout = testTimeout
+		cfg.Retries = testRetries
 		cfg.Insecure = testInsecure
 
 		// Suggest --insecure flag if any RPC URL uses https without insecure mode
@@ -557,6 +560,7 @@ func main() {
 		cmd.Flags().StringArrayVar(&contenderArgs, "contender.arg", []string{}, "add/override contender CLI flags")
 		cmd.Flags().StringVar(&contenderTarget, "contender.target", "", "override the node that contender spams")
 		cmd.Flags().BoolVar(&detached, "detached", false, "Detached mode: Run the recipes in the background")
+		cmd.Flags().BoolVar(&skipSetup, "skip-setup", false, "Skip the setup commands defined in the YAML recipe")
 		cmd.Flags().StringArrayVar(&prefundedAccounts, "prefunded-accounts", []string{}, "Fund this account in addition to static prefunded accounts")
 	}
 
@@ -605,6 +609,7 @@ func main() {
 			},
 		}
 		recipeCmd.Flags().AddFlagSet(recipe.Flags())
+		generateCmd.Flags().AddFlagSet(recipe.Flags())
 		addCommonRecipeFlags(recipeCmd)
 		startCmd.AddCommand(recipeCmd)
 	}
@@ -633,7 +638,8 @@ func main() {
 	rootCmd.AddCommand(recipesCmd)
 	testCmd.Flags().StringVar(&testRPCURL, "rpc", "http://localhost:8545", "Target RPC URL for sending transactions")
 	testCmd.Flags().StringVar(&testELRPCURL, "el-rpc", "", "EL RPC URL for chain queries (default: same as --rpc)")
-	testCmd.Flags().DurationVar(&testTimeout, "timeout", 2*time.Minute, "Timeout for waiting for transaction receipt")
+	testCmd.Flags().DurationVar(&testTimeout, "timeout", time.Minute, "Timeout for waiting for transaction receipt (0 means no timeout - default: 1m)")
+	testCmd.Flags().IntVar(&testRetries, "retries", 0, "Max number of failed receipt requests before giving up (0 means retry forever - default: 0)")
 	testCmd.Flags().BoolVar(&testInsecure, "insecure", false, "Skip TLS certificate verification (for self-signed certs)")
 	rootCmd.AddCommand(testCmd)
 
@@ -700,6 +706,9 @@ func runIt(recipe playground.Recipe) error {
 	components := recipe.Apply(exCtx)
 	svcManager := playground.NewManifest(sessionID, components)
 	svcManager.Bootnode = exCtx.Bootnode
+	if yamlRecipe, ok := recipe.(*playground.YAMLRecipe); ok && !skipSetup {
+		svcManager.Setup, svcManager.SetupDir = yamlRecipe.SetupCommands()
+	}
 
 	// generate the dot graph
 	slog.Debug("Generating dot graph...")

playground/local_runner.go

@@ -1187,6 +1187,11 @@ func (d *LocalRunner) Run(ctx context.Context) error {
 		return fmt.Errorf("failed to write docker-compose.yaml: %w", err)
 	}
 
+	// Run setup commands before launching any services
+	if err := d.runSetupCommands(ctx); err != nil {
+		return err
+	}
+
 	// Pull all required images in parallel
 	if err := d.pullNotAvailableImages(ctx); err != nil {
 		return err

playground/local_runner_lifecycle.go

@@ -160,3 +160,30 @@ func (d *LocalRunner) runAllLifecycleStopCommands() {
 		d.runLifecycleStopCommands(info.svc, info.logFile, info.logPath)
 	}
 }
+
+// runSetupCommands runs the setup commands from the manifest before any services
+// are launched. Commands run sequentially via "sh -c" in the recipe directory;
+// each must exit 0 or an error is returned.
+func (d *LocalRunner) runSetupCommands(ctx context.Context) error {
+	if len(d.manifest.Setup) == 0 {
+		return nil
+	}
+
+	dir := d.manifest.SetupDir
+	if dir == "" {
+		dir = d.out.sessionDir
+	}
+
+	for i, command := range d.manifest.Setup {
+		slog.Info("Running setup command", "index", i, "command", command)
+		cmd := exec.CommandContext(ctx, "sh", "-c", command)
+		cmd.Dir = dir
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		if err := cmd.Run(); err != nil {
+			return fmt.Errorf("setup command %d failed: %q: %w", i, command, err)
+		}
+	}
+
+	return nil
+}

playground/manifest.go

@@ -47,6 +47,13 @@ type Manifest struct {
 
 	Bootnode *BootnodeRef `json:"bootnode,omitempty"`
 
+	// Setup contains shell commands to run before any services are launched.
+	// Commands run sequentially in SetupDir; each must exit 0.
+	Setup []string `json:"setup,omitempty"`
+
+	// SetupDir is the working directory for setup commands.
+	SetupDir string `json:"setup_dir,omitempty"`
+
 	// overrides is a map of service name to the path of the executable to run
 	// on the host machine instead of a container.
 	overrides map[string]string
@@ -515,12 +522,13 @@ func (s *Service) WithPort(name string, portNumber int, protocolVar ...string) *
 		protocol = protocolVar[0]
 	}
 
-	// add the port if not already present with the same name.
-	// if preset with the same name, they must have same port number
+	// add or replace the ports
 	for _, p := range s.Ports {
 		if p.Name == name {
 			if p.Port != portNumber {
-				panic(fmt.Sprintf("port %s already defined with different port number (existing: %d, new: %d) on service %s", name, p.Port, portNumber, s.Name))
+				p.Port = portNumber
+				p.Protocol = protocol
+				return s
 			}
 			if p.Protocol != protocol {
 				// If they have different protocols they are different ports

playground/recipe_yaml.go

@@ -22,6 +22,10 @@ type YAMLRecipeConfig struct {
 	// Description is an optional description of the recipe
 	Description string `yaml:"description,omitempty"`
 
+	// Setup is a list of shell commands to run before any services are launched.
+	// Commands run sequentially in the recipe's directory; each must exit 0.
+	Setup []string `yaml:"setup,omitempty"`
+
 	// Recipe contains the component/service hierarchy to apply as overrides or additions
 	Recipe map[string]*YAMLComponentConfig `yaml:"recipe"`
 }
@@ -228,6 +232,11 @@ func (y *YAMLRecipe) Output(manifest *Manifest) map[string]interface{} {
 	return y.baseRecipe.Output(manifest)
 }
 
+// SetupCommands returns the setup commands and the directory to run them in.
+func (y *YAMLRecipe) SetupCommands() ([]string, string) {
+	return y.config.Setup, y.recipeDir
+}
+
 // applyModifications applies the YAML recipe modifications to the component tree
 func (y *YAMLRecipe) applyModifications(ctx *ExContext, component *Component) {
 	if y.config.Recipe == nil {
@@ -464,7 +473,11 @@ func applyServiceOverrides(svc *Service, config *YAMLServiceConfig, root *Compon
 		applyDependsOn(svc, config.DependsOn, root)
 	}
 	if config.HostPath != "" {
-		svc.HostPath = config.HostPath
+		if filepath.IsAbs(config.HostPath) {
+			svc.HostPath = config.HostPath
+		} else {
+			svc.HostPath, _ = filepath.Abs(filepath.Join(recipeDir, config.HostPath))
+		}
 		svc.UseHostExecution()
 	}
 	if config.Release != nil {
@@ -641,7 +654,11 @@ func createServiceFromConfig(name string, config *YAMLServiceConfig, root *Compo
 		applyDependsOn(svc, config.DependsOn, root)
 	}
 	if config.HostPath != "" {
-		svc.HostPath = config.HostPath
+		if filepath.IsAbs(config.HostPath) {
+			svc.HostPath = config.HostPath
+		} else {
+			svc.HostPath, _ = filepath.Abs(filepath.Join(recipeDir, config.HostPath))
+		}
 		svc.UseHostExecution()
 	}
 	if config.Release != nil {

playground/test_tx.go

@@ -67,7 +67,8 @@ type TestTxConfig struct {
 	Value      *big.Int
 	GasLimit   uint64
 	GasPrice   *big.Int
-	Timeout    time.Duration // Timeout for waiting for receipt. If 0, defaults to 2 minutes
+	Timeout    time.Duration // Timeout for waiting for receipt. If 0, no timeout.
+	Retries    int           // Max failed receipt requests before giving up. If 0, retry forever.
 	Insecure   bool          // Skip TLS certificate verification
 }
 
@@ -209,23 +210,23 @@ func SendTestTransaction(ctx context.Context, cfg *TestTxConfig) error {
 	txHash := signedTx.Hash()
 	fmt.Printf("TX Hash: %s\n", txHash.Hex())
 
-	// Wait for receipt with timeout
-	timeout := cfg.Timeout
-	if timeout == 0 {
-		timeout = 2 * time.Minute
+	// Apply timeout if configured
+	if cfg.Timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, cfg.Timeout)
+		defer cancel()
 	}
-	ctx, cancel := context.WithTimeout(ctx, timeout)
-	defer cancel()
 
 	fmt.Println("Waiting for receipt...")
 	ticker := time.NewTicker(1 * time.Second)
 	defer ticker.Stop()
 
+	failedAttempts := 0
 	for {
 		select {
 		case <-ctx.Done():
 			if ctx.Err() == context.DeadlineExceeded {
-				return fmt.Errorf("timeout waiting for transaction receipt after %s", timeout)
+				return fmt.Errorf("timeout waiting for transaction receipt after %s", cfg.Timeout)
 			}
 			return ctx.Err()
 		case <-ticker.C:
@@ -243,6 +244,10 @@ func SendTestTransaction(ctx context.Context, cfg *TestTxConfig) error {
 				}
 				return nil
 			}
+			failedAttempts++
+			if cfg.Retries > 0 && failedAttempts >= cfg.Retries {
+				return fmt.Errorf("failed to get transaction receipt after %d attempts", cfg.Retries)
+			}
 		}
 	}
 }