Skip to content

armgit / dbx

Public Imported from GitHub
0

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。

33.7 KB
Raw Blame
use std::collections::HashMap;
use std::io::{self, BufRead, BufReader, Read, Write};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{mpsc, Arc, Mutex};
use std::thread;
use std::time::Duration;

use serde::{Deserialize, Serialize};
use serde_json::Value;

pub const PROTOCOL_VERSION: u32 = 1;
const MAX_JSON_BYTES: usize = 8 * 1024 * 1024;
const MAX_BINARY_BYTES: usize = 64 * 1024 * 1024;
const FRAME_KIND_JSON: u8 = 0;
const FRAME_KIND_BINARY: u8 = 1;
const DEFAULT_WORK_QUEUE_CAPACITY: usize = 256;
/// How long a plugin waits for a host answer before giving up. User prompts are
/// bounded by their own `timeoutSecs`, so the default covers one prompt plus a
/// little slack.
const DEFAULT_HOST_REQUEST_TIMEOUT: Duration = Duration::from_secs(330);
/// Host API method that relays a question to the DBX user interface.
pub const HOST_REQUEST_USER_INPUT_METHOD: &str = "host/requestUserInput";

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PluginTransport {
    JsonLines,
    Framed,
}

#[derive(Debug, Clone)]
pub struct PluginMetadata {
    pub id: String,
    pub version: String,
    pub capabilities: Vec<String>,
}

impl PluginMetadata {
    pub fn new(id: impl Into<String>, version: impl Into<String>) -> Self {
        Self { id: id.into(), version: version.into(), capabilities: Vec::new() }
    }

    pub fn with_capability(mut self, capability: impl Into<String>) -> Self {
        self.capabilities.push(capability.into());
        self
    }
}

#[derive(Debug, Clone)]
pub struct RequestContext {
    pub request_id: Option<u64>,
    pub driver: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct PluginError {
    pub code: i32,
    pub message: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub data: Option<Value>,
}

impl PluginError {
    pub fn new(code: i32, message: impl Into<String>) -> Self {
        Self { code, message: message.into(), data: None }
    }

    pub fn method_not_found(method: &str) -> Self {
        Self::new(-32601, format!("Method not found: {method}"))
    }
}

pub trait PluginHandler: Send + Sync + 'static {
    fn handle(
        &self,
        context: RequestContext,
        method: &str,
        params: Value,
        emitter: &PluginEmitter,
    ) -> Result<Value, PluginError>;

    fn handle_binary(&self, _channel: &str, _data: Vec<u8>, _emitter: &PluginEmitter) -> Result<(), PluginError> {
        Err(PluginError::new(-32601, "Binary input is not supported"))
    }
}

#[derive(Clone)]
pub struct PluginEmitter {
    output: Arc<Mutex<Box<dyn Write + Send>>>,
    transport: PluginTransport,
}

impl PluginEmitter {
    pub fn event(&self, method: &str, params: Value) -> Result<(), PluginError> {
        validate_protocol_name(method)?;
        self.write_json(&serde_json::json!({
            "jsonrpc": "2.0",
            "method": method,
            "params": params
        }))
    }

    pub fn binary(&self, channel: &str, data: &[u8]) -> Result<(), PluginError> {
        if self.transport != PluginTransport::Framed {
            return Err(PluginError::new(-32000, "Binary messages require framed transport"));
        }
        validate_protocol_name(channel)?;
        if data.len() > MAX_BINARY_BYTES {
            return Err(PluginError::new(-32600, "Binary message is too large"));
        }
        let channel = channel.as_bytes();
        if channel.len() > u16::MAX as usize {
            return Err(PluginError::new(-32600, "Binary channel is too long"));
        }
        let payload_len = 2 + channel.len() + data.len();
        let mut output = self.output.lock().map_err(|_| PluginError::new(-32000, "Plugin output lock is poisoned"))?;
        output.write_all(&[FRAME_KIND_BINARY]).map_err(io_error)?;
        output.write_all(&(payload_len as u32).to_be_bytes()).map_err(io_error)?;
        output.write_all(&(channel.len() as u16).to_be_bytes()).map_err(io_error)?;
        output.write_all(channel).map_err(io_error)?;
        output.write_all(data).map_err(io_error)?;
        output.flush().map_err(io_error)
    }

