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::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::{ChildStdin, ChildStdout};
use tokio::sync::{broadcast, oneshot, watch, Mutex, RwLock};
use tokio::time::Instant;
use super::{
InstalledPlugin, PluginBackendTransport, PluginRuntimeEnv, SUPPORTED_PLUGIN_HOST_API_VERSION,
SUPPORTED_PLUGIN_HOST_FEATURES, SUPPORTED_PLUGIN_PROTOCOL_VERSION,
};
use dbx_platform::ssh_prompt;
/// A request failed this way without the host observing the end of the
/// handler, so the plugin may still be executing it. Lifecycle callers treat
/// the outcome as unconfirmed instead of assuming the request died with the
/// abandoned caller.
pub(super) fn request_may_still_execute(error: &str) -> bool {
error.contains("timed out after") || error.contains("was waiting for user input")
}
pub const PLUGIN_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
/// Host API method a plugin backend calls to ask the user for input
/// (`user_input.rs` semantics). Plugin-initiated requests use string ids, which
/// is what lets one stream carry both directions (see `dispatch_json`).
pub const PLUGIN_REQUEST_USER_INPUT_METHOD: &str = "host/requestUserInput";
/// Namespace reserved for host-initiated requests, i.e. calls a plugin makes
/// back into the host. Plugin manifests never receive methods from it.
pub const PLUGIN_HOST_REQUEST_PREFIX: &str = "host/";
/// Cap on user prompts a single plugin session may have open at once, so a
/// broken or hostile backend cannot stack dialogs.
const MAX_PLUGIN_PROMPTS_IN_FLIGHT: usize = 4;
/// Total time one request may spend paused on user input before it fails.
const MAX_PROMPT_PAUSE: Duration = Duration::from_secs(600);
const USER_INPUT_DEFAULT_TIMEOUT: Duration = Duration::from_secs(300);
const USER_INPUT_MIN_TIMEOUT: Duration = Duration::from_secs(5);
const USER_INPUT_MAX_TIMEOUT: Duration = Duration::from_secs(600);
const USER_INPUT_MAX_PROMPT_CHARS: usize = 2_000;
const USER_INPUT_MAX_TITLE_CHARS: usize = 200;
const USER_INPUT_MAX_DEFAULT_CHARS: usize = 1_000;
const USER_INPUT_MAX_OPTIONS: usize = 8;
const USER_INPUT_MAX_OPTION_CHARS: usize = 200;
const MAX_JSON_MESSAGE_BYTES: usize = 8 * 1024 * 1024;
const MAX_BINARY_MESSAGE_BYTES: usize = 64 * 1024 * 1024;
/// A legacy `stdio-jsonl` plugin writes one whole response per line, so a single
/// query page has to fit in that line. The framed transport caps JSON payloads at
/// `MAX_JSON_MESSAGE_BYTES` because an oversized payload can move to a binary frame,
/// but a JSONL plugin has no equivalent escape hatch: rejecting the line fails the
/// user's query (`plugin output line is too large`, seen with wide Oracle/JDBC pages).
/// Allow the line reader the same ceiling as a binary frame instead.
const MAX_JSON_LINE_BYTES: usize = MAX_BINARY_MESSAGE_BYTES;
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],
/// Host capabilities a plugin can rely on for this session. Feature names
/// are the Host API methods the plugin may call.
features: &'static [&'static str],
}
#[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<crate::process::ManagedChild>>,
shutdown_lock: Mutex<()>,
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>>,
/// Open `host/requestUserInput` prompts. While non-zero the host pauses the
/// request deadlines of this session so a user typing an MFA code cannot
/// fail a plugin `connection/test` or `connection/connect` call.
prompts: PromptActivity,
owner_runtime: tokio::runtime::Handle,
/// Last stderr lines, used to explain a sidecar that dies during startup.
stderr_tail: Arc<std::sync::Mutex<std::collections::VecDeque<String>>>,
stderr_closed: watch::Sender<bool>,
stdout_closed: std::sync::atomic::AtomicBool,
// Kept until the session (including its child/image handle) is completely dropped.
_runtime_lease: Option<std::fs::File>,
}
/// Shown when a Java sidecar (the JDBC plugin) was started by a runtime older
/// than its bytecode. Kept verbatim in sync with the desktop error catalog
/// (apps/desktop/src/i18n/backend-errors.ts -> connection.agentJavaTooOld).
pub const PLUGIN_JAVA_TOO_OLD_MESSAGE: &str =
"Plugin requires Java 21, but DBX started it with an older Java runtime. Use DBX managed JRE 21 or select a Java 21 executable in Driver Manager.";
const STDERR_TAIL_LINES: usize = 20;
const STDERR_TAIL_LINE_CHARS: usize = 2000;
const STDERR_CLOSE_WAIT: Duration = Duration::from_millis(500);
fn plugin_stderr_hint(stderr: &str) -> Option<&'static str> {
let lower = stderr.to_ascii_lowercase();
// Match the JVM wording variants independently: the tail keeps only the
// last lines, so a long stack trace can push the exception header out.
if lower.contains("unsupportedclassversionerror")
|| lower.contains("only recognizes class file versions up to")
|| lower.contains("has been compiled by a more recent version of the java runtime")
{
return Some(PLUGIN_JAVA_TOO_OLD_MESSAGE);
}
None
}
/// Cancelled discovery/initialization must not leave the stdout task and child owning each other.
pub(super) struct ShutdownOnDrop(Option<Arc<PluginSidecarSession>>);
impl ShutdownOnDrop {
pub(super) fn new(session: Arc<PluginSidecarSession>) -> Self {
Self(Some(session))
}
pub(super) fn disarm(mut self) {
self.0.take();
}
}
impl Drop for ShutdownOnDrop {
fn drop(&mut self) {
let Some(session) = self.0.take() else { return };
if session.status().state == PluginSessionState::Stopped {
return;
}
// Pool/session owners can also be dropped from a blocking thread.
let runtime = session.owner_runtime.clone();
runtime.spawn(async move {
if let Err(error) = session.shutdown().await {
log::warn!("{error}");
}
});
}
}
/// Tracks whether this plugin session has a user prompt open, and wakes the
/// requests that are waiting on a response so they can start or stop pausing
/// their deadline.
#[derive(Default)]
struct PromptActivity {
state: watch::Sender<PromptState>,
}
#[derive(Clone, Copy, Default)]
struct PromptState {
open: usize,
closed: bool,
}
impl PromptActivity {
fn begin(&self) {
self.state.send_modify(|state| state.open += 1);
}
fn end(&self) {
self.state.send_modify(|state| state.open -= 1);
}
/// Releases every open prompt when the session goes away, so the dialog
/// does not linger in front of a plugin that can no longer answer.
fn close(&self) {
self.state.send_modify(|state| state.closed = true);
}
async fn wait_close(&self) {
let mut state = self.state.subscribe();
let _ = state.wait_for(|state| state.closed).await;
}
}
impl PluginSidecarSession {
pub async fn start(
plugin: InstalledPlugin,
app_version: impl Into<String>,
env: PluginRuntimeEnv,
) -> Result<Arc<Self>, String> {
Self::start_with_runtime_lease(plugin, app_version, env, None).await
}
pub(super) async fn start_with_runtime_lease(
plugin: InstalledPlugin,
app_version: impl Into<String>,
env: PluginRuntimeEnv,
runtime_lease: Option<std::fs::File>,
) -> 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).await?;
let stdin = child.take_stdin().ok_or("Plugin stdin unavailable")?;
let stdout = child.take_stdout().ok_or("Plugin stdout unavailable")?;
let stderr = child.take_stderr();
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,
shutdown_lock: Mutex::new(()),
stdin: Mutex::new(stdin),
pending,
next_request_id: AtomicU64::new(1),
events,
binary_messages,
status,
handshake: RwLock::new(None),
prompts: PromptActivity::default(),
owner_runtime: tokio::runtime::Handle::current(),
stderr_tail: Default::default(),
stderr_closed: watch::channel(stderr.is_none()).0,
stdout_closed: Default::default(),
_runtime_lease: runtime_lease,
});
let startup = ShutdownOnDrop::new(session.clone());
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) => {
let shutdown_error = session.shutdown().await.err();
let message = match shutdown_error {
Some(shutdown_error) => format!("{error}; additionally failed to shut down: {shutdown_error}"),
None => error,
};
let message = format!("Plugin '{}' initialization failed: {message}", session.plugin.manifest.id);
return Err(session.with_stderr_hint(message).await);
}
};
*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();
let shutdown_error = session.shutdown().await.err();
let message = status.message.map_or_else(String::new, |message| format!(": {message}"));
let shutdown_error = shutdown_error.map_or_else(String::new, |error| format!("; shutdown failed: {error}"));
let message = format!(
"Plugin '{}' stopped during initialization{message}{shutdown_error}",
session.plugin.manifest.id
);
return Err(session.with_stderr_hint(message).await);
}
startup.disarm();
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(¬ification).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) -> Result<(), String> {
let _shutdown = self.shutdown_lock.lock().await;
if self.status().state == PluginSessionState::Stopped {
return Ok(());
}
self.status.send_replace(PluginSessionStatus::new(PluginSessionState::Stopping, None));
// Let any open user prompt resolve and close its dialog.
self.prompts.close();
// Stop the whole sidecar process tree, not just the tracked child. Script launchers can
// leave descendants that keep using the plugin container, which makes the rename-first
// uninstall fail with ERROR_ACCESS_DENIED even though the launcher itself is gone
// (#10601). `terminate()` is bounded by construction, so the app-exit path (`stop_all`)
// can never wait on it indefinitely: on Windows it terminates the private Job Object and
// confirms the tree has no active processes before reaping the launcher, and on other
// platforms it keeps tokio's direct-child kill semantics. The executable image lock is
// released when the session holding the `kill_on_drop` child drops, which uninstall
// performs before renaming the plugin directory (#10943).
let termination = self
.child
.lock()
.await
.terminate()
.await
.map_err(|error| format!("Failed to stop plugin '{}' process tree: {error}", self.plugin.manifest.id));
fail_pending(&self.pending, "Plugin session stopped").await;
match termination {
Ok(()) => {
self.status.send_replace(PluginSessionStatus::new(PluginSessionState::Stopped, None));
Ok(())
}
Err(error) => {
self.status.send_replace(PluginSessionStatus::new(PluginSessionState::Stopping, Some(error.clone())));
Err(error)
}
}
}
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],
features: SUPPORTED_PLUGIN_HOST_FEATURES,
},
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> {
let result = self.invoke_value_unhinted(method, params, driver, timeout_duration).await;
match result {
// Legacy sidecars (the JDBC plugin) skip `plugin/initialize`, so a
// JVM that dies at startup first surfaces as a failed request.
// A write can hit the broken pipe before stdout reports EOF.
Err(error) if self.process_output_closed() || error.starts_with("Failed to write to plugin") => {
Err(self.with_stderr_hint(error).await)
}
result => result,
}
}
fn process_output_closed(&self) -> bool {
self.stdout_closed.load(Ordering::Acquire)
|| !matches!(self.status().state, PluginSessionState::Starting | PluginSessionState::Running)
}
async fn invoke_value_unhinted(
&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);
}
match timeout_duration {
Some(duration) => {
let result = self.await_response(receiver, method, duration).await;
if result.is_err() {
self.pending.lock().await.remove(&request_id);
}
result
}
None => {
receiver.await.map_err(|_| format!("Plugin '{}' response channel closed", self.plugin.manifest.id))?
}
}
}
/// Waits for a host -> plugin response under `duration`, pausing the
/// deadline while the plugin has a user prompt open. `connection/test` and
/// `connection/connect` share the connection's connect timeout, which is
/// far shorter than a human reading a bastion MFA challenge; without the
/// pause the host would time out while the user is still typing and the
/// answer would arrive at a dead request.
async fn await_response(
&self,
mut receiver: oneshot::Receiver<Result<serde_json::Value, String>>,
method: &str,
duration: Duration,
) -> Result<serde_json::Value, String> {
let mut prompt_state = self.prompts.state.subscribe();
let start = Instant::now();
let mut paused_total = Duration::ZERO;
loop {
let state = *prompt_state.borrow_and_update();
if state.closed {
return Err("Plugin session stopped".to_string());
}
let active = start.elapsed().saturating_sub(paused_total);
if active >= duration {
return Err(format!(
"Plugin '{}' request '{}' timed out after {} seconds",
self.plugin.manifest.id,
method,
duration.as_secs()
));
}
if state.open > 0 {
// The user is answering: hold the deadline and re-measure when
// the prompt state changes.
let tick = Instant::now();
tokio::select! {
result = &mut receiver => {
return result
.map_err(|_| format!("Plugin '{}' response channel closed", self.plugin.manifest.id))?;
}
_ = prompt_state.changed() => {}
}
paused_total += tick.elapsed();
if paused_total > MAX_PROMPT_PAUSE {
return Err(format!(
"Plugin '{}' request '{}' was waiting for user input for more than {} seconds",
self.plugin.manifest.id,
method,
MAX_PROMPT_PAUSE.as_secs()
));
}
continue;
}
tokio::select! {
result = &mut receiver => {
return result
.map_err(|_| format!("Plugin '{}' response channel closed", self.plugin.manifest.id))?;
}
_ = prompt_state.changed() => {}
_ = tokio::time::sleep(duration - active) => {
return Err(format!(
"Plugin '{}' request '{}' timed out after {} seconds",
self.plugin.manifest.id,
method,
duration.as_secs()
));
}
}
}
}
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,
};
session.stdout_closed.store(true, Ordering::Release);
fail_pending(&session.pending, &message).await;
// A plugin that died mid-prompt can no longer answer it.
session.prompts.close();
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();
let tail = self.stderr_tail.clone();
let closed = self.stderr_closed.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)) => {
let line = String::from_utf8_lossy(&line).trim_end().to_string();
log::warn!("[plugin:{plugin_id}] {line}");
let mut tail = tail.lock().unwrap_or_else(|error| error.into_inner());
if tail.len() == STDERR_TAIL_LINES {
tail.pop_front();
}
tail.push_back(line.chars().take(STDERR_TAIL_LINE_CHARS).collect());
}
Ok(None) => break,
Err(error) => {
log::warn!("[plugin:{plugin_id}] failed to read stderr: {error}");
break;
}
}
}
closed.send_replace(true);
});
}
/// Puts a known cause found in the sidecar's stderr in front of a startup
/// error. Waits briefly for stderr to drain, since the JVM can close stdout
/// before its class-version error has been read.
async fn with_stderr_hint(&self, message: String) -> String {
if message.contains(PLUGIN_JAVA_TOO_OLD_MESSAGE) {
return message;
}
let mut closed = self.stderr_closed.subscribe();
let _ = tokio::time::timeout(STDERR_CLOSE_WAIT, closed.wait_for(|closed| *closed)).await;
let stderr = {
let tail = self.stderr_tail.lock().unwrap_or_else(|error| error.into_inner());
tail.iter().cloned().collect::<Vec<_>>().join("\n")
};
match plugin_stderr_hint(&stderr) {
Some(hint) => format!("{hint} Details: {message}; recent stderr:\n{stderr}"),
None => message,
}
}
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 {
match self.child.lock().await.terminate().await {
Ok(()) => format!("{message}; process tree terminated by host"),
Err(error) => format!("{message}; failed to terminate process tree: {error}"),
}
}
async fn dispatch_json(self: &Arc<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(());
}
// Host API requests initiated by the plugin sidecar. The host owns
// numeric ids (its own requests and the responses to them), the plugin
// owns string ids, so one stream carries both directions without
// changing the wire format older hosts already parse. Only `host/*`
// methods qualify, which keeps a plugin event that happens to carry a
// string id on the legacy path.
if let Some(request_id) = value.get("id").and_then(serde_json::Value::as_str) {
let method = value.get("method").and_then(serde_json::Value::as_str).unwrap_or_default();
if method.starts_with(PLUGIN_HOST_REQUEST_PREFIX) {
let request_id = request_id.to_string();
let method = method.to_string();
let params = value.get("params").cloned().unwrap_or(serde_json::Value::Null);
let session = self.clone();
session.spawn_plugin_request(request_id, method, params);
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(())
}
/// Answers one plugin-initiated Host API request in the background. The
/// stdout reader must keep draining plugin output while a prompt is open
/// (the plugin may still emit events), so the work is spawned instead of
/// being awaited inline.
fn spawn_plugin_request(self: &Arc<Self>, id: String, method: String, params: serde_json::Value) {
let session = self.clone();
tokio::spawn(async move {
let result = session.handle_plugin_request(&method, params).await;
if let Err(error) = session.respond_to_plugin_request(&id, result).await {
log::warn!("[plugin:{}] failed to answer '{method}': {error}", session.plugin.manifest.id);
}
});
}
/// Dispatches a Host API method a plugin called. Errors use JSON-RPC codes
/// so a plugin can tell "the host cannot ask the user" from "you asked for
/// something invalid" and degrade accordingly.
async fn handle_plugin_request(
&self,
method: &str,
params: serde_json::Value,
) -> Result<serde_json::Value, PluginHostRequestError> {
match method {
PLUGIN_REQUEST_USER_INPUT_METHOD => self.request_user_input(params).await,
other => Err(PluginHostRequestError::method_not_found(other)),
}
}
/// `host/requestUserInput` (Host API 1.1): relay one question to the user
/// and return the answer. The host only carries the question and the typed
/// value — it never answers on the user's behalf, and without an attached
/// UI it fails immediately so the plugin can fail closed instead of waiting.
async fn request_user_input(&self, params: serde_json::Value) -> Result<serde_json::Value, PluginHostRequestError> {
let spec = UserInputSpec::parse(params)?;
let state = *self.prompts.state.borrow();
if state.closed {
return Ok(serde_json::json!({ "action": "cancel" }));
}
if state.open >= MAX_PLUGIN_PROMPTS_IN_FLIGHT {
return Err(PluginHostRequestError::new(
-32002,
format!("Plugin already has {MAX_PLUGIN_PROMPTS_IN_FLIGHT} input prompts open"),
));
}
let prompt = ssh_prompt::UserInputRequest::new(spec.prompt.clone())
.with_title(spec.title.clone())
.with_source(Some(self.plugin.manifest.name.clone()))
.with_default(spec.default_value.clone())
.with_options(spec.options.clone())
.with_echo(spec.echo)
.into_request("", 0);
let Some(receiver) = ssh_prompt::request_ssh_prompt(prompt) else {
return Err(PluginHostRequestError::new(-32001, "The DBX host cannot ask the user for input right now"));
};
self.prompts.begin();
let answer = tokio::select! {
result = tokio::time::timeout(spec.timeout, receiver) => Some(result),
// Session gone: drop the receiver so the dialog is dismissed.
_ = self.prompts.wait_close() => None,
};
self.prompts.end();
Ok(match answer {
Some(Ok(Ok(answer))) => user_input_result(answer),
// The prompt was dismissed mid-flight (the dialog closed, the
// session went away) or the UI is gone: report a cancel, never a
// synthesized answer.
Some(Ok(Err(_))) | None => serde_json::json!({ "action": "cancel" }),
Some(Err(_)) => serde_json::json!({ "action": "timeout" }),
})
}
async fn respond_to_plugin_request(
&self,
id: &str,
result: Result<serde_json::Value, PluginHostRequestError>,
) -> Result<(), String> {
let value = match result {
Ok(result) => serde_json::json!({ "jsonrpc": "2.0", "id": id, "result": result }),
Err(error) => serde_json::json!({
"jsonrpc": "2.0",
"id": id,
"error": { "code": error.code, "message": error.message }
}),
};
let payload = serde_json::to_vec(&value).map_err(|error| error.to_string())?;
self.write_json(&payload).await
}
}
/// A JSON-RPC error returned to a plugin-initiated Host API call.
#[derive(Debug)]
struct PluginHostRequestError {
code: i64,
message: String,
}
impl PluginHostRequestError {
fn new(code: i64, message: impl Into<String>) -> Self {
Self { code, message: message.into() }
}
fn method_not_found(method: &str) -> Self {
Self::new(-32601, format!("Method not found: {method}"))
}
fn invalid_params(message: impl Into<String>) -> Self {
Self::new(-32602, message)
}
}
/// Validated `host/requestUserInput` params. Bounded so a plugin cannot push an
/// unbounded payload or an unusable timeout into the dialog.
#[derive(Debug)]
struct UserInputSpec {
prompt: String,
echo: bool,
title: Option<String>,
default_value: Option<String>,
options: Vec<ssh_prompt::SshPromptOption>,
timeout: Duration,
}
impl UserInputSpec {
fn parse(params: serde_json::Value) -> Result<Self, PluginHostRequestError> {
let object =
params.as_object().ok_or_else(|| PluginHostRequestError::invalid_params("params must be an object"))?;
let prompt = match object.get("prompt") {
Some(serde_json::Value::String(prompt)) if !prompt.trim().is_empty() => prompt.clone(),
_ => return Err(PluginHostRequestError::invalid_params("'prompt' must be a non-empty string")),
};
if prompt.chars().count() > USER_INPUT_MAX_PROMPT_CHARS {
return Err(PluginHostRequestError::invalid_params(format!(
"'prompt' must be at most {USER_INPUT_MAX_PROMPT_CHARS} characters"
)));
}
let title = optional_text(object.get("title"), "title", USER_INPUT_MAX_TITLE_CHARS)?;
let default_value = optional_text(object.get("default"), "default", USER_INPUT_MAX_DEFAULT_CHARS)?;
let echo = match object.get("echo") {
None | Some(serde_json::Value::Null) => false,
Some(serde_json::Value::Bool(echo)) => *echo,
Some(_) => return Err(PluginHostRequestError::invalid_params("'echo' must be a boolean")),
};
let mut options = Vec::new();
if let Some(value) = object.get("options") {
let list =
value.as_array().ok_or_else(|| PluginHostRequestError::invalid_params("'options' must be an array"))?;
if list.len() > USER_INPUT_MAX_OPTIONS {
return Err(PluginHostRequestError::invalid_params(format!(
"'options' supports at most {USER_INPUT_MAX_OPTIONS} entries"
)));
}
for entry in list {
let entry = entry
.as_object()
.ok_or_else(|| PluginHostRequestError::invalid_params("each option must be an object"))?;
let value = entry
.get("value")
.and_then(serde_json::Value::as_str)
.filter(|value| !value.is_empty())
.ok_or_else(|| PluginHostRequestError::invalid_params("each option needs a non-empty 'value'"))?;
let label = entry
.get("label")
.and_then(serde_json::Value::as_str)
.filter(|label| !label.trim().is_empty())
.unwrap_or(value);
if value.chars().count() > USER_INPUT_MAX_OPTION_CHARS
|| label.chars().count() > USER_INPUT_MAX_OPTION_CHARS
{
return Err(PluginHostRequestError::invalid_params(format!(
"option values and labels must be at most {USER_INPUT_MAX_OPTION_CHARS} characters"
)));
}
if options.iter().any(|existing: &ssh_prompt::SshPromptOption| existing.value == value) {
return Err(PluginHostRequestError::invalid_params("option values must be unique"));
}
options.push(ssh_prompt::SshPromptOption { value: value.to_string(), label: label.to_string() });
}
}
let timeout = match object.get("timeoutSecs") {
None | Some(serde_json::Value::Null) => USER_INPUT_DEFAULT_TIMEOUT,
Some(value) => match value.as_u64() {
Some(seconds) => Duration::from_secs(seconds).clamp(USER_INPUT_MIN_TIMEOUT, USER_INPUT_MAX_TIMEOUT),
None => return Err(PluginHostRequestError::invalid_params("'timeoutSecs' must be a number")),
},
};
Ok(Self { prompt, echo, title, default_value, options, timeout })
}
}
fn optional_text(
value: Option<&serde_json::Value>,
name: &str,
maximum: usize,
) -> Result<Option<String>, PluginHostRequestError> {
match value {
None | Some(serde_json::Value::Null) => Ok(None),
Some(serde_json::Value::String(text)) if text.chars().count() <= maximum => Ok(Some(text.clone())),
Some(serde_json::Value::String(_)) => {
Err(PluginHostRequestError::invalid_params(format!("'{name}' must be at most {maximum} characters")))
}
Some(_) => Err(PluginHostRequestError::invalid_params(format!("'{name}' must be a string"))),
}
}
/// Maps a user's answer to the `host/requestUserInput` result payload. Only a
/// typed value counts as a submission: host-key wording or a dismissal is a
/// cancel, so a plugin can never mistake "the dialog went away" for an answer.
fn user_input_result(answer: ssh_prompt::SshPromptAnswer) -> serde_json::Value {
match answer {
ssh_prompt::SshPromptAnswer::Secret(value) => serde_json::json!({ "action": "submit", "value": value }),
ssh_prompt::SshPromptAnswer::Reject | ssh_prompt::SshPromptAnswer::Accept { .. } => {
serde_json::json!({ "action": "cancel" })
}
}
}
async fn read_json_lines(
session: &Arc<PluginSidecarSession>,
mut reader: BufReader<ChildStdout>,
) -> Result<(), String> {
loop {
let Some(line) = read_limited_line(&mut reader, MAX_JSON_LINE_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: &Arc<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,
format!("plugin output line is too large: {maximum} bytes maximum"),
));
}
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(())
}
async fn spawn_plugin_child(
plugin: &InstalledPlugin,
app_version: &str,
env: &PluginRuntimeEnv,
) -> Result<crate::process::ManagedChild, 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);
crate::process::spawn_managed_child(&mut command)
.await
.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, user_input_result, PromptActivity,
UserInputSpec, USER_INPUT_DEFAULT_TIMEOUT, USER_INPUT_MAX_OPTIONS, USER_INPUT_MAX_TIMEOUT,
USER_INPUT_MIN_TIMEOUT,
};
use super::{plugin_stderr_hint, PLUGIN_JAVA_TOO_OLD_MESSAGE};
#[cfg(unix)]
use super::{PluginSessionState, PluginSidecarSession};
#[cfg(unix)]
use crate::plugins::{InstalledPlugin, PluginManifest, PluginRuntimeEnv};
use tokio::io::BufReader;
async fn assert_pending<F: std::future::Future>(mut future: std::pin::Pin<&mut F>) {
std::future::poll_fn(|context| {
assert!(future.as_mut().poll(context).is_pending());
std::task::Poll::Ready(())
})
.await;
}
#[tokio::test]
async fn prompt_activity_closes_all_waiters_and_stays_closed() {
let prompts = PromptActivity::default();
let first = prompts.wait_close();
let second = prompts.wait_close();
tokio::pin!(first, second);
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
prompts.close();
tokio::time::timeout(Duration::from_secs(1), async {
tokio::join!(first, second);
})
.await
.expect("every registered waiter must observe closure");
prompts.begin();
prompts.end();
prompts.close();
tokio::time::timeout(Duration::from_secs(1), prompts.wait_close())
.await
.expect("closure must persist for late subscribers after activity changes");
}
#[tokio::test]
async fn prompt_activity_preserves_changes_between_read_and_wait() {
let prompts = PromptActivity::default();
let mut first = prompts.state.subscribe();
let mut second = prompts.state.subscribe();
for receiver in [&mut first, &mut second] {
assert_eq!(receiver.borrow_and_update().open, 0);
}
prompts.begin();
for receiver in [&mut first, &mut second] {
tokio::time::timeout(Duration::from_secs(1), receiver.changed()).await.unwrap().unwrap();
assert_eq!(receiver.borrow_and_update().open, 1);
}
prompts.end();
for receiver in [&mut first, &mut second] {
tokio::time::timeout(Duration::from_secs(1), receiver.changed()).await.unwrap().unwrap();
assert_eq!(receiver.borrow_and_update().open, 0);
}
prompts.close();
for receiver in [&mut first, &mut second] {
tokio::time::timeout(Duration::from_secs(1), receiver.changed()).await.unwrap().unwrap();
assert!(receiver.borrow_and_update().closed);
}
}
#[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"{}");
}
/// Installs a sidecar that forwards two questions to the host over string
/// ids and echoes whatever it got back, so a test can assert the Host API
/// answers: `host/requestUserInput` plus an unknown `host/*` method.
#[cfg(unix)]
fn write_questioning_sidecar(dir: &std::path::Path) -> std::path::PathBuf {
use std::os::unix::fs::PermissionsExt;
let executable = 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 echo_request
echo_id=$(printf '%s' "$echo_request" | sed -E 's/.*"id":([0-9]+).*/\1/')
printf '{"jsonrpc":"2.0","id":"prompt-1","method":"host/requestUserInput","params":{"prompt":"Verification code","echo":true}}\n'
printf '{"jsonrpc":"2.0","id":"prompt-2","method":"host/unknown","params":{}}\n'
IFS= read -r first_answer
IFS= read -r second_answer
printf '{"jsonrpc":"2.0","id":%s,"result":{"first":%s,"second":%s}}\n' "$echo_id" "$first_answer" "$second_answer"
sleep 30
"#,
)
.unwrap();
let mut permissions = std::fs::metadata(&executable).unwrap().permissions();
permissions.set_mode(0o755);
std::fs::set_permissions(&executable, permissions).unwrap();
executable
}
#[cfg(unix)]
async fn questioning_session(dir: &std::path::Path) -> std::sync::Arc<PluginSidecarSession> {
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.to_path_buf(), "0.6.14");
PluginSidecarSession::start(plugin, "0.6.14", PluginRuntimeEnv::default())
.await
.expect("v1 sidecar should initialize")
}
/// The sidecar echoes both answers, and the unknown method answers first, so
/// tests must look responses up by id instead of by position.
#[cfg(unix)]
fn echoed_answer<'a>(echoed: &'a serde_json::Value, id: &str) -> &'a serde_json::Value {
["first", "second"]
.iter()
.map(|slot| &echoed[*slot])
.find(|response| response["id"] == id)
.unwrap_or_else(|| panic!("no answer for {id} in {echoed}"))
}
/// Installs a prompt gateway that records every request it relays and
/// answers after `delay` — the test-visible stand-in for the desktop dialog.
#[cfg(unix)]
fn install_prompt_harness(
delay: Duration,
answer: dbx_platform::ssh_prompt::SshPromptAnswer,
) -> tokio::sync::mpsc::UnboundedReceiver<(
dbx_platform::ssh_prompt::SshPromptRequest,
dbx_platform::ssh_prompt::SshPromptAnswer,
)> {
use dbx_platform::ssh_prompt;
let (tx, mut rx) = tokio::sync::mpsc::channel::<ssh_prompt::SshPromptEnvelope>(4);
ssh_prompt::install_ssh_prompt_gateway(tx);
let (seen_tx, seen_rx) = tokio::sync::mpsc::unbounded_channel();
tokio::spawn(async move {
while let Some(envelope) = rx.recv().await {
let _ = seen_tx.send((envelope.request.clone(), answer.clone()));
tokio::time::sleep(delay).await;
let _ = envelope.responder.send(answer.clone());
}
});
seen_rx
}
/// Installs a prompt gateway that relays requests to the test and never
/// answers, so the test can watch what happens to a prompt nobody answers.
#[cfg(unix)]
fn install_silent_prompt_harness() -> tokio::sync::mpsc::UnboundedReceiver<(
dbx_platform::ssh_prompt::SshPromptRequest,
tokio::sync::oneshot::Sender<dbx_platform::ssh_prompt::SshPromptAnswer>,
)> {
use dbx_platform::ssh_prompt;
let (tx, mut rx) = tokio::sync::mpsc::channel::<ssh_prompt::SshPromptEnvelope>(4);
ssh_prompt::install_ssh_prompt_gateway(tx);
let (seen_tx, seen_rx) = tokio::sync::mpsc::unbounded_channel();
tokio::spawn(async move {
while let Some(envelope) = rx.recv().await {
let _ = seen_tx.send((envelope.request, envelope.responder));
}
});
seen_rx
}
#[cfg(unix)]
#[tokio::test]
async fn fails_plugin_prompts_closed_without_a_prompt_ui() {
use dbx_platform::ssh_prompt;
let _guard = ssh_prompt::prompt_gateway_test_lock().lock().await;
ssh_prompt::clear_ssh_prompt_gateway();
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let echoed: serde_json::Value = session
.invoke("sample/echo", serde_json::Value::Null)
.await
.expect("host should answer every plugin-initiated request");
session.shutdown().await.unwrap();
// A headless host (tests, MCP) must refuse instead of hanging the
// plugin until the prompt timeout expires.
let prompt = echoed_answer(&echoed, "prompt-1");
assert_eq!(prompt["error"]["code"], -32001);
let unknown = echoed_answer(&echoed, "prompt-2");
assert_eq!(unknown["error"]["code"], -32601);
}
#[cfg(unix)]
#[tokio::test]
async fn relays_plugin_user_input_through_the_prompt_gateway() {
use dbx_platform::ssh_prompt::{self, SshPromptAnswer, SshPromptKind};
let _guard = ssh_prompt::prompt_gateway_test_lock().lock().await;
let mut prompts = install_prompt_harness(Duration::ZERO, SshPromptAnswer::Secret("123456".to_string()));
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let echoed: serde_json::Value = session
.invoke("sample/echo", serde_json::Value::Null)
.await
.expect("host should answer every plugin-initiated request");
session.shutdown().await.unwrap();
ssh_prompt::clear_ssh_prompt_gateway();
let prompt = echoed_answer(&echoed, "prompt-1");
assert_eq!(prompt["result"]["action"], "submit");
assert_eq!(prompt["result"]["value"], "123456");
// The host relays the question and the answer, nothing else: the plugin
// asked, the user typed, and the host never synthesizes a value.
let (request, answer) = prompts.recv().await.expect("the host should relay exactly one prompt");
assert_eq!(request.kind, SshPromptKind::UserInput);
assert_eq!(request.source.as_deref(), Some("Sample Sidecar"));
assert_eq!(request.prompt.as_deref(), Some("Verification code"));
assert!(request.echo);
assert_eq!(answer, SshPromptAnswer::Secret("123456".to_string()));
}
#[cfg(unix)]
#[tokio::test]
async fn reports_plugin_user_input_cancel_when_the_user_dismisses_the_prompt() {
use dbx_platform::ssh_prompt::{self, SshPromptAnswer};
let _guard = ssh_prompt::prompt_gateway_test_lock().lock().await;
install_prompt_harness(Duration::ZERO, SshPromptAnswer::Reject);
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let echoed: serde_json::Value = session
.invoke("sample/echo", serde_json::Value::Null)
.await
.expect("host should answer every plugin-initiated request");
session.shutdown().await.unwrap();
ssh_prompt::clear_ssh_prompt_gateway();
let prompt = echoed_answer(&echoed, "prompt-1");
assert_eq!(prompt["result"]["action"], "cancel");
assert!(prompt["result"].get("value").is_none());
}
#[cfg(unix)]
#[tokio::test]
async fn connection_request_timeout_pauses_while_the_user_types() {
use dbx_platform::ssh_prompt::{self, SshPromptAnswer};
let _guard = ssh_prompt::prompt_gateway_test_lock().lock().await;
// The user needs longer than the caller's connect timeout. `connection/
// test` and `connection/connect` share that timeout, so without the
// prompt pause the plugin would answer a request the host had already
// abandoned — exactly the bug this channel exists to avoid.
install_prompt_harness(Duration::from_millis(700), SshPromptAnswer::Secret("123456".to_string()));
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let echoed: serde_json::Value = session
.invoke_with_timeout("sample/echo", serde_json::Value::Null, None, Some(Duration::from_millis(300)))
.await
.expect("a prompt must pause the request deadline instead of failing it");
session.shutdown().await.unwrap();
ssh_prompt::clear_ssh_prompt_gateway();
assert_eq!(echoed_answer(&echoed, "prompt-1")["result"]["value"], "123456");
}
#[cfg(unix)]
#[tokio::test]
async fn stopping_a_plugin_session_releases_its_open_prompt() {
use dbx_platform::ssh_prompt;
let _guard = ssh_prompt::prompt_gateway_test_lock().lock().await;
let mut prompts = install_silent_prompt_harness();
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let caller = {
let session = session.clone();
tokio::spawn(
async move { session.invoke::<serde_json::Value>("sample/echo", serde_json::Value::Null).await },
)
};
let (request, responder) = prompts.recv().await.expect("the plugin should ask before answering");
assert_eq!(request.kind, dbx_platform::ssh_prompt::SshPromptKind::UserInput);
assert!(!responder.is_closed());
session.shutdown().await.unwrap();
ssh_prompt::clear_ssh_prompt_gateway();
// The request fails (the session is gone) and the prompt's responder is
// dropped, which is how the dialog learns to dismiss itself instead of
// waiting for a plugin that will never answer.
let error = tokio::time::timeout(Duration::from_secs(5), async { caller.await.unwrap().unwrap_err() })
.await
.expect("stopping the session must not strand the caller");
assert!(error.contains("stopped") || error.contains("closed"), "{error}");
assert!(responder.is_closed(), "the prompt must be released when the session stops");
}
#[cfg(unix)]
#[tokio::test]
async fn stopping_a_plugin_session_releases_all_open_prompts() {
use dbx_platform::ssh_prompt;
let _guard = ssh_prompt::prompt_gateway_test_lock().lock().await;
let mut prompts = install_silent_prompt_harness();
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let first = session.request_user_input(serde_json::json!({ "prompt": "First code" }));
let second = session.request_user_input(serde_json::json!({ "prompt": "Second code" }));
tokio::pin!(first, second);
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
let (_, first_responder) = prompts.recv().await.unwrap();
let (_, second_responder) = prompts.recv().await.unwrap();
assert!(!first_responder.is_closed());
assert!(!second_responder.is_closed());
assert_eq!(session.prompts.state.borrow().open, 2);
session.shutdown().await.unwrap();
let (first_answer, second_answer) =
tokio::time::timeout(Duration::from_secs(1), async { tokio::join!(first, second) })
.await
.expect("stopping the session must cancel all prompts without waiting for their deadlines");
assert_eq!(first_answer.unwrap(), serde_json::json!({ "action": "cancel" }));
assert_eq!(second_answer.unwrap(), serde_json::json!({ "action": "cancel" }));
assert!(first_responder.is_closed());
assert!(second_responder.is_closed());
assert_eq!(session.prompts.state.borrow().open, 0);
assert_eq!(
session.request_user_input(serde_json::json!({ "prompt": "Too late" })).await.unwrap(),
serde_json::json!({ "action": "cancel" })
);
assert!(prompts.try_recv().is_err());
ssh_prompt::clear_ssh_prompt_gateway();
}
#[cfg(unix)]
#[tokio::test]
async fn concurrent_response_deadlines_pause_and_resume_together() {
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
tokio::time::pause();
let (_first_sender, first_receiver) = tokio::sync::oneshot::channel();
let (_second_sender, second_receiver) = tokio::sync::oneshot::channel();
let first = session.await_response(first_receiver, "sample/first", Duration::from_secs(30));
let second = session.await_response(second_receiver, "sample/second", Duration::from_secs(30));
tokio::pin!(first, second);
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
tokio::time::advance(Duration::from_secs(10)).await;
session.prompts.begin();
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
tokio::time::advance(Duration::from_secs(60)).await;
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
session.prompts.begin();
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
session.prompts.end();
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
tokio::time::advance(Duration::from_secs(60)).await;
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
session.prompts.end();
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
tokio::time::advance(Duration::from_secs(19)).await;
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
tokio::time::advance(Duration::from_secs(1)).await;
let (first_result, second_result) =
tokio::time::timeout(Duration::from_secs(1), async { tokio::join!(first, second) })
.await
.expect("every response deadline must resume when the final prompt ends");
for result in [first_result, second_result] {
assert!(result.unwrap_err().contains("timed out after 30 seconds"));
}
tokio::time::resume();
session.shutdown().await.unwrap();
}
#[cfg(unix)]
#[tokio::test]
async fn concurrent_paused_responses_still_accept_success_and_channel_closure() {
let dir = tempfile::tempdir().unwrap();
write_questioning_sidecar(dir.path());
let session = questioning_session(dir.path()).await;
let (first_sender, first_receiver) = tokio::sync::oneshot::channel();
let (second_sender, second_receiver) = tokio::sync::oneshot::channel();
session.prompts.begin();
let first = session.await_response(first_receiver, "sample/first", Duration::from_secs(30));
let second = session.await_response(second_receiver, "sample/second", Duration::from_secs(30));
tokio::pin!(first, second);
assert_pending(first.as_mut()).await;
assert_pending(second.as_mut()).await;
first_sender.send(Ok(serde_json::json!({ "ok": true }))).unwrap();
drop(second_sender);
assert_eq!(first.await.unwrap(), serde_json::json!({ "ok": true }));
assert!(second.await.unwrap_err().contains("response channel closed"));
session.prompts.end();
session.shutdown().await.unwrap();
}
#[test]
fn maps_user_answers_to_host_request_user_input_results() {
use dbx_platform::ssh_prompt::SshPromptAnswer;
assert_eq!(
user_input_result(SshPromptAnswer::Secret("123456".to_string())),
serde_json::json!({ "action": "submit", "value": "123456" })
);
// Host-key wording and a dismissal are never an answer.
assert_eq!(user_input_result(SshPromptAnswer::Reject), serde_json::json!({ "action": "cancel" }));
assert_eq!(
user_input_result(SshPromptAnswer::Accept { remember: true }),
serde_json::json!({ "action": "cancel" })
);
}
#[test]
fn parses_and_bounds_host_request_user_input_params() {
let spec = UserInputSpec::parse(serde_json::json!({
"prompt": "Verification code",
"title": "Bastion MFA",
"secret": true,
"echo": true,
"default": "000000",
"options": [{ "value": "totp", "label": "TOTP" }],
"timeoutSecs": 90
}))
.unwrap();
assert_eq!(spec.prompt, "Verification code");
assert_eq!(spec.title.as_deref(), Some("Bastion MFA"));
assert_eq!(spec.default_value.as_deref(), Some("000000"));
assert!(spec.echo);
assert_eq!(spec.options.len(), 1);
assert_eq!(spec.options[0].value, "totp");
assert_eq!(spec.timeout, Duration::from_secs(90));
// An option without a label falls back to its value; the host clamps
// timeouts and defaults `echo` to masked input.
let spec = UserInputSpec::parse(serde_json::json!({
"prompt": "Pick one",
"options": [{ "value": "a" }],
"timeoutSecs": 1
}))
.unwrap();
assert_eq!(spec.options[0].label, "a");
assert!(!spec.echo);
assert_eq!(spec.timeout, USER_INPUT_MIN_TIMEOUT);
let spec = UserInputSpec::parse(serde_json::json!({
"prompt": "Pick one",
"timeoutSecs": 100_000
}))
.unwrap();
assert_eq!(spec.timeout, USER_INPUT_MAX_TIMEOUT);
assert_eq!(
UserInputSpec::parse(serde_json::json!({ "prompt": "x" })).unwrap().timeout,
USER_INPUT_DEFAULT_TIMEOUT
);
for invalid in [
serde_json::json!("not-an-object"),
serde_json::json!({}),
serde_json::json!({ "prompt": " " }),
serde_json::json!({ "prompt": "x".repeat(2001) }),
serde_json::json!({ "prompt": "x", "title": 1 }),
serde_json::json!({ "prompt": "x", "echo": "yes" }),
serde_json::json!({ "prompt": "x", "timeoutSecs": -1 }),
serde_json::json!({ "prompt": "x", "options": { "value": "a" } }),
serde_json::json!({ "prompt": "x", "options": [{ "label": "A" }] }),
serde_json::json!({ "prompt": "x", "options": [{ "value": "a" }, { "value": "a" }] }),
serde_json::json!({
"prompt": "x",
"options": (0..USER_INPUT_MAX_OPTIONS + 1).map(|index| serde_json::json!({ "value": index.to_string() })).collect::<Vec<_>>()
}),
] {
let error = UserInputSpec::parse(invalid.clone()).expect_err("params should be rejected");
assert_eq!(error.code, -32602, "unexpected error for {invalid}: {}", error.message);
}
}
#[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.unwrap();
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.unwrap();
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.unwrap();
}
/// The JDBC plugin is a legacy sidecar: started by Java 8 it dies on its
/// first request, and that error must name the Java version as the cause.
#[cfg(unix)]
#[tokio::test]
async fn legacy_runtime_explains_a_java_class_version_failure() {
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
echo 'Exception in thread "main" java.lang.UnsupportedClassVersionError: app/dbx/jdbc/Main has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 52.0' >&2
exit 1
"#,
)
.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");
// The process may already be gone when `start` returns, so either step can fail.
let error = match PluginSidecarSession::start(plugin, "0.5.67", PluginRuntimeEnv::default()).await {
Ok(session) => {
let error = session.invoke::<serde_json::Value>("ping", serde_json::Value::Null).await.unwrap_err();
let _ = session.shutdown().await;
error
}
Err(error) => error,
};
assert!(error.starts_with(PLUGIN_JAVA_TOO_OLD_MESSAGE), "unexpected error: {error}");
assert!(error.contains("UnsupportedClassVersionError"));
}
#[test]
fn stderr_hint_recognizes_java_class_version_failures() {
assert_eq!(
plugin_stderr_hint("java.lang.UnsupportedClassVersionError: app/dbx/jdbc/Main"),
Some(PLUGIN_JAVA_TOO_OLD_MESSAGE)
);
assert_eq!(
plugin_stderr_hint("this version of the Java Runtime only recognizes class file versions up to 52.0"),
Some(PLUGIN_JAVA_TOO_OLD_MESSAGE)
);
assert_eq!(plugin_stderr_hint("java.net.ConnectException: Connection refused"), None);
}
/// A legacy `stdio-jsonl` plugin answers with one line per response, so a whole
/// query page has to fit in that line — there is no binary frame to fall back on
/// the way the framed transport has. A 12 MB page (a wide Oracle/JDBC result)
/// must therefore be read instead of failing the query with
/// "plugin output line is too large".
#[cfg(unix)]
#[tokio::test]
async fn legacy_jsonl_runtime_reads_responses_above_the_json_frame_limit() {
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 '{"id":%s,"result":{"page":"' "$request_id"
head -c 12000000 /dev/zero | tr '\0' 'x'
printf '"}}\n'
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("executeQuery", serde_json::Value::Null)
.await
.expect("a 12 MB legacy JSONL response must be read instead of failing the query");
assert_eq!(result["page"].as_str().map(str::len), Some(12_000_000));
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)
}
}