Trait MappingExt

Source

pub trait MappingExt {
    // Required methods
    fn insert_str_key(&mut self, key: &str, value: Value) -> Option<Value>;
    fn insert_string<V: Into<String>>(
        &mut self,
        key: &str,
        value: V,
    ) -> Option<Value>;
    fn insert_number<N: Into<Number>>(
        &mut self,
        key: &str,
        value: N,
    ) -> Option<Value>;
    fn insert_mapping(&mut self, key: &str, value: Mapping) -> Option<Value>;
    fn insert_sequence(&mut self, key: &str, value: Vec<Value>) -> Option<Value>;
    fn insert_singleton_mapping_sequence(
        &mut self,
        key: &str,
        value: Mapping,
    ) -> Option<Value>;
    fn entry_str_key(&mut self, key: &str) -> Entry<'_>;
    fn insert_str_key_if_some(
        &mut self,
        key: &str,
        value: Option<&Value>,
    ) -> Option<Value>;
    fn entry_or_default_mapping(&mut self, key: &str) -> Option<&mut Mapping>;
    fn entry_or_default_sequence(
        &mut self,
        key: &str,
    ) -> Option<&mut Vec<Value>>;
}

Expand description

Extension methods on serde_yaml::Mapping that lift the per-key scalar-promotion boilerplate every K8s-artifact-emitter across caixa-mesh, caixa-flux, caixa-helm, and caixa-core::render carries: the canonical mapping.insert(Value::String(key.into()), value) three-liner the schema-key axis of every emitted YAML document tunnels a &'static str key axis-name through.

Five methods form the primitive quintuple — one per non-Null primitive serde_yaml::Value variant the K8s-artifact-emit surface actually reaches for as a leaf payload:

Self::insert_str_key — insert with a &str key and any fully-built serde_yaml::Value. The building block every other renderer helper (yaml_string_mapping, label_selector, kube_resource_skeleton, single_field_overlay) composes on top of.
Self::insert_string — insert with a &str key and an Into<String> value that gets auto-promoted to serde_yaml::Value::String. The string-scalar-valued-field shape every schema-typed apiVersion / kind / metadata.namespace / port.protocol / hostname / path.value axis emission uses — collapses the two-step insert_str_key(K, Value::String(V.into())) boilerplate onto one direct call.
Self::insert_number — insert with a &str key and an Into<serde_yaml::Number> value that gets auto-promoted to serde_yaml::Value::Number. The integer-scalar-valued-field shape every schema-typed port / targetPort / attempts / maxFailures / hostPort axis emission uses — collapses the two-step insert_str_key(K, Value::Number(N.into())) boilerplate onto one direct call.
Self::insert_mapping — insert with a &str key and a serde_yaml::Mapping value that gets auto-promoted to serde_yaml::Value::Mapping. The nested-Mapping-valued-field shape every schema-typed metadata / spec / spec.rules[].path / toPorts[].rules sub-block emission uses — collapses the two-step insert_str_key(K, Value::Mapping(m)) boilerplate onto one direct call.
Self::insert_sequence — insert with a &str key and a Vec<serde_yaml::Value> value that gets auto-promoted to serde_yaml::Value::Sequence. The list-shape-valued-field shape every schema-typed spec.ingress[].fromEndpoints / spec.ingress[].toPorts / spec.hostnames / spec.rules list emission uses — collapses the two-step insert_str_key(K, Value::Sequence(v)) boilerplate onto one direct call.

A sibling method — Self::entry_str_key — closes the entry-API twin of Self::insert_str_key on the same &str → Value::String key-promotion axis: the serde_yaml::Mapping::entry method’s Value parameter demands the same Value::String(<K>.into()) wrapping every fresh-emit site’s insert_str_key call closes, but on the idempotent-upsert axis (where callers compose .or_insert(...) / .or_insert_with(...) / .and_modify(...) / .or_default() on the returned entry handle) rather than the fresh-emit axis. Same key-promotion contract, different downstream API surface — so a future rebrand of the promotion (e.g. to serde_yaml::Value::Tagged under a K8s Server-Side-Apply typed- field-ownership axis) reaches both fresh-emit and upsert sites through one lift.

See each method’s docstring for its compounding rationale.

Required Methods§

Source

fn insert_str_key(&mut self, key: &str, value: Value) -> Option<Value>

Insert (key, value) into self with key promoted to a serde_yaml::Value::String. Returns the prior value at that key, mirroring serde_yaml::Mapping::insert.

The canonical shape ~48 call sites across the caixa-side renderer surface (caixa-mesh per-CiliumNetworkPolicy / Gateway / HTTPRoute construction, caixa-flux per- GitRepository / HelmRelease / Kustomization construction, caixa-helm per-Chart.yaml / values.yaml construction, caixa-core::render per-skeleton construction) previously carried inline as the three-line block mapping.insert(serde_yaml::Value::String(<KEY>.into()), <VALUE>) — three per-call boilerplate axes (serde_yaml:: path re-quote, Value::String(_) promotion, .into() &str → String coercion) around a two-token semantic payload (<KEY>, <VALUE>).