    fn respond(&self, id: u64, result: Result<Value, PluginError>) -> Result<(), PluginError> {
        match result {
            Ok(result) => self.write_json(&serde_json::json!({ "jsonrpc": "2.0", "id": id, "result": result })),
            Err(error) => self.write_json(&serde_json::json!({ "jsonrpc": "2.0", "id": id, "error": error })),
        }
    }

    fn write_json(&self, value: &Value) -> Result<(), PluginError> {
        let payload = serde_json::to_vec(value).map_err(|error| PluginError::new(-32603, error.to_string()))?;
        if payload.len() > MAX_JSON_BYTES {
            return Err(PluginError::new(-32600, "JSON message is too large"));
        }
        write_json_frame(&self.output, self.transport, &payload)
    }
}

fn write_json_frame(
    output: &Arc<Mutex<Box<dyn Write + Send>>>,
    transport: PluginTransport,
    payload: &[u8],
) -> Result<(), PluginError> {
    let mut output = output.lock().map_err(|_| PluginError::new(-32000, "Plugin output lock is poisoned"))?;
    match transport {
        PluginTransport::JsonLines => {
            output.write_all(payload).map_err(io_error)?;
            output.write_all(b"\n").map_err(io_error)?;
        }
        PluginTransport::Framed => {
            output.write_all(&[FRAME_KIND_JSON]).map_err(io_error)?;
            output.write_all(&(payload.len() as u32).to_be_bytes()).map_err(io_error)?;
            output.write_all(payload).map_err(io_error)?;
        }
    }
    output.flush().map_err(io_error)
}

/// A question the plugin asks the user through the host, e.g. a bastion's
/// keyboard-interactive MFA challenge or a host-key confirmation. Serializes
/// into the `host/requestUserInput` params of Host API 1.1.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UserInputPrompt {
    /// Text the user answers, already localized by the plugin.
    pub prompt: String,
    /// Optional heading shown above `prompt`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// Show the typed characters (defaults to masked input).
    #[serde(default)]
    pub echo: bool,
    /// Preset answer the user may keep or replace.
    #[serde(rename = "default", skip_serializing_if = "Option::is_none")]
    pub default_value: Option<String>,
    /// Fixed answers; leave empty for free-form input (at most 8).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub options: Vec<UserInputOption>,
    /// How long the user has to answer, in seconds (host clamps to 5..600).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timeout_secs: Option<u64>,
}

/// One fixed answer of a [`UserInputPrompt`].
#[derive(Debug, Clone, Serialize)]
pub struct UserInputOption {
    pub value: String,
    pub label: String,
}

impl UserInputPrompt {
    /// A masked free-form question (verification codes, passwords, tokens).
    pub fn secret(prompt: impl Into<String>) -> Self {
        Self { prompt: prompt.into(), title: None, echo: false, default_value: None, options: Vec::new(), timeout_secs: None }
    }

    /// A question whose answer is visible while typing (account names, paths).
    pub fn text(prompt: impl Into<String>) -> Self {
        Self { echo: true, ..Self::secret(prompt) }
    }

    /// A multiple-choice question; the host shows the options as buttons.
    pub fn choice(prompt: impl Into<String>, options: Vec<UserInputOption>) -> Self {
        Self { options, ..Self::text(prompt) }
    }

    pub fn with_title(mut self, title: impl Into<String>) -> Self {
        self.title = Some(title.into());
        self
    }

    pub fn with_default(mut self, value: impl Into<String>) -> Self {
        self.default_value = Some(value.into());
        self
    }

    pub fn with_timeout_secs(mut self, seconds: u64) -> Self {
        self.timeout_secs = Some(seconds);
        self
    }
}

/// The user's answer to a [`UserInputPrompt`].
#[derive(Debug, Clone, Deserialize)]
pub struct UserInputAnswer {
    /// `submit`, `cancel`, or `timeout`.
    pub action: String,
    /// The typed value or chosen option value; only present on `submit`.
    #[serde(default)]
    pub value: Option<String>,
}

