dre_protocol/
lib.rs

1//! The DRE plugin protocol, version 0.
2//!
3//! Plugins ship in packages: one executable, `dre-plugin-<package>`, serving every plugin the
4//! package provides (a single plugin may also be named `dre-<kind>-<name>`). It talks to DRE core
5//! over stdin/stdout in length-prefixed frames. Each frame is a JSON control message or an Arrow IPC stream; stderr
6//! is the plugin's log channel. See `docs/protocol.md` in the repository for the public contract.
7//!
8//! - [`frame`]: the wire format.
9//! - [`msg`]: every control message.
10//! - [`host`]: the core side: spawning a plugin, the handshake, requests.
11//! - [`plugin`]: the SDK plugin authors use to serve requests.
12//! - [`options`]: the options a plugin declares, and how they're checked.
13//! - [`conformance`]: checks any plugin binary against the protocol.
14//! - [`sessions`]: OAuth sessions plugins keep in `~/.dre/oauth_sessions.json`.
15//! - [`markdown`]: the portable Markdown subset of messages, and its translations.
16
17pub mod conformance;
18pub mod frame;
19pub mod host;
20pub mod markdown;
21pub mod msg;
22pub mod options;
23pub mod plugin;
24pub mod sessions;
25pub mod util;
26
27/// This crate's version (its own, not DRE's); the fixture plugins report it.
28pub const CRATE_VERSION: &str = env!("CARGO_PKG_VERSION");
29
30/// Protocol versions this build speaks.
31pub const MIN_VERSION: u32 = 0;
32pub const MAX_VERSION: u32 = 0;
33
34/// Capability: can hold one session (and its temp objects) across requests.
35pub const CAP_SESSIONS: &str = "sessions";
36/// Capability: can open a connection read-only.
37pub const CAP_READ_ONLY: &str = "read_only";
38/// Capability: can verify a statement without executing it.
39pub const CAP_CHECK: &str = "check";
40/// Capability (destinations): takes every file of one output in a single `deliver`.
41pub const CAP_MULTI_FILE: &str = "multi_file";
42/// Capability (destinations): takes a message (`deliver` with `message`), not only files.
43pub const CAP_MESSAGE: &str = "message";
44/// Capability (destinations): takes only messages; core never sends it a file output.
45pub const CAP_MESSAGE_ONLY: &str = "message_only";
46/// Source: loads rows into a temporary table on the session (`load`), for large lookups.
47pub const CAP_LOAD: &str = "load";
48/// Answers `validate` (checks a config block of options). The Rust SDK always advertises it.
49pub const CAP_VALIDATE: &str = "validate";
50
51#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize)]
52#[serde(rename_all = "lowercase")]
53pub enum Kind {
54    Source,
55    Format,
56    Destination,
57}
58
59impl Kind {
60    pub fn as_str(self) -> &'static str {
61        match self {
62            Kind::Source => "source",
63            Kind::Format => "format",
64            Kind::Destination => "destination",
65        }
66    }
67
68    /// Parse a kind, singular or plural (`source`, `sources`).
69    pub fn parse(s: &str) -> Option<Kind> {
70        match s {
71            "source" | "sources" => Some(Kind::Source),
72            "format" | "formats" => Some(Kind::Format),
73            "destination" | "destinations" => Some(Kind::Destination),
74            _ => None,
75        }
76    }
77}
78
79impl std::fmt::Display for Kind {
80    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
81        f.write_str(self.as_str())
82    }
83}
84
85/// One plugin: its kind and name. Written `<kind>/<name>` (`destination/s3`), in messages as
86/// well as in `dre.lock`.
87#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
88pub struct PluginId {
89    pub kind: Kind,
90    pub name: String,
91}
92
93impl PluginId {
94    pub fn new(kind: Kind, name: impl Into<String>) -> PluginId {
95        PluginId {
96            kind,
97            name: name.into(),
98        }
99    }
100}
101
102impl std::fmt::Display for PluginId {
103    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
104        write!(f, "{}/{}", self.kind, self.name)
105    }
106}
107
108impl std::str::FromStr for PluginId {
109    type Err = String;
110
111    fn from_str(s: &str) -> Result<PluginId, String> {
112        let bad = || format!("`{s}` isn't `<kind>/<name>` (e.g. `destination/s3`)");
113        let (k, n) = s.split_once('/').ok_or_else(bad)?;
114        let kind = Kind::parse(k).ok_or_else(bad)?;
115        valid_name(n).then(|| PluginId::new(kind, n)).ok_or_else(bad)
116    }
117}
118
119impl serde::Serialize for PluginId {
120    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
121        s.collect_str(self)
122    }
123}
124
125impl<'de> serde::Deserialize<'de> for PluginId {
126    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
127        String::deserialize(d)?.parse().map_err(serde::de::Error::custom)
128    }
129}
130
131/// Whether `name` is a valid plugin or package name: `[a-z0-9_]+`.
132pub fn valid_name(name: &str) -> bool {
133    !name.is_empty()
134        && name
135            .bytes()
136            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')
137}
138
139/// The executable file name for a package on this platform: `dre-plugin-<package>`.
140pub fn package_executable_name(package: &str) -> String {
141    format!("dre-plugin-{package}{}", std::env::consts::EXE_SUFFIX)
142}
143
144/// Parse `dre-plugin-<package>[.exe]` into the package name.
145pub fn parse_package_executable_name(file: &str) -> Option<String> {
146    let stem = file.strip_suffix(std::env::consts::EXE_SUFFIX).unwrap_or(file);
147    if !std::env::consts::EXE_SUFFIX.is_empty() && stem == file {
148        return None;
149    }
150    let name = stem.strip_prefix("dre-plugin-")?;
151    valid_name(name).then(|| name.to_string())
152}
153
154/// The executable file name for a single plugin on this platform.
155pub fn executable_name(kind: Kind, name: &str) -> String {
156    format!("dre-{}-{name}{}", kind.as_str(), std::env::consts::EXE_SUFFIX)
157}
158
159/// Parse `dre-<kind>-<name>[.exe]` into its kind and name. Names are `[a-z0-9_]+`.
160pub fn parse_executable_name(file: &str) -> Option<(Kind, String)> {
161    let stem = file.strip_suffix(std::env::consts::EXE_SUFFIX).unwrap_or(file);
162    if !std::env::consts::EXE_SUFFIX.is_empty() && stem == file {
163        return None;
164    }
165    let rest = stem.strip_prefix("dre-")?;
166    let (kind, name) = rest.split_once('-')?;
167    let kind = Kind::parse(kind)?;
168    valid_name(name).then(|| (kind, name.to_string()))
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174
175    #[test]
176    fn parses_plugin_executable_names() {
177        let exe = |s: &str| format!("{s}{}", std::env::consts::EXE_SUFFIX);
178        assert_eq!(
179            parse_executable_name(&exe("dre-source-duckdb")),
180            Some((Kind::Source, "duckdb".into()))
181        );
182        assert_eq!(
183            parse_executable_name(&exe("dre-destination-azure_blob")),
184            Some((Kind::Destination, "azure_blob".into()))
185        );
186        assert_eq!(parse_executable_name(&exe("dre-format-csv.d")), None);
187        assert_eq!(parse_executable_name(&exe("dre-widget-x")), None);
188        assert_eq!(parse_executable_name(&exe("dre")), None);
189        assert_eq!(parse_executable_name(&exe("dre-plugin-csv")), None);
190    }
191
192    #[test]
193    fn parses_package_executable_names() {
194        let exe = |s: &str| format!("{s}{}", std::env::consts::EXE_SUFFIX);
195        assert_eq!(
196            parse_package_executable_name(&exe("dre-plugin-object_store")).as_deref(),
197            Some("object_store")
198        );
199        assert_eq!(parse_package_executable_name(&exe("dre-source-duckdb")), None);
200        assert_eq!(parse_package_executable_name(&exe("dre-plugin-")), None);
201    }
202
203    #[test]
204    fn plugin_ids_read_and_write_as_kind_slash_name() {
205        let id: PluginId = "destination/s3".parse().unwrap();
206        assert_eq!(id, PluginId::new(Kind::Destination, "s3"));
207        assert_eq!(id.to_string(), "destination/s3");
208        assert_eq!(serde_json::to_string(&id).unwrap(), "\"destination/s3\"");
209        assert!("s3".parse::<PluginId>().is_err());
210        assert!("widget/s3".parse::<PluginId>().is_err());
211    }
212}
dre_protocol/lib.rs

dre_protocol/
lib.rs
