@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/rust/feature/secrets/plugin/depend.rs

@@ -0,0 +1,245 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (rust/src/depend.rs)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+//! Dependency cardinality, policy, and the restart graph (§11.3).
+//!
+//! TWO AXES, BOTH DECLARED BY THE DEFINITION THAT HAS THE REQUIREMENT,
+//! because only it knows what it can cope with:
+//!
+//! ```text
+//!                | static (default)          | dynamic
+//!   -------------|---------------------------|--------------------------
+//!   mandatory    | unmet -> pending;         | unmet -> pending;
+//!   (default)    | lost  -> pending,         | lost  -> STAYS LIVE,
+//!                |          recursively      |          notified
+//!   -------------|---------------------------|--------------------------
+//!   optional:true| never gates activation;   | never gates activation;
+//!                | a change deactivates and  | a change is a
+//!                | reactivates               | notification, nothing else
+//! ```
+//!
+//! `dynamic` means the plugin has said, IN WRITING, that it can survive
+//! its provider being swapped underneath it. It is not the default because
+//! most plugins cannot, and the cost of wrongly assuming they can is a
+//! live instance holding a dead reference.
+//!
+//! The rebinding-preference axis is deliberately omitted. OSGi has
+//! reluctant vs greedy and it is a knob every author must understand to
+//! read anyone else's component; we take always-reluctant. Three axes were
+//! more than the model can carry across twenty ports.
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use super::types::{details, fail, PluginError};
+use super::value::Value;
+use super::refs::canon;
+
+/// A bare string is shorthand for `{name}`.
+pub fn normrequire(raw: &Value) -> Value {
+    if let Value::Str(_) = raw {
+        let mut out = Value::map();
+        out.set("name", raw.clone());
+        return out;
+    }
+    match raw {
+        Value::Map(_) => raw.clone(),
+        _ => Value::map(),
+    }
+}
+
+/// The requirements a definition declared, normalized.
+///
+/// BOTH AXES ARE READ AT TWO LEVELS, AND THE PER-REQUIREMENT ONE WINS.
+///
+/// The instance-level `policy` and `optional` list are how a DOCUMENT
+/// states the axis without editing the definition, and they apply to every
+/// requirement. The per-requirement form is the one §11.1's object syntax
+/// exists for, and it is strictly more expressive: an instance that is
+/// `static` on its store and `dynamic` on its metrics cannot be written at
+/// all at the instance level.
+///
+/// `optional` unions rather than overriding - both spellings are
+/// statements that this requirement need not gate activation, and there is
+/// no reading under which one of them means "actually, mandatory".
+pub fn requirements(options: &Value) -> Vec<Value> {
+    let raw = options.get("requires");
+    let marked = options.get("optional");
+    let fallback = options.get("policy");
+
+    let mut out = Vec::new();
+    for item in raw.as_list().cloned().unwrap_or_default().iter() {
+        let mut req = normrequire(item);
+        let ismarked = marked
+            .as_list()
+            .map(|l| l.iter().any(|m| m.same(&req.get("name"))))
+            .unwrap_or(false);
+        if req.get("optional").truthy() || ismarked {
+            req.set("optional", Value::Bool(true));
+        }
+        if req.get("policy").is_null() && !fallback.is_null() {
+            req.set("policy", fallback.clone());
+        }
+        out.push(req);
+    }
+    out
+}
+
+/// Does losing this requirement's SELECTED provider restart the consumer?
+/// The mandatory ones under `static`, and the `static` optional ones -
+/// both make a capability change deactivate and reactivate. `dynamic`
+/// never restarts.
+pub fn restartsonloss(req: &Value) -> bool {
+    let policy = req.get("policy");
+    policy.as_str().unwrap_or("static") != "dynamic"
+}
+
+/// Does an unmet requirement keep the consumer out of `live`?
+///
+/// Cardinality alone decides this, NOT policy. `dynamic` is a statement
+/// about surviving a SWAP, not about starting without the thing at all - a
+/// mandatory-dynamic consumer still waits in `pending` for its first
+/// provider.
+pub fn gatesactivation(req: &Value) -> bool {
+    !matches!(req.get("optional"), Value::Bool(true))
+}
+
+/// Edges that can cause a restart, which is exactly the set a cycle must
+/// be detected over (§11.3).
+///
+/// ONLY `dynamic` OPTIONAL EDGES ARE EXCLUDED, and they are the ones the
+/// exclusion was for: two plugins that optionally and dynamically consume
+/// each other's capabilities both activate happily, neither gates on the
+/// other, and each is merely notified when the other appears. Nothing
+/// restarts, so nothing oscillates.
+///
+/// An earlier draft of §11.3 excluded EVERY optional edge and thereby
+/// admitted the non-terminating case it was trying to permit.
+pub fn restartcausing(req: &Value) -> bool {
+    gatesactivation(req) || restartsonloss(req)
+}
+
+/// One node of the requirement graph, as plain data for the pure detector.
+pub struct Node {
+    pub eref: String,
+    pub provides: Vec<String>,
+    pub requires: Vec<Value>,
+}
+
+/// A cycle through restart-causing requirements is
+/// `plugin_dependency_cycle`, detected AT LOAD - before anything runs,
+/// because the failure it describes is a non-terminating reconcile and the
+/// only safe time to report that is before it starts.
+///
+/// The graph is over capabilities, not refs: an edge runs from a consumer
+/// to EVERY node that provides what it needs, because any of them could be
+/// the one selected and a cycle through any is a cycle. A node also
+/// satisfies its own name as a ref (§11.1), which is why the ref is a
+/// provider of itself here.
+pub fn dependencycycle(nodes: &[Node]) -> Option<Vec<String>> {
+    // TWO INDEXES, NOT ONE MERGED MAP. Capability names and refs are
+    // matched differently - a capability by its exact name, a ref through
+    // the canonical spelling (section 4 rule 5) - and one map keyed by
+    // both can only do one of them. Keyed by both and looked up raw, as
+    // this was, a cycle spelled `a$`/`b$` found no providers and EVADED
+    // the load-time check that exists to catch a non-terminating
+    // reconcile.
+    let mut bycap: BTreeMap<String, Vec<String>> = BTreeMap::new();
+    let mut isref: BTreeSet<String> = BTreeSet::new();
+    for n in nodes.iter() {
+        isref.insert(n.eref.clone());
+        for cap in n.provides.iter() {
+            bycap.entry(cap.clone()).or_default().push(n.eref.clone());
+        }
+    }
+
+    let mut edges: BTreeMap<String, Vec<String>> = BTreeMap::new();
+    for n in nodes.iter() {
+        let mut out: Vec<String> = Vec::new();
+        for req in n.requires.iter() {
+            if !restartcausing(req) {
+                continue;
+            }
+            let name = req.get("name");
+            let name = name.as_str().unwrap_or("");
+            let mut from: Vec<String> = bycap.get(name).cloned().unwrap_or_default();
+            // A node satisfies its own name AS A REF (section 11.1),
+            // canonically - exactly what `providersof` does at runtime.
+            // `canon` hands back a name no ref could have unchanged, and
+            // no instance ref can equal one, so it is the tolerant test.
+            let asref = canon(name);
+            if isref.contains(&asref) && !from.contains(&asref) {
+                from.push(asref);
+            }
+            for p in from.iter() {
+                if *p != n.eref && !out.contains(p) {
+                    out.push(p.clone());
+                }
+            }
+        }
+        out.sort();
+        edges.insert(n.eref.clone(), out);
+    }
+
+    // Iterative DFS with an explicit stack: twenty ports, and several of
+    // them have no recursion budget worth relying on.
+    const WHITE: u8 = 0;
+    const GREY: u8 = 1;
+    const BLACK: u8 = 2;
+    let mut colour: BTreeMap<String, u8> =
+        nodes.iter().map(|n| (n.eref.clone(), WHITE)).collect();
+
+    let starts: Vec<String> = edges.keys().cloned().collect();
+    for start in starts.iter() {
+        if WHITE != colour[start] {
+            continue;
+        }
+
+        let mut path: Vec<String> = vec![start.clone()];
+        let mut stack: Vec<(String, usize)> = vec![(start.clone(), 0)];
+        colour.insert(start.clone(), GREY);
+
+        while !stack.is_empty() {
+            let top = stack.last_mut().unwrap();
+            let outs = &edges[&top.0];
+            if outs.len() <= top.1 {
+                let done = top.0.clone();
+                colour.insert(done, BLACK);
+                stack.pop();
+                path.pop();
+                continue;
+            }
+            let nxt = outs[top.1].clone();
+            top.1 += 1;
+            if GREY == colour[&nxt] {
+                // Report the cycle itself, not the walk that found it.
+                let at = path.iter().position(|p| *p == nxt).unwrap_or(0);
+                let mut cycle: Vec<String> = path[at..].to_vec();
+                cycle.push(nxt);
+                return Some(cycle);
+            }
+            if BLACK == colour[&nxt] {
+                continue;
+            }
+            colour.insert(nxt.clone(), GREY);
+            path.push(nxt.clone());
+            stack.push((nxt, 0));
+        }
+    }
+    None
+}
+
+/// Raise on a cycle, naming it. Separate from the detector so the detector
+/// stays pure and corpus-testable.
+pub fn checkcycle(nodes: &[Node]) -> Result<(), PluginError> {
+    match dependencycycle(nodes) {
+        None => Ok(()),
+        Some(cycle) => fail(
+            "plugin_dependency_cycle",
+            &format!("requirements cycle: {}", cycle.join(" -> ")),
+            details(&[(
+                "cycle",
+                Value::List(cycle.iter().map(|r| Value::str(r)).collect()),
+            )]),
+        ),
+    }
+}