impl UserInputAnswer {
    /// The submitted value, or `None` when the user cancelled and the host gave
    /// up waiting. Callers must fail closed on `None`.
    pub fn submitted(&self) -> Option<&str> {
        if self.action == "submit" {
            self.value.as_deref()
        } else {
            None
        }
    }

    pub fn is_cancelled(&self) -> bool {
        self.action == "cancel"
    }

    pub fn is_timeout(&self) -> bool {
        self.action == "timeout"
    }
}

/// What the host told the plugin about itself at `plugin/initialize`.
#[derive(Debug, Default, Clone)]
struct HostDescription {
    api_version: Option<String>,
    features: Vec<String>,
}

/// Client for Host API methods the plugin calls back into DBX. Create it by
/// running a [`PluginServer`]; [`host_client`] returns the running instance.
///
/// Calls block the calling thread until the host answers, so call them from a
/// plugin worker (a `connection/connect` handler is already one) rather than
/// from the thread that runs the server loop. While a user prompt is open the
/// host pauses the deadline of the request that is waiting on it, so a human
/// typing an MFA code is never mistaken for a connect timeout.
#[derive(Clone)]
pub struct HostClient {
    output: Arc<Mutex<Box<dyn Write + Send>>>,
    transport: PluginTransport,
    pending: Arc<Mutex<HashMap<String, mpsc::Sender<Result<Value, PluginError>>>>>,
    next_request_id: Arc<AtomicU64>,
    host: Arc<Mutex<HostDescription>>,
}

impl HostClient {
    fn new(output: Arc<Mutex<Box<dyn Write + Send>>>, transport: PluginTransport) -> Self {
        Self {
            output,
            transport,
            pending: Arc::new(Mutex::new(HashMap::new())),
            next_request_id: Arc::new(AtomicU64::new(1)),
            host: Arc::new(Mutex::new(HostDescription::default())),
        }
    }

    /// Host API version DBX reported at `plugin/initialize`.
    pub fn host_api_version(&self) -> Option<String> {
        self.host.lock().ok().and_then(|host| host.api_version.clone())
    }

    /// Whether DBX advertised `method` for this session. Gate optional calls on
    /// this (or on [`HostClient::host_api_version`]) so a plugin still works
    /// against an older host that predates the capability.
    pub fn supports(&self, method: &str) -> bool {
        self.host.lock().map(|host| host.features.iter().any(|feature| feature == method)).unwrap_or(false)
    }

    /// Calls one Host API method and waits for the answer.
    pub fn request(&self, method: &str, params: Value) -> Result<Value, PluginError> {
        self.request_with_timeout(method, params, DEFAULT_HOST_REQUEST_TIMEOUT)
    }

    pub fn request_with_timeout(
        &self,
        method: &str,
        params: Value,
        timeout: Duration,
    ) -> Result<Value, PluginError> {
        validate_protocol_name(method)?;
        let id = format!("plugin-{}", self.next_request_id.fetch_add(1, Ordering::Relaxed));
        let (sender, receiver) = mpsc::channel();
        self.pending
            .lock()
            .map_err(|_| PluginError::new(-32000, "Host request lock is poisoned"))?
            .insert(id.clone(), sender);
        let message = serde_json::json!({
            "jsonrpc": "2.0",
            "id": id,
            "method": method,
            "params": params,
        });
        if let Err(error) = self.write(&message) {
            if let Ok(mut pending) = self.pending.lock() {
                pending.remove(&id);
            }
            return Err(error);
        }
        match receiver.recv_timeout(timeout) {
            Ok(result) => result,
            Err(mpsc::RecvTimeoutError::Timeout) => {
                if let Ok(mut pending) = self.pending.lock() {
                    pending.remove(&id);
                }
                Err(PluginError::new(-32001, format!("Host did not answer '{method}' in time")))
            }
            Err(mpsc::RecvTimeoutError::Disconnected) => {
                Err(PluginError::new(-32000, format!("Host dropped the answer to '{method}'")))
            }
        }
    }

