Struct NodeCtx

pub struct NodeCtx<'a> { /* private fields */ }

Context object for a FlowNode.

Implementations

impl<'ctx> NodeCtx<'ctx>

pub fn emit_rust_step<F, G>( &mut self, label: impl AsRef<str>, code: F, ) -> ReadVar<SideEffect>

where F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> Result<()> + 'static,

Emit a Rust-based step.

As a convenience feature, this function returns a special optional ReadVar<SideEffect>, which will not result in a “unused variable” error if no subsequent step ends up claiming it.

pub fn emit_minor_rust_step<F, G>( &mut self, label: impl AsRef<str>, code: F, ) -> ReadVar<SideEffect>

where F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) + 'static,

Emit a Rust-based step that cannot fail.

This is equivalent to emit_rust_step, but it is for steps that cannot fail and that do not need to be emitted as a separate step in a YAML pipeline. This simplifies the pipeline logs.

As a convenience feature, this function returns a special optional ReadVar<SideEffect>, which will not result in a “unused variable” error if no subsequent step ends up claiming it.

pub fn emit_rust_stepv<T, F, G>( &mut self, label: impl AsRef<str>, code: F, ) -> ReadVar<T>

where T: Serialize + DeserializeOwned + 'static, F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> Result<T> + 'static,

Emit a Rust-based step, creating a new ReadVar<T> from the step’s return value.

The var returned by this method is not secret. In order to create secret variables, use the ctx.new_var_secret() method.

This is a convenience function that streamlines the following common flowey pattern:

// creating a new Var explicitly
let (read_foo, write_foo) = ctx.new_var();
ctx.emit_rust_step("foo", |ctx| {
    let write_foo = write_foo.claim(ctx);
    |rt| {
        rt.write(write_foo, &get_foo());
        Ok(())
    }
});

// creating a new Var automatically
let read_foo = ctx.emit_rust_stepv("foo", |ctx| |rt| Ok(get_foo()));

pub fn emit_minor_rust_stepv<T, F, G>( &mut self, label: impl AsRef<str>, code: F, ) -> ReadVar<T>

where T: Serialize + DeserializeOwned + 'static, F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> T + 'static,

Emit a Rust-based step, creating a new ReadVar<T> from the step’s return value.

This is equivalent to emit_rust_stepv, but it is for steps that cannot fail and that do not need to be emitted as a separate step in a YAML pipeline. This simplifies the pipeline logs.

The var returned by this method is not secret. In order to create secret variables, use the ctx.new_var_secret() method.

This is a convenience function that streamlines the following common flowey pattern:

// creating a new Var explicitly
let (read_foo, write_foo) = ctx.new_var();
ctx.emit_minor_rust_step("foo", |ctx| {
    let write_foo = write_foo.claim(ctx);
    |rt| {
        rt.write(write_foo, &get_foo());
    }
});

// creating a new Var automatically
let read_foo = ctx.emit_minor_rust_stepv("foo", |ctx| |rt| get_foo());

pub fn get_ado_variable(&mut self, ado_var: AdoRuntimeVar) -> ReadVar<String>

Load an ADO global runtime variable into a flowey ReadVar.

pub fn emit_ado_step<F, G>( &mut self, display_name: impl AsRef<str>, yaml_snippet: F, )

where F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,

Emit an ADO step.

pub fn emit_ado_step_with_condition<F, G>( &mut self, display_name: impl AsRef<str>, cond: ReadVar<bool>, yaml_snippet: F, )

where F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,

Emit an ADO step, conditionally executed based on the value of cond at runtime.

pub fn emit_ado_step_with_condition_optional<F, G>( &mut self, display_name: impl AsRef<str>, cond: Option<ReadVar<bool>>, yaml_snippet: F, )

where F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G, G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,

Emit an ADO step, conditionally executed based on the value ofcond at runtime.

pub fn emit_ado_step_with_inline_script<F, G, H>( &mut self, display_name: impl AsRef<str>, yaml_snippet: F, )

where F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> (G, H), G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static, H: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> Result<()> + 'static,

Emit an ADO step which invokes a rust callback using an inline script.

By using the {{FLOWEY_INLINE_SCRIPT}} template in the returned yaml snippet, flowey will interpolate a command ~roughly akin to flowey exec-snippet <rust-snippet-id> into the generated yaml.

