//! Running a flow over one event. //! //! The flow types, their checks and the built-in flows are //! `swarm_wire::notify_flows`; the built-in and the custom flows are the same //! type and this walk runs both. A `match` node passes when every one of its //! conditions holds, and then each of its children runs, so one event can //! reach several branches. A `todo` node emits one op per recipient. The //! router runs only flows that pass [`Flow::validate`]. use std::collections::BTreeMap; use swarm_wire::notify_flows::{Condition, Flow, Node, NodeKind, Recipients, TodoSink}; use swarm_wire::router_todo::{Op, RouterTodoOp}; /// One event, as the fields a flow reads. pub type Fields = BTreeMap<&'static str, Value>; /// A field's value. #[derive(Clone, Debug, PartialEq, Eq)] pub enum Value { Text(String), List(Vec), } /// One op the walk emitted, for one recipient. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Action { pub flow: String, pub node: String, pub agent: String, pub op: RouterTodoOp, } /// Walk `flow` for one event of type `event_type` and return the ops it /// emits. Assumes [`Flow::validate`] passed. pub fn evaluate(flow: &Flow, event_type: &str, fields: &Fields) -> Vec { let Some(root) = flow .nodes .iter() .find(|n| matches!(&n.kind, NodeKind::Source { events } if events.iter().any(|e| e == event_type))) else { return Vec::new(); }; let mut actions = Vec::new(); let mut stack = vec![root.id.as_str()]; while let Some(id) = stack.pop() { let Some(node) = flow.node(id) else { continue }; match &node.kind { NodeKind::Source { .. } => stack.extend(flow.children(id)), NodeKind::Match { when } => { if when.iter().all(|c| holds(c, fields)) { stack.extend(flow.children(id)); } } NodeKind::Todo(sink) => actions.extend(emit(flow, node, sink, fields)), } } actions } fn emit(flow: &Flow, node: &Node, sink: &TodoSink, fields: &Fields) -> Vec { let recipients = match &sink.to { Recipients::Agent(agent) => vec![agent.clone()], Recipients::Field(name) => match fields.get(name.as_str()) { Some(Value::List(items)) => items.clone(), Some(Value::Text(one)) => vec![one.clone()], None => Vec::new(), }, }; let rendered = expand(&sink.key, fields).and_then(|key| { let summary = match sink.op { Op::Upsert => expand(&sink.text, fields)?, Op::Clear => String::new(), }; Ok((key, summary)) }); let (key, summary) = match rendered { Ok(done) => done, Err(why) => { tracing::warn!(flow = %flow.id, node = %node.id, %why, "notify router: a todo node names a placeholder the event lacks; nothing sent"); return Vec::new(); } }; let op = RouterTodoOp { op: sink.op, key, prefix: sink.op == Op::Clear && sink.prefix, summary, source: format!("router:{}", flow.id), }; recipients .into_iter() .map(|agent| Action { flow: flow.id.clone(), node: node.id.clone(), agent, op: op.clone(), }) .collect() } fn holds(condition: &Condition, fields: &Fields) -> bool { match fields.get(condition.field.as_str()) { Some(Value::Text(v)) => *v == condition.equals, Some(Value::List(items)) => items.contains(&condition.equals), None => false, } } /// `template` with each `{field}` replaced by that field's value, a list /// joined with `, `. A name that is no field is an error naming it. pub fn expand(template: &str, fields: &Fields) -> Result { let mut out = String::with_capacity(template.len()); let mut rest = template; while let Some(open) = rest.find('{') { out.push_str(&rest[..open]); let after = &rest[open + 1..]; let Some(close) = after.find('}') else { out.push_str(&rest[open..]); return Ok(out); }; let name = &after[..close]; match fields.get(name) { Some(Value::Text(v)) => out.push_str(v), Some(Value::List(items)) => out.push_str(&items.join(", ")), None => return Err(format!("{{{name}}} is no event field")), } rest = &after[close + 1..]; } out.push_str(rest); Ok(out) } #[cfg(test)] mod tests { use swarm_wire::notify_flows::{Edge, builtins}; use super::*; fn text(v: &str) -> Value { Value::Text(v.to_owned()) } fn list(v: &[&str]) -> Value { Value::List(v.iter().map(|s| (*s).to_owned()).collect()) } fn event(action: &str, added: &[&str], removed: &[&str], holders: &[&str]) -> Fields { Fields::from([ ("action", text(action)), ("kind", text("issue")), ("repo", text("hyperhive/hyperhive")), ("number", text("7")), ("title", text("router")), ("url", text("https://forge/7")), ("assignees_added", list(added)), ("assignees_removed", list(removed)), ("todo_holders", list(holders)), ]) } fn flow(id: &str) -> Flow { builtins() .into_iter() .find(|f| f.id == id) .expect("a built-in") } #[test] fn assigning_queues_a_todo_for_each_newly_assigned_agent_only() { let assigned = flow("assigned"); let got = evaluate( &assigned, "issue_assign", &event("assigned", &["atlas", "iris"], &[], &[]), ); let agents: Vec<&str> = got.iter().map(|a| a.agent.as_str()).collect(); assert_eq!(agents, ["atlas", "iris"]); assert_eq!(got[0].op.op, Op::Upsert); assert_eq!(got[0].op.key, "forge:hyperhive/hyperhive#7:assignment"); assert_eq!( got[0].op.summary, "you are assigned to issue hyperhive/hyperhive#7: router (https://forge/7)" ); assert_eq!(got[0].op.source, "router:assigned"); // The match gates: an unassign event reaches no assigned sink. assert!( evaluate( &assigned, "issue_assign", &event("unassigned", &["atlas"], &[], &[]) ) .is_empty() ); // The source gates: another event type starts nothing. assert!( evaluate( &assigned, "issues", &event("assigned", &["atlas"], &[], &[]) ) .is_empty() ); } #[test] fn unassigning_rewrites_the_same_key_for_the_removed_agent() { let got = evaluate( &flow("unassigned"), "pull_request_assign", &event("unassigned", &[], &["argus"], &[]), ); assert_eq!(got.len(), 1); assert_eq!(got[0].agent, "argus"); assert_eq!(got[0].op.key, "forge:hyperhive/hyperhive#7:assignment"); assert!( got[0] .op .summary .starts_with("you are not assigned to issue") ); } #[test] fn closing_clears_by_prefix_for_every_holder() { let closed = flow("closed"); let got = evaluate( &closed, "issues", &event("closed", &[], &[], &["atlas", "argus"]), ); assert_eq!(got.len(), 2); for a in &got { assert_eq!(a.op.op, Op::Clear); assert!(a.op.prefix); assert_eq!(a.op.key, "forge:hyperhive/hyperhive#7:"); assert_eq!(a.op.summary, ""); } assert!(evaluate(&closed, "issues", &event("reopened", &[], &[], &["atlas"])).is_empty()); } /// A match node with two children runs both: the branching the tree /// allows. #[test] fn a_match_with_two_children_runs_both() { let mut f = flow("assigned"); let NodeKind::Todo(sink) = f.nodes[2].kind.clone() else { panic!("the third node is the sink") }; f.nodes.push(Node { id: "second".to_owned(), kind: NodeKind::Todo(TodoSink { to: Recipients::Field("assignees_removed".to_owned()), ..sink }), }); f.edges.push(Edge { from: "match".to_owned(), to: "second".to_owned(), }); assert_eq!(f.validate(), Ok(())); let got = evaluate( &f, "issue_assign", &event("assigned", &["atlas"], &["argus"], &[]), ); let mut nodes: Vec<(&str, &str)> = got .iter() .map(|a| (a.node.as_str(), a.agent.as_str())) .collect(); nodes.sort_unstable(); assert_eq!(nodes, [("second", "argus"), ("sink", "atlas")]); } /// A custom flow's sink can name one agent, whatever the event holds. #[test] fn a_sink_to_a_named_agent_reaches_it_once() { let mut f = flow("assigned"); f.nodes[2].kind = NodeKind::Todo(TodoSink { to: Recipients::Agent("triage".to_owned()), op: Op::Upsert, key: "forge:{repo}#{number}:triage".to_owned(), prefix: false, text: "triage {repo}#{number}".to_owned(), }); let got = evaluate( &f, "issue_assign", &event("assigned", &["atlas", "iris"], &[], &[]), ); assert_eq!(got.len(), 1); assert_eq!(got[0].agent, "triage"); assert_eq!(got[0].op.summary, "triage hyperhive/hyperhive#7"); assert_eq!(got[0].op.source, "router:assigned"); } #[test] fn a_placeholder_expands_to_its_field_and_an_unknown_one_is_an_error() { let fields = event("assigned", &["a", "b"], &[], &[]); assert_eq!( expand("{repo}#{number} {assignees_added} {", &fields), Ok("hyperhive/hyperhive#7 a, b {".to_owned()) ); assert_eq!( expand("x {nope}", &fields), Err("{nope} is no event field".to_owned()) ); } /// A sink naming a placeholder the event lacks sends nothing, rather /// than a todo under a literal `{name}` key. #[test] fn a_sink_with_an_unknown_placeholder_emits_nothing() { let mut f = flow("assigned"); f.nodes[2].kind = NodeKind::Todo(TodoSink { to: Recipients::Agent("triage".to_owned()), op: Op::Upsert, key: "forge:{repo}#{numbr}:triage".to_owned(), prefix: false, text: "t".to_owned(), }); let fields = event("assigned", &["atlas"], &[], &[]); assert!(evaluate(&f, "issue_assign", &fields).is_empty()); // Control: spelled right, the same flow emits. if let NodeKind::Todo(s) = &mut f.nodes[2].kind { s.key = "forge:{repo}#{number}:triage".to_owned(); } assert_eq!(evaluate(&f, "issue_assign", &fields).len(), 1); } }