@dbx-app/plugin-cli 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @dbx-app/plugin-cli
+
+Precompiled `dbx-plugin` CLI for creating and packaging DBX plugins. Installing this package does not compile the CLI and does not require a DBX source checkout.
+
+```bash
+npm install --global @dbx-app/plugin-cli
+dbx-plugin create my-plugin
+```
+
+Or run it without a global installation:
+
+```bash
+npx @dbx-app/plugin-cli create my-plugin
+```
+
+The package selects a precompiled binary for macOS, Linux, or Windows and bundles the matching Rust and Go DBX plugin SDK sources. Frontend-only plugins require only Node.js. Rust and Go are needed only when the plugin itself has a Rust or Go backend.
+
+```bash
+dbx-plugin create my-plugin --template frontend
+dbx-plugin create my-rust-plugin --template rust
+dbx-plugin create my-go-plugin --template go
+dbx-plugin package my-plugin
+```
+
+## 中文说明
+
+`@dbx-app/plugin-cli` 提供预编译的 `dbx-plugin` 命令。安装时不会编译 CLI，也不需要克隆 DBX 源码仓库。
+
+```bash
+npm install -g @dbx-app/plugin-cli
+dbx-plugin create my-plugin
+```
+
+也可以直接使用：
+
+```bash
+npx @dbx-app/plugin-cli create my-plugin
+```
+
+npm 主包会自动选择当前操作系统对应的预编译二进制，并携带匹配版本的 Rust 和 Go 插件 SDK。纯前端插件只需要 Node.js；只有插件自身包含 Rust 或 Go 后端时才需要对应语言的编译环境。

