feat(plugin): add plugin framework workflow

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

No files matched your search

+432
View File
@@ -0,0 +1,432 @@
use std::io::{self, BufRead, BufReader, Read, Write};
use std::sync::{mpsc, Arc, Mutex};
use std::thread;
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;
#[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"));
}
let mut output = self.output.lock().map_err(|_| PluginError::new(-32000, "Plugin output lock is poisoned"))?;
match self.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)
}
}
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 emitter = PluginEmitter { output: Arc::new(Mutex::new(Box::new(io::stdout()))), transport: 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 request: ProtocolRequest = serde_json::from_slice(payload).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")?;
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"));
}
}
fn io_error(error: io::Error) -> PluginError {
PluginError::new(-32000, error.to_string())
}