From a1339277f0a00018e398b2b32c7102f619552467 Mon Sep 17 00:00:00 2001 From: Pat Gavlin Date: Tue, 16 Nov 2021 15:53:28 -0800 Subject: [PATCH] [schema] Add enum overlay support. (#8425) And update the metaschema to accommodate the `isOverlay` properties added in #8338. Overlay enums, like other overlay members, are implemented out-of-band by the declaring package. Code generators should not generate declarations for overlay enums. --- CHANGELOG_PENDING.md | 1 + developer-docs/providers/metaschema.md | 36 +++++++++++- pkg/codegen/dotnet/gen.go | 6 +- pkg/codegen/go/gen.go | 6 +- .../test/testdata/schema/overlay.json | 22 ++++++++ .../docs/overlayresource/_index.md | 55 +++++++++++++++++++ .../simple-resource-schema/schema.json | 16 ++++++ pkg/codegen/nodejs/gen.go | 8 ++- pkg/codegen/python/gen.go | 6 +- pkg/codegen/schema/pulumi.json | 22 ++++++-- pkg/codegen/schema/schema.go | 17 ++++-- 11 files changed, 173 insertions(+), 22 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index de2843bd2..c79a31188 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -11,6 +11,7 @@ - [schema] Add IsOverlay option to disable codegen for particular types [#8338](https://github.com/pulumi/pulumi/pull/8338) + [#8425](https://github.com/pulumi/pulumi/pull/8425) - [sdk/dotnet] - Marshal output values. [#8316](https://github.com/pulumi/pulumi/pull/8316) diff --git a/developer-docs/providers/metaschema.md b/developer-docs/providers/metaschema.md index 5c496c966..8b00d2e17 100644 --- a/developer-docs/providers/metaschema.md +++ b/developer-docs/providers/metaschema.md @@ -57,6 +57,14 @@ The description of the package. Descriptions are interpreted as Markdown. --- +### `displayName` + +The human-friendly name of the package. + +`string` + +--- + ### `functions` A map from token to functionSpec that describes the set of functions defined by this package. @@ -159,6 +167,14 @@ The provider type for this package. --- +### `publisher` + +The name of the person or organization that authored and published the package. + +`string` + +--- + ### `repository` The URL at which the package's sources can be found. @@ -361,6 +377,14 @@ The bag of input values for the function, if any. --- +#### `isOverlay` + +Indicates that the implementation of the function should not be generated from the schema, and is instead provided out-of-band by the package author + +`boolean` + +--- + #### `language` Additional language-specific data about the function. @@ -661,7 +685,7 @@ Indicates whether the resource is a component. #### `isOverlay` -Indicates whether the resource is an overlay (code is generated by the package rather than by the core Pulumi codegen). +Indicates that the implementation of the resource should not be generated from the schema, and is instead provided out-of-band by the package author `boolean` @@ -699,7 +723,7 @@ An optional objectTypeSpec that describes additional inputs that mau be necessar `string` -Pattern: `^[a-zA-Z][-a-zA-Z0-9_]*:([^0-9][a-zA-Z0-9._/]*)?:[^0-9][a-zA-Z0-9._/]*$` +Pattern: `^[a-zA-Z][-a-zA-Z0-9_]*:([^0-9][a-zA-Z0-9._/-]*)?:[^0-9][a-zA-Z0-9._/]*$` ## Type Definition @@ -721,6 +745,14 @@ The description of the type, if any. Interpreted as Markdown. --- +#### `isOverlay` + +Indicates that the implementation of the type should not be generated from the schema, and is instead provided out-of-band by the package author + +`boolean` + +--- + #### `language` Additional language-specific data about the type. diff --git a/pkg/codegen/dotnet/gen.go b/pkg/codegen/dotnet/gen.go index 0b26c4e7a..b91187a52 100644 --- a/pkg/codegen/dotnet/gen.go +++ b/pkg/codegen/dotnet/gen.go @@ -2352,8 +2352,10 @@ func generateModuleContextMap(tool string, pkg *schema.Package) (map[string]*mod mod := getModFromToken(typ.Token, pkg) mod.types = append(mod.types, typ) case *schema.EnumType: - mod := getModFromToken(typ.Token, pkg) - mod.enums = append(mod.enums, typ) + if !typ.IsOverlay { + mod := getModFromToken(typ.Token, pkg) + mod.enums = append(mod.enums, typ) + } default: continue } diff --git a/pkg/codegen/go/gen.go b/pkg/codegen/go/gen.go index 06c41b4ed..0cb8e9f88 100644 --- a/pkg/codegen/go/gen.go +++ b/pkg/codegen/go/gen.go @@ -2769,8 +2769,10 @@ func generatePackageContextMap(tool string, pkg *schema.Package, goInfo GoPackag } populateDetailsForPropertyTypes(seenMap, typ.Properties, false) case *schema.EnumType: - pkg := getPkgFromToken(typ.Token) - pkg.enums = append(pkg.enums, typ) + if !typ.IsOverlay { + pkg := getPkgFromToken(typ.Token) + pkg.enums = append(pkg.enums, typ) + } } } diff --git a/pkg/codegen/internal/test/testdata/schema/overlay.json b/pkg/codegen/internal/test/testdata/schema/overlay.json index 65d3778d8..8cc2f81b0 100644 --- a/pkg/codegen/internal/test/testdata/schema/overlay.json +++ b/pkg/codegen/internal/test/testdata/schema/overlay.json @@ -10,6 +10,16 @@ }, "type": "object" }, + "example::EnumOverlay": { + "type": "string", + "enum": [ + { + "name": "SomeEnumValue", + "value": "SOME_ENUM_VALUE" + } + ], + "isOverlay": true + }, "example::ConfigMapOverlay": { "isOverlay": true, "properties": { @@ -25,11 +35,17 @@ "properties": { "foo": { "$ref": "#/types/example::ConfigMapOverlay" + }, + "bar": { + "$ref": "#/types/example::EnumOverlay" } }, "inputProperties": { "foo": { "$ref": "#/types/example::ConfigMapOverlay" + }, + "bar": { + "$ref": "#/types/example::EnumOverlay" } }, "type": "object" @@ -39,11 +55,17 @@ "properties": { "foo": { "$ref": "#/types/example::ConfigMapOverlay" + }, + "bar": { + "$ref": "#/types/example::EnumOverlay" } }, "inputProperties": { "foo": { "$ref": "#/types/example::ConfigMapOverlay" + }, + "bar": { + "$ref": "#/types/example::EnumOverlay" } }, "type": "object" diff --git a/pkg/codegen/internal/test/testdata/simple-resource-schema/docs/overlayresource/_index.md b/pkg/codegen/internal/test/testdata/simple-resource-schema/docs/overlayresource/_index.md index fe940258c..6683ab811 100644 --- a/pkg/codegen/internal/test/testdata/simple-resource-schema/docs/overlayresource/_index.md +++ b/pkg/codegen/internal/test/testdata/simple-resource-schema/docs/overlayresource/_index.md @@ -27,6 +27,7 @@ no_edit_this_page: true 
@overload
 def OverlayResource(resource_name: str,
                     opts: Optional[ResourceOptions] = None,
+                    bar: Optional[EnumOverlay] = None,
                     foo: Optional[ConfigMapOverlayArgs] = None)
 @overload
 def OverlayResource(resource_name: str,
@@ -157,6 +158,14 @@ The OverlayResource resource accepts the following [input]({{< relref "/docs/int
 {{% choosable language csharp %}}
 

+        
+Bar
+
+        
+        Pulumi.Example.EnumOverlay
+    

+    
{{% md %}}{{% /md %}}

         
 Foo
 
@@ -169,6 +178,14 @@ The OverlayResource resource accepts the following [input]({{< relref "/docs/int
 {{% choosable language go %}}
 

+        
+Bar
+
+        
+        EnumOverlay
+    

+    
{{% md %}}{{% /md %}}

         
 Foo
 
@@ -181,6 +198,14 @@ The OverlayResource resource accepts the following [input]({{< relref "/docs/int
 {{% choosable language nodejs %}}
 

+        
+bar
+
+        
+        EnumOverlay
+    

+    
{{% md %}}{{% /md %}}

         
 foo
 
@@ -193,6 +218,14 @@ The OverlayResource resource accepts the following [input]({{< relref "/docs/int
 {{% choosable language python %}}
 

+        
+bar
+
+        
+        EnumOverlay
+    

+    
{{% md %}}{{% /md %}}

         
 foo
 
@@ -317,6 +350,28 @@ All [input](#inputs) properties are implicitly available as output properties. A
     
{{% md %}}{{% /md %}}

 {{% /choosable %}}
 
+
EnumOverlay

+
+{{% choosable language csharp %}}
+
SomeEnumValue

+    
SOME_ENUM_VALUE

+{{% /choosable %}}
+
+{{% choosable language go %}}
+
EnumOverlaySomeEnumValue

+    
SOME_ENUM_VALUE

+{{% /choosable %}}
+
+{{% choosable language nodejs %}}
+
SomeEnumValue

+    
SOME_ENUM_VALUE

+{{% /choosable %}}
+
+{{% choosable language python %}}
+
SOME_ENUM_VALUE

+    
SOME_ENUM_VALUE

+{{% /choosable %}}
+
 
 
Package Details

 

diff --git a/pkg/codegen/internal/test/testdata/simple-resource-schema/schema.json b/pkg/codegen/internal/test/testdata/simple-resource-schema/schema.json
index 199ddf9ee..1f86638a4 100644
--- a/pkg/codegen/internal/test/testdata/simple-resource-schema/schema.json
+++ b/pkg/codegen/internal/test/testdata/simple-resource-schema/schema.json
@@ -66,6 +66,16 @@
       },
       "type": "object"
     },
+    "example::EnumOverlay": {
+      "type": "string",
+      "enum": [
+        {
+          "name": "SomeEnumValue",
+          "value": "SOME_ENUM_VALUE"
+        }
+      ],
+      "isOverlay": true
+    },
     "example::ConfigMapOverlay": {
       "isOverlay": true,
       "properties": {
@@ -128,11 +138,17 @@
       "properties": {
         "foo": {
           "$ref": "#/types/example::ConfigMapOverlay"
+        },
+        "bar": {
+          "$ref": "#/types/example::EnumOverlay"
         }
       },
       "inputProperties": {
         "foo": {
           "$ref": "#/types/example::ConfigMapOverlay"
+        },
+        "bar": {
+          "$ref": "#/types/example::EnumOverlay"
         }
       },
       "type": "object"
diff --git a/pkg/codegen/nodejs/gen.go b/pkg/codegen/nodejs/gen.go
index 4f51b8ae7..045890b4d 100644
--- a/pkg/codegen/nodejs/gen.go
+++ b/pkg/codegen/nodejs/gen.go
@@ -2200,9 +2200,11 @@ func generateModuleContextMap(tool string, pkg *schema.Package, extraFiles map[s
 		case *schema.ObjectType:
 			types.types = append(types.types, typ)
 		case *schema.EnumType:
-			info.ContainsEnums = true
-			mod := getModFromToken(typ.Token)
-			mod.enums = append(mod.enums, typ)
+			if !typ.IsOverlay {
+				info.ContainsEnums = true
+				mod := getModFromToken(typ.Token)
+				mod.enums = append(mod.enums, typ)
+			}
 		default:
 			continue
 		}
diff --git a/pkg/codegen/python/gen.go b/pkg/codegen/python/gen.go
index 901c46a5c..b396a3661 100644
--- a/pkg/codegen/python/gen.go
+++ b/pkg/codegen/python/gen.go
@@ -2722,8 +2722,10 @@ func generateModuleContextMap(tool string, pkg *schema.Package, info PackageInfo
 				mod.types = append(mod.types, typ)
 			}
 		case *schema.EnumType:
-			mod := getModFromToken(typ.Token, pkg)
-			mod.enums = append(mod.enums, typ)
+			if !typ.IsOverlay {
+				mod := getModFromToken(typ.Token, pkg)
+				mod.enums = append(mod.enums, typ)
+			}
 		default:
 			continue
 		}
diff --git a/pkg/codegen/schema/pulumi.json b/pkg/codegen/schema/pulumi.json
index 6dabe48b6..ee4fd76e7 100644
--- a/pkg/codegen/schema/pulumi.json
+++ b/pkg/codegen/schema/pulumi.json
@@ -311,7 +311,7 @@
                     "required": ["environment"]
                 },
                 "deprecationMessage": {
-                    "description": "Indicates whether or not the property is deprecated",
+                    "description": "Indicates whether the property is deprecated",
                     "type": "string"
                 },
                 "language": {
@@ -340,6 +340,10 @@
                 "language": {
                     "description": "Additional language-specific data about the type.",
                     "type": "object"
+                },
+                "isOverlay": {
+                    "description": "Indicates that the implementation of the type should not be generated from the schema, and is instead provided out-of-band by the package author",
+                    "type": "boolean"
                 }
             },
             "oneOf": [
@@ -409,7 +413,7 @@
                                 "type": ["boolean", "integer", "number", "string"]
                             },
                             "deprecationMessage": {
-                                "description": "Indicates whether or not the value is deprecated.",
+                                "description": "Indicates whether the value is deprecated.",
                                 "type": "string"
                             }
                         },
@@ -472,11 +476,11 @@
                     }
                 },
                 "deprecationMessage": {
-                    "description": "Indicates whether or not the resource is deprecated",
+                    "description": "Indicates whether the resource is deprecated",
                     "type": "string"
                 },
                 "isComponent": {
-                    "description": "Indicates whether or not the resource is a component.",
+                    "description": "Indicates whether the resource is a component.",
                     "type": "boolean"
                 },
                 "methods": {
@@ -485,6 +489,10 @@
                     "additionalProperties": {
                         "type": "string"
                     }
+                },
+                "isOverlay": {
+                    "description": "Indicates that the implementation of the resource should not be generated from the schema, and is instead provided out-of-band by the package author",
+                    "type": "boolean"
                 }
             }
         },
@@ -506,12 +514,16 @@
                     "$ref": "#/$defs/objectTypeSpec"
                 },
                 "deprecationMessage": {
-                    "description": "Indicates whether or not the function is deprecated",
+                    "description": "Indicates whether the function is deprecated",
                     "type": "string"
                 },
                 "language": {
                     "description": "Additional language-specific data about the function.",
                     "type": "object"
+                },
+                "isOverlay": {
+                    "description": "Indicates that the implementation of the function should not be generated from the schema, and is instead provided out-of-band by the package author",
+                    "type": "boolean"
                 }
             }
         }
diff --git a/pkg/codegen/schema/schema.go b/pkg/codegen/schema/schema.go
index 4f9d9101a..2f3b38c59 100644
--- a/pkg/codegen/schema/schema.go
+++ b/pkg/codegen/schema/schema.go
@@ -166,6 +166,10 @@ type EnumType struct {
 	Elements []*Enum
 	// ElementType is the underlying type for the enum.
 	ElementType Type
+
+	// IsOverlay indicates whether the type is an overlay provided by the package. Overlay code is generated by the
+	// package rather than using the core Pulumi codegen libraries.
+	IsOverlay bool
 }
 
 // Enum contains information about an enum.
@@ -968,8 +972,8 @@ func (pkg *Package) MarshalYAML() ([]byte, error) {
 	return b.Bytes(), nil
 }
 
-func (pkg *Package) marshalObjectData(
-	comment string, properties []*Property, language map[string]interface{}, plain bool) (ObjectTypeSpec, error) {
+func (pkg *Package) marshalObjectData(comment string, properties []*Property, language map[string]interface{},
+	plain, isOverlay bool) (ObjectTypeSpec, error) {
 
 	required, props, err := pkg.marshalProperties(properties, plain)
 	if err != nil {
@@ -987,11 +991,12 @@ func (pkg *Package) marshalObjectData(
 		Type:        "object",
 		Required:    required,
 		Language:    lang,
+		IsOverlay:   isOverlay,
 	}, nil
 }
 
 func (pkg *Package) marshalObject(t *ObjectType, plain bool) (ComplexTypeSpec, error) {
-	data, err := pkg.marshalObjectData(t.Comment, t.Properties, t.Language, plain)
+	data, err := pkg.marshalObjectData(t.Comment, t.Properties, t.Language, plain, t.IsOverlay)
 	if err != nil {
 		return ComplexTypeSpec{}, err
 	}
@@ -1010,17 +1015,16 @@ func (pkg *Package) marshalEnum(t *EnumType) ComplexTypeSpec {
 	}
 
 	return ComplexTypeSpec{
-		ObjectTypeSpec: ObjectTypeSpec{Type: pkg.marshalType(t.ElementType, false).Type},
+		ObjectTypeSpec: ObjectTypeSpec{Type: pkg.marshalType(t.ElementType, false).Type, IsOverlay: t.IsOverlay},
 		Enum:           values,
 	}
 }
 
 func (pkg *Package) marshalResource(r *Resource) (ResourceSpec, error) {
-	object, err := pkg.marshalObjectData(r.Comment, r.Properties, r.Language, true)
+	object, err := pkg.marshalObjectData(r.Comment, r.Properties, r.Language, true, r.IsOverlay)
 	if err != nil {
 		return ResourceSpec{}, fmt.Errorf("marshaling properties: %w", err)
 	}
-	object.IsOverlay = r.IsOverlay
 
 	requiredInputs, inputs, err := pkg.marshalProperties(r.InputProperties, false)
 	if err != nil {
@@ -2409,6 +2413,7 @@ func (t *types) bindEnumTypeDetails(enum *EnumType, token string, spec ComplexTy
 	enum.Elements = values
 	enum.ElementType = typ
 	enum.Comment = spec.Description
+	enum.IsOverlay = spec.IsOverlay
 
 	return diags
 }