Crate jsonrpc_fdpass

Expand description

§JSON-RPC 2.0 with Unix File Descriptor Passing

This crate provides an implementation of JSON-RPC 2.0 with file descriptor passing over Unix domain sockets. It enables reliable inter-process communication (IPC) with the ability to pass file descriptors alongside JSON-RPC messages.

§Features

JSON-RPC 2.0 compliance: Full support for requests, responses, and notifications
File descriptor passing: Pass file descriptors using Unix socket ancillary data
Streaming JSON parsing: Self-delimiting JSON messages without newline requirements
Async support: Built on tokio for high-performance async I/O
Type-safe: Rust’s type system ensures correct message handling

§Quick Start

§Server Example

use jsonrpc_fdpass::{Server, Result};
use std::fs::File;
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<()> {
    let mut server = Server::new();
     
    server.register_method("read_file", |_method, _params, fds| {
        if let Some(fd) = fds.into_iter().next() {
            let mut file = File::from(fd);
            let mut contents = String::new();
            use std::io::Read;
            file.read_to_string(&mut contents).unwrap();
            Ok((Some(Value::String(contents)), Vec::new()))
        } else {
            Err(jsonrpc_fdpass::Error::InvalidMessage("No FD provided".into()))
        }
    });
     
    server.listen("/tmp/test.sock").await
}

§Client Example

use jsonrpc_fdpass::{
    JsonRpcRequest, JsonRpcMessage, MessageWithFds, UnixSocketTransport, Result
};
use std::fs::File;
use std::os::unix::io::OwnedFd;
use serde_json::json;
use tokio::net::UnixStream;

#[tokio::main]
async fn main() -> Result<()> {
    let stream = UnixStream::connect("/tmp/test.sock").await?;
    let transport = UnixSocketTransport::new(stream);
    let (mut sender, mut receiver) = transport.split();
     
    let file = File::open("example.txt").unwrap();
    let fd: OwnedFd = file.into();
     
    let request = JsonRpcRequest::new(
        "read_file".to_string(),
        Some(json!({"filename": "example.txt"})),
        json!(1),
    );
    let message = MessageWithFds::new(JsonRpcMessage::Request(request), vec![fd]);
    sender.send(message).await?;
     
    let response = receiver.receive().await?;
    println!("Response: {:?}", response.message);
     
    Ok(())
}

§Protocol Details

This implementation is a minimal extension to JSON-RPC 2.0 that adds file descriptor passing over Unix domain sockets:

Uses Unix domain sockets (SOCK_STREAM)
Standard JSON-RPC 2.0 message format with no additional framing requirements
JSON objects are self-delimiting; no newline or length-prefix framing is required
File descriptors are passed as ancillary data via sendmsg(2)/recvmsg(2)
Each sendmsg() call contains exactly one complete JSON-RPC message

§File Descriptor Count Field

When file descriptors are attached to a message, the fds field at the top level of the JSON object specifies how many FDs are attached:

{
  "jsonrpc": "2.0",
  "method": "read_file",
  "params": {"filename": "example.txt"},
  "id": 1,
  "fds": 1
}

File descriptors are passed positionally—the application layer defines the semantic mapping between FD positions and parameters.

Re-exports§

pub use error::Error;
pub use error::Result;
pub use message::FILE_DESCRIPTOR_ERROR_CODE;
pub use message::JsonRpcMessage;
pub use message::JsonRpcNotification;
pub use message::JsonRpcRequest;
pub use message::JsonRpcResponse;
pub use message::MessageWithFds;
pub use message::file_descriptor_error;
pub use server::Server;
pub use transport::DEFAULT_MAX_FDS_PER_SENDMSG;
pub use transport::Receiver;
pub use transport::Sender;
pub use transport::UnixSocketTransport;

Modules§

error: Error types for JSON-RPC operations.
message: JSON-RPC message types and serialization.
server: JSON-RPC 2.0 server implementation with file descriptor passing.
transport: Low-level Unix socket transport with ancillary data support.

Structs§

JsonRpcError: Failed JSON-RPC response object.

Enums§

ErrorCode: JSONRPC error code

Constants§

CALL_EXECUTION_FAILED_CODE: Custom server error when a call failed.
INTERNAL_ERROR_CODE: Internal error code.
INTERNAL_ERROR_MSG: Internal error message.
INVALID_PARAMS_CODE: Invalid params error code.
INVALID_PARAMS_MSG: Invalid params error message.
INVALID_REQUEST_CODE: Invalid request error code.
INVALID_REQUEST_MSG: Invalid request error message.
METHOD_NOT_FOUND_CODE: Method not found error code.
METHOD_NOT_FOUND_MSG: Method not found error message.
PARSE_ERROR_CODE: Parse error code.
PARSE_ERROR_MSG: Parse error message