procwire_client/
lib.rs

1//! # procwire-client
2//!
3//! Rust client SDK for [Procwire](https://github.com/SebastianWebdev/procwire) v2.0 IPC protocol.
4//!
5//! This crate enables Rust workers (child processes) to communicate with
6//! a Node.js parent process running `@procwire/core` using a high-performance
7//! binary protocol.
8//!
9//! ## Features
10//!
11//! - **High Performance**: Binary protocol with MsgPack serialization
12//! - **Zero-copy**: Uses `bytes::BytesMut` for efficient buffer management
13//! - **Async/await**: Built on Tokio for non-blocking I/O
14//! - **Cross-platform**: Works on Linux, macOS, and Windows
15//! - **Type-safe**: Strongly typed handlers with Serde integration
16//! - **Streaming**: Support for chunked responses
17//! - **Cancellation**: Full abort signal support with `CancellationToken`
18//!
19//! ## Architecture
20//!
21//! Procwire uses a dual-channel architecture:
22//!
23//! - **Control Plane** (stdio): JSON-RPC for the `$init` handshake
24//! - **Data Plane** (named pipe/Unix socket): Binary protocol for high-throughput communication
25//!
26//! ## Quick Start
27//!
28//! ```ignore
29//! use procwire_client::ClientBuilder;
30//! use serde::{Deserialize, Serialize};
31//!
32//! #[derive(Serialize, Deserialize)]
33//! struct EchoRequest {
34//!     message: String,
35//! }
36//!
37//! #[derive(Serialize, Deserialize)]
38//! struct EchoResponse {
39//!     message: String,
40//! }
41//!
42//! #[tokio::main]
43//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
44//!     let client = ClientBuilder::new()
45//!         .method("echo", |ctx, payload: EchoRequest| async move {
46//!             ctx.respond(&EchoResponse {
47//!                 message: payload.message,
48//!             })
49//!             .await
50//!         })
51//!         .build()
52//!         .await?;
53//!
54//!     client.run().await?;
55//!     Ok(())
56//! }
57//! ```
58//!
59//! ## Response Types
60//!
61//! Handlers can respond in several ways:
62//!
63//! - [`RequestContext::respond`] - Send a single response
64//! - [`RequestContext::ack`] - Acknowledge receipt (fire-and-forget pattern)
65//! - [`RequestContext::chunk`] / [`RequestContext::end`] - Streaming responses
66//! - [`RequestContext::error`] - Send an error response
67//!
68//! ## Cancellation
69//!
70//! Handlers can check for abort signals from the parent:
71//!
72//! ```ignore
73//! .method("long_task", |ctx, _payload: ()| async move {
74//!     if ctx.is_cancelled() {
75//!         return Ok(());
76//!     }
77//!     // ... do work
78//!     ctx.respond(&result).await
79//! })
80//! ```
81//!
82//! ## Modules
83//!
84//! - [`protocol`] - Wire format, frame buffer, and frame types
85//! - [`codec`] - Serialization codecs (MsgPack, Raw)
86//! - [`transport`] - Platform-specific pipe/socket transport
87//! - [`control`] - Control plane ($init message)
88//! - [`handler`] - Handler registry and request context
89//! - [`error`] - Error types
90
91pub mod backpressure;
92pub mod codec;
93pub mod control;
94pub mod error;
95pub mod handler;
96pub mod protocol;
97pub mod transport;
98pub mod writer;
99
100mod client;
101
102pub use client::{Client, ClientBuilder};
103pub use error::ProcwireError;
104pub use handler::RequestContext;
procwire_client/lib.rs

procwire_client/
lib.rs