Lifting collapses the boilerplate into one method call the caller reads as intent (mapping.insert_str_key(<KEY>, <VALUE>) — “insert this schema key with this rendered value”) rather than five hand-spelled positional artifacts. The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (MESH-COMPOSITION §III.2 #3), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (§III.2 #5), the M4 cross-cluster fan-out’s per-cluster Service / HTTPRoute backendRefs emission, the future caixa-otel OpenTelemetry-Collector pipeline emitter — gets the canonical key-scalar-promotion for free with one method call, instead of re-inlining the three-line block.

Peer to the sibling render-side helpers on the serde_yaml::Value-construction surface: yaml_string_mapping (string→string mapping), label_selector (K8s LabelSelector shape), kube_resource_skeleton (K8s apiVersion+kind+metadata skeleton), single_field_overlay (Option<T> → single-key overlay). Each closes a distinct axis of the K8s-artifact-emit surface’s “same shape, written N times” duplication; this one closes the per-key insert primitive the other four all compose on top of.

Source

fn insert_string<V: Into<String>>( &mut self, key: &str, value: V, ) -> Option<Value>

Insert (key, Value::String(value.into())) into self — the string-scalar-valued-field emission shape that combines Self::insert_str_key’s &str → Value::String key promotion with an automatic Value::String promotion of an Into<String> value. Returns the prior value at that key, mirroring serde_yaml::Mapping::insert.

The canonical shape ~17 production call sites across the caixa- side renderer surface previously carried inline as the three- line block mapping.insert_str_key(<KEY>, serde_yaml::Value::String(<VALUE>.into() | .clone() | .to_string())) — the two-token semantic payload (<KEY>, <VALUE>) buried under three boilerplate axes (serde_yaml:: path re-quote, Value::String(_) promotion, the .into() | .clone() | .to_string() → String coercion).

Sites lifted:

caixa-mesh’s programs_for_aplicacao per-:membros entry (FLEET_PROGRAMS_KEY_NAME / FLEET_PROGRAMS_KEY_VERSAO / FLEET_PROGRAMS_KEY_APLICACAO);
caixa-mesh’s cilium_network_policies per-toPorts[] port entry (KUBE_KEY_PORT / KUBE_KEY_PROTOCOL) and per-HTTP- rule CILIUM_KEY_PATH L7 predicate;
caixa-mesh’s gateway_routes per-Gateway listener block (GATEWAY_API_KEY_NAME / crate::GATEWAY_API_KEY_HOSTNAME / GATEWAY_API_KEY_PROTOCOL) and spec.gatewayClassName;
caixa-mesh’s gateway_routes per-HTTPRoute parentRefs[] name, per-rule matches[].path.{type,value} prefix-match, and per-rule backendRefs[].name backend-target;
caixa-flux’s programs_yaml_entry per-entry name / namespace axes;
caixa-core kube_resource_skeleton’s apiVersion / kind scalar heads (the two production emit sites the prior Value::String(_.to_string()) inline shape sat at).

Lifting collapses the boilerplate into one method call the caller reads as intent (mapping.insert_string(<KEY>, <VALUE>) — “insert a string-scalar-typed field named KEY with rendered value VALUE”) rather than four hand-spelled positional artifacts. The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-policy string- scalar axes are name / namespace / defaultAction), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (per-spec.selectors[] name / per-spec.gates[] string-typed axes), the M4 cross-cluster fan-out’s per-cluster Service.spec.ports[].name / HTTPRoute.spec.rules[].filters[]. requestHeaderModifier.set[].name string-scalar emission, the future caixa-otel OpenTelemetry-Collector pipelines.traces. receivers[].endpoint string-scalar emission — gets the canonical string-scalar-valued-field shape for free with one method call, instead of re-inlining the three-token Value::String(_.into() | .clone() | .to_string()) block.

Peer to Self::insert_str_key on the sibling any-Value axis — the two together form the “one method call per emission axis” primitive pair the K8s-artifact-emit surface’s “same shape, written N times” duplication (THEORY.md §I.3.5) collapses onto.

Source

fn insert_number<N: Into<Number>>( &mut self, key: &str, value: N, ) -> Option<Value>

Insert (key, Value::Number(value.into())) into self — the integer-scalar-valued-field emission shape that combines Self::insert_str_key’s &str → Value::String key promotion with an automatic serde_yaml::Value::Number promotion of an Into<serde_yaml::Number> value. Returns the prior value at that key, mirroring serde_yaml::Mapping::insert.

The canonical shape 2 production call sites across caixa-mesh previously carried inline as the three-token block mapping.insert_str_key(<KEY>, serde_yaml::Value::Number(<N>.into())) — the two-token semantic payload (<KEY>, <N>) buried under three boilerplate axes (serde_yaml:: path re-quote, Value::Number(_) promotion, the <N>.into() typed-integer → serde_yaml::Number coercion) around a numeric constant or typed field the caller already carries as u16 / u32 / u64.

