reifydb_flow_operator_sdk/
lib.rs

1//! ReifyDB Operator SDK
2
3#![cfg_attr(not(debug_assertions), deny(warnings))]
4
5use std::collections::HashMap;
6
7use reifydb_core::{
8	CommitVersion, Row,
9	interface::{FlowNodeId, SourceId},
10};
11use reifydb_type::{RowNumber, TypeConstraint, Value};
12
13pub mod catalog;
14pub mod change;
15pub mod context;
16pub mod error;
17pub mod ffi;
18pub mod marshal;
19pub mod stateful;
20pub mod store;
21pub mod testing;
22
23pub use catalog::Catalog;
24pub use change::FlowChangeBuilder;
25pub use context::OperatorContext;
26pub use error::{FFIError, Result};
27pub use reifydb_core::{
28	CowVec,
29	key::EncodableKey,
30	value::encoded::{EncodedKey, EncodedValues},
31};
32pub use stateful::State;
33pub use store::Store;
34
35/// Origin of a flow change
36#[derive(Debug, Clone)]
37pub enum FlowChangeOrigin {
38	/// Change originated from an external source (table, view, ring buffer)
39	External(SourceId),
40	/// Change originated from an internal flow node
41	Internal(FlowNodeId),
42}
43
44/// Represents a single diff in a flow change
45#[derive(Debug, Clone)]
46pub enum FlowDiff {
47	/// Insert a new row
48	Insert {
49		/// The row to insert
50		post: Row,
51	},
52	/// Update an existing row
53	Update {
54		/// The previous value
55		pre: Row,
56		/// The new value
57		post: Row,
58	},
59	/// Remove an existing row
60	Remove {
61		/// The row to remove
62		pre: Row,
63	},
64}
65
66/// Represents a flow change with insertions, updates, and deletions
67#[derive(Debug, Clone)]
68pub struct FlowChange {
69	/// Origin of this change
70	pub origin: FlowChangeOrigin,
71	/// The list of diffs (changes) in this flow change
72	pub diffs: Vec<FlowDiff>,
73	/// Version of this change
74	pub version: CommitVersion,
75}
76
77impl FlowChange {
78	/// Create a flow change from an external source
79	pub fn external(source: SourceId, version: CommitVersion, diffs: Vec<FlowDiff>) -> Self {
80		Self {
81			origin: FlowChangeOrigin::External(source),
82			diffs,
83			version,
84		}
85	}
86
87	/// Create a flow change from an internal flow node
88	pub fn internal(from: FlowNodeId, version: CommitVersion, diffs: Vec<FlowDiff>) -> Self {
89		Self {
90			origin: FlowChangeOrigin::Internal(from),
91			diffs,
92			version,
93		}
94	}
95}
96
97/// A single column definition in an operator's input/output
98#[derive(Debug, Clone)]
99pub struct OperatorColumnDef {
100	/// Column name
101	pub name: &'static str,
102	/// Column type constraint (use TypeConstraint::unconstrained(Type::X) for unconstrained types)
103	pub field_type: TypeConstraint,
104	/// Human-readable description
105	pub description: &'static str,
106}
107
108/// Static metadata about an operator type
109/// This trait provides compile-time constant metadata
110pub trait FFIOperatorMetadata {
111	/// Operator name (must be unique within a library)
112	const NAME: &'static str;
113	/// API version for FFI compatibility (must match host's CURRENT_API)
114	const API: u32;
115	/// Semantic version of the operator (e.g., "1.0.0")
116	const VERSION: &'static str;
117	/// Human-readable description of the operator
118	const DESCRIPTION: &'static str;
119	/// Input columns describing expected input row format
120	const INPUT_COLUMNS: &'static [OperatorColumnDef];
121	/// Output columns describing output row format
122	const OUTPUT_COLUMNS: &'static [OperatorColumnDef];
123	/// Capabilities bitflags describing supported operations
124	/// Use CAPABILITY_* constants from reifydb_flow_operator_abi
125	const CAPABILITIES: u32;
126}
127
128/// Runtime operator behavior
129/// Operators must be Send + Sync for thread safety
130pub trait FFIOperator: Send + Sync + 'static {
131	/// Create a new operator instance with the operator ID and configuration
132	fn new(operator_id: FlowNodeId, config: &HashMap<String, Value>) -> Result<Self>
133	where
134		Self: Sized;
135
136	/// Process a flow change (inserts, updates, removes)
137	fn apply(&mut self, ctx: &mut OperatorContext, input: FlowChange) -> Result<FlowChange>;
138
139	/// Get specific rows by row number
140	fn get_rows(&mut self, ctx: &mut OperatorContext, row_numbers: &[RowNumber]) -> Result<Vec<Option<Row>>>;
141}
142
143pub trait FFIOperatorWithMetadata: FFIOperator + FFIOperatorMetadata {}
144impl<T> FFIOperatorWithMetadata for T where T: FFIOperator + FFIOperatorMetadata {}
145
146// Prelude module for convenient imports
147pub mod prelude {
148	pub use reifydb_core::{
149		CowVec, Row,
150		key::EncodableKey,
151		value::encoded::{EncodedKey, EncodedValues},
152	};
153	pub use reifydb_flow_operator_abi::{
154		CAPABILITY_ALL_STANDARD, CAPABILITY_DELETE, CAPABILITY_DROP, CAPABILITY_GET_ROWS, CAPABILITY_INSERT,
155		CAPABILITY_TICK, CAPABILITY_UPDATE, has_capability,
156	};
157	pub use reifydb_type::{RowNumber, Type, TypeConstraint, Value};
158
159	pub use crate::{
160		Catalog, FFIOperator, FFIOperatorMetadata, FFIOperatorWithMetadata, FlowChange, FlowChangeBuilder,
161		FlowChangeOrigin, FlowDiff, OperatorColumnDef,
162		context::OperatorContext,
163		error::{FFIError, Result},
164		stateful::State,
165		store::Store,
166	};
167}
reifydb_flow_operator_sdk/lib.rs

reifydb_flow_operator_sdk/
lib.rs
