feat: update plugin to check for a minimum required version

README.md

@@ -18,7 +18,7 @@ cf install-plugin <path_to_plugin_binary>
 ```
 
 ### Releasing
-To create a new GitHub release, decide on a new version number [according to Semanitc Versioning](https://semver.org/), and then:
+To create a new GitHub release, decide on a new version number [according to Semantic Versioning](https://semver.org/), and then:
 1. Create a tag on the main branch with a leading `v`:
    `git tag vX.Y.X`
 1. Push the tag:
@@ -32,9 +32,10 @@ To create a new GitHub release, decide on a new version number [according to Sem
 cf upgrade-all-services <broker_name> [options]
 
 Options:
-    -parallel - number of upgrades to run in parallel (defaults to 10)
-    -loghttp  - log HTTP requests and responses
-    -dry-run  - print the service instances that would be upgraded
-    -check-up-to-date - checks and fails if any service instance is not up-to-date - implies a dry-run
-    -check-deactivated-plans - checks whether any of the plans have been deactivated. If any deactivated plans are found, the command will fail
+    -parallel                                 - number of upgrades to run in parallel (defaults to 10)
+    -loghttp                                  - log HTTP requests and responses
+    -dry-run                                  - print the service instances that would be upgraded
+    -min-version-required <major.minor.patch> - checks and fails if any service instance has a version less than the minimum required <major.minor.patch>
+    -check-up-to-date                         - checks and fails if any service instance is not up-to-date. An instance is not up-to-date if it is marked as upgradable or belongs to a deactivated plan
+    -check-deactivated-plans                  - checks and fails if any of the plans have been deactivated
 ```

internal/config/config.go