Sites lifted:

caixa-mesh’s gateway_routes per-Gateway spec.listeners[].port external HTTP listener port (KUBE_KEY_PORT around the lifted crate::GATEWAY_API_DEFAULT_HTTP_LISTENER_PORT u16 const, cd60fde);
caixa-mesh’s gateway_routes per-HTTPRoute.spec.rules[].backendRefs[].port backend-target Servico port (KUBE_KEY_PORT around the crate::AplicacaoSpec-side entrada.port u16 field the :entrada :port typed slot flows through).

Lifting collapses the boilerplate into one method call the caller reads as intent (mapping.insert_number(<KEY>, <N>) — “insert a numeric-scalar-typed field named KEY with the typed integer N”) rather than three hand-spelled positional artifacts. The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-policy integer-scalar axes are the Envoy circuit-breaker maxRequests / maxPendingRequests / maxConnections count fields and the Cilium ratelimit requestPerUnit field, MESH-COMPOSITION §III.2 #3), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (per-spec. selectors[] integer-scored weight fields, §III.2 #5), the M4 cross-cluster fan-out’s per-cluster Service.spec.ports[].{port, targetPort, nodePort} / HTTPRoute.spec.rules[].backendRefs[].{port, weight} integer-scalar emission, the future caixa-otel OpenTelemetry-Collector service.pipelines.traces.receivers[]. grpc.max_recv_msg_size_mib integer-scalar emission — gets the canonical integer-scalar-valued-field shape for free with one method call, instead of re-inlining the three-token Value::Number(_.into()) block.

The Into<serde_yaml::Number> bound accepts every numeric primitive serde_yaml::Number declares From for (i8..=i64, u8..=u64, f32, f64) — the same coverage the two production sites reach through with their u16 port fields and the same coverage every future numeric-scalar emission (the K8s Service.spec.ports[].targetPort IntOrString integer arm, the HTTPRoute.spec.rules[].backendRefs[].weight int32 axis, the Envoy maxRequests uint32 axis) reaches through with matching typed integer fields.

Peer to Self::insert_string on the sibling string-scalar axis and to Self::insert_mapping / Self::insert_sequence on the sibling nested-Mapping / list-shape axes — the five together with Self::insert_str_key form the “one method call per emission axis” primitive quintuple the K8s-artifact-emit surface’s “same shape, written N times” duplication (THEORY.md §I.3.5) collapses onto: insert_str_key for any-Value inserts, insert_string for the string-scalar-valued-field shape, insert_number for the integer-scalar-valued-field shape, insert_mapping for the nested-Mapping-valued-field shape, insert_sequence for the list-shape-valued-field shape.

Source

fn insert_mapping(&mut self, key: &str, value: Mapping) -> Option<Value>

Insert (key, Value::Mapping(value)) into self — the nested-Mapping-valued-field emission shape that combines Self::insert_str_key’s &str → Value::String key promotion with an automatic serde_yaml::Value::Mapping promotion of a serde_yaml::Mapping value. Returns the prior value at that key, mirroring serde_yaml::Mapping::insert.

The canonical shape ~6 production call sites across the caixa- side renderer surface previously carried inline as the three- token block mapping.insert_str_key(<KEY>, serde_yaml::Value::Mapping(<INNER>)) — a two-token semantic payload (<KEY>, <INNER>) buried under a two-axis boilerplate (serde_yaml:: path re-quote, Value::Mapping(_) promotion) around a Mapping variable the caller already built.

Sites lifted:

caixa-mesh’s cilium_network_policies per-toPorts[] rules: L7-introspection sub-block (KUBE_KEY_RULES around the built rules Mapping);
caixa-mesh’s cilium_network_policies per-CiliumNetworkPolicy spec: block (KUBE_KEY_SPEC around the built policy_spec Mapping);
caixa-mesh’s gateway_routes per-Gateway spec: block (KUBE_KEY_SPEC around the built g_spec Mapping);
caixa-mesh’s gateway_routes per-HTTPRoute.spec.rules[] matches[].path: sub-block (GATEWAY_API_KEY_PATH around the built path_match Mapping);
caixa-mesh’s gateway_routes per-HTTPRoute spec: block (KUBE_KEY_SPEC around the built r_spec Mapping);
caixa-core’s kube_resource_skeleton per-CR metadata: sub-block (KUBE_KEY_METADATA around the built metadata_map Mapping).

Lifting collapses the boilerplate into one method call the caller reads as intent (mapping.insert_mapping(<KEY>, <INNER>) — “insert a nested-Mapping-typed sub-block named KEY with the built inner INNER”) rather than three hand-spelled positional artifacts. The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-policy nested-Mapping sub-blocks are metadata: / spec: / spec.resources[]), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (per-spec.selectors[] and per-spec.gates[] sub-blocks), the M4 cross-cluster fan-out’s per-cluster Service.spec / HTTPRoute.spec sub-block emission, the future caixa-otel OpenTelemetry-Collector per-pipeline receivers: / processors: / exporters: nested-Mapping emission — gets the canonical nested-Mapping-valued-field shape for free with one method call, instead of re-inlining the three-token Value::Mapping(_) promotion.

