Version Protocol Changes

CHANGELOG.md

@@ -18,6 +18,8 @@ CHANGE: Refactored API implementation. Cleanup, lint removal, additional data el
 
 CHANGE: Deprecated the `passwords` configuration stanza. The zrok controller and API console now use a hard-coded set of (what we believe to be) reasonable assumptions about password quality (https://github.com/openziti/zrok/issues/834)
 
+CHANGE: The protocol for determining valid client versions has been changed. Previously a zrok client would do a `GET` against the `/api/v1/version` endpoint and do a local version string comparison (as a normal precondition to any API call) to see if the controller version matched. The protocol has been amended so that any out-of-date client using the old protocol will receive a version string indicating that they need to uprade their client. New clients will do a `POST` against the `/api/v1/version` endpoint, posting their client version, and the server will check for compatibility. Does not change the security posture in any significant way, but gives more flexibility on the server side for managing client compatibility. Provides a better, cleared out-of-date error message for old clients when accessing `v1.0.0`+ (https://github.com/openziti/zrok/issues/859)
+
 ## v0.4.48
 
 FIX: the Python SDK erroneously assumed the enabled zrok environment contained a config.json file, and was changed to only load it if the file was present (https://github.com/openziti/zrok/pull/853/).

controller/controller.go

@@ -67,9 +67,10 @@ func Run(inCfg *config.Config) error {
 	api.AdminUpdateFrontendHandler = newUpdateFrontendHandler()
 	api.EnvironmentEnableHandler = newEnableHandler()
 	api.EnvironmentDisableHandler = newDisableHandler()
+	api.MetadataConfigurationHandler = newConfigurationHandler(cfg)
+	api.MetadataClientVersionCheckHandler = metadata.ClientVersionCheckHandlerFunc(clientVersionCheckHandler)
 	api.MetadataGetAccountDetailHandler = newAccountDetailHandler()
 	api.MetadataGetSparklinesHandler = newSparklinesHandler()
-	api.MetadataConfigurationHandler = newConfigurationHandler(cfg)
 	if cfg.Metrics != nil && cfg.Metrics.Influx != nil {
 		api.MetadataGetAccountMetricsHandler = newGetAccountMetricsHandler(cfg.Metrics.Influx)
 		api.MetadataGetEnvironmentMetricsHandler = newGetEnvironmentMetricsHandler(cfg.Metrics.Influx)

controller/version.go

@@ -1,12 +1,28 @@
 package controller
 
 import (
+	"fmt"
 	"github.com/go-openapi/runtime/middleware"
 	"github.com/openziti/zrok/build"
 	"github.com/openziti/zrok/rest_model_zrok"
 	"github.com/openziti/zrok/rest_server_zrok/operations/metadata"
+	"github.com/sirupsen/logrus"
+	"regexp"
 )
 
 func versionHandler(_ metadata.VersionParams) middleware.Responder {
-	return metadata.NewVersionOK().WithPayload(rest_model_zrok.Version(build.String()))
+	outOfDate := "your local zrok installation is out of date and needs to be upgraded! " +
+		"please visit 'https://github.com/openziti/zrok/releases' for the latest build!"
+	return metadata.NewVersionOK().WithPayload(rest_model_zrok.Version(outOfDate))
+}
+
+func clientVersionCheckHandler(params metadata.ClientVersionCheckParams) middleware.Responder {
+	logrus.Debugf("client sent version '%v'", params.Body.ClientVersion)
+	// allow reported version string to be optionally prefixed with
+	// "refs/heads/" or "refs/tags/"
+	re := regexp.MustCompile(`^(refs/(heads|tags)/)?` + build.Series)
+	if !re.MatchString(params.Body.ClientVersion) {
+		return metadata.NewClientVersionCheckBadRequest().WithPayload(fmt.Sprintf("expecting a zrok client version matching '%v' version, received: '%v'; please visit 'https://github.com/openziti/zrok/releases' to make sure you're running the correct client version!", build.Series, params.Body.ClientVersion))
+	}
+	return metadata.NewClientVersionCheckOK()
 }

environment/env_v0_3/api.go

@@ -7,11 +7,11 @@ import (
 	"github.com/openziti/zrok/build"
 	"github.com/openziti/zrok/environment/env_core"
 	"github.com/openziti/zrok/rest_client_zrok"
+	metadata2 "github.com/openziti/zrok/rest_client_zrok/metadata"
 	"github.com/pkg/errors"
 	"net/url"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strconv"
 )
 
@@ -49,15 +49,13 @@ func (r *Root) Client() (*rest_client_zrok.Zrok, error) {
 	transport.Consumers["application/zrok.v1+json"] = runtime.JSONConsumer()
 
 	zrok := rest_client_zrok.New(transport, strfmt.Default)
-	v, err := zrok.Metadata.Version(nil)
+	_, err = zrok.Metadata.ClientVersionCheck(&metadata2.ClientVersionCheckParams{
+		Body: metadata2.ClientVersionCheckBody{
+			ClientVersion: build.String(),
+		},
+	})
 	if err != nil {
-		return nil, errors.Wrapf(err, "error getting version from api endpoint '%v': %v", apiEndpoint, err)
-	}
-	// allow reported version string to be optionally prefixed with
-	// "refs/heads/" or "refs/tags/"
-	re := regexp.MustCompile(`^(refs/(heads|tags)/)?` + build.Series)
-	if !re.MatchString(string(v.Payload)) {
-		return nil, errors.Errorf("expected a '%v' version, received: '%v'", build.Series, v.Payload)
+		return nil, errors.Wrapf(err, "client version error accessing api endpoint '%v': %v", apiEndpoint, err)
 	}
 
 	return zrok, nil

environment/env_v0_4/api.go

@@ -7,11 +7,12 @@ import (
 	"github.com/openziti/zrok/build"
 	"github.com/openziti/zrok/environment/env_core"
 	"github.com/openziti/zrok/rest_client_zrok"
+	metadata2 "github.com/openziti/zrok/rest_client_zrok/metadata"
 	"github.com/pkg/errors"
+	"github.com/sirupsen/logrus"
 	"net/url"
 	"os"
 	"path/filepath"
-	"regexp"
 	"strconv"
 )
 
@@ -48,18 +49,16 @@ func (r *Root) Client() (*rest_client_zrok.Zrok, error) {
 	transport.Producers["application/zrok.v1+json"] = runtime.JSONProducer()
 	transport.Consumers["application/zrok.v1+json"] = runtime.JSONConsumer()
 
+	logrus.Infof("version = %v", build.Version)
 	zrok := rest_client_zrok.New(transport, strfmt.Default)
-	v, err := zrok.Metadata.Version(nil)
+	_, err = zrok.Metadata.ClientVersionCheck(&metadata2.ClientVersionCheckParams{
+		Body: metadata2.ClientVersionCheckBody{
+			ClientVersion: build.String(),
+		},
+	})
 	if err != nil {
-		return nil, errors.Wrapf(err, "error getting version from api endpoint '%v': %v", apiEndpoint, err)
+		return nil, errors.Wrapf(err, "client version error accessing api endpoint '%v': %v", apiEndpoint, err)
 	}
-	// allow reported version string to be optionally prefixed with
-	// "refs/heads/" or "refs/tags/"
-	re := regexp.MustCompile(`^(refs/(heads|tags)/)?` + build.Series)
-	if !re.MatchString(string(v.Payload)) {
-		return nil, errors.Errorf("expected a '%v' version, received: '%v'", build.Series, v.Payload)
-	}
-
 	return zrok, nil
 }