25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
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 jdbc_sessions;
mod lifecycle;
#[cfg(all(test, any(windows, unix)))]
mod lifecycle_tests;
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, PluginRuntimeProxy,
};
pub use installer::{
PluginInstallPolicy, PluginInstallProvenance, PluginInstallResponse, PluginInstallResult, PluginInstallSource,
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,
PluginCapabilityManifest, PluginCompatibility, PluginConnectionActionContribution, PluginConnectionActionVariant,
PluginConnectionActionWhen, PluginConnectionCapability, PluginConnectionProviderContribution, PluginContribution,
PluginDriverManifest, PluginEngines, PluginEntrypoints, PluginFieldCondition, PluginFieldConditionClause,
PluginFieldConditionLiteral, PluginFilesystemCapability, PluginFilesystemProviderContribution,
PluginFormFieldBinding, PluginFormFieldDefinition, PluginFormFieldOption, PluginFormFieldPicker,
PluginFormFieldPickerKind, PluginFormFieldType, PluginManifest, PluginMcpAccess, PluginMcpContribution,
PluginMcpScope, PluginMcpToolDeclaration, PluginMcpToolset, 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,
/// Where the active installation came from (repository / publisher / signing key / source).
/// `None` for installs recorded before provenance existed; those stay unconstrained until the
/// next install records fresh provenance.
pub provenance: Option<PluginInstallProvenance>,
}
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct InstalledPluginInfo {
pub manifest: PluginManifest,
pub compatibility: PluginCompatibilityInfo,
#[serde(skip_serializing_if = "Option::is_none")]
pub provenance: Option<PluginInstallProvenance>,
}
#[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, provenance: None }
}
/// Attaches the recorded install provenance (see `installer::read_container_provenance`).
pub fn with_provenance(mut self, provenance: Option<PluginInstallProvenance>) -> Self {
self.provenance = provenance;
self
}
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(),
},
provenance: self.provenance.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,
jdbc_runtimes: jdbc_sessions::JdbcRuntimeCache,
}
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 {
let lifecycle = PluginLifecycle::for_store(&root_dir);
Self { root_dir, app_version: app_version.into(), lifecycle, jdbc_runtimes: Default::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())?;
if entry.file_name() == std::ffi::OsStr::new(installer::PLUGIN_TRASH_DIR) {
// Logical uninstall tombstones are not plugin containers: never discover one, not
// even while its physical delete is still pending.
continue;
}
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)
.with_provenance(PluginPackageInstaller::read_container_provenance(&container_path)?),
);
}
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 fn find_capability(&self, capability_id: &str) -> Result<Option<InstalledPlugin>, String> {
Ok(self.list_installed()?.into_iter().find(|plugin| {
plugin.compatibility.compatible
&& plugin.manifest.capabilities.iter().any(|capability| capability.id == capability_id)
}))
}
pub fn find_capability_for_plugin(
&self,
plugin_id: &str,
capability_id: &str,
) -> Result<Option<InstalledPlugin>, String> {
Ok(self.find_plugin(plugin_id)?.filter(|plugin| {
plugin.compatibility.compatible
&& plugin.manifest.capabilities.iter().any(|capability| capability.id == capability_id)
}))
}
pub async fn invoke_capability<T>(
&self,
capability_id: &str,
method: &str,
params: serde_json::Value,
) -> Result<T, String>
where
T: DeserializeOwned,
{
let plugin = self
.find_capability(capability_id)?
.ok_or_else(|| format!("Plugin capability '{capability_id}' is not installed"))?;
self.invoke_capability_on_plugin(plugin, capability_id, method, params).await
}
pub async fn invoke_capability_for_plugin<T>(
&self,
plugin_id: &str,
capability_id: &str,
method: &str,
params: serde_json::Value,
) -> Result<T, String>
where
T: DeserializeOwned,
{
let plugin = self
.find_capability_for_plugin(plugin_id, capability_id)?
.ok_or_else(|| format!("Plugin '{plugin_id}' capability '{capability_id}' is not installed"))?;
self.invoke_capability_on_plugin(plugin, capability_id, method, params).await
}
async fn invoke_capability_on_plugin<T>(
&self,
plugin: InstalledPlugin,
capability_id: &str,
method: &str,
params: serde_json::Value,
) -> Result<T, String>
where
T: DeserializeOwned,
{
let _operation = self.lifecycle.begin_operation(&plugin.manifest.id)?;
// A rollback in another host may have completed between discovery and admission.
let plugin = self.find_plugin(&plugin.manifest.id)?.ok_or("Plugin is no longer installed")?;
ensure_plugin_compatible(&plugin)?;
let env = PluginRuntimeEnv::default().with_plugin_data_dir(&self.plugin_data_dir(&plugin.manifest.id));
let runtime_lease = self.lifecycle.runtime_lease(&plugin.manifest.id)?;
let session =
PluginSidecarSession::start_with_runtime_lease(plugin, self.app_version.clone(), env, runtime_lease)
.await?;
let _cleanup = runtime::ShutdownOnDrop::new(session.clone());
let result =
session.invoke_with_timeout(method, params, Some(capability_id), Some(PLUGIN_REQUEST_TIMEOUT)).await;
match (result, session.shutdown().await) {
(Ok(value), Ok(())) => Ok(value),
(Err(invoke_error), Ok(())) => Err(invoke_error),
(Ok(_), Err(shutdown_error)) => {
Err(format!("Plugin capability invocation completed but shutdown failed: {shutdown_error}"))
}
(Err(invoke_error), Err(shutdown_error)) => {
Err(format!("{invoke_error}; additionally failed to stop plugin: {shutdown_error}"))
}
}
}
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)?;
// This is a short-lived, one-shot driver invocation: it starts its own sidecar instead of
// going through `PluginHost`, so it is not in `PluginHost::sessions` and needs its own
// lease. `begin_operation` matches those semantics (not a connection the user keeps open)
// and makes the whole start -> invoke -> shutdown sequence mutually exclusive with an
// install, rollback, or uninstall of the same plugin.
let _operation = self.lifecycle.begin_operation(&plugin.manifest.id)?;
let current = self.find_driver(driver_id)?.ok_or("Plugin driver is no longer 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));
let runtime_lease = self.lifecycle.runtime_lease(&plugin.manifest.id)?;
let session =
PluginSidecarSession::start_with_runtime_lease(plugin, self.app_version.clone(), env, runtime_lease)
.await?;
let _cleanup = runtime::ShutdownOnDrop::new(session.clone());
let result = session.invoke_with_timeout(method, params, Some(driver_id), timeout_duration).await;
match (result, session.shutdown().await) {
(Ok(value), Ok(())) => Ok(value),
(Err(invoke_error), Ok(())) => Err(invoke_error),
(Ok(_), Err(shutdown_error)) => {
Err(format!("Plugin invocation completed but shutdown failed: {shutdown_error}"))
}
(Err(invoke_error), Err(shutdown_error)) => {
Err(format!("{invoke_error}; additionally failed to stop plugin: {shutdown_error}"))
}
}
}
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()
},
provenance: None,
}
}
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: Option<lifecycle::PluginUsageGuard>,
logical: Option<Arc<jdbc_sessions::JdbcLogicalSession>>,
}
impl PluginDriverSession {
async fn start(
plugin: InstalledPlugin,
driver_id: String,
app_version: String,
env: PluginRuntimeEnv,
activity: lifecycle::PluginUsageGuard,
) -> Result<Self, String> {
let runtime_lease = activity.runtime_lease()?;
let sidecar = PluginSidecarSession::start_with_runtime_lease(plugin, app_version, env, runtime_lease).await?;
Ok(Self { sidecar, driver_id, _activity: Some(activity), logical: None })
}
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,
{
if let Some(logical) = &self.logical {
return logical.invoke(method, params, timeout_duration).await;
}
let mut params = params;
let mut cancel = self.cancel_statement_on_drop(&mut params);
let result = self.sidecar.invoke_with_timeout(method, params, Some(&self.driver_id), timeout_duration).await;
if let Some(cancel) = cancel.as_mut() {
cancel.token = None;
}
result
}
/// The JDBC plugin runs one statement at a time on its shared connection, so a request the host
/// abandons (the user pressed stop) would otherwise keep the next request waiting until the
/// database finishes it. Tagging the request lets the plugin cancel exactly that statement.
fn cancel_statement_on_drop(&self, params: &mut serde_json::Value) -> Option<CancelStatementOnDrop> {
if self.driver_id != "jdbc" {
return None;
}
let token = uuid::Uuid::new_v4().to_string();
params.as_object_mut()?.insert(JDBC_CANCEL_TOKEN_PARAM.into(), token.clone().into());
Some(CancelStatementOnDrop {
sidecar: self.sidecar.clone(),
driver_id: self.driver_id.clone(),
token: Some(token),
})
}
pub async fn shutdown(&self) -> Result<(), String> {
if let Some(logical) = &self.logical {
logical.close().await;
return Ok(());
}
self.sidecar.shutdown().await
}
/// Confirm JDBC cleanup for an owned native-operation scope. Ordinary shutdown remains best effort.
pub async fn shutdown_confirmed(&self) -> Result<(), String> {
if let Some(logical) = &self.logical {
return logical.close_confirmed().await;
}
if self.driver_id == "jdbc" {
let closed: Result<serde_json::Value, _> = self
.sidecar
.invoke_with_timeout(
"close",
serde_json::json!({}),
Some(&self.driver_id),
Some(Duration::from_secs(3)),
)
.await;
let acknowledged = closed.and_then(|value| {
if value["ok"] == true {
Ok(())
} else {
Err("JDBC session cleanup was not confirmed".to_string())
}
});
let stopped = self.sidecar.shutdown().await;
return acknowledged.and(stopped);
}
self.sidecar.shutdown().await
}
pub fn is_available(&self) -> bool {
self.logical.as_ref().is_none_or(|logical| logical.is_available())
}
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
}
}
const JDBC_CANCEL_STATEMENT_METHOD: &str = "cancelStatement";
const JDBC_CANCEL_TOKEN_PARAM: &str = "cancelToken";
const JDBC_CANCEL_STATEMENT_TIMEOUT: Duration = Duration::from_secs(5);
struct CancelStatementOnDrop {
sidecar: Arc<PluginSidecarSession>,
driver_id: String,
token: Option<String>,
}
impl Drop for CancelStatementOnDrop {
fn drop(&mut self) {
let Some(token) = self.token.take() else {
return;
};
let Ok(handle) = tokio::runtime::Handle::try_current() else {
return;
};
let sidecar = self.sidecar.clone();
let driver_id = std::mem::take(&mut self.driver_id);
handle.spawn(async move {
// Plugins without `cancelStatement` reply with an error once the abandoned statement ends.
let _: Result<serde_json::Value, _> = sidecar
.invoke_with_timeout(
JDBC_CANCEL_STATEMENT_METHOD,
serde_json::json!({ JDBC_CANCEL_TOKEN_PARAM: token }),
Some(&driver_id),
Some(JDBC_CANCEL_STATEMENT_TIMEOUT),
)
.await;
});
}
}
impl Drop for PluginDriverSession {
fn drop(&mut self) {
if let Some(logical) = &self.logical {
logical.close_in_background();
} else {
drop(runtime::ShutdownOnDrop::new(self.sidecar.clone()));
}
}
}
#[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.unwrap();
}
#[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.unwrap();
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
assert!(!process_exists(pid));
let _ = std::fs::remove_dir_all(dir);
}
#[cfg(unix)]
#[tokio::test]
async fn dropped_jdbc_request_cancels_its_statement_by_token() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let executable = dir.path().join("plugin.py");
std::fs::write(
&executable,
r#"#!/usr/bin/python3
import json, os, sys
root = os.path.dirname(__file__)
for line in sys.stdin:
request = json.loads(line)
params = request.get('params', {})
if request['method'] == 'cancelStatement':
with open(os.path.join(root, 'cancelled.tmp'), 'w') as out:
out.write(params.get('cancelToken', ''))
os.replace(os.path.join(root, 'cancelled.tmp'), os.path.join(root, 'cancelled'))
print(json.dumps({'id': request['id'], 'result': {'cancelled': True}}), flush=True)
elif request['method'] == 'executeQuery' and params.get('sql') == 'slow':
with open(os.path.join(root, 'running.tmp'), 'w') as out:
out.write(params.get('cancelToken', ''))
os.replace(os.path.join(root, 'running.tmp'), os.path.join(root, 'running'))
else:
print(json.dumps({'id': request['id'], 'result': {'token': params.get('cancelToken')}}), flush=True)
"#,
)
.unwrap();
std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o755)).unwrap();
let plugin = InstalledPlugin::new(
PluginManifest {
id: "jdbc".to_string(),
name: "JDBC".to_string(),
version: "test".to_string(),
protocol_version: 1,
executable: Some("plugin.py".to_string()),
drivers: vec![PluginDriverManifest {
id: "jdbc".to_string(),
label: "JDBC".to_string(),
kind: "external".to_string(),
database_type: Some("jdbc".to_string()),
}],
..PluginManifest::default()
},
dir.path().to_path_buf(),
env!("CARGO_PKG_VERSION"),
);
let session = std::sync::Arc::new(
PluginDriverSession::start_for_test(plugin, "jdbc".to_string(), PluginRuntimeEnv::default()).await.unwrap(),
);
let completed: serde_json::Value = session.invoke("listTables", serde_json::json!({})).await.unwrap();
assert!(completed["token"].is_string(), "every JDBC request carries a cancel token");
let running = dir.path().join("running");
let slow_session = session.clone();
let slow = tokio::spawn(async move {
slow_session.invoke::<serde_json::Value>("executeQuery", serde_json::json!({ "sql": "slow" })).await
});
tokio::time::timeout(std::time::Duration::from_secs(5), async {
while !running.exists() {
tokio::time::sleep(std::time::Duration::from_millis(10)).await;
}
})
.await
.unwrap();
slow.abort();
assert!(slow.await.unwrap_err().is_cancelled());
let cancelled = dir.path().join("cancelled");
tokio::time::timeout(std::time::Duration::from_secs(5), async {
while !cancelled.exists() {
tokio::time::sleep(std::time::Duration::from_millis(10)).await;
}
})
.await
.expect("dropping the request must send cancelStatement");
let slow_token = std::fs::read_to_string(&running).unwrap();
assert!(!slow_token.is_empty());
assert_eq!(std::fs::read_to_string(&cancelled).unwrap(), slow_token);
assert_ne!(completed["token"], slow_token.as_str(), "completed requests are never cancelled");
session.shutdown().await.unwrap();
}
#[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);
}
#[tokio::test]
async fn driver_invocations_are_gated_by_the_update_lease_for_their_whole_session() {
let root = std::env::temp_dir().join(format!("dbx-plugin-driver-lease-test-{}", uuid::Uuid::new_v4()));
let plugin_dir = root.join("sample");
std::fs::create_dir_all(&plugin_dir).unwrap();
std::fs::write(
plugin_dir.join("manifest.json"),
// External drivers only exist on the legacy manifest shape, which is what
// `PluginRegistry::find_driver` resolves.
serde_json::json!({
"id": "sample",
"name": "Sample",
"version": "1.0.0",
"publisher": "example",
"protocol_version": 1,
"executable": "plugin.sh",
"drivers": [{ "id": "sample-driver", "label": "Sample", "kind": "external", "database_type": "sample" }]
})
.to_string(),
)
.unwrap();
// Present but never executable: the manifest stays compatible so the invocation gets past
// the lease, while starting the sidecar fails immediately and deterministically on every
// platform (no exec bit on unix, not a valid image on Windows).
std::fs::write(plugin_dir.join("plugin.sh"), "#!/bin/sh\nexit 1\n").unwrap();
let registry = PluginRegistry::new_with_app_version(root.clone(), "0.5.67");
let update = registry.lifecycle().begin_update("sample").unwrap();
let refused = registry
.invoke_driver_with_env_and_timeout::<serde_json::Value>(
"sample-driver",
"testConnection",
serde_json::json!({}),
PluginRuntimeEnv::default(),
None,
)
.await
.unwrap_err();
assert!(refused.contains("Plugin update is in progress"), "{refused}");
drop(update);
// Once the update released the lease the invocation runs, and because the sidecar cannot
// start it must report that instead of the update error: the guard covered the start
// attempt and was released on the way out.
let failed_start = registry
.invoke_driver_with_env_and_timeout::<serde_json::Value>(
"sample-driver",
"testConnection",
serde_json::json!({}),
PluginRuntimeEnv::default(),
None,
)
.await
.unwrap_err();
assert!(!failed_start.contains("Plugin update is in progress"), "{failed_start}");
assert!(registry.lifecycle().begin_update("sample").is_ok(), "a failed invocation must not leak its lease");
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());
}
}