Add advertises_capabilities and has_capability helpers

Functions need to know whether Crossplane will honor particular request
or response fields, like schema requirements. Crossplane v2.2 and later
advertise their capabilities in the request metadata, but older versions
don't advertise capabilities at all.

This commit adds two helpers. advertises_capabilities checks whether the
calling Crossplane advertises its capabilities. has_capability checks
whether a specific capability is present. Functions should check
advertises_capabilities first, since has_capability returns False both
when a capability is absent and when Crossplane predates capability
advertisement.

Signed-off-by: Nic Cope <[email protected]>

Author: negz

crossplane/function/request.py

@@ -133,6 +133,29 @@ def get_credentials(req: fnv1.RunFunctionRequest, name: str) -> Credentials:
     return empty
 
 
+def advertises_capabilities(req: fnv1.RunFunctionRequest) -> bool:
+    """Check whether Crossplane advertises its capabilities.
+
+    Args:
+        req: The RunFunctionRequest to check.
+
+    Returns:
+        True if Crossplane advertises its capabilities.
+
+    Crossplane v2.2 and later advertise their capabilities in the request
+    metadata. If this returns False, the calling Crossplane predates capability
+    advertisement and has_capability will always return False, even for features
+    the older Crossplane does support.
+
+        if not request.advertises_capabilities(req):
+            # Pre-v2.2 Crossplane, capabilities are unknown.
+            ...
+        elif request.has_capability(req, fnv1.CAPABILITY_REQUIRED_SCHEMAS):
+            response.require_schema(rsp, "xr", xr_api_version, xr_kind)
+    """
+    return fnv1.CAPABILITY_CAPABILITIES in req.meta.capabilities
+
+
 def has_capability(
     req: fnv1.RunFunctionRequest,
     cap: fnv1.Capability.ValueType,
@@ -150,9 +173,9 @@ def has_capability(
     this to determine whether Crossplane will honor certain fields in their
     response, or populate certain fields in their request.
 
-    If CAPABILITY_CAPABILITIES is absent, the calling Crossplane predates
-    capability advertisement (pre-v2.2). In this case has_capability always
-    returns False, even for features the older Crossplane does support.
+    Use advertises_capabilities to check whether Crossplane advertises its
+    capabilities at all. If it doesn't, has_capability always returns False even
+    for features the older Crossplane does support.
 
         if request.has_capability(req, fnv1.CAPABILITY_REQUIRED_SCHEMAS):
             response.require_schema(rsp, "xr", xr_api_version, xr_kind)

tests/test_request.py

@@ -264,6 +264,37 @@ class TestCase:
                 dataclasses.asdict(case.want), dataclasses.asdict(got), case.reason
             )
 
+    def test_advertises_capabilities(self) -> None:
+        @dataclasses.dataclass
+        class TestCase:
+            reason: str
+            req: fnv1.RunFunctionRequest
+            want: bool
+
+        cases = [
+            TestCase(
+                reason="Should return False when no capabilities are advertised.",
+                req=fnv1.RunFunctionRequest(),
+                want=False,
+            ),
+            TestCase(
+                reason="Should return True when CAPABILITY_CAPABILITIES is present.",
+                req=fnv1.RunFunctionRequest(
+                    meta=fnv1.RequestMeta(
+                        capabilities=[
+                            fnv1.CAPABILITY_CAPABILITIES,
+                            fnv1.CAPABILITY_REQUIRED_SCHEMAS,
+                        ],
+                    ),
+                ),
+                want=True,
+            ),
+        ]
+
+        for case in cases:
+            got = request.advertises_capabilities(case.req)
+            self.assertEqual(case.want, got, case.reason)
+
     def test_has_capability(self) -> None:
         @dataclasses.dataclass
         class TestCase: