Add Required resources and schemas

src/index.ts

@@ -6,73 +6,83 @@ export { FunctionRunner, getServer } from './function/function.js';
 
 // Request helpers
 export {
-  getDesiredCompositeResource,
-  getObservedCompositeResource,
+  getContextKey,
+  getCredentials,
   getDesiredComposedResources,
-  getObservedComposedResources,
+  getDesiredCompositeResource,
   getInput,
-  getContextKey,
+  getObservedComposedResources,
+  getObservedCompositeResource,
+  getRequiredResource,
   getRequiredResources,
-  getCredentials,
+  getRequiredSchema,
+  getRequiredSchemas,
 } from './request/request.js';
 
 // Response helpers
 export {
-  to,
+  DEFAULT_TTL,
   fatal,
   normal,
-  warning,
+  requireResource,
+  requireSchema,
+  setContextKey,
   setDesiredComposedResources,
-  setDesiredResources,
-  setDesiredCompositeStatus,
   setDesiredCompositeResource,
-  updateDesiredComposedResources,
-  update,
-  setContextKey,
+  setDesiredCompositeStatus,
+  setDesiredResources,
   setOutput,
-  DEFAULT_TTL,
+  to,
+  update,
+  updateDesiredComposedResources,
+  warning,
 } from './response/response.js';
 
 // Resource utilities
 export {
   asObject,
   asStruct,
-  fromObject,
+  type Composite,
+  type ConnectionDetails,
+  type DesiredComposed,
   fromModel,
-  toObject,
-  newDesiredComposed,
-  mustStructObject,
+  fromObject,
   mustStructJSON,
-  type Composite,
+  mustStructObject,
+  newDesiredComposed,
   type ObservedComposed,
-  type DesiredComposed,
-  type ConnectionDetails,
+  toObject,
 } from './resource/resource.js';
 
 // Runtime utilities
 export {
-  newGrpcServer,
-  startServer,
   getServerCredentials,
+  newGrpcServer,
   type ServerOptions,
+  startServer,
 } from './runtime/runtime.js';
 
 // Protocol buffer types
 export {
+  Capability,
+  Condition,
+  CredentialData,
+  Credentials,
+  FunctionRunnerServiceService,
+  Ready,
+  Requirements,
+  Resource,
+  Resources,
+  ResourceSelector,
+  Result,
   RunFunctionRequest,
   RunFunctionResponse,
-  Resource,
+  Schema,
+  SchemaSelector,
   Severity,
-  Result,
   State,
-  Ready,
-  Target,
   Status,
-  Condition,
-  Resources,
-  Credentials,
-  CredentialData,
-  FunctionRunnerServiceService,
+  Target,
 } from './proto/run_function.js';
 
 export type { Logger } from 'pino';

src/proto/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.
@@ -247,7 +313,7 @@ message Resource {
   // the observed connection details of a composite or composed resource.
   //
   // * A function should set this field in a RunFunctionResponse to indicate the
-  // desired connection details of the XR.
+  // desired connection details of legacy XRs. For modern XRs, this will be ignored.
   //
   // * A function should not set this field in a RunFunctionResponse to indicate
   // the desired connection details of a composed resource. This will be
@@ -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;
-}
+}