V2 API Version Support

* Update blang/semver to allow ParseTolerant() support
* Provide helper functions for API handlers to obtain client's 'version'
  path variable focused on API endpoint tree: libpod vs. compat
* Introduce new errors:
  * version not given in path, endpoints may determine if this is a hard
    error (ErrVersionNotGiven)
  * given version not supported (ErrVersionNotSupported), only a soft
    error if the handler is going to hijack the connection
* Added unit tests for version parsing
* bindings check version on connect:
  * client <= Server API version connection is continued
  * client >= Server API version connection fails

Signed-off-by: Jhon Honce <jhonce@redhat.com>

1 files changed, 86 insertions, 0 deletions

diff --git a/pkg/api/handlers/utils/handler.go b/pkg/api/handlers/utils/handler.go
index b5bd488fb..2f4a54b98 100644
--- a/pkg/api/handlers/utils/handler.go
+++ b/pkg/api/handlers/utils/handler.go
@@ -9,11 +9,55 @@ import (
 	"os"
 	"strings"
 
+	"github.com/blang/semver"
 	"github.com/gorilla/mux"
 	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 )
 
+type (
+	// VersionTree determines which API endpoint tree for version
+	VersionTree int
+	// VersionLevel determines which API level, current or something from the past
+	VersionLevel int
+)
+
+const (
+	// LibpodTree supports Libpod endpoints
+	LibpodTree = VersionTree(iota)
+	// CompatTree supports Libpod endpoints
+	CompatTree
+
+	// CurrentApiVersion announces what is the current API level
+	CurrentApiVersion = VersionLevel(iota)
+	// MinimalApiVersion announces what is the oldest API level supported
+	MinimalApiVersion
+)
+
+var (
+	// See https://docs.docker.com/engine/api/v1.40/
+	// libpod compat handlers are expected to honor docker API versions
+
+	// ApiVersion provides the current and minimal API versions for compat and libpod endpoint trees
+	// Note: GET|HEAD /_ping is never versioned and provides the API-Version and Libpod-API-Version headers to allow
+	//       clients to shop for the Version they wish to support
+	ApiVersion = map[VersionTree]map[VersionLevel]semver.Version{
+		LibpodTree: {
+			CurrentApiVersion: semver.MustParse("1.0.0"),
+			MinimalApiVersion: semver.MustParse("1.0.0"),
+		},
+		CompatTree: {
+			CurrentApiVersion: semver.MustParse("1.40.0"),
+			MinimalApiVersion: semver.MustParse("1.24.0"),
+		},
+	}
+
+	// ErrVersionNotGiven returned when version not given by client
+	ErrVersionNotGiven = errors.New("version not given in URL path")
+	// ErrVersionNotSupported returned when given version is too old
+	ErrVersionNotSupported = errors.New("given version is not supported")
+)
+
 // IsLibpodRequest returns true if the request related to a libpod endpoint
 // (e.g., /v2/libpod/...).
 func IsLibpodRequest(r *http.Request) bool {
@@ -21,6 +65,48 @@ func IsLibpodRequest(r *http.Request) bool {
 	return len(split) >= 3 && split[2] == "libpod"
 }
 
+// SupportedVersion validates that the version provided by client is included in the given condition
+// https://github.com/blang/semver#ranges provides the details for writing conditions
+// If a version is not given in URL path, ErrVersionNotGiven is returned
+func SupportedVersion(r *http.Request, condition string) (semver.Version, error) {
+	version := semver.Version{}
+	val, ok := mux.Vars(r)["version"]
+	if !ok {
+		return version, ErrVersionNotGiven
+	}
+	safeVal, err := url.PathUnescape(val)
+	if err != nil {
+		return version, errors.Wrapf(err, "unable to unescape given API version: %q", val)
+	}
+	version, err = semver.ParseTolerant(safeVal)
+	if err != nil {
+		return version, errors.Wrapf(err, "unable to parse given API version: %q from %q", safeVal, val)
+	}
+
+	inRange, err := semver.ParseRange(condition)
+	if err != nil {
+		return version, err
+	}
+
+	if inRange(version) {
+		return version, nil
+	}
+	return version, ErrVersionNotSupported
+}
+
+// SupportedVersionWithDefaults validates that the version provided by client valid is supported by server
+// minimal API version <= client path version <= maximum API version focused on the endpoint tree from URL
+func SupportedVersionWithDefaults(r *http.Request) (semver.Version, error) {
+	tree := CompatTree
+	if IsLibpodRequest(r) {
+		tree = LibpodTree
+	}
+
+	return SupportedVersion(r,
+		fmt.Sprintf(">=%s <=%s", ApiVersion[tree][MinimalApiVersion].String(),
+			ApiVersion[tree][CurrentApiVersion].String()))
+}
+
 // WriteResponse encodes the given value as JSON or string and renders it for http client
 func WriteResponse(w http.ResponseWriter, code int, value interface{}) {
 	// RFC2616 explicitly states that the following status codes "MUST NOT