How paritytech/jsonrpc works
This project is a Rust-based implementation of the JSON-RPC 2.0 specification, designed to be transport agnostic. It’s organized as a multi-crate repository where each sub-project (or “crate”) targets a specific aspect—whether it be the core JSON-RPC logic, client support, deriving RPC traits via macros, or actual transport implementations (HTTP, IPC, TCP, WS, stdio). The primary goal is to offer a modular JSON-RPC solution where different transport servers plug into a common core, along with support for advanced features like publish/subscribe.
Main Components
• Core Library (“core”): Contains the essential logic for handling JSON-RPC calls, middleware, error handling, and the basic types for requests, responses, and delegating methods.
• Core Client (“core-client”): Focused on the client-side implementation that enables invoking JSON-RPC methods.
• Transport Servers: Multiple crates implement transport-specific servers:
– HTTP (jsonrpc-http-server)
– IPC (jsonrpc-ipc-server)
– TCP (jsonrpc-tcp-server)
– WebSocket (jsonrpc-ws-server)
– Stdio (jsonrpc-stdio-server)
• Derive Macros (“derive”): Provides procedural macros to easily implement RPC traits and generate delegates.
• Server Utilities (“server-utils”): Contains helper functions and modules for CORS, sessions, stream management, and other server-side utilities.
• PubSub Support (“pubsub”): Implements publish/subscribe functionality for handling subscriptions beyond basic RPC call/response.
Relationships and Interactions
• The Core acts as the central engine. All transport servers and the client wrap around this core logic.
• When a request comes in via a transport server (for example, HTTP), the server receives the request and routes it to the core’s IoHandler. The IoHandler processes the request using methods (which might have been generated/enhanced by derive macros) and returns a response.
• The Client component in “core-client” sends JSON-RPC requests to any of these transport layers, receiving the processed results from the server.
• The Derive crate is used to automatically generate trait delegates and helpers for converting high-level RPC interface definitions into code that interacts with the core layer.
• Server Utilities provide additional functionality (like logging, session management, and middleware support) that is shared across different transport implementations.
• PubSub extends the core functionality to support subscription-based interactions which is integrated into one or more transport servers.
Architectural Patterns and Design Principles
• Separation of Concerns: Each crate has a distinct responsibility (core processing, transport handling, client-side interactions, etc.) ensuring modularity.
• Transport Agnosticism: The core JSON-RPC logic remains independent of the transport layer. This decoupling allows simple swapping or additions of new transport protocols.
• Extensibility via Macros: The “derive” crate aids in reducing boilerplate for implementing RPC methods, promoting DRY code and ease of use.
• Utility Layer: The server utilities abstract common patterns such as session management and error logging.
• Example Driven: The presence of multiple examples in different directories (e.g., in “core/examples”, “derive/examples”) illustrates a focus on clarity and ease-of-adoption.