Add grammar for platform string

Platform string to be of the form
<os>[(<osversion>)]|<arch>|<os>[(<OSVersion>)]/<arch>[/<variant>]
OSVersion is optional only and currently used only by Windows OS.

Signed-off-by: Kirtana Ashok <[email protected]>

database.go

@@ -17,6 +17,7 @@
 package platforms
 
 import (
+	"regexp"
 	"runtime"
 	"strings"
 )
@@ -59,6 +60,25 @@ func isKnownArch(arch string) bool {
 	return false
 }
 
+// normalizeOSAndVersion will only include the OSVersion if present.
+// The formart of OS on the platform specifier is <OS>[(<OSVersion>)]
+// OSVersion is optional only and is currently used only by windows OS.
+// If OsVersion is not specified, empty string is returned.
+func normalizeOSAndVersion(OSAndVersion string) (string, string) {
+	if OSAndVersion == "" {
+		return runtime.GOOS, ""
+	}
+
+	parts := regexp.MustCompile("[()]").Split(OSAndVersion, -1)
+	OS := normalizeOS(parts[0])
+	OSVersion := ""
+	if len(parts) > 1 && parts[1] != "" {
+		OSVersion = normalizeOSVersion(parts[1])
+	}
+
+	return OS, OSVersion
+}
+
 func normalizeOS(os string) string {
 	if os == "" {
 		return runtime.GOOS
@@ -72,6 +92,13 @@ func normalizeOS(os string) string {
 	return os
 }
 
+func normalizeOSVersion(OSVersion string) string {
+	if OSVersion == "" {
+		return ""
+	}
+	return OSVersion
+}
+
 // normalizeArch normalizes the architecture.
 func normalizeArch(arch, variant string) (string, string) {
 	arch, variant = strings.ToLower(arch), strings.ToLower(variant)

defaults.go

@@ -18,7 +18,7 @@ package platforms
 
 // DefaultString returns the default string specifier for the platform.
 func DefaultString() string {
-	return Format(DefaultSpec())
+	return FormatV2(DefaultSpec())
 }
 
 // DefaultStrict returns strict form of Default.

defaults_unix_test.go

@@ -38,7 +38,7 @@ func TestDefault(t *testing.T) {
 	}
 
 	s := DefaultString()
-	if s != Format(p) {
+	if s != FormatV2(p) {
 		t.Fatalf("default specifier should match formatted default spec: %v != %v", s, p)
 	}
 }

defaults_windows_test.go

@@ -42,7 +42,7 @@ func TestDefault(t *testing.T) {
 	}
 
 	s := DefaultString()
-	if s != Format(p) {
+	if s != FormatV2(p) {
 		t.Fatalf("default specifier should match formatted default spec: %v != %v", s, p)
 	}
 }

platforms.go

@@ -121,9 +121,12 @@ import (
 )
 
 var (
-	specifierRe = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
+	specifierRe    = regexp.MustCompile(`^[A-Za-z0-9_-]+(\([A-Za-z0-9_.-]*\))?$`)
+	OSAndVersionRe = regexp.MustCompile(`[()]`)
 )
 
+const OSAndVersionFormat = "%s(%s)"
+
 // Platform is a type alias for convenience, so there is no need to import image-spec package everywhere.
 type Platform = specs.Platform
 
@@ -156,7 +159,7 @@ func (m *matcher) Match(platform specs.Platform) bool {
 }
 
 func (m *matcher) String() string {
-	return Format(m.Platform)
+	return FormatV2(m.Platform)
 }
 
 // ParseAll parses a list of platform specifiers into a list of platform.
@@ -174,9 +177,12 @@ func ParseAll(specifiers []string) ([]specs.Platform, error) {
 
 // Parse parses the platform specifier syntax into a platform declaration.
 //
-// Platform specifiers are in the format `<os>|<arch>|<os>/<arch>[/<variant>]`.
+// Platform specifiers are in the format `<os>[(<OSVersion>)]|<arch>|<os>[(<OSVersion>)]/<arch>[/<variant>]`.
 // The minimum required information for a platform specifier is the operating
-// system or architecture. If there is only a single string (no slashes), the
+// system or architecture. The OSVersion can be part of the OS like windows(10.0.17763)
+// Therefore, an os version is specified, then specs.Platform.OSVersion is populated.
+// If not it is left empty.
+// If there is only a single string (no slashes), the
 // value will be matched against the known set of operating systems, then fall
 // back to the known set of architectures. The missing component will be
 // inferred based on the local environment.
@@ -197,23 +203,20 @@ func Parse(specifier string) (specs.Platform, error) {
 	var p specs.Platform
 	switch len(parts) {
 	case 1:
-		// in this case, we will test that the value might be an OS, then look
-		// it up. If it is not known, we'll treat it as an architecture. Since
+		// in this case, we will test that the value might be an OS (with or
+		// without the optional osversion specified) and look it up.
+		// If it is not known, we'll treat it as an architecture. Since
 		// we have very little information about the platform here, we are
 		// going to be a little more strict if we don't know about the argument
 		// value.
-		p.OS = normalizeOS(parts[0])
+		p.OS, p.OSVersion = normalizeOSAndVersion(parts[0])
 		if isKnownOS(p.OS) {
 			// picks a default architecture
 			p.Architecture = runtime.GOARCH
 			if p.Architecture == "arm" && cpuVariant() != "v7" {
 				p.Variant = cpuVariant()
 			}
 
-			if p.OS == "windows" {
-				p.OSVersion = GetWindowsOsVersion()
-			}
-
 			return p, nil
 		}
 
@@ -228,31 +231,23 @@ func Parse(specifier string) (specs.Platform, error) {
 
 		return specs.Platform{}, fmt.Errorf("%q: unknown operating system or architecture: %w", specifier, errInvalidArgument)
 	case 2:
-		// In this case, we treat as a regular os/arch pair. We don't care
+		// In this case, we treat as a regular os[(osversion)]/arch pair. We don't care
 		// about whether or not we know of the platform.
-		p.OS = normalizeOS(parts[0])
+		p.OS, p.OSVersion = normalizeOSAndVersion(parts[0])
 		p.Architecture, p.Variant = normalizeArch(parts[1], "")
 		if p.Architecture == "arm" && p.Variant == "v7" {
 			p.Variant = ""
 		}
 
-		if p.OS == "windows" {
-			p.OSVersion = GetWindowsOsVersion()
-		}
-
 		return p, nil
 	case 3:
 		// we have a fully specified variant, this is rare
-		p.OS = normalizeOS(parts[0])
+		p.OS, p.OSVersion = normalizeOSAndVersion(parts[0])
 		p.Architecture, p.Variant = normalizeArch(parts[1], parts[2])
 		if p.Architecture == "arm64" && p.Variant == "" {
 			p.Variant = "v8"
 		}
 
-		if p.OS == "windows" {
-			p.OSVersion = GetWindowsOsVersion()
-		}
-
 		return p, nil
 	}
 
@@ -278,12 +273,27 @@ func Format(platform specs.Platform) string {
 	return path.Join(platform.OS, platform.Architecture, platform.Variant)
 }
 
+// FormatV2 returns a string specifier that also includes the OSVersion from the
+// provided platform specification.
+func FormatV2(platform specs.Platform) string {
+	if platform.OS == "" {
+		return "unknown"
+	}
+
+	if platform.OSVersion != "" {
+		OSAndVersion := fmt.Sprintf(OSAndVersionFormat, platform.OS, platform.OSVersion)
+		return path.Join(OSAndVersion, platform.Architecture, platform.Variant)
+	}
+	return path.Join(platform.OS, platform.Architecture, platform.Variant)
+}
+
 // Normalize validates and translate the platform to the canonical value.
 //
 // For example, if "Aarch64" is encountered, we change it to "arm64" or if
 // "x86_64" is encountered, it becomes "amd64".
 func Normalize(platform specs.Platform) specs.Platform {
 	platform.OS = normalizeOS(platform.OS)
+	platform.OSVersion = normalizeOSVersion(platform.OSVersion)
 	platform.Architecture, platform.Variant = normalizeArch(platform.Architecture, platform.Variant)
 
 	return platform

platforms_other.go

@@ -28,7 +28,3 @@ func newDefaultMatcher(platform specs.Platform) Matcher {
 		Platform: Normalize(platform),
 	}
 }
-
-func GetWindowsOsVersion() string {
-	return ""
-}

platforms_test.go

@@ -290,6 +290,36 @@ func TestParseSelector(t *testing.T) {
 			},
 			formatted: path.Join("darwin", defaultArch, defaultVariant),
 		},
+		{
+			input: "windows",
+			expected: specs.Platform{
+				OS:           "windows",
+				OSVersion:    "",
+				Architecture: defaultArch,
+				Variant:      defaultVariant,
+			},
+			formatted: path.Join("windows", defaultArch, defaultVariant),
+		},
+		{
+			input: "windows()",
+			expected: specs.Platform{
+				OS:           "windows",
+				OSVersion:    "",
+				Architecture: defaultArch,
+				Variant:      defaultVariant,
+			},
+			formatted: path.Join("windows", defaultArch, defaultVariant),
+		},
+		{
+			input: "windows(10.0.17763)",
+			expected: specs.Platform{
+				OS:           "windows",
+				OSVersion:    "10.0.17763",
+				Architecture: defaultArch,
+				Variant:      defaultVariant,
+			},
+			formatted: path.Join("windows(10.0.17763)", defaultArch, defaultVariant),
+		},
 	} {
 		t.Run(testcase.input, func(t *testing.T) {
 			if testcase.skip {
@@ -316,7 +346,7 @@ func TestParseSelector(t *testing.T) {
 				}
 			}
 
-			formatted := Format(p)
+			formatted := FormatV2(p)
 			if formatted != testcase.formatted {
 				t.Fatalf("unexpected format: %q != %q", formatted, testcase.formatted)
 			}
@@ -327,8 +357,8 @@ func TestParseSelector(t *testing.T) {
 				t.Fatalf("error parsing formatted output: %v", err)
 			}
 
-			if Format(reparsed) != formatted {
-				t.Fatalf("normalized output did not survive the round trip: %v != %v", Format(reparsed), formatted)
+			if FormatV2(reparsed) != formatted {
+				t.Fatalf("normalized output did not survive the round trip: %v != %v", FormatV2(reparsed), formatted)
 			}
 		})
 	}

platforms_windows.go

@@ -17,10 +17,7 @@
 package platforms
 
 import (
-	"fmt"
-
 	specs "github.com/opencontainers/image-spec/specs-go/v1"
-	"golang.org/x/sys/windows"
 )
 
 // NewMatcher returns a Windows matcher that will match on osVersionPrefix if
@@ -35,8 +32,3 @@ func newDefaultMatcher(platform specs.Platform) Matcher {
 		},
 	}
 }
-
-func GetWindowsOsVersion() string {
-	major, minor, build := windows.RtlGetNtVersionNumbers()
-	return fmt.Sprintf("%d.%d.%d", major, minor, build)
-}