GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/openvmm

Public

mirrored from https://github.com/microsoft/openvmmAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
045b1b0dbef400c88d68fce3fbe84ee2cedb2fa2

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

openvmm/flowey/flowey_core/src

flowey/flowey_core/src/node.rs

3026lines · modecode

RawDownload
Latest commit unavailable.
1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4//! Core types and traits used to create and work with flowey nodes.
5
6mod github_context;
7mod spec;
8
9pub use github_context::GhOutput;
10pub use github_context::GhToRust;
11pub use github_context::RustToGh;
12
13use self::steps::ado::AdoRuntimeVar;
14use self::steps::ado::AdoStepServices;
15use self::steps::github::GhStepBuilder;
16use self::steps::rust::RustRuntimeServices;
17use self::user_facing::ClaimedGhParam;
18use self::user_facing::GhPermission;
19use self::user_facing::GhPermissionValue;
20use crate::node::github_context::GhContextVarReader;
21use github_context::state::Root;
22use serde::Deserialize;
23use serde::Serialize;
24use serde::de::DeserializeOwned;
25use std::cell::RefCell;
26use std::collections::BTreeMap;
27use std::path::PathBuf;
28use std::rc::Rc;
29use user_facing::GhParam;
30
31/// Node types which are considered "user facing", and re-exported in the
32/// `flowey` crate.
33pub mod user_facing {
34 pub use super::ClaimVar;
35 pub use super::ClaimedReadVar;
36 pub use super::ClaimedWriteVar;
37 pub use super::FlowArch;
38 pub use super::FlowBackend;
39 pub use super::FlowNode;
40 pub use super::FlowPlatform;
41 pub use super::FlowPlatformKind;
42 pub use super::GhUserSecretVar;
43 pub use super::ImportCtx;
44 pub use super::IntoRequest;
45 pub use super::NodeCtx;
46 pub use super::ReadVar;
47 pub use super::SideEffect;
48 pub use super::SimpleFlowNode;
49 pub use super::StepCtx;
50 pub use super::VarClaimed;
51 pub use super::VarEqBacking;
52 pub use super::VarNotClaimed;
53 pub use super::WriteVar;
54 pub use super::steps::ado::AdoResourcesRepositoryId;
55 pub use super::steps::ado::AdoRuntimeVar;
56 pub use super::steps::ado::AdoStepServices;
57 pub use super::steps::github::ClaimedGhParam;
58 pub use super::steps::github::GhParam;
59 pub use super::steps::github::GhPermission;
60 pub use super::steps::github::GhPermissionValue;
61 pub use super::steps::rust::RustRuntimeServices;
62 pub use crate::flowey_request;
63 pub use crate::new_flow_node;
64 pub use crate::new_simple_flow_node;
65 pub use crate::node::FlowPlatformLinuxDistro;
66 pub use crate::pipeline::Artifact;
67
68 /// Helper method to streamline request validation in cases where a value is
69 /// expected to be identical across all incoming requests.
70 ///
71 /// # Example: Request Aggregation Pattern
72 ///
73 /// When a node receives multiple requests, it often needs to ensure certain
74 /// values are consistent across all requests. This helper simplifies that pattern:
75 ///
76 /// ```rust,ignore
77 /// fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()> {
78 /// let mut version = None;
79 /// let mut ensure_installed = Vec::new();
80 ///
81 /// for req in requests {
82 /// match req {
83 /// Request::Version(v) => {
84 /// // Ensure all requests agree on the version
85 /// same_across_all_reqs("Version", &mut version, v)?;
86 /// }
87 /// Request::EnsureInstalled(v) => {
88 /// ensure_installed.push(v);
89 /// }
90 /// }
91 /// }
92 ///
93 /// let version = version.ok_or(anyhow::anyhow!("Missing required request: Version"))?;
94 ///
95 /// // ... emit steps using aggregated requests
96 /// Ok(())
97 /// }
98 /// ```
99 pub fn same_across_all_reqs<T: PartialEq>(
100 req_name: &str,
101 var: &mut Option<T>,
102 new: T,
103 ) -> anyhow::Result<()> {
104 match (var.as_ref(), new) {
105 (None, v) => *var = Some(v),
106 (Some(old), new) => {
107 if *old != new {
108 anyhow::bail!("`{}` must be consistent across requests", req_name);
109 }
110 }
111 }
112
113 Ok(())
114 }
115
116 /// Helper method to streamline request validation in cases where a value is
117 /// expected to be identical across all incoming requests, using a custom
118 /// comparison function.
119 pub fn same_across_all_reqs_backing_var<V: VarEqBacking>(
120 req_name: &str,
121 var: &mut Option<V>,
122 new: V,
123 ) -> anyhow::Result<()> {
124 match (var.as_ref(), new) {
125 (None, v) => *var = Some(v),
126 (Some(old), new) => {
127 if !old.eq(&new) {
128 anyhow::bail!("`{}` must be consistent across requests", req_name);
129 }
130 }
131 }
132
133 Ok(())
134 }
135
136 /// Helper method to handle Linux distros that are supported only on one
137 /// host architecture.
138 /// match_arch!(var, arch, result)
139 #[macro_export]
140 macro_rules! match_arch {
141 ($host_arch:expr, $match_arch:pat, $expr:expr) => {
142 if matches!($host_arch, $match_arch) {
143 $expr
144 } else {
145 anyhow::bail!("Linux distro not supported on host arch {}", $host_arch);
146 }
147 };
148 }
149}
150
151/// Check if `ReadVar` / `WriteVar` instances are backed by the same underlying
152/// flowey Var.
153///
154/// # Why not use `Eq`? Why have a whole separate trait?
155///
156/// `ReadVar` and `WriteVar` are, in some sense, flowey's analog to
157/// "pointers", insofar as these types primary purpose is to mediate access to
158/// some contained value, as opposed to being "values" themselves.
159///
160/// Assuming you agree with this analogy, then we can apply the same logic to
161/// `ReadVar` and `WriteVar` as Rust does to `Box<T>` wrt. what the `Eq`
162/// implementation should mean.
163///
164/// Namely: `Eq` should check the equality of the _contained objects_, as
165/// opposed to the pointers themselves.
166///
167/// Unfortunately, unlike `Box<T>`, it is _impossible_ to have an `Eq` impl for
168/// `ReadVar` / `WriteVar` that checks contents for equality, due to the fact
169/// that these types exist at flow resolution time, whereas the values they
170/// contain only exist at flow runtime.
171///
172/// As such, we have a separate trait to perform different kinds of equality
173/// checks on Vars.
174pub trait VarEqBacking {
175 /// Check if `self` is backed by the same variable as `other`.
176 fn eq(&self, other: &Self) -> bool;
177}
178
179impl<T> VarEqBacking for WriteVar<T>
180where
181 T: Serialize + DeserializeOwned,
182{
183 fn eq(&self, other: &Self) -> bool {
184 self.backing_var == other.backing_var
185 }
186}
187
188impl<T> VarEqBacking for ReadVar<T>
189where
190 T: Serialize + DeserializeOwned + PartialEq + Eq + Clone,
191{
192 fn eq(&self, other: &Self) -> bool {
193 self.backing_var == other.backing_var
194 }
195}
196
197// TODO: this should be generic across all tuple sizes
198impl<T, U> VarEqBacking for (T, U)
199where
200 T: VarEqBacking,
201 U: VarEqBacking,
202{
203 fn eq(&self, other: &Self) -> bool {
204 (self.0.eq(&other.0)) && (self.1.eq(&other.1))
205 }
206}
207
208/// Type corresponding to a step which performs a side-effect,
209/// without returning a specific value.
210///
211/// e.g: A step responsible for installing a package from `apt` might claim a
212/// `WriteVar<SideEffect>`, with any step requiring the package to have been
213/// installed prior being able to claim the corresponding `ReadVar<SideEffect>.`
214pub type SideEffect = ();
215
216/// Uninhabited type used to denote that a particular [`WriteVar`] / [`ReadVar`]
217/// is not currently claimed by any step, and cannot be directly accessed.
218#[derive(Clone, Debug, Serialize, Deserialize)]
219pub enum VarNotClaimed {}
220
221/// Uninhabited type used to denote that a particular [`WriteVar`] / [`ReadVar`]
222/// is currently claimed by a step, and can be read/written to.
223#[derive(Clone, Debug, Serialize, Deserialize)]
224pub enum VarClaimed {}
225
226/// Write a value into a flowey Var at runtime, which can then be read via a
227/// corresponding [`ReadVar`].
228///
229/// Vars in flowey must be serde de/serializable, in order to be de/serialized
230/// between multiple steps/nodes.
231///
232/// In order to write a value into a `WriteVar`, it must first be _claimed_ by a
233/// particular step (using the [`ClaimVar::claim`] API). Once claimed, the Var
234/// can be written to using APIs such as [`RustRuntimeServices::write`], or
235/// [`AdoStepServices::set_var`]
236///
237/// Note that it is only possible to write a value into a `WriteVar` _once_.
238/// Once the value has been written, the `WriteVar` type is immediately
239/// consumed, making it impossible to overwrite the stored value at some later
240/// point in execution.
241///
242/// This "write-once" property is foundational to flowey's execution model, as
243/// by recoding what step wrote to a Var, and what step(s) read from the Var, it
244/// is possible to infer what order steps must be run in.
245#[derive(Debug, Serialize, Deserialize)]
246pub struct WriteVar<T: Serialize + DeserializeOwned, C = VarNotClaimed> {
247 backing_var: String,
248 /// If true, then readers on this var expect to read a side effect (`()`)
249 /// and not `T`.
250 is_side_effect: bool,
251
252 #[serde(skip)]
253 _kind: core::marker::PhantomData<(T, C)>,
254}
255
256/// A [`WriteVar`] which has been claimed by a particular step, allowing it
257/// to be written to at runtime.
258pub type ClaimedWriteVar<T> = WriteVar<T, VarClaimed>;
259
260impl<T: Serialize + DeserializeOwned> WriteVar<T, VarNotClaimed> {
261 /// (Internal API) Switch the claim marker to "claimed".
262 fn into_claimed(self) -> WriteVar<T, VarClaimed> {
263 let Self {
264 backing_var,
265 is_side_effect,
266 _kind,
267 } = self;
268
269 WriteVar {
270 backing_var,
271 is_side_effect,
272 _kind: std::marker::PhantomData,
273 }
274 }
275
276 /// Write a static value into the Var.
277 #[track_caller]
278 pub fn write_static(self, ctx: &mut NodeCtx<'_>, val: T)
279 where
280 T: 'static,
281 {
282 let val = ReadVar::from_static(val);
283 val.write_into(ctx, self, |v| v);
284 }
285
286 pub(crate) fn into_json(self) -> WriteVar<serde_json::Value> {
287 WriteVar {
288 backing_var: self.backing_var,
289 is_side_effect: self.is_side_effect,
290 _kind: std::marker::PhantomData,
291 }
292 }
293}
294
295impl WriteVar<SideEffect, VarNotClaimed> {
296 /// Transforms this writer into one that can be used to write a `T`.
297 ///
298 /// This is useful when a reader only cares about the side effect of an
299 /// operation, but the writer wants to provide output as well.
300 pub fn discard_result<T: Serialize + DeserializeOwned>(self) -> WriteVar<T> {
301 WriteVar {
302 backing_var: self.backing_var,
303 is_side_effect: true,
304 _kind: std::marker::PhantomData,
305 }
306 }
307}
308
309/// Claim one or more flowey Vars for a particular step.
310///
311/// By having this be a trait, it is possible to `claim` both single instances
312/// of `ReadVar` / `WriteVar`, as well as whole _collections_ of Vars.
313//
314// FUTURE: flowey should include a derive macro for easily claiming read/write
315// vars in user-defined structs / enums.
316pub trait ClaimVar {
317 /// The claimed version of Self.
318 type Claimed;
319 /// Claim the Var for this step, allowing it to be accessed at runtime.
320 fn claim(self, ctx: &mut StepCtx<'_>) -> Self::Claimed;
321}
322
323/// Read the value of one or more flowey Vars.
324///
325/// By having this be a trait, it is possible to `read` both single
326/// instances of `ReadVar` / `WriteVar`, as well as whole _collections_ of
327/// Vars.
328pub trait ReadVarValue {
329 /// The read value of Self.
330 type Value;
331 /// Read the value of the Var at runtime.
332 fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value;
333}
334
335impl<T: Serialize + DeserializeOwned> ClaimVar for ReadVar<T> {
336 type Claimed = ClaimedReadVar<T>;
337
338 fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedReadVar<T> {
339 if let ReadVarBacking::RuntimeVar {
340 var,
341 is_side_effect: _,
342 } = &self.backing_var
343 {
344 ctx.backend.borrow_mut().on_claimed_runtime_var(var, true);
345 }
346 self.into_claimed()
347 }
348}
349
350impl<T: Serialize + DeserializeOwned> ClaimVar for WriteVar<T> {
351 type Claimed = ClaimedWriteVar<T>;
352
353 fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedWriteVar<T> {
354 ctx.backend
355 .borrow_mut()
356 .on_claimed_runtime_var(&self.backing_var, false);
357 self.into_claimed()
358 }
359}
360
361impl<T: Serialize + DeserializeOwned> ReadVarValue for ClaimedReadVar<T> {
362 type Value = T;
363
364 fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
365 match self.backing_var {
366 ReadVarBacking::RuntimeVar {
367 var,
368 is_side_effect,
369 } => {
370 // Always get the data to validate that the variable is actually there.
371 let data = rt.get_var(&var, is_side_effect);
372 if is_side_effect {
373 // This was converted into a `ReadVar<SideEffect>` from
374 // another type, so parse the value that a
375 // `WriteVar<SideEffect>` would have written.
376 serde_json::from_slice(b"null").expect("should be deserializing into ()")
377 } else {
378 // This is a normal variable.
379 serde_json::from_slice(&data).expect("improve this error path")
380 }
381 }
382 ReadVarBacking::Inline(val) => val,
383 }
384 }
385}
386
387impl<T: ClaimVar> ClaimVar for Vec<T> {
388 type Claimed = Vec<T::Claimed>;
389
390 fn claim(self, ctx: &mut StepCtx<'_>) -> Vec<T::Claimed> {
391 self.into_iter().map(|v| v.claim(ctx)).collect()
392 }
393}
394
395impl<T: ReadVarValue> ReadVarValue for Vec<T> {
396 type Value = Vec<T::Value>;
397
398 fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
399 self.into_iter().map(|v| v.read_value(rt)).collect()
400 }
401}
402
403impl<T: ClaimVar> ClaimVar for Option<T> {
404 type Claimed = Option<T::Claimed>;
405
406 fn claim(self, ctx: &mut StepCtx<'_>) -> Option<T::Claimed> {
407 self.map(|x| x.claim(ctx))
408 }
409}
410
411impl<T: ReadVarValue> ReadVarValue for Option<T> {
412 type Value = Option<T::Value>;
413
414 fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
415 self.map(|x| x.read_value(rt))
416 }
417}
418
419impl<U: Ord, T: ClaimVar> ClaimVar for BTreeMap<U, T> {
420 type Claimed = BTreeMap<U, T::Claimed>;
421
422 fn claim(self, ctx: &mut StepCtx<'_>) -> BTreeMap<U, T::Claimed> {
423 self.into_iter().map(|(k, v)| (k, v.claim(ctx))).collect()
424 }
425}
426
427impl<U: Ord, T: ReadVarValue> ReadVarValue for BTreeMap<U, T> {
428 type Value = BTreeMap<U, T::Value>;
429
430 fn read_value(self, rt: &mut RustRuntimeServices<'_>) -> Self::Value {
431 self.into_iter()
432 .map(|(k, v)| (k, v.read_value(rt)))
433 .collect()
434 }
435}
436
437macro_rules! impl_tuple_claim {
438 ($($T:tt)*) => {
439 impl<$($T,)*> $crate::node::ClaimVar for ($($T,)*)
440 where
441 $($T: $crate::node::ClaimVar,)*
442 {
443 type Claimed = ($($T::Claimed,)*);
444
445 #[expect(non_snake_case)]
446 fn claim(self, ctx: &mut $crate::node::StepCtx<'_>) -> Self::Claimed {
447 let ($($T,)*) = self;
448 ($($T.claim(ctx),)*)
449 }
450 }
451
452 impl<$($T,)*> $crate::node::ReadVarValue for ($($T,)*)
453 where
454 $($T: $crate::node::ReadVarValue,)*
455 {
456 type Value = ($($T::Value,)*);
457
458 #[expect(non_snake_case)]
459 fn read_value(self, rt: &mut $crate::node::RustRuntimeServices<'_>) -> Self::Value {
460 let ($($T,)*) = self;
461 ($($T.read_value(rt),)*)
462 }
463 }
464 };
465}
466
467impl_tuple_claim!(A B C D E F G H I J);
468impl_tuple_claim!(A B C D E F G H I);
469impl_tuple_claim!(A B C D E F G H);
470impl_tuple_claim!(A B C D E F G);
471impl_tuple_claim!(A B C D E F);
472impl_tuple_claim!(A B C D E);
473impl_tuple_claim!(A B C D);
474impl_tuple_claim!(A B C);
475impl_tuple_claim!(A B);
476impl_tuple_claim!(A);
477
478impl ClaimVar for () {
479 type Claimed = ();
480
481 fn claim(self, _ctx: &mut StepCtx<'_>) -> Self::Claimed {}
482}
483
484impl ReadVarValue for () {
485 type Value = ();
486
487 fn read_value(self, _rt: &mut RustRuntimeServices<'_>) -> Self::Value {}
488}
489
490/// Read a custom, user-defined secret by passing in the secret name.
491///
492/// Intended usage is to get a secret using the [`crate::pipeline::Pipeline::gh_use_secret`] API
493/// and to use the returned value through the [`NodeCtx::get_gh_context_var`] API.
494#[derive(Serialize, Deserialize, Clone)]
495pub struct GhUserSecretVar(pub(crate) String);
496
497/// Read a value from a flowey Var at runtime, returning the value written by
498/// the Var's corresponding [`WriteVar`].
499///
500/// Vars in flowey must be serde de/serializable, in order to be de/serialized
501/// between multiple steps/nodes.
502///
503/// In order to read the value contained within a `ReadVar`, it must first be
504/// _claimed_ by a particular step (using the [`ClaimVar::claim`] API). Once
505/// claimed, the Var can be read using APIs such as
506/// [`RustRuntimeServices::read`], or [`AdoStepServices::get_var`]
507///
508/// Note that all `ReadVar`s in flowey are _immutable_. In other words:
509/// reading the value of a `ReadVar` multiple times from multiple nodes will
510/// _always_ return the same value.
511///
512/// This is a natural consequence `ReadVar` obtaining its value from the result
513/// of a write into [`WriteVar`], whose API enforces that there can only ever be
514/// a single Write to a `WriteVar`.
515#[derive(Debug, Serialize, Deserialize)]
516pub struct ReadVar<T, C = VarNotClaimed> {
517 backing_var: ReadVarBacking<T>,
518 #[serde(skip)]
519 _kind: std::marker::PhantomData<C>,
520}
521
522/// A [`ReadVar`] which has been claimed by a particular step, allowing it to
523/// be read at runtime.
524pub type ClaimedReadVar<T> = ReadVar<T, VarClaimed>;
525
526// cloning is fine, since you can totally have multiple dependents
527impl<T: Serialize + DeserializeOwned, C> Clone for ReadVar<T, C> {
528 fn clone(&self) -> Self {
529 ReadVar {
530 backing_var: self.backing_var.clone(),
531 _kind: std::marker::PhantomData,
532 }
533 }
534}
535
536#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
537enum ReadVarBacking<T> {
538 RuntimeVar {
539 var: String,
540 /// If true, then don't try to parse this variable--it was converted
541 /// into a side effect (of type `()`) from another type, so the
542 /// serialization will not match.
543 ///
544 /// If false, it may still be a "side effect" variable, but type `T`
545 /// matches its serialization.
546 is_side_effect: bool,
547 },
548 Inline(T),
549}
550
551// avoid requiring types to include an explicit clone bound
552impl<T: Serialize + DeserializeOwned> Clone for ReadVarBacking<T> {
553 fn clone(&self) -> Self {
554 match self {
555 Self::RuntimeVar {
556 var,
557 is_side_effect,
558 } => Self::RuntimeVar {
559 var: var.clone(),
560 is_side_effect: *is_side_effect,
561 },
562 Self::Inline(v) => {
563 Self::Inline(serde_json::from_value(serde_json::to_value(v).unwrap()).unwrap())
564 }
565 }
566 }
567}
568
569impl<T: Serialize + DeserializeOwned> ReadVar<T> {
570 /// (Internal API) Switch the claim marker to "claimed".
571 fn into_claimed(self) -> ReadVar<T, VarClaimed> {
572 let Self { backing_var, _kind } = self;
573
574 ReadVar {
575 backing_var,
576 _kind: std::marker::PhantomData,
577 }
578 }
579
580 /// Discard any type information associated with the Var, and treat the Var
581 /// as through it was only a side effect.
582 ///
583 /// e.g: if a Node returns a `ReadVar<PathBuf>`, but you know that the mere
584 /// act of having _run_ the node has ensured the file is placed in a "magic
585 /// location" for some other node, then it may be useful to treat the
586 /// `ReadVar<PathBuf>` as a simple `ReadVar<SideEffect>`, which can be
587 /// passed along as part of a larger bundle of `Vec<ReadVar<SideEffect>>`.
588 #[must_use]
589 pub fn into_side_effect(self) -> ReadVar<SideEffect> {
590 ReadVar {
591 backing_var: match self.backing_var {
592 ReadVarBacking::RuntimeVar {
593 var,
594 is_side_effect: _,
595 } => ReadVarBacking::RuntimeVar {
596 var,
597 is_side_effect: true,
598 },
599 ReadVarBacking::Inline(_) => ReadVarBacking::Inline(()),
600 },
601 _kind: std::marker::PhantomData,
602 }
603 }
604
605 /// Maps a `ReadVar<T>` to a new `ReadVar<U>`, by applying a function to the
606 /// Var at runtime.
607 #[track_caller]
608 #[must_use]
609 pub fn map<F, U>(&self, ctx: &mut NodeCtx<'_>, f: F) -> ReadVar<U>
610 where
611 T: 'static,
612 U: Serialize + DeserializeOwned + 'static,
613 F: FnOnce(T) -> U + 'static,
614 {
615 let (read_from, write_into) = ctx.new_var();
616 self.write_into(ctx, write_into, f);
617 read_from
618 }
619
620 /// Maps a `ReadVar<T>` into an existing `WriteVar<U>` by applying a
621 /// function to the Var at runtime.
622 #[track_caller]
623 pub fn write_into<F, U>(&self, ctx: &mut NodeCtx<'_>, write_into: WriteVar<U>, f: F)
624 where
625 T: 'static,
626 U: Serialize + DeserializeOwned + 'static,
627 F: FnOnce(T) -> U + 'static,
628 {
629 let this = self.clone();
630 ctx.emit_minor_rust_step("🌼 write_into Var", move |ctx| {
631 let this = this.claim(ctx);
632 let write_into = write_into.claim(ctx);
633 move |rt| {
634 let this = rt.read(this);
635 rt.write(write_into, &f(this));
636 }
637 });
638 }
639
640 /// Zips self (`ReadVar<T>`) with another `ReadVar<U>`, returning a new
641 /// `ReadVar<(T, U)>`
642 #[track_caller]
643 #[must_use]
644 pub fn zip<U>(&self, ctx: &mut NodeCtx<'_>, other: ReadVar<U>) -> ReadVar<(T, U)>
645 where
646 T: 'static,
647 U: Serialize + DeserializeOwned + 'static,
648 {
649 let (read_from, write_into) = ctx.new_var();
650 let this = self.clone();
651 ctx.emit_minor_rust_step("🌼 Zip Vars", move |ctx| {
652 let this = this.claim(ctx);
653 let other = other.claim(ctx);
654 let write_into = write_into.claim(ctx);
655 move |rt| {
656 let this = rt.read(this);
657 let other = rt.read(other);
658 rt.write(write_into, &(this, other));
659 }
660 });
661 read_from
662 }
663
664 /// Create a new `ReadVar` from a static value.
665 ///
666 /// **WARNING:** Static values **CANNOT BE SECRETS**, as they are encoded as
667 /// plain-text in the output flow.
668 #[track_caller]
669 #[must_use]
670 pub fn from_static(val: T) -> ReadVar<T>
671 where
672 T: 'static,
673 {
674 ReadVar {
675 backing_var: ReadVarBacking::Inline(val),
676 _kind: std::marker::PhantomData,
677 }
678 }
679
680 /// If this [`ReadVar`] contains a static value, return it.
681 ///
682 /// Nodes can opt-in to using this method as a way to generate optimized
683 /// steps in cases where the value of a variable is known ahead of time.
684 ///
685 /// e.g: a node doing a git checkout could leverage this method to decide
686 /// whether its ADO backend should emit a conditional step for checking out
687 /// a repo, or if it can statically include / exclude the checkout request.
688 pub fn get_static(&self) -> Option<T> {
689 match self.clone().backing_var {
690 ReadVarBacking::Inline(v) => Some(v),
691 _ => None,
692 }
693 }
694
695 /// Transpose a `Vec<ReadVar<T>>` into a `ReadVar<Vec<T>>`
696 #[track_caller]
697 #[must_use]
698 pub fn transpose_vec(ctx: &mut NodeCtx<'_>, vec: Vec<ReadVar<T>>) -> ReadVar<Vec<T>>
699 where
700 T: 'static,
701 {
702 let (read_from, write_into) = ctx.new_var();
703 ctx.emit_minor_rust_step("🌼 Transpose Vec<ReadVar<T>>", move |ctx| {
704 let vec = vec.claim(ctx);
705 let write_into = write_into.claim(ctx);
706 move |rt| {
707 let mut v = Vec::new();
708 for var in vec {
709 v.push(rt.read(var));
710 }
711 rt.write(write_into, &v);
712 }
713 });
714 read_from
715 }
716
717 /// Returns a new instance of this variable with an artificial dependency on
718 /// `other`.
719 ///
720 /// This is useful for making explicit a non-explicit dependency between the
721 /// two variables. For example, if `self` contains a path to a file, and
722 /// `other` is only written once that file has been created, then this
723 /// method can be used to return a new `ReadVar` which depends on `other`
724 /// but is otherwise identical to `self`. This ensures that when the new
725 /// variable is read, the file has been created.
726 ///
727 /// In general, it is better to ensure that the dependency is explicit, so
728 /// that if you have a variable with a path, then you know that the file
729 /// exists when you read it. This method is useful in cases where this is
730 /// not naturally the case, e.g., when you are providing a path as part of a
731 /// request, as opposed to the path being returned to you.
732 #[must_use]
733 pub fn depending_on<U>(&self, ctx: &mut NodeCtx<'_>, other: &ReadVar<U>) -> Self
734 where
735 T: 'static,
736 U: Serialize + DeserializeOwned + 'static,
737 {
738 // This could probably be handled without an additional Rust step with some
739 // additional work in the backend, but this is simple enough for now.
740 ctx.emit_minor_rust_stepv("🌼 Add dependency", |ctx| {
741 let this = self.clone().claim(ctx);
742 other.clone().claim(ctx);
743 move |rt| rt.read(this)
744 })
745 }
746
747 /// Consume this `ReadVar` outside the context of a step, signalling that it
748 /// won't be used.
749 pub fn claim_unused(self, ctx: &mut NodeCtx<'_>) {
750 match self.backing_var {
751 ReadVarBacking::RuntimeVar {
752 var,
753 is_side_effect: _,
754 } => ctx.backend.borrow_mut().on_unused_read_var(&var),
755 ReadVarBacking::Inline(_) => {}
756 }
757 }
758
759 pub(crate) fn into_json(self) -> ReadVar<serde_json::Value> {
760 match self.backing_var {
761 ReadVarBacking::RuntimeVar {
762 var,
763 is_side_effect,
764 } => ReadVar {
765 backing_var: ReadVarBacking::RuntimeVar {
766 var,
767 is_side_effect,
768 },
769 _kind: std::marker::PhantomData,
770 },
771 ReadVarBacking::Inline(v) => ReadVar {
772 backing_var: ReadVarBacking::Inline(serde_json::to_value(v).unwrap()),
773 _kind: std::marker::PhantomData,
774 },
775 }
776 }
777}
778
779/// DANGER: obtain a handle to a [`ReadVar`] "out of thin air".
780///
781/// This should NEVER be used from within a flowey node. This is a sharp tool,
782/// and should only be used by code implementing flow / pipeline resolution
783/// logic.
784#[must_use]
785pub fn thin_air_read_runtime_var<T>(backing_var: String) -> ReadVar<T>
786where
787 T: Serialize + DeserializeOwned,
788{
789 ReadVar {
790 backing_var: ReadVarBacking::RuntimeVar {
791 var: backing_var,
792 is_side_effect: false,
793 },
794 _kind: std::marker::PhantomData,
795 }
796}
797
798/// DANGER: obtain a handle to a [`WriteVar`] "out of thin air".
799///
800/// This should NEVER be used from within a flowey node. This is a sharp tool,
801/// and should only be used by code implementing flow / pipeline resolution
802/// logic.
803#[must_use]
804pub fn thin_air_write_runtime_var<T>(backing_var: String) -> WriteVar<T>
805where
806 T: Serialize + DeserializeOwned,
807{
808 WriteVar {
809 backing_var,
810 is_side_effect: false,
811 _kind: std::marker::PhantomData,
812 }
813}
814
815/// DANGER: obtain a [`ReadVar`] backing variable and side effect status.
816///
817/// This should NEVER be used from within a flowey node. This relies on
818/// flowey variable implementation details, and should only be used by code
819/// implementing flow / pipeline resolution logic.
820pub fn read_var_internals<T: Serialize + DeserializeOwned, C>(
821 var: &ReadVar<T, C>,
822) -> (Option<String>, bool) {
823 match var.backing_var {
824 ReadVarBacking::RuntimeVar {
825 var: ref s,
826 is_side_effect,
827 } => (Some(s.clone()), is_side_effect),
828 ReadVarBacking::Inline(_) => (None, false),
829 }
830}
831
832pub trait ImportCtxBackend {
833 fn on_possible_dep(&mut self, node_handle: NodeHandle);
834}
835
836/// Context passed to [`FlowNode::imports`].
837pub struct ImportCtx<'a> {
838 backend: &'a mut dyn ImportCtxBackend,
839}
840
841impl ImportCtx<'_> {
842 /// Declare that a Node can be referenced in [`FlowNode::emit`]
843 pub fn import<N: FlowNodeBase + 'static>(&mut self) {
844 self.backend.on_possible_dep(NodeHandle::from_type::<N>())
845 }
846}
847
848pub fn new_import_ctx(backend: &mut dyn ImportCtxBackend) -> ImportCtx<'_> {
849 ImportCtx { backend }
850}
851
852#[derive(Debug)]
853pub enum CtxAnchor {
854 PostJob,
855}
856
857pub trait NodeCtxBackend {
858 /// Handle to the current node this `ctx` corresponds to
859 fn current_node(&self) -> NodeHandle;
860
861 /// Return a string which uniquely identifies this particular Var
862 /// registration.
863 ///
864 /// Typically consists of `{current node handle}{ordinal}`
865 fn on_new_var(&mut self) -> String;
866
867 /// Invoked when a node claims a particular runtime variable
868 fn on_claimed_runtime_var(&mut self, var: &str, is_read: bool);
869
870 /// Invoked when a node marks a particular runtime variable as unused
871 fn on_unused_read_var(&mut self, var: &str);
872
873 /// Invoked when a node sets a request on a node.
874 ///
875 /// - `node_typeid` will always correspond to a node that was previously
876 /// passed to `on_register`.
877 /// - `req` may be an error, in the case where the NodeCtx failed to
878 /// serialize the provided request.
879 // FIXME: this should be using type-erased serde
880 fn on_request(&mut self, node_handle: NodeHandle, req: anyhow::Result<Box<[u8]>>);
881
882 fn on_emit_rust_step(
883 &mut self,
884 label: &str,
885 can_merge: bool,
886 code: Box<dyn for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()>>,
887 );
888
889 fn on_emit_ado_step(
890 &mut self,
891 label: &str,
892 yaml_snippet: Box<dyn for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String>,
893 inline_script: Option<
894 Box<dyn for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()>>,
895 >,
896 condvar: Option<String>,
897 );
898
899 fn on_emit_gh_step(
900 &mut self,
901 label: &str,
902 uses: &str,
903 with: BTreeMap<String, ClaimedGhParam>,
904 condvar: Option<String>,
905 outputs: BTreeMap<String, Vec<GhOutput>>,
906 permissions: BTreeMap<GhPermission, GhPermissionValue>,
907 gh_to_rust: Vec<GhToRust>,
908 rust_to_gh: Vec<RustToGh>,
909 );
910
911 fn on_emit_side_effect_step(&mut self);
912
913 fn backend(&mut self) -> FlowBackend;
914 fn platform(&mut self) -> FlowPlatform;
915 fn arch(&mut self) -> FlowArch;
916
917 /// Return a node-specific persistent store path. The backend does not need
918 /// to ensure that the path exists - flowey will automatically emit a step
919 /// to construct the directory at runtime.
920 fn persistent_dir_path_var(&mut self) -> Option<String>;
921}
922
923pub fn new_node_ctx(backend: &mut dyn NodeCtxBackend) -> NodeCtx<'_> {
924 NodeCtx {
925 backend: Rc::new(RefCell::new(backend)),
926 }
927}
928
929/// What backend the flow is being running on.
930#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
931pub enum FlowBackend {
932 /// Running locally.
933 Local,
934 /// Running on ADO.
935 Ado,
936 /// Running on GitHub Actions
937 Github,
938}
939
940/// The kind platform the flow is being running on, Windows or Unix.
941#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
942pub enum FlowPlatformKind {
943 Windows,
944 Unix,
945}
946
947/// The kind platform the flow is being running on, Windows or Unix.
948#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
949pub enum FlowPlatformLinuxDistro {
950 /// Fedora (including WSL2)
951 Fedora,
952 /// Ubuntu (including WSL2)
953 Ubuntu,
954 /// Arch Linux (including WSL2)
955 Arch,
956 /// Nix environment (detected via IN_NIX_SHELL env var or having a `/nix/store` in PATH)
957 Nix,
958 /// An unknown distribution
959 Unknown,
960}
961
962/// What platform the flow is being running on.
963#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
964#[non_exhaustive]
965pub enum FlowPlatform {
966 /// Windows
967 Windows,
968 /// Linux (including WSL2)
969 Linux(FlowPlatformLinuxDistro),
970 /// macOS
971 MacOs,
972}
973
974impl FlowPlatform {
975 pub fn kind(&self) -> FlowPlatformKind {
976 match self {
977 Self::Windows => FlowPlatformKind::Windows,
978 Self::Linux(_) | Self::MacOs => FlowPlatformKind::Unix,
979 }
980 }
981
982 fn as_str(&self) -> &'static str {
983 match self {
984 Self::Windows => "windows",
985 Self::Linux(_) => "linux",
986 Self::MacOs => "macos",
987 }
988 }
989
990 /// The suffix to use for executables on this platform.
991 pub fn exe_suffix(&self) -> &'static str {
992 if self == &Self::Windows { ".exe" } else { "" }
993 }
994
995 /// The full name for a binary on this platform (i.e. `name + self.exe_suffix()`).
996 pub fn binary(&self, name: &str) -> String {
997 format!("{}{}", name, self.exe_suffix())
998 }
999}
1000
1001impl std::fmt::Display for FlowPlatform {
1002 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1003 f.pad(self.as_str())
1004 }
1005}
1006
1007/// What architecture the flow is being running on.
1008#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
1009#[non_exhaustive]
1010pub enum FlowArch {
1011 X86_64,
1012 Aarch64,
1013}
1014
1015impl FlowArch {
1016 fn as_str(&self) -> &'static str {
1017 match self {
1018 Self::X86_64 => "x86_64",
1019 Self::Aarch64 => "aarch64",
1020 }
1021 }
1022}
1023
1024impl std::fmt::Display for FlowArch {
1025 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1026 f.pad(self.as_str())
1027 }
1028}
1029
1030/// Context object for an individual step.
1031pub struct StepCtx<'a> {
1032 backend: Rc<RefCell<&'a mut dyn NodeCtxBackend>>,
1033}
1034
1035impl StepCtx<'_> {
1036 /// What backend the flow is being running on (e.g: locally, ADO, GitHub,
1037 /// etc...)
1038 pub fn backend(&self) -> FlowBackend {
1039 self.backend.borrow_mut().backend()
1040 }
1041
1042 /// What platform the flow is being running on (e.g: windows, linux, wsl2,
1043 /// etc...).
1044 pub fn platform(&self) -> FlowPlatform {
1045 self.backend.borrow_mut().platform()
1046 }
1047}
1048
1049const NO_ADO_INLINE_SCRIPT: Option<
1050 for<'a> fn(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()>,
1051> = None;
1052
1053/// Context object for a `FlowNode`.
1054pub struct NodeCtx<'a> {
1055 backend: Rc<RefCell<&'a mut dyn NodeCtxBackend>>,
1056}
1057
1058impl<'ctx> NodeCtx<'ctx> {
1059 /// Emit a Rust-based step.
1060 ///
1061 /// As a convenience feature, this function returns a special _optional_
1062 /// [`ReadVar<SideEffect>`], which will not result in a "unused variable"
1063 /// error if no subsequent step ends up claiming it.
1064 pub fn emit_rust_step<F, G>(&mut self, label: impl AsRef<str>, code: F) -> ReadVar<SideEffect>
1065 where
1066 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1067 G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
1068 {
1069 self.emit_rust_step_inner(label.as_ref(), false, code)
1070 }
1071
1072 /// Emit a Rust-based step that cannot fail.
1073 ///
1074 /// This is equivalent to `emit_rust_step`, but it is for steps that cannot
1075 /// fail and that do not need to be emitted as a separate step in a YAML
1076 /// pipeline. This simplifies the pipeline logs.
1077 ///
1078 /// As a convenience feature, this function returns a special _optional_
1079 /// [`ReadVar<SideEffect>`], which will not result in a "unused variable"
1080 /// error if no subsequent step ends up claiming it.
1081 pub fn emit_minor_rust_step<F, G>(
1082 &mut self,
1083 label: impl AsRef<str>,
1084 code: F,
1085 ) -> ReadVar<SideEffect>
1086 where
1087 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1088 G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) + 'static,
1089 {
1090 self.emit_rust_step_inner(label.as_ref(), true, |ctx| {
1091 let f = code(ctx);
1092 |rt| {
1093 f(rt);
1094 Ok(())
1095 }
1096 })
1097 }
1098
1099 /// Emit a Rust-based step, creating a new `ReadVar<T>` from the step's
1100 /// return value.
1101 ///
1102 /// This is a convenience function that streamlines the following common
1103 /// flowey pattern:
1104 ///
1105 /// ```ignore
1106 /// // creating a new Var explicitly
1107 /// let (read_foo, write_foo) = ctx.new_var();
1108 /// ctx.emit_rust_step("foo", |ctx| {
1109 /// let write_foo = write_foo.claim(ctx);
1110 /// |rt| {
1111 /// rt.write(write_foo, &get_foo());
1112 /// Ok(())
1113 /// }
1114 /// });
1115 ///
1116 /// // creating a new Var automatically
1117 /// let read_foo = ctx.emit_rust_stepv("foo", |ctx| |rt| Ok(get_foo()));
1118 /// ```
1119 #[must_use]
1120 #[track_caller]
1121 pub fn emit_rust_stepv<T, F, G>(&mut self, label: impl AsRef<str>, code: F) -> ReadVar<T>
1122 where
1123 T: Serialize + DeserializeOwned + 'static,
1124 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1125 G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<T> + 'static,
1126 {
1127 self.emit_rust_stepv_inner(label.as_ref(), false, code)
1128 }
1129
1130 /// Emit a Rust-based step, creating a new `ReadVar<T>` from the step's
1131 /// return value.
1132 ///
1133 /// This is equivalent to `emit_rust_stepv`, but it is for steps that cannot
1134 /// fail and that do not need to be emitted as a separate step in a YAML
1135 /// pipeline. This simplifies the pipeline logs.
1136 ///
1137 /// This is a convenience function that streamlines the following common
1138 /// flowey pattern:
1139 ///
1140 /// ```ignore
1141 /// // creating a new Var explicitly
1142 /// let (read_foo, write_foo) = ctx.new_var();
1143 /// ctx.emit_minor_rust_step("foo", |ctx| {
1144 /// let write_foo = write_foo.claim(ctx);
1145 /// |rt| {
1146 /// rt.write(write_foo, &get_foo());
1147 /// }
1148 /// });
1149 ///
1150 /// // creating a new Var automatically
1151 /// let read_foo = ctx.emit_minor_rust_stepv("foo", |ctx| |rt| get_foo());
1152 /// ```
1153 #[must_use]
1154 #[track_caller]
1155 pub fn emit_minor_rust_stepv<T, F, G>(&mut self, label: impl AsRef<str>, code: F) -> ReadVar<T>
1156 where
1157 T: Serialize + DeserializeOwned + 'static,
1158 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1159 G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> T + 'static,
1160 {
1161 self.emit_rust_stepv_inner(label.as_ref(), true, |ctx| {
1162 let f = code(ctx);
1163 |rt| Ok(f(rt))
1164 })
1165 }
1166
1167 fn emit_rust_step_inner<F, G>(
1168 &mut self,
1169 label: &str,
1170 can_merge: bool,
1171 code: F,
1172 ) -> ReadVar<SideEffect>
1173 where
1174 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1175 G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
1176 {
1177 let (read, write) = self.new_prefixed_var("auto_se");
1178
1179 let ctx = &mut StepCtx {
1180 backend: self.backend.clone(),
1181 };
1182 write.claim(ctx);
1183
1184 let code = code(ctx);
1185 self.backend
1186 .borrow_mut()
1187 .on_emit_rust_step(label.as_ref(), can_merge, Box::new(code));
1188 read
1189 }
1190
1191 #[must_use]
1192 #[track_caller]
1193 fn emit_rust_stepv_inner<T, F, G>(
1194 &mut self,
1195 label: impl AsRef<str>,
1196 can_merge: bool,
1197 code: F,
1198 ) -> ReadVar<T>
1199 where
1200 T: Serialize + DeserializeOwned + 'static,
1201 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1202 G: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<T> + 'static,
1203 {
1204 let (read, write) = self.new_var();
1205
1206 let ctx = &mut StepCtx {
1207 backend: self.backend.clone(),
1208 };
1209 let write = write.claim(ctx);
1210
1211 let code = code(ctx);
1212 self.backend.borrow_mut().on_emit_rust_step(
1213 label.as_ref(),
1214 can_merge,
1215 Box::new(|rt| {
1216 let val = code(rt)?;
1217 rt.write(write, &val);
1218 Ok(())
1219 }),
1220 );
1221 read
1222 }
1223
1224 /// Load an ADO global runtime variable into a flowey [`ReadVar`].
1225 #[track_caller]
1226 #[must_use]
1227 pub fn get_ado_variable(&mut self, ado_var: AdoRuntimeVar) -> ReadVar<String> {
1228 let (var, write_var) = self.new_var();
1229 self.emit_ado_step(format!("🌼 read {}", ado_var.as_raw_var_name()), |ctx| {
1230 let write_var = write_var.claim(ctx);
1231 |rt| {
1232 rt.set_var(write_var, ado_var);
1233 "".into()
1234 }
1235 });
1236 var
1237 }
1238
1239 /// Emit an ADO step.
1240 pub fn emit_ado_step<F, G>(&mut self, display_name: impl AsRef<str>, yaml_snippet: F)
1241 where
1242 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1243 G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
1244 {
1245 self.emit_ado_step_inner(display_name, None, |ctx| {
1246 (yaml_snippet(ctx), NO_ADO_INLINE_SCRIPT)
1247 })
1248 }
1249
1250 /// Emit an ADO step, conditionally executed based on the value of `cond` at
1251 /// runtime.
1252 pub fn emit_ado_step_with_condition<F, G>(
1253 &mut self,
1254 display_name: impl AsRef<str>,
1255 cond: ReadVar<bool>,
1256 yaml_snippet: F,
1257 ) where
1258 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1259 G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
1260 {
1261 self.emit_ado_step_inner(display_name, Some(cond), |ctx| {
1262 (yaml_snippet(ctx), NO_ADO_INLINE_SCRIPT)
1263 })
1264 }
1265
1266 /// Emit an ADO step, conditionally executed based on the value of`cond` at
1267 /// runtime.
1268 pub fn emit_ado_step_with_condition_optional<F, G>(
1269 &mut self,
1270 display_name: impl AsRef<str>,
1271 cond: Option<ReadVar<bool>>,
1272 yaml_snippet: F,
1273 ) where
1274 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> G,
1275 G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
1276 {
1277 self.emit_ado_step_inner(display_name, cond, |ctx| {
1278 (yaml_snippet(ctx), NO_ADO_INLINE_SCRIPT)
1279 })
1280 }
1281
1282 /// Emit an ADO step which invokes a rust callback using an inline script.
1283 ///
1284 /// By using the `{{FLOWEY_INLINE_SCRIPT}}` template in the returned yaml
1285 /// snippet, flowey will interpolate a command ~roughly akin to `flowey
1286 /// exec-snippet <rust-snippet-id>` into the generated yaml.
1287 ///
1288 /// e.g: if we wanted to _manually_ wrap the bash ADO snippet for whatever
1289 /// reason:
1290 ///
1291 /// ```text
1292 /// - bash: |
1293 /// echo "hello there!"
1294 /// {{FLOWEY_INLINE_SCRIPT}}
1295 /// echo echo "bye!"
1296 /// ```
1297 ///
1298 /// # Limitations
1299 ///
1300 /// At the moment, due to flowey API limitations, it is only possible to
1301 /// embed a single inline script into a YAML step.
1302 ///
1303 /// In the future, rather than having separate methods for "emit step with X
1304 /// inline scripts", flowey should support declaring "first-class" callbacks
1305 /// via a (hypothetical) `ctx.new_callback_var(|ctx| |rt, input: Input| ->
1306 /// Output { ... })` API, at which point.
1307 ///
1308 /// If such an API were to exist, one could simply use the "vanilla" emit
1309 /// yaml step functions with these first-class callbacks.
1310 pub fn emit_ado_step_with_inline_script<F, G, H>(
1311 &mut self,
1312 display_name: impl AsRef<str>,
1313 yaml_snippet: F,
1314 ) where
1315 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> (G, H),
1316 G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
1317 H: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
1318 {
1319 self.emit_ado_step_inner(display_name, None, |ctx| {
1320 let (f, g) = yaml_snippet(ctx);
1321 (f, Some(g))
1322 })
1323 }
1324
1325 fn emit_ado_step_inner<F, G, H>(
1326 &mut self,
1327 display_name: impl AsRef<str>,
1328 cond: Option<ReadVar<bool>>,
1329 yaml_snippet: F,
1330 ) where
1331 F: for<'a> FnOnce(&'a mut StepCtx<'_>) -> (G, Option<H>),
1332 G: for<'a> FnOnce(&'a mut AdoStepServices<'_>) -> String + 'static,
1333 H: for<'a> FnOnce(&'a mut RustRuntimeServices<'_>) -> anyhow::Result<()> + 'static,
1334 {
1335 let condvar = match cond.map(|c| c.backing_var) {
1336 // it seems silly to allow this... but it's not hard so why not?
1337 Some(ReadVarBacking::Inline(cond)) => {
1338 if !cond {
1339 return;
1340 } else {
1341 None
1342 }
1343 }
1344 Some(ReadVarBacking::RuntimeVar {
1345 var,
1346 is_side_effect,
1347 }) => {
1348 assert!(!is_side_effect);
1349 self.backend.borrow_mut().on_claimed_runtime_var(&var, true);
1350 Some(var)
1351 }
1352 None => None,
1353 };
1354
1355 let (yaml_snippet, inline_script) = yaml_snippet(&mut StepCtx {
1356 backend: self.backend.clone(),
1357 });
1358 self.backend.borrow_mut().on_emit_ado_step(
1359 display_name.as_ref(),
1360 Box::new(yaml_snippet),
1361 if let Some(inline_script) = inline_script {
1362 Some(Box::new(inline_script))
1363 } else {
1364 None
1365 },
1366 condvar,
1367 );
1368 }
1369
1370 /// Load a GitHub context variable into a flowey [`ReadVar`].
1371 #[track_caller]
1372 #[must_use]
1373 pub fn get_gh_context_var(&mut self) -> GhContextVarReader<'ctx, Root> {
1374 GhContextVarReader {
1375 ctx: NodeCtx {
1376 backend: self.backend.clone(),
1377 },
1378 _state: std::marker::PhantomData,
1379 }
1380 }
1381
1382 /// Emit a GitHub Actions action step.
1383 pub fn emit_gh_step(
1384 &mut self,
1385 display_name: impl AsRef<str>,
1386 uses: impl AsRef<str>,
1387 ) -> GhStepBuilder {
1388 GhStepBuilder::new(display_name, uses)
1389 }
1390
1391 fn emit_gh_step_inner(
1392 &mut self,
1393 display_name: impl AsRef<str>,
1394 cond: Option<ReadVar<bool>>,
1395 uses: impl AsRef<str>,
1396 with: Option<BTreeMap<String, GhParam>>,
1397 outputs: BTreeMap<String, Vec<WriteVar<String>>>,
1398 run_after: Vec<ReadVar<SideEffect>>,
1399 permissions: BTreeMap<GhPermission, GhPermissionValue>,
1400 ) {
1401 let condvar = match cond.map(|c| c.backing_var) {
1402 // it seems silly to allow this... but it's not hard so why not?
1403 Some(ReadVarBacking::Inline(cond)) => {
1404 if !cond {
1405 return;
1406 } else {
1407 None
1408 }
1409 }
1410 Some(ReadVarBacking::RuntimeVar {
1411 var,
1412 is_side_effect,
1413 }) => {
1414 assert!(!is_side_effect);
1415 self.backend.borrow_mut().on_claimed_runtime_var(&var, true);
1416 Some(var)
1417 }
1418 None => None,
1419 };
1420
1421 let with = with
1422 .unwrap_or_default()
1423 .into_iter()
1424 .map(|(k, v)| {
1425 (
1426 k.clone(),
1427 v.claim(&mut StepCtx {
1428 backend: self.backend.clone(),
1429 }),
1430 )
1431 })
1432 .collect();
1433
1434 for var in run_after {
1435 var.claim(&mut StepCtx {
1436 backend: self.backend.clone(),
1437 });
1438 }
1439
1440 let outputvars = outputs
1441 .into_iter()
1442 .map(|(name, vars)| {
1443 (
1444 name,
1445 vars.into_iter()
1446 .map(|var| {
1447 let var = var.claim(&mut StepCtx {
1448 backend: self.backend.clone(),
1449 });
1450 GhOutput {
1451 backing_var: var.backing_var,
1452 is_secret: false,
1453 is_object: false,
1454 }
1455 })
1456 .collect(),
1457 )
1458 })
1459 .collect();
1460
1461 self.backend.borrow_mut().on_emit_gh_step(
1462 display_name.as_ref(),
1463 uses.as_ref(),
1464 with,
1465 condvar,
1466 outputvars,
1467 permissions,
1468 Vec::new(),
1469 Vec::new(),
1470 );
1471 }
1472
1473 /// Emit a "side-effect" step, which simply claims a set of side-effects in
1474 /// order to resolve another set of side effects.
1475 ///
1476 /// The same functionality could be achieved (less efficiently) by emitting
1477 /// a Rust step (or ADO step, or github step, etc...) that claims both sets
1478 /// of side-effects, and then does nothing. By using this method - flowey is
1479 /// able to avoid emitting that additional noop step at runtime.
1480 pub fn emit_side_effect_step(
1481 &mut self,
1482 use_side_effects: impl IntoIterator<Item = ReadVar<SideEffect>>,
1483 resolve_side_effects: impl IntoIterator<Item = WriteVar<SideEffect>>,
1484 ) {
1485 let mut backend = self.backend.borrow_mut();
1486 for var in use_side_effects.into_iter() {
1487 if let ReadVarBacking::RuntimeVar {
1488 var,
1489 is_side_effect: _,
1490 } = &var.backing_var
1491 {
1492 backend.on_claimed_runtime_var(var, true);
1493 }
1494 }
1495
1496 for var in resolve_side_effects.into_iter() {
1497 backend.on_claimed_runtime_var(&var.backing_var, false);
1498 }
1499
1500 backend.on_emit_side_effect_step();
1501 }
1502
1503 /// What backend the flow is being running on (e.g: locally, ADO, GitHub,
1504 /// etc...)
1505 pub fn backend(&self) -> FlowBackend {
1506 self.backend.borrow_mut().backend()
1507 }
1508
1509 /// What platform the flow is being running on (e.g: windows, linux, wsl2,
1510 /// etc...).
1511 pub fn platform(&self) -> FlowPlatform {
1512 self.backend.borrow_mut().platform()
1513 }
1514
1515 /// What architecture the flow is being running on (x86_64 or Aarch64)
1516 pub fn arch(&self) -> FlowArch {
1517 self.backend.borrow_mut().arch()
1518 }
1519
1520 /// Set a request on a particular node.
1521 pub fn req<R>(&mut self, req: R)
1522 where
1523 R: IntoRequest + 'static,
1524 {
1525 let mut backend = self.backend.borrow_mut();
1526 backend.on_request(
1527 NodeHandle::from_type::<R::Node>(),
1528 serde_json::to_vec(&req.into_request())
1529 .map(Into::into)
1530 .map_err(Into::into),
1531 );
1532 }
1533
1534 /// Set a request on a particular node, simultaneously creating a new flowey
1535 /// Var in the process.
1536 #[track_caller]
1537 #[must_use]
1538 pub fn reqv<T, R>(&mut self, f: impl FnOnce(WriteVar<T>) -> R) -> ReadVar<T>
1539 where
1540 T: Serialize + DeserializeOwned,
1541 R: IntoRequest + 'static,
1542 {
1543 let (read, write) = self.new_var();
1544 self.req::<R>(f(write));
1545 read
1546 }
1547
1548 /// Set multiple requests on a particular node.
1549 pub fn requests<N>(&mut self, reqs: impl IntoIterator<Item = N::Request>)
1550 where
1551 N: FlowNodeBase + 'static,
1552 {
1553 let mut backend = self.backend.borrow_mut();
1554 for req in reqs.into_iter() {
1555 backend.on_request(
1556 NodeHandle::from_type::<N>(),
1557 serde_json::to_vec(&req).map(Into::into).map_err(Into::into),
1558 );
1559 }
1560 }
1561
1562 /// Allocate a new flowey Var, returning two handles: one for reading the
1563 /// value, and another for writing the value.
1564 #[track_caller]
1565 #[must_use]
1566 pub fn new_var<T>(&self) -> (ReadVar<T>, WriteVar<T>)
1567 where
1568 T: Serialize + DeserializeOwned,
1569 {
1570 self.new_prefixed_var("")
1571 }
1572
1573 #[track_caller]
1574 #[must_use]
1575 fn new_prefixed_var<T>(&self, prefix: &'static str) -> (ReadVar<T>, WriteVar<T>)
1576 where
1577 T: Serialize + DeserializeOwned,
1578 {
1579 // normalize call path to ensure determinism between windows and linux
1580 let caller = std::panic::Location::caller()
1581 .to_string()
1582 .replace('\\', "/");
1583
1584 // until we have a proper way to "split" debug info related to vars, we
1585 // kinda just lump it in with the var name itself.
1586 //
1587 // HACK: to work around cases where - depending on what the
1588 // current-working-dir is when incoking flowey - the returned
1589 // caller.file() path may leak the full path of the file (as opposed to
1590 // the relative path), resulting in inconsistencies between build
1591 // environments.
1592 //
1593 // For expediency, and to preserve some semblance of useful error
1594 // messages, we decided to play some sketchy games with the resulting
1595 // string to only preserve the _consistent_ bit of the path for a human
1596 // to use as reference.
1597 //
1598 // This is not ideal in the slightest, but it works OK for now
1599 let caller = caller
1600 .split_once("flowey/")
1601 .expect("due to a known limitation with flowey, all flowey code must have an ancestor dir called 'flowey/' somewhere in its full path")
1602 .1;
1603
1604 let colon = if prefix.is_empty() { "" } else { ":" };
1605 let ordinal = self.backend.borrow_mut().on_new_var();
1606 let backing_var = format!("{prefix}{colon}{ordinal}:{caller}");
1607
1608 (
1609 ReadVar {
1610 backing_var: ReadVarBacking::RuntimeVar {
1611 var: backing_var.clone(),
1612 is_side_effect: false,
1613 },
1614 _kind: std::marker::PhantomData,
1615 },
1616 WriteVar {
1617 backing_var,
1618 is_side_effect: false,
1619 _kind: std::marker::PhantomData,
1620 },
1621 )
1622 }
1623
1624 /// Allocate special [`SideEffect`] var which can be used to schedule a
1625 /// "post-job" step associated with some existing step.
1626 ///
1627 /// This "post-job" step will then only run after all other regular steps
1628 /// have run (i.e: steps required to complete any top-level objectives
1629 /// passed in via [`crate::pipeline::PipelineJob::dep_on`]). This makes it
1630 /// useful for implementing various "cleanup" or "finalize" tasks.
1631 ///
1632 /// e.g: the Cache node uses this to upload the contents of a cache
1633 /// directory at the end of a Job.
1634 #[track_caller]
1635 #[must_use]
1636 pub fn new_post_job_side_effect(&self) -> (ReadVar<SideEffect>, WriteVar<SideEffect>) {
1637 self.new_prefixed_var("post_job")
1638 }
1639
1640 /// Return a flowey Var pointing to a **node-specific** directory which
1641 /// will be persisted between runs, if such a directory is available.
1642 ///
1643 /// WARNING: this method is _very likely_ to return None when running on CI
1644 /// machines, as most CI agents are wiped between jobs!
1645 ///
1646 /// As such, it is NOT recommended that node authors reach for this method
1647 /// directly, and instead use abstractions such as the
1648 /// `flowey_lib_common::cache` Node, which implements node-level persistence
1649 /// in a way that works _regardless_ if a persistent_dir is available (e.g:
1650 /// by falling back to uploading / downloading artifacts to a "cache store"
1651 /// on platforms like ADO or Github Actions).
1652 #[track_caller]
1653 #[must_use]
1654 pub fn persistent_dir(&mut self) -> Option<ReadVar<PathBuf>> {
1655 let path: ReadVar<PathBuf> = ReadVar {
1656 backing_var: ReadVarBacking::RuntimeVar {
1657 var: self.backend.borrow_mut().persistent_dir_path_var()?,
1658 is_side_effect: false,
1659 },
1660 _kind: std::marker::PhantomData,
1661 };
1662
1663 let folder_name = self
1664 .backend
1665 .borrow_mut()
1666 .current_node()
1667 .modpath()
1668 .replace("::", "__");
1669
1670 Some(
1671 self.emit_rust_stepv("🌼 Create persistent store dir", |ctx| {
1672 let path = path.claim(ctx);
1673 |rt| {
1674 let dir = rt.read(path).join(folder_name);
1675 fs_err::create_dir_all(&dir)?;
1676 Ok(dir)
1677 }
1678 }),
1679 )
1680 }
1681
1682 /// Check to see if a persistent dir is available, without yet creating it.
1683 pub fn supports_persistent_dir(&mut self) -> bool {
1684 self.backend
1685 .borrow_mut()
1686 .persistent_dir_path_var()
1687 .is_some()
1688 }
1689}
1690
1691// FUTURE: explore using type-erased serde here, instead of relying on
1692// `serde_json` in `flowey_core`.
1693pub trait RuntimeVarDb {
1694 fn get_var(&mut self, var_name: &str) -> (Vec<u8>, bool) {
1695 self.try_get_var(var_name)
1696 .unwrap_or_else(|| panic!("db is missing var {}", var_name))
1697 }
1698
1699 fn try_get_var(&mut self, var_name: &str) -> Option<(Vec<u8>, bool)>;
1700 fn set_var(&mut self, var_name: &str, is_secret: bool, value: Vec<u8>);
1701}
1702
1703impl RuntimeVarDb for Box<dyn RuntimeVarDb> {
1704 fn try_get_var(&mut self, var_name: &str) -> Option<(Vec<u8>, bool)> {
1705 (**self).try_get_var(var_name)
1706 }
1707
1708 fn set_var(&mut self, var_name: &str, is_secret: bool, value: Vec<u8>) {
1709 (**self).set_var(var_name, is_secret, value)
1710 }
1711}
1712
1713pub mod steps {
1714 pub mod ado {
1715 use crate::node::ClaimedReadVar;
1716 use crate::node::ClaimedWriteVar;
1717 use crate::node::ReadVarBacking;
1718 use serde::Deserialize;
1719 use serde::Serialize;
1720 use std::borrow::Cow;
1721
1722 /// An ADO repository declared as a resource in the top-level pipeline.
1723 ///
1724 /// Created via [`crate::pipeline::Pipeline::ado_add_resources_repository`].
1725 ///
1726 /// Consumed via [`AdoStepServices::resolve_repository_id`].
1727 #[derive(Debug, Clone, Serialize, Deserialize)]
1728 pub struct AdoResourcesRepositoryId {
1729 pub(crate) repo_id: String,
1730 }
1731
1732 impl AdoResourcesRepositoryId {
1733 /// Create a `AdoResourcesRepositoryId` corresponding to `self`
1734 /// (i.e: the repo which stores the current pipeline).
1735 ///
1736 /// This is safe to do from any context, as the `self` resource will
1737 /// _always_ be available.
1738 pub fn new_self() -> Self {
1739 Self {
1740 repo_id: "self".into(),
1741 }
1742 }
1743
1744 /// (dangerous) get the raw ID associated with this resource.
1745 ///
1746 /// It is highly recommended to avoid losing type-safety, and
1747 /// sticking to [`AdoStepServices::resolve_repository_id`].in order
1748 /// to resolve this type to a String.
1749 pub fn dangerous_get_raw_id(&self) -> &str {
1750 &self.repo_id
1751 }
1752
1753 /// (dangerous) create a new ID out of thin air.
1754 ///
1755 /// It is highly recommended to avoid losing type-safety, and
1756 /// sticking to [`AdoStepServices::resolve_repository_id`].in order
1757 /// to resolve this type to a String.
1758 pub fn dangerous_new(repo_id: &str) -> Self {
1759 Self {
1760 repo_id: repo_id.into(),
1761 }
1762 }
1763 }
1764
1765 /// Handle to an ADO variable.
1766 ///
1767 /// Includes a (non-exhaustive) list of associated constants
1768 /// corresponding to global ADO vars which are _always_ available.
1769 #[derive(Clone, Debug, Serialize, Deserialize)]
1770 pub struct AdoRuntimeVar {
1771 is_secret: bool,
1772 ado_var: Cow<'static, str>,
1773 }
1774
1775 #[allow(non_upper_case_globals)]
1776 impl AdoRuntimeVar {
1777 /// `build.SourceBranch`
1778 ///
1779 /// NOTE: Includes the full branch ref (ex: `refs/heads/main`) so
1780 /// unlike `build.SourceBranchName`, a branch like `user/foo/bar`
1781 /// won't be stripped to just `bar`
1782 pub const BUILD__SOURCE_BRANCH: AdoRuntimeVar =
1783 AdoRuntimeVar::new("build.SourceBranch");
1784
1785 /// `build.BuildNumber`
1786 pub const BUILD__BUILD_NUMBER: AdoRuntimeVar = AdoRuntimeVar::new("build.BuildNumber");
1787
1788 /// `System.AccessToken`
1789 pub const SYSTEM__ACCESS_TOKEN: AdoRuntimeVar =
1790 AdoRuntimeVar::new_secret("System.AccessToken");
1791
1792 /// `System.System.JobAttempt`
1793 pub const SYSTEM__JOB_ATTEMPT: AdoRuntimeVar =
1794 AdoRuntimeVar::new_secret("System.JobAttempt");
1795 }
1796
1797 impl AdoRuntimeVar {
1798 const fn new(s: &'static str) -> Self {
1799 Self {
1800 is_secret: false,
1801 ado_var: Cow::Borrowed(s),
1802 }
1803 }
1804
1805 const fn new_secret(s: &'static str) -> Self {
1806 Self {
1807 is_secret: true,
1808 ado_var: Cow::Borrowed(s),
1809 }
1810 }
1811
1812 /// Check if the ADO var is tagged as being a secret
1813 pub fn is_secret(&self) -> bool {
1814 self.is_secret
1815 }
1816
1817 /// Get the raw underlying ADO variable name
1818 pub fn as_raw_var_name(&self) -> String {
1819 self.ado_var.as_ref().into()
1820 }
1821
1822 /// Get a handle to an ADO runtime variable corresponding to a
1823 /// global ADO variable with the given name.
1824 ///
1825 /// This method should be used rarely and with great care!
1826 ///
1827 /// ADO variables are global, and sidestep the type-safe data flow
1828 /// between flowey nodes entirely!
1829 pub fn dangerous_from_global(ado_var_name: impl AsRef<str>, is_secret: bool) -> Self {
1830 Self {
1831 is_secret,
1832 ado_var: ado_var_name.as_ref().to_owned().into(),
1833 }
1834 }
1835 }
1836
1837 pub fn new_ado_step_services(
1838 fresh_ado_var: &mut dyn FnMut() -> String,
1839 ) -> AdoStepServices<'_> {
1840 AdoStepServices {
1841 fresh_ado_var,
1842 ado_to_rust: Vec::new(),
1843 rust_to_ado: Vec::new(),
1844 }
1845 }
1846
1847 pub struct CompletedAdoStepServices {
1848 pub ado_to_rust: Vec<(String, String, bool)>,
1849 pub rust_to_ado: Vec<(String, String)>,
1850 }
1851
1852 impl CompletedAdoStepServices {
1853 pub fn from_ado_step_services(access: AdoStepServices<'_>) -> Self {
1854 let AdoStepServices {
1855 fresh_ado_var: _,
1856 ado_to_rust,
1857 rust_to_ado,
1858 } = access;
1859
1860 Self {
1861 ado_to_rust,
1862 rust_to_ado,
1863 }
1864 }
1865 }
1866
1867 pub struct AdoStepServices<'a> {
1868 fresh_ado_var: &'a mut dyn FnMut() -> String,
1869 ado_to_rust: Vec<(String, String, bool)>,
1870 rust_to_ado: Vec<(String, String)>,
1871 }
1872
1873 impl AdoStepServices<'_> {
1874 /// Return the raw string identifier for the given
1875 /// [`AdoResourcesRepositoryId`].
1876 pub fn resolve_repository_id(&self, repo_id: AdoResourcesRepositoryId) -> String {
1877 repo_id.repo_id
1878 }
1879
1880 /// Set the specified flowey Var using the value of the given ADO var.
1881 // TODO: is there a good way to allow auto-casting the ADO var back
1882 // to a WriteVar<T>, instead of just a String? It's complicated by
1883 // the fact that the ADO var to flowey bridge is handled by the ADO
1884 // backend, which itself needs to know type info...
1885 pub fn set_var(&mut self, var: ClaimedWriteVar<String>, from_ado_var: AdoRuntimeVar) {
1886 self.ado_to_rust.push((
1887 from_ado_var.ado_var.into(),
1888 var.backing_var,
1889 from_ado_var.is_secret,
1890 ))
1891 }
1892
1893 /// Get the value of a flowey Var as a ADO runtime variable.
1894 pub fn get_var(&mut self, var: ClaimedReadVar<String>) -> AdoRuntimeVar {
1895 let backing_var = if let ReadVarBacking::RuntimeVar {
1896 var,
1897 is_side_effect,
1898 } = &var.backing_var
1899 {
1900 assert!(!is_side_effect);
1901 var
1902 } else {
1903 todo!("support inline ado read vars")
1904 };
1905
1906 let new_ado_var_name = (self.fresh_ado_var)();
1907
1908 self.rust_to_ado
1909 .push((backing_var.clone(), new_ado_var_name.clone()));
1910 AdoRuntimeVar::dangerous_from_global(new_ado_var_name, false)
1911 }
1912 }
1913 }
1914
1915 pub mod github {
1916 use crate::node::ClaimVar;
1917 use crate::node::NodeCtx;
1918 use crate::node::ReadVar;
1919 use crate::node::ReadVarBacking;
1920 use crate::node::SideEffect;
1921 use crate::node::StepCtx;
1922 use crate::node::VarClaimed;
1923 use crate::node::VarNotClaimed;
1924 use crate::node::WriteVar;
1925 use std::collections::BTreeMap;
1926
1927 pub struct GhStepBuilder {
1928 display_name: String,
1929 cond: Option<ReadVar<bool>>,
1930 uses: String,
1931 with: Option<BTreeMap<String, GhParam>>,
1932 outputs: BTreeMap<String, Vec<WriteVar<String>>>,
1933 run_after: Vec<ReadVar<SideEffect>>,
1934 permissions: BTreeMap<GhPermission, GhPermissionValue>,
1935 }
1936
1937 impl GhStepBuilder {
1938 /// Creates a new GitHub step builder, with the given display name and
1939 /// action to use. For example, the following code generates the following yaml:
1940 ///
1941 /// ```ignore
1942 /// GhStepBuilder::new("Check out repository code", "actions/checkout@v4").finish()
1943 /// ```
1944 ///
1945 /// ```ignore
1946 /// - name: Check out repository code
1947 /// uses: actions/checkout@v4
1948 /// ```
1949 ///
1950 /// For more information on the yaml syntax for the `name` and `uses` parameters,
1951 /// see <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsname>
1952 pub fn new(display_name: impl AsRef<str>, uses: impl AsRef<str>) -> Self {
1953 Self {
1954 display_name: display_name.as_ref().into(),
1955 cond: None,
1956 uses: uses.as_ref().into(),
1957 with: None,
1958 outputs: BTreeMap::new(),
1959 run_after: Vec::new(),
1960 permissions: BTreeMap::new(),
1961 }
1962 }
1963
1964 /// Adds a condition [`ReadVar<bool>`] to the step,
1965 /// such that the step only executes if the condition is true.
1966 /// This is equivalent to using an `if` conditional in the yaml.
1967 ///
1968 /// For more information on the yaml syntax for `if` conditionals, see
1969 /// <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsname>
1970 pub fn condition(mut self, cond: ReadVar<bool>) -> Self {
1971 self.cond = Some(cond);
1972 self
1973 }
1974
1975 /// Adds a parameter to the step, specified as a key-value pair corresponding
1976 /// to the param name and value. For example the following code generates the following yaml:
1977 ///
1978 /// ```rust,ignore
1979 /// let (client_id, write_client_id) = ctx.new_var();
1980 /// let (tenant_id, write_tenant_id) = ctx.new_var();
1981 /// let (subscription_id, write_subscription_id) = ctx.new_var();
1982 /// // ... insert rust step writing to each of those secrets ...
1983 /// GhStepBuilder::new("Azure Login", "Azure/login@v2")
1984 /// .with("client-id", client_id)
1985 /// .with("tenant-id", tenant_id)
1986 /// .with("subscription-id", subscription_id)
1987 /// ```
1988 ///
1989 /// ```text
1990 /// - name: Azure Login
1991 /// uses: Azure/login@v2
1992 /// with:
1993 /// client-id: ${{ env.floweyvar1 }} // Assuming the backend wrote client_id to floweyvar1
1994 /// tenant-id: ${{ env.floweyvar2 }} // Assuming the backend wrote tenant-id to floweyvar2
1995 /// subscription-id: ${{ env.floweyvar3 }} // Assuming the backend wrote subscription-id to floweyvar3
1996 /// ```
1997 ///
1998 /// For more information on the yaml syntax for the `with` parameters,
1999 /// see <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith>
2000 pub fn with(mut self, k: impl AsRef<str>, v: impl Into<GhParam>) -> Self {
2001 self.with.get_or_insert_with(BTreeMap::new);
2002 if let Some(with) = &mut self.with {
2003 with.insert(k.as_ref().to_string(), v.into());
2004 }
2005 self
2006 }
2007
2008 /// Specifies an output to read from the step, specified as a key-value pair
2009 /// corresponding to the output name and the flowey var to write the output to.
2010 ///
2011 /// This is equivalent to writing into `v` the output of a step in the yaml using:
2012 /// `${{ steps.<backend-assigned-step-id>.outputs.<k> }}`
2013 ///
2014 /// For more information on step outputs, see
2015 /// <https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions>
2016 pub fn output(mut self, k: impl AsRef<str>, v: WriteVar<String>) -> Self {
2017 self.outputs
2018 .entry(k.as_ref().to_string())
2019 .or_default()
2020 .push(v);
2021 self
2022 }
2023
2024 /// Specifies a side-effect that must be resolved before this step can run.
2025 pub fn run_after(mut self, side_effect: ReadVar<SideEffect>) -> Self {
2026 self.run_after.push(side_effect);
2027 self
2028 }
2029
2030 /// Declare that this step requires a certain GITHUB_TOKEN permission in order to run.
2031 ///
2032 /// For more info about Github Actions permissions, see [`gh_grant_permissions`](crate::pipeline::PipelineJob::gh_grant_permissions) and
2033 /// <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs>
2034 pub fn requires_permission(
2035 mut self,
2036 perm: GhPermission,
2037 value: GhPermissionValue,
2038 ) -> Self {
2039 self.permissions.insert(perm, value);
2040 self
2041 }
2042
2043 /// Finish building the step, emitting it to the backend and returning a side-effect.
2044 #[track_caller]
2045 pub fn finish(self, ctx: &mut NodeCtx<'_>) -> ReadVar<SideEffect> {
2046 let (side_effect, claim_side_effect) = ctx.new_prefixed_var("auto_se");
2047 ctx.backend
2048 .borrow_mut()
2049 .on_claimed_runtime_var(&claim_side_effect.backing_var, false);
2050
2051 ctx.emit_gh_step_inner(
2052 self.display_name,
2053 self.cond,
2054 self.uses,
2055 self.with,
2056 self.outputs,
2057 self.run_after,
2058 self.permissions,
2059 );
2060
2061 side_effect
2062 }
2063 }
2064
2065 #[derive(Clone, Debug)]
2066 pub enum GhParam<C = VarNotClaimed> {
2067 Static(String),
2068 FloweyVar(ReadVar<String, C>),
2069 }
2070
2071 impl From<String> for GhParam {
2072 fn from(param: String) -> GhParam {
2073 GhParam::Static(param)
2074 }
2075 }
2076
2077 impl From<&str> for GhParam {
2078 fn from(param: &str) -> GhParam {
2079 GhParam::Static(param.to_string())
2080 }
2081 }
2082
2083 impl From<ReadVar<String>> for GhParam {
2084 fn from(param: ReadVar<String>) -> GhParam {
2085 GhParam::FloweyVar(param)
2086 }
2087 }
2088
2089 pub type ClaimedGhParam = GhParam<VarClaimed>;
2090
2091 impl ClaimVar for GhParam {
2092 type Claimed = ClaimedGhParam;
2093
2094 fn claim(self, ctx: &mut StepCtx<'_>) -> ClaimedGhParam {
2095 match self {
2096 GhParam::Static(s) => ClaimedGhParam::Static(s),
2097 GhParam::FloweyVar(var) => match &var.backing_var {
2098 ReadVarBacking::RuntimeVar { is_side_effect, .. } => {
2099 assert!(!is_side_effect);
2100 ClaimedGhParam::FloweyVar(var.claim(ctx))
2101 }
2102 ReadVarBacking::Inline(var) => ClaimedGhParam::Static(var.clone()),
2103 },
2104 }
2105 }
2106 }
2107
2108 /// The assigned permission value for a scope.
2109 ///
2110 /// For more details on how these values affect a particular scope, refer to:
2111 /// <https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs>
2112 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
2113 pub enum GhPermissionValue {
2114 Read,
2115 Write,
2116 None,
2117 }
2118
2119 /// Refers to the scope of a permission granted to the GITHUB_TOKEN
2120 /// for a job.
2121 ///
2122 /// For more details on each scope, refer to:
2123 /// <https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs>
2124 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
2125 pub enum GhPermission {
2126 Actions,
2127 Attestations,
2128 Checks,
2129 Contents,
2130 Deployments,
2131 Discussions,
2132 IdToken,
2133 Issues,
2134 Packages,
2135 Pages,
2136 PullRequests,
2137 RepositoryProjects,
2138 SecurityEvents,
2139 Statuses,
2140 }
2141 }
2142
2143 pub mod rust {
2144 use crate::node::ClaimedWriteVar;
2145 use crate::node::FlowArch;
2146 use crate::node::FlowBackend;
2147 use crate::node::FlowPlatform;
2148 use crate::node::ReadVarValue;
2149 use crate::node::RuntimeVarDb;
2150 use serde::Serialize;
2151 use serde::de::DeserializeOwned;
2152
2153 pub fn new_rust_runtime_services(
2154 runtime_var_db: &mut dyn RuntimeVarDb,
2155 backend: FlowBackend,
2156 platform: FlowPlatform,
2157 arch: FlowArch,
2158 ) -> RustRuntimeServices<'_> {
2159 RustRuntimeServices {
2160 runtime_var_db,
2161 backend,
2162 platform,
2163 arch,
2164 has_read_secret: false,
2165 }
2166 }
2167
2168 pub struct RustRuntimeServices<'a> {
2169 runtime_var_db: &'a mut dyn RuntimeVarDb,
2170 backend: FlowBackend,
2171 platform: FlowPlatform,
2172 arch: FlowArch,
2173 has_read_secret: bool,
2174 }
2175
2176 impl RustRuntimeServices<'_> {
2177 /// What backend the flow is being running on (e.g: locally, ADO,
2178 /// GitHub, etc...)
2179 pub fn backend(&self) -> FlowBackend {
2180 self.backend
2181 }
2182
2183 /// What platform the flow is being running on (e.g: windows, linux,
2184 /// etc...).
2185 pub fn platform(&self) -> FlowPlatform {
2186 self.platform
2187 }
2188
2189 /// What arch the flow is being running on (X86_64 or Aarch64)
2190 pub fn arch(&self) -> FlowArch {
2191 self.arch
2192 }
2193
2194 /// Write a value.
2195 ///
2196 /// If this step has already read a secret value, then this will be
2197 /// written as a secret value, as a conservative estimate to avoid
2198 /// leaking secrets. Use [`write_secret`](Self::write_secret) or
2199 /// [`write_not_secret`](Self::write_not_secret) to override this
2200 /// behavior.
2201 pub fn write<T>(&mut self, var: ClaimedWriteVar<T>, val: &T)
2202 where
2203 T: Serialize + DeserializeOwned,
2204 {
2205 self.write_maybe_secret(var, val, self.has_read_secret)
2206 }
2207
2208 /// Write a secret value, such as a key or token.
2209 ///
2210 /// Flowey will avoid logging this value, and if the value is
2211 /// converted to a CI environment variable, the CI system will be
2212 /// told not to print the value either.
2213 pub fn write_secret<T>(&mut self, var: ClaimedWriteVar<T>, val: &T)
2214 where
2215 T: Serialize + DeserializeOwned,
2216 {
2217 self.write_maybe_secret(var, val, true)
2218 }
2219
2220 /// Write a value that is not secret, even if this step has already
2221 /// read secret values.
2222 ///
2223 /// Usually [`write`](Self::write) is preferred--use this only when
2224 /// your step reads secret values and you explicitly want to write a
2225 /// non-secret value.
2226 pub fn write_not_secret<T>(&mut self, var: ClaimedWriteVar<T>, val: &T)
2227 where
2228 T: Serialize + DeserializeOwned,
2229 {
2230 self.write_maybe_secret(var, val, false)
2231 }
2232
2233 fn write_maybe_secret<T>(&mut self, var: ClaimedWriteVar<T>, val: &T, is_secret: bool)
2234 where
2235 T: Serialize + DeserializeOwned,
2236 {
2237 let val = if var.is_side_effect {
2238 b"null".to_vec()
2239 } else {
2240 serde_json::to_vec(val).expect("improve this error path")
2241 };
2242 self.runtime_var_db
2243 .set_var(&var.backing_var, is_secret, val);
2244 }
2245
2246 pub fn write_all<T>(
2247 &mut self,
2248 vars: impl IntoIterator<Item = ClaimedWriteVar<T>>,
2249 val: &T,
2250 ) where
2251 T: Serialize + DeserializeOwned,
2252 {
2253 for var in vars {
2254 self.write(var, val)
2255 }
2256 }
2257
2258 pub fn read<T: ReadVarValue>(&mut self, var: T) -> T::Value {
2259 var.read_value(self)
2260 }
2261
2262 pub(crate) fn get_var(&mut self, var: &str, is_side_effect: bool) -> Vec<u8> {
2263 let (v, is_secret) = self.runtime_var_db.get_var(var);
2264 self.has_read_secret |= is_secret && !is_side_effect;
2265 v
2266 }
2267
2268 /// DANGEROUS: Set the value of _Global_ Environment Variable (GitHub Actions only).
2269 ///
2270 /// It is up to the caller to ensure that the variable does not get
2271 /// unintentionally overwritten or used.
2272 ///
2273 /// This method should be used rarely and with great care!
2274 pub fn dangerous_gh_set_global_env_var(
2275 &mut self,
2276 var: String,
2277 gh_env_var: String,
2278 ) -> anyhow::Result<()> {
2279 if !matches!(self.backend, FlowBackend::Github) {
2280 return Err(anyhow::anyhow!(
2281 "dangerous_set_gh_env_var can only be used on GitHub Actions"
2282 ));
2283 }
2284
2285 let gh_env_file_path = std::env::var("GITHUB_ENV")?;
2286 let mut gh_env_file = fs_err::OpenOptions::new()
2287 .append(true)
2288 .open(gh_env_file_path)?;
2289 let gh_env_var_assignment = format!(
2290 r#"{}<<EOF
2291{}
2292EOF
2293"#,
2294 gh_env_var, var
2295 );
2296 std::io::Write::write_all(&mut gh_env_file, gh_env_var_assignment.as_bytes())?;
2297
2298 Ok(())
2299 }
2300 }
2301 }
2302}
2303
2304/// The base underlying implementation of all FlowNode variants.
2305///
2306/// Do not implement this directly! Use the `new_flow_node!` family of macros
2307/// instead!
2308pub trait FlowNodeBase {
2309 type Request: Serialize + DeserializeOwned;
2310
2311 fn imports(&mut self, ctx: &mut ImportCtx<'_>);
2312 fn emit(&mut self, requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()>;
2313
2314 /// A noop method that all human-written impls of `FlowNodeBase` are
2315 /// required to implement.
2316 ///
2317 /// By implementing this method, you're stating that you "know what you're
2318 /// doing" by having this manual impl.
2319 fn i_know_what_im_doing_with_this_manual_impl(&mut self);
2320}
2321
2322pub mod erased {
2323 use crate::node::FlowNodeBase;
2324 use crate::node::NodeCtx;
2325 use crate::node::user_facing::*;
2326
2327 pub struct ErasedNode<N: FlowNodeBase>(pub N);
2328
2329 impl<N: FlowNodeBase> ErasedNode<N> {
2330 pub fn from_node(node: N) -> Self {
2331 Self(node)
2332 }
2333 }
2334
2335 impl<N> FlowNodeBase for ErasedNode<N>
2336 where
2337 N: FlowNodeBase,
2338 {
2339 // FIXME: this should be using type-erased serde
2340 type Request = Box<[u8]>;
2341
2342 fn imports(&mut self, ctx: &mut ImportCtx<'_>) {
2343 self.0.imports(ctx)
2344 }
2345
2346 fn emit(&mut self, requests: Vec<Box<[u8]>>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()> {
2347 let mut converted_requests = Vec::new();
2348 for req in requests {
2349 converted_requests.push(serde_json::from_slice(&req)?)
2350 }
2351
2352 self.0.emit(converted_requests, ctx)
2353 }
2354
2355 fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
2356 }
2357}
2358
2359/// Cheap handle to a registered [`FlowNode`]
2360#[derive(Clone, Copy, PartialEq, Eq, Hash)]
2361pub struct NodeHandle(std::any::TypeId);
2362
2363impl Ord for NodeHandle {
2364 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
2365 self.modpath().cmp(other.modpath())
2366 }
2367}
2368
2369impl PartialOrd for NodeHandle {
2370 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
2371 Some(self.cmp(other))
2372 }
2373}
2374
2375impl std::fmt::Debug for NodeHandle {
2376 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2377 std::fmt::Debug::fmt(&self.try_modpath(), f)
2378 }
2379}
2380
2381impl NodeHandle {
2382 pub fn from_type<N: FlowNodeBase + 'static>() -> NodeHandle {
2383 NodeHandle(std::any::TypeId::of::<N>())
2384 }
2385
2386 pub fn from_modpath(modpath: &str) -> NodeHandle {
2387 node_luts::erased_node_by_modpath().get(modpath).unwrap().0
2388 }
2389
2390 pub fn try_from_modpath(modpath: &str) -> Option<NodeHandle> {
2391 node_luts::erased_node_by_modpath()
2392 .get(modpath)
2393 .map(|(s, _)| *s)
2394 }
2395
2396 pub fn new_erased_node(&self) -> Box<dyn FlowNodeBase<Request = Box<[u8]>>> {
2397 let ctor = node_luts::erased_node_by_typeid().get(self).unwrap();
2398 ctor()
2399 }
2400
2401 pub fn modpath(&self) -> &'static str {
2402 node_luts::modpath_by_node_typeid().get(self).unwrap()
2403 }
2404
2405 pub fn try_modpath(&self) -> Option<&'static str> {
2406 node_luts::modpath_by_node_typeid().get(self).cloned()
2407 }
2408
2409 /// Return a dummy NodeHandle, which will panic if `new_erased_node` is ever
2410 /// called on it.
2411 pub fn dummy() -> NodeHandle {
2412 NodeHandle(std::any::TypeId::of::<()>())
2413 }
2414}
2415
2416pub fn list_all_registered_nodes() -> impl Iterator<Item = NodeHandle> {
2417 node_luts::modpath_by_node_typeid().keys().cloned()
2418}
2419
2420// Encapsulate these look up tables in their own module to limit the scope of
2421// the HashMap import.
2422//
2423// In general, using HashMap in flowey is a recipe for disaster, given that
2424// iterating through the hash-map will result in non-deterministic orderings,
2425// which can cause annoying ordering churn.
2426//
2427// That said, in this case, it's OK since the code using these LUTs won't ever
2428// iterate through the map.
2429//
2430// Why is the HashMap even necessary vs. a BTreeMap?
2431//
2432// Well... NodeHandle's `Ord` impl does a `modpath` comparison instead of a
2433// TypeId comparison, since TypeId will vary between compilations.
2434mod node_luts {
2435 use super::FlowNodeBase;
2436 use super::NodeHandle;
2437 use std::collections::HashMap;
2438 use std::sync::OnceLock;
2439
2440 pub(super) fn modpath_by_node_typeid() -> &'static HashMap<NodeHandle, &'static str> {
2441 static TYPEID_TO_MODPATH: OnceLock<HashMap<NodeHandle, &'static str>> = OnceLock::new();
2442
2443 TYPEID_TO_MODPATH.get_or_init(|| {
2444 let mut lookup = HashMap::new();
2445 for crate::node::private::FlowNodeMeta {
2446 module_path,
2447 ctor: _,
2448 typeid,
2449 } in crate::node::private::FLOW_NODES
2450 {
2451 let existing = lookup.insert(
2452 NodeHandle(*typeid),
2453 module_path
2454 .strip_suffix("::_only_one_call_to_flowey_node_per_module")
2455 .unwrap(),
2456 );
2457 // if this were to fire for an array where the key is a TypeId...
2458 // something has gone _terribly_ wrong
2459 assert!(existing.is_none())
2460 }
2461
2462 lookup
2463 })
2464 }
2465
2466 pub(super) fn erased_node_by_typeid()
2467 -> &'static HashMap<NodeHandle, fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>> {
2468 static LOOKUP: OnceLock<
2469 HashMap<NodeHandle, fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>>,
2470 > = OnceLock::new();
2471
2472 LOOKUP.get_or_init(|| {
2473 let mut lookup = HashMap::new();
2474 for crate::node::private::FlowNodeMeta {
2475 module_path: _,
2476 ctor,
2477 typeid,
2478 } in crate::node::private::FLOW_NODES
2479 {
2480 let existing = lookup.insert(NodeHandle(*typeid), *ctor);
2481 // if this were to fire for an array where the key is a TypeId...
2482 // something has gone _terribly_ wrong
2483 assert!(existing.is_none())
2484 }
2485
2486 lookup
2487 })
2488 }
2489
2490 pub(super) fn erased_node_by_modpath() -> &'static HashMap<
2491 &'static str,
2492 (
2493 NodeHandle,
2494 fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>,
2495 ),
2496 > {
2497 static MODPATH_LOOKUP: OnceLock<
2498 HashMap<
2499 &'static str,
2500 (
2501 NodeHandle,
2502 fn() -> Box<dyn FlowNodeBase<Request = Box<[u8]>>>,
2503 ),
2504 >,
2505 > = OnceLock::new();
2506
2507 MODPATH_LOOKUP.get_or_init(|| {
2508 let mut lookup = HashMap::new();
2509 for crate::node::private::FlowNodeMeta { module_path, ctor, typeid } in crate::node::private::FLOW_NODES {
2510 let existing = lookup.insert(module_path.strip_suffix("::_only_one_call_to_flowey_node_per_module").unwrap(), (NodeHandle(*typeid), *ctor));
2511 if existing.is_some() {
2512 panic!("conflicting node registrations at {module_path}! please ensure there is a single node per module!")
2513 }
2514 }
2515 lookup
2516 })
2517 }
2518}
2519
2520#[doc(hidden)]
2521pub mod private {
2522 pub use linkme;
2523
2524 pub struct FlowNodeMeta {
2525 pub module_path: &'static str,
2526 pub ctor: fn() -> Box<dyn super::FlowNodeBase<Request = Box<[u8]>>>,
2527 pub typeid: std::any::TypeId,
2528 }
2529
2530 #[linkme::distributed_slice]
2531 pub static FLOW_NODES: [FlowNodeMeta] = [..];
2532
2533 // UNSAFETY: linkme uses manual link sections, which are unsafe.
2534 #[expect(unsafe_code)]
2535 #[linkme::distributed_slice(FLOW_NODES)]
2536 static DUMMY_FLOW_NODE: FlowNodeMeta = FlowNodeMeta {
2537 module_path: "<dummy>::_only_one_call_to_flowey_node_per_module",
2538 ctor: || unreachable!(),
2539 typeid: std::any::TypeId::of::<()>(),
2540 };
2541}
2542
2543#[doc(hidden)]
2544#[macro_export]
2545macro_rules! new_flow_node_base {
2546 (struct Node) => {
2547 /// (see module-level docs)
2548 #[non_exhaustive]
2549 pub struct Node;
2550
2551 mod _only_one_call_to_flowey_node_per_module {
2552 const _: () = {
2553 use $crate::node::private::linkme;
2554
2555 fn new_erased() -> Box<dyn $crate::node::FlowNodeBase<Request = Box<[u8]>>> {
2556 Box::new($crate::node::erased::ErasedNode(super::Node))
2557 }
2558
2559 #[linkme::distributed_slice($crate::node::private::FLOW_NODES)]
2560 #[linkme(crate = linkme)]
2561 static FLOW_NODE: $crate::node::private::FlowNodeMeta =
2562 $crate::node::private::FlowNodeMeta {
2563 module_path: module_path!(),
2564 ctor: new_erased,
2565 typeid: std::any::TypeId::of::<super::Node>(),
2566 };
2567 };
2568 }
2569 };
2570}
2571
2572/// A reusable unit of automation logic in flowey.
2573///
2574/// FlowNodes process requests, emit steps, and can depend on other nodes. They are
2575/// the building blocks for creating complex automation workflows.
2576///
2577/// # The Node/Request Pattern
2578///
2579/// Every node has an associated **Request** type that defines what the node can do.
2580/// Nodes receive a vector of requests and process them together, allowing for
2581/// aggregation and conflict resolution.
2582///
2583/// # Example: Basic FlowNode Implementation
2584///
2585/// ```rust,ignore
2586/// use flowey_core::node::*;
2587///
2588/// // Define the node
2589/// new_flow_node!(struct Node);
2590///
2591/// // Define requests using the flowey_request! macro
2592/// flowey_request! {
2593/// pub enum Request {
2594/// InstallRust(String), // Install specific version
2595/// EnsureInstalled(WriteVar<SideEffect>), // Ensure it's installed
2596/// GetCargoHome(WriteVar<PathBuf>), // Get CARGO_HOME path
2597/// }
2598/// }
2599///
2600/// impl FlowNode for Node {
2601/// type Request = Request;
2602///
2603/// fn imports(ctx: &mut ImportCtx<'_>) {
2604/// // Declare node dependencies
2605/// ctx.import::<other_node::Node>();
2606/// }
2607///
2608/// fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()> {
2609/// // 1. Aggregate and validate requests
2610/// let mut version = None;
2611/// let mut ensure_installed = Vec::new();
2612/// let mut get_cargo_home = Vec::new();
2613///
2614/// for req in requests {
2615/// match req {
2616/// Request::InstallRust(v) => {
2617/// same_across_all_reqs("version", &mut version, v)?;
2618/// }
2619/// Request::EnsureInstalled(var) => ensure_installed.push(var),
2620/// Request::GetCargoHome(var) => get_cargo_home.push(var),
2621/// }
2622/// }
2623///
2624/// let version = version.ok_or(anyhow::anyhow!("Version not specified"))?;
2625///
2626/// // 2. Emit steps to do the work
2627/// ctx.emit_rust_step("install rust", |ctx| {
2628/// let ensure_installed = ensure_installed.claim(ctx);
2629/// let get_cargo_home = get_cargo_home.claim(ctx);
2630/// move |rt| {
2631/// // Install rust with the specified version
2632/// // Write to all the output variables
2633/// for var in ensure_installed {
2634/// rt.write(var, &());
2635/// }
2636/// for var in get_cargo_home {
2637/// rt.write(var, &PathBuf::from("/path/to/cargo"));
2638/// }
2639/// Ok(())
2640/// }
2641/// });
2642///
2643/// Ok(())
2644/// }
2645/// }
2646/// ```
2647///
2648/// # When to Use FlowNode vs SimpleFlowNode
2649///
2650/// **Use `FlowNode`** when you need to:
2651/// - Aggregate multiple requests and process them together
2652/// - Resolve conflicts between requests
2653/// - Perform complex request validation
2654///
2655/// **Use [`SimpleFlowNode`]** when:
2656/// - Each request can be processed independently
2657/// - No aggregation logic is needed
2658pub trait FlowNode {
2659 /// The request type that defines what operations this node can perform.
2660 ///
2661 /// Use the [`crate::flowey_request!`] macro to define this type.
2662 type Request: Serialize + DeserializeOwned;
2663
2664 /// A list of nodes that this node is capable of taking a dependency on.
2665 ///
2666 /// Attempting to take a dep on a node that wasn't imported via this method
2667 /// will result in an error during flow resolution time.
2668 ///
2669 /// * * *
2670 ///
2671 /// To put it bluntly: This is boilerplate.
2672 ///
2673 /// We (the flowey devs) are thinking about ways to avoid requiring this
2674 /// method, but do not have a good solution at this time.
2675 fn imports(ctx: &mut ImportCtx<'_>);
2676
2677 /// Given a set of incoming `requests`, emit various steps to run, set
2678 /// various dependencies, etc...
2679 fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()>;
2680}
2681
2682#[macro_export]
2683macro_rules! new_flow_node {
2684 (struct Node) => {
2685 $crate::new_flow_node_base!(struct Node);
2686
2687 impl $crate::node::FlowNodeBase for Node
2688 where
2689 Node: FlowNode,
2690 {
2691 type Request = <Node as FlowNode>::Request;
2692
2693 fn imports(&mut self, dep: &mut $crate::node::ImportCtx<'_>) {
2694 <Node as FlowNode>::imports(dep)
2695 }
2696
2697 fn emit(
2698 &mut self,
2699 requests: Vec<Self::Request>,
2700 ctx: &mut $crate::node::NodeCtx<'_>,
2701 ) -> anyhow::Result<()> {
2702 <Node as FlowNode>::emit(requests, ctx)
2703 }
2704
2705 fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
2706 }
2707 };
2708}
2709
2710/// A helper trait to streamline implementing [`FlowNode`] instances that only
2711/// ever operate on a single request at a time.
2712///
2713/// In essence, [`SimpleFlowNode`] handles the boilerplate (and rightward-drift)
2714/// of manually writing:
2715///
2716/// ```ignore
2717/// impl FlowNode for Node {
2718/// fn imports(dep: &mut ImportCtx<'_>) { ... }
2719/// fn emit(requests: Vec<Self::Request>, ctx: &mut NodeCtx<'_>) {
2720/// for req in requests {
2721/// Node::process_request(req, ctx)
2722/// }
2723/// }
2724/// }
2725/// ```
2726///
2727/// Nodes which accept a `struct Request` often fall into this pattern, whereas
2728/// nodes which accept a `enum Request` typically require additional logic to
2729/// aggregate / resolve incoming requests.
2730pub trait SimpleFlowNode {
2731 type Request: Serialize + DeserializeOwned;
2732
2733 /// A list of nodes that this node is capable of taking a dependency on.
2734 ///
2735 /// Attempting to take a dep on a node that wasn't imported via this method
2736 /// will result in an error during flow resolution time.
2737 ///
2738 /// * * *
2739 ///
2740 /// To put it bluntly: This is boilerplate.
2741 ///
2742 /// We (the flowey devs) are thinking about ways to avoid requiring this
2743 /// method, but do not have a good solution at this time.
2744 fn imports(ctx: &mut ImportCtx<'_>);
2745
2746 /// Process a single incoming `Self::Request`
2747 fn process_request(request: Self::Request, ctx: &mut NodeCtx<'_>) -> anyhow::Result<()>;
2748}
2749
2750#[macro_export]
2751macro_rules! new_simple_flow_node {
2752 (struct Node) => {
2753 $crate::new_flow_node_base!(struct Node);
2754
2755 impl $crate::node::FlowNodeBase for Node
2756 where
2757 Node: $crate::node::SimpleFlowNode,
2758 {
2759 type Request = <Node as $crate::node::SimpleFlowNode>::Request;
2760
2761 fn imports(&mut self, dep: &mut $crate::node::ImportCtx<'_>) {
2762 <Node as $crate::node::SimpleFlowNode>::imports(dep)
2763 }
2764
2765 fn emit(&mut self, requests: Vec<Self::Request>, ctx: &mut $crate::node::NodeCtx<'_>) -> anyhow::Result<()> {
2766 for req in requests {
2767 <Node as $crate::node::SimpleFlowNode>::process_request(req, ctx)?
2768 }
2769
2770 Ok(())
2771 }
2772
2773 fn i_know_what_im_doing_with_this_manual_impl(&mut self) {}
2774 }
2775 };
2776}
2777
2778/// A "glue" trait which improves [`NodeCtx::req`] ergonomics, by tying a
2779/// particular `Request` type to its corresponding [`FlowNode`].
2780///
2781/// This trait should be autogenerated via [`flowey_request!`] - do not try to
2782/// implement it manually!
2783///
2784/// [`flowey_request!`]: crate::flowey_request
2785pub trait IntoRequest {
2786 type Node: FlowNodeBase;
2787 fn into_request(self) -> <Self::Node as FlowNodeBase>::Request;
2788
2789 /// By implementing this method manually, you're indicating that you know what you're
2790 /// doing,
2791 #[doc(hidden)]
2792 #[expect(nonstandard_style)]
2793 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self);
2794}
2795
2796#[doc(hidden)]
2797#[macro_export]
2798macro_rules! __flowey_request_inner {
2799 //
2800 // @emit_struct: emit structs for each variant of the request enum
2801 //
2802 (@emit_struct [$req:ident]
2803 $(#[$a:meta])*
2804 $variant:ident($($tt:tt)*),
2805 $($rest:tt)*
2806 ) => {
2807 $(#[$a])*
2808 #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
2809 pub struct $variant($($tt)*);
2810
2811 impl IntoRequest for $variant {
2812 type Node = Node;
2813 fn into_request(self) -> $req {
2814 $req::$variant(self)
2815 }
2816 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
2817 }
2818
2819 $crate::__flowey_request_inner!(@emit_struct [$req] $($rest)*);
2820 };
2821 (@emit_struct [$req:ident]
2822 $(#[$a:meta])*
2823 $variant:ident { $($tt:tt)* },
2824 $($rest:tt)*
2825 ) => {
2826 $(#[$a])*
2827 #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
2828 pub struct $variant {
2829 $($tt)*
2830 }
2831
2832 impl IntoRequest for $variant {
2833 type Node = Node;
2834 fn into_request(self) -> $req {
2835 $req::$variant(self)
2836 }
2837 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
2838 }
2839
2840 $crate::__flowey_request_inner!(@emit_struct [$req] $($rest)*);
2841 };
2842 (@emit_struct [$req:ident]
2843 $(#[$a:meta])*
2844 $variant:ident,
2845 $($rest:tt)*
2846 ) => {
2847 $(#[$a])*
2848 #[derive(Serialize, Deserialize)]
2849 pub struct $variant;
2850
2851 impl IntoRequest for $variant {
2852 type Node = Node;
2853 fn into_request(self) -> $req {
2854 $req::$variant(self)
2855 }
2856 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
2857 }
2858
2859 $crate::__flowey_request_inner!(@emit_struct [$req] $($rest)*);
2860 };
2861 (@emit_struct [$req:ident]
2862 ) => {};
2863
2864 //
2865 // @emit_req_enum: build up root request enum
2866 //
2867 (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
2868 $(#[$a:meta])*
2869 $variant:ident($($tt:tt)*),
2870 $($rest:tt)*
2871 ) => {
2872 $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*), $($prev[$($prev_a,)*])* $variant[$($a,)*]] $($rest)*);
2873 };
2874 (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
2875 $(#[$a:meta])*
2876 $variant:ident { $($tt:tt)* },
2877 $($rest:tt)*
2878 ) => {
2879 $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*), $($prev[$($prev_a,)*])* $variant[$($a,)*]] $($rest)*);
2880 };
2881 (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
2882 $(#[$a:meta])*
2883 $variant:ident,
2884 $($rest:tt)*
2885 ) => {
2886 $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*), $($prev[$($prev_a,)*])* $variant[$($a,)*]] $($rest)*);
2887 };
2888 (@emit_req_enum [$req:ident($($root_a:meta,)*), $($prev:ident[$($prev_a:meta,)*])*]
2889 ) => {
2890 #[derive(Serialize, Deserialize)]
2891 pub enum $req {$(
2892 $(#[$prev_a])*
2893 $prev(self::req::$prev),
2894 )*}
2895
2896 impl IntoRequest for $req {
2897 type Node = Node;
2898 fn into_request(self) -> $req {
2899 self
2900 }
2901 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
2902 }
2903 };
2904}
2905
2906/// Declare a new `Request` type for the current `Node`.
2907///
2908/// ## `struct` and `enum` Requests
2909///
2910/// When wrapping a vanilla Rust `struct` and `enum` declaration, this macro
2911/// simply derives [`Serialize`], [`Deserialize`], and [`IntoRequest`] for the
2912/// type, and does nothing else.
2913///
2914/// ## `enum_struct` Requests
2915///
2916/// This macro also supports a special kind of `enum_struct` derive, which
2917/// allows declaring a Request enum where each variant is split off into its own
2918/// separate (named) `struct`.
2919///
2920/// e.g:
2921///
2922/// ```ignore
2923/// flowey_request! {
2924/// pub enum_struct Foo {
2925/// Bar,
2926/// Baz(pub usize),
2927/// Qux(pub String),
2928/// }
2929/// }
2930/// ```
2931///
2932/// will be expanded into:
2933///
2934/// ```ignore
2935/// #[derive(Serialize, Deserialize)]
2936/// pub enum Foo {
2937/// Bar(req::Bar),
2938/// Baz(req::Baz),
2939/// Qux(req::Qux),
2940/// }
2941///
2942/// pud mod req {
2943/// #[derive(Serialize, Deserialize)]
2944/// pub struct Bar;
2945///
2946/// #[derive(Serialize, Deserialize)]
2947/// pub struct Baz(pub usize);
2948///
2949/// #[derive(Serialize, Deserialize)]
2950/// pub struct Qux(pub String);
2951/// }
2952/// ```
2953#[macro_export]
2954macro_rules! flowey_request {
2955 (
2956 $(#[$root_a:meta])*
2957 pub enum_struct $req:ident {
2958 $($tt:tt)*
2959 }
2960 ) => {
2961 $crate::__flowey_request_inner!(@emit_req_enum [$req($($root_a,)*),] $($tt)*);
2962 pub mod req {
2963 use super::*;
2964 $crate::__flowey_request_inner!(@emit_struct [$req] $($tt)*);
2965 }
2966 };
2967
2968 (
2969 $(#[$a:meta])*
2970 pub enum $req:ident {
2971 $($tt:tt)*
2972 }
2973 ) => {
2974 $(#[$a])*
2975 #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
2976 pub enum $req {
2977 $($tt)*
2978 }
2979
2980 impl $crate::node::IntoRequest for $req {
2981 type Node = Node;
2982 fn into_request(self) -> $req {
2983 self
2984 }
2985 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
2986 }
2987 };
2988
2989 (
2990 $(#[$a:meta])*
2991 pub struct $req:ident {
2992 $($tt:tt)*
2993 }
2994 ) => {
2995 $(#[$a])*
2996 #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
2997 pub struct $req {
2998 $($tt)*
2999 }
3000
3001 impl $crate::node::IntoRequest for $req {
3002 type Node = Node;
3003 fn into_request(self) -> $req {
3004 self
3005 }
3006 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
3007 }
3008 };
3009
3010 (
3011 $(#[$a:meta])*
3012 pub struct $req:ident($($tt:tt)*);
3013 ) => {
3014 $(#[$a])*
3015 #[derive($crate::reexports::Serialize, $crate::reexports::Deserialize)]
3016 pub struct $req($($tt)*);
3017
3018 impl $crate::node::IntoRequest for $req {
3019 type Node = Node;
3020 fn into_request(self) -> $req {
3021 self
3022 }
3023 fn do_not_manually_impl_this_trait__use_the_flowey_request_macro_instead(&mut self) {}
3024 }
3025 };
3026}