Skip to main content

weirdnet_plugin/
lib.rs

1//! # weirdnet-plugin
2//!
3//! The SDK for Weirdnet code spaces. A code space is compiled into a shared library that
4//! its host application loads and runs; this crate is the safe side of that: the [`Host`] API (load,
5//! update and create records, create models), [`Frame`]s of loaded records, result
6//! [`View`]s, and the [`plugin!`] macro that exports the C ABI ([`abi`]).
7//!
8//! ```ignore
9//! use weirdnet_plugin::prelude::*;
10//!
11//! pub fn run(host: &Host) -> Result<View> {
12//!     let bars = host.input()?;                       // the code space's load request
13//!     let close = bars.f64("close")?;
14//!     let sma = series::sma(&close, &[20.0]);
15//!     Ok(View::chart("close and SMA 20").x("timestamp", bars.f64("timestamp")?, true)
16//!         .line("close", close).line("sma20", sma))
17//! }
18//! weirdnet_plugin::plugin!(run);
19//! ```
20//!
21//! A host built on `weirdnet-code-spaces` writes this crate next to every code space it
22//! builds, and can write a copy for plugins built elsewhere. Which host methods exist (and
23//! what they read and write) is the host's: [`Host::methods`] lists them.
24pub mod abi;
25pub mod columns;
26pub mod connector;
27pub mod json;
28pub mod series;
29
30pub use json::Json;
31use std::fmt;
32
33/// The SDK version (the ABI version is [`abi::ABI_VERSION`]).
34pub const SDK_VERSION: &str = env!("CARGO_PKG_VERSION");
35
36pub mod prelude {
37    pub use crate::connector::{Context, Piped, Request, Response, RulesetRun};
38    pub use crate::series;
39    pub use crate::{Error, Frame, Host, Json, Load, Result, View};
40}
41
42/// An error for the host to show.
43#[derive(Debug, Clone, PartialEq)]
44pub struct Error(pub String);
45
46impl Error {
47    pub fn new(msg: impl Into<String>) -> Self {
48        Error(msg.into())
49    }
50}
51impl fmt::Display for Error {
52    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
53        f.write_str(&self.0)
54    }
55}
56impl std::error::Error for Error {}
57impl From<String> for Error {
58    fn from(s: String) -> Self {
59        Error(s)
60    }
61}
62impl From<&str> for Error {
63    fn from(s: &str) -> Self {
64        Error(s.to_string())
65    }
66}
67
68pub type Result<T> = std::result::Result<T, Error>;
69
70/// The host for one run.
71pub struct Host {
72    raw: *const abi::WnHost,
73}
74
75impl Host {
76    /// # Safety
77    /// `raw` must be the host table passed to `weirdnet_plugin_run`, valid for the run.
78    pub unsafe fn from_raw(raw: *const abi::WnHost) -> Result<Host> {
79        if raw.is_null() {
80            return Err("no host".into());
81        }
82        let v = (*raw).abi_version;
83        if v != abi::ABI_VERSION {
84            return Err(Error(format!("host ABI {v}, plugin ABI {}", abi::ABI_VERSION)));
85        }
86        Ok(Host { raw })
87    }
88
89    /// Call a host method with a JSON request.
90    pub fn call(&self, method: &str, request: &Json) -> Result<Json> {
91        let req = request.to_string();
92        let mut out = abi::WnBuf::EMPTY;
93        // SAFETY: the host table is valid for the run; strings are borrowed for the call only.
94        let (code, text) = unsafe {
95            let h = &*self.raw;
96            let code = (h.call)(h.ctx, abi::WnStr::new(method), abi::WnStr::new(&req), &mut out);
97            let text =
98                if out.ptr.is_null() { String::new() } else { String::from_utf8_lossy(std::slice::from_raw_parts(out.ptr, out.len)).into_owned() };
99            (h.free)(h.ctx, out);
100            (code, text)
101        };
102        if code != abi::CALL_OK {
103            return Err(Error(text));
104        }
105        if text.is_empty() {
106            return Ok(Json::Null);
107        }
108        Json::parse(&text).map_err(|e| Error(format!("bad reply from {method}: {e}")))
109    }
110
111    /// The host methods this host knows.
112    pub fn methods(&self) -> Result<Vec<String>> {
113        Ok(self.call("methods", &Json::Null)?.as_array().unwrap_or(&[]).iter().filter_map(|m| m.as_str().map(str::to_string)).collect())
114    }
115
116    /// Records as the code space's input says (model, filters, grouping, sorting).
117    pub fn input(&self) -> Result<Frame> {
118        Frame::from_json(&self.call("input", &Json::Null)?)
119    }
120
121    /// The input as the host sent it (a frame's JSON), to hand on to [`Host::call_code`].
122    pub fn input_json(&self) -> Result<Json> {
123        self.call("input", &Json::Null)
124    }
125
126    /// A code space's main calls a member by its alias (declared in an
127    /// `@imports alias` header) over `input` (a frame's JSON; `None`: the member's own default
128    /// input). Returns the member's output frame. Only main may call.
129    pub fn call_code(&self, alias: &str, input: Option<&Json>) -> Result<Frame> {
130        let mut req = Json::obj().with("alias", alias);
131        if let Some(i) = input {
132            req = req.with("input", i.clone());
133        }
134        Frame::from_json(&self.call("call", &req)?)
135    }
136
137    /// A code space's main runs another space (its main), declared as
138    /// `@imports space:NAME`. Returns its output frame. Spaces nest at most 8 deep, no loops.
139    pub fn call_space(&self, name: &str, input: Option<&Json>) -> Result<Frame> {
140        let mut req = Json::obj().with("name", name);
141        if let Some(i) = input {
142            req = req.with("input", i.clone());
143        }
144        Frame::from_json(&self.call("call_space", &req)?)
145    }
146
147    /// The names of the inputs, when several feed this run (a pipeline's fan-in).
148    pub fn inputs(&self) -> Result<Vec<String>> {
149        Ok(self.call("inputs", &Json::Null)?.as_array().unwrap_or(&[]).iter().filter_map(|m| m.as_str().map(str::to_string)).collect())
150    }
151
152    /// One input by name (a pipeline's fan-in: the upstream node's id, or the edge's name).
153    pub fn input_named(&self, name: &str) -> Result<Frame> {
154        Frame::from_json(&self.call("input_named", &Json::obj().with("name", name))?)
155    }
156
157    /// The step's options, as text: `code:to-bars?symbol=BTC/USDT&duration=5m` gives
158    /// `[("symbol", "BTC/USDT"), ("duration", "5m")]`. Empty when none were given (or the
159    /// host is older than options).
160    pub fn options(&self) -> Vec<(String, String)> {
161        let o = self.call("options", &Json::Null).unwrap_or(Json::Null);
162        o.as_object().unwrap_or(&[]).iter().map(|(k, v)| (k.clone(), v.as_str().map(str::to_string).unwrap_or_else(|| v.to_string()))).collect()
163    }
164
165    /// One option by name (see [`Host::options`]).
166    pub fn option(&self, name: &str) -> Option<String> {
167        self.options().into_iter().find(|(k, _)| k == name).map(|(_, v)| v)
168    }
169
170    /// The code space's input request itself (what [`Host::input`] loads).
171    pub fn input_request(&self) -> Result<Json> {
172        self.call("input_request", &Json::Null)
173    }
174
175    /// Every model with its fields: `[{"name": "signals", "version": 2, "fields": [{"name", "type", "ref"}]}]`.
176    pub fn models(&self) -> Result<Json> {
177        self.call("models", &Json::Null)
178    }
179
180    /// Load records.
181    pub fn load(&self, q: &Load) -> Result<Frame> {
182        Frame::from_json(&self.call("load", &q.to_json())?)
183    }
184
185    /// Change one record by id: `values` is an object of FIELD: VALUE.
186    pub fn update(&self, model: &str, id: &str, values: Json) -> Result<()> {
187        self.call("update", &Json::obj().with("model", model).with("id", id).with("values", values)).map(|_| ())
188    }
189
190    /// Change every record matching all conditions (`price > 3`); returns how many.
191    pub fn update_where(&self, model: &str, conditions: &[&str], values: Json) -> Result<usize> {
192        let w: Vec<Json> = conditions.iter().map(|c| Json::from(*c)).collect();
193        let r = self.call("update_where", &Json::obj().with("model", model).with("where", Json::Arr(w)).with("values", values))?;
194        Ok(r.get("count").and_then(Json::as_f64).unwrap_or(0.0) as usize)
195    }
196
197    /// Change many records, each by id with its own values (one history entry).
198    pub fn update_each(&self, model: &str, updates: Vec<(String, Json)>) -> Result<usize> {
199        let u: Vec<Json> = updates.into_iter().map(|(id, v)| Json::obj().with("id", id).with("values", v)).collect();
200        let r = self.call("update_each", &Json::obj().with("model", model).with("updates", Json::Arr(u)))?;
201        Ok(r.get("count").and_then(Json::as_f64).unwrap_or(0.0) as usize)
202    }
203
204    /// Create a record; returns its id.
205    pub fn create(&self, model: &str, values: Json) -> Result<String> {
206        let r = self.call("create", &Json::obj().with("model", model).with("values", values))?;
207        Ok(r.get("id").and_then(Json::as_str).unwrap_or_default().to_string())
208    }
209
210    /// Create many records (one history entry); returns their ids.
211    pub fn create_many(&self, model: &str, records: Vec<Json>) -> Result<Vec<String>> {
212        let r = self.call("create_many", &Json::obj().with("model", model).with("records", Json::Arr(records)))?;
213        Ok(r.get("ids").and_then(Json::as_array).unwrap_or(&[]).iter().filter_map(|i| i.as_str().map(str::to_string)).collect())
214    }
215
216    /// Create a model with the designer's field syntax (`"symbol:text!; score:real; idea:ref:ideas"`),
217    /// applied as v1. Nothing happens if it exists already (returns false).
218    pub fn create_model(&self, name: &str, fields: &str, about: &str) -> Result<bool> {
219        let r = self.call("model_create", &Json::obj().with("name", name).with("fields", fields).with("about", about))?;
220        Ok(r.get("created").and_then(Json::as_bool).unwrap_or(false))
221    }
222
223    /// A line for the run log (shown with the result, never printed by the host).
224    pub fn log(&self, text: impl Into<String>) {
225        let _ = self.call("log", &Json::obj().with("text", text.into()));
226    }
227}
228
229/// A load request: which model, and which records in what order.
230#[derive(Debug, Clone, Default)]
231pub struct Load {
232    pub model: String,
233    pub conditions: Vec<String>,
234    pub sort: Vec<String>,
235    pub group: Vec<String>,
236    pub text: String,
237    pub limit: Option<usize>,
238}
239
240impl Load {
241    pub fn model(m: &str) -> Self {
242        Load { model: m.into(), ..Default::default() }
243    }
244    /// A condition: `price > 3`, `side = buy`, `note ~ halving`.
245    pub fn filter(mut self, c: &str) -> Self {
246        self.conditions.push(c.into());
247        self
248    }
249    /// A sort field; `-price` sorts descending.
250    pub fn sort(mut self, f: &str) -> Self {
251        self.sort.push(f.into());
252        self
253    }
254    /// Group by a field (rows come ordered by group; see [`Frame::groups`]).
255    pub fn group(mut self, f: &str) -> Self {
256        self.group.push(f.into());
257        self
258    }
259    pub fn text(mut self, t: &str) -> Self {
260        self.text = t.into();
261        self
262    }
263    pub fn limit(mut self, n: usize) -> Self {
264        self.limit = Some(n);
265        self
266    }
267    pub fn to_json(&self) -> Json {
268        let s = |v: &[String]| Json::Arr(v.iter().map(|x| Json::from(x.as_str())).collect());
269        Json::obj()
270            .with("model", self.model.as_str())
271            .with("where", s(&self.conditions))
272            .with("sort", s(&self.sort))
273            .with("group", s(&self.group))
274            .with("text", self.text.as_str())
275            .with("limit", self.limit)
276    }
277}
278
279/// One field of a frame.
280#[derive(Debug, Clone, PartialEq)]
281pub struct FieldInfo {
282    pub name: String,
283    /// `text`, `integer`, `real`, `bool`, `timestamp`, `json` or `ref:MODEL`.
284    pub ty: String,
285}
286
287/// Rows `start .. start + len` share the group `key`.
288#[derive(Debug, Clone, PartialEq)]
289pub struct Group {
290    pub key: Vec<(String, Json)>,
291    pub start: usize,
292    pub len: usize,
293}
294
295/// Loaded records, by column.
296#[derive(Debug, Clone, Default, PartialEq)]
297pub struct Frame {
298    pub model: String,
299    pub fields: Vec<FieldInfo>,
300    pub ids: Vec<String>,
301    pub columns: Vec<(String, Vec<Json>)>,
302    pub groups: Vec<Group>,
303}
304
305impl Frame {
306    pub fn from_json(j: &Json) -> Result<Frame> {
307        let model = j.get("model").and_then(Json::as_str).unwrap_or_default().to_string();
308        let fields = j
309            .get("fields")
310            .and_then(Json::as_array)
311            .unwrap_or(&[])
312            .iter()
313            .map(|f| FieldInfo {
314                name: f.get("name").and_then(Json::as_str).unwrap_or_default().into(),
315                ty: f.get("type").and_then(Json::as_str).unwrap_or_default().into(),
316            })
317            .collect();
318        let ids: Vec<String> = j.get("ids").and_then(Json::as_array).unwrap_or(&[]).iter().map(Json::text).collect();
319        let columns: Vec<(String, Vec<Json>)> = j
320            .get("columns")
321            .and_then(Json::as_object)
322            .unwrap_or(&[])
323            .iter()
324            .map(|(k, v)| (k.clone(), v.as_array().unwrap_or(&[]).to_vec()))
325            .collect();
326        if let Some((name, c)) = columns.iter().find(|(_, c)| c.len() != ids.len()) {
327            return Err(Error(format!("column {name} has {} values for {} records", c.len(), ids.len())));
328        }
329        let groups = j
330            .get("groups")
331            .and_then(Json::as_array)
332            .unwrap_or(&[])
333            .iter()
334            .map(|g| Group {
335                key: g.get("key").and_then(Json::as_object).unwrap_or(&[]).to_vec(),
336                start: g.get("start").and_then(Json::as_f64).unwrap_or(0.0) as usize,
337                len: g.get("len").and_then(Json::as_f64).unwrap_or(0.0) as usize,
338            })
339            .collect();
340        Ok(Frame { model, fields, ids, columns, groups })
341    }
342
343    pub fn len(&self) -> usize {
344        self.ids.len()
345    }
346    pub fn is_empty(&self) -> bool {
347        self.ids.is_empty()
348    }
349    pub fn has(&self, name: &str) -> bool {
350        name == "id" || self.columns.iter().any(|(n, _)| n == name)
351    }
352    /// The values of a field (`Null` where a record has none).
353    pub fn column(&self, name: &str) -> Result<&[Json]> {
354        self.columns.iter().find(|(n, _)| n == name).map(|(_, c)| c.as_slice()).ok_or_else(|| {
355            Error(format!(
356                "{} has no field `{name}` (fields: {})",
357                self.model,
358                self.columns.iter().map(|(n, _)| n.as_str()).collect::<Vec<_>>().join(", ")
359            ))
360        })
361    }
362    /// A field as numbers (`NaN` where missing or not a number; timestamps are epoch ms).
363    pub fn f64(&self, name: &str) -> Result<Vec<f64>> {
364        if name == "row" && !self.has("row") {
365            return Ok(series::row(self.len()));
366        }
367        Ok(self.column(name)?.iter().map(|v| v.as_f64().unwrap_or(f64::NAN)).collect())
368    }
369    /// A field as text (empty where missing).
370    pub fn text(&self, name: &str) -> Result<Vec<String>> {
371        if name == "id" {
372            return Ok(self.ids.clone());
373        }
374        Ok(self.column(name)?.iter().map(Json::text).collect())
375    }
376    /// One value.
377    pub fn get(&self, row: usize, name: &str) -> Json {
378        self.column(name).ok().and_then(|c| c.get(row).cloned()).unwrap_or_default()
379    }
380    /// Rows `start .. start + len` as a frame of their own.
381    pub fn slice(&self, start: usize, len: usize) -> Frame {
382        let end = (start + len).min(self.len());
383        let start = start.min(end);
384        Frame {
385            model: self.model.clone(),
386            fields: self.fields.clone(),
387            ids: self.ids[start..end].to_vec(),
388            columns: self.columns.iter().map(|(n, c)| (n.clone(), c[start..end].to_vec())).collect(),
389            groups: vec![],
390        }
391    }
392    /// The given rows (in that order) as a frame of their own.
393    pub fn take(&self, rows: &[usize]) -> Frame {
394        let rows: Vec<usize> = rows.iter().copied().filter(|r| *r < self.len()).collect();
395        Frame {
396            model: self.model.clone(),
397            fields: self.fields.clone(),
398            ids: rows.iter().map(|r| self.ids[*r].clone()).collect(),
399            columns: self.columns.iter().map(|(n, c)| (n.clone(), rows.iter().map(|r| c[*r].clone()).collect())).collect(),
400            groups: vec![],
401        }
402    }
403    /// The groups of a grouped load, or one group with every row.
404    pub fn groups(&self) -> Vec<Group> {
405        if self.groups.is_empty() {
406            vec![Group { key: vec![], start: 0, len: self.len() }]
407        } else {
408            self.groups.clone()
409        }
410    }
411}
412
413/// What a run shows: a table, a chart, text, or tiles of those. A host may show tables as
414/// list tiles and charts as chart tiles, side by side for tiles.
415#[derive(Debug, Clone, PartialEq)]
416pub enum View {
417    Table { title: String, columns: Vec<String>, rows: Vec<Vec<Json>> },
418    Chart { title: String, x_name: String, x: Vec<f64>, x_time: bool, series: Vec<(String, Vec<f64>)> },
419    Text { title: String, text: String },
420    Tiles { title: String, below: bool, tiles: Vec<View> },
421}
422
423impl View {
424    pub fn table(title: &str, columns: &[&str]) -> View {
425        View::Table { title: title.into(), columns: columns.iter().map(|c| c.to_string()).collect(), rows: vec![] }
426    }
427    /// Add a row (tables only).
428    pub fn row(mut self, values: Vec<Json>) -> View {
429        if let View::Table { rows, .. } = &mut self {
430            rows.push(values);
431        }
432        self
433    }
434    pub fn chart(title: &str) -> View {
435        View::Chart { title: title.into(), x_name: "row".into(), x: vec![], x_time: false, series: vec![] }
436    }
437    /// The x axis (`time`: epoch milliseconds).
438    pub fn x(mut self, name: &str, values: Vec<f64>, time: bool) -> View {
439        if let View::Chart { x_name, x, x_time, .. } = &mut self {
440            *x_name = name.into();
441            *x = values;
442            *x_time = time;
443        }
444        self
445    }
446    /// A line on the chart.
447    pub fn line(mut self, name: &str, values: Vec<f64>) -> View {
448        if let View::Chart { series, .. } = &mut self {
449            series.push((name.into(), values));
450        }
451        self
452    }
453    pub fn text(title: &str, text: &str) -> View {
454        View::Text { title: title.into(), text: text.into() }
455    }
456    /// Tiles side by side (`below`: stacked).
457    pub fn tiles(title: &str, below: bool, tiles: Vec<View>) -> View {
458        View::Tiles { title: title.into(), below, tiles }
459    }
460
461    pub fn to_json(&self) -> Json {
462        match self {
463            View::Table { title, columns, rows } => Json::obj()
464                .with("kind", "table")
465                .with("title", title.as_str())
466                .with("columns", Json::Arr(columns.iter().map(|c| Json::from(c.as_str())).collect()))
467                .with("rows", Json::Arr(rows.iter().map(|r| Json::Arr(r.clone())).collect())),
468            View::Chart { title, x_name, x, x_time, series } => Json::obj()
469                .with("kind", "chart")
470                .with("title", title.as_str())
471                .with("x", Json::obj().with("name", x_name.as_str()).with("time", *x_time).with("values", nums(x)))
472                .with("series", Json::Arr(series.iter().map(|(n, v)| Json::obj().with("name", n.as_str()).with("values", nums(v))).collect())),
473            View::Text { title, text } => Json::obj().with("kind", "text").with("title", title.as_str()).with("text", text.as_str()),
474            View::Tiles { title, below, tiles } => Json::obj()
475                .with("kind", "tiles")
476                .with("title", title.as_str())
477                .with("dir", if *below { "below" } else { "right" })
478                .with("tiles", Json::Arr(tiles.iter().map(View::to_json).collect())),
479        }
480    }
481}
482
483fn nums(v: &[f64]) -> Json {
484    Json::Arr(v.iter().map(|x| if x.is_finite() { Json::Num(*x) } else { Json::Null }).collect())
485}
486
487fn panic_text(p: &(dyn std::any::Any + Send)) -> String {
488    p.downcast_ref::<&str>().map(|s| s.to_string()).or_else(|| p.downcast_ref::<String>().cloned()).unwrap_or_else(|| "panic".into())
489}
490
491/// Run `f` for `weirdnet_plugin_run`: hands its view or error to the host; panics are caught.
492///
493/// # Safety
494/// `raw` must be the host table passed to `weirdnet_plugin_run`.
495#[doc(hidden)]
496pub unsafe fn __run(raw: *const abi::WnHost, f: fn(&Host) -> Result<View>) -> i32 {
497    let host = match Host::from_raw(raw) {
498        Ok(h) => h,
499        Err(_) => return abi::RUN_ERROR,
500    };
501    // a panic message goes to the host, not to the terminal
502    std::panic::set_hook(Box::new(|_| {}));
503    let out = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(&host)));
504    let _ = std::panic::take_hook();
505    match out {
506        Ok(Ok(view)) => match host.call("result", &view.to_json()) {
507            Ok(_) => abi::RUN_OK,
508            Err(e) => {
509                let _ = host.call("error", &Json::obj().with("message", format!("the host refused the result: {e}")));
510                abi::RUN_ERROR
511            }
512        },
513        Ok(Err(e)) => {
514            let _ = host.call("error", &Json::obj().with("message", e.0));
515            abi::RUN_ERROR
516        }
517        Err(p) => {
518            let _ = host.call("error", &Json::obj().with("message", format!("panicked: {}", panic_text(&*p))));
519            abi::RUN_PANIC
520        }
521    }
522}
523
524/// Export the plugin ABI for a `fn(&Host) -> Result<View>` (and the language it came from).
525#[macro_export]
526macro_rules! plugin {
527    ($run:path) => {
528        $crate::plugin!($run, "rust");
529    };
530    ($run:path, kind = $kind:literal) => {
531        $crate::plugin!(@export $run, concat!("{\"sdk\":\"0.1.0\",\"lang\":\"rust\",\"kind\":\"", $kind, "\"}"));
532    };
533    ($run:path, $lang:literal, kind = $kind:literal) => {
534        $crate::plugin!(@export $run, concat!("{\"sdk\":\"0.1.0\",\"lang\":\"", $lang, "\",\"kind\":\"", $kind, "\"}"));
535    };
536    ($run:path, $lang:literal) => {
537        $crate::plugin!(@export $run, concat!("{\"sdk\":\"0.1.0\",\"lang\":\"", $lang, "\"}"));
538    };
539    (@export $run:path, $info:expr) => {
540        #[no_mangle]
541        pub extern "C" fn weirdnet_plugin_abi() -> u32 {
542            $crate::abi::ABI_VERSION
543        }
544        #[no_mangle]
545        pub extern "C" fn weirdnet_plugin_info() -> $crate::abi::WnStr {
546            const INFO: &str = $info;
547            $crate::abi::WnStr::new(INFO)
548        }
549        /// # Safety
550        /// Called by the host with a valid host table.
551        #[no_mangle]
552        pub unsafe extern "C" fn weirdnet_plugin_run(host: *const $crate::abi::WnHost) -> i32 {
553            $crate::__run(host, $run)
554        }
555    };
556}