versioning: plugins report a list of supported versions

Further progress on versioning support (Issue #266).
Bump CNI spec version to 0.3.0

pkg/version/version.go

@@ -16,27 +16,67 @@ package version
 
 import (
 	"encoding/json"
+	"fmt"
 	"io"
 )
 
-// A PluginVersioner can encode information about its version
-type PluginVersioner interface {
+// Current reports the version of the CNI spec implemented by this library
+func Current() string {
+	return "0.3.0"
+}
+
+// PluginInfo reports information about CNI versioning
+type PluginInfo interface {
+	// SupportedVersions returns one or more CNI spec versions that the plugin
+	// supports.  If input is provided in one of these versions, then the plugin
+	// promises to use the same CNI version in its response
+	SupportedVersions() []string
+
+	// Encode writes this CNI version information as JSON to the given Writer
 	Encode(io.Writer) error
 }
 
-// BasicVersioner is a PluginVersioner which reports a single cniVersion string
-type BasicVersioner struct {
-	CNIVersion string `json:"cniVersion"`
+type simple struct {
+	CNIVersion_        string   `json:"cniVersion"`
+	SupportedVersions_ []string `json:"supportedVersions,omitempty"`
 }
 
-func (p *BasicVersioner) Encode(w io.Writer) error {
+func (p *simple) Encode(w io.Writer) error {
 	return json.NewEncoder(w).Encode(p)
 }
 
-// Current reports the version of the CNI spec implemented by this library
-func Current() string {
-	return "0.2.0"
+func (p *simple) SupportedVersions() []string {
+	return p.SupportedVersions_
 }
 
-// DefaultPluginVersioner reports the Current library spec version as the cniVersion
-var DefaultPluginVersioner = &BasicVersioner{CNIVersion: Current()}
+// PluginSupports returns a new PluginInfo that will report the given versions
+// as supported
+func PluginSupports(supportedVersions ...string) PluginInfo {
+	if len(supportedVersions) < 1 {
+		panic("programmer error: you must support at least one version")
+	}
+	return &simple{
+		CNIVersion_:        Current(),
+		SupportedVersions_: supportedVersions,
+	}
+}
+
+func Decode(jsonBytes []byte) (PluginInfo, error) {
+	var info simple
+	err := json.Unmarshal(jsonBytes, &info)
+	if err != nil {
+		return nil, fmt.Errorf("decoding version info: %s", err)
+	}
+	if info.CNIVersion_ == "" {
+		return nil, fmt.Errorf("decoding version info: missing field cniVersion")
+	}
+	if len(info.SupportedVersions_) == 0 {
+		if info.CNIVersion_ == "0.2.0" {
+			return PluginSupports("0.1.0", "0.2.0"), nil
+		}
+		return nil, fmt.Errorf("decoding version info: missing field supportedVersions")
+	}
+	return &info, nil
+}
+
+var Legacy = PluginSupports("0.1.0", "0.2.0", "0.3.0")

pkg/version/version_suite_test.go

@@ -0,0 +1,27 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package version_test
+
+import (
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+
+	"testing"
+)
+
+func TestVersion(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Version Suite")
+}

pkg/version/version_test.go

@@ -0,0 +1,72 @@
+// Copyright 2016 CNI authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package version_test
+
+import (
+	"github.com/containernetworking/cni/pkg/version"
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Decode", func() {
+	It("returns a PluginInfo that represents the given json bytes", func() {
+		pluginInfo, err := version.Decode([]byte(`{
+			"cniVersion": "some-library-version",
+			"supportedVersions": [ "some-version", "some-other-version" ]
+		}`))
+		Expect(err).NotTo(HaveOccurred())
+		Expect(pluginInfo).NotTo(BeNil())
+		Expect(pluginInfo.SupportedVersions()).To(Equal([]string{
+			"some-version",
+			"some-other-version",
+		}))
+	})
+
+	Context("when the bytes cannot be decoded as json", func() {
+		It("returns a meaningful error", func() {
+			_, err := version.Decode([]byte(`{{{`))
+			Expect(err).To(MatchError("decoding version info: invalid character '{' looking for beginning of object key string"))
+		})
+	})
+
+	Context("when the json bytes are missing the required CNIVersion field", func() {
+		It("returns a meaningful error", func() {
+			_, err := version.Decode([]byte(`{ "supportedVersions": [ "foo" ] }`))
+			Expect(err).To(MatchError("decoding version info: missing field cniVersion"))
+		})
+	})
+
+	Context("when there are no supported versions", func() {
+		Context("when the cniVersion is 0.2.0", func() {
+			It("infers the supported versions are 0.1.0 and 0.2.0", func() {
+				pluginInfo, err := version.Decode([]byte(`{ "cniVersion": "0.2.0" }`))
+				Expect(err).NotTo(HaveOccurred())
+				Expect(pluginInfo).NotTo(BeNil())
+				Expect(pluginInfo.SupportedVersions()).To(Equal([]string{
+					"0.1.0",
+					"0.2.0",
+				}))
+			})
+		})
+
+		Context("when the cniVersion is >= 0.3.0", func() {
+			It("returns a meaningful error", func() {
+				_, err := version.Decode([]byte(`{ "cniVersion": "0.3.0" }`))
+				Expect(err).To(MatchError("decoding version info: missing field supportedVersions"))
+			})
+		})
+	})
+
+})