pub struct EnvironmentDeclaration { /* private fields */ }Expand description
The environment pass-through allow-list a document declares: variable NAMES, in the order they were written.
Order is preserved because it is the operator’s own; duplicates are preserved for the
same reason and collapse when the environment is built, where a later name simply
resolves to the same value. Nothing here reads a value: this is the declaration, and
Self::resolve is where it meets a launching context.
Implementations§
Source§impl EnvironmentDeclaration
impl EnvironmentDeclaration
Sourcepub fn new(
names: impl IntoIterator<Item = impl Into<String>>,
) -> Result<Self, EnvironmentError>
pub fn new( names: impl IntoIterator<Item = impl Into<String>>, ) -> Result<Self, EnvironmentError>
The declaration carrying names.
§Errors
Returns EnvironmentError::EmptyName for a blank entry and
EnvironmentError::NameContainsEquals for a KEY=VALUE pair — the two ways an
entry can look like a declaration without being one.
Sourcepub fn empty() -> Self
pub fn empty() -> Self
The declaration naming NO variable.
Infallible, because there is no entry to be malformed. A child launched under it gets a genuinely empty environment, which is a coherent thing for an absolute command that needs nothing at all.
It is reachable only from a hand-written composition root, and that is deliberate
rather than an oversight in the grammar: a worker DOCUMENT cannot express it,
because env_pass takes one or more names and there is no spelling for none. An
empty list in a file is indistinguishable from an unfinished line, and the cost of
reading one as the other is an agent launched with no PATH, no HOME and no
credentials, failing three layers down for a reason nobody wrote. A caller
constructing this in code has stated it unambiguously; an author typing it into a
document has not. If the hermetic-empty case is ever wanted from a document it
needs its own explicit spelling, not a permissive reading of an empty list.
Sourcepub fn resolve(&self, context: &BTreeMap<String, String>) -> ChildEnvironment
pub fn resolve(&self, context: &BTreeMap<String, String>) -> ChildEnvironment
Resolves the declaration against context — a snapshot of the launching process’s
environment — into the exact, total environment a child receives.
A declared name absent from context contributes NO variable: an unset variable
and a variable set to the empty string are different things, and inventing one for
the other would be a value nobody wrote. Which names came up absent is kept on the
result so a launcher can say so rather than leave the operator guessing.
Sourcepub fn resolve_from_process(&self) -> ChildEnvironment
pub fn resolve_from_process(&self) -> ChildEnvironment
Resolves the declaration against THIS process’s environment.
The launching context of a worker that spawns its own harness children. Non-UTF-8 names and values are skipped rather than lossily transcoded: a mangled credential is worse than an absent one, and an absent one is reported.
Trait Implementations§
Source§impl Clone for EnvironmentDeclaration
impl Clone for EnvironmentDeclaration
Source§fn clone(&self) -> EnvironmentDeclaration
fn clone(&self) -> EnvironmentDeclaration
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more