Support composed resource dependencies

[stevendborrelli]

Support composed resource dependencies

Work in progress. Please don't merge. This follows
crossplane/crossplane#7842,
the draft prototype that adds dependencies to the function protocol and has
Crossplane order composed resource creation and deletion from them. The
design is in
crossplane/crossplane#7841.
The proto messages here come from that prototype and aren't upstream yet, so
this can't land before it does.

Description of your changes

This adds SDK support for the dependencies field that #7842 adds to
RunFunctionRequest and RunFunctionResponse, in two layers.

Declaring dependencies directly. The vendored protos are synced with the
prototype's, which adds Dependency, RequiredResourceDependency, the
DependencyLifecycle enum and CAPABILITY_DEPENDENCIES. Along with them:

• response.to carries the request's dependencies forward, the way it carries
  desired state and context, so a function that adds a dependency keeps the ones
  earlier functions declared. It copies them only when the request has them,
  because an unset field means "no opinion" and an empty one means "drop every
  constraint".
• response.add_dependency, response.add_required_resource_dependency and
  response.clear_dependencies, plus request.get_dependencies.

if request.has_capability(req, fnv1.CAPABILITY_DEPENDENCIES):
    response.add_dependency(rsp, "subnet", "vpc")

Recording dependencies from field references. The new
crossplane.function.dependency module records a dependency whenever one
composed resource's field is filled in from another resource. It's meant to
replace provider reference selectors such as vpcIdSelector, which hide the
relationship from Crossplane:

vpc = dependency.named("vpc", VPC)  # typed stand-in; typos fail here

with dependency.composing(req, rsp, "subnet") as c:
    c.update(Subnet(spec={"forProvider": {
        "vpcId": c.external_name(vpc),                        # the real value, or None
        "mapPublicIpOnLaunch": c.ref(vpc.spec.forProvider.enableDnsHostnames),
    }}))
# subnet -> vpc is recorded when the block exits

composing scopes the work to one composed resource, so a reference resolves
to its value as soon as it's read, in a field of any type, and the scope
records the dependency when the block exits.

• The source doesn't exist yet: c.ref returns None, and the field is
  left out. When the block exits, None is stripped from the resource however
  it was written - c.update, resource.update, or a helper that calls it -
  because sending it would clear the field. The dependency means Crossplane
  doesn't create the resource until the source is ready.
• The resource exists but its source is gone: it keeps its current spec
  under whatever the block wrote. If the block didn't compose it at all because
  the value was missing, it's kept rather than deleted. Either way the XR's
  DependencyValuesAvailable condition turns False with reason
  KeptCurrentSpec, naming each kept resource and the value it's waiting for.
  It's returned True otherwise, on every reconcile, because Crossplane keeps
  a condition a function set earlier until it's set again. A condition rather
  than a warning result, because a result becomes an event on every reconcile
  for as long as the value is missing.
• A block that composes nothing declares nothing, so Crossplane isn't told
  about dependencies of a resource it doesn't know.
• Typed values: a resource named with its model returns values as the model
  types them, so c.ref(cluster.status.secrets) is a list of Secret models,
  not of dicts.
• Model fields: the stand-in follows the model's fields, so a typo fails
  where it's written, and a field whose JSON name is a Python keyword (from,
  class) is read by its JSON name.
• No accidental values: truth-testing a stand-in, or calling str() on it,
  raises an error, so code can't branch on a value that doesn't exist yet.

Dependencies order resources only on a Crossplane that advertises
CAPABILITY_DEPENDENCIES. On any other, a resource whose value is missing is
held back by leaving it out of desired state, but nothing waits for a source
to be ready, and nothing orders deletion - that would need Usages, which is
function-sequencer's job.

An earlier revision also offered marker strings resolved in a pass afterwards,
following the TypeScript SDK prototype. Porting Modelplane used the scoped
style throughout, so markers, and the runtime guard that caught unresolved
ones, were removed.

Open questions

• The fallback for an existing resource keeps its whole observed spec under
  the new one. It can also take ownership of fields the provider filled in
  itself. It only happens when a source disappears.
• named("vpc", VPC) is typed as VPC, so strict type checkers warn that
  vpc.status may be None on every read. That would need generated stubs.
• Two functions in one pipeline that both use composing share the
  DependencyValuesAvailable condition type, so the later one's report wins.

Testing

• hatch test: 58 tests pass, 32 of them in tests/test_dependency.py.
• hatch fmt --check passes.
• Checked against real datamodel-codegen models (the Upbound AWS VPC and
  Subnet).
• Modelplane's ordering conversion
  uses both layers: add_dependency for ordering on existence, and
  dependency.composing in compose-inference-cluster, where each cloud's
  backend and ProviderConfig are built from the cluster's status.secrets.
  All 14 of its functions' tests pass against this branch, and its end-to-end
  suite passes on this branch's head, against the #7842 prototype's
  v2.5.0-ordering.2 release. The suite uses an existing cluster, so it
  doesn't exercise the provisioned-cloud paths the port changed, which only
  unit tests cover.

I have:

• Read and followed Crossplane's contribution process.
• Added or updated unit tests for my change.

🤖 Generated with Claude Code