Skip to main content

paganel_plugin_sdk/
lib.rs

1//! Write [Paganel](https://github.com/stanstork/paganel) plugins in Rust.
2//!
3//! Paganel is a data migration engine. A plugin runs inside its WASM sandbox as
4//! a **transform** (compute a column), a **filter** (accept or reject a row), a
5//! **source** (produce rows) or a **sink** (consume them). Pick the matching
6//! attribute macro and write an ordinary function: the macro emits the ABI the
7//! host expects.
8//!
9//! ```no_run
10//! use paganel_plugin_sdk::{paganel_transform, PluginInput, PluginResult};
11//!
12//! #[paganel_transform(
13//!     name = "adder",
14//!     version = "1.0.0",
15//!     output = "f64",
16//!     input = [
17//!         { name = "a", type = "f64", nullable = false },
18//!         { name = "b", type = "f64", nullable = false },
19//!     ]
20//! )]
21//! fn add(inputs: Vec<PluginInput>) -> PluginResult<Vec<f64>> {
22//!     inputs
23//!         .iter()
24//!         .map(|input| Ok(input.get_f64("a")? + input.get_f64("b")?))
25//!         .collect()
26//! }
27//! ```
28//!
29//! Build with `--target wasm32-wasip1 --release` and a `cdylib` crate type.
30//!
31//! Your function receives a whole batch, not one row: the host crosses the WASM
32//! boundary once per batch, which is why a native Rust plugin runs close to the
33//! no-plugin rate. Plugins execute under fuel, memory and timeout caps with no
34//! filesystem or network access unless the pipeline grants it.
35//!
36//! # Where to look
37//!
38//! - [`input`] / [`output`] - the values your function reads and returns
39//! - [`filter`], [`source`], [`sink`] - the other roles
40//! - [`host`] - host functions a pipeline can grant (logging, HTTP, key-value)
41//! - [`error`] - failing a row versus failing the run
42
43pub mod columnar;
44pub mod error;
45pub mod exchange;
46pub mod filter;
47pub mod host;
48pub mod input;
49pub mod output;
50pub mod record;
51pub mod runtime;
52pub mod schema;
53pub mod sink;
54pub mod source;
55pub mod value;
56
57// Re-export the proc macros at crate root.
58pub use paganel_plugin_sdk_macros::{
59    paganel_filter, paganel_sink, paganel_source, paganel_transform,
60};
61
62// Re-export primary types for `use paganel_plugin_sdk::*;`.
63pub use error::{PluginError, PluginErrorCode, PluginResult};
64pub use filter::FilterDecision;
65pub use input::PluginInput;
66pub use output::PluginOutput;
67pub use record::{FieldValue, Record};
68pub use schema::{PluginField, PluginMetadata, PluginType};
69pub use sink::{PluginBatch, SinkConfig, WriteResult};
70pub use source::{SourceConfig, SourcePage};
71pub use value::Value;
72
73// Host wrappers.
74pub use host::env::env_get;
75pub use host::fs::{fs_read, fs_read_to_string, fs_write};
76pub use host::http::{HttpResponse, http_get, http_post};
77pub use host::kv::{kv_get, kv_set};
78pub use host::log::{log_debug, log_error, log_info, log_warn};
79pub use host::metrics::{metric_counter, metric_gauge};
80
81// Runtime helpers - used by macro-generated code.
82pub use runtime::pack::{pack, unpack};
83
84use std::collections::HashMap;
85use std::sync::OnceLock;
86
87/// Static configuration delivered to a plugin at initialize time, parsed from
88/// the PPL `plugin "x" { config { ... } }` block.
89#[derive(Debug, Clone, Default)]
90pub struct PluginConfig {
91    params: HashMap<String, String>,
92}
93
94impl PluginConfig {
95    pub fn new(params: HashMap<String, String>) -> Self {
96        Self { params }
97    }
98
99    /// Look up a config value; `None` if the key was not supplied.
100    pub fn get(&self, key: &str) -> Option<&str> {
101        self.params.get(key).map(String::as_str)
102    }
103
104    /// Look up a config value, erroring if absent.
105    pub fn require(&self, key: &str) -> PluginResult<&str> {
106        self.get(key)
107            .ok_or_else(|| PluginError::invalid_input(format!("missing config key: '{}'", key)))
108    }
109}
110
111static PLUGIN_CONFIG: OnceLock<PluginConfig> = OnceLock::new();
112static SOURCE_CONFIG: OnceLock<SourceConfig> = OnceLock::new();
113static SINK_CONFIG: OnceLock<SinkConfig> = OnceLock::new();
114
115/// Access the plugin's static configuration.
116pub fn config() -> &'static PluginConfig {
117    PLUGIN_CONFIG.get_or_init(PluginConfig::default)
118}
119
120#[doc(hidden)]
121pub fn __set_plugin_config(cfg: PluginConfig) {
122    let _ = PLUGIN_CONFIG.set(cfg);
123}
124
125/// Access the source plugin's static configuration. Returns an error if the
126/// plugin's `__paganel_initialize` hasn't run yet.
127pub fn source_config() -> PluginResult<&'static SourceConfig> {
128    SOURCE_CONFIG
129        .get()
130        .ok_or_else(|| PluginError::internal("source plugin not initialized"))
131}
132
133/// Access the sink plugin's static configuration. Returns an error if the
134/// plugin's `__paganel_initialize` hasn't run yet.
135pub fn sink_config() -> PluginResult<&'static SinkConfig> {
136    SINK_CONFIG
137        .get()
138        .ok_or_else(|| PluginError::internal("sink plugin not initialized"))
139}
140
141#[doc(hidden)]
142pub fn __set_source_config(cfg: SourceConfig) {
143    let _ = SOURCE_CONFIG.set(cfg);
144}
145
146#[doc(hidden)]
147pub fn __set_sink_config(cfg: SinkConfig) {
148    let _ = SINK_CONFIG.set(cfg);
149}