@@ -14,6 +14,7 @@ type Config struct {
 	SkipSSLValidation     bool
 	HTTPLogging           bool
 	DryRun                bool
+	MinVersionRequired    string
 	CheckUpToDate         bool
 	CheckDeactivatedPlans bool
 	ParallelUpgrades      int
@@ -28,41 +29,33 @@ func ParseConfig(conn CLIConnection, args []string) (Config, error) {
 	flagSet.BoolVar(&cfg.HTTPLogging, httpLoggingFlag, httpLoggingDefault, httpLoggingDescription)
 	flagSet.BoolVar(&cfg.DryRun, dryRunFlag, dryRunDefault, dryRunDescription)
 	flagSet.BoolVar(&cfg.CheckUpToDate, checkUpToDateFlag, checkUpToDateDefault, checkUpToDateDescription)
+	flagSet.StringVar(&cfg.MinVersionRequired, minVersionRequiredFlag, minVersionRequiredDefault, minVersionRequiredDescription)
 	flagSet.BoolVar(&cfg.CheckDeactivatedPlans, checkDeactivatedPlansFlag, checkDeactivatedPlansDefault, checkDeactivatedPlansDescription)
 
 	// This ranges over a chain of functions, each of which performs a single action and may return an error.
 	// The chain breaks at the first error received. It arguably reads better than repetitive error handling logic.
 	for _, s := range []func() error{
-		func() error {
-			return validateLoginStatus(conn)
-		},
-		func() error {
-			return validateAPIVersion(conn)
-		},
-		func() error {
-			return read("access token", conn.AccessToken, &cfg.APIToken)
-		},
-		func() error {
-			return read("API endpoint", conn.ApiEndpoint, &cfg.APIEndpoint)
-		},
-		func() error {
-			return read("skip SSL validation", conn.IsSSLDisabled, &cfg.SkipSSLValidation)
-		},
+		func() error { return validateLoginStatus(conn) },
+		func() error { return validateAPIVersion(conn) },
+		func() error { return read("access token", conn.AccessToken, &cfg.APIToken) },
+		func() error { return read("API endpoint", conn.ApiEndpoint, &cfg.APIEndpoint) },
+		func() error { return read("skip SSL validation", conn.IsSSLDisabled, &cfg.SkipSSLValidation) },
 		func() (err error) {
 			cfg.BrokerName, err = parseCommandLine(flagSet, args)
 			return
 		},
-		func() error {
-			return validateParallelUpgrades(cfg.ParallelUpgrades)
-		},
-		func() error {
-			return validateBrokerName(cfg.BrokerName)
+		func() error { return validateParallelUpgrades(cfg.ParallelUpgrades) },
+		func() error { return validateBrokerName(cfg.BrokerName) },
+		func() (err error) {
+			cfg.MinVersionRequired, err = validateMinVersionRequired(cfg.MinVersionRequired)
+			return
 		},
 	} {
 		if err := s(); err != nil {
 			return Config{}, err
 		}
 	}
+
 	return cfg, nil
 }
 

internal/config/config_test.go

@@ -2,6 +2,7 @@ package config_test
 
 import (
 	"fmt"
+
 	"upgrade-all-services-cli-plugin/internal/config"
 	"upgrade-all-services-cli-plugin/internal/config/configfakes"
 
@@ -309,6 +310,44 @@ var _ = Describe("Config", func() {
 		})
 	})
 
+	Describe("min-version-required", func() {
+		When("not specified", func() {
+			It("is not set", func() {
+				Expect(cfg.MinVersionRequired).To(BeEmpty())
+			})
+		})
+
+		When("specified without version", func() {
+			BeforeEach(func() {
+				fakeArgs = append(fakeArgs, "-min-version-required=")
+			})
+
+			It("an empty value is set", func() {
+				Expect(cfg.MinVersionRequired).To(BeEmpty())
+			})
+		})
+
+		When("specified with a non-semver version", func() {
+			BeforeEach(func() {
+				fakeArgs = append(fakeArgs, "-min-version-required", "invalid version")
+			})
+
+			It("returns an error", func() {
+				Expect(cfgErr).To(MatchError(ContainSubstring("error parsing min-version-required option: Malformed version: invalid version")))
+			})
+		})
+
+		When("specified with version", func() {
+			BeforeEach(func() {
+				fakeArgs = append(fakeArgs, "-min-version-required", "1.3.0")
+			})
+
+			It("is set and the value is the version", func() {
+				Expect(cfg.MinVersionRequired).To(Equal("1.3.0"))
+			})
+		})
+	})
+
 	Describe("invalid combinations", func() {
 		When("-dry-run and -parallel are specified together", func() {
 			BeforeEach(func() {

internal/config/flags.go

@@ -19,7 +19,11 @@ const (
 
 	checkUpToDateDefault     = false
 	checkUpToDateFlag        = "check-up-to-date"
-	checkUpToDateDescription = "checks and fails if any service instance is not up-to-date - implies a dry-run"
+	checkUpToDateDescription = "checks and fails if any service instance is not up-to-date. An instance is not up-to-date if it is marked as upgradable or belongs to a deactivated plan"
+
+	minVersionRequiredDefault     = ""
+	minVersionRequiredFlag        = "min-version-required"
+	minVersionRequiredDescription = "--min-version-required <major.minor.patch>. Checks and fails if any service instance has a version lower than the specified"
 
 	checkDeactivatedPlansDefault     = false
 	checkDeactivatedPlansFlag        = "check-deactivated-plans"

internal/config/usage.go

@@ -14,6 +14,7 @@ func UsageOptions() map[string]string {
 		parallelFlag:              parallelDescription,
 		httpLoggingFlag:           httpLoggingDescription,
 		dryRunFlag:                dryRunDescription,
+		minVersionRequiredFlag:    minVersionRequiredDescription,
 		checkUpToDateFlag:         checkUpToDateDescription,
 		checkDeactivatedPlansFlag: checkDeactivatedPlansDescription,
 	}

internal/config/validations.go

@@ -68,3 +68,15 @@ func validateBrokerName(name string) error {
 
 	return nil
 }
+
+func validateMinVersionRequired(ver string) (string, error) {
+	if ver == "" {
+		return "", nil
+	}
+
+	v, err := version.NewVersion(ver)
+	if err != nil {
+		return "", fmt.Errorf("error parsing min-version-required option: %w", err)
+	}
+	return v.String(), nil
+}

internal/upgrader/multi_error.go

@@ -0,0 +1,27 @@
+package upgrader
+
+import (
+	"errors"
+)
+
+type MultiError struct {
+	Errors []error
+}
+
+// Append adds a non-nil error to the MultiError.
+// If the provided error is nil, it will be ignored, preventing
+// nil errors from being included in the error slice.
+// This method simplifies error aggregation by centralizing nil checks.
+func (m *MultiError) Append(err error) {
+	if err != nil {
+		m.Errors = append(m.Errors, err)
+	}
+}
+
+// Error implements the error interface. It returns a concatenated
+// string of all the non-nil errors it contains. If there are no non-nil
+// errors, it returns an empty string.
+// This method allows MultiError to seamlessly integrate with typical error handling in Go.
+func (m *MultiError) Error() string {
+	return errors.Join(m.Errors...).Error()
+}

internal/upgrader/upgrader.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"upgrade-all-services-cli-plugin/internal/ccapi"
+	"upgrade-all-services-cli-plugin/internal/versionchecker"
 	"upgrade-all-services-cli-plugin/internal/workers"
 )
 
@@ -34,6 +35,7 @@ type UpgradeConfig struct {
 	BrokerName            string
 	ParallelUpgrades      int
 	DryRun                bool
+	MinVersionRequired    string
 	CheckUpToDate         bool
 	CheckDeactivatedPlans bool
 }
@@ -45,7 +47,7 @@ func Upgrade(api CFClient, log Logger, cfg UpgradeConfig) error {
 	}
 
 	if len(servicePlans) == 0 {
-		return fmt.Errorf(fmt.Sprintf("no service plans available for broker: %s", cfg.BrokerName))
+		return fmt.Errorf("no service plans available for broker: %s", cfg.BrokerName)
 	}
 
 	log.Printf("discovering service instances for broker: %s", cfg.BrokerName)
@@ -54,31 +56,75 @@ func Upgrade(api CFClient, log Logger, cfg UpgradeConfig) error {
 		return err
 	}
 
-	if cfg.CheckDeactivatedPlans {
-		if err := checkDeactivatedPlans(log, serviceInstances); err != nil {
+	upgradableInstances := discoverInstancesWithPendingUpgrade(log, serviceInstances)
+
+	switch {
+	case cfg.CheckDeactivatedPlans:
+		return checkDeactivatedPlans(log, serviceInstances)
+	case cfg.CheckUpToDate:
+		log.InitialTotals(len(serviceInstances), len(upgradableInstances))
+		defer log.FinalTotals()
+		var errs MultiError
+		performDryRun(upgradableInstances, log)
+		if len(upgradableInstances) > 0 {
+			errs.Append(fmt.Errorf("found %d instances which are not up-to-date", len(upgradableInstances)))
+		}
+		errs.Append(checkDeactivatedPlans(log, serviceInstances))
+		if len(errs.Errors) > 0 {
+			return &errs
+		}
+
+		return nil
+	case cfg.MinVersionRequired != "":
+		filteredInstances, err := filterInstancesVersionLessThanMinimumVersionRequired(serviceInstances, cfg.MinVersionRequired)
+		if err != nil {
 			return err
 		}
-	}
 
-	totalServiceInstances := len(serviceInstances)
-	upgradableInstances := discoverInstancesWithPendingUpgrade(log, serviceInstances)
+		if len(filteredInstances) == 0 {
+			log.Printf("no instances found with version less than required")
+			return nil
+		}
 
-	switch {
+		log.InitialTotals(len(serviceInstances), len(filteredInstances))
+		defer log.FinalTotals()
+		performDryRun(filteredInstances, log)
+		return fmt.Errorf("found %d service instances with a version less than the minimum required", len(filteredInstances))
 	case len(upgradableInstances) == 0:
 		log.Printf("no instances available to upgrade")
 		return nil
-	case cfg.CheckUpToDate:
-		log.InitialTotals(totalServiceInstances, len(upgradableInstances))
-		return performCheckUpToDate(upgradableInstances, log)
 	case cfg.DryRun:
-		log.InitialTotals(totalServiceInstances, len(upgradableInstances))
-		return performDryRun(upgradableInstances, log)
+		log.InitialTotals(len(serviceInstances), len(upgradableInstances))
+		defer log.FinalTotals()
+		performDryRun(upgradableInstances, log)
+		return nil
 	default:
-		log.InitialTotals(totalServiceInstances, len(upgradableInstances))
+		log.InitialTotals(len(serviceInstances), len(upgradableInstances))
+		defer log.FinalTotals()
 		return performUpgrade(api, upgradableInstances, cfg.ParallelUpgrades, log)
 	}
 }
 
+func filterInstancesVersionLessThanMinimumVersionRequired(instances []ccapi.ServiceInstance, minVersionRequired string) ([]ccapi.ServiceInstance, error) {
+	checker, err := versionchecker.New(minVersionRequired)
+	if err != nil {
+		return nil, err
+	}
+
+	var filteredInstances []ccapi.ServiceInstance
+	for _, instance := range instances {
+		is, err := checker.IsInstanceVersionLessThanMinimumRequired(instance.MaintenanceInfoVersion)
+		if err != nil {
+			return nil, err
+		}
+
+		if is {
+			filteredInstances = append(filteredInstances, instance)
+		}
+	}
+	return filteredInstances, nil
+}
+
 func checkDeactivatedPlans(log Logger, instances []ccapi.ServiceInstance) error {
 	var deactivatedPlanFound bool
 	for _, instance := range instances {
@@ -131,31 +177,17 @@ func performUpgrade(api CFClient, upgradableInstances []ccapi.ServiceInstance, p
 		}
 	})
 
-	log.FinalTotals()
 	if !log.HasUpgradeSucceeded() {
 		return errors.New("there were failures upgrading one or more instances. Review the logs for more information")
 	}
 	return nil
 }
 
-func performCheckUpToDate(upgradableInstances []ccapi.ServiceInstance, log Logger) error {
-	err := performDryRun(upgradableInstances, log)
-	if err != nil {
-		return fmt.Errorf("check up-to-date failed because dry-run returned the following error: %w", err)
-	}
-	if len(upgradableInstances) > 0 {
-		return fmt.Errorf("check up-to-date failed: found %d instances which are not up-to-date", len(upgradableInstances))
-	}
-	return nil
-}
-
-func performDryRun(upgradableInstances []ccapi.ServiceInstance, log Logger) error {
-	log.Printf("the following service instances would be upgraded:")
-	for _, i := range upgradableInstances {
-		log.UpgradeFailed(i, time.Duration(0), fmt.Errorf("dry-run prevented upgrade"))
+func performDryRun(serviceInstances []ccapi.ServiceInstance, log Logger) {
+	for _, i := range serviceInstances {
+		dryRunErr := fmt.Errorf("dry-run prevented upgrade instance guid %s", i.GUID)
+		log.UpgradeFailed(i, time.Duration(0), dryRunErr)
 	}
-	log.FinalTotals()
-	return nil
 }
 
 func discoverInstancesWithPendingUpgrade(log Logger, serviceInstances []ccapi.ServiceInstance) []ccapi.ServiceInstance {