package/bin/dbx-plugin.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const platformPackages = {
+  "darwin-arm64": ["@dbx-app/plugin-cli-darwin-arm64", "dbx-plugin"],
+  "darwin-x64": ["@dbx-app/plugin-cli-darwin-x64", "dbx-plugin"],
+  "linux-arm64": ["@dbx-app/plugin-cli-linux-arm64-gnu", "dbx-plugin"],
+  "linux-x64": ["@dbx-app/plugin-cli-linux-x64-gnu", "dbx-plugin"],
+  "win32-arm64": ["@dbx-app/plugin-cli-win32-arm64", "dbx-plugin.exe"],
+  "win32-x64": ["@dbx-app/plugin-cli-win32-x64", "dbx-plugin.exe"],
+};
+
+function platformTarget() {
+  const platform = `${process.platform}-${process.arch}`;
+  const target = platformPackages[platform];
+  if (!target) {
+    throw new Error(`DBX Plugin CLI does not provide a binary for ${platform}.`);
+  }
+  return target;
+}
+
+function resolveBinary() {
+  if (process.env.DBX_PLUGIN_CLI_BINARY) {
+    if (!existsSync(process.env.DBX_PLUGIN_CLI_BINARY)) {
+      throw new Error(`DBX_PLUGIN_CLI_BINARY does not exist: ${process.env.DBX_PLUGIN_CLI_BINARY}`);
+    }
+    return process.env.DBX_PLUGIN_CLI_BINARY;
+  }
+
+  const [packageName, binaryName] = platformTarget();
+  let manifest;
+  try {
+    manifest = require.resolve(`${packageName}/package.json`);
+  } catch {
+    throw new Error(
+      `The optional package ${packageName} was not installed. Reinstall @dbx-app/plugin-cli without --no-optional.`,
+    );
+  }
+
+  const binary = join(dirname(manifest), "bin", binaryName);
+  if (!existsSync(binary)) {
+    throw new Error(`The DBX Plugin CLI binary is missing from ${packageName}.`);
+  }
+  return binary;
+}
+
+function bundledSdkRoot() {
+  const sdkRoot = join(packageRoot, "sdk-root");
+  const rustManifest = join(sdkRoot, "plugins", "sdk", "rust", "dbx-plugin-sdk", "Cargo.toml");
+  const goManifest = join(sdkRoot, "plugins", "sdk", "go", "dbx-plugin-sdk", "go.mod");
+  return existsSync(rustManifest) && existsSync(goManifest) ? sdkRoot : undefined;
+}
+
+try {
+  if (process.argv[2] === "--verify-platform") {
+    platformTarget();
+    process.exit(0);
+  }
+
+  const binary = resolveBinary();
+  const env = { ...process.env };
+  delete env.DBX_PLUGIN_CLI_BINARY;
+  if (!env.DBX_PLUGIN_SDK_ROOT) {
+    const sdkRoot = bundledSdkRoot();
+    if (sdkRoot) env.DBX_PLUGIN_SDK_ROOT = sdkRoot;
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit", env });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+  process.exit(result.status ?? 1);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dbx-app/plugin-cli",
+  "version": "0.1.0",
+  "description": "Create and package DBX plugins without compiling the DBX plugin CLI",
+  "keywords": [
+    "cli",
+    "database",
+    "dbx",
+    "plugin",
+    "plugin-development"
+  ],
+  "homepage": "https://github.com/t8y2/dbx/tree/main/plugins",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/t8y2/dbx",
+    "directory": "packages/plugin-cli"
+  },
+  "bin": {
+    "dbx-plugin": "bin/dbx-plugin.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "sdk-root"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "node --check bin/dbx-plugin.js && node --check scripts/stage-sdk.mjs",
+    "test": "node --test tests/*.test.mjs",
+    "prepack": "node scripts/stage-sdk.mjs",
+    "postpack": "node scripts/stage-sdk.mjs --clean",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "optionalDependencies": {
+    "@dbx-app/plugin-cli-darwin-arm64": "0.1.0",
+    "@dbx-app/plugin-cli-darwin-x64": "0.1.0",
+    "@dbx-app/plugin-cli-linux-arm64-gnu": "0.1.0",
+    "@dbx-app/plugin-cli-linux-x64-gnu": "0.1.0",
+    "@dbx-app/plugin-cli-win32-arm64": "0.1.0",
+    "@dbx-app/plugin-cli-win32-x64": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  }
+}

package/sdk-root/README.md

@@ -0,0 +1,3 @@
+# Bundled DBX Plugin SDK
+
+This directory is bundled for `dbx-plugin package` and is managed by `@dbx-app/plugin-cli`.

package/sdk-root/plugins/sdk/go/dbx-plugin-sdk/README.md

@@ -0,0 +1,17 @@
+# DBX Go plugin SDK
+
+Go SDK for DBX native sidecar plugins using protocol v1 over JSON Lines stdin/stdout.
+
+```go
+metadata := dbxpluginsdk.Metadata{
+    ID: "vendor.example",
+    Version: "1.0.0",
+    Capabilities: []string{"events"},
+}
+server := dbxpluginsdk.NewServer(metadata, handler)
+if err := server.Serve(); err != nil {
+    log.Fatal(err)
+}
+```
+
+Keep stdout reserved for protocol messages. Write diagnostics to stderr.

package/sdk-root/plugins/sdk/go/dbx-plugin-sdk/go.mod

@@ -0,0 +1,3 @@
+module github.com/t8y2/dbx/plugins/sdk/go/dbx-plugin-sdk
+
+go 1.22

package/sdk-root/plugins/sdk/go/dbx-plugin-sdk/sdk.go

@@ -0,0 +1,244 @@
+package dbxpluginsdk
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"sync"
+)
+
+const ProtocolVersion = 1
+
+const maxJSONBytes = 8 * 1024 * 1024
+
+type Metadata struct {
+	ID           string
+	Version      string
+	Capabilities []string
+}
+
+type RequestContext struct {
+	RequestID json.RawMessage
+	Driver    string
+}
+
+type PluginError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    any    `json:"data,omitempty"`
+}
+
+func NewError(code int, message string) *PluginError {
+	return &PluginError{Code: code, Message: message}
+}
+
+func MethodNotFound(method string) *PluginError {
+	return NewError(-32601, fmt.Sprintf("Method not found: %s", method))
+}
+
+type Handler interface {
+	Handle(context RequestContext, method string, params json.RawMessage, emitter *Emitter) (any, *PluginError)
+}
+
+type HandlerFunc func(context RequestContext, method string, params json.RawMessage, emitter *Emitter) (any, *PluginError)
+
+func (handler HandlerFunc) Handle(
+	context RequestContext,
+	method string,
+	params json.RawMessage,
+	emitter *Emitter,
+) (any, *PluginError) {
+	return handler(context, method, params, emitter)
+}
+
+type Emitter struct {
+	writer io.Writer
+	mutex  *sync.Mutex
+}
+
+func (emitter *Emitter) Event(method string, params any) *PluginError {
+	if !validProtocolName(method) {
+		return NewError(-32600, "Invalid event method")
+	}
+	return emitter.write(map[string]any{
+		"jsonrpc": "2.0",
+		"method":  method,
+		"params":  params,
+	})
+}
+
+func (emitter *Emitter) respond(id json.RawMessage, result any, pluginError *PluginError) *PluginError {
+	response := map[string]any{"jsonrpc": "2.0", "id": id}
+	if pluginError != nil {
+		response["error"] = pluginError
+	} else {
+		response["result"] = result
+	}
+	return emitter.write(response)
+}
+
+func (emitter *Emitter) write(value any) *PluginError {
+	payload, err := json.Marshal(value)
+	if err != nil {
+		return NewError(-32603, err.Error())
+	}
+	if len(payload) > maxJSONBytes {
+		return NewError(-32600, "JSON message is too large")
+	}
+	emitter.mutex.Lock()
+	defer emitter.mutex.Unlock()
+	if _, err := emitter.writer.Write(append(payload, '\n')); err != nil {
+		return NewError(-32000, err.Error())
+	}
+	return nil
+}
+
+type Server struct {
+	metadata Metadata
+	handler  Handler
+	input    io.Reader
+	output   io.Writer
+	errors   io.Writer
+}
+
+func NewServer(metadata Metadata, handler Handler) *Server {
+	return &Server{
+		metadata: metadata,
+		handler:  handler,
+		input:    os.Stdin,
+		output:   os.Stdout,
+		errors:   os.Stderr,
+	}
+}
+
+func (server *Server) WithIO(input io.Reader, output io.Writer, errorsWriter io.Writer) *Server {
+	server.input = input
+	server.output = output
+	server.errors = errorsWriter
+	return server
+}
+
+func (server *Server) Serve() error {
+	if server.handler == nil {
+		return errors.New("plugin handler is required")
+	}
+	if !validProtocolName(server.metadata.ID) {
+		return errors.New("plugin id is invalid")
+	}
+	emitter := &Emitter{writer: server.output, mutex: &sync.Mutex{}}
+	scanner := bufio.NewScanner(server.input)
+	scanner.Buffer(make([]byte, 64*1024), maxJSONBytes)
+	var workers sync.WaitGroup
+	for scanner.Scan() {
+		payload := bytes.TrimSpace(scanner.Bytes())
+		if len(payload) == 0 {
+			continue
+		}
+		request, err := decodeRequest(payload)
+		if err != nil {
+			fmt.Fprintf(server.errors, "[dbx-plugin-sdk-go] %v\n", err)
+			continue
+		}
+		if request.Method == "plugin/initialize" {
+			if len(request.ID) == 0 {
+				fmt.Fprintln(server.errors, "[dbx-plugin-sdk-go] plugin/initialize must be a request")
+				continue
+			}
+			result, pluginError := server.initialize(request.Params)
+			if writeError := emitter.respond(request.ID, result, pluginError); writeError != nil {
+				return errors.New(writeError.Message)
+			}
+			continue
+		}
+		workers.Add(1)
+		go func(request protocolRequest) {
+			defer workers.Done()
+			result, pluginError := server.handler.Handle(
+				RequestContext{RequestID: request.ID, Driver: request.Driver},
+				request.Method,
+				request.Params,
+				emitter,
+			)
+			if len(request.ID) == 0 {
+				if pluginError != nil {
+					fmt.Fprintf(server.errors, "[dbx-plugin-sdk-go] %s\n", pluginError.Message)
+				}
+				return
+			}
+			if writeError := emitter.respond(request.ID, result, pluginError); writeError != nil {
+				fmt.Fprintf(server.errors, "[dbx-plugin-sdk-go] failed to write response: %s\n", writeError.Message)
+			}
+		}(request)
+	}
+	workers.Wait()
+	return scanner.Err()
+}
+
+func (server *Server) initialize(params json.RawMessage) (any, *PluginError) {
+	var request struct {
+		Host struct {
+			ProtocolVersions []int `json:"protocolVersions"`
+		} `json:"host"`
+	}
+	if err := json.Unmarshal(params, &request); err != nil {
+		return nil, NewError(-32602, "Invalid initialize parameters")
+	}
+	for _, version := range request.Host.ProtocolVersions {
+		if version == ProtocolVersion {
+			return map[string]any{
+				"protocolVersion": ProtocolVersion,
+				"capabilities":    server.metadata.Capabilities,
+				"plugin": map[string]string{
+					"id":      server.metadata.ID,
+					"version": server.metadata.Version,
+				},
+			}, nil
+		}
+	}
+	return nil, NewError(-32001, "DBX and plugin do not share a protocol version")
+}
+
+type protocolRequest struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id"`
+	Driver  string          `json:"driver"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params"`
+}
+
+func decodeRequest(payload []byte) (protocolRequest, error) {
+	var request protocolRequest
+	if err := json.Unmarshal(payload, &request); err != nil {
+		return request, err
+	}
+	if request.JSONRPC != "2.0" {
+		return request, errors.New("request does not declare jsonrpc 2.0")
+	}
+	if !validProtocolName(request.Method) {
+		return request, errors.New("request method is invalid")
+	}
+	if len(request.Params) == 0 {
+		request.Params = json.RawMessage("null")
+	}
+	return request, nil
+}
+
+func validProtocolName(value string) bool {
+	if len(value) == 0 || len(value) > 256 {
+		return false
+	}
+	for index, character := range value {
+		if character >= 'a' && character <= 'z' || character >= 'A' && character <= 'Z' || character >= '0' && character <= '9' {
+			continue
+		}
+		if index > 0 && (character == '.' || character == '_' || character == ':' || character == '/' || character == '-') {
+			continue
+		}
+		return false
+	}
+	return true
+}

