Merge pull request #193 from negz/schematics

Add support for requesting OpenAPI schemas

Author: negz

crossplane/function/proto/v1/run_function.proto

@@ -90,6 +90,13 @@ message RunFunctionRequest {
   // satisfy the request. This field is only populated when the function uses
   // resources in its requirements.
   map<string, Resources> required_resources = 8;
+
+  // Optional schemas that the function specified in its requirements. The map
+  // key corresponds to the key in a RunFunctionResponse's requirements.schemas
+  // field. If a function requested a schema that could not be found, Crossplane
+  // sets the map key to an empty Schema message to indicate that it attempted
+  // to satisfy the request.
+  map<string, Schema> required_schemas = 9;
 }
 
 // Credentials that a function may use to communicate with an external system.
@@ -156,6 +163,44 @@ message RequestMeta {
   // An opaque string identifying a request. Requests with identical tags will
   // be otherwise identical.
   string tag = 1;
+
+  // Capabilities supported by this version of Crossplane. Functions may use
+  // this to determine whether Crossplane will honor certain fields in their
+  // response, or populate certain fields in their request.
+  repeated Capability capabilities = 2;
+}
+
+// Capability indicates that Crossplane supports a particular feature.
+// Functions can check for capabilities to determine whether Crossplane will
+// honor a particular request or response field.
+enum Capability {
+  CAPABILITY_UNSPECIFIED = 0;
+
+  // Crossplane sends capabilities in RequestMeta. If this capability is
+  // present, the function knows that if another capability is absent, it's
+  // because Crossplane doesn't support it (not because Crossplane predates
+  // capability advertisement). Added in Crossplane v2.2.
+  CAPABILITY_CAPABILITIES = 1;
+
+  // Crossplane supports the requirements.resources field. Functions can return
+  // resource requirements and Crossplane will fetch the requested resources and
+  // return them in required_resources. Added in Crossplane v1.15.
+  CAPABILITY_REQUIRED_RESOURCES = 2;
+
+  // Crossplane supports the credentials field. Functions can receive
+  // credentials from secrets specified in the Composition. Added in Crossplane
+  // v1.16.
+  CAPABILITY_CREDENTIALS = 3;
+
+  // Crossplane supports the conditions field. Functions can return status
+  // conditions to be applied to the XR and optionally its claim. Added in
+  // Crossplane v1.17.
+  CAPABILITY_CONDITIONS = 4;
+
+  // Crossplane supports the requirements.schemas field. Functions can request
+  // OpenAPI schemas and Crossplane will return them in required_schemas. Added
+  // in Crossplane v2.2.
+  CAPABILITY_REQUIRED_SCHEMAS = 5;
 }
 
 // Requirements that must be satisfied for a function to run successfully.
@@ -169,6 +214,27 @@ message Requirements {
   // Resources that this function requires. The map key uniquely identifies the
   // group of resources.
   map<string, ResourceSelector> resources = 2;
+
+  // Schemas that this function requires. The map key uniquely identifies the
+  // schema request.
+  map<string, SchemaSelector> schemas = 3;
+}
+
+// SchemaSelector identifies a resource kind whose OpenAPI schema is requested.
+message SchemaSelector {
+  // API version of the resource kind, e.g. "example.org/v1".
+  string api_version = 1;
+
+  // Kind of resource, e.g. "MyResource".
+  string kind = 2;
+}
+
+// Schema represents the OpenAPI schema for a resource kind.
+message Schema {
+  // The OpenAPI v3 schema of the resource kind as unstructured JSON.
+  // For CRDs this is the spec.versions[].schema.openAPIV3Schema field.
+  // Empty if Crossplane could not find a schema for the requested kind.
+  optional google.protobuf.Struct openapi_v3 = 1;
 }
 
 // ResourceSelector selects a group of resources, either by name or by label.
@@ -267,7 +333,7 @@ message Resource {
   // * A function should set this field to READY_TRUE in a RunFunctionResponse
   // to indicate that a desired XR is ready. This overwrites the standard
   // readiness detection that determines the ready state of the composite by the
-  // ready state of the the composed resources.
+  // ready state of the composed resources.
   //
   // Ready is only used for composition. It's ignored by Operations.
   Ready ready = 3;
@@ -367,4 +433,4 @@ enum Status {
   STATUS_CONDITION_TRUE = 2;
 
   STATUS_CONDITION_FALSE = 3;
-}
+}

