choose whether to pull images or not, add strict TOML validation with helpful hints (#1239)

* choose whether to pull images or not
add strict TOML validation with helpful hints

Author: skudasov

framework/COMPONENTS.md

@@ -41,6 +41,20 @@ Each component can define inputs and outputs, following these rules:
 - `if input.Out != nil && framework.UseCache()` should be added if you'd like to use caching
 
 ### Docker components good practices for [testcontainers-go](https://golang.testcontainers.org/):
+
+An example [simple component](components/blockchain/anvil.go)
+
+An example of [complex component](components/clnode/clnode.go)
+
+An example of [composite component](components/don/don.go)
+
+- Inputs should include at least `image`, `tag` and `pull_image` field
+```
+	Image                string `toml:"image" validate:"required"`
+	Tag                  string `toml:"tag" validate:"required"`
+	PullImage            bool   `toml:"pull_image" validate:"required"`
+```
+
 - `ContainerRequest` must contain labels, network and alias required for local observability stack and deployment isolation
 ```
 		Labels:   framework.DefaultTCLabels(),

framework/components/blockchain/anvil.go

@@ -23,11 +23,12 @@ func deployAnvil(in *Input) (*Output, error) {
 	containerName := framework.DefaultTCName("anvil")
 
 	req := testcontainers.ContainerRequest{
-		Image:        fmt.Sprintf("%s:%s", in.Image, in.Tag),
-		Labels:       framework.DefaultTCLabels(),
-		Name:         containerName,
-		ExposedPorts: []string{bindPort},
-		Networks:     []string{framework.DefaultNetworkName},
+		AlwaysPullImage: in.PullImage,
+		Image:           fmt.Sprintf("%s:%s", in.Image, in.Tag),
+		Labels:          framework.DefaultTCLabels(),
+		Name:            containerName,
+		ExposedPorts:    []string{bindPort},
+		Networks:        []string{framework.DefaultNetworkName},
 		NetworkAliases: map[string][]string{
 			framework.DefaultNetworkName: {containerName},
 		},

framework/components/blockchain/blockchain.go

@@ -10,6 +10,7 @@ type Input struct {
 	Type                     string   `toml:"type" validate:"required,oneof=anvil geth" envconfig:"net_type"`
 	Image                    string   `toml:"image" validate:"required"`
 	Tag                      string   `toml:"tag" validate:"required"`
+	PullImage                bool     `toml:"pull_image" validate:"required"`
 	Port                     string   `toml:"port" validate:"required"`
 	ChainID                  string   `toml:"chain_id" validate:"required"`
 	DockerCmdParamsOverrides []string `toml:"docker_cmd_params"`

framework/components/clnode/clnode.go

@@ -26,6 +26,7 @@ type Input struct {
 type NodeInput struct {
 	Image                string `toml:"image" validate:"required"`
 	Tag                  string `toml:"tag" validate:"required"`
+	PullImage            bool   `toml:"pull_image" validate:"required"`
 	Port                 string `toml:"port" validate:"required"`
 	TestConfigOverrides  string `toml:"test_config_overrides"`
 	UserConfigOverrides  string `toml:"user_config_overrides"`
@@ -107,10 +108,11 @@ func newNode(in *Input, pgOut *postgres.Output) (*NodeOut, error) {
 	containerName := framework.DefaultTCName("clnode")
 
 	req := tc.ContainerRequest{
-		Image:    fmt.Sprintf("%s:%s", in.Node.Image, in.Node.Tag),
-		Name:     containerName,
-		Labels:   framework.DefaultTCLabels(),
-		Networks: []string{framework.DefaultNetworkName},
+		AlwaysPullImage: in.Node.PullImage,
+		Image:           fmt.Sprintf("%s:%s", in.Node.Image, in.Node.Tag),
+		Name:            containerName,
+		Labels:          framework.DefaultTCLabels(),
+		Networks:        []string{framework.DefaultNetworkName},
 		NetworkAliases: map[string][]string{
 			framework.DefaultNetworkName: {containerName},
 		},

framework/components/don/clnode.go framework/components/don/don.goframework/components/don/clnode.go renamed to framework/components/don/don.go

@@ -11,11 +11,14 @@ import (
 )
 
 type Input struct {
-	User     string  `toml:"user" validate:"required"`
-	Password string  `toml:"password" validate:"required"`
-	Database string  `toml:"database" validate:"required"`
-	Port     string  `toml:"port" validate:"required"`
-	Out      *Output `toml:"out"`
+	Image     string  `toml:"image" validate:"required"`
+	Tag       string  `toml:"tag" validate:"required"`
+	PullImage bool    `toml:"pull_image" validate:"required"`
+	User      string  `toml:"user" validate:"required"`
+	Password  string  `toml:"password" validate:"required"`
+	Database  string  `toml:"database" validate:"required"`
+	Port      string  `toml:"port" validate:"required"`
+	Out       *Output `toml:"out"`
 }
 
 type Output struct {
@@ -31,11 +34,12 @@ func NewPostgreSQL(in *Input) (*Output, error) {
 	containerName := framework.DefaultTCName("postgresql")
 
 	req := testcontainers.ContainerRequest{
-		Image:        "postgres:15.6",
-		Name:         containerName,
-		Labels:       framework.DefaultTCLabels(),
-		ExposedPorts: []string{bindPort},
-		Networks:     []string{framework.DefaultNetworkName},
+		AlwaysPullImage: in.PullImage,
+		Image:           fmt.Sprintf("%s:%s", in.Image, in.Tag),
+		Name:            containerName,
+		Labels:          framework.DefaultTCLabels(),
+		ExposedPorts:    []string{bindPort},
+		Networks:        []string{framework.DefaultNetworkName},
 		NetworkAliases: map[string][]string{
 			framework.DefaultNetworkName: {containerName},
 		},

framework/components/postgres/postgres.go

@@ -3,6 +3,7 @@ package framework
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"github.com/davecgh/go-spew/spew"
 	"github.com/go-playground/validator/v10"
@@ -63,17 +64,23 @@ func mergeInputs[T any]() (*T, error) {
 	}
 	for _, path := range paths {
 		L.Info().Str("Path", path).Msg("Loading configuration input")
-		file, err := os.ReadFile(filepath.Join(DefaultConfigDir, path))
+		data, err := os.ReadFile(filepath.Join(DefaultConfigDir, path))
 		if err != nil {
 			return nil, fmt.Errorf("error reading promtailConfig file %s: %w", path, err)
 		}
 		if L.GetLevel() == zerolog.DebugLevel {
-			fmt.Println(string(file))
+			fmt.Println(string(data))
 		}
 
-		err = toml.Unmarshal(file, &config)
-		if err != nil {
-			return nil, fmt.Errorf("error parsing config file %s: %w", path, err)
+		decoder := toml.NewDecoder(strings.NewReader(string(data)))
+		decoder.DisallowUnknownFields()
+
+		if err := decoder.Decode(&config); err != nil {
+			var details *toml.StrictMissingError
+			if errors.As(err, &details) {
+				fmt.Println(details.String())
+			}
+			return nil, fmt.Errorf("failed to decode TOML config, strict mode: %s", err)
 		}
 	}
 	if L.GetLevel() == zerolog.DebugLevel {