package/sdk-root/plugins/sdk/go/dbx-plugin-sdk/sdk_test.go

@@ -0,0 +1,62 @@
+package dbxpluginsdk
+
+import (
+	"bytes"
+	"encoding/json"
+	"sync"
+	"testing"
+)
+
+func TestServerInitializesAndDispatches(t *testing.T) {
+	input := bytes.NewBufferString(
+		"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"plugin/initialize\",\"params\":{\"host\":{\"protocolVersions\":[1]}}}\n" +
+			"{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"sample/ping\",\"params\":{\"name\":\"DBX\"}}\n",
+	)
+	var output bytes.Buffer
+	server := NewServer(
+		Metadata{ID: "sample.plugin", Version: "1.0.0", Capabilities: []string{"commands"}},
+		HandlerFunc(func(_ RequestContext, method string, _ json.RawMessage, _ *Emitter) (any, *PluginError) {
+			if method != "sample/ping" {
+				return nil, MethodNotFound(method)
+			}
+			return map[string]any{"ok": true}, nil
+		}),
+	).WithIO(input, &output, &bytes.Buffer{})
+	if err := server.Serve(); err != nil {
+		t.Fatal(err)
+	}
+	var responses []map[string]any
+	for _, line := range bytes.Split(bytes.TrimSpace(output.Bytes()), []byte{'\n'}) {
+		var response map[string]any
+		if err := json.Unmarshal(line, &response); err != nil {
+			t.Fatal(err)
+		}
+		responses = append(responses, response)
+	}
+	if len(responses) != 2 {
+		t.Fatalf("expected 2 responses, got %d", len(responses))
+	}
+	initialize := responses[0]["result"].(map[string]any)
+	if initialize["protocolVersion"] != float64(ProtocolVersion) {
+		t.Fatalf("unexpected initialize response: %#v", initialize)
+	}
+	pong := responses[1]["result"].(map[string]any)
+	if pong["ok"] != true {
+		t.Fatalf("unexpected handler response: %#v", pong)
+	}
+}
+
+func TestEmitterWritesEvents(t *testing.T) {
+	var output bytes.Buffer
+	emitter := &Emitter{writer: &output, mutex: &sync.Mutex{}}
+	if pluginError := emitter.Event("sample/progress", map[string]any{"value": 1}); pluginError != nil {
+		t.Fatal(pluginError.Message)
+	}
+	var event map[string]any
+	if err := json.Unmarshal(bytes.TrimSpace(output.Bytes()), &event); err != nil {
+		t.Fatal(err)
+	}
+	if event["method"] != "sample/progress" {
+		t.Fatalf("unexpected event: %#v", event)
+	}
+}

