streamkit_core/
control.rs

1// SPDX-FileCopyrightText: © 2025 StreamKit Contributors
2//
3// SPDX-License-Identifier: MPL-2.0
4
5//! Control messages for node and engine management.
6//!
7//! This module defines messages used to control node lifecycle and modify
8//! pipeline graphs at runtime:
9//!
10//! - [`NodeControlMessage`]: Messages sent to individual nodes to update parameters or control execution
11//! - [`EngineControlMessage`]: Messages sent to the engine to modify the pipeline graph
12//! - [`ConnectionMode`]: How a connection handles backpressure
13
14use serde::{Deserialize, Serialize};
15use ts_rs::TS;
16
17/// A message sent to a specific, running node to tune its parameters or control its lifecycle.
18#[derive(Debug, Deserialize, Serialize, TS)]
19#[ts(export)]
20pub enum NodeControlMessage {
21    UpdateParams(#[ts(type = "JsonValue")] serde_json::Value),
22    /// Start signal for source nodes waiting in Ready state.
23    /// Tells the node to begin producing packets.
24    Start,
25    /// Shutdown signal for graceful termination.
26    /// Nodes should clean up resources and exit their run loop when receiving this.
27    Shutdown,
28}
29
30/// Specifies how a connection handles backpressure from slow consumers.
31#[derive(Debug, Deserialize, Serialize, Clone, Copy, PartialEq, Eq, Default, TS)]
32#[ts(export)]
33#[serde(rename_all = "snake_case")]
34pub enum ConnectionMode {
35    /// Normal connection with synchronized backpressure.
36    /// If the downstream consumer is slow, the upstream producer will wait.
37    /// This ensures no packet loss but can stall the pipeline.
38    #[default]
39    Reliable,
40
41    /// Best-effort connection that drops packets when the downstream buffer is full.
42    /// Useful for observer outputs (metrics, UI, debug taps) that shouldn't stall
43    /// the main data flow. Dropped packets are logged and counted in metrics.
44    BestEffort,
45}
46
47/// A message sent to the central Engine actor to modify the pipeline graph itself.
48#[derive(Debug)]
49pub enum EngineControlMessage {
50    AddNode {
51        node_id: String,
52        kind: String,
53        params: Option<serde_json::Value>,
54    },
55    RemoveNode {
56        node_id: String,
57    },
58    Connect {
59        from_node: String,
60        from_pin: String,
61        to_node: String,
62        to_pin: String,
63        mode: ConnectionMode,
64    },
65    Disconnect {
66        from_node: String,
67        from_pin: String,
68        to_node: String,
69        to_pin: String,
70    },
71    TuneNode {
72        node_id: String,
73        message: NodeControlMessage,
74    },
75    Shutdown,
76}
streamkit_core/control.rs

streamkit_core/
control.rs
