feat(core): split foundational capabilities into dedicated crates

This commit is contained in:
t8y2 committed 2026-09-18 13:00:56 +08:00
1 parent d50f5175d6
commit bc00431834
402 files changed
+4386 -3367

No files matched your search

+4
View File
@@ -0,0 +1,4 @@
pub use dbx_platform::process;
pub use dbx_types::models;
pub mod plugins;
+699
View File
@@ -0,0 +1,699 @@
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;
use serde::de::DeserializeOwned;
use serde::Serialize;
use tokio::process::Command;
mod assets;
mod filesystem;
mod host;
mod installer;
mod lifecycle;
mod manifest;
mod marketplace;
mod runtime;
pub use assets::PluginUiAsset;
pub use filesystem::{
PluginFilesystemEntry, PluginFilesystemEntryKind, PluginFilesystemListResult, PluginFilesystemMutationResult,
PluginFilesystemReadResult, DEFAULT_PLUGIN_FILESYSTEM_PAGE_SIZE, DEFAULT_PLUGIN_FILESYSTEM_PREVIEW_BYTES,
MAX_PLUGIN_FILESYSTEM_INLINE_WRITE_BYTES, MAX_PLUGIN_FILESYSTEM_PAGE_SIZE, MAX_PLUGIN_FILESYSTEM_PREVIEW_BYTES,
PLUGIN_FILESYSTEM_CREATE_DIRECTORY_METHOD, PLUGIN_FILESYSTEM_DELETE_METHOD, PLUGIN_FILESYSTEM_LIST_METHOD,
PLUGIN_FILESYSTEM_READ_METHOD, PLUGIN_FILESYSTEM_RENAME_METHOD, PLUGIN_FILESYSTEM_WRITE_METHOD,
};
pub use host::{ActivePluginSession, PluginConnectionActionResult, PluginConnectionHandle, PluginHost};
pub use installer::{
PluginInstallPolicy, PluginInstallResponse, PluginInstallResult, PluginPackageInstaller, PluginRollbackResponse,
PluginRollbackResult, PluginSignatureStatus, PluginTrustStore, PluginTrustedKey, DBXP_EXTENSION,
MAX_PLUGIN_PACKAGE_BYTES, PLUGIN_CHECKSUMS_FILE, PLUGIN_SIGNATURE_FILE,
};
pub use lifecycle::PluginLifecycle;
pub use marketplace::{
url_install_trust_store, PluginMarketplace, PluginMarketplaceArtifact, PluginMarketplaceCatalog,
PluginMarketplaceInstallRequest, PluginMarketplaceLocalization, PluginMarketplacePlugin,
PluginMarketplaceRepositoryMetadata, PluginMarketplaceVersion, PluginRepository, PluginRepositoryCatalogResult,
PluginRepositoryKind, PluginRepositoryStore, MAX_PLUGIN_CATALOG_BYTES, OFFICIAL_PLUGIN_REPOSITORY_ID,
SUPPORTED_PLUGIN_CATALOG_VERSION,
};
pub use manifest::{
current_plugin_target, resolve_safe_plugin_path, PluginBackendEntrypoint, PluginBackendTransport,
PluginCompatibility, PluginConnectionActionContribution, PluginConnectionActionVariant, PluginConnectionActionWhen,
PluginConnectionCapability, PluginConnectionProviderContribution, PluginContribution, PluginDriverManifest,
PluginEngines, PluginEntrypoints, PluginFieldCondition, PluginFieldConditionClause, PluginFieldConditionLiteral,
PluginFilesystemCapability, PluginFilesystemProviderContribution, PluginFormFieldBinding,
PluginFormFieldDefinition, PluginFormFieldOption, PluginFormFieldPicker, PluginFormFieldPickerKind,
PluginFormFieldType, PluginManifest, PluginUiEntrypoint, PluginWorkbenchContribution,
PLUGIN_CONNECTION_ACTION_METHOD, PLUGIN_CONNECTION_CONNECT_METHOD, PLUGIN_CONNECTION_DISCONNECT_METHOD,
PLUGIN_CONNECTION_TEST_METHOD, SUPPORTED_PLUGIN_HOST_API_VERSION, SUPPORTED_PLUGIN_HOST_FEATURES,
SUPPORTED_PLUGIN_MANIFEST_VERSION, SUPPORTED_PLUGIN_PERMISSIONS, SUPPORTED_PLUGIN_PROTOCOL_VERSION,
};
pub use runtime::{
PluginBinaryMessage, PluginEvent, PluginHandshake, PluginHandshakeIdentity, PluginSessionState,
PluginSessionStatus, PluginSidecarSession, PLUGIN_REQUEST_TIMEOUT, PLUGIN_REQUEST_USER_INPUT_METHOD,
};
#[derive(Debug, Clone)]
pub struct InstalledPlugin {
pub manifest: PluginManifest,
pub path: PathBuf,
pub compatibility: PluginCompatibility,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct InstalledPluginInfo {
pub manifest: PluginManifest,
pub compatibility: PluginCompatibilityInfo,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct PluginCompatibilityInfo {
pub compatible: bool,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub errors: Vec<String>,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub warnings: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub target: Option<String>,
}
impl InstalledPlugin {
pub fn new(manifest: PluginManifest, path: PathBuf, app_version: &str) -> Self {
let compatibility = manifest.compatibility(&path, app_version);
Self { manifest, path, compatibility }
}
pub fn info(&self) -> InstalledPluginInfo {
InstalledPluginInfo {
manifest: self.manifest.clone(),
compatibility: PluginCompatibilityInfo {
compatible: self.compatibility.compatible,
errors: self.compatibility.errors.clone(),
warnings: self.compatibility.warnings.clone(),
target: self.compatibility.target.clone(),
},
}
}
}
#[derive(Debug, Clone, Default)]
pub struct PluginRuntimeEnv {
vars: Vec<(String, String)>,
}
/// Environment variable that tells a plugin sidecar where to keep its
/// persistent, version-independent local data (preferences, audit logs,
/// known hosts, ...). Injected by the registry so plugins never have to fall
/// back to the OS temp dir, which macOS wipes on reboot.
pub const PLUGIN_DATA_DIR_ENV: &str = "DBX_PLUGIN_DATA_DIR";
impl PluginRuntimeEnv {
pub fn with_var(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
self.vars.push((key.into(), value.into()));
self
}
/// Sets `DBX_PLUGIN_DATA_DIR` unless the caller already provided one, so
/// an explicit override keeps winning over the registry default.
pub fn with_plugin_data_dir(self, data_dir: &Path) -> Self {
if self.get(PLUGIN_DATA_DIR_ENV).is_some() {
return self;
}
self.with_var(PLUGIN_DATA_DIR_ENV, data_dir.to_string_lossy().into_owned())
}
pub fn get(&self, key: &str) -> Option<&str> {
self.vars.iter().find_map(|(name, value)| (name == key).then_some(value.as_str()))
}
pub fn apply_to(&self, command: &mut Command) {
for (key, value) in &self.vars {
command.env(key, value);
}
}
}
#[derive(Debug, Clone)]
pub struct PluginRegistry {
root_dir: PathBuf,
app_version: String,
lifecycle: PluginLifecycle,
}
impl PluginRegistry {
pub fn new(root_dir: PathBuf) -> Self {
Self::new_with_app_version(root_dir, env!("CARGO_PKG_VERSION"))
}
pub fn new_with_app_version(root_dir: PathBuf, app_version: impl Into<String>) -> Self {
Self { root_dir, app_version: app_version.into(), lifecycle: PluginLifecycle::default() }
}
pub fn lifecycle(&self) -> PluginLifecycle {
self.lifecycle.clone()
}
pub fn root_dir(&self) -> &Path {
&self.root_dir
}
pub fn app_version(&self) -> &str {
&self.app_version
}
/// Persistent data directory for one plugin: `<data dir>/plugin-data/<id>`,
/// a sibling of the `plugins/` registry root so it survives version
/// upgrades and never collides with the installer-managed
/// `versions/` + `activations/` tree.
pub fn plugin_data_dir(&self, plugin_id: &str) -> PathBuf {
self.root_dir.parent().unwrap_or(&self.root_dir).join("plugin-data").join(plugin_id)
}
pub fn list_installed(&self) -> Result<Vec<InstalledPlugin>, String> {
let entries = match std::fs::read_dir(&self.root_dir) {
Ok(entries) => entries,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(vec![]),
Err(err) => return Err(err.to_string()),
};
let mut plugins = Vec::new();
for entry in entries {
let entry = entry.map_err(|err| err.to_string())?;
let container_path = entry.path();
if !container_path.is_dir() {
continue;
}
let path = match installer::resolve_active_plugin_dir(&container_path) {
Ok(Some(path)) => path,
Ok(None) => continue,
Err(error) => {
plugins.push(unavailable_plugin(container_path, error));
continue;
}
};
let manifest_path = path.join("manifest.json");
if !manifest_path.exists() {
continue;
}
let raw = match std::fs::read_to_string(&manifest_path) {
Ok(raw) => raw,
Err(error) => {
plugins.push(unavailable_plugin(
container_path,
format!("Failed to read plugin manifest {}: {error}", manifest_path.display()),
));
continue;
}
};
let manifest: PluginManifest = match serde_json::from_str(&raw) {
Ok(manifest) => manifest,
Err(error) => {
plugins.push(unavailable_plugin(
container_path,
format!("Failed to parse plugin manifest {}: {error}", manifest_path.display()),
));
continue;
}
};
plugins.push(InstalledPlugin::new(manifest, path, &self.app_version));
}
plugins.sort_by(|a, b| a.manifest.id.cmp(&b.manifest.id));
Ok(plugins)
}
pub fn find_driver(&self, driver_id: &str) -> Result<Option<InstalledPlugin>, String> {
Ok(self.list_installed()?.into_iter().find(|plugin| {
plugin.compatibility.compatible
&& plugin
.manifest
.drivers
.iter()
.any(|driver| driver.id == driver_id || driver.database_type.as_deref() == Some(driver_id))
}))
}
pub fn find_plugin(&self, plugin_id: &str) -> Result<Option<InstalledPlugin>, String> {
Ok(self.list_installed()?.into_iter().find(|plugin| plugin.manifest.id == plugin_id))
}
pub async fn invoke_driver<T>(&self, driver_id: &str, method: &str, params: serde_json::Value) -> Result<T, String>
where
T: DeserializeOwned,
{
self.invoke_driver_with_env(driver_id, method, params, PluginRuntimeEnv::default()).await
}
pub async fn invoke_driver_with_env<T>(
&self,
driver_id: &str,
method: &str,
params: serde_json::Value,
env: PluginRuntimeEnv,
) -> Result<T, String>
where
T: DeserializeOwned,
{
self.invoke_driver_with_env_and_timeout(driver_id, method, params, env, Some(PLUGIN_REQUEST_TIMEOUT)).await
}
pub async fn invoke_driver_with_env_and_timeout<T>(
&self,
driver_id: &str,
method: &str,
params: serde_json::Value,
env: PluginRuntimeEnv,
timeout_duration: Option<Duration>,
) -> Result<T, String>
where
T: DeserializeOwned,
{
let plugin =
self.find_driver(driver_id)?.ok_or_else(|| format!("Plugin driver '{driver_id}' is not installed"))?;
ensure_plugin_compatible(&plugin)?;
let env = env.with_plugin_data_dir(&self.plugin_data_dir(&plugin.manifest.id));
let session = PluginSidecarSession::start(plugin, self.app_version.clone(), env).await?;
let result = session.invoke_with_timeout(method, params, Some(driver_id), timeout_duration).await;
session.shutdown().await;
result
}
pub async fn start_driver_session(&self, driver_id: &str) -> Result<Arc<PluginDriverSession>, String> {
self.start_driver_session_with_env(driver_id, PluginRuntimeEnv::default()).await
}
pub async fn start_driver_session_with_env(
&self,
driver_id: &str,
env: PluginRuntimeEnv,
) -> Result<Arc<PluginDriverSession>, String> {
self.start_driver_session_for_connection(driver_id, env, driver_id).await
}
pub async fn start_driver_session_for_connection(
&self,
driver_id: &str,
env: PluginRuntimeEnv,
connection_label: &str,
) -> Result<Arc<PluginDriverSession>, String> {
let plugin =
self.find_driver(driver_id)?.ok_or_else(|| format!("Plugin driver '{driver_id}' is not installed"))?;
let activity = self.lifecycle.begin_connection(&plugin.manifest.id, connection_label)?;
let current =
self.find_driver(driver_id)?.ok_or_else(|| format!("Plugin driver '{driver_id}' is not installed"))?;
if current.manifest.id != plugin.manifest.id {
return Err(format!("Plugin driver '{driver_id}' changed. Please reconnect."));
}
let plugin = current;
ensure_plugin_compatible(&plugin)?;
let env = env.with_plugin_data_dir(&self.plugin_data_dir(&plugin.manifest.id));
PluginDriverSession::start(plugin, driver_id.to_string(), self.app_version.clone(), env, activity)
.await
.map(Arc::new)
}
}
fn unavailable_plugin(path: PathBuf, error: String) -> InstalledPlugin {
let id = path
.file_name()
.and_then(|name| name.to_str())
.filter(|name| !name.is_empty())
.unwrap_or("invalid-plugin")
.to_string();
InstalledPlugin {
manifest: PluginManifest {
id: id.clone(),
name: id,
version: "0.0.0-invalid".to_string(),
description: error.clone(),
..PluginManifest::default()
},
path,
compatibility: PluginCompatibility {
compatible: false,
errors: vec![error],
target: Some(current_plugin_target()),
..PluginCompatibility::default()
},
}
}
fn ensure_plugin_compatible(plugin: &InstalledPlugin) -> Result<(), String> {
if plugin.compatibility.compatible {
return Ok(());
}
Err(format!("Plugin '{}' is incompatible: {}", plugin.manifest.id, plugin.compatibility.errors.join("; ")))
}
pub struct PluginDriverSession {
sidecar: Arc<PluginSidecarSession>,
driver_id: String,
_activity: lifecycle::PluginUsageGuard,
}
impl PluginDriverSession {
async fn start(
plugin: InstalledPlugin,
driver_id: String,
app_version: String,
env: PluginRuntimeEnv,
activity: lifecycle::PluginUsageGuard,
) -> Result<Self, String> {
let sidecar = PluginSidecarSession::start(plugin, app_version, env).await?;
Ok(Self { sidecar, driver_id, _activity: activity })
}
pub async fn invoke<T>(&self, method: &str, params: serde_json::Value) -> Result<T, String>
where
T: DeserializeOwned,
{
self.invoke_with_timeout(method, params, Some(PLUGIN_REQUEST_TIMEOUT)).await
}
pub async fn invoke_with_timeout<T>(
&self,
method: &str,
params: serde_json::Value,
timeout_duration: Option<Duration>,
) -> Result<T, String>
where
T: DeserializeOwned,
{
self.sidecar.invoke_with_timeout(method, params, Some(&self.driver_id), timeout_duration).await
}
pub async fn shutdown(&self) {
self.sidecar.shutdown().await;
}
pub async fn pid(&self) -> Option<u32> {
self.sidecar.pid().await
}
pub fn subscribe_events(&self) -> tokio::sync::broadcast::Receiver<PluginEvent> {
self.sidecar.subscribe_events()
}
pub fn subscribe_binary(&self) -> tokio::sync::broadcast::Receiver<PluginBinaryMessage> {
self.sidecar.subscribe_binary()
}
pub async fn send_binary(&self, channel: &str, data: &[u8]) -> Result<(), String> {
self.sidecar.send_binary(channel, data).await
}
#[cfg(all(any(test, feature = "test-support"), unix))]
pub async fn start_for_test(
plugin: InstalledPlugin,
driver_id: String,
env: PluginRuntimeEnv,
) -> Result<Self, String> {
let activity = PluginLifecycle::default().begin_connection(&plugin.manifest.id, &driver_id)?;
Self::start(plugin, driver_id, env!("CARGO_PKG_VERSION").to_string(), env, activity).await
}
}
#[cfg(test)]
mod tests {
use std::path::{Path, PathBuf};
use super::{InstalledPlugin, PluginContribution, PluginManifest, PluginRegistry, PluginRuntimeEnv};
#[cfg(unix)]
use super::{PluginDriverManifest, PluginDriverSession};
#[test]
fn plugin_data_dir_lives_beside_the_plugin_registry() {
let registry = PluginRegistry::new(PathBuf::from("/data/plugins"));
assert_eq!(registry.plugin_data_dir("io.dbx.ssh"), PathBuf::from("/data/plugin-data/io.dbx.ssh"));
}
#[test]
fn plugin_data_dir_falls_back_to_registry_root_without_a_parent() {
let registry = PluginRegistry::new(PathBuf::from("/"));
assert_eq!(registry.plugin_data_dir("io.dbx.ssh"), PathBuf::from("/plugin-data/io.dbx.ssh"));
}
#[test]
fn with_plugin_data_dir_sets_the_env_var_once() {
let env = PluginRuntimeEnv::default().with_plugin_data_dir(Path::new("/data/plugin-data/io.dbx.ssh"));
assert_eq!(env.get("DBX_PLUGIN_DATA_DIR"), Some("/data/plugin-data/io.dbx.ssh"));
// An explicit caller-provided value wins over the registry default.
let explicit = PluginRuntimeEnv::default()
.with_var("DBX_PLUGIN_DATA_DIR", "/custom")
.with_plugin_data_dir(Path::new("/ignored"));
assert_eq!(explicit.get("DBX_PLUGIN_DATA_DIR"), Some("/custom"));
}
/// The registry-injected data dir must reach the sidecar process itself,
/// not just the `PluginRuntimeEnv` value object.
#[cfg(unix)]
#[tokio::test]
async fn activated_sidecar_receives_plugin_data_dir_env() {
use std::os::unix::fs::PermissionsExt;
use super::PluginHost;
let data_dir = tempfile::tempdir().unwrap();
let plugin_dir = data_dir.path().join("plugins").join("sample.sidecar");
std::fs::create_dir_all(&plugin_dir).unwrap();
let executable = plugin_dir.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":[],"plugin":{"id":"sample.sidecar","version":"1.0.0"}}}\n' "$initialize_id"
IFS= read -r request
request_id=$(printf '%s' "$request" | sed -E 's/.*"id":([0-9]+).*/\1/')
printf '{"jsonrpc":"2.0","id":%s,"result":"%s"}\n' "$request_id" "$DBX_PLUGIN_DATA_DIR"
sleep 30
"#,
)
.unwrap();
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
std::fs::write(
plugin_dir.join("manifest.json"),
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": [],
"entrypoints": {
"backend": {
"protocol_versions": [1],
"transport": "stdio-jsonl",
"executable": "plugin.sh"
}
}
})
.to_string(),
)
.unwrap();
let registry = PluginRegistry::new_with_app_version(data_dir.path().join("plugins"), "0.5.67");
let lifecycle = registry.lifecycle();
let host = PluginHost::new(registry);
let reported: String =
host.invoke("sample.sidecar", "sample/dataDir", serde_json::Value::Null, None, None).await.unwrap();
assert_eq!(
PathBuf::from(reported),
data_dir.path().join("plugin-data").join("sample.sidecar"),
"sidecar must see <data dir>/plugin-data/<id> in DBX_PLUGIN_DATA_DIR"
);
assert!(lifecycle.begin_update("sample.sidecar").is_ok());
let request_host = host.clone();
let pending = tokio::spawn(async move {
request_host
.invoke::<serde_json::Value>("sample.sidecar", "sample/wait", serde_json::Value::Null, None, None)
.await
});
tokio::time::timeout(std::time::Duration::from_secs(5), async {
while lifecycle.check_update("sample.sidecar").is_ok() {
tokio::task::yield_now().await;
}
})
.await
.unwrap();
assert!(lifecycle.begin_update("sample.sidecar").unwrap_err().contains("active operations"));
pending.abort();
assert!(pending.await.unwrap_err().is_cancelled());
assert!(lifecycle.begin_update("sample.sidecar").is_ok());
host.stop_all().await;
}
#[cfg(unix)]
#[tokio::test]
async fn shutdown_kills_plugin_child_process() {
let dir = std::env::temp_dir().join(format!("dbx-plugin-shutdown-test-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&dir).unwrap();
let executable = dir.join("plugin.sh");
std::fs::write(&executable, "#!/bin/sh\nsleep 30\n").unwrap();
{
use std::os::unix::fs::PermissionsExt;
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
}
let plugin = InstalledPlugin::new(
PluginManifest {
id: "jdbc".to_string(),
name: "JDBC".to_string(),
version: "test".to_string(),
protocol_version: 1,
description: String::new(),
executable: Some("plugin.sh".to_string()),
drivers: vec![PluginDriverManifest {
id: "jdbc".to_string(),
label: "JDBC".to_string(),
kind: "external".to_string(),
database_type: Some("jdbc".to_string()),
}],
contributions: Vec::new(),
..PluginManifest::default()
},
dir.clone(),
env!("CARGO_PKG_VERSION"),
);
let session = PluginDriverSession::start_for_test(plugin, "jdbc".to_string(), PluginRuntimeEnv::default())
.await
.expect("session should start");
let pid = session.pid().await.expect("child should have a pid");
session.shutdown().await;
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
assert!(!process_exists(pid));
let _ = std::fs::remove_dir_all(dir);
}
#[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)
}
#[test]
fn preserves_typed_contributions_in_manifest_round_trip() {
let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
"manifest_version": 1,
"id": "sample",
"name": "Sample",
"version": "1.0.0",
"publisher": "example",
"engines": { "host_api": "1" },
"contributions": [{
"type": "connection-provider",
"id": "sample.connection",
"database_type": "sample",
"fields": []
}]
}))
.expect("manifest should parse");
assert!(matches!(
&manifest.contributions[0],
PluginContribution::ConnectionProvider(provider) if provider.id == "sample.connection"
));
let serialized = serde_json::to_value(manifest).expect("manifest should serialize");
assert_eq!(serialized["contributions"][0]["database_type"], "sample");
}
#[test]
fn registry_lists_frontend_contributions_from_disk() {
let root = std::env::temp_dir().join(format!("dbx-plugin-registry-test-{}", uuid::Uuid::new_v4()));
let plugin_dir = root.join("sample");
std::fs::create_dir_all(&plugin_dir).expect("plugin directory should be created");
std::fs::write(
plugin_dir.join("manifest.json"),
serde_json::json!({
"manifest_version": 1,
"id": "sample",
"name": "Sample",
"version": "1.0.0",
"publisher": "example",
"engines": { "host_api": "1" },
"contributions": [{
"type": "connection-provider",
"id": "sample.connection",
"database_type": "sample",
"fields": []
}]
})
.to_string(),
)
.expect("manifest should be written");
let plugins = PluginRegistry::new(root.clone()).list_installed().expect("plugins should be listed");
assert_eq!(plugins.len(), 1);
assert!(matches!(
&plugins[0].manifest.contributions[0],
PluginContribution::ConnectionProvider(provider) if provider.id == "sample.connection"
));
let _ = std::fs::remove_dir_all(root);
}
#[test]
fn registry_keeps_other_plugins_visible_when_one_manifest_is_corrupt() {
let root = std::env::temp_dir().join(format!("dbx-plugin-corrupt-registry-test-{}", uuid::Uuid::new_v4()));
let valid = root.join("valid");
let corrupt = root.join("corrupt");
std::fs::create_dir_all(&valid).unwrap();
std::fs::create_dir_all(&corrupt).unwrap();
std::fs::write(
valid.join("manifest.json"),
serde_json::json!({ "id": "valid", "name": "Valid", "drivers": [] }).to_string(),
)
.unwrap();
std::fs::write(corrupt.join("manifest.json"), "{").unwrap();
let plugins = PluginRegistry::new(root.clone()).list_installed().unwrap();
assert_eq!(plugins.len(), 2);
assert!(plugins.iter().any(|plugin| plugin.manifest.id == "valid" && plugin.compatibility.compatible));
assert!(plugins.iter().any(|plugin| {
plugin.manifest.id == "corrupt"
&& !plugin.compatibility.compatible
&& plugin.compatibility.errors.iter().any(|error| error.contains("Failed to parse"))
}));
let _ = std::fs::remove_dir_all(root);
}
#[test]
fn installed_plugin_info_hides_runtime_paths() {
let plugin = InstalledPlugin::new(
PluginManifest {
manifest_version: 1,
id: "sample".to_string(),
name: "Sample".to_string(),
version: "1.0.0".to_string(),
publisher: "example".to_string(),
..PluginManifest::default()
},
std::path::PathBuf::from("/private/plugin/install"),
env!("CARGO_PKG_VERSION"),
);
let serialized = serde_json::to_value(plugin.info()).unwrap();
assert!(serialized.get("path").is_none());
assert!(serialized["compatibility"].get("backend_executable").is_none());
assert!(serialized["compatibility"].get("ui_entry").is_none());
assert!(serialized["compatibility"].get("ui_root").is_none());
}
}
@@ -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());
}
}
@@ -0,0 +1,537 @@
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,
icon: 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"));
}
}
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,183 @@
use std::collections::{BTreeMap, HashMap};
use std::sync::{Arc, Mutex};
const UPDATE_IN_PROGRESS: &str = "Plugin update is in progress. Please try again after it finishes.";
const OPERATIONS_ACTIVE: &str = "Plugin update blocked by active operations. Please wait for them to finish.";
#[derive(Debug, Clone, Default)]
pub struct PluginLifecycle {
usage: Arc<Mutex<HashMap<String, PluginUsage>>>,
}
#[derive(Debug, Default)]
struct PluginUsage {
connections: BTreeMap<String, usize>,
operations: usize,
updating: bool,
}
impl PluginUsage {
fn ensure_updatable(&self) -> Result<(), String> {
if self.updating {
return Err(UPDATE_IN_PROGRESS.to_string());
}
if !self.connections.is_empty() {
return Err(format!(
"Plugin update blocked by active connections: {}",
self.connections.keys().cloned().collect::<Vec<_>>().join(", ")
));
}
if self.operations > 0 {
return Err(OPERATIONS_ACTIVE.to_string());
}
Ok(())
}
}
#[derive(Debug, Clone)]
pub(crate) struct PluginUsageGuard {
_lease: Arc<PluginUsageLease>,
}
#[derive(Debug)]
struct PluginUsageLease {
lifecycle: PluginLifecycle,
plugin_id: String,
kind: PluginUsageKind,
}
#[derive(Debug)]
enum PluginUsageKind {
Connection(String),
Operation,
Update,
}
impl PluginLifecycle {
pub(crate) fn check_update(&self, plugin_id: &str) -> Result<(), String> {
let usage = self.usage.lock().unwrap_or_else(|error| error.into_inner());
usage.get(plugin_id).map_or(Ok(()), PluginUsage::ensure_updatable)
}
pub(crate) fn begin_connection(&self, plugin_id: &str, label: &str) -> Result<PluginUsageGuard, String> {
let label = if label.trim().is_empty() { plugin_id } else { label };
self.acquire(plugin_id, PluginUsageKind::Connection(label.to_string()))
}
pub(crate) fn begin_operation(&self, plugin_id: &str) -> Result<PluginUsageGuard, String> {
self.acquire(plugin_id, PluginUsageKind::Operation)
}
pub(crate) fn begin_update(&self, plugin_id: &str) -> Result<PluginUsageGuard, String> {
self.acquire(plugin_id, PluginUsageKind::Update)
}
fn acquire(&self, plugin_id: &str, kind: PluginUsageKind) -> Result<PluginUsageGuard, String> {
let mut plugins = self.usage.lock().unwrap_or_else(|error| error.into_inner());
let usage = plugins.entry(plugin_id.to_string()).or_default();
if usage.updating {
return Err(UPDATE_IN_PROGRESS.to_string());
}
match &kind {
PluginUsageKind::Connection(label) => *usage.connections.entry(label.clone()).or_default() += 1,
PluginUsageKind::Operation => usage.operations += 1,
PluginUsageKind::Update => {
usage.ensure_updatable()?;
usage.updating = true;
}
}
Ok(PluginUsageGuard {
_lease: Arc::new(PluginUsageLease { lifecycle: self.clone(), plugin_id: plugin_id.to_string(), kind }),
})
}
}
impl Drop for PluginUsageLease {
fn drop(&mut self) {
let mut plugins = self.lifecycle.usage.lock().unwrap_or_else(|error| error.into_inner());
let Some(usage) = plugins.get_mut(&self.plugin_id) else {
return;
};
match &self.kind {
PluginUsageKind::Connection(label) => {
if let Some(count) = usage.connections.get_mut(label) {
*count -= 1;
if *count == 0 {
usage.connections.remove(label);
}
}
}
PluginUsageKind::Operation => usage.operations -= 1,
PluginUsageKind::Update => usage.updating = false,
}
if usage.connections.is_empty() && usage.operations == 0 && !usage.updating {
plugins.remove(&self.plugin_id);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn connections_block_only_their_plugin_until_all_handles_are_dropped() {
let lifecycle = PluginLifecycle::default();
let connection = lifecycle.begin_connection("s3", "Production S3").unwrap();
let clone = connection.clone();
let second = lifecycle.begin_connection("s3", "Production S3").unwrap();
assert_eq!(
lifecycle.begin_update("s3").unwrap_err(),
"Plugin update blocked by active connections: Production S3"
);
assert!(lifecycle.begin_update("other").is_ok());
drop(connection);
drop(second);
assert!(lifecycle.begin_update("s3").is_err());
drop(clone);
assert!(lifecycle.begin_update("s3").is_ok());
}
#[test]
fn operations_block_updates_without_connections() {
let lifecycle = PluginLifecycle::default();
let operation = lifecycle.begin_operation("tool").unwrap();
assert_eq!(lifecycle.begin_update("tool").unwrap_err(), OPERATIONS_ACTIVE);
drop(operation);
assert!(lifecycle.begin_update("tool").is_ok());
}
#[test]
fn updates_block_new_connections_operations_and_updates() {
let lifecycle = PluginLifecycle::default();
let update = lifecycle.begin_update("s3").unwrap();
assert_eq!(lifecycle.begin_connection("s3", "S3").unwrap_err(), UPDATE_IN_PROGRESS);
assert_eq!(lifecycle.begin_operation("s3").unwrap_err(), UPDATE_IN_PROGRESS);
assert_eq!(lifecycle.begin_update("s3").unwrap_err(), UPDATE_IN_PROGRESS);
assert!(lifecycle.begin_connection("other", "Other").is_ok());
drop(update);
assert!(lifecycle.begin_connection("s3", "S3").is_ok());
assert!(lifecycle.usage.lock().unwrap().is_empty());
}
#[test]
fn connection_and_update_admission_are_atomic() {
for _ in 0..64 {
let lifecycle = PluginLifecycle::default();
let barrier = Arc::new(std::sync::Barrier::new(2));
let other_lifecycle = lifecycle.clone();
let other_barrier = barrier.clone();
let connection = std::thread::spawn(move || {
other_barrier.wait();
let result = other_lifecycle.begin_connection("s3", "S3");
other_barrier.wait();
result
});
barrier.wait();
let update = lifecycle.begin_update("s3");
barrier.wait();
let connection = connection.join().unwrap();
assert_ne!(connection.is_ok(), update.is_ok());
}
}
}
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