Collect the inputs a Fabric names, and refuse to render without them

The Fabric asks Crossplane for each entry in spec.requires by kind, name and
namespace, layers what comes back, and renders per device. A Fabric with no
requires takes the released path unchanged: one document handed to every device.

The gate is the point. Requirements are answered on the *next* reconcile, so the
first one always arrives with nothing at all -- rendering then would push a
fabric short of its inputs, as a full config replacement, with no Delete. So an
unresolved requires composes nothing.

The proto settles a question this design could not answer before: "not yet" and
"never" are distinguishable. Crossplane sends an empty Resources for a
requirement it looked for and did not find, and omits the key entirely when it
has not fetched yet. Both gate, but they are different states and the condition
says which -- WaitingForInputs against InputsMissing.

Two refusals rather than a silent render, both because the alternative reaches a
device. A matchHostnames pattern that matches nothing is fatal: a pattern is
silent about matching nothing, so it cannot be allowed to be. A Secret named in
requires is fatal too -- it is in the enum so the mechanism can land without a
schema change, but rendering a fabric whose credentials are quietly absent is
worse than not rendering.

Values replaced by a later input are reported as a warning, never an error: the
order is declared by whoever wrote requires, so an override is intentional.

First tests in this repo to drive RunFunction. They cover both gate states, both
refusals, that resolved inputs compose devices, that each input kind reconciles
and reports its own keys, and that a fabric with only spec.design still composes
-- the last one guarding the refactor that put both paths through
render_structured_configs, since v0.1.6 is published and netclab-xp pins it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mbakalarski

function/fn.py

@@ -29,9 +29,17 @@
 from .engine import (
     InputValidationError,
     device_roles_from_design,
-    render_fabric_design,
+    hostnames_from_design,
+    render_structured_configs,
+)
+from .kinds import (
+    KINDS,
+    Input,
+    hosts_in_blocks,
+    overwrites,
+    resolve,
+    unmatched_patterns,
 )
-from .kinds import KINDS, hosts_in_blocks
 
 API_VERSION = "avd.netclab.dev/v1alpha1"
 
