feat(plugin): add plugin framework workflow

This commit is contained in:
t8y2 authored and GitHub committed 2026-09-13 10:39:17 +08:00
1 parent 3767f4a83b
commit b5072f1a3e
247 files changed
+33841 -2256

No files matched your search

+184
View File
@@ -0,0 +1,184 @@
use std::path::{Component, Path, PathBuf};
use sha2::{Digest, Sha256};
use super::{InstalledPlugin, PluginRegistry};
const MAX_PLUGIN_UI_ASSET_BYTES: u64 = 32 * 1024 * 1024;
#[derive(Debug, Clone)]
pub struct PluginUiAsset {
pub content_type: String,
pub bytes: Vec<u8>,
pub etag: String,
}
impl PluginRegistry {
pub fn read_asset(&self, plugin_id: &str, relative_path: &str) -> Result<PluginUiAsset, String> {
let plugin = self.find_plugin(plugin_id)?.ok_or_else(|| format!("Plugin '{plugin_id}' is not installed"))?;
let relative = validate_asset_path(relative_path)?;
let path = plugin.path.join(relative);
read_asset_file(plugin_id, &plugin.path, &path)
}
pub fn read_ui_entry(&self, plugin_id: &str) -> Result<PluginUiAsset, String> {
let plugin = self.compatible_ui_plugin(plugin_id)?;
let entry = plugin
.compatibility
.ui_entry
.as_ref()
.ok_or_else(|| format!("Plugin '{plugin_id}' does not provide a UI entrypoint"))?;
let root = plugin
.compatibility
.ui_root
.as_ref()
.ok_or_else(|| format!("Plugin '{plugin_id}' does not provide a UI root"))?;
read_asset_file(plugin_id, root, entry)
}
pub fn read_ui_asset(&self, plugin_id: &str, relative_path: &str) -> Result<PluginUiAsset, String> {
let plugin = self.compatible_ui_plugin(plugin_id)?;
let root = plugin
.compatibility
.ui_root
.as_ref()
.ok_or_else(|| format!("Plugin '{plugin_id}' does not provide a UI root"))?;
let relative = validate_asset_path(relative_path)?;
let path = root.join(relative);
read_asset_file(plugin_id, root, &path)
}
fn compatible_ui_plugin(&self, plugin_id: &str) -> Result<InstalledPlugin, String> {
let plugin = self.find_plugin(plugin_id)?.ok_or_else(|| format!("Plugin '{plugin_id}' is not installed"))?;
if !plugin.compatibility.compatible {
return Err(format!("Plugin '{plugin_id}' is incompatible: {}", plugin.compatibility.errors.join("; ")));
}
if plugin.manifest.entrypoints.ui.is_none() {
return Err(format!("Plugin '{plugin_id}' does not provide a UI entrypoint"));
}
Ok(plugin)
}
}
fn read_asset_file(plugin_id: &str, root: &Path, path: &Path) -> Result<PluginUiAsset, String> {
let canonical_root = std::fs::canonicalize(root)
.map_err(|error| format!("Failed to resolve plugin asset root {}: {error}", root.display()))?;
let canonical_path = std::fs::canonicalize(path)
.map_err(|error| format!("Plugin UI asset does not exist {}: {error}", path.display()))?;
if !canonical_path.starts_with(&canonical_root) {
return Err(format!("Plugin asset escapes plugin '{plugin_id}': {}", path.display()));
}
let metadata = std::fs::metadata(&canonical_path).map_err(|error| error.to_string())?;
if !metadata.is_file() {
return Err(format!("Plugin UI asset is not a file: {}", canonical_path.display()));
}
if metadata.len() > MAX_PLUGIN_UI_ASSET_BYTES {
return Err(format!("Plugin UI asset exceeds {MAX_PLUGIN_UI_ASSET_BYTES} bytes"));
}
let bytes = std::fs::read(&canonical_path).map_err(|error| error.to_string())?;
let etag = format!("\"{}\"", hex_digest(Sha256::digest(&bytes)));
Ok(PluginUiAsset { content_type: content_type(&canonical_path).to_string(), bytes, etag })
}
fn validate_asset_path(relative_path: &str) -> Result<PathBuf, String> {
let path = Path::new(relative_path);
if path.as_os_str().is_empty() || path.is_absolute() {
return Err("Plugin UI asset path must be a non-empty relative path".to_string());
}
if path.components().any(|component| !matches!(component, Component::Normal(_))) {
return Err(format!("Plugin UI asset path is unsafe: {relative_path}"));
}
Ok(path.to_path_buf())
}
fn content_type(path: &Path) -> &'static str {
match path.extension().and_then(|extension| extension.to_str()).map(str::to_ascii_lowercase).as_deref() {
Some("html" | "htm") => "text/html; charset=utf-8",
Some("js" | "mjs") => "text/javascript; charset=utf-8",
Some("css") => "text/css; charset=utf-8",
Some("json" | "map") => "application/json; charset=utf-8",
Some("svg") => "image/svg+xml",
Some("png") => "image/png",
Some("jpg" | "jpeg") => "image/jpeg",
Some("gif") => "image/gif",
Some("webp") => "image/webp",
Some("ico") => "image/x-icon",
Some("woff") => "font/woff",
Some("woff2") => "font/woff2",
Some("wasm") => "application/wasm",
Some("txt") => "text/plain; charset=utf-8",
_ => "application/octet-stream",
}
}
fn hex_digest(bytes: impl AsRef<[u8]>) -> String {
use std::fmt::Write as _;
bytes.as_ref().iter().fold(String::with_capacity(64), |mut output, byte| {
let _ = write!(output, "{byte:02x}");
output
})
}
#[cfg(test)]
mod tests {
use super::PluginRegistry;
#[test]
fn serves_assets_inside_declared_ui_root() {
let root = tempfile::tempdir().unwrap();
let plugin_dir = root.path().join("sample");
std::fs::create_dir_all(plugin_dir.join("ui")).unwrap();
std::fs::write(plugin_dir.join("ui/index.html"), "<h1>Hello</h1>").unwrap();
std::fs::write(plugin_dir.join("ui/app.js"), "console.log('hello')").unwrap();
std::fs::write(
plugin_dir.join("manifest.json"),
serde_json::json!({
"manifest_version": 1,
"id": "sample",
"name": "Sample",
"version": "1.0.0",
"publisher": "dbx",
"engines": { "dbx": ">=0.1.0", "host_api": "^1.0" },
"entrypoints": { "ui": { "root": "ui", "entry": "ui/index.html" } }
})
.to_string(),
)
.unwrap();
let registry = PluginRegistry::new_with_app_version(root.path().to_path_buf(), "0.5.67");
let entry = registry.read_ui_entry("sample").unwrap();
assert_eq!(entry.content_type, "text/html; charset=utf-8");
assert_eq!(entry.bytes, b"<h1>Hello</h1>");
assert!(registry.read_ui_asset("sample", "app.js").is_ok());
assert!(registry.read_ui_asset("sample", "../manifest.json").is_err());
}
#[test]
fn serves_package_assets_without_a_ui_entrypoint() {
let root = tempfile::tempdir().unwrap();
let plugin_dir = root.path().join("sample");
std::fs::create_dir_all(plugin_dir.join("assets")).unwrap();
std::fs::write(plugin_dir.join("assets/icon.svg"), "<svg/>").unwrap();
std::fs::write(
plugin_dir.join("manifest.json"),
serde_json::json!({
"manifest_version": 1,
"id": "sample",
"name": "Sample",
"version": "1.0.0",
"publisher": "dbx",
"engines": { "dbx": ">=0.1.0", "host_api": "^1.0" },
"icon": "assets/icon.svg"
})
.to_string(),
)
.unwrap();
let registry = PluginRegistry::new_with_app_version(root.path().to_path_buf(), "0.5.67");
let icon = registry.read_asset("sample", "assets/icon.svg").unwrap();
assert_eq!(icon.content_type, "image/svg+xml");
assert_eq!(icon.bytes, b"<svg/>");
assert!(registry.read_asset("sample", "../outside.svg").is_err());
}
}
+536
View File
@@ -0,0 +1,536 @@
use std::time::Duration;
use base64::Engine;
use serde::{Deserialize, Serialize};
use super::{PluginFilesystemCapability, PluginFilesystemProviderContribution, PluginHost, PLUGIN_REQUEST_TIMEOUT};
pub const PLUGIN_FILESYSTEM_LIST_METHOD: &str = "filesystem/list";
pub const PLUGIN_FILESYSTEM_READ_METHOD: &str = "filesystem/read";
pub const PLUGIN_FILESYSTEM_WRITE_METHOD: &str = "filesystem/write";
pub const PLUGIN_FILESYSTEM_CREATE_DIRECTORY_METHOD: &str = "filesystem/createDirectory";
pub const PLUGIN_FILESYSTEM_DELETE_METHOD: &str = "filesystem/delete";
pub const PLUGIN_FILESYSTEM_RENAME_METHOD: &str = "filesystem/rename";
pub const DEFAULT_PLUGIN_FILESYSTEM_PAGE_SIZE: u32 = 200;
pub const MAX_PLUGIN_FILESYSTEM_PAGE_SIZE: u32 = 1_000;
pub const DEFAULT_PLUGIN_FILESYSTEM_PREVIEW_BYTES: u64 = 256 * 1024;
pub const MAX_PLUGIN_FILESYSTEM_PREVIEW_BYTES: u64 = 4 * 1024 * 1024;
pub const MAX_PLUGIN_FILESYSTEM_INLINE_WRITE_BYTES: u64 = 4 * 1024 * 1024;
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginFilesystemListRequest<'a> {
provider_id: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
connection_id: Option<&'a str>,
uri: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
cursor: Option<&'a str>,
limit: u32,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginFilesystemReadRequest<'a> {
provider_id: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
connection_id: Option<&'a str>,
uri: &'a str,
max_bytes: u64,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginFilesystemWriteRequest<'a> {
provider_id: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
connection_id: Option<&'a str>,
uri: &'a str,
data_base64: &'a str,
create: bool,
overwrite: bool,
#[serde(skip_serializing_if = "Option::is_none")]
etag: Option<&'a str>,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginFilesystemCreateDirectoryRequest<'a> {
provider_id: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
connection_id: Option<&'a str>,
uri: &'a str,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginFilesystemDeleteRequest<'a> {
provider_id: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
connection_id: Option<&'a str>,
uri: &'a str,
recursive: bool,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginFilesystemRenameRequest<'a> {
provider_id: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
connection_id: Option<&'a str>,
source_uri: &'a str,
target_uri: &'a str,
overwrite: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum PluginFilesystemEntryKind {
File,
Directory,
Symlink,
Other,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct PluginFilesystemEntry {
pub name: String,
pub uri: String,
pub kind: PluginFilesystemEntryKind,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub size: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub modified_at: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub content_type: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct PluginFilesystemListResult {
#[serde(default)]
pub entries: Vec<PluginFilesystemEntry>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub next_cursor: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct PluginFilesystemReadResult {
pub data_base64: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub content_type: Option<String>,
#[serde(default)]
pub truncated: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub etag: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct PluginFilesystemMutationResult {
#[serde(default = "default_true")]
pub success: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub entry: Option<PluginFilesystemEntry>,
}
fn default_true() -> bool {
true
}
impl PluginHost {
pub async fn list_filesystem_entries(
&self,
plugin_id: &str,
provider_id: &str,
connection_id: Option<&str>,
uri: Option<&str>,
cursor: Option<&str>,
limit: Option<u32>,
) -> Result<PluginFilesystemListResult, String> {
let provider = self.resolve_filesystem_provider(plugin_id, provider_id)?;
let uri = resolve_filesystem_uri(&provider, uri)?;
let limit = limit.unwrap_or(DEFAULT_PLUGIN_FILESYSTEM_PAGE_SIZE).clamp(1, MAX_PLUGIN_FILESYSTEM_PAGE_SIZE);
let request = PluginFilesystemListRequest {
provider_id,
connection_id: normalized_optional_value(connection_id),
uri: &uri,
cursor: normalized_optional_value(cursor),
limit,
};
let result: PluginFilesystemListResult = self
.invoke(
plugin_id,
PLUGIN_FILESYSTEM_LIST_METHOD,
serde_json::to_value(request).map_err(|error| error.to_string())?,
None,
Some(PLUGIN_REQUEST_TIMEOUT),
)
.await?;
validate_list_result(&provider, &result, limit)?;
Ok(result)
}
pub async fn read_filesystem_file(
&self,
plugin_id: &str,
provider_id: &str,
connection_id: Option<&str>,
uri: &str,
max_bytes: Option<u64>,
) -> Result<PluginFilesystemReadResult, String> {
let provider = self.resolve_filesystem_provider(plugin_id, provider_id)?;
ensure_provider_capability(plugin_id, &provider, PluginFilesystemCapability::Read)?;
let uri = resolve_filesystem_uri(&provider, Some(uri))?;
let max_bytes =
max_bytes.unwrap_or(DEFAULT_PLUGIN_FILESYSTEM_PREVIEW_BYTES).clamp(1, MAX_PLUGIN_FILESYSTEM_PREVIEW_BYTES);
let request = PluginFilesystemReadRequest {
provider_id,
connection_id: normalized_optional_value(connection_id),
uri: &uri,
max_bytes,
};
let result: PluginFilesystemReadResult = self
.invoke(
plugin_id,
PLUGIN_FILESYSTEM_READ_METHOD,
serde_json::to_value(request).map_err(|error| error.to_string())?,
None,
Some(Duration::from_secs(30)),
)
.await?;
validate_read_result(&result, max_bytes)?;
Ok(result)
}
pub async fn write_filesystem_file(
&self,
plugin_id: &str,
provider_id: &str,
connection_id: Option<&str>,
uri: &str,
data_base64: &str,
create: bool,
overwrite: bool,
etag: Option<&str>,
) -> Result<PluginFilesystemMutationResult, String> {
let provider = self.resolve_filesystem_provider(plugin_id, provider_id)?;
ensure_provider_capability(plugin_id, &provider, PluginFilesystemCapability::Write)?;
let uri = resolve_filesystem_uri(&provider, Some(uri))?;
validate_inline_write_data(data_base64)?;
let request = PluginFilesystemWriteRequest {
provider_id,
connection_id: normalized_optional_value(connection_id),
uri: &uri,
data_base64,
create,
overwrite,
etag: normalized_optional_value(etag),
};
let result =
self.invoke_filesystem_mutation(plugin_id, &provider, PLUGIN_FILESYSTEM_WRITE_METHOD, request).await?;
Ok(result)
}
pub async fn create_filesystem_directory(
&self,
plugin_id: &str,
provider_id: &str,
connection_id: Option<&str>,
uri: &str,
) -> Result<PluginFilesystemMutationResult, String> {
let provider = self.resolve_filesystem_provider(plugin_id, provider_id)?;
ensure_provider_capability(plugin_id, &provider, PluginFilesystemCapability::Mkdir)?;
let uri = resolve_filesystem_uri(&provider, Some(uri))?;
let request = PluginFilesystemCreateDirectoryRequest {
provider_id,
connection_id: normalized_optional_value(connection_id),
uri: &uri,
};
self.invoke_filesystem_mutation(plugin_id, &provider, PLUGIN_FILESYSTEM_CREATE_DIRECTORY_METHOD, request).await
}
pub async fn delete_filesystem_entry(
&self,
plugin_id: &str,
provider_id: &str,
connection_id: Option<&str>,
uri: &str,
recursive: bool,
) -> Result<PluginFilesystemMutationResult, String> {
let provider = self.resolve_filesystem_provider(plugin_id, provider_id)?;
ensure_provider_capability(plugin_id, &provider, PluginFilesystemCapability::Delete)?;
let uri = resolve_filesystem_uri(&provider, Some(uri))?;
let request = PluginFilesystemDeleteRequest {
provider_id,
connection_id: normalized_optional_value(connection_id),
uri: &uri,
recursive,
};
self.invoke_filesystem_mutation(plugin_id, &provider, PLUGIN_FILESYSTEM_DELETE_METHOD, request).await
}
pub async fn rename_filesystem_entry(
&self,
plugin_id: &str,
provider_id: &str,
connection_id: Option<&str>,
source_uri: &str,
target_uri: &str,
overwrite: bool,
) -> Result<PluginFilesystemMutationResult, String> {
let provider = self.resolve_filesystem_provider(plugin_id, provider_id)?;
ensure_provider_capability(plugin_id, &provider, PluginFilesystemCapability::Rename)?;
let source_uri = resolve_filesystem_uri(&provider, Some(source_uri))?;
let target_uri = resolve_filesystem_uri(&provider, Some(target_uri))?;
let request = PluginFilesystemRenameRequest {
provider_id,
connection_id: normalized_optional_value(connection_id),
source_uri: &source_uri,
target_uri: &target_uri,
overwrite,
};
self.invoke_filesystem_mutation(plugin_id, &provider, PLUGIN_FILESYSTEM_RENAME_METHOD, request).await
}
async fn invoke_filesystem_mutation<T: Serialize>(
&self,
plugin_id: &str,
provider: &PluginFilesystemProviderContribution,
method: &str,
request: T,
) -> Result<PluginFilesystemMutationResult, String> {
let result: PluginFilesystemMutationResult = self
.invoke(
plugin_id,
method,
serde_json::to_value(request).map_err(|error| error.to_string())?,
None,
Some(Duration::from_secs(30)),
)
.await?;
validate_mutation_result(provider, &result)?;
Ok(result)
}
fn resolve_filesystem_provider(
&self,
plugin_id: &str,
provider_id: &str,
) -> Result<PluginFilesystemProviderContribution, String> {
let plugin =
self.registry().find_plugin(plugin_id)?.ok_or_else(|| format!("Plugin '{plugin_id}' is not installed"))?;
if !plugin.compatibility.compatible {
return Err(format!("Plugin '{plugin_id}' is incompatible: {}", plugin.compatibility.errors.join("; ")));
}
plugin
.manifest
.filesystem_provider(provider_id)?
.ok_or_else(|| format!("Filesystem provider '{plugin_id}/{provider_id}' is not declared"))
}
}
fn normalized_optional_value(value: Option<&str>) -> Option<&str> {
value.map(str::trim).filter(|value| !value.is_empty())
}
fn resolve_filesystem_uri(
provider: &PluginFilesystemProviderContribution,
requested_uri: Option<&str>,
) -> Result<String, String> {
let uri = requested_uri
.map(str::trim)
.filter(|uri| !uri.is_empty())
.map(ToOwned::to_owned)
.or_else(|| provider.root_uri.clone())
.unwrap_or_else(|| format!("{}:/", provider.schemes[0]));
if uri.len() > 4_096 || uri.chars().any(char::is_control) {
return Err("Plugin filesystem URI is invalid".to_string());
}
let scheme = uri.split_once(':').map(|(scheme, _)| scheme).unwrap_or_default();
if !provider.schemes.iter().any(|candidate| candidate == scheme) {
return Err(format!("Filesystem URI scheme '{scheme}' is not handled by provider '{}'", provider.id));
}
Ok(uri)
}
fn validate_list_result(
provider: &PluginFilesystemProviderContribution,
result: &PluginFilesystemListResult,
requested_limit: u32,
) -> Result<(), String> {
let maximum_entries = usize::try_from(requested_limit).unwrap_or(usize::MAX);
if result.entries.len() > maximum_entries {
return Err(format!(
"Filesystem provider '{}' returned {} entries for a limit of {requested_limit}",
provider.id,
result.entries.len()
));
}
if result.next_cursor.as_ref().is_some_and(|cursor| cursor.is_empty() || cursor.len() > 4_096) {
return Err(format!("Filesystem provider '{}' returned an invalid cursor", provider.id));
}
for entry in &result.entries {
validate_entry(provider, entry)?;
}
Ok(())
}
fn validate_entry(
provider: &PluginFilesystemProviderContribution,
entry: &PluginFilesystemEntry,
) -> Result<(), String> {
if entry.name.trim().is_empty() || entry.name.len() > 1_024 || entry.name.chars().any(char::is_control) {
return Err(format!("Filesystem provider '{}' returned an invalid entry name", provider.id));
}
resolve_filesystem_uri(provider, Some(&entry.uri))?;
if entry.modified_at.as_ref().is_some_and(|value| value.len() > 128) {
return Err(format!("Filesystem provider '{}' returned an invalid modified timestamp", provider.id));
}
if entry.content_type.as_ref().is_some_and(|value| value.len() > 256 || value.chars().any(char::is_control)) {
return Err(format!("Filesystem provider '{}' returned an invalid content type", provider.id));
}
Ok(())
}
fn validate_read_result(result: &PluginFilesystemReadResult, max_bytes: u64) -> Result<(), String> {
if result.content_type.as_ref().is_some_and(|value| value.len() > 256 || value.chars().any(char::is_control)) {
return Err("Filesystem provider returned an invalid content type".to_string());
}
if result.etag.as_ref().is_some_and(|value| value.len() > 512 || value.chars().any(char::is_control)) {
return Err("Filesystem provider returned an invalid etag".to_string());
}
let estimated_bytes = result.data_base64.len().saturating_mul(3) / 4;
if estimated_bytes as u64 > max_bytes.saturating_add(2) {
return Err(format!("Filesystem provider returned more than the requested {max_bytes} bytes"));
}
let decoded = base64::engine::general_purpose::STANDARD
.decode(&result.data_base64)
.map_err(|error| format!("Filesystem provider returned invalid base64 data: {error}"))?;
if decoded.len() as u64 > max_bytes {
return Err(format!("Filesystem provider returned more than the requested {max_bytes} bytes"));
}
Ok(())
}
fn validate_inline_write_data(data_base64: &str) -> Result<(), String> {
let estimated_bytes = data_base64.len().saturating_mul(3) / 4;
if estimated_bytes as u64 > MAX_PLUGIN_FILESYSTEM_INLINE_WRITE_BYTES.saturating_add(2) {
return Err(format!(
"Inline plugin filesystem writes are limited to {MAX_PLUGIN_FILESYSTEM_INLINE_WRITE_BYTES} bytes"
));
}
let decoded = base64::engine::general_purpose::STANDARD
.decode(data_base64)
.map_err(|error| format!("Plugin filesystem write contains invalid base64 data: {error}"))?;
if decoded.len() as u64 > MAX_PLUGIN_FILESYSTEM_INLINE_WRITE_BYTES {
return Err(format!(
"Inline plugin filesystem writes are limited to {MAX_PLUGIN_FILESYSTEM_INLINE_WRITE_BYTES} bytes"
));
}
Ok(())
}
fn validate_mutation_result(
provider: &PluginFilesystemProviderContribution,
result: &PluginFilesystemMutationResult,
) -> Result<(), String> {
if !result.success {
return Err(result.message.clone().unwrap_or_else(|| "Plugin filesystem operation failed".to_string()));
}
if result.message.as_ref().is_some_and(|message| message.len() > 4_096 || message.chars().any(char::is_control)) {
return Err(format!("Filesystem provider '{}' returned an invalid operation message", provider.id));
}
if let Some(entry) = &result.entry {
validate_entry(provider, entry)?;
}
Ok(())
}
fn ensure_provider_capability(
plugin_id: &str,
provider: &PluginFilesystemProviderContribution,
capability: PluginFilesystemCapability,
) -> Result<(), String> {
if provider.has_capability(capability) {
Ok(())
} else {
Err(format!(
"Filesystem provider '{plugin_id}/{}' does not declare {} capability",
provider.id,
capability.as_str()
))
}
}
#[cfg(test)]
mod tests {
use super::{resolve_filesystem_uri, validate_inline_write_data, validate_list_result, validate_read_result};
use crate::plugins::{
PluginFilesystemCapability, PluginFilesystemEntry, PluginFilesystemEntryKind, PluginFilesystemListResult,
PluginFilesystemProviderContribution, PluginFilesystemReadResult,
};
fn provider() -> PluginFilesystemProviderContribution {
PluginFilesystemProviderContribution {
id: "sample.files".to_string(),
label: "Sample files".to_string(),
schemes: vec!["sample".to_string()],
description: None,
capabilities: vec![PluginFilesystemCapability::Read],
root_uri: Some("sample:/home".to_string()),
}
}
#[test]
fn resolves_declared_root_and_rejects_other_schemes() {
assert_eq!(resolve_filesystem_uri(&provider(), None).unwrap(), "sample:/home");
assert!(resolve_filesystem_uri(&provider(), Some("other:/tmp")).unwrap_err().contains("not handled"));
}
#[test]
fn validates_list_limits_and_entry_uris() {
let valid = PluginFilesystemListResult {
entries: vec![PluginFilesystemEntry {
name: "README.txt".to_string(),
uri: "sample:/README.txt".to_string(),
kind: PluginFilesystemEntryKind::File,
size: Some(5),
modified_at: None,
content_type: Some("text/plain".to_string()),
}],
next_cursor: None,
};
validate_list_result(&provider(), &valid, 1).unwrap();
assert!(validate_list_result(&provider(), &valid, 0).unwrap_err().contains("limit of 0"));
}
#[test]
fn rejects_invalid_or_oversized_file_preview() {
let invalid = PluginFilesystemReadResult {
data_base64: "not base64".to_string(),
content_type: None,
truncated: false,
etag: None,
};
assert!(validate_read_result(&invalid, 16).unwrap_err().contains("invalid base64"));
let oversized = PluginFilesystemReadResult {
data_base64: "YWJjZA==".to_string(),
content_type: None,
truncated: false,
etag: None,
};
assert!(validate_read_result(&oversized, 3).unwrap_err().contains("more than"));
}
#[test]
fn validates_inline_write_base64() {
validate_inline_write_data("YWJjZA==").unwrap();
assert!(validate_inline_write_data("not base64").unwrap_err().contains("invalid base64"));
}
}
+702
View File
@@ -0,0 +1,702 @@
use std::collections::{BTreeMap, HashMap, HashSet};
use std::sync::Arc;
use std::time::Duration;
use crate::models::connection::{ConnectionConfig, ConnectionTestResult, DatabaseType};
use serde::de::DeserializeOwned;
use serde::Serialize;
use tokio::sync::{broadcast, Mutex, RwLock};
use super::{
InstalledPlugin, PluginBinaryMessage, PluginConnectionActionContribution, PluginConnectionCapability,
PluginConnectionProviderContribution, PluginEvent, PluginFormFieldBinding, PluginFormFieldDefinition,
PluginFormFieldType, PluginRegistry, PluginRuntimeEnv, PluginSessionState, PluginSidecarSession,
PLUGIN_CONNECTION_ACTION_METHOD, PLUGIN_CONNECTION_CONNECT_METHOD, PLUGIN_CONNECTION_DISCONNECT_METHOD,
PLUGIN_CONNECTION_TEST_METHOD,
};
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ActivePluginSession {
pub plugin_id: String,
pub process_id: Option<u32>,
pub state: PluginSessionState,
}
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct PluginConnectionActionResult {
#[serde(skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub field_values: BTreeMap<String, serde_json::Value>,
}
#[derive(Clone)]
pub struct PluginHost {
inner: Arc<PluginHostInner>,
}
#[derive(Clone)]
pub struct PluginConnectionHandle {
pub plugin_id: String,
pub provider_id: String,
pub connection_id: String,
session: Option<Arc<PluginSidecarSession>>,
disconnect: bool,
params: serde_json::Value,
}
impl PluginConnectionHandle {
pub fn is_running(&self) -> bool {
self.session.as_ref().is_none_or(|session| session.status().state == PluginSessionState::Running)
}
pub async fn disconnect(&self) -> Result<(), String> {
let Some(session) = &self.session else {
return Ok(());
};
if !self.disconnect || session.status().state != PluginSessionState::Running {
return Ok(());
}
let result: serde_json::Value = session
.invoke_with_timeout(
PLUGIN_CONNECTION_DISCONNECT_METHOD,
self.params.clone(),
None,
Some(super::PLUGIN_REQUEST_TIMEOUT),
)
.await?;
ensure_plugin_operation_succeeded(result)
}
}
struct PluginHostInner {
registry: PluginRegistry,
sessions: RwLock<HashMap<String, Arc<PluginSidecarSession>>>,
activation_lock: Mutex<()>,
events: broadcast::Sender<PluginEvent>,
binary_messages: broadcast::Sender<PluginBinaryMessage>,
}
impl PluginHost {
pub fn new(registry: PluginRegistry) -> Self {
let (events, _) = broadcast::channel(512);
let (binary_messages, _) = broadcast::channel(128);
Self {
inner: Arc::new(PluginHostInner {
registry,
sessions: RwLock::new(HashMap::new()),
activation_lock: Mutex::new(()),
events,
binary_messages,
}),
}
}
pub fn subscribe_events(&self) -> broadcast::Receiver<PluginEvent> {
self.inner.events.subscribe()
}
pub fn subscribe_binary(&self) -> broadcast::Receiver<PluginBinaryMessage> {
self.inner.binary_messages.subscribe()
}
pub(super) fn registry(&self) -> &PluginRegistry {
&self.inner.registry
}
pub async fn activate(&self, plugin_id: &str) -> Result<Arc<PluginSidecarSession>, String> {
self.activate_with_env(plugin_id, PluginRuntimeEnv::default()).await
}
pub async fn activate_with_env(
&self,
plugin_id: &str,
env: PluginRuntimeEnv,
) -> Result<Arc<PluginSidecarSession>, String> {
if let Some(session) = self.running_session(plugin_id).await {
return Ok(session);
}
let _activation = self.inner.activation_lock.lock().await;
if let Some(session) = self.running_session(plugin_id).await {
return Ok(session);
}
self.inner.sessions.write().await.remove(plugin_id);
let plugin = self
.inner
.registry
.find_plugin(plugin_id)?
.ok_or_else(|| format!("Plugin '{plugin_id}' is not installed"))?;
if !plugin.compatibility.compatible {
return Err(format!("Plugin '{plugin_id}' is incompatible: {}", plugin.compatibility.errors.join("; ")));
}
let session = PluginSidecarSession::start(plugin, self.inner.registry.app_version().to_string(), env).await?;
self.forward_session_events(&session);
self.inner.sessions.write().await.insert(plugin_id.to_string(), session.clone());
Ok(session)
}
pub async fn invoke<T>(
&self,
plugin_id: &str,
method: &str,
params: serde_json::Value,
required_permission: Option<&str>,
timeout: Option<Duration>,
) -> Result<T, String>
where
T: DeserializeOwned,
{
let session = self.activate(plugin_id).await?;
ensure_permission(session.plugin(), required_permission)?;
session.invoke_with_timeout(method, params, None, timeout).await
}
pub async fn notify(
&self,
plugin_id: &str,
method: &str,
params: serde_json::Value,
required_permission: Option<&str>,
) -> Result<(), String> {
let session = self.activate(plugin_id).await?;
ensure_permission(session.plugin(), required_permission)?;
session.notify(method, params, None).await
}
pub async fn send_binary(
&self,
plugin_id: &str,
channel: &str,
data: &[u8],
required_permission: Option<&str>,
) -> Result<(), String> {
let session = self.activate(plugin_id).await?;
ensure_permission(session.plugin(), required_permission)?;
session.send_binary(channel, data).await
}
pub async fn test_connection(
&self,
config: &ConnectionConfig,
runtime_host: &str,
runtime_port: u16,
) -> Result<ConnectionTestResult, String> {
let (plugin, provider) = self.resolve_connection_provider(config)?;
validate_plugin_connection_values(config, &provider)?;
let provider_label = provider.label.as_deref().unwrap_or(&plugin.manifest.name);
if !provider.has_capability(PluginConnectionCapability::Test) {
return Ok(ConnectionTestResult::success(format!("{provider_label} is available")));
}
let session = self.activate(config.plugin_id.as_deref().unwrap_or_default()).await?;
let result: serde_json::Value = session
.invoke_with_timeout(
PLUGIN_CONNECTION_TEST_METHOD,
plugin_connection_params(config, &provider, runtime_host, runtime_port)?,
None,
Some(Duration::from_secs(config.effective_connect_timeout_secs())),
)
.await?;
plugin_connection_test_result(result, provider_label)
}
pub async fn connect_connection(
&self,
config: &ConnectionConfig,
runtime_host: &str,
runtime_port: u16,
) -> Result<PluginConnectionHandle, String> {
let (_, provider) = self.resolve_connection_provider(config)?;
validate_plugin_connection_values(config, &provider)?;
let params = plugin_connection_params(config, &provider, runtime_host, runtime_port)?;
let needs_session = provider.has_capability(PluginConnectionCapability::Connect)
|| provider.has_capability(PluginConnectionCapability::Disconnect);
let session = if needs_session {
Some(self.activate(config.plugin_id.as_deref().unwrap_or_default()).await?)
} else {
None
};
if provider.has_capability(PluginConnectionCapability::Connect) {
if let Some(session) = &session {
let result: serde_json::Value = session
.invoke_with_timeout(
PLUGIN_CONNECTION_CONNECT_METHOD,
params.clone(),
None,
Some(Duration::from_secs(config.effective_connect_timeout_secs())),
)
.await?;
ensure_plugin_operation_succeeded(result)?;
}
}
let disconnect = provider.has_capability(PluginConnectionCapability::Disconnect);
Ok(PluginConnectionHandle {
plugin_id: config.plugin_id.clone().unwrap_or_default(),
provider_id: provider.id,
connection_id: config.id.clone(),
session,
disconnect,
params,
})
}
pub async fn invoke_connection_action(
&self,
config: &ConnectionConfig,
action_id: &str,
runtime_host: &str,
runtime_port: u16,
) -> Result<PluginConnectionActionResult, String> {
let (_, provider) = self.resolve_connection_provider(config)?;
let action = plugin_invoke_connection_action(&provider, action_id)?;
validate_plugin_connection_values_for_action(config, &provider, action.requires_valid_form)?;
let session = self.activate(config.plugin_id.as_deref().unwrap_or_default()).await?;
let mut params = plugin_connection_params(config, &provider, runtime_host, runtime_port)?;
params
.as_object_mut()
.ok_or("Plugin connection action params must be an object")?
.insert("action".to_string(), serde_json::json!({ "id": action.id }));
let result: serde_json::Value = session
.invoke_with_timeout(
PLUGIN_CONNECTION_ACTION_METHOD,
params,
None,
action.timeout_ms.map(Duration::from_millis).or(Some(super::PLUGIN_REQUEST_TIMEOUT)),
)
.await?;
plugin_connection_action_result(result, &provider)
}
pub async fn list_active(&self) -> Vec<ActivePluginSession> {
let sessions = self.inner.sessions.read().await.values().cloned().collect::<Vec<_>>();
let mut active = Vec::with_capacity(sessions.len());
for session in sessions {
active.push(ActivePluginSession {
plugin_id: session.plugin().manifest.id.clone(),
process_id: session.pid().await,
state: session.status().state,
});
}
active.sort_by(|left, right| left.plugin_id.cmp(&right.plugin_id));
active
}
pub async fn stop(&self, plugin_id: &str) {
if let Some(session) = self.inner.sessions.write().await.remove(plugin_id) {
session.shutdown().await;
}
}
pub async fn stop_all(&self) {
let sessions = std::mem::take(&mut *self.inner.sessions.write().await);
for (_, session) in sessions {
session.shutdown().await;
}
}
async fn running_session(&self, plugin_id: &str) -> Option<Arc<PluginSidecarSession>> {
let session = self.inner.sessions.read().await.get(plugin_id).cloned()?;
(session.status().state == PluginSessionState::Running).then_some(session)
}
fn resolve_connection_provider(
&self,
config: &ConnectionConfig,
) -> Result<(InstalledPlugin, PluginConnectionProviderContribution), String> {
if config.db_type != DatabaseType::Plugin {
return Err("Connection is not a plugin-owned connection".to_string());
}
let plugin_id = required_plugin_binding(&config.plugin_id, "plugin_id")?;
let provider_id = required_plugin_binding(&config.plugin_connection_provider, "plugin_connection_provider")?;
let connection_type = required_plugin_binding(&config.plugin_connection_type, "plugin_connection_type")?;
let plugin = self
.inner
.registry
.find_plugin(plugin_id)?
.ok_or_else(|| format!("Plugin '{plugin_id}' is not installed"))?;
if !plugin.compatibility.compatible {
return Err(format!("Plugin '{plugin_id}' is incompatible: {}", plugin.compatibility.errors.join("; ")));
}
let provider = plugin
.manifest
.connection_provider(provider_id)?
.ok_or_else(|| format!("Plugin '{plugin_id}' does not provide connection provider '{provider_id}'"))?;
if provider.database_type != connection_type {
return Err(format!(
"Connection type '{}' does not match provider '{}' type '{}'",
connection_type, provider.id, provider.database_type
));
}
Ok((plugin, provider))
}
fn forward_session_events(&self, session: &Arc<PluginSidecarSession>) {
let mut events = session.subscribe_events();
let host_events = self.inner.events.clone();
tokio::spawn(async move {
loop {
match events.recv().await {
Ok(event) => {
let _ = host_events.send(event);
}
Err(broadcast::error::RecvError::Lagged(skipped)) => {
log::warn!("Plugin host event relay skipped {skipped} events");
}
Err(broadcast::error::RecvError::Closed) => break,
}
}
});
let mut binary = session.subscribe_binary();
let host_binary = self.inner.binary_messages.clone();
tokio::spawn(async move {
loop {
match binary.recv().await {
Ok(message) => {
let _ = host_binary.send(message);
}
Err(broadcast::error::RecvError::Lagged(skipped)) => {
log::warn!("Plugin host binary relay skipped {skipped} messages");
}
Err(broadcast::error::RecvError::Closed) => break,
}
}
});
}
}
fn required_plugin_binding<'a>(value: &'a Option<String>, field: &str) -> Result<&'a str, String> {
value
.as_deref()
.filter(|value| !value.trim().is_empty())
.ok_or_else(|| format!("Plugin connection is missing {field}"))
}
fn plugin_connection_params(
config: &ConnectionConfig,
provider: &PluginConnectionProviderContribution,
runtime_host: &str,
runtime_port: u16,
) -> Result<serde_json::Value, String> {
Ok(serde_json::json!({
"provider": {
"id": provider.id,
"databaseType": provider.database_type,
},
"connection": serde_json::to_value(config).map_err(|error| error.to_string())?,
"runtime": {
"host": runtime_host,
"port": runtime_port,
}
}))
}
fn validate_plugin_connection_values(
config: &ConnectionConfig,
provider: &PluginConnectionProviderContribution,
) -> Result<(), String> {
validate_plugin_connection_values_for_action(config, provider, true)
}
fn plugin_invoke_connection_action<'a>(
provider: &'a PluginConnectionProviderContribution,
action_id: &str,
) -> Result<&'a PluginConnectionActionContribution, String> {
provider
.actions
.iter()
.find(|action| action.id == action_id)
.ok_or_else(|| format!("Connection provider '{}' does not declare action '{action_id}'", provider.id))
}
fn validate_plugin_connection_values_for_action(
config: &ConnectionConfig,
provider: &PluginConnectionProviderContribution,
require_required_fields: bool,
) -> Result<(), String> {
let allowed_secrets = provider
.fields
.iter()
.filter(|field| field.effective_binding() == PluginFormFieldBinding::Secret)
.map(|field| field.key.as_str())
.collect::<HashSet<_>>();
for key in config.connection_secrets.keys() {
if !allowed_secrets.contains(key.as_str()) {
return Err(format!("Connection secret '{key}' is not declared by provider '{}'", provider.id));
}
}
for field in &provider.fields {
let value = plugin_connection_field_value(config, field);
if require_required_fields && field.required && plugin_field_value_is_empty(value.as_ref()) {
return Err(format!("Plugin connection field '{}' is required", field.label));
}
if let Some(value) = value {
validate_plugin_field_type(field, &value)?;
if field.effective_binding() == PluginFormFieldBinding::Port
&& value.as_u64().is_none_or(|port| port == 0 || port > u16::MAX as u64)
{
return Err(format!("Plugin connection field '{}' must be a port between 1 and 65535", field.label));
}
}
}
Ok(())
}
fn plugin_connection_action_result(
result: serde_json::Value,
provider: &PluginConnectionProviderContribution,
) -> Result<PluginConnectionActionResult, String> {
if let Some(message) = result.as_str() {
return Ok(PluginConnectionActionResult { message: Some(message.to_string()), field_values: BTreeMap::new() });
}
if result.is_null() {
return Ok(PluginConnectionActionResult::default());
}
let object = result
.as_object()
.ok_or_else(|| "Plugin connection action must return null, a message string, or an object".to_string())?;
if object.get("success").and_then(serde_json::Value::as_bool) == Some(false) {
return Err(object
.get("message")
.and_then(serde_json::Value::as_str)
.unwrap_or("Plugin connection action failed")
.to_string());
}
let message = match object.get("message") {
None | Some(serde_json::Value::Null) => None,
Some(serde_json::Value::String(message)) => Some(message.clone()),
Some(_) => return Err("Plugin connection action message must be a string".to_string()),
};
let mut field_values = BTreeMap::new();
if let Some(values) = object.get("fieldValues") {
let values =
values.as_object().ok_or_else(|| "Plugin connection action fieldValues must be an object".to_string())?;
for (key, value) in values {
let field = provider
.fields
.iter()
.find(|field| field.key == *key)
.ok_or_else(|| format!("Plugin connection action returned undeclared field '{key}'"))?;
if !value.is_null() {
validate_plugin_field_type(field, value)?;
if field.effective_binding() == PluginFormFieldBinding::Port
&& value.as_u64().is_none_or(|port| port == 0 || port > u16::MAX as u64)
{
return Err(format!(
"Plugin connection field '{}' must be a port between 1 and 65535",
field.label
));
}
}
field_values.insert(key.clone(), value.clone());
}
}
Ok(PluginConnectionActionResult { message, field_values })
}
fn plugin_connection_field_value(
config: &ConnectionConfig,
field: &PluginFormFieldDefinition,
) -> Option<serde_json::Value> {
match field.effective_binding() {
PluginFormFieldBinding::Name => Some(serde_json::Value::String(config.name.clone())),
PluginFormFieldBinding::Host => Some(serde_json::Value::String(config.host.clone())),
PluginFormFieldBinding::Port => Some(serde_json::Value::Number(config.port.into())),
PluginFormFieldBinding::Username => Some(serde_json::Value::String(config.username.clone())),
PluginFormFieldBinding::Password => Some(serde_json::Value::String(config.password.clone())),
PluginFormFieldBinding::Database => config.database.clone().map(serde_json::Value::String),
PluginFormFieldBinding::Secret => {
config.connection_secrets.get(&field.key).cloned().map(serde_json::Value::String)
}
PluginFormFieldBinding::Config => config.external_config.as_ref()?.get(&field.key).cloned(),
}
}
fn plugin_field_value_is_empty(value: Option<&serde_json::Value>) -> bool {
match value {
None | Some(serde_json::Value::Null) => true,
Some(serde_json::Value::String(value)) => value.trim().is_empty(),
_ => false,
}
}
fn validate_plugin_field_type(field: &PluginFormFieldDefinition, value: &serde_json::Value) -> Result<(), String> {
let valid = match field.field_type {
PluginFormFieldType::Text
| PluginFormFieldType::Password
| PluginFormFieldType::Select
| PluginFormFieldType::Radio
| PluginFormFieldType::Textarea => value.is_string(),
PluginFormFieldType::Number => value.is_number(),
PluginFormFieldType::Boolean => value.is_boolean(),
};
if valid {
Ok(())
} else {
Err(format!("Plugin connection field '{}' has an invalid value type", field.label))
}
}
fn plugin_connection_test_result(
result: serde_json::Value,
provider_label: &str,
) -> Result<ConnectionTestResult, String> {
if let Some(success) = result.get("success").and_then(serde_json::Value::as_bool) {
let message = result.get("message").and_then(serde_json::Value::as_str).unwrap_or(if success {
"Connection successful"
} else {
"Connection failed"
});
if !success {
return Err(message.to_string());
}
return Ok(ConnectionTestResult::success(message));
}
if let Some(message) = result.as_str() {
return Ok(ConnectionTestResult::success(message));
}
if result.is_null() {
return Ok(ConnectionTestResult::success(format!("{provider_label} connection successful")));
}
serde_json::from_value(result)
.map_err(|error| format!("Plugin connection test returned an invalid result: {error}"))
}
fn ensure_plugin_operation_succeeded(result: serde_json::Value) -> Result<(), String> {
if result.get("success").and_then(serde_json::Value::as_bool) == Some(false) {
return Err(result
.get("message")
.and_then(serde_json::Value::as_str)
.unwrap_or("Plugin connection operation failed")
.to_string());
}
Ok(())
}
fn ensure_permission(plugin: &super::InstalledPlugin, required_permission: Option<&str>) -> Result<(), String> {
let Some(permission) = required_permission else {
return Ok(());
};
if plugin.manifest.permissions.iter().any(|declared| declared == permission) {
return Ok(());
}
Err(format!("Plugin '{}' has not declared permission '{permission}'", plugin.manifest.id))
}
#[cfg(test)]
mod tests {
use super::{
plugin_connection_action_result, plugin_invoke_connection_action, validate_plugin_connection_values,
validate_plugin_connection_values_for_action,
};
use crate::models::connection::ConnectionConfig;
use crate::plugins::PluginConnectionProviderContribution;
#[test]
fn rejects_zero_port_for_port_bound_connection_field() {
let config: ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "plugin-connection",
"name": "Plugin connection",
"db_type": "plugin",
"host": "localhost",
"port": 0,
"username": "",
"password": "",
"database": null,
"plugin_id": "sample",
"plugin_connection_provider": "sample.connection",
"plugin_connection_type": "sample"
}))
.unwrap();
let provider: PluginConnectionProviderContribution = serde_json::from_value(serde_json::json!({
"id": "sample.connection",
"label": "Sample",
"database_type": "sample",
"fields": [{ "key": "port", "label": "Port", "type": "number", "binding": "port", "required": true }]
}))
.unwrap();
assert!(validate_plugin_connection_values(&config, &provider)
.unwrap_err()
.contains("port between 1 and 65535"));
}
#[test]
fn allows_incomplete_fields_only_for_declared_permissive_actions() {
let config: ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "plugin-connection",
"name": "Plugin connection",
"db_type": "plugin",
"host": "",
"port": 0,
"username": "",
"password": "",
"database": null,
"plugin_id": "sample",
"plugin_connection_provider": "sample.connection",
"plugin_connection_type": "sample"
}))
.unwrap();
let provider: PluginConnectionProviderContribution = serde_json::from_value(serde_json::json!({
"id": "sample.connection",
"label": "Sample",
"database_type": "sample",
"fields": [{ "key": "host", "label": "Host", "type": "text", "binding": "host", "required": true }]
}))
.unwrap();
assert!(validate_plugin_connection_values_for_action(&config, &provider, false).is_ok());
assert!(validate_plugin_connection_values_for_action(&config, &provider, true)
.unwrap_err()
.contains("is required"));
}
#[test]
fn resolves_only_declared_custom_actions() {
let provider: PluginConnectionProviderContribution = serde_json::from_value(serde_json::json!({
"id": "sample.connection",
"label": "Sample",
"database_type": "sample",
"fields": [],
"actions": [{ "id": "discover", "label": "Discover" }]
}))
.unwrap();
assert_eq!(plugin_invoke_connection_action(&provider, "discover").unwrap().id, "discover");
assert!(plugin_invoke_connection_action(&provider, "missing").unwrap_err().contains("does not declare action"));
}
#[test]
fn validates_connection_action_field_updates() {
let provider: PluginConnectionProviderContribution = serde_json::from_value(serde_json::json!({
"id": "sample.connection",
"label": "Sample",
"database_type": "sample",
"fields": [
{ "key": "host", "label": "Host", "type": "text", "binding": "host" },
{ "key": "port", "label": "Port", "type": "number", "binding": "port" }
]
}))
.unwrap();
let result = plugin_connection_action_result(
serde_json::json!({ "message": "Updated", "fieldValues": { "host": "db.internal", "port": 5432 } }),
&provider,
)
.unwrap();
assert_eq!(result.message.as_deref(), Some("Updated"));
assert_eq!(result.field_values.get("port").and_then(serde_json::Value::as_u64), Some(5432));
assert!(plugin_connection_action_result(
serde_json::json!({ "fieldValues": { "unknown": "value" } }),
&provider,
)
.unwrap_err()
.contains("undeclared field"));
assert!(plugin_connection_action_result(serde_json::json!({ "fieldValues": { "port": "5432" } }), &provider,)
.unwrap_err()
.contains("invalid value type"));
}
}
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+912
View File
@@ -0,0 +1,912 @@
use std::collections::HashMap;
use std::path::Path;
use std::process::Stdio;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::Duration;
use bytes::Bytes;
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use tokio::io::{AsyncBufRead, AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
use tokio::process::{Child, ChildStdin, ChildStdout};
use tokio::sync::{broadcast, oneshot, watch, Mutex, RwLock};
use tokio::time::timeout;
use super::{
InstalledPlugin, PluginBackendTransport, PluginRuntimeEnv, SUPPORTED_PLUGIN_HOST_API_VERSION,
SUPPORTED_PLUGIN_PROTOCOL_VERSION,
};
pub const PLUGIN_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
const MAX_JSON_MESSAGE_BYTES: usize = 8 * 1024 * 1024;
const MAX_BINARY_MESSAGE_BYTES: usize = 64 * 1024 * 1024;
const FRAME_KIND_JSON: u8 = 0;
const FRAME_KIND_BINARY: u8 = 1;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct PluginEvent {
pub plugin_id: String,
pub method: String,
#[serde(default)]
pub params: serde_json::Value,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PluginBinaryMessage {
pub plugin_id: String,
pub channel: String,
pub data: Bytes,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum PluginSessionState {
Starting,
Running,
Stopping,
Stopped,
Exited,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct PluginSessionStatus {
pub state: PluginSessionState,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
}
impl PluginSessionStatus {
fn new(state: PluginSessionState, message: Option<String>) -> Self {
Self { state, message }
}
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct PluginHandshake {
pub protocol_version: u32,
#[serde(default)]
pub capabilities: Vec<String>,
pub plugin: PluginHandshakeIdentity,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
pub struct PluginHandshakeIdentity {
pub id: String,
pub version: String,
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginInitializeParams<'a> {
host: PluginHostDescription<'a>,
plugin: PluginDescription<'a>,
permissions: &'a [String],
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginHostDescription<'a> {
dbx_version: &'a str,
host_api_version: &'static str,
protocol_versions: [u32; 1],
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
struct PluginDescription<'a> {
id: &'a str,
version: &'a str,
}
#[derive(Debug, Serialize)]
struct PluginRequest<'a> {
jsonrpc: &'static str,
id: u64,
#[serde(skip_serializing_if = "Option::is_none")]
driver: Option<&'a str>,
method: &'a str,
params: serde_json::Value,
}
#[derive(Debug, Serialize)]
struct PluginNotification<'a> {
jsonrpc: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
driver: Option<&'a str>,
method: &'a str,
params: serde_json::Value,
}
type PendingResponse = oneshot::Sender<Result<serde_json::Value, String>>;
pub struct PluginSidecarSession {
plugin: InstalledPlugin,
app_version: String,
transport: PluginBackendTransport,
child: Arc<Mutex<Child>>,
stdin: Mutex<ChildStdin>,
pending: Arc<Mutex<HashMap<u64, PendingResponse>>>,
next_request_id: AtomicU64,
events: broadcast::Sender<PluginEvent>,
binary_messages: broadcast::Sender<PluginBinaryMessage>,
status: watch::Sender<PluginSessionStatus>,
handshake: RwLock<Option<PluginHandshake>>,
}
impl PluginSidecarSession {
pub async fn start(
plugin: InstalledPlugin,
app_version: impl Into<String>,
env: PluginRuntimeEnv,
) -> Result<Arc<Self>, String> {
ensure_plugin_backend(&plugin)?;
let transport = plugin.manifest.backend_entrypoint().map(|backend| backend.transport).unwrap_or_default();
let app_version = app_version.into();
let mut child = spawn_plugin_child(&plugin, &app_version, &env)?;
let stdin = child.stdin.take().ok_or("Plugin stdin unavailable")?;
let stdout = child.stdout.take().ok_or("Plugin stdout unavailable")?;
let stderr = child.stderr.take();
let child = Arc::new(Mutex::new(child));
let pending = Arc::new(Mutex::new(HashMap::new()));
let (events, _) = broadcast::channel(256);
let (binary_messages, _) = broadcast::channel(64);
let (status, _) = watch::channel(PluginSessionStatus::new(PluginSessionState::Starting, None));
let session = Arc::new(Self {
plugin,
app_version,
transport,
child,
stdin: Mutex::new(stdin),
pending,
next_request_id: AtomicU64::new(1),
events,
binary_messages,
status,
handshake: RwLock::new(None),
});
session.spawn_stdout_reader(stdout);
if let Some(stderr) = stderr {
session.spawn_stderr_reader(stderr);
}
if !session.plugin.manifest.is_legacy() {
let handshake = match session.initialize().await {
Ok(handshake) => handshake,
Err(error) => {
session.shutdown().await;
return Err(format!("Plugin '{}' initialization failed: {error}", session.plugin.manifest.id));
}
};
*session.handshake.write().await = Some(handshake);
}
let transitioned = session.status.send_if_modified(|status| {
if status.state != PluginSessionState::Starting {
return false;
}
*status = PluginSessionStatus::new(PluginSessionState::Running, None);
true
});
if !transitioned {
let status = session.status();
session.shutdown().await;
return Err(format!(
"Plugin '{}' stopped during initialization{}",
session.plugin.manifest.id,
status.message.map_or_else(String::new, |message| format!(": {message}"))
));
}
Ok(session)
}
pub fn plugin(&self) -> &InstalledPlugin {
&self.plugin
}
pub fn subscribe_events(&self) -> broadcast::Receiver<PluginEvent> {
self.events.subscribe()
}
pub fn subscribe_binary(&self) -> broadcast::Receiver<PluginBinaryMessage> {
self.binary_messages.subscribe()
}
pub fn subscribe_status(&self) -> watch::Receiver<PluginSessionStatus> {
self.status.subscribe()
}
pub fn status(&self) -> PluginSessionStatus {
self.status.borrow().clone()
}
pub async fn handshake(&self) -> Option<PluginHandshake> {
self.handshake.read().await.clone()
}
pub async fn invoke<T>(&self, method: &str, params: serde_json::Value) -> Result<T, String>
where
T: DeserializeOwned,
{
self.invoke_with_timeout(method, params, None, Some(PLUGIN_REQUEST_TIMEOUT)).await
}
pub async fn invoke_with_timeout<T>(
&self,
method: &str,
params: serde_json::Value,
driver: Option<&str>,
timeout_duration: Option<Duration>,
) -> Result<T, String>
where
T: DeserializeOwned,
{
let value = self.invoke_value(method, params, driver, timeout_duration).await?;
serde_json::from_value(value)
.map_err(|error| format!("Failed to decode plugin '{}' result: {error}", self.plugin.manifest.id))
}
pub async fn notify(&self, method: &str, params: serde_json::Value, driver: Option<&str>) -> Result<(), String> {
self.ensure_running()?;
validate_protocol_name(method)?;
let notification = PluginNotification { jsonrpc: "2.0", driver, method, params };
let payload = serde_json::to_vec(&notification).map_err(|error| error.to_string())?;
self.write_json(&payload).await
}
pub async fn send_binary(&self, channel: &str, data: &[u8]) -> Result<(), String> {
self.ensure_running()?;
if self.transport != PluginBackendTransport::StdioFramed {
return Err(format!(
"Plugin '{}' does not use the framed transport required for binary messages",
self.plugin.manifest.id
));
}
validate_binary_channel(channel)?;
if data.len() > MAX_BINARY_MESSAGE_BYTES {
return Err(format!("Plugin binary message exceeds {MAX_BINARY_MESSAGE_BYTES} bytes"));
}
let channel_bytes = channel.as_bytes();
let payload_len = 2usize
.checked_add(channel_bytes.len())
.and_then(|length| length.checked_add(data.len()))
.ok_or("Plugin binary frame is too large")?;
let mut stdin = self.stdin.lock().await;
stdin.write_u8(FRAME_KIND_BINARY).await.map_err(|error| self.write_error(error))?;
stdin.write_u32(payload_len as u32).await.map_err(|error| self.write_error(error))?;
stdin.write_u16(channel_bytes.len() as u16).await.map_err(|error| self.write_error(error))?;
stdin.write_all(channel_bytes).await.map_err(|error| self.write_error(error))?;
stdin.write_all(data).await.map_err(|error| self.write_error(error))?;
stdin.flush().await.map_err(|error| self.write_error(error))
}
pub async fn shutdown(&self) {
self.status.send_replace(PluginSessionStatus::new(PluginSessionState::Stopping, None));
let kill_result = self.child.lock().await.kill().await;
let message = kill_result.err().map(|error| error.to_string());
fail_pending(&self.pending, "Plugin session stopped").await;
self.status.send_replace(PluginSessionStatus::new(PluginSessionState::Stopped, message));
}
pub async fn pid(&self) -> Option<u32> {
self.child.lock().await.id()
}
async fn initialize(&self) -> Result<PluginHandshake, String> {
let params = PluginInitializeParams {
host: PluginHostDescription {
dbx_version: &self.app_version,
host_api_version: SUPPORTED_PLUGIN_HOST_API_VERSION,
protocol_versions: [SUPPORTED_PLUGIN_PROTOCOL_VERSION],
},
plugin: PluginDescription { id: &self.plugin.manifest.id, version: &self.plugin.manifest.version },
permissions: &self.plugin.manifest.permissions,
};
let params = serde_json::to_value(params).map_err(|error| error.to_string())?;
let handshake: PluginHandshake =
self.invoke_with_timeout("plugin/initialize", params, None, Some(PLUGIN_REQUEST_TIMEOUT)).await?;
if handshake.protocol_version != SUPPORTED_PLUGIN_PROTOCOL_VERSION {
return Err(format!(
"Plugin selected protocol version {}, expected {}",
handshake.protocol_version, SUPPORTED_PLUGIN_PROTOCOL_VERSION
));
}
if handshake.plugin.id != self.plugin.manifest.id || handshake.plugin.version != self.plugin.manifest.version {
return Err(format!(
"Plugin backend identity '{}/{}' does not match manifest '{}/{}'",
handshake.plugin.id, handshake.plugin.version, self.plugin.manifest.id, self.plugin.manifest.version
));
}
Ok(handshake)
}
async fn invoke_value(
&self,
method: &str,
params: serde_json::Value,
driver: Option<&str>,
timeout_duration: Option<Duration>,
) -> Result<serde_json::Value, String> {
self.ensure_running_or_starting()?;
validate_protocol_name(method)?;
let request_id = self.next_request_id.fetch_add(1, Ordering::Relaxed);
let request = PluginRequest { jsonrpc: "2.0", id: request_id, driver, method, params };
let payload = serde_json::to_vec(&request).map_err(|error| error.to_string())?;
let (sender, receiver) = oneshot::channel();
self.pending.lock().await.insert(request_id, sender);
if let Err(error) = self.write_json(&payload).await {
self.pending.lock().await.remove(&request_id);
return Err(error);
}
let receive = async {
receiver.await.map_err(|_| format!("Plugin '{}' response channel closed", self.plugin.manifest.id))?
};
match timeout_duration {
Some(duration) => match timeout(duration, receive).await {
Ok(result) => result,
Err(_) => {
self.pending.lock().await.remove(&request_id);
Err(format!(
"Plugin '{}' request '{}' timed out after {} seconds",
self.plugin.manifest.id,
method,
duration.as_secs()
))
}
},
None => receive.await,
}
}
async fn write_json(&self, payload: &[u8]) -> Result<(), String> {
if payload.len() > MAX_JSON_MESSAGE_BYTES {
return Err(format!("Plugin JSON message exceeds {MAX_JSON_MESSAGE_BYTES} bytes"));
}
let mut stdin = self.stdin.lock().await;
match self.transport {
PluginBackendTransport::StdioJsonLines => {
stdin.write_all(payload).await.map_err(|error| self.write_error(error))?;
stdin.write_u8(b'\n').await.map_err(|error| self.write_error(error))?;
}
PluginBackendTransport::StdioFramed => {
stdin.write_u8(FRAME_KIND_JSON).await.map_err(|error| self.write_error(error))?;
stdin.write_u32(payload.len() as u32).await.map_err(|error| self.write_error(error))?;
stdin.write_all(payload).await.map_err(|error| self.write_error(error))?;
}
}
stdin.flush().await.map_err(|error| self.write_error(error))
}
fn write_error(&self, error: std::io::Error) -> String {
format!("Failed to write to plugin '{}': {error}", self.plugin.manifest.id)
}
fn ensure_running(&self) -> Result<(), String> {
let status = self.status();
if status.state == PluginSessionState::Running {
Ok(())
} else {
Err(format!("Plugin '{}' is not running ({:?})", self.plugin.manifest.id, status.state))
}
}
fn ensure_running_or_starting(&self) -> Result<(), String> {
let status = self.status();
if matches!(status.state, PluginSessionState::Starting | PluginSessionState::Running) {
Ok(())
} else {
Err(format!("Plugin '{}' is not available ({:?})", self.plugin.manifest.id, status.state))
}
}
fn spawn_stdout_reader(self: &Arc<Self>, stdout: ChildStdout) {
let session = self.clone();
tokio::spawn(async move {
let result = match session.transport {
PluginBackendTransport::StdioJsonLines => read_json_lines(&session, BufReader::new(stdout)).await,
PluginBackendTransport::StdioFramed => read_framed(&session, stdout).await,
};
let message = match result {
Ok(()) => session.exit_message().await,
Err(error) => error,
};
fail_pending(&session.pending, &message).await;
if matches!(session.status().state, PluginSessionState::Stopping | PluginSessionState::Stopped) {
return;
}
let message = session.terminate_after_output_end(message).await;
session.status.send_if_modified(|status| {
if matches!(status.state, PluginSessionState::Stopping | PluginSessionState::Stopped) {
return false;
}
*status = PluginSessionStatus::new(PluginSessionState::Exited, Some(message.clone()));
true
});
});
}
fn spawn_stderr_reader(self: &Arc<Self>, stderr: tokio::process::ChildStderr) {
let plugin_id = self.plugin.manifest.id.clone();
tokio::spawn(async move {
let mut reader = BufReader::new(stderr);
loop {
match read_limited_line(&mut reader, MAX_JSON_MESSAGE_BYTES).await {
Ok(Some(line)) => log::warn!("[plugin:{plugin_id}] {}", String::from_utf8_lossy(&line).trim_end()),
Ok(None) => break,
Err(error) => {
log::warn!("[plugin:{plugin_id}] failed to read stderr: {error}");
break;
}
}
}
});
}
async fn exit_message(&self) -> String {
match self.child.lock().await.try_wait() {
Ok(Some(status)) => format!("Plugin '{}' exited with status {status}", self.plugin.manifest.id),
Ok(None) => format!("Plugin '{}' closed its output stream", self.plugin.manifest.id),
Err(error) => format!("Plugin '{}' output closed: {error}", self.plugin.manifest.id),
}
}
async fn terminate_after_output_end(&self, message: String) -> String {
let mut child = self.child.lock().await;
match child.try_wait() {
Ok(Some(_)) => message,
Ok(None) => match child.kill().await {
Ok(()) => format!("{message}; process terminated by host"),
Err(error) => format!("{message}; failed to terminate process: {error}"),
},
Err(error) => format!("{message}; failed to inspect process: {error}"),
}
}
async fn dispatch_json(&self, payload: &[u8]) -> Result<(), String> {
let value: serde_json::Value = serde_json::from_slice(payload).map_err(|error| {
format!("Failed to parse plugin '{}' protocol message: {error}", self.plugin.manifest.id)
})?;
if !self.plugin.manifest.is_legacy() && value.get("jsonrpc").and_then(serde_json::Value::as_str) != Some("2.0")
{
return Err(format!("Plugin '{}' sent a message without jsonrpc 2.0", self.plugin.manifest.id));
}
if let Some(request_id) = value.get("id").and_then(serde_json::Value::as_u64) {
let result = decode_response_value(&self.plugin.manifest.id, value);
if let Some(sender) = self.pending.lock().await.remove(&request_id) {
let _ = sender.send(result);
} else {
log::warn!("[plugin:{}] ignored response for unknown request {request_id}", self.plugin.manifest.id);
}
return Ok(());
}
if let Some(method) = value.get("method").and_then(serde_json::Value::as_str) {
if !self.plugin.manifest.is_legacy() {
validate_protocol_name(method)?;
}
let event = PluginEvent {
plugin_id: self.plugin.manifest.id.clone(),
method: method.to_string(),
params: value.get("params").cloned().unwrap_or(serde_json::Value::Null),
};
let _ = self.events.send(event);
return Ok(());
}
Err(format!("Plugin '{}' sent a protocol message without id or method", self.plugin.manifest.id))
}
fn dispatch_binary(&self, payload: Bytes) -> Result<(), String> {
if payload.len() < 2 {
return Err(format!("Plugin '{}' sent an invalid binary frame", self.plugin.manifest.id));
}
let channel_len = u16::from_be_bytes([payload[0], payload[1]]) as usize;
if channel_len == 0 || payload.len() < 2 + channel_len {
return Err(format!("Plugin '{}' sent an invalid binary channel", self.plugin.manifest.id));
}
let channel = std::str::from_utf8(&payload[2..2 + channel_len]).map_err(|error| {
format!("Plugin '{}' sent a non-UTF-8 binary channel: {error}", self.plugin.manifest.id)
})?;
validate_binary_channel(channel)?;
let message = PluginBinaryMessage {
plugin_id: self.plugin.manifest.id.clone(),
channel: channel.to_string(),
data: payload.slice(2 + channel_len..),
};
let _ = self.binary_messages.send(message);
Ok(())
}
}
async fn read_json_lines(session: &PluginSidecarSession, mut reader: BufReader<ChildStdout>) -> Result<(), String> {
loop {
let Some(line) = read_limited_line(&mut reader, MAX_JSON_MESSAGE_BYTES)
.await
.map_err(|error| format!("Failed to read plugin '{}' output: {error}", session.plugin.manifest.id))?
else {
return Ok(());
};
let trimmed = trim_ascii_whitespace(&line);
if trimmed.is_empty() {
continue;
}
if let Err(error) = session.dispatch_json(trimmed).await {
if !session.plugin.manifest.is_legacy() {
return Err(error);
}
log::warn!(
"[plugin:{}] ignored non-protocol stdout: {} ({error})",
session.plugin.manifest.id,
String::from_utf8_lossy(trimmed)
);
}
}
}
async fn read_framed(session: &PluginSidecarSession, mut stdout: ChildStdout) -> Result<(), String> {
loop {
let kind = match stdout.read_u8().await {
Ok(kind) => kind,
Err(error) if error.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(()),
Err(error) => {
return Err(format!("Failed to read plugin '{}' frame kind: {error}", session.plugin.manifest.id))
}
};
let length =
stdout.read_u32().await.map_err(|error| {
format!("Failed to read plugin '{}' frame length: {error}", session.plugin.manifest.id)
})? as usize;
let maximum = if kind == FRAME_KIND_JSON { MAX_JSON_MESSAGE_BYTES } else { MAX_BINARY_MESSAGE_BYTES + 1024 };
if length > maximum {
return Err(format!("Plugin '{}' frame exceeds {maximum} bytes", session.plugin.manifest.id));
}
let mut payload = vec![0; length];
stdout.read_exact(&mut payload).await.map_err(|error| {
format!("Failed to read plugin '{}' frame payload: {error}", session.plugin.manifest.id)
})?;
match kind {
FRAME_KIND_JSON => session.dispatch_json(&payload).await?,
FRAME_KIND_BINARY => session.dispatch_binary(Bytes::from(payload))?,
_ => return Err(format!("Plugin '{}' sent unknown frame kind {kind}", session.plugin.manifest.id)),
}
}
}
async fn read_limited_line<R>(reader: &mut R, maximum: usize) -> std::io::Result<Option<Vec<u8>>>
where
R: AsyncBufRead + Unpin,
{
let mut output = Vec::new();
loop {
let available = reader.fill_buf().await?;
if available.is_empty() {
return if output.is_empty() { Ok(None) } else { Ok(Some(output)) };
}
let take = available.iter().position(|byte| *byte == b'\n').map(|index| index + 1).unwrap_or(available.len());
if output.len().saturating_add(take) > maximum {
return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "plugin output line is too large"));
}
output.extend_from_slice(&available[..take]);
reader.consume(take);
if output.last() == Some(&b'\n') {
return Ok(Some(output));
}
}
}
fn trim_ascii_whitespace(mut bytes: &[u8]) -> &[u8] {
while bytes.first().is_some_and(u8::is_ascii_whitespace) {
bytes = &bytes[1..];
}
while bytes.last().is_some_and(u8::is_ascii_whitespace) {
bytes = &bytes[..bytes.len() - 1];
}
bytes
}
fn decode_response_value(plugin_id: &str, value: serde_json::Value) -> Result<serde_json::Value, String> {
if let Some(error) = value.get("error") {
let message = error
.get("message")
.and_then(serde_json::Value::as_str)
.map(str::to_string)
.unwrap_or_else(|| error.to_string());
return Err(message);
}
if value.get("result").is_none() && value.get("error").is_none() {
return Err(format!("Plugin '{plugin_id}' response has neither result nor error"));
}
Ok(value.get("result").cloned().unwrap_or(serde_json::Value::Null))
}
async fn fail_pending(pending: &Mutex<HashMap<u64, PendingResponse>>, message: &str) {
let responses = std::mem::take(&mut *pending.lock().await);
for (_, sender) in responses {
let _ = sender.send(Err(message.to_string()));
}
}
fn validate_binary_channel(channel: &str) -> Result<(), String> {
if channel.is_empty() || channel.len() > u16::MAX as usize {
return Err("Plugin binary channel must contain 1-65535 bytes".to_string());
}
if channel.chars().any(char::is_whitespace) {
return Err("Plugin binary channel cannot contain whitespace".to_string());
}
Ok(())
}
fn validate_protocol_name(value: &str) -> Result<(), String> {
if value.is_empty()
|| value.len() > 256
|| !value
.chars()
.all(|character| character.is_ascii_alphanumeric() || matches!(character, '.' | '_' | ':' | '/' | '-'))
{
return Err("Plugin protocol name is invalid".to_string());
}
Ok(())
}
fn ensure_plugin_backend(plugin: &InstalledPlugin) -> Result<(), String> {
if !plugin.compatibility.compatible {
return Err(format!(
"Plugin '{}' is incompatible: {}",
plugin.manifest.id,
plugin.compatibility.errors.join("; ")
));
}
if plugin.compatibility.backend_executable.is_none() {
return Err(format!("Plugin '{}' does not provide a backend entrypoint", plugin.manifest.id));
}
Ok(())
}
fn spawn_plugin_child(plugin: &InstalledPlugin, app_version: &str, env: &PluginRuntimeEnv) -> Result<Child, String> {
let executable_path =
plugin.compatibility.backend_executable.as_ref().ok_or_else(|| {
format!("Plugin '{}' does not provide a compatible backend executable", plugin.manifest.id)
})?;
ensure_executable_permission(executable_path)?;
let mut command = crate::process::new_tokio_command(executable_path);
command
.current_dir(&plugin.path)
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.kill_on_drop(true)
.env("DBX_PLUGIN_ID", &plugin.manifest.id)
.env("DBX_PLUGIN_VERSION", &plugin.manifest.version)
.env("DBX_APP_VERSION", app_version)
.env("DBX_HOST_API_VERSION", SUPPORTED_PLUGIN_HOST_API_VERSION)
.env("DBX_PLUGIN_PROTOCOL_VERSION", SUPPORTED_PLUGIN_PROTOCOL_VERSION.to_string());
env.apply_to(&mut command);
command.spawn().map_err(|error| format!("Failed to start plugin '{}': {error}", plugin.manifest.id))
}
fn ensure_executable_permission(path: &Path) -> Result<(), String> {
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
let mode = std::fs::metadata(path).map_err(|error| error.to_string())?.permissions().mode();
if mode & 0o111 == 0 {
return Err(format!("Plugin backend is not executable: {}", path.display()));
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use std::time::Duration;
use super::{
decode_response_value, read_limited_line, trim_ascii_whitespace, PluginSessionState, PluginSidecarSession,
};
use crate::plugins::{InstalledPlugin, PluginManifest, PluginRuntimeEnv};
use tokio::io::BufReader;
#[tokio::test]
async fn rejects_oversized_json_lines_before_unbounded_growth() {
let mut reader = BufReader::new(std::io::Cursor::new(b"123456\n"));
let error = read_limited_line(&mut reader, 4).await.expect_err("line should be rejected");
assert_eq!(error.kind(), std::io::ErrorKind::InvalidData);
}
#[test]
fn decodes_json_rpc_result_and_error() {
assert_eq!(
decode_response_value("sample", serde_json::json!({ "id": 1, "result": { "ok": true } })).unwrap(),
serde_json::json!({ "ok": true })
);
assert_eq!(
decode_response_value("sample", serde_json::json!({ "id": 1, "error": { "message": "boom" } }))
.unwrap_err(),
"boom"
);
}
#[test]
fn trims_protocol_whitespace() {
assert_eq!(trim_ascii_whitespace(b" \n{}\r\n"), b"{}");
}
#[cfg(unix)]
#[tokio::test]
async fn negotiates_routes_concurrent_responses_and_forwards_events() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let executable = dir.path().join("plugin.sh");
std::fs::write(
&executable,
r#"#!/bin/sh
IFS= read -r initialize
initialize_id=$(printf '%s' "$initialize" | sed -E 's/.*"id":([0-9]+).*/\1/')
printf '{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":1,"capabilities":["events"],"plugin":{"id":"sample.sidecar","version":"1.0.0"}}}\n' "$initialize_id"
IFS= read -r first
IFS= read -r second
first_id=$(printf '%s' "$first" | sed -E 's/.*"id":([0-9]+).*/\1/')
second_id=$(printf '%s' "$second" | sed -E 's/.*"id":([0-9]+).*/\1/')
first_method=$(printf '%s' "$first" | sed -E 's/.*"method":"([^"]+)".*/\1/')
second_method=$(printf '%s' "$second" | sed -E 's/.*"method":"([^"]+)".*/\1/')
printf '{"jsonrpc":"2.0","method":"sample/progress","params":{"value":50}}\n'
printf '{"jsonrpc":"2.0","id":%s,"result":"%s"}\n' "$second_id" "$second_method"
printf '{"jsonrpc":"2.0","id":%s,"result":"%s"}\n' "$first_id" "$first_method"
sleep 30
"#,
)
.unwrap();
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
"manifest_version": 1,
"id": "sample.sidecar",
"name": "Sample Sidecar",
"version": "1.0.0",
"publisher": "dbx",
"engines": { "dbx": ">=0.1.0", "host_api": "^1.0" },
"permissions": ["host.events"],
"entrypoints": {
"backend": {
"protocol_versions": [1],
"transport": "stdio-jsonl",
"executable": "plugin.sh"
}
}
}))
.unwrap();
let plugin = InstalledPlugin::new(manifest, dir.path().to_path_buf(), "0.5.67");
let session = PluginSidecarSession::start(plugin, "0.5.67", PluginRuntimeEnv::default())
.await
.expect("v1 sidecar should initialize");
assert_eq!(session.status().state, PluginSessionState::Running);
assert_eq!(session.handshake().await.unwrap().capabilities, vec!["events"]);
let mut events = session.subscribe_events();
let first = session.invoke::<String>("sample/first", serde_json::Value::Null);
let second = session.invoke::<String>("sample/second", serde_json::Value::Null);
let (first, second) = tokio::join!(first, second);
assert_eq!(first.unwrap(), "sample/first");
assert_eq!(second.unwrap(), "sample/second");
let event = events.recv().await.unwrap();
assert_eq!(event.method, "sample/progress");
assert_eq!(event.params["value"], 50);
session.shutdown().await;
assert_eq!(session.status().state, PluginSessionState::Stopped);
}
#[cfg(unix)]
#[tokio::test]
async fn failed_initialize_terminates_plugin_process() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let executable = dir.path().join("plugin.sh");
let pid_file = dir.path().join("plugin.pid");
std::fs::write(
&executable,
format!(
r#"#!/bin/sh
printf '%s' "$$" > '{}'
IFS= read -r initialize
initialize_id=$(printf '%s' "$initialize" | sed -E 's/.*"id":([0-9]+).*/\1/')
printf '{{"jsonrpc":"2.0","id":%s,"result":{{"protocolVersion":1,"capabilities":[],"plugin":{{"id":"wrong.sidecar","version":"1.0.0"}}}}}}\n' "$initialize_id"
sleep 30
"#,
pid_file.display()
),
)
.unwrap();
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
"manifest_version": 1,
"id": "sample.sidecar",
"name": "Sample Sidecar",
"version": "1.0.0",
"publisher": "dbx",
"engines": { "dbx": ">=0.1.0", "host_api": "^1.0" },
"entrypoints": {
"backend": {
"protocol_versions": [1],
"transport": "stdio-jsonl",
"executable": "plugin.sh"
}
}
}))
.unwrap();
let plugin = InstalledPlugin::new(manifest, dir.path().to_path_buf(), "0.5.67");
let error = match PluginSidecarSession::start(plugin, "0.5.67", PluginRuntimeEnv::default()).await {
Ok(session) => {
session.shutdown().await;
panic!("mismatched backend identity should fail initialization")
}
Err(error) => error,
};
assert!(error.contains("does not match manifest"));
let pid = std::fs::read_to_string(&pid_file).unwrap().parse::<u32>().unwrap();
for _ in 0..20 {
if !process_exists(pid) {
return;
}
tokio::time::sleep(Duration::from_millis(10)).await;
}
assert!(!process_exists(pid), "plugin process {pid} survived failed initialization");
}
#[cfg(unix)]
#[tokio::test]
async fn legacy_jsonl_runtime_ignores_banner_output() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let executable = dir.path().join("plugin.sh");
std::fs::write(
&executable,
r#"#!/bin/sh
IFS= read -r request
request_id=$(printf '%s' "$request" | sed -E 's/.*"id":([0-9]+).*/\1/')
printf 'legacy banner\n'
printf '{"id":%s,"result":{"ok":true}}\n' "$request_id"
sleep 30
"#,
)
.unwrap();
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
"id": "legacy",
"name": "Legacy",
"executable": "plugin.sh"
}))
.unwrap();
let plugin = InstalledPlugin::new(manifest, dir.path().to_path_buf(), "0.5.67");
let session = PluginSidecarSession::start(plugin, "0.5.67", PluginRuntimeEnv::default()).await.unwrap();
let result: serde_json::Value = session.invoke("ping", serde_json::Value::Null).await.unwrap();
assert_eq!(result["ok"], true);
session.shutdown().await;
}
#[cfg(unix)]
fn process_exists(pid: u32) -> bool {
std::process::Command::new("kill")
.arg("-0")
.arg(pid.to_string())
.stderr(std::process::Stdio::null())
.status()
.map(|status| status.success())
.unwrap_or(false)
}
}