crossplane/function/proto/v1/run_function_pb2.py

@@ -11,6 +11,15 @@ from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
 
 DESCRIPTOR: _descriptor.FileDescriptor
 
+class Capability(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    CAPABILITY_UNSPECIFIED: _ClassVar[Capability]
+    CAPABILITY_CAPABILITIES: _ClassVar[Capability]
+    CAPABILITY_REQUIRED_RESOURCES: _ClassVar[Capability]
+    CAPABILITY_CREDENTIALS: _ClassVar[Capability]
+    CAPABILITY_CONDITIONS: _ClassVar[Capability]
+    CAPABILITY_REQUIRED_SCHEMAS: _ClassVar[Capability]
+
 class Ready(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     __slots__ = ()
     READY_UNSPECIFIED: _ClassVar[Ready]
@@ -36,6 +45,12 @@ class Status(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
     STATUS_CONDITION_UNKNOWN: _ClassVar[Status]
     STATUS_CONDITION_TRUE: _ClassVar[Status]
     STATUS_CONDITION_FALSE: _ClassVar[Status]
+CAPABILITY_UNSPECIFIED: Capability
+CAPABILITY_CAPABILITIES: Capability
+CAPABILITY_REQUIRED_RESOURCES: Capability
+CAPABILITY_CREDENTIALS: Capability
+CAPABILITY_CONDITIONS: Capability
+CAPABILITY_REQUIRED_SCHEMAS: Capability
 READY_UNSPECIFIED: Ready
 READY_TRUE: Ready
 READY_FALSE: Ready
@@ -52,7 +67,7 @@ STATUS_CONDITION_TRUE: Status
 STATUS_CONDITION_FALSE: Status
 
 class RunFunctionRequest(_message.Message):
-    __slots__ = ("meta", "observed", "desired", "input", "context", "extra_resources", "credentials", "required_resources")
+    __slots__ = ("meta", "observed", "desired", "input", "context", "extra_resources", "credentials", "required_resources", "required_schemas")
     class ExtraResourcesEntry(_message.Message):
         __slots__ = ("key", "value")
         KEY_FIELD_NUMBER: _ClassVar[int]
@@ -74,6 +89,13 @@ class RunFunctionRequest(_message.Message):
         key: str
         value: Resources
         def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[Resources, _Mapping]] = ...) -> None: ...
+    class RequiredSchemasEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: Schema
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[Schema, _Mapping]] = ...) -> None: ...
     META_FIELD_NUMBER: _ClassVar[int]
     OBSERVED_FIELD_NUMBER: _ClassVar[int]
     DESIRED_FIELD_NUMBER: _ClassVar[int]
@@ -82,6 +104,7 @@ class RunFunctionRequest(_message.Message):
     EXTRA_RESOURCES_FIELD_NUMBER: _ClassVar[int]
     CREDENTIALS_FIELD_NUMBER: _ClassVar[int]
     REQUIRED_RESOURCES_FIELD_NUMBER: _ClassVar[int]
+    REQUIRED_SCHEMAS_FIELD_NUMBER: _ClassVar[int]
     meta: RequestMeta
     observed: State
     desired: State
@@ -90,7 +113,8 @@ class RunFunctionRequest(_message.Message):
     extra_resources: _containers.MessageMap[str, Resources]
     credentials: _containers.MessageMap[str, Credentials]
     required_resources: _containers.MessageMap[str, Resources]
-    def __init__(self, meta: _Optional[_Union[RequestMeta, _Mapping]] = ..., observed: _Optional[_Union[State, _Mapping]] = ..., desired: _Optional[_Union[State, _Mapping]] = ..., input: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., context: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., extra_resources: _Optional[_Mapping[str, Resources]] = ..., credentials: _Optional[_Mapping[str, Credentials]] = ..., required_resources: _Optional[_Mapping[str, Resources]] = ...) -> None: ...
+    required_schemas: _containers.MessageMap[str, Schema]
+    def __init__(self, meta: _Optional[_Union[RequestMeta, _Mapping]] = ..., observed: _Optional[_Union[State, _Mapping]] = ..., desired: _Optional[_Union[State, _Mapping]] = ..., input: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., context: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., extra_resources: _Optional[_Mapping[str, Resources]] = ..., credentials: _Optional[_Mapping[str, Credentials]] = ..., required_resources: _Optional[_Mapping[str, Resources]] = ..., required_schemas: _Optional[_Mapping[str, Schema]] = ...) -> None: ...
 
 class Credentials(_message.Message):
     __slots__ = ("credential_data",)