@@ -142,12 +150,24 @@ def _reconcile_fabric(
         namespace = meta.get("namespace", "default")
         xr_name = meta.get("name") or (fabric_name or "fabric").lower()
 
-        if not fabric_name or not design:
-            response.fatal(rsp, "spec.fabricName and spec.design are required")
+        requires = spec.get("requires") or []
+        if not fabric_name or not (design or requires):
+            response.fatal(rsp, "spec.fabricName and spec.design or spec.requires are required")
             return
 
+        if requires:
+            all_inputs = self._collect(req, rsp, observed, requires, design, fabric_name)
+            if all_inputs is None:
+                return  # gated -- _collect reported why
+        else:
+            # The released path: one fabric-wide document handed to every device,
+            # with AVD resolving roles from the node-type blocks.
+            document = dict(design)
+            document["fabric_name"] = fabric_name
+            all_inputs = {host: document for host in hostnames_from_design(document)}
+
         try:
-            structured_configs = render_fabric_design(design, fabric_name)
+            structured_configs = render_structured_configs(all_inputs)
         except InputValidationError as err:
             resource.update_status(
                 rsp.desired.composite,
@@ -171,7 +191,12 @@ def _reconcile_fabric(
             "urlTemplate", "https://{hostname}.{namespace}.svc/command-api"
         )
 
-        roles = device_roles_from_design(design)
+        # Roles come from each device's own view: with inputs, a leaf in DC1 sees
+        # DC1's node-type block and nothing of DC2's.
+        roles = {
+            host: device_roles_from_design(hostvars).get(host) or hostvars.get("type", "")
+            for host, hostvars in all_inputs.items()
+        }
         observed_devices = req.observed.resources  # keyed by composition-resource-name (hostname)
         devices = []
         for hostname, structured_config in structured_configs.items():
@@ -227,6 +252,139 @@ def _reconcile_fabric(
             rsp, f"Composed {len(structured_configs)} Device(s) for fabric {fabric_name}"
         )
 
+    # -- Collecting the inputs a Fabric names ---------------------------------
+
+    def _collect(  # noqa: PLR0913
+        self,
+        req: fnv1.RunFunctionRequest,
+        rsp: fnv1.RunFunctionResponse,
+        observed: dict,
+        requires: list[dict],
+        design: dict,
+        fabric_name: str,
+    ) -> dict[str, dict] | None:
+        """Ask Crossplane for the named inputs; layer them once they arrive.
+
+        Returns per-device inputs, or ``None`` when the fabric must not render --
+        the gate. That gate is not only a guard against a slow operator:
+        requirements are answered on the *next* reconcile, so the first one
+        always arrives with nothing at all, and rendering then would push a
+        fabric short of its inputs as a full config replacement.
+        """
+        namespace = (observed.get("metadata") or {}).get("namespace", "default")
+
+        # State the requirements on every reconcile. Crossplane fetches what the
+        # latest response asked for, so leaving them out once drops the inputs.
+        keys: list[tuple[str, dict]] = []
+        for index, entry in enumerate(requires):
+            kind = entry["kind"]
+            key = f"{index:03d}-{kind.lower()}-{entry['name']}"
+            keys.append((key, entry))
+            response.require_resources(
+                rsp,
+                name=key,
+                api_version="v1" if kind == "Secret" else API_VERSION,
+                kind=kind,
+                match_name=entry["name"],
+                namespace=entry.get("namespace", namespace),
+            )
+
+        pending: list[str] = []
+        absent: list[str] = []
+        inputs: list[Input] = []
+        for key, entry in keys:
+            named = f"{entry['kind']}/{entry.get('namespace', namespace)}/{entry['name']}"
+            if entry["kind"] == "Secret":
+                # In the API from the first version so the mechanism can land
+                # without a schema change, but not implemented. Refuse rather
+                # than render a fabric whose credentials are silently absent.
+                response.fatal(rsp, f"Secret inputs are not implemented yet: {named}")
+                return None
+            if key not in req.required_resources:
+                pending.append(named)
+                continue
+            items = req.required_resources[key].items
+            if not items:
+                # Crossplane looked and found nothing. The proto distinguishes
+                # this from "not fetched yet" by sending an empty Resources, and
+                # that is what lets a Fabric tell "waiting" from "missing" --
+                # the one thing this design was previously unable to do.
+                absent.append(named)
+                continue
+            inputs.append(
+                Input.from_xr(_normalize_numbers(resource.struct_to_dict(items[0].resource)))
+            )
+
+        if pending or absent:
+            detail = []
+            if absent:
+                detail.append(f"not found: {', '.join(absent)}")
+            if pending:
+                detail.append(f"not fetched yet: {', '.join(pending)}")
+            message = "; ".join(detail)
+            response.set_conditions(
+                rsp,
+                resource.Condition(
+                    typ="InputsResolved",
+                    status="False",
+                    reason="InputsMissing" if absent else "WaitingForInputs",
+                    message=message[:400],
+                ),
+            )
+            resource.update_status(
+                rsp.desired.composite,
+                {"fabricName": fabric_name, "validation": {"ok": False, "message": message}},
+            )
+            # Missing is a real problem; not-fetched-yet is the normal first pass.
+            report = response.warning if absent else response.normal
+            report(rsp, f"fabric {fabric_name} is waiting on inputs -- {message}")
+            return None
+
+        # The Fabric's own design is the first input: fabric-wide, seen by every
+        # device, and declaring whatever devices its own blocks name so a Fabric
+        # that carries both a design and a requires list still has its devices.
+        document = dict(design)
+        document["fabric_name"] = fabric_name
+        inputs.insert(
+            0,
+            Input(
+                name="fabric",
+                kind="Settings",
+                design=document,
+                all_devices=True,
+                declares=sorted(hosts_in_blocks(document)),
+            ),
+        )
+
+        if stray := unmatched_patterns(inputs):
+            listed = ", ".join(f"{name}: {pattern!r}" for name, pattern in stray)
+            response.fatal(
+                rsp,
+                f"appliesTo.matchHostnames matched no device ({listed}) -- "
+                f"a pattern that matches nothing is silent, so it is refused",
+            )
+            return None
+
+        if replaced := overwrites(inputs):
+            shown = ", ".join(f"{key} on {host} ({first} -> {second})"
+                              for host, key, first, second in replaced[:5])
+            response.warning(
+                rsp,
+                f"{len(replaced)} value(s) replaced by a later input: {shown}"
+                + (" ..." if len(replaced) > 5 else ""),
+            )
+
+        response.set_conditions(
+            rsp,
+            resource.Condition(
+                typ="InputsResolved",
+                status="True",
+                reason="AllInputsResolved",
+                message=f"{len(inputs)} input(s)",
+            ),
+        )
+        return resolve(inputs)
+
     # -- Device: validate + render one device's config -----------------------
 
     def _reconcile_device(

tests/test_fabric_collect.py

@@ -0,0 +1,181 @@
+"""A Fabric collects the inputs it names, and refuses to render without them.
+
+Offline -- drives RunFunction directly, with no cluster and no Crossplane. The
+gate is the most safety-critical piece in the collect path: requirements are
+answered on the *next* reconcile, so the first one always arrives with nothing,
+and a fabric rendered short of its inputs would be pushed to devices as a full
+config replacement.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from crossplane.function import resource
+from crossplane.function.proto.v1 import run_function_pb2 as fnv1
+
+from function.fn import FunctionRunner
+
+API = "avd.netclab.dev/v1alpha1"
+
+
+def _run(req: fnv1.RunFunctionRequest) -> fnv1.RunFunctionResponse:
+    return asyncio.run(FunctionRunner().RunFunction(req, None))
+
+
+def _fabric(requires: list[dict], design: dict | None = None) -> dict:
+    return {
+        "apiVersion": API,
+        "kind": "Fabric",
+        "metadata": {"name": "fabric", "namespace": "avd"},
+        "spec": {"fabricName": "FABRIC", "design": design or {}, "requires": requires},
+    }
+
+
+def _input_xr(kind: str, name: str, spec: dict) -> dict:
+    return {
+        "apiVersion": API,
+        "kind": kind,
+        "metadata": {"name": name, "namespace": "avd"},
+        "spec": spec,
+    }
+
+
+def _request(xr: dict, required: dict[str, list[dict]] | None = None) -> fnv1.RunFunctionRequest:
+    req = fnv1.RunFunctionRequest()
+    req.observed.composite.resource.CopyFrom(resource.dict_to_struct(xr))
+    for key, objects in (required or {}).items():
+        # An empty list is Crossplane saying "I looked and found nothing", which
+        # the proto distinguishes from a key that is absent entirely.
+        entry = req.required_resources[key]
+        for obj in objects:
+            entry.items.add().resource.CopyFrom(resource.dict_to_struct(obj))
+    return req
+
+
+def _condition(rsp: fnv1.RunFunctionResponse, typ: str):
+    return next((c for c in rsp.conditions if c.type == typ), None)
+
+
+# A spine rather than a leaf, only because a leaf defaults to being a VTEP and
+# would drag in the VXLAN pools -- this fixture is about the collect path, not
+# about exercising AVD.
+SPINES = _input_xr(
+    "NodeSet",
+    "spines",
+    {
+        # `type` rides in the same input: AVD needs it (or default_node_types)
+        # to know what the device is, and it applies to whoever sees this input.
+        "design": {
+            "type": "spine",
+            "spine": {
+                "defaults": {"loopback_ipv4_pool": "10.255.0.0/27"},
+                "nodes": [{"name": "spine1", "id": 1, "bgp_as": 65100}],
+            },
+        }
+    },
+)
+
+
+def test_first_reconcile_asks_and_renders_nothing() -> None:
+    """Requirements are answered next time round, so the first pass is empty.
+
+    This is the case the gate exists for: not a slow operator, but the protocol.
+    """
+    rsp = _run(_request(_fabric([{"kind": "NodeSet", "name": "spines"}])))
+
+    assert set(rsp.requirements.resources) == {"000-nodeset-spines"}
+    selector = rsp.requirements.resources["000-nodeset-spines"]
+    assert (selector.kind, selector.match_name, selector.namespace) == ("NodeSet", "spines", "avd")
+
+    assert not rsp.desired.resources, "nothing may be composed before the inputs arrive"
+    condition = _condition(rsp, "InputsResolved")
+    assert condition.reason == "WaitingForInputs"
+
+
+def test_missing_input_is_distinguished_from_not_yet_fetched() -> None:
+    """An empty Resources means Crossplane looked and found nothing."""
+    rsp = _run(
+        _request(
+            _fabric([{"kind": "NodeSet", "name": "spines"}]),
+            required={"000-nodeset-spines": []},
+        )
+    )
+
+    assert not rsp.desired.resources
+    assert _condition(rsp, "InputsResolved").reason == "InputsMissing"
+    assert "not found" in _condition(rsp, "InputsResolved").message
+
+
+def test_resolved_inputs_compose_devices() -> None:
+    rsp = _run(
+        _request(
+            _fabric([{"kind": "NodeSet", "name": "spines"}]),
+            required={"000-nodeset-spines": [SPINES]},
+        )
+    )
+
+    assert _condition(rsp, "InputsResolved").status == fnv1.STATUS_CONDITION_TRUE
+    assert set(rsp.desired.resources) == {"spine1"}
+
+
+def test_design_without_requires_still_composes() -> None:
+    """The released path is untouched: one document, handed to every device.
+
+    Guards the refactor that put both paths through render_structured_configs --
+    v0.1.6 is published and netclab-xp pins it, so this must keep working with no
+    inputs in sight.
+    """
+    rsp = _run(_request(_fabric(requires=[], design=SPINES["spec"]["design"])))
+
+    assert not any(r.severity == fnv1.SEVERITY_FATAL for r in rsp.results)
+    assert set(rsp.desired.resources) == {"spine1"}
+    assert not rsp.requirements.resources, "a fabric with no requires asks for nothing"
+
+
+def test_secret_input_is_refused_until_implemented() -> None:
+    """It is in the enum so the mechanism can land without a schema change.
+
+    Rendering a fabric whose credentials are silently absent would push a config
+    without them, so refusing is the only safe placeholder.
+    """
+    rsp = _run(_request(_fabric([{"kind": "Secret", "name": "creds"}])))
+
+    assert any(r.severity == fnv1.SEVERITY_FATAL for r in rsp.results)
+    assert not rsp.desired.resources
+
+
+def test_pattern_matching_no_device_is_refused() -> None:
+    """A pattern is silent about matching nothing, so it cannot be allowed to."""
+    settings = _input_xr(
+        "Settings",
+        "typo",
+        # The fabric holds only spine1, so this pattern matches nothing.
+        {"design": {"ntp_settings": {}}, "appliesTo": {"matchHostnames": ["leaf.*"]}},
+    )
+    rsp = _run(
+        _request(
+            _fabric(
+                [
+                    {"kind": "NodeSet", "name": "spines"},
+                    {"kind": "Settings", "name": "typo"},
+                ]
+            ),
+            required={"000-nodeset-spines": [SPINES], "001-settings-typo": [settings]},
+        )
+    )
+
+    fatal = [r for r in rsp.results if r.severity == fnv1.SEVERITY_FATAL]
+    assert fatal and "matched no device" in fatal[0].message
+    assert not rsp.desired.resources
+
+
+@pytest.mark.parametrize("kind", ["NodeSet", "NetworkServices", "ConnectedEndpoints", "Settings"])
+def test_input_kinds_reconcile_and_report_their_keys(kind: str) -> None:
+    """Each input reports its own shape on its own object, composing nothing."""
+    rsp = _run(_request(_input_xr(kind, "an-input", {"design": {"ntp_settings": {}, "type": "x"}})))
+
+    assert not any(r.severity == fnv1.SEVERITY_FATAL for r in rsp.results)
+    status = resource.struct_to_dict(rsp.desired.composite.resource).get("status", {})
+    assert status["keys"] == ["ntp_settings", "type"]