lib: Add deny(missing_docs), also drop Client

Enforce documentation requirements for all public API items by adding
the `#![deny(missing_docs)]` lint.

Also while looking at this, the Client doesn't make sense because
most use cases should be using async calls, so drop it.

Assisted-by: OpenCode (Sonnet 4)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

examples/demo.rs

@@ -1,11 +1,14 @@
-use jsonrpc_fdpass::{Client, Result, Server};
+use jsonrpc_fdpass::{
+    JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, MessageWithFds, Result, Server,
+    UnixSocketTransport,
+};
 use serde_json::Value;
 use std::fs::File;
 use std::io::{Read, Write};
 use std::os::unix::io::OwnedFd;
 use std::path::PathBuf;
 use tempfile::TempDir;
-use tokio::net::UnixListener;
+use tokio::net::{UnixListener, UnixStream};
 use tracing::info;
 
 #[tokio::main]
@@ -63,7 +66,7 @@ async fn run_server(listener: UnixListener) -> Result<()> {
 
     // Accept one connection and handle it
     if let Ok((stream, _)) = listener.accept().await {
-        let transport = jsonrpc_fdpass::UnixSocketTransport::new(stream);
+        let transport = UnixSocketTransport::new(stream);
         let (mut sender, mut receiver) = transport.split();
 
         // Handle messages from this connection
@@ -82,7 +85,9 @@ async fn run_server(listener: UnixListener) -> Result<()> {
 }
 
 async fn run_client(socket_path: PathBuf) -> Result<()> {
-    let mut client = Client::connect(&socket_path).await?;
+    let stream = UnixStream::connect(&socket_path).await?;
+    let transport = UnixSocketTransport::new(stream);
+    let (mut sender, mut _receiver) = transport.split();
 
     // Create a temporary file to send to the server
     let mut temp_file = tempfile::NamedTempFile::new().map_err(jsonrpc_fdpass::Error::Io)?;
@@ -97,19 +102,19 @@ async fn run_client(socket_path: PathBuf) -> Result<()> {
     });
 
     info!("Client sending file descriptor to server");
-    client
-        .call_method("read_file", Some(params), vec![fd])
-        .await?;
+    let request = JsonRpcRequest::new("read_file".to_string(), Some(params), serde_json::json!(1));
+    let message = MessageWithFds::new(JsonRpcMessage::Request(request), vec![fd]);
+    sender.send(message).await?;
 
     // Send notification
     let params = serde_json::json!({
         "message": "This is a test notification"
     });
 
     info!("Client sending notification");
-    client
-        .send_notification("log_message", Some(params), vec![])
-        .await?;
+    let notification = JsonRpcNotification::new("log_message".to_string(), Some(params));
+    let message = MessageWithFds::new(JsonRpcMessage::Notification(notification), vec![]);
+    sender.send(message).await?;
 
     info!("Client finished");
     Ok(())

src/client.rs

@@ -1,29 +1,43 @@
 use thiserror::Error;
 
+/// Errors that can occur during JSON-RPC operations.
 #[derive(Error, Debug)]
 pub enum Error {
+    /// JSON serialization or deserialization failed.
     #[error("JSON parsing error: {0}")]
     Json(#[from] serde_json::Error),
 
+    /// An I/O error occurred.
     #[error("IO error: {0}")]
     Io(#[from] std::io::Error),
 
+    /// The message contained invalid JSON.
     #[error("Protocol framing error: invalid JSON in message")]
     FramingError,
 
+    /// The `fds` field in the message doesn't match the number of received file descriptors.
     #[error(
         "File descriptor count mismatch: fds field specifies {expected}, but {found} FDs available"
     )]
-    MismatchedCount { expected: usize, found: usize },
-
+    MismatchedCount {
+        /// Number of file descriptors specified in the `fds` field.
+        expected: usize,
+        /// Number of file descriptors actually available.
+        found: usize,
+    },
+
+    /// A system call failed.
     #[error("System call error: {0}")]
     SystemCall(String),
 
+    /// The connection was closed by the peer.
     #[error("Connection closed")]
     ConnectionClosed,
 
+    /// The message format was invalid.
     #[error("Invalid message format: {0}")]
     InvalidMessage(String),
 }
 
+/// A specialized Result type for JSON-RPC operations.
 pub type Result<T> = std::result::Result<T, Error>;

src/error.rs

@@ -44,23 +44,33 @@
 //! ### Client Example
 //!
 //! ```rust,no_run
-//! use jsonrpc_fdpass::{Client, Result};
+//! 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 mut client = Client::connect("/tmp/test.sock").await?;
+//!     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 params = json!({
-//!         "filename": "example.txt"
-//!     });
+//!     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?;
 //!     
-//!     client.call_method("read_file", Some(params), vec![fd]).await?;
+//!     let response = receiver.receive().await?;
+//!     println!("Response: {:?}", response.message);
 //!     
 //!     Ok(())
 //! }
@@ -96,14 +106,17 @@
 //! mapping between FD positions and parameters.
 
 #![forbid(unsafe_code)]
+#![deny(missing_docs)]
 
-pub mod client;
+/// Error types for JSON-RPC operations.
 pub mod error;
+/// JSON-RPC message types and serialization.
 pub mod message;
+/// JSON-RPC 2.0 server implementation with file descriptor passing.
 pub mod server;
+/// Low-level Unix socket transport with ancillary data support.
 pub mod transport;
 
-pub use client::Client;
 pub use error::{Error, Result};
 pub use jsonrpsee::types::error::{
     ErrorCode, ErrorObject as JsonRpcError, CALL_EXECUTION_FAILED_CODE, INTERNAL_ERROR_CODE,

src/lib.rs

@@ -23,51 +23,69 @@ fn skip_if_zero_or_none(fds: &Option<usize>) -> bool {
     fds.map_or(true, |n| n == 0)
 }
 
-// Define our own message types that don't have lifetime constraints
+/// A JSON-RPC 2.0 request message.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JsonRpcRequest {
+    /// The JSON-RPC protocol version (always "2.0").
     pub jsonrpc: String,
+    /// The name of the method to invoke.
     pub method: String,
+    /// Optional parameters for the method.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub params: Option<serde_json::Value>,
+    /// The request identifier.
     pub id: serde_json::Value,
-    /// Number of file descriptors attached to this message
+    /// Number of file descriptors attached to this message.
     #[serde(skip_serializing_if = "skip_if_zero_or_none")]
     pub fds: Option<usize>,
 }
 
+/// A JSON-RPC 2.0 response message.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JsonRpcResponse {
+    /// The JSON-RPC protocol version (always "2.0").
     pub jsonrpc: String,
+    /// The result of the method invocation (present on success).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub result: Option<serde_json::Value>,
+    /// The error object (present on failure).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub error: Option<JsonRpcError<'static>>,
+    /// The request identifier this response corresponds to.
     pub id: serde_json::Value,
-    /// Number of file descriptors attached to this message
+    /// Number of file descriptors attached to this message.
     #[serde(skip_serializing_if = "skip_if_zero_or_none")]
     pub fds: Option<usize>,
 }
 
+/// A JSON-RPC 2.0 notification message (a request without an id).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JsonRpcNotification {
+    /// The JSON-RPC protocol version (always "2.0").
     pub jsonrpc: String,
+    /// The name of the method to invoke.
     pub method: String,
+    /// Optional parameters for the method.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub params: Option<serde_json::Value>,
-    /// Number of file descriptors attached to this message
+    /// Number of file descriptors attached to this message.
     #[serde(skip_serializing_if = "skip_if_zero_or_none")]
     pub fds: Option<usize>,
 }
 