    /// Asks the user a question through the DBX UI. Fails when the host has no
    /// user interface attached (headless/MCP runs), so the plugin can fall back
    /// to its own behaviour instead of waiting for an answer that cannot come.
    pub fn request_user_input(&self, prompt: &UserInputPrompt) -> Result<UserInputAnswer, PluginError> {
        let params = serde_json::to_value(prompt).map_err(|error| PluginError::new(-32603, error.to_string()))?;
        let answer = self.request(HOST_REQUEST_USER_INPUT_METHOD, params)?;
        serde_json::from_value(answer)
            .map_err(|error| PluginError::new(-32002, format!("Host returned an invalid input answer: {error}")))
    }

    fn write(&self, value: &Value) -> Result<(), PluginError> {
        let payload = serde_json::to_vec(value).map_err(|error| PluginError::new(-32603, error.to_string()))?;
        if payload.len() > MAX_JSON_BYTES {
            return Err(PluginError::new(-32600, "JSON message is too large"));
        }
        write_json_frame(&self.output, self.transport, &payload)
    }

    /// Remembers what the host advertised at `plugin/initialize`.
    fn note_host_description(&self, params: &Value) {
        let host = params.get("host");
        let api_version = host
            .and_then(|host| host.get("hostApiVersion"))
            .and_then(Value::as_str)
            .map(str::to_string);
        let features = host
            .and_then(|host| host.get("features"))
            .and_then(Value::as_array)
            .map(|features| features.iter().filter_map(Value::as_str).map(str::to_string).collect())
            .unwrap_or_default();
        if let Ok(mut description) = self.host.lock() {
            *description = HostDescription { api_version, features };
        }
    }

    /// Routes an answer from the host to the waiting caller. Returns `false`
    /// when the message is not a response to a plugin-initiated request, so the
    /// server loop can keep handling host -> plugin requests.
    fn deliver_response(&self, value: &Value) -> bool {
        if value.get("method").is_some() {
            return false;
        }
        let Some(id) = value.get("id").and_then(Value::as_str) else {
            return false;
        };
        let Some(sender) = self.pending.lock().ok().and_then(|mut pending| pending.remove(id)) else {
            return false;
        };
        let result = match value.get("error") {
            Some(error) => {
                let code = error.get("code").and_then(Value::as_i64).unwrap_or(-32603) as i32;
                let message = error
                    .get("message")
                    .and_then(Value::as_str)
                    .map(str::to_string)
                    .unwrap_or_else(|| error.to_string());
                Err(PluginError::new(code, message))
            }
            None => match value.get("result") {
                Some(result) => Ok(result.clone()),
                None => Err(PluginError::new(-32603, "Host answer has neither result nor error")),
            },
        };
        let _ = sender.send(result);
        true
    }
}

static HOST_CLIENT: Mutex<Option<HostClient>> = Mutex::new(None);

/// The host client of the running plugin server, if any.
pub fn host_client() -> Option<HostClient> {
    HOST_CLIENT.lock().ok().and_then(|client| client.clone())
}

/// Installs the process-wide host client. [`PluginServer::serve`] calls this;
/// tests may replace it.
pub fn install_host_client(client: HostClient) {
    if let Ok(mut current) = HOST_CLIENT.lock() {
        *current = Some(client);
    }
}

/// Convenience wrapper for [`HostClient::request_user_input`] on the running
/// server. Fails when the plugin server is not running.
pub fn request_user_input(prompt: &UserInputPrompt) -> Result<UserInputAnswer, PluginError> {
    let Some(client) = host_client() else {
        return Err(PluginError::new(-32000, "Host API is unavailable: the plugin server is not running"));
    };
    client.request_user_input(prompt)
}

pub struct PluginServer<H> {
    metadata: PluginMetadata,
    handler: Arc<H>,
    transport: PluginTransport,
    worker_threads: usize,
    work_queue_capacity: usize,
}

impl<H: PluginHandler> PluginServer<H> {
    pub fn new(metadata: PluginMetadata, handler: H) -> Self {
        Self {
            metadata,
            handler: Arc::new(handler),
            transport: PluginTransport::JsonLines,
            worker_threads: default_worker_threads(),
            work_queue_capacity: DEFAULT_WORK_QUEUE_CAPACITY,
        }
    }

