Add support for capability detection

Crossplane v2.2 introduces capability advertisement. Crossplane sends
the capabilities it supports in the request metadata, allowing functions
to detect whether the calling Crossplane will honor particular request
or response fields (e.g. schema requirements, conditions).

This commit updates the protos to include the new Capability enum and
RequestMeta.capabilities field, and adds a request.has_capability helper
that checks whether a specific capability is present.

Signed-off-by: Nic Cope <nicc@rk0n.org>

Author: negz

crossplane/function/proto/v1/run_function.proto

@@ -163,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.
@@ -295,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;

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
@@ -145,10 +160,12 @@ 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", "schemas")

crossplane/function/proto/v1/run_function_pb2.pyi

@@ -165,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.
@@ -297,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;