@@ -136,13 +160,15 @@ class RunFunctionResponse(_message.Message):
     def __init__(self, meta: _Optional[_Union[ResponseMeta, _Mapping]] = ..., desired: _Optional[_Union[State, _Mapping]] = ..., results: _Optional[_Iterable[_Union[Result, _Mapping]]] = ..., context: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., requirements: _Optional[_Union[Requirements, _Mapping]] = ..., conditions: _Optional[_Iterable[_Union[Condition, _Mapping]]] = ..., output: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ...) -> None: ...
 
 class RequestMeta(_message.Message):
-    __slots__ = ("tag",)
+    __slots__ = ("tag", "capabilities")
     TAG_FIELD_NUMBER: _ClassVar[int]
+    CAPABILITIES_FIELD_NUMBER: _ClassVar[int]
     tag: str
-    def __init__(self, tag: _Optional[str] = ...) -> None: ...
+    capabilities: _containers.RepeatedScalarFieldContainer[Capability]
+    def __init__(self, tag: _Optional[str] = ..., capabilities: _Optional[_Iterable[_Union[Capability, str]]] = ...) -> None: ...
 
 class Requirements(_message.Message):
-    __slots__ = ("extra_resources", "resources")
+    __slots__ = ("extra_resources", "resources", "schemas")
     class ExtraResourcesEntry(_message.Message):
         __slots__ = ("key", "value")
         KEY_FIELD_NUMBER: _ClassVar[int]
@@ -157,11 +183,34 @@ class Requirements(_message.Message):
         key: str
         value: ResourceSelector
         def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[ResourceSelector, _Mapping]] = ...) -> None: ...
+    class SchemasEntry(_message.Message):
+        __slots__ = ("key", "value")
+        KEY_FIELD_NUMBER: _ClassVar[int]
+        VALUE_FIELD_NUMBER: _ClassVar[int]
+        key: str
+        value: SchemaSelector
+        def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[SchemaSelector, _Mapping]] = ...) -> None: ...
     EXTRA_RESOURCES_FIELD_NUMBER: _ClassVar[int]
     RESOURCES_FIELD_NUMBER: _ClassVar[int]
+    SCHEMAS_FIELD_NUMBER: _ClassVar[int]
     extra_resources: _containers.MessageMap[str, ResourceSelector]
     resources: _containers.MessageMap[str, ResourceSelector]
-    def __init__(self, extra_resources: _Optional[_Mapping[str, ResourceSelector]] = ..., resources: _Optional[_Mapping[str, ResourceSelector]] = ...) -> None: ...
+    schemas: _containers.MessageMap[str, SchemaSelector]
+    def __init__(self, extra_resources: _Optional[_Mapping[str, ResourceSelector]] = ..., resources: _Optional[_Mapping[str, ResourceSelector]] = ..., schemas: _Optional[_Mapping[str, SchemaSelector]] = ...) -> None: ...
+
+class SchemaSelector(_message.Message):
+    __slots__ = ("api_version", "kind")
+    API_VERSION_FIELD_NUMBER: _ClassVar[int]
+    KIND_FIELD_NUMBER: _ClassVar[int]
+    api_version: str
+    kind: str
+    def __init__(self, api_version: _Optional[str] = ..., kind: _Optional[str] = ...) -> None: ...
+
+class Schema(_message.Message):
+    __slots__ = ("openapi_v3",)
+    OPENAPI_V3_FIELD_NUMBER: _ClassVar[int]
+    openapi_v3: _struct_pb2.Struct
+    def __init__(self, openapi_v3: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ...) -> None: ...
 
 class ResourceSelector(_message.Message):
     __slots__ = ("api_version", "kind", "match_name", "match_labels", "namespace")