    pub fn transport(mut self, transport: PluginTransport) -> Self {
        self.transport = transport;
        self
    }

    pub fn worker_threads(mut self, worker_threads: usize) -> Self {
        self.worker_threads = worker_threads.max(1);
        self
    }

    pub fn work_queue_capacity(mut self, work_queue_capacity: usize) -> Self {
        self.work_queue_capacity = work_queue_capacity.max(1);
        self
    }

    pub fn serve(self) -> io::Result<()> {
        let output: Arc<Mutex<Box<dyn Write + Send>>> = Arc::new(Mutex::new(Box::new(io::stdout())));
        let emitter = PluginEmitter { output: output.clone(), transport: self.transport };
        // Publish the client before serving so a handler (including the very
        // first request) can call back into the host.
        install_host_client(HostClient::new(output, self.transport));
        let workers = WorkerPool::new(self.worker_threads, self.work_queue_capacity)?;
        match self.transport {
            PluginTransport::JsonLines => self.serve_json_lines(BufReader::new(io::stdin()), emitter, &workers),
            PluginTransport::Framed => self.serve_framed(io::stdin(), emitter, &workers),
        }
    }

    fn serve_json_lines<R: BufRead>(
        &self,
        mut input: R,
        emitter: PluginEmitter,
        workers: &WorkerPool,
    ) -> io::Result<()> {
        loop {
            let Some(line) = read_limited_line(&mut input, MAX_JSON_BYTES)? else {
                return Ok(());
            };
            if line.iter().all(u8::is_ascii_whitespace) {
                continue;
            }
            if let Err(error) = self.dispatch_json(&line, emitter.clone(), workers) {
                eprintln!("[dbx-plugin-sdk] {error}");
            }
        }
    }

    fn serve_framed<R: Read>(&self, mut input: R, emitter: PluginEmitter, workers: &WorkerPool) -> io::Result<()> {
        loop {
            let mut header = [0u8; 5];
            match input.read_exact(&mut header) {
                Ok(()) => {}
                Err(error) if error.kind() == io::ErrorKind::UnexpectedEof => return Ok(()),
                Err(error) => return Err(error),
            }
            let kind = header[0];
            let length = u32::from_be_bytes(header[1..5].try_into().unwrap()) as usize;
            let maximum = if kind == FRAME_KIND_JSON { MAX_JSON_BYTES } else { MAX_BINARY_BYTES + 1024 };
            if length > maximum {
                return Err(io::Error::new(io::ErrorKind::InvalidData, "plugin frame is too large"));
            }
            let mut payload = vec![0; length];
            input.read_exact(&mut payload)?;
            match kind {
                FRAME_KIND_JSON => {
                    if let Err(error) = self.dispatch_json(&payload, emitter.clone(), workers) {
                        eprintln!("[dbx-plugin-sdk] {error}");
                    }
                }
                FRAME_KIND_BINARY => {
                    if let Err(error) = self.dispatch_binary(payload, emitter.clone(), workers) {
                        eprintln!("[dbx-plugin-sdk] {error}");
                    }
                }
                _ => return Err(io::Error::new(io::ErrorKind::InvalidData, "unknown plugin frame kind")),
            }
        }
    }