e.g: if we wanted to manually wrap the bash ADO snippet for whatever reason:

- bash: |
    echo "hello there!"
    {{FLOWEY_INLINE_SCRIPT}}
    echo echo "bye!"

Limitations

At the moment, due to flowey API limitations, it is only possible to embed a single inline script into a YAML step.

In the future, rather than having separate methods for “emit step with X inline scripts”, flowey should support declaring “first-class” callbacks via a (hypothetical) ctx.new_callback_var(|ctx| |rt, input: Input| -> Output { ... }) API, at which point.

If such an API were to exist, one could simply use the “vanilla” emit yaml step functions with these first-class callbacks.

pub fn get_gh_context_var(&mut self) -> GhContextVarReader<'ctx, Root>

Load a GitHub context variable into a flowey ReadVar.

pub fn emit_gh_step( &mut self, display_name: impl AsRef<str>, uses: impl AsRef<str>, ) -> GhStepBuilder

Emit a GitHub Actions action step.

pub fn emit_side_effect_step( &mut self, use_side_effects: impl IntoIterator<Item = ReadVar<SideEffect>>, resolve_side_effects: impl IntoIterator<Item = WriteVar<SideEffect>>, )

Emit a “side-effect” step, which simply claims a set of side-effects in order to resolve another set of side effects.

The same functionality could be achieved (less efficiently) by emitting a Rust step (or ADO step, or github step, etc…) that claims both sets of side-effects, and then does nothing. By using this method - flowey is able to avoid emitting that additional noop step at runtime.

pub fn backend(&self) -> FlowBackend

What backend the flow is being running on (e.g: locally, ADO, GitHub, etc…)

pub fn platform(&self) -> FlowPlatform

What platform the flow is being running on (e.g: windows, linux, wsl2, etc…).

pub fn arch(&self) -> FlowArch

What architecture the flow is being running on (x86_64 or Aarch64)

pub fn req<R>(&mut self, req: R)

where R: IntoRequest + 'static,

Set a request on a particular node.

pub fn reqv<T, R>(&mut self, f: impl FnOnce(WriteVar<T>) -> R) -> ReadVar<T>

where T: Serialize + DeserializeOwned, R: IntoRequest + 'static,

Set a request on a particular node, simultaneously creating a new flowey Var in the process.

pub fn requests<N>(&mut self, reqs: impl IntoIterator<Item = N::Request>)

where N: FlowNodeBase + 'static,

Set multiple requests on a particular node.

pub fn new_var<T>(&self) -> (ReadVar<T>, WriteVar<T>)

where T: Serialize + DeserializeOwned,

Allocate a new flowey Var, returning two handles: one for reading the value, and another for writing the value.

This will return a non-secret Var, and its value may be displayed in logs and other output.

pub fn new_secret_var<T>(&self) -> (ReadVar<T>, WriteVar<T>)

where T: Serialize + DeserializeOwned,

Allocate a new secret flowey Var, returning two handles: one for reading the value, and another for writing the value.

A secret Var must not be displayed in logs or other output.

pub fn new_post_job_side_effect( &self, ) -> (ReadVar<SideEffect>, WriteVar<SideEffect>)

Allocate special SideEffect var which can be used to schedule a “post-job” step associated with some existing step.

This “post-job” step will then only run after all other regular steps have run (i.e: steps required to complete any top-level objectives passed in via crate::pipeline::PipelineJob::dep_on). This makes it useful for implementing various “cleanup” or “finalize” tasks.

e.g: the Cache node uses this to upload the contents of a cache directory at the end of a Job.

pub fn persistent_dir(&mut self) -> Option<ReadVar<PathBuf>>

Return a flowey Var pointing to a node-specific directory which will be persisted between runs, if such a directory is available.

WARNING: this method is very likely to return None when running on CI machines, as most CI agents are wiped between jobs!

As such, it is NOT recommended that node authors reach for this method directly, and instead use abstractions such as the flowey_lib_common::cache Node, which implements node-level persistence in a way that works regardless if a persistent_dir is available (e.g: by falling back to uploading / downloading artifacts to a “cache store” on platforms like ADO or Github Actions).

pub fn supports_persistent_dir(&mut self) -> bool

Check to see if a persistent dir is available, without yet creating it.