package/project/.sdk/tm/rust/feature/secrets/plugin/env.rs

@@ -0,0 +1,200 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (rust/src/env.rs)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+//! Environment overrides (§9.5) - level 7 of the ladder.
+//!
+//! One prefix, so nothing drifts: `VOXGIG_PLUGIN_*`.
+//!
+//! ```text
+//!   VOXGIG_PLUGIN_PROFILE            the profile name
+//!   VOXGIG_PLUGIN_<REF>_<PATH>       one option
+//!   VOXGIG_PLUGIN_ACTIVE/INACTIVE    comma-separated refs, INACTIVE wins
+//! ```
+//!
+//! THE ENCODING IS LOSSY, AND THIS SAYS SO RATHER THAN PRETENDING
+//! OTHERWISE. Ref and path are upper-snake with `$` -> `__` and `.` ->
+//! `_`. But `_` is legal in a name and in a tag, and the mapping folds
+//! case, so `retry$fast` and `retry__fast` both encode to `RETRY__FAST`.
+//!
+//! Rather than restrict a grammar the rest of the stack already uses, the
+//! host DETECTS THE COLLISION: it encodes every ref it holds, and a key
+//! two refs claim is `plugin_env_ambiguous`, naming both.
+
+use std::collections::BTreeMap;
+
+use super::refs::{canon_ref, refname};
+use super::types::{details, fail, stable_sort_by, PluginError};
+use super::value::{self, Value};
+
+pub const ENV_PREFIX: &str = "VOXGIG_PLUGIN_";
+
+/// `retry$fast` -> `RETRY__FAST`.
+pub fn encode_ref(eref: &str) -> String {
+    eref.replace('$', "__").replace('.', "_").to_uppercase()
+}
+
+pub fn apply_env(input: &Value) -> Result<Value, PluginError> {
+    let env = input.get("env");
+    let reserved = input.get("reserved");
+
+    let mut refs: Vec<String> = Vec::new();
+    for r in input.get("refs").as_list().cloned().unwrap_or_default().iter() {
+        refs.push(canon_ref(r)?);
+    }
+
+    let mut out = Value::map();
+    out.set("options", Value::map());
+    out.set("active", Value::List(Vec::new()));
+    out.set("inactive", Value::List(Vec::new()));
+
+    // Encode every ref the host holds, and refuse a key that two of them
+    // claim. Done up front so the collision is reported even when no
+    // environment variable exercises it - a latent ambiguity is still an
+    // ambiguity, and finding it at deploy time is the failure this exists
+    // to prevent.
+    let mut byencoded: BTreeMap<String, Vec<String>> = BTreeMap::new();
+    for r in refs.iter() {
+        byencoded.entry(encode_ref(r)).or_default().push(r.clone());
+    }
+    for (e, group) in byencoded.iter() {
+        if group.len() <= 1 {
+            continue;
+        }
+        let mut pair = group.clone();
+        pair.sort();
+        return fail(
+            "plugin_env_ambiguous",
+            &format!(
+                "refs collide in the environment encoding as {}: {}",
+                e,
+                pair.join(", ")
+            ),
+            details(&[(
+                "refs",
+                Value::List(pair.iter().map(|r| Value::str(r)).collect()),
+            )]),
+        );
+    }
+
+    // Longest encoded ref first, so `retry$fast` wins over `retry` on
+    // `RETRY__FAST_MIN`. Shortest-first would read the tag as a path.
+    let mut encoded: Vec<String> = byencoded.keys().cloned().collect();
+    stable_sort_by(&mut encoded, |e| -(e.len() as i64));
+
+    for key in env.keys() {
+        if !key.starts_with(ENV_PREFIX) {
+            continue;
+        }
+        let rest = &key[ENV_PREFIX.len()..];
+
+        if "PROFILE" == rest {
+            out.set("profile", env.get(&key));
+            continue;
+        }
+
+        if "ACTIVE" == rest || "INACTIVE" == rest {
+            let field = if "ACTIVE" == rest { "active" } else { "inactive" };
+            let mut list = out.get(field).as_list().cloned().unwrap_or_default();
+            for raw in env_split(&env.get(&key)) {
+                let eref = canon_ref(&Value::str(&raw))?;
+                // The reservation covers EVERY input layer (§9.1).
+                // VOXGIG_PLUGIN_INACTIVE=station is easier to set than
+                // editing a config file, and INACTIVE has the final word -
+                // so guarding documents alone would leave the one lever
+                // this mechanism exists to deny wide open.
+                env_checkreserved(&eref, &reserved)?;
+                list.push(Value::str(&eref));
+            }
+            out.set(field, Value::List(list));
+            continue;
+        }
+
+        let enc = encoded
+            .iter()
+            .find(|e| rest == e.as_str() || rest.starts_with(&format!("{}_", e)));
+        let enc = match enc {
+            Some(e) => e.clone(),
+            None => continue, // not for any ref this host holds
+        };
+
+        let eref = byencoded[&enc][0].clone();
+        env_checkreserved(&eref, &reserved)?;
+
+        if rest == enc {
+            continue; // a ref with no path sets nothing
+        }
+
+        let path: Vec<String> = rest[enc.len() + 1..]
+            .to_lowercase()
+            .split('_')
+            .map(|s| s.to_string())
+            .collect();
+
+        let mut options = out.get("options");
+        if options.get(&eref).as_map().is_none() {
+            options.set(&eref, Value::map());
+        }
+        if let Value::Map(m) = &mut options {
+            if let Some(node) = m.get_mut(&eref) {
+                set_path(node, &path, env_parsevalue(&env.get(&key)));
+            }
+        }
+        out.set("options", options);
+    }
+
+    Ok(out)
+}
+
+/// Write a value at a dotted path, creating maps on the way down. A map is
+/// REPLACED when the path needs to descend through a scalar - the same
+/// rule every other port applies, and the reason it is written out here is
+/// that rust cannot express it as a chain of `//=`.
+fn set_path(node: &mut Value, path: &[String], value: Value) {
+    if 1 == path.len() {
+        node.set(&path[0], value);
+        return;
+    }
+    let key = &path[0];
+    if node.get(key).as_map().is_none() {
+        node.set(key, Value::map());
+    }
+    if let Value::Map(m) = node {
+        if let Some(child) = m.get_mut(key) {
+            set_path(child, &path[1..], value);
+        }
+    }
+}
+
+fn env_split(value: &Value) -> Vec<String> {
+    let text = value.as_str().unwrap_or("");
+    text.split(',')
+        .map(|p| p.trim().to_string())
+        .filter(|p| !p.is_empty())
+        .collect()
+}
+
+fn env_checkreserved(eref: &str, reserved: &Value) -> Result<(), PluginError> {
+    let list = match reserved.as_list() {
+        Some(l) if !l.is_empty() => l,
+        _ => return Ok(()),
+    };
+    let name = refname(eref);
+    if !list.iter().any(|r| r.as_str() == Some(name.as_str())) {
+        return Ok(());
+    }
+    fail(
+        "plugin_ref_reserved",
+        &format!("ref is reserved by the host: {}", eref),
+        details(&[("ref", Value::str(eref))]),
+    )
+}
+
+/// Values parse as JSON, FALLING BACK TO STRING - so `8080` is a number,
+/// `true` is a boolean, `{"a":1}` is a map, and `hello` is the string it
+/// looks like rather than a parse error.
+fn env_parsevalue(value: &Value) -> Value {
+    match value.as_str() {
+        Some(text) => value::parse(text).unwrap_or_else(|_| value.clone()),
+        None => value.clone(),
+    }
+}