    fn dispatch_json(&self, payload: &[u8], emitter: PluginEmitter, workers: &WorkerPool) -> Result<(), String> {
        let value: Value = serde_json::from_slice(payload).map_err(|error| error.to_string())?;
        // Answers to Host API calls the plugin made (string ids). Everything
        // else is a host -> plugin request, whose ids are numeric.
        if let Some(host) = host_client() {
            if host.deliver_response(&value) {
                return Ok(());
            }
        }
        let request: ProtocolRequest = serde_json::from_value(value).map_err(|error| error.to_string())?;
        if request.jsonrpc.as_deref() != Some("2.0") {
            return Err("request does not declare jsonrpc 2.0".to_string());
        }
        validate_protocol_name(&request.method).map_err(|error| error.message)?;
        if request.method == "plugin/initialize" {
            let id = request.id.ok_or("plugin/initialize must be a request")?;
            if let Some(host) = host_client() {
                host.note_host_description(&request.params);
            }
            let supported = request
                .params
                .get("host")
                .and_then(|host| host.get("protocolVersions"))
                .and_then(Value::as_array)
                .is_some_and(|versions| {
                    versions.iter().any(|version| version.as_u64() == Some(PROTOCOL_VERSION as u64))
                });
            let result = if supported {
                Ok(serde_json::json!({
                    "protocolVersion": PROTOCOL_VERSION,
                    "capabilities": self.metadata.capabilities,
                    "plugin": { "id": self.metadata.id, "version": self.metadata.version }
                }))
            } else {
                Err(PluginError::new(-32001, "DBX and plugin do not share a protocol version"))
            };
            return emitter.respond(id, result).map_err(|error| error.message);
        }

        let handler = self.handler.clone();
        workers.submit(move || {
            let context = RequestContext { request_id: request.id, driver: request.driver };
            let result = handler.handle(context, &request.method, request.params, &emitter);
            if let Some(id) = request.id {
                if let Err(error) = emitter.respond(id, result) {
                    eprintln!("[dbx-plugin-sdk] failed to write response: {}", error.message);
                }
            }
        })
    }

    fn dispatch_binary(&self, payload: Vec<u8>, emitter: PluginEmitter, workers: &WorkerPool) -> Result<(), String> {
        if payload.len() < 2 {
            return Err("invalid binary frame".to_string());
        }
        let channel_len = u16::from_be_bytes([payload[0], payload[1]]) as usize;
        if channel_len == 0 || payload.len() < 2 + channel_len {
            return Err("invalid binary channel".to_string());
        }
        let channel = std::str::from_utf8(&payload[2..2 + channel_len])
            .map_err(|_| "binary channel is not UTF-8".to_string())?
            .to_string();
        validate_protocol_name(&channel).map_err(|error| error.message)?;
        let data = payload[2 + channel_len..].to_vec();
        let handler = self.handler.clone();
        workers.submit(move || {
            if let Err(error) = handler.handle_binary(&channel, data, &emitter) {
                eprintln!("[dbx-plugin-sdk] binary handler failed: {}", error.message);
            }
        })
    }
}

#[derive(Debug, Deserialize)]
struct ProtocolRequest {
    jsonrpc: Option<String>,
    #[serde(default)]
    id: Option<u64>,
    #[serde(default)]
    driver: Option<String>,
    method: String,
    #[serde(default)]
    params: Value,
}

type PluginJob = Box<dyn FnOnce() + Send + 'static>;

struct WorkerPool {
    sender: mpsc::SyncSender<PluginJob>,
}

impl WorkerPool {
    fn new(worker_threads: usize, queue_capacity: usize) -> io::Result<Self> {
        let (sender, receiver) = mpsc::sync_channel::<PluginJob>(queue_capacity);
        let receiver = Arc::new(Mutex::new(receiver));
        for index in 0..worker_threads {
            let receiver = receiver.clone();
            thread::Builder::new().name(format!("dbx-plugin-worker-{index}")).spawn(move || loop {
                let job = match receiver.lock() {
                    Ok(receiver) => receiver.recv(),
                    Err(_) => return,
                };
                match job {
                    Ok(job) => job(),
                    Err(_) => return,
                }
            })?;
        }
        Ok(Self { sender })
    }

    fn submit(&self, job: impl FnOnce() + Send + 'static) -> Result<(), String> {
        self.sender.send(Box::new(job)).map_err(|_| "plugin worker pool is unavailable".to_string())
    }
}

fn default_worker_threads() -> usize {
    thread::available_parallelism().map(usize::from).unwrap_or(4).clamp(2, 16)
}

fn read_limited_line<R: BufRead>(reader: &mut R, maximum: usize) -> io::Result<Option<Vec<u8>>> {
    let mut output = Vec::new();
    loop {
        let available = reader.fill_buf()?;
        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(io::Error::new(io::ErrorKind::InvalidData, "plugin JSON line is too large"));
        }
        output.extend_from_slice(&available[..take]);
        reader.consume(take);
        if output.last() == Some(&b'\n') {
            return Ok(Some(output));
        }
    }
}