package/sdk-root/plugins/sdk/rust/dbx-plugin-sdk/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "dbx-plugin-sdk"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+description = "Sidecar protocol SDK for DBX plugins"
+
+[workspace]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

package/sdk-root/plugins/sdk/rust/dbx-plugin-sdk/README.md

@@ -0,0 +1,87 @@
+# dbx-plugin-sdk
+
+Rust SDK for DBX sidecar protocol v1.
+
+It provides:
+
+- `plugin/initialize` negotiation and backend identity reporting;
+- concurrent JSON-RPC request dispatch through a bounded worker pool;
+- JSON-RPC responses and plugin events;
+- JSON Lines and framed transports;
+- binary input/output channels for framed plugins;
+- bounded JSON and binary message sizes.
+
+## Minimal sidecar
+
+```rust
+use dbx_plugin_sdk::{
+    PluginEmitter, PluginError, PluginHandler, PluginMetadata, PluginServer,
+    RequestContext,
+};
+use serde_json::{json, Value};
+
+struct Example;
+
+impl PluginHandler for Example {
+    fn handle(
+        &self,
+        _context: RequestContext,
+        method: &str,
+        params: Value,
+        emitter: &PluginEmitter,
+    ) -> Result<Value, PluginError> {
+        match method {
+            "example/echo" => {
+                emitter.event("example/progress", json!({ "done": true }))?;
+                Ok(params)
+            }
+            _ => Err(PluginError::method_not_found(method)),
+        }
+    }
+}
+
+fn main() -> std::io::Result<()> {
+    PluginServer::new(
+        PluginMetadata::new("vendor.example", env!("CARGO_PKG_VERSION"))
+            .with_capability("events"),
+        Example,
+    )
+    .serve()
+}
+```
+
+The metadata ID and version must exactly match `manifest.json`; DBX rejects a mismatched backend during initialization.
+
+## Framed transport
+
+Use framed transport for PTY, SFTP, file transfer, or other binary streams:
+
+```rust
+use dbx_plugin_sdk::{PluginServer, PluginTransport};
+
+PluginServer::new(metadata, handler)
+    .transport(PluginTransport::Framed)
+    .serve()?;
+```
+
+Implement `PluginHandler::handle_binary` for host-to-plugin frames and call `PluginEmitter::binary` for plugin-to-host frames. The manifest must declare `"transport": "stdio-framed"`; workbench UI binary access requires the `host.binary` permission.
+
+The server defaults to 2-16 worker threads (based on available parallelism) and a 256-job queue. CPU-heavy or latency-sensitive plugins can tune both without falling back to unbounded thread creation:
+
+```rust
+PluginServer::new(metadata, handler)
+    .worker_threads(8)
+    .work_queue_capacity(512)
+    .serve()?;
+```
+
+## Process rules
+
+- Reserve stdout for protocol traffic.
+- Write diagnostics to stderr.
+- Keep plugin-owned sessions in the handler or another process-wide registry.
+- Make connect/disconnect idempotent.
+- Use application-level cancellation and chunk acknowledgements for long-running transfers.
+- Never send connection secrets in plugin events or workbench context.
+
+See `plugins/examples/hello-workbench` for a complete package.

package/sdk-root/plugins/sdk/rust/dbx-plugin-sdk/src/lib.rs

@@ -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())
+}