use std::{collections::HashMap, fmt, sync::Arc};
use stateknot_core::{
BoxFuture, BudgetUsage, CancellationSignal, Checkpoint, ChildRunPolicyError, CompiledGraph,
Failure, GraphReducer, GraphReducerReference, GraphReference, NodeAttemptStartHead,
NodeControl, NodeId, NodeInvocationBindings, NodeStateChange, RetryAdvice,
};
use thiserror::Error;
use crate::{GraphChildJoin, JsonSchemaRegistry};
#[derive(Clone)]
pub struct GraphNodeContext {
attempt: NodeAttemptStartHead,
checkpoint: Arc<Checkpoint>,
cancellation: CancellationSignal,
child_join: Option<Arc<GraphChildJoin>>,
}
impl GraphNodeContext {
pub fn new(
attempt: NodeAttemptStartHead,
checkpoint: Arc<Checkpoint>,
cancellation: CancellationSignal,
) -> Result<Self, GraphNodeContextError> {
let activation = attempt.activation();
if activation.tenant_id() != checkpoint.tenant_id() {
return Err(GraphNodeContextError::TenantMismatch);
}
if activation.run_id() != checkpoint.run_id() {
return Err(GraphNodeContextError::RunMismatch);
}
if activation.base_checkpoint() != &checkpoint.head() {
return Err(GraphNodeContextError::CheckpointMismatch);
}
Ok(Self {
attempt,
checkpoint,
cancellation,
child_join: None,
})
}
#[must_use]
pub const fn attempt(&self) -> &NodeAttemptStartHead {
&self.attempt
}
#[must_use]
pub fn checkpoint(&self) -> &Checkpoint {
&self.checkpoint
}
#[must_use]
pub const fn cancellation(&self) -> &CancellationSignal {
&self.cancellation
}
#[must_use]
pub fn child_join(&self) -> Option<&GraphChildJoin> {
self.child_join.as_deref()
}
pub(crate) fn with_child_join(mut self, join: Arc<GraphChildJoin>) -> Self {
self.child_join = Some(join);
self
}
}
impl fmt::Debug for GraphNodeContext {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("GraphNodeContext")
.field("attempt", &self.attempt)
.field("checkpoint", &self.checkpoint.head())
.field("cancellation", &self.cancellation)
.finish_non_exhaustive()
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum GraphNodeContextError {
#[error("node execution context crosses a tenant boundary")]
TenantMismatch,
#[error("node execution context crosses a run boundary")]
RunMismatch,
#[error("node execution attempt does not belong to the supplied checkpoint")]
CheckpointMismatch,
}
#[derive(Clone, Debug)]
#[allow(clippy::large_enum_variant)]
pub enum GraphNodeExecution {
Completed {
state_change: NodeStateChange,
control: NodeControl,
bindings: NodeInvocationBindings,
usage: BudgetUsage,
},
ChildJoin(Box<stateknot_core::ChildRunJoinRequest>),
}
impl GraphNodeExecution {
#[must_use]
pub const fn new(
state_change: NodeStateChange,
control: NodeControl,
bindings: NodeInvocationBindings,
usage: BudgetUsage,
) -> Self {
Self::Completed {
state_change,
control,
bindings,
usage,
}
}
#[must_use]
pub fn child_join(request: stateknot_core::ChildRunJoinRequest) -> Self {
Self::ChildJoin(Box::new(request))
}
}
#[derive(Clone, Debug)]
pub struct GraphNodeExecutionError {
failure: Failure,
usage: BudgetUsage,
}
impl GraphNodeExecutionError {
pub fn new(
failure: Failure,
usage: BudgetUsage,
) -> Result<Self, GraphNodeExecutionErrorBuildError> {
if failure.caused_by_event_id().is_some() {
return Err(GraphNodeExecutionErrorBuildError::CausationAlreadyAttached);
}
if failure.retry_advice() == RetryAdvice::ReconcileFirst {
return Err(GraphNodeExecutionErrorBuildError::ReconciliationNotAllowed);
}
Ok(Self { failure, usage })
}
#[must_use]
pub const fn failure(&self) -> &Failure {
&self.failure
}
#[must_use]
pub const fn usage(&self) -> &BudgetUsage {
&self.usage
}
#[must_use]
pub fn into_parts(self) -> (Failure, BudgetUsage) {
(self.failure, self.usage)
}
}
#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum GraphNodeExecutionErrorBuildError {
#[error("node failure already contains durable event causation")]
CausationAlreadyAttached,
#[error("node failure cannot request reconcile-first recovery")]
ReconciliationNotAllowed,
}
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum GraphNodeScheduling {
#[default]
Exclusive,
JournalIsolated,
}
pub trait GraphNodeExecutor: Send + Sync + 'static {
fn graph(&self) -> &GraphReference;
fn node_id(&self) -> &NodeId;
fn scheduling(&self) -> GraphNodeScheduling {
GraphNodeScheduling::Exclusive
}
fn supports_child_join(&self) -> bool {
false
}
fn execute(
&self,
context: GraphNodeContext,
) -> BoxFuture<'_, Result<GraphNodeExecution, GraphNodeExecutionError>>;
}
#[derive(Clone)]
pub struct ExecutableGraph {
graph: Arc<CompiledGraph>,
schemas: JsonSchemaRegistry,
reducer: Arc<dyn GraphReducer>,
nodes: Arc<HashMap<NodeId, Arc<dyn GraphNodeExecutor>>>,
}
impl ExecutableGraph {
#[must_use]
pub fn graph(&self) -> &CompiledGraph {
&self.graph
}
#[must_use]
pub const fn schemas(&self) -> &JsonSchemaRegistry {
&self.schemas
}
#[must_use]
pub fn reducer(&self) -> &(dyn GraphReducer + 'static) {
self.reducer.as_ref()
}
#[must_use]
pub fn node(&self, node_id: &NodeId) -> Option<&(dyn GraphNodeExecutor + 'static)> {
self.nodes.get(node_id).map(Arc::as_ref)
}
#[must_use]
pub fn node_executor(&self, node_id: &NodeId) -> Option<Arc<dyn GraphNodeExecutor>> {
self.nodes.get(node_id).cloned()
}
#[must_use]
pub fn node_count(&self) -> usize {
self.nodes.len()
}
}
impl fmt::Debug for ExecutableGraph {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ExecutableGraph")
.field("graph", &self.graph.reference())
.field("reducer", self.reducer.reference())
.field("nodes", &self.nodes.len())
.finish_non_exhaustive()
}
}
pub struct ExecutableGraphRegistryBuilder {
schemas: JsonSchemaRegistry,
graphs: HashMap<GraphReference, Arc<CompiledGraph>>,
graph_identities: HashMap<stateknot_core::CapabilityIdentity, GraphReference>,
reducers: HashMap<GraphReducerReference, Arc<dyn GraphReducer>>,
reducer_identities: HashMap<stateknot_core::CapabilityIdentity, GraphReducerReference>,
nodes: HashMap<(GraphReference, NodeId), Arc<dyn GraphNodeExecutor>>,
}
impl ExecutableGraphRegistryBuilder {
pub const MAX_GRAPHS: usize = 1024;
pub const MAX_REDUCERS: usize = 1024;
pub const MAX_NODE_EXECUTORS: usize = 65_536;
#[must_use]
pub fn new(schemas: JsonSchemaRegistry) -> Self {
Self {
schemas,
graphs: HashMap::new(),
graph_identities: HashMap::new(),
reducers: HashMap::new(),
reducer_identities: HashMap::new(),
nodes: HashMap::new(),
}
}
pub fn register_graph(
&mut self,
graph: CompiledGraph,
) -> Result<(), ExecutableGraphRegistryError> {
if self.graphs.len() == Self::MAX_GRAPHS {
return Err(ExecutableGraphRegistryError::TooManyGraphs {
maximum: Self::MAX_GRAPHS,
actual: Self::MAX_GRAPHS + 1,
});
}
let reference = graph.reference();
if self.graphs.contains_key(&reference) {
return Err(ExecutableGraphRegistryError::DuplicateGraph {
reference: Box::new(reference),
});
}
if let Some(existing) = self.graph_identities.get(graph.identity()) {
return Err(ExecutableGraphRegistryError::GraphIdentityConflict {
existing: Box::new(existing.clone()),
rejected: Box::new(reference),
});
}
self.graph_identities
.insert(graph.identity().clone(), reference.clone());
self.graphs.insert(reference, Arc::new(graph));
Ok(())
}
pub fn register_reducer(
&mut self,
reducer: Arc<dyn GraphReducer>,
) -> Result<(), ExecutableGraphRegistryError> {
if self.reducers.len() == Self::MAX_REDUCERS {
return Err(ExecutableGraphRegistryError::TooManyReducers {
maximum: Self::MAX_REDUCERS,
actual: Self::MAX_REDUCERS + 1,
});
}
let reference = reducer.reference().clone();
if self.reducers.contains_key(&reference) {
return Err(ExecutableGraphRegistryError::DuplicateReducer {
reference: Box::new(reference),
});
}
if let Some(existing) = self.reducer_identities.get(reference.identity()) {
return Err(ExecutableGraphRegistryError::ReducerIdentityConflict {
existing: Box::new(existing.clone()),
rejected: Box::new(reference),
});
}
self.reducer_identities
.insert(reference.identity().clone(), reference.clone());
self.reducers.insert(reference, reducer);
Ok(())
}
pub fn register_node(
&mut self,
executor: Arc<dyn GraphNodeExecutor>,
) -> Result<(), ExecutableGraphRegistryError> {
if self.nodes.len() == Self::MAX_NODE_EXECUTORS {
return Err(ExecutableGraphRegistryError::TooManyNodeExecutors {
maximum: Self::MAX_NODE_EXECUTORS,
actual: Self::MAX_NODE_EXECUTORS + 1,
});
}
let key = (executor.graph().clone(), executor.node_id().clone());
if self.nodes.contains_key(&key) {
return Err(ExecutableGraphRegistryError::DuplicateNodeExecutor {
graph: Box::new(key.0),
node_id: key.1,
});
}
self.nodes.insert(key, executor);
Ok(())
}
pub fn build(self) -> Result<ExecutableGraphRegistry, ExecutableGraphRegistryError> {
if self.graphs.is_empty() {
return Err(ExecutableGraphRegistryError::EmptyGraphs);
}
for (reference, graph) in &self.graphs {
if let Some(policy) = graph.child_runs() {
for declaration in policy.declarations() {
let target = self.graphs.get(declaration.graph()).ok_or_else(|| {
ExecutableGraphRegistryError::MissingChildGraph {
parent: Box::new(reference.clone()),
child: Box::new(declaration.graph().clone()),
}
})?;
declaration
.validate_target(target, policy.limits())
.map_err(|source| ExecutableGraphRegistryError::ChildPolicy {
graph: Box::new(reference.clone()),
source,
})?;
}
}
}
let mut executable = HashMap::with_capacity(self.graphs.len());
let mut used_reducers = std::collections::HashSet::new();
let mut used_nodes = std::collections::HashSet::new();
for (reference, graph) in &self.graphs {
for schema in [
graph.input_schema(),
graph.state_schema(),
graph.update_schema(),
graph.output_schema(),
] {
if !self.schemas.contains(schema) {
return Err(ExecutableGraphRegistryError::MissingSchema {
graph: Box::new(reference.clone()),
schema: Box::new(schema.clone()),
});
}
}
let reducer = self.reducers.get(graph.reducer()).cloned().ok_or_else(|| {
ExecutableGraphRegistryError::MissingReducer {
graph: Box::new(reference.clone()),
reducer: Box::new(graph.reducer().clone()),
}
})?;
used_reducers.insert(graph.reducer().clone());
let mut graph_nodes = HashMap::with_capacity(graph.nodes().len());
for node in graph.nodes() {
let key = (reference.clone(), node.node_id().clone());
let executor = self.nodes.get(&key).cloned().ok_or_else(|| {
ExecutableGraphRegistryError::MissingNodeExecutor {
graph: Box::new(reference.clone()),
node_id: node.node_id().clone(),
}
})?;
let declares_children = graph.child_runs().is_some_and(|policy| {
policy
.declarations()
.iter()
.any(|d| d.node_id() == node.node_id())
});
if (declares_children && executor.scheduling() != GraphNodeScheduling::Exclusive)
|| (executor.supports_child_join()
&& (!declares_children
|| !crate::child_join::schema_available(&self.schemas)))
{
return Err(ExecutableGraphRegistryError::InvalidChildJoinExecutor);
}
used_nodes.insert(key);
graph_nodes.insert(node.node_id().clone(), executor);
}
executable.insert(
reference.clone(),
ExecutableGraph {
graph: Arc::clone(graph),
schemas: self.schemas.clone(),
reducer,
nodes: Arc::new(graph_nodes),
},
);
}
if let Some(reference) = self
.reducers
.keys()
.find(|reference| !used_reducers.contains(*reference))
{
return Err(ExecutableGraphRegistryError::OrphanReducer {
reducer: Box::new(reference.clone()),
});
}
if let Some((graph, node_id)) = self.nodes.keys().find(|key| !used_nodes.contains(*key)) {
return Err(ExecutableGraphRegistryError::OrphanNodeExecutor {
graph: Box::new(graph.clone()),
node_id: node_id.clone(),
});
}
Ok(ExecutableGraphRegistry {
schemas: self.schemas,
graphs: Arc::new(executable),
})
}
}
impl fmt::Debug for ExecutableGraphRegistryBuilder {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ExecutableGraphRegistryBuilder")
.field("schemas", &self.schemas)
.field("graphs", &self.graphs.len())
.field("reducers", &self.reducers.len())
.field("nodes", &self.nodes.len())
.finish_non_exhaustive()
}
}
#[derive(Clone)]
pub struct ExecutableGraphRegistry {
schemas: JsonSchemaRegistry,
graphs: Arc<HashMap<GraphReference, ExecutableGraph>>,
}
impl ExecutableGraphRegistry {
pub(crate) fn has_child_graphs(&self) -> bool {
self.graphs
.values()
.any(|entry| entry.graph().child_runs().is_some())
}
#[must_use]
pub fn resolve(&self, reference: &GraphReference) -> Option<&ExecutableGraph> {
self.graphs.get(reference)
}
#[must_use]
pub const fn schemas(&self) -> &JsonSchemaRegistry {
&self.schemas
}
#[must_use]
pub fn len(&self) -> usize {
self.graphs.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.graphs.is_empty()
}
}
impl fmt::Debug for ExecutableGraphRegistry {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("ExecutableGraphRegistry")
.field("schemas", &self.schemas.len())
.field("graphs", &self.graphs.len())
.finish_non_exhaustive()
}
}
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ExecutableGraphRegistryError {
#[error(
"child Join executor requires declared slots, exclusive scheduling and its audit schema"
)]
InvalidChildJoinExecutor,
#[error("executable registry lacks a declared child graph")]
MissingChildGraph {
parent: Box<GraphReference>,
child: Box<GraphReference>,
},
#[error("executable registry child policy validation failed: {source}")]
ChildPolicy {
graph: Box<GraphReference>,
#[source]
source: ChildRunPolicyError,
},
#[error("executable graph registry must contain at least one graph")]
EmptyGraphs,
#[error("executable registry contains {actual} graphs; maximum is {maximum}")]
TooManyGraphs {
maximum: usize,
actual: usize,
},
#[error("executable registry contains {actual} reducers; maximum is {maximum}")]
TooManyReducers {
maximum: usize,
actual: usize,
},
#[error("executable registry contains {actual} nodes; maximum is {maximum}")]
TooManyNodeExecutors {
maximum: usize,
actual: usize,
},
#[error("compiled graph reference was registered more than once")]
DuplicateGraph {
reference: Box<GraphReference>,
},
#[error("graph owner/name/version identity was reused with another definition")]
GraphIdentityConflict {
existing: Box<GraphReference>,
rejected: Box<GraphReference>,
},
#[error("graph reducer reference was registered more than once")]
DuplicateReducer {
reference: Box<GraphReducerReference>,
},
#[error("reducer owner/name/version identity was reused with another definition")]
ReducerIdentityConflict {
existing: Box<GraphReducerReference>,
rejected: Box<GraphReducerReference>,
},
#[error("graph node executor was registered more than once")]
DuplicateNodeExecutor {
graph: Box<GraphReference>,
node_id: NodeId,
},
#[error("compiled graph references an unavailable schema")]
MissingSchema {
graph: Box<GraphReference>,
schema: Box<stateknot_core::SchemaReference>,
},
#[error("compiled graph references an unavailable reducer")]
MissingReducer {
graph: Box<GraphReference>,
reducer: Box<GraphReducerReference>,
},
#[error("compiled graph node has no executable implementation")]
MissingNodeExecutor {
graph: Box<GraphReference>,
node_id: NodeId,
},
#[error("registered reducer is not referenced by any installed graph")]
OrphanReducer {
reducer: Box<GraphReducerReference>,
},
#[error("registered node executor is not declared by an installed graph")]
OrphanNodeExecutor {
graph: Box<GraphReference>,
node_id: NodeId,
},
}
#[cfg(test)]
#[path = "registry_child_tests.rs"]
mod child_tests;
#[cfg(test)]
mod tests {
use serde_json::{Value, json};
use stateknot_core::{
BoundedJson, CapabilityIdentity, CapabilityName, CapabilityReference, GraphExecutionLimits,
GraphNode, GraphReducerError, GraphReducerInput, GraphRoutes, IssuerId, PrincipalIdentity,
ReadyNodes, SchemaId, SchemaReference, SubjectId, Superstep, Version,
};
use super::*;
use crate::JsonSchemaRegistryBuilder;
const DRAFT: &str = "https://json-schema.org/draft/2020-12/schema";
fn identity(name: &str) -> CapabilityIdentity {
CapabilityIdentity::new(
PrincipalIdentity::new(
IssuerId::new("https://issuer.example.com").unwrap(),
SubjectId::new("runtime-tests").unwrap(),
),
CapabilityReference::new(CapabilityName::new(name).unwrap(), Version::new(1, 0, 0)),
)
}
fn schema_reference(id: &str, document: &Value) -> SchemaReference {
SchemaReference::new(
id.parse::<SchemaId>().unwrap(),
Version::new(1, 0, 0),
stateknot_core::Digest::sha256(serde_json_canonicalizer::to_vec(document).unwrap()),
)
}
fn schemas() -> (JsonSchemaRegistry, SchemaReference) {
let id = "https://schemas.example.com/graph-value/1.0.0";
let document = json!({
"$schema": DRAFT,
"$id": id,
"type": "object",
"additionalProperties": true
});
let reference = schema_reference(id, &document);
let mut builder = JsonSchemaRegistryBuilder::default();
builder.register(reference.clone(), document).unwrap();
(builder.build().unwrap(), reference)
}
fn graph(schema: &SchemaReference, reducer: GraphReducerReference) -> (CompiledGraph, NodeId) {
let node_id = NodeId::new("finish").unwrap();
let node = GraphNode::new(node_id.clone(), None, GraphRoutes::empty(), None, true).unwrap();
let graph = CompiledGraph::compile(
identity("graph"),
schema.clone(),
schema.clone(),
schema.clone(),
schema.clone(),
reducer,
ReadyNodes::try_new([node_id.clone()]).unwrap(),
[node],
GraphExecutionLimits::new(Superstep::new(32).unwrap(), 4).unwrap(),
)
.unwrap();
(graph, node_id)
}
struct Reducer {
reference: GraphReducerReference,
}
impl GraphReducer for Reducer {
fn reference(&self) -> &GraphReducerReference {
&self.reference
}
fn reduce(
&self,
state: &BoundedJson,
_: &[GraphReducerInput<'_>],
) -> Result<BoundedJson, GraphReducerError> {
Ok(state.clone())
}
}
struct Executor {
graph: GraphReference,
node_id: NodeId,
}
impl GraphNodeExecutor for Executor {
fn graph(&self) -> &GraphReference {
&self.graph
}
fn node_id(&self) -> &NodeId {
&self.node_id
}
fn execute(
&self,
_: GraphNodeContext,
) -> BoxFuture<'_, Result<GraphNodeExecution, GraphNodeExecutionError>> {
Box::pin(async { panic!("registry tests do not execute node code") })
}
}
#[test]
fn complete_registry_freezes_exact_graph_dependencies() {
let (schemas, schema) = schemas();
let reducer_reference =
GraphReducerReference::new(identity("reducer"), stateknot_core::Digest::sha256(b"v1"));
let reducer = Arc::new(Reducer {
reference: reducer_reference.clone(),
});
let (graph, node_id) = graph(&schema, reducer_reference.clone());
let graph_reference = graph.reference();
let executor: Arc<dyn GraphNodeExecutor> = Arc::new(Executor {
graph: graph_reference.clone(),
node_id: node_id.clone(),
});
let mut builder = ExecutableGraphRegistryBuilder::new(schemas);
builder.register_node(Arc::clone(&executor)).unwrap();
assert!(matches!(
builder.register_node(Arc::new(Executor {
graph: graph_reference.clone(),
node_id: node_id.clone(),
})),
Err(ExecutableGraphRegistryError::DuplicateNodeExecutor { .. })
));
builder.register_reducer(reducer).unwrap();
builder.register_graph(graph).unwrap();
let registry = builder.build().unwrap();
let executable = registry.resolve(&graph_reference).unwrap();
assert_eq!(registry.len(), 1);
assert_eq!(executable.graph().reference(), graph_reference);
assert_eq!(executable.reducer().reference(), &reducer_reference);
assert_eq!(executable.node(&node_id).unwrap().node_id(), &node_id);
assert!(Arc::ptr_eq(
&executable.node_executor(&node_id).unwrap(),
&executor
));
}
#[test]
fn build_rejects_missing_and_orphan_node_code() {
let (schemas, schema) = schemas();
let reducer_reference = GraphReducerReference::new(
identity("reducer"),
stateknot_core::Digest::sha256(b"reducer"),
);
let reducer = Arc::new(Reducer {
reference: reducer_reference.clone(),
});
let (graph, node_id) = graph(&schema, reducer_reference);
let graph_reference = graph.reference();
let mut missing = ExecutableGraphRegistryBuilder::new(schemas.clone());
missing.register_reducer(reducer.clone()).unwrap();
missing.register_graph(graph.clone()).unwrap();
assert!(matches!(
missing.build(),
Err(ExecutableGraphRegistryError::MissingNodeExecutor { .. })
));
let mut orphan = ExecutableGraphRegistryBuilder::new(schemas);
orphan.register_reducer(reducer).unwrap();
orphan.register_graph(graph).unwrap();
orphan
.register_node(Arc::new(Executor {
graph: graph_reference.clone(),
node_id,
}))
.unwrap();
orphan
.register_node(Arc::new(Executor {
graph: graph_reference,
node_id: NodeId::new("undeclared").unwrap(),
}))
.unwrap();
assert!(matches!(
orphan.build(),
Err(ExecutableGraphRegistryError::OrphanNodeExecutor { .. })
));
}
}