+/// A JSON-RPC 2.0 message (request, response, or notification).
 #[derive(Debug, Clone)]
 pub enum JsonRpcMessage {
+    /// A request message expecting a response.
     Request(JsonRpcRequest),
+    /// A response to a previous request.
     Response(JsonRpcResponse),
+    /// A notification (no response expected).
     Notification(JsonRpcNotification),
 }
 
 impl JsonRpcRequest {
+    /// Create a new JSON-RPC request.
     pub fn new(method: String, params: Option<serde_json::Value>, id: serde_json::Value) -> Self {
         Self {
             jsonrpc: JSONRPC_VERSION.to_string(),
@@ -80,6 +98,7 @@ impl JsonRpcRequest {
 }
 
 impl JsonRpcResponse {
+    /// Create a successful JSON-RPC response.
     pub fn success(result: serde_json::Value, id: serde_json::Value) -> Self {
         Self {
             jsonrpc: JSONRPC_VERSION.to_string(),
@@ -90,6 +109,7 @@ impl JsonRpcResponse {
         }
     }
 
+    /// Create an error JSON-RPC response.
     pub fn error(error: JsonRpcError<'static>, id: serde_json::Value) -> Self {
         Self {
             jsonrpc: JSONRPC_VERSION.to_string(),
@@ -102,6 +122,7 @@ impl JsonRpcResponse {
 }
 
 impl JsonRpcNotification {
+    /// Create a new JSON-RPC notification.
     pub fn new(method: String, params: Option<serde_json::Value>) -> Self {
         Self {
             jsonrpc: JSONRPC_VERSION.to_string(),
@@ -113,6 +134,7 @@ impl JsonRpcNotification {
 }
 
 impl JsonRpcMessage {
+    /// Convert this message to a JSON value.
     pub fn to_json_value(&self) -> Result<serde_json::Value> {
         match self {
             JsonRpcMessage::Request(req) => Ok(serde_json::to_value(req)?),
@@ -121,6 +143,7 @@ impl JsonRpcMessage {
         }
     }
 
+    /// Parse a JSON-RPC message from a JSON value.
     pub fn from_json_value(value: serde_json::Value) -> Result<Self> {
         if let serde_json::Value::Object(obj) = &value {
             if obj.contains_key("method") && obj.contains_key("id") {
@@ -141,9 +164,12 @@ impl JsonRpcMessage {
     }
 }
 
+/// A JSON-RPC message paired with file descriptors to send or that were received.
 #[derive(Debug)]
 pub struct MessageWithFds {
+    /// The JSON-RPC message.
     pub message: JsonRpcMessage,
+    /// File descriptors attached to this message.
     pub file_descriptors: Vec<OwnedFd>,
 }
 
@@ -169,6 +195,7 @@ impl JsonRpcMessage {
 }
 
 impl MessageWithFds {
+    /// Create a new message with file descriptors.
     pub fn new(message: JsonRpcMessage, file_descriptors: Vec<OwnedFd>) -> Self {
         Self {
             message,
@@ -218,8 +245,10 @@ impl MessageWithFds {
     }
 }
 
+/// JSON-RPC error code for file descriptor errors.
 pub const FILE_DESCRIPTOR_ERROR_CODE: i32 = -32050;
 
+/// Create a JSON-RPC error object for file descriptor errors.
 pub fn file_descriptor_error() -> JsonRpcError<'static> {
     JsonRpcError::owned(
         FILE_DESCRIPTOR_ERROR_CODE,