fn validate_protocol_name(value: &str) -> Result<(), PluginError> {
    if value.is_empty() || value.len() > 256 || value.chars().any(char::is_whitespace) {
        return Err(PluginError::new(-32600, "Protocol name is invalid"));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use std::io::Cursor;
    use std::sync::mpsc;
    use std::time::Duration;

    use super::{
        read_limited_line, PluginError, PluginHandler, PluginMetadata, PluginServer, RequestContext, WorkerPool,
    };
    use crate::PluginEmitter;
    use serde_json::Value;

    struct NoopHandler;

    impl PluginHandler for NoopHandler {
        fn handle(
            &self,
            _context: RequestContext,
            method: &str,
            _params: Value,
            _emitter: &PluginEmitter,
        ) -> Result<Value, PluginError> {
            Err(PluginError::method_not_found(method))
        }
    }

    #[test]
    fn worker_pool_executes_queued_jobs() {
        let pool = WorkerPool::new(2, 4).unwrap();
        let (sender, receiver) = mpsc::channel();
        for value in 0..4 {
            let sender = sender.clone();
            pool.submit(move || sender.send(value).unwrap()).unwrap();
        }
        drop(sender);

        let mut values = (0..4).map(|_| receiver.recv_timeout(Duration::from_secs(1)).unwrap()).collect::<Vec<_>>();
        values.sort_unstable();
        assert_eq!(values, vec![0, 1, 2, 3]);
    }

    #[test]
    fn server_configuration_clamps_zero_worker_values() {
        let server = PluginServer::new(PluginMetadata::new("sample", "1.0.0"), NoopHandler)
            .worker_threads(0)
            .work_queue_capacity(0);

        assert_eq!(server.worker_threads, 1);
        assert_eq!(server.work_queue_capacity, 1);
    }

    #[test]
    fn limited_line_reader_rejects_oversized_messages() {
        let mut reader = Cursor::new(b"12345\n".to_vec());
        assert!(read_limited_line(&mut reader, 4).unwrap_err().to_string().contains("too large"));
    }

    use super::{
        host_client, install_host_client, request_user_input, HostClient, PluginTransport, UserInputAnswer,
        UserInputOption, UserInputPrompt, HOST_CLIENT, HOST_REQUEST_USER_INPUT_METHOD,
    };
    use std::thread;
    use std::sync::{Arc, Mutex};

    /// Output sink that records every frame the plugin writes.
    #[derive(Clone, Default)]
    struct RecordingOutput(Arc<Mutex<Vec<u8>>>);

    impl RecordingOutput {
        fn lines(&self) -> Vec<Value> {
            let bytes = self.0.lock().unwrap().clone();
            String::from_utf8(bytes)
                .unwrap()
                .lines()
                .filter(|line| !line.trim().is_empty())
                .map(|line| serde_json::from_str(line).unwrap())
                .collect()
        }
    }

    impl std::io::Write for RecordingOutput {
        fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
            self.0.lock().unwrap().extend_from_slice(buffer);
            Ok(buffer.len())
        }

        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    fn recording_client() -> (HostClient, RecordingOutput) {
        let output = RecordingOutput::default();
        let sink: Arc<Mutex<Box<dyn std::io::Write + Send>>> = Arc::new(Mutex::new(Box::new(output.clone())));
        let client = HostClient::new(sink, PluginTransport::JsonLines);
        install_host_client(client.clone());
        (client, output)
    }

    #[test]
    fn host_client_routes_answers_and_gates_on_advertised_features() {
        let (client, output) = recording_client();
        assert!(!client.supports(HOST_REQUEST_USER_INPUT_METHOD));
        assert_eq!(client.host_api_version(), None);

        client.note_host_description(&serde_json::json!({
            "host": { "hostApiVersion": "1.1.0", "features": [HOST_REQUEST_USER_INPUT_METHOD] }
        }));
        assert_eq!(client.host_api_version().as_deref(), Some("1.1.0"));
        assert!(client.supports(HOST_REQUEST_USER_INPUT_METHOD));

        let prompt = UserInputPrompt::secret("Verification code")
            .with_title("Bastion MFA")
            .with_default("000000")
            .with_timeout_secs(120);
        let caller = {
            let client = client.clone();
            thread::spawn(move || client.request_user_input(&prompt))
        };

        // Simulate the host answering the outbound request.
        let request = loop {
            if let Some(request) = output
                .lines()
                .into_iter()
                .find(|line| line["method"] == HOST_REQUEST_USER_INPUT_METHOD)
            {
                break request;
            }
            thread::sleep(Duration::from_millis(5));
        };
        assert_eq!(request["params"]["prompt"], "Verification code");
        assert_eq!(request["params"]["title"], "Bastion MFA");
        assert_eq!(request["params"]["default"], "000000");
        assert_eq!(request["params"]["timeoutSecs"], 120);
        assert_eq!(request["params"]["echo"], false);
        assert!(request["params"].get("options").is_none());

        assert!(client.deliver_response(&serde_json::json!({
            "jsonrpc": "2.0",
            "id": request["id"],
            "result": { "action": "submit", "value": "123456" }
        })));
        // Host -> plugin requests and unknown answers stay on the server path.
        assert!(!client.deliver_response(&serde_json::json!({ "jsonrpc": "2.0", "id": 1, "method": "connection/test" })));
        assert!(!client.deliver_response(&serde_json::json!({ "jsonrpc": "2.0", "id": "plugin-999", "result": {} })));

        let answer = caller.join().unwrap().unwrap();
        assert_eq!(answer.submitted(), Some("123456"));
        assert!(!answer.is_cancelled());
    }

    #[test]
    fn host_client_surfaces_host_errors_cancels_and_timeouts() {
        let (client, output) = recording_client();

        let error_call = {
            let client = client.clone();
            thread::spawn(move || client.request_user_input(&UserInputPrompt::text("Account")))
        };
        let request = loop {
            if let Some(request) = output.lines().into_iter().find(|line| line["method"] == HOST_REQUEST_USER_INPUT_METHOD) {
                break request;
            }
            thread::sleep(Duration::from_millis(5));
        };
        assert!(client.deliver_response(&serde_json::json!({
            "jsonrpc": "2.0",
            "id": request["id"],
            "error": { "code": -32001, "message": "The DBX host cannot ask the user for input right now" }
        })));
        let error = error_call.join().unwrap().unwrap_err();
        assert_eq!(error.code, -32001);
        assert!(error.message.contains("cannot ask the user"));

        // A cancel carries no value, so callers fail closed.
        let cancel = UserInputAnswer { action: "cancel".to_string(), value: None };
        assert_eq!(cancel.submitted(), None);
        assert!(cancel.is_cancelled());
        let timeout = UserInputAnswer { action: "timeout".to_string(), value: Some("ignored".to_string()) };
        assert_eq!(timeout.submitted(), None);
        assert!(timeout.is_timeout());

        let timed_out = client
            .request_with_timeout("host/requestUserInput", serde_json::json!({ "prompt": "x" }), Duration::from_millis(30))
            .unwrap_err();
        assert!(timed_out.message.contains("did not answer"), "{}", timed_out.message);
    }

    #[test]
    fn user_input_prompt_builders_match_the_host_contract() {
        assert_eq!(
            serde_json::to_value(UserInputPrompt::secret("Code")).unwrap(),
            serde_json::json!({ "prompt": "Code", "echo": false })
        );
        assert_eq!(
            serde_json::to_value(UserInputPrompt::choice(
                "Account",
                vec![UserInputOption { value: "deploy".to_string(), label: "deploy".to_string() }]
            ))
            .unwrap(),
            serde_json::json!({
                "prompt": "Account",
                "echo": true,
                "options": [{ "value": "deploy", "label": "deploy" }]
            })
        );
        // The convenience wrapper needs a running server to talk to.
        HOST_CLIENT.lock().unwrap().take();
        assert!(request_user_input(&UserInputPrompt::secret("Code")).is_err());
        assert!(host_client().is_none());
    }
}

fn io_error(error: io::Error) -> PluginError {
    PluginError::new(-32000, error.to_string())
}