Peer to Self::insert_string on the sibling scalar-value axis and Self::insert_sequence on the sibling list-shape axis — the four together with Self::insert_str_key form the “one method call per emission axis” primitive quadruple the K8s- artifact-emit surface’s “same shape, written N times” duplication (THEORY.md §I.3.5) collapses onto: insert_str_key for any-Value inserts, insert_string for the string-scalar-valued-field shape, insert_mapping for the nested-Mapping-valued-field shape, insert_sequence for the list-shape-valued-field shape.

Source

fn insert_sequence(&mut self, key: &str, value: Vec<Value>) -> Option<Value>

Insert (key, Value::Sequence(value)) into self — the list-shape-valued-field emission shape that combines Self::insert_str_key’s &str → Value::String key promotion with an automatic serde_yaml::Value::Sequence promotion of a pre-built Vec<serde_yaml::Value> value. Returns the prior value at that key, mirroring serde_yaml::Mapping::insert.

The canonical shape 4 production call sites across caixa-mesh previously carried inline as the three-token block mapping.insert_str_key(<KEY>, serde_yaml::Value::Sequence(<VEC>)) — a two-token semantic payload (<KEY>, <VEC>) buried under a two-axis boilerplate (serde_yaml:: path re-quote, Value::Sequence(_) promotion) around a Vec<Value> variable the caller already built.

Sites lifted:

caixa-mesh’s cilium_network_policies per-CiliumNetworkPolicy spec.ingress[].fromEndpoints: singleton-list (CILIUM_KEY_FROM_ENDPOINTS around a vec![from_endpoint] selector wrapper);
caixa-mesh’s cilium_network_policies per-CiliumNetworkPolicy spec.ingress[].toPorts: list (CILIUM_KEY_TO_PORTS around the built to_ports_seq per-edge port-and-L7-rule vec);
caixa-mesh’s gateway_routes per-HTTPRoute spec.hostnames: singleton-list (GATEWAY_API_KEY_HOSTNAMES around a vec![Value::String(entrada.host…)] host wrapper);
caixa-mesh’s gateway_routes per-HTTPRoute spec.rules: list (KUBE_KEY_RULES around the built rules per-path match+backend+overlay vec).

Lifting collapses the boilerplate into one method call the caller reads as intent (mapping.insert_sequence(<KEY>, <VEC>) — “insert a list-shape-typed sub-block named KEY with the built inner VEC”) rather than three hand-spelled positional artifacts. The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-policy list-shape sub-blocks are spec.resources[] / spec.listeners[] / spec.virtualHosts[], MESH-COMPOSITION §III.2 #3), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (per-spec.selectors[] and per-spec.gates[] list-shape sub-blocks, §III.2 #5), the M4 cross-cluster fan-out’s per-cluster Service.spec.ports[] / HTTPRoute.spec.rules[].backendRefs[] list emission, the future caixa-otel OpenTelemetry-Collector per-pipeline receivers[] / processors[] / exporters[] list emission — gets the canonical list-shape-valued-field shape for free with one method call, instead of re-inlining the three-token Value::Sequence(_) promotion.

Peer to Self::insert_mapping on the sibling nested-Mapping axis and Self::insert_string on the sibling scalar-value axis — the four together with Self::insert_str_key form the “one method call per emission axis” primitive quadruple the K8s- artifact-emit surface’s “same shape, written N times” duplication (THEORY.md §I.3.5) collapses onto: insert_str_key for any-Value inserts, insert_string for the string-scalar-valued-field shape, insert_mapping for the nested-Mapping-valued-field shape, insert_sequence for the list-shape-valued-field shape.

Complementary to singleton_mapping_sequence on the peer singleton-list-shape axis: singleton_mapping_sequence(m) builds the sole-Mapping-element Value::Sequence payload; insert_sequence(K, v) inserts an already-built Vec<Value> payload under a schema key. A caller composing the two through Self::insert_singleton_mapping_sequence writes mapping.insert_singleton_mapping_sequence(K, m) for the singleton case (the sole element is a fresh Mapping); reach for mapping.insert_sequence(K, v) for the multi-element or non-Mapping-element case (the vec is built up per-iteration or wraps a non-Mapping scalar).

Source

fn insert_singleton_mapping_sequence( &mut self, key: &str, value: Mapping, ) -> Option<Value>

Insert (key, Value::Sequence(vec![Value::Mapping(value)])) into self — the singleton-Mapping-list-shape-valued-field emission shape that composes Self::insert_str_key’s &str → Value::String key promotion with the singleton_mapping_sequence helper’s singleton-list wrap of a serde_yaml::Mapping payload. Returns the prior value at that key, mirroring serde_yaml::Mapping::insert.

