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 <kiashok@microsoft.com>

Author: kiashok

defaults.go

@@ -16,9 +16,11 @@
 
 package platforms
 
-// DefaultString returns the default string specifier for the platform.
+// DefaultString returns the default string specifier for the platform,
+// with [PR#6](https://github.com/containerd/platforms/pull/6) the result
+// may now also include the OSVersion from the provided platform specification.
 func DefaultString() string {
-	return Format(DefaultSpec())
+	return FormatAll(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 != FormatAll(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 != FormatAll(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_-]+$`)
+	osAndVersionRe = regexp.MustCompile(`^([A-Za-z0-9_-]+)(?:\(([A-Za-z0-9_.-]*)\))?$`)
 )
 
+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 FormatAll(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)`
+// When an OSVersion is specified, then specs.Platform.OSVersion is populated with that value,
+// and an empty string otherwise.
+// 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.
@@ -186,34 +192,42 @@ func Parse(specifier string) (specs.Platform, error) {
 		return specs.Platform{}, fmt.Errorf("%q: wildcards not yet supported: %w", specifier, errInvalidArgument)
 	}
 
-	parts := strings.Split(specifier, "/")
+	// Limit to 4 elements to prevent unbounded split
+	parts := strings.SplitN(specifier, "/", 4)
 
-	for _, part := range parts {
-		if !specifierRe.MatchString(part) {
-			return specs.Platform{}, fmt.Errorf("%q is an invalid component of %q: platform specifier component must match %q: %w", part, specifier, specifierRe.String(), errInvalidArgument)
+	var p specs.Platform
+	for i, part := range parts {
+		if i == 0 {
+			// First element is <os>[(<OSVersion>)]
+			osVer := osAndVersionRe.FindStringSubmatch(part)
+			if osVer == nil {
+				return specs.Platform{}, fmt.Errorf("%q is an invalid OS component of %q: OSAndVersion specifier component must match %q: %w", part, specifier, osAndVersionRe.String(), errInvalidArgument)
+			}
+
+			p.OS = normalizeOS(osVer[1])
+			p.OSVersion = osVer[2]
+		} else {
+			if !specifierRe.MatchString(part) {
+				return specs.Platform{}, fmt.Errorf("%q is an invalid component of %q: platform specifier component must match %q: %w", part, specifier, specifierRe.String(), errInvalidArgument)
+			}
 		}
 	}
 
-	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])
 		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 +242,21 @@ 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.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.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,6 +282,20 @@ func Format(platform specs.Platform) string {
 	return path.Join(platform.OS, platform.Architecture, platform.Variant)
 }
 
+// FormatAll returns a string specifier that also includes the OSVersion from the
+// provided platform specification.
+func FormatAll(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

platforms_other.go

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