pub fn kube_map<'a, R: KubeReceiver + ?Sized>(
recv: &'a R,
field: &str,
) -> Option<&'a Mapping>Expand description
Read a sub-<field> YAML mapping nested one hop under an arbitrary
&serde_yaml::Value mapping receiver as Option<&serde_yaml::Mapping>
— the value-level two-hop navigation primitive that folds
.get(<field>) → as_mapping into a single helper call. Sub-mapping-
arity peer of the value-level scalar-str kube_str (a23f61d),
scalar-integer kube_u64 (bfbec1d), and sequence-arity kube_seq
(9c74ddb) accessors on the same value-level two-hop navigation axis:
where those three close the string / unsigned-integer / sequence
shape-gates on the nested <field> axis, this accessor closes the
sub-mapping shape-gate on the same axis, so every routed test-side +
production per-nested-mapping sub-block readback (per-HTTPRouteMatch
path: sub-mapping on the Gateway API family, per-programs-entry
placement: sub-mapping on the caixa-mesh M3 fan-out, per-HTTPRoute
per-rule timeouts: / retry: mesh-policy overlay sub-mappings, per-
CiliumNetworkPolicy per-rule authentication: mTLS-overlay sub-
mapping, per-HelmRelease spec.values.<library>: wrap sub-mapping on
the caixa-flux cluster-bundle path) now reaches through the same
one-line dispatch the scalar-str / scalar-integer / sequence arities
already do. The quartet
(kube_str, kube_u64, kube_seq, kube_map) closes the
value-level axis at the four principal K8s apiserver OpenAPI schema
shape arities — string, unsigned-integer, sequence, sub-mapping —
matching the closed shape of the spec/metadata/root-anchored families
one altitude above where each arity already has its named accessor
(kube_spec_str_field / kube_spec_seq_field /
kube_spec_map_field, and the parallel metadata_* / root_*
families).
Returns None on any of the three short-circuit arms folded through
the underlying two-hop composition: the receiver value carries a
YAML type without a get(<field>) navigation surface
(serde_yaml::Value::get returns None on scalar arms — string,
bool, number, null — that expose no per-key lookup), the requested
<field> axis-key is absent from the receiver’s mapping
(serde_yaml::Value::get trailing miss), or the sub-field value is
present but carries a non-mapping YAML type (the trailing
serde_yaml::Value::as_mapping shape-gate short-circuit — a
schema-invalid sub-field type per the K8s apiserver’s OpenAPI schema
but tolerated here as None so the readback stays a total function,
mirroring the sibling kube_str / kube_u64 / kube_seq
posture). The returned &Mapping borrows into the input Value — the
caller decides whether to assert_eq!(_, Some(<expected>)) for a
determinism pin, thread through a nested .get(<K>) on the returned
sub-mapping for a downstream scalar readback, .expect(...) for a
load-bearing sub-block identity, or .is_empty() / .len() for a
cardinality predicate.
The canonical shape 7 test-side per-nested-mapping sub-block
readback sites in caixa-mesh previously carried inline as
the two-line composition
<value>.get(<FIELD>).and_then(|v| v.as_mapping())
...around a one-token semantic payload (the <FIELD> sub-field axis-key
— GATEWAY_API_KEY_PATH on the per-HTTPRouteMatch path: sub-
mapping (two routed matches-per-rule readback sites folding onto
this arity), M3_KEY_PLACEMENT on the per-programs-entry
placement: sub-mapping’s placement_blocks helper,
GATEWAY_API_KEY_TIMEOUTS on the per-rule timeouts: mesh-policy
overlay sub-mapping, GATEWAY_API_KEY_RETRY on the per-rule
retry: overlay sub-mapping, CILIUM_KEY_AUTHENTICATION on the
per-CNP rule authentication: mTLS sub-mapping (two routed
tristate-arm readback sites — the Some(true) required arm and
the explicit Some(false) disabled arm — folding onto this
arity)). The &Value-receiver signature also stays the reachable
call surface for every future caller already holding a nested
&Value bracket (the caixa-flux cluster-bundle
spec.values.<library>: wrap sub-mapping stays out-of-reach today
because its receiver is a lifted &Mapping returned from
kube_spec_map_field rather than a &Value — a peer
Mapping-receiver overload would land on a separate lift, one
altitude down on the mapping-arity axis, if the routed caller
surface ever grows dense enough on that receiver-arm to justify it).
After this lift every routed &Value-receiver consumer folds the
two-line navigation onto kube_map(<value>, <FIELD>) — the two-hop
get → as_mapping walk happens once inside the helper, and the
caller keeps its downstream continuation posture (.get(<K>) on the
returned &Mapping, .expect(...), .is_empty(), .len())
unchanged — the lift closes the navigation surface, not the per-site
downstream posture.
Every future nested <field> sub-mapping readback the M3.x + M4
renderer set materializes (per-:politicas
CiliumClusterwideEnvoyConfig per-policy nested sub-blocks, the
app-operator’s per-Aplicacao materializer’s
spec.placement.<affinity-block> nested affinity sub-mapping, the
future caixa-otel per-Servico per-receivers.<name>: nested
sub-mapping, the future per-:contratos per-edge WIT-attribute
sub-block once the M4 typed per-edge overlay lands) reaches this one
helper by construction. No per-consumer two-hop re-inline; no
coordinated rewrite across every nested-sub-mapping readback on a
future serde_yaml surface rebrand or shape-gate shift.