The canonical shape 7 production call sites across caixa-mesh previously carried inline as the two-token composition mapping.insert_str_key(<KEY>, singleton_mapping_sequence(<M>)) — a two-token semantic payload (<KEY>, <M>) buried under a two-symbol boilerplate (insert_str_key(_, _) + singleton_mapping_sequence(_)) that fully covers the axis: every site both wraps its per-call Mapping as the sole-element list value and inserts it under a schema key on an outer Mapping. A rebrand on either half — the outer key-scalar promotion axis migrating to a per-key typed Value variant, the singleton-list wrap migrating to a Server-Side-Apply-typed Value::Tagged per-CRD-list shape once K8s per-field ownership annotations reach the K8s Gateway API / Cilium NetworkPolicy CRD list schemas — would silently desynchronize one site while leaving the other six on the old shape.

Sites lifted:

caixa-mesh’s cilium_network_policies per-toPorts[] port entry ports: singleton-list (CILIUM_KEY_PORTS around the built port_entry Mapping);
caixa-mesh’s cilium_network_policies per-toPorts[] L7 rules.http: singleton-list (CILIUM_KEY_HTTP around the built http_rule Mapping);
caixa-mesh’s cilium_network_policies per-CiliumNetworkPolicy spec.ingress: singleton-list (CILIUM_KEY_INGRESS around the built ingress_rule Mapping);
caixa-mesh’s gateway_routes per-Gateway spec.listeners: singleton-list (GATEWAY_API_KEY_LISTENERS around the built listener Mapping);
caixa-mesh’s gateway_routes per-HTTPRoute.spec.rules[] matches: singleton-list (GATEWAY_API_KEY_MATCHES around the built match_entry Mapping);
caixa-mesh’s gateway_routes per-HTTPRoute.spec.rules[] backendRefs: singleton-list (GATEWAY_API_KEY_BACKEND_REFS around the built backend_ref Mapping);
caixa-mesh’s gateway_routes per-HTTPRoute spec.parentRefs: singleton-list (GATEWAY_API_KEY_PARENT_REFS around the built parent_ref Mapping).

Lifting collapses the two-symbol composition into one method call the caller reads as intent (mapping.insert_singleton_mapping_sequence (<KEY>, <M>) — “insert a singleton-Mapping-list-shape sub-block named KEY wrapping the built inner M”) rather than two nested calls. Peer to Self::insert_sequence on the sibling multi-element or non-Mapping-element list-shape axis — the two together partition the list-shape-valued-field emission surface: Self::insert_singleton_mapping_sequence for the sole-Mapping- element case, Self::insert_sequence for every other case.

The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose singleton spec.resources:[] / spec.listeners:[] / spec.virtualHosts:[] Mapping-element blocks, MESH-COMPOSITION §III.2 #3, are exactly the singleton-Mapping-list shape), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (per-single- selector / per-single-gate emission, §III.2 #5), the M4 cross- cluster fan-out’s per-cluster singleton Service.spec.ports[] / HTTPRoute.spec.rules[].backendRefs[] sole-element emission, the future caixa-otel OpenTelemetry-Collector pipelines.traces. receivers[] singleton-receiver emission — gets the canonical singleton-Mapping-list-shape wrap+insert for free with one method call, instead of re-inlining the two-symbol composition.

Source

fn entry_str_key(&mut self, key: &str) -> Entry<'_>

Entry-API sibling of Self::insert_str_key — mint the Value::String(<KEY>.into()) key-promotion the underlying serde_yaml::Mapping::entry method’s Value parameter demands, and return the entry-API’s serde_yaml::mapping::Entry handle the caller composes .or_insert(<V>) / .or_insert_with(<F>) / .and_modify(<F>) / .or_default() on.

The canonical shape 4 production call sites across caixa-flux previously carried inline as the three-token composition mapping.entry(serde_yaml::Value::String(<KEY>.into())) around a one-token semantic payload (the schema key axis-name). Every site immediately composes an .or_insert(...) on the returned serde_yaml::mapping::Entry handle — the pattern is the entry-API twin of the Self::insert_str_key pattern the ~48 fresh-emit sites already collapsed onto (23506b3).

Sites lifted:

caixa-flux’s programs_yaml_entry per-servico_m2_overlay key idempotent-upsert loop (entry.entry(Value::String( <key>.to_string())).or_insert(<value>) — one .or_insert(...) per M2_KEY_LIMITS / M2_KEY_BEHAVIOR / M2_KEY_UPGRADE_FROM axis, iterating the servico_m2_overlay BTreeMap);
caixa-flux’s upsert_into_helmrelease_programs per- HelmRelease.spec.values upsert-if-absent (FLUX_KEY_VALUES around a default fresh Value::Mapping);
caixa-flux’s upsert_into_helmrelease_programs per- HelmRelease.spec.values.programs upsert-if-absent (FLEET_PROGRAMS_KEY_PROGRAMS around a default fresh Value::Sequence);
caixa-flux’s upsert_into_programs_yaml per-top-level programs: upsert-if-absent (FLEET_PROGRAMS_KEY_PROGRAMS around a default fresh Value::Sequence — the sibling of the upsert_into_helmrelease_programs site on the same key, one path deep in a HelmRelease spec.values. sub-tree, one path at the values.yaml root).