crossplane/function/proto/v1/run_function_pb2.pyi

@@ -92,6 +92,13 @@ message RunFunctionRequest {
   // satisfy the request. This field is only populated when the function uses
   // resources in its requirements.
   map<string, Resources> required_resources = 8;
+
+  // Optional schemas that the function specified in its requirements. The map
+  // key corresponds to the key in a RunFunctionResponse's requirements.schemas
+  // field. If a function requested a schema that could not be found, Crossplane
+  // sets the map key to an empty Schema message to indicate that it attempted
+  // to satisfy the request.
+  map<string, Schema> required_schemas = 9;
 }
 
 // Credentials that a function may use to communicate with an external system.
@@ -158,6 +165,44 @@ message RequestMeta {
   // An opaque string identifying a request. Requests with identical tags will
   // be otherwise identical.
   string tag = 1;
+
+  // Capabilities supported by this version of Crossplane. Functions may use
+  // this to determine whether Crossplane will honor certain fields in their
+  // response, or populate certain fields in their request.
+  repeated Capability capabilities = 2;
+}
+
+// Capability indicates that Crossplane supports a particular feature.
+// Functions can check for capabilities to determine whether Crossplane will
+// honor a particular request or response field.
+enum Capability {
+  CAPABILITY_UNSPECIFIED = 0;
+
+  // Crossplane sends capabilities in RequestMeta. If this capability is
+  // present, the function knows that if another capability is absent, it's
+  // because Crossplane doesn't support it (not because Crossplane predates
+  // capability advertisement). Added in Crossplane v2.2.
+  CAPABILITY_CAPABILITIES = 1;
+
+  // Crossplane supports the requirements.resources field. Functions can return
+  // resource requirements and Crossplane will fetch the requested resources and
+  // return them in required_resources. Added in Crossplane v1.15.
+  CAPABILITY_REQUIRED_RESOURCES = 2;
+
+  // Crossplane supports the credentials field. Functions can receive
+  // credentials from secrets specified in the Composition. Added in Crossplane
+  // v1.16.
+  CAPABILITY_CREDENTIALS = 3;
+
+  // Crossplane supports the conditions field. Functions can return status
+  // conditions to be applied to the XR and optionally its claim. Added in
+  // Crossplane v1.17.
+  CAPABILITY_CONDITIONS = 4;
+
+  // Crossplane supports the requirements.schemas field. Functions can request
+  // OpenAPI schemas and Crossplane will return them in required_schemas. Added
+  // in Crossplane v2.2.
+  CAPABILITY_REQUIRED_SCHEMAS = 5;
 }
 
 // Requirements that must be satisfied for a function to run successfully.
@@ -171,6 +216,27 @@ message Requirements {
   // Resources that this function requires. The map key uniquely identifies the
   // group of resources.
   map<string, ResourceSelector> resources = 2;
+
+  // Schemas that this function requires. The map key uniquely identifies the
+  // schema request.
+  map<string, SchemaSelector> schemas = 3;
+}
+
+// SchemaSelector identifies a resource kind whose OpenAPI schema is requested.
+message SchemaSelector {
+  // API version of the resource kind, e.g. "example.org/v1".
+  string api_version = 1;
+
+  // Kind of resource, e.g. "MyResource".
+  string kind = 2;
+}
+
+// Schema represents the OpenAPI schema for a resource kind.
+message Schema {
+  // The OpenAPI v3 schema of the resource kind as unstructured JSON.
+  // For CRDs this is the spec.versions[].schema.openAPIV3Schema field.
+  // Empty if Crossplane could not find a schema for the requested kind.
+  optional google.protobuf.Struct openapi_v3 = 1;
 }
 
 // ResourceSelector selects a group of resources, either by name or by label.
@@ -269,7 +335,7 @@ message Resource {
   // * A function should set this field to READY_TRUE in a RunFunctionResponse
   // to indicate that a desired XR is ready. This overwrites the standard
   // readiness detection that determines the ready state of the composite by the
-  // ready state of the the composed resources.
+  // ready state of the composed resources.
   //
   // Ready is only used for composition. It's ignored by Operations.
   Ready ready = 3;