package/project/.sdk/tm/rust/feature/secrets/plugin/export.rs

@@ -0,0 +1,90 @@
+// VENDORED: @voxgig/plugin sdk-20260908-1556-0 (rust/src/export.rs)
+// Source: https://github.com/voxgig/plugin @ 48392f5e2b6d1434ee9b1a4a9a11f4480aaeb46a  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+//! Exports (§11).
+//!
+//! An instance publishes values for other plugins and for the application.
+//! Read with `host.exports("retry$fast/client")`.
+//!
+//! THE UNQUALIFIED ALIAS IS THE INTERESTING PART. `retry/client` resolves
+//! to the UNTAGGED instance if one exists; if not, and exactly one tagged
+//! instance exports that key, it resolves to that one; if two do, it is
+//! `plugin_export_ambiguous` - deliberately diverging from seneca's silent
+//! last-wins, because with multi-instance as a headline feature an
+//! ambiguous alias is a defect waiting for production.
+
+use super::refs::{canon, parse_ref, refname};
+use super::types::{details, fail, PluginError};
+use super::value::Value;
+
+/// One published value: which instance, under which key.
+#[derive(Clone)]
+pub struct Exported {
+    pub eref: String,
+    pub key: String,
+    pub value: Value,
+}
+
+pub fn resolve_export(spec: &str, exported: &[Exported]) -> Result<Value, PluginError> {
+    let cut = match spec.find('/') {
+        Some(c) => c,
+        None => {
+            return fail(
+                "plugin_export_ambiguous",
+                &format!("export spec needs a key: {}", spec),
+                details(&[("spec", Value::str(spec))]),
+            )
+        }
+    };
+    let head = &spec[..cut];
+    let key = &spec[cut + 1..];
+
+    // A fully qualified ref: exactly one answer or none.
+    let want = canon(head);
+    for e in exported.iter() {
+        if e.eref == want && e.key == key {
+            return Ok(e.value.clone());
+        }
+    }
+
+    // An alias: the name, not a ref. Look at every instance of it.
+    let byname: Vec<&Exported> = exported
+        .iter()
+        .filter(|e| refname(&e.eref) == head && e.key == key)
+        .collect();
+    if byname.is_empty() {
+        return Ok(Value::Null);
+    }
+
+    for e in byname.iter() {
+        let parsed = parse_ref(&Value::str(&e.eref))?;
+        if parsed.get("tag").as_str().unwrap_or("").is_empty() {
+            return Ok(e.value.clone());
+        }
+    }
+
+    if 1 == byname.len() {
+        return Ok(byname[0].value.clone());
+    }
+
+    let mut refs: Vec<String> = byname.iter().map(|e| e.eref.clone()).collect();
+    refs.sort();
+    fail(
+        "plugin_export_ambiguous",
+        &format!(
+            "alias {} matches {} instances: {}",
+            spec,
+            refs.len(),
+            refs.join(", ")
+        ),
+        // `spec` is not one of §12's fields, so it does not render - the
+        // same detail map every other port builds, and the same message.
+        details(&[
+            ("spec", Value::str(spec)),
+            (
+                "refs",
+                Value::List(refs.iter().map(|r| Value::str(r)).collect()),
+            ),
+        ]),
+    )
+}