Lifting collapses the three-token composition into one method call the caller reads as intent (mapping.entry_str_key(<KEY>).or_insert(<DEFAULT>) — “get the entry handle for this schema key and default it if missing”) rather than four hand-spelled positional artifacts (serde_yaml:: path re-quote, Value::String(_) promotion, the .into() | .to_string() &str → String coercion, plus the .entry(_) call itself). The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (which upserts singleton spec.resources:[] / spec.listeners:[] blocks under an existing per-cluster overlay CR, MESH-COMPOSITION §III.2 #3), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (which upserts status. sub-fields on partial reconciles, §III.2 #5), the M4 cross-cluster fan-out’s per-cluster idempotent HelmRelease upsert — gets the canonical entry-API key-promotion for free with one method call, instead of re-inlining the three-token block.

Peer to Self::insert_str_key on the sibling fresh-emit axis of the same &str → Value::String key-promotion — the two together partition the Mapping-write surface: entry-API for idempotent-upsert sites where the caller cares whether the prior value was present (or_insert / and_modify / or_default composition), insert-API for fresh-emit sites where the caller unconditionally writes a value and either drops or pattern-matches on the returned Option<Value> prior value.

Source

fn insert_str_key_if_some( &mut self, key: &str, value: Option<&Value>, ) -> Option<Value>

Arity-0-or-1 twin of Self::insert_str_key — insert (key, value.clone()) iff value is Some; leave self untouched iff value is None. Returns the prior value at that key when the insert fires (mirroring serde_yaml::Mapping::insert), and None otherwise (no insert happened, so no prior value can be surfaced).

The canonical shape 3 production call sites across caixa-mesh previously carried inline as the three-line block if let Some(<x>) = &<overlay> { <mapping>.insert_str_key(<KEY>, <x>.clone()); } around a two-token semantic payload (the schema key axis-name + the Option<Value> overlay slot). Every site pairs a per-:politicas overlay single_field_overlay Option <Value> output with the same conditional-insert conditional — the arity-0-or-1 twin of Self::insert_str_key’s always-1 arity on the per-(:de, :para) axis.

Sites lifted:

caixa-mesh’s cilium_network_policies per-ingress-rule :politicas :mtls-required mutual-auth overlay (crate::CILIUM_KEY_AUTHENTICATION around the mtls_overlay single_field_overlay output — the tristate {mode: required | disabled} block or the None-omit arm);
caixa-mesh’s gateway_routes per-HTTPRoute-rule :politicas :timeout request-deadline overlay (crate::GATEWAY_API_KEY_TIMEOUTS around the timeout_overlay single_field_overlay output — the {request: "<duration>"} block or the None-omit arm);
caixa-mesh’s gateway_routes per-HTTPRoute-rule :politicas :retries retry-attempt-cap overlay (crate::GATEWAY_API_KEY_RETRY around the retry_overlay single_field_overlay output — the {attempts: <N>} block or the None-omit arm).

Lifting collapses the three-line block into one method call the caller reads as intent (mapping.insert_str_key_if_some(<KEY>, <overlay>.as_ref()) — “insert this schema key if the overlay carried a value; else leave the key absent”) rather than four hand-spelled positional artifacts (the if let Some(_) = &_ destructure, the per-inner .clone(), the trailing brace, plus the .insert_str_key(_) call itself). The absent-overlay arm — which every [MeshPolicy] axis defaults to when the author leaves the typed slot unset (the None arm of the Option<Value> single_field_overlay output) — reads as the method’s own Option::None branch, not a per-call-site inverted if let Some scaffold around a per-call-site clone.

The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-policy authentication: / rateLimit: / circuitBreaker: Option overlays, MESH-COMPOSITION §III.2 #3, thread through the same single_field_overlay Option<Value> axis the three lifted sites here already reach), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (whose per- selector status. sub-field overlays are the same arity-0-or-1 shape, §III.2 #5), the M4 cross-cluster fan-out’s per-cluster HTTPRoute.spec.rules[].filters[] per-filter Option overlays (the same shape at the per-cluster axis) — gets the canonical arity-0-or-1 conditional-insert for free with one method call, instead of re-inlining the three-line if let Some { clone; insert_str_key } block.

Peer to Self::insert_str_key on the always-1 arity axis (fresh-emit sites where the caller unconditionally writes a value) — the two together partition the fresh-emit surface exactly on the arity axis: Self::insert_str_key for unconditional writes, Self::insert_str_key_if_some for conditional writes gated on an Option<Value> upstream producer (the per-:politicas overlay single_field_overlay axis, and every future arity-0-or-1 axis every future renderer’s optional-slot machinery reaches through).

The Option<&Value> shape (as opposed to an owned Option<Value>) lets the caller pass overlay.as_ref() on an owned Option<Value> the caller reuses across iterations of an outer per-(:de, :para) or per-rule loop — every lifted site consumes the overlay from a loop-outer binding into each of N per-iteration Mappings, so the clone happens iff the insert fires (the None arm skips the clone entirely) and the outer binding stays available for the next iteration.

Source

fn entry_or_default_mapping(&mut self, key: &str) -> Option<&mut Mapping>

Fetch a &mut serde_yaml::Mapping at key, defaulting an empty serde_yaml::Mapping into place when the entry is absent. Returns Some(&mut inner) on the absent-key (fresh empty Mapping) and present-Mapping arms; None iff key holds a different serde_yaml::Value variant — a structural container-type mismatch the caller surfaces as its own domain-specific error (Error::MissingField("spec.values must be a mapping") for the caixa-flux Flux-HelmRelease overlay walker).

The canonical shape 1 production call site in caixa-flux (upsert_into_helmrelease_programs’s per-HelmRelease.spec.values container-upsert on the way down to spec.values.programs[]) previously carried inline as a four-line block combining Self::entry_str_key’s entry-API key promotion (68d035e), an .or_insert(Value::Mapping(Mapping::new())) empty-Mapping default, and a let Value::Mapping(inner) = _ else { Err(...) } destructure — a two-token semantic payload (the schema key + the domain-specific type-mismatch diagnostic) buried under three boilerplate axes (Value::Mapping(_) variant promotion, Mapping::new() empty-container construction, the outer let else destructure). Peer to Self::entry_or_default_sequence on the sibling Vec<Value>- valued idempotent-container-upsert axis — the two together partition the entry-API-container-upsert surface exactly on the container-variant axis: Self::entry_or_default_mapping for nested-Mapping sub-blocks, Self::entry_or_default_sequence for list-shape sub-blocks.

Sites lifted:

caixa-flux’s upsert_into_helmrelease_programs per- HelmRelease.spec.values container-upsert (FLUX_KEY_VALUES around the default fresh Value::Mapping, on the way down to the nested spec.values.programs[] sequence).

Lifting collapses the four-line block into one method call the caller reads as intent (mapping.entry_or_default_mapping(<KEY>) .ok_or(<ERR>)? — “give me the nested Mapping at this schema key, defaulting empty if absent, else surface my domain error”) rather than five hand-spelled positional artifacts (serde_yaml:: path re-quote, Value::Mapping(_) promotion, Mapping::new() construction, the entry-API .or_insert(...) call, plus the outer let Value::Mapping(_) = _ else {} destructure). The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-cluster upsert walks HelmRelease.spec.values.<library>.<:politicas-axis>, idempotent-upserting nested-Mapping sub-blocks under each axis, MESH-COMPOSITION §III.2 #3), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (which upserts status.<axis> nested-Mapping sub-blocks on partial reconciles, §III.2 #5), the M4 cross-cluster fan-out’s per-cluster idempotent HelmRelease.spec.values.<library> container-upsert — gets the canonical entry-API-with- container-type-check for free with one method call, instead of re-inlining the four-line block.

The default-empty-Mapping construction fires only on the absent-key arm (.or_insert_with(...) gates the closure on vacancy) — the present-key arm reuses the existing Mapping verbatim, so the caller’s downstream writes on &mut inner compose with any prior overlay writes from earlier passes (the exact idempotent-upsert semantic the caixa-flux per-cluster feira app deploy write path depends on to preserve operator-pinned overlays across re-renders).

Source

fn entry_or_default_sequence(&mut self, key: &str) -> Option<&mut Vec<Value>>

Fetch a &mut Vec<serde_yaml::Value> at key, defaulting an empty Vec<serde_yaml::Value> into place when the entry is absent. Returns Some(&mut inner) on the absent-key (fresh empty Sequence) and present-Sequence arms; None iff key holds a different serde_yaml::Value variant — a structural container-type mismatch the caller surfaces as its own domain-specific error (Error::MissingField("programs must be a sequence") for the caixa-flux fleet-programs upsert walkers).

The canonical shape 2 production call sites in caixa-flux (upsert_into_helmrelease_programs’s per- HelmRelease.spec.values.programs container-upsert and upsert_into_programs_yaml’s top-level programs: container- upsert) previously carried inline as a four-line block combining Self::entry_str_key’s entry-API key promotion (68d035e), an .or_insert(Value::Sequence(Vec::new())) empty-Sequence default, and a match _ { Value::Sequence(seq) => seq, _ => return Err(...) } destructure — a two-token semantic payload (the schema key + the domain-specific type-mismatch diagnostic) buried under three boilerplate axes (Value::Sequence(_) variant promotion, Vec::new() empty-container construction, the outer match destructure). Peer to Self::entry_or_default_mapping on the sibling nested-Mapping-valued idempotent-container-upsert axis.

Sites lifted:

caixa-flux’s upsert_into_helmrelease_programs per- HelmRelease.spec.values.programs list-container-upsert (FLEET_PROGRAMS_KEY_PROGRAMS around the default fresh Value::Sequence, one path deep in a HelmRelease spec.values. sub-tree);
caixa-flux’s upsert_into_programs_yaml per-top-level programs: list-container-upsert (FLEET_PROGRAMS_KEY_PROGRAMS around the default fresh Value::Sequence — the sibling of the upsert_into_helmrelease_programs site on the same key, one path at the values.yaml root).

Lifting collapses the four-line block into one method call the caller reads as intent (mapping.entry_or_default_sequence(<KEY>) .ok_or(<ERR>)? — “give me the list at this schema key, defaulting empty if absent, else surface my domain error”) rather than five hand-spelled positional artifacts (serde_yaml:: path re-quote, Value::Sequence(_) promotion, Vec::new() construction, the entry-API .or_insert(...) call, plus the outer match { Value::Sequence(_) => _, _ => return Err(_) } destructure). The next renderer to land — the per-:politicas CiliumClusterwideEnvoyConfig emitter (whose per-cluster upsert walks nested list-shape sub-blocks spec.resources[] / spec.listeners[] / spec.virtualHosts[] under existing operator-pinned overlay CRs, MESH-COMPOSITION §III.2 #3), the app-operator’s typed mesh.pleme.io/v1alpha1/Aplicacao CR materializer (which upserts status.selectors[] / status.gates[] list-shape sub-blocks on partial reconciles, §III.2 #5), the M4 cross- cluster fan-out’s per-cluster idempotent HelmRelease.spec.values.programs list-upsert — gets the canonical entry-API-with-container-type-check for free with one method call, instead of re-inlining the four-line block.

The default-empty-Sequence construction fires only on the absent-key arm (.or_insert_with(...) gates the closure on vacancy) — the present-key arm reuses the existing Vec verbatim, so the caller’s downstream upsert_named_entry (10bf310) call on &mut inner composes with any prior entries the emitter wrote on earlier passes (the exact idempotent-upsert semantic the feira app deploy per-cluster write path depends on to preserve prior programs[] entries across per-Servico rewrites).

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types§

Source §

impl MappingExt for Mapping

Source §

fn insert_str_key(&mut self, key: &str, value: Value) -> Option<Value>

Source §

fn insert_string<V: Into<String>>( &mut self, key: &str, value: V, ) -> Option<Value>

Source §

fn insert_number<N: Into<Number>>( &mut self, key: &str, value: N, ) -> Option<Value>

Source §

fn insert_mapping(&mut self, key: &str, value: Mapping) -> Option<Value>

Source §

fn insert_sequence(&mut self, key: &str, value: Vec<Value>) -> Option<Value>

Source §

fn insert_singleton_mapping_sequence( &mut self, key: &str, value: Mapping, ) -> Option<Value>

Source §

fn entry_str_key(&mut self, key: &str) -> Entry<'_>

Source §

MappingExt

Trait MappingExt Copy item path

Required Methods§

fn insert_str_key(&mut self, key: &str, value: Value) -> Option<Value>

fn insert_string<V: Into<String>>( &mut self, key: &str, value: V, ) -> Option<Value>

fn insert_number<N: Into<Number>>( &mut self, key: &str, value: N, ) -> Option<Value>

fn insert_mapping(&mut self, key: &str, value: Mapping) -> Option<Value>

fn insert_sequence(&mut self, key: &str, value: Vec<Value>) -> Option<Value>

fn insert_singleton_mapping_sequence( &mut self, key: &str, value: Mapping, ) -> Option<Value>

fn entry_str_key(&mut self, key: &str) -> Entry<'_>

fn insert_str_key_if_some( &mut self, key: &str, value: Option<&Value>, ) -> Option<Value>

fn entry_or_default_mapping(&mut self, key: &str) -> Option<&mut Mapping>

fn entry_or_default_sequence(&mut self, key: &str) -> Option<&mut Vec<Value>>

Dyn Compatibility§

Implementations on Foreign Types§

impl MappingExt for Mapping

fn insert_str_key(&mut self, key: &str, value: Value) -> Option<Value>

fn insert_string<V: Into<String>>( &mut self, key: &str, value: V, ) -> Option<Value>

fn insert_number<N: Into<Number>>( &mut self, key: &str, value: N, ) -> Option<Value>

fn insert_mapping(&mut self, key: &str, value: Mapping) -> Option<Value>

fn insert_sequence(&mut self, key: &str, value: Vec<Value>) -> Option<Value>

fn insert_singleton_mapping_sequence( &mut self, key: &str, value: Mapping, ) -> Option<Value>

fn entry_str_key(&mut self, key: &str) -> Entry<'_>

fn insert_str_key_if_some( &mut self, key: &str, value: Option<&Value>, ) -> Option<Value>

fn entry_or_default_mapping(&mut self, key: &str) -> Option<&mut Mapping>

fn entry_or_default_sequence(&mut self, key: &str) -> Option<&mut Vec<Value>>

Implementors§

Trait MappingExt