starpc 0.41.2 → 0.43.1

package/srpc/error.rs

@@ -0,0 +1,177 @@
+//! Error types for starpc.
+//!
+//! This module provides the error types used throughout the starpc library,
+//! matching the error semantics of the Go and TypeScript implementations.
+
+use thiserror::Error;
+
+/// Errors that can occur in starpc operations.
+#[derive(Error, Debug)]
+pub enum Error {
+    /// The requested RPC method is not implemented.
+    #[error("method not implemented")]
+    Unimplemented,
+
+    /// A packet was received after the RPC was completed.
+    #[error("unexpected packet after rpc was completed")]
+    Completed,
+
+    /// An unrecognized packet type was received.
+    #[error("unrecognized packet type")]
+    UnrecognizedPacket,
+
+    /// An empty packet was received (no body or CallData with no content).
+    #[error("invalid empty packet")]
+    EmptyPacket,
+
+    /// Invalid message format (protobuf decode error).
+    #[error("invalid message: {0}")]
+    InvalidMessage(#[from] prost::DecodeError),
+
+    /// The method ID is empty.
+    #[error("method id empty")]
+    EmptyMethodId,
+
+    /// The service ID is empty.
+    #[error("service id empty")]
+    EmptyServiceId,
+
+    /// No RPC clients are available.
+    #[error("no available rpc clients")]
+    NoAvailableClients,
+
+    /// The writer is not initialized.
+    #[error("writer cannot be nil")]
+    NilWriter,
+
+    /// IO error during read/write operations.
+    #[error("io error: {0}")]
+    Io(#[from] std::io::Error),
+
+    /// The stream was closed.
+    #[error("stream closed")]
+    StreamClosed,
+
+    /// The RPC was aborted.
+    #[error("rpc aborted")]
+    Aborted,
+
+    /// The context was cancelled.
+    #[error("context cancelled")]
+    Cancelled,
+
+    /// The stream idle timeout was exceeded.
+    #[error("stream idle timeout exceeded")]
+    StreamIdle,
+
+    /// Remote error from the other end.
+    #[error("remote error: {0}")]
+    Remote(String),
+
+    /// Message size exceeds maximum allowed size.
+    #[error("message size {0} exceeds maximum {1}")]
+    MessageTooLarge(usize, usize),
+
+    /// Message size is zero but data_is_zero flag is not set.
+    #[error("unexpected zero length prefix")]
+    MessageSizeZero,
+
+    /// Expected CallStart packet but got a different packet type.
+    #[error("expected CallStart packet")]
+    ExpectedCallStart,
+
+    /// CallStart was sent more than once.
+    #[error("call start must be sent only once")]
+    DuplicateCallStart,
+
+    /// CallData received before CallStart.
+    #[error("call start must be sent before call data")]
+    CallDataBeforeStart,
+
+    /// Protocol encode error.
+    #[error("encode error: {0}")]
+    Encode(#[from] prost::EncodeError),
+
+    /// Channel send error (internal).
+    #[error("channel closed")]
+    ChannelClosed,
+}
+
+impl Error {
+    /// Returns true if this error indicates the RPC was aborted.
+    pub fn is_abort(&self) -> bool {
+        matches!(self, Error::Aborted | Error::Cancelled)
+    }
+
+    /// Returns true if this error indicates the stream was closed.
+    pub fn is_closed(&self) -> bool {
+        matches!(self, Error::StreamClosed | Error::Cancelled)
+    }
+
+    /// Returns true if this error indicates a timeout.
+    pub fn is_timeout(&self) -> bool {
+        matches!(self, Error::StreamIdle)
+    }
+
+    /// Returns true if this error indicates the method is not implemented.
+    pub fn is_unimplemented(&self) -> bool {
+        matches!(self, Error::Unimplemented)
+    }
+
+    /// Creates a remote error from a string.
+    pub fn remote(msg: impl Into<String>) -> Self {
+        Error::Remote(msg.into())
+    }
+}
+
+/// Result type alias using starpc's Error type.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Error code constants matching the TypeScript implementation.
+pub mod codes {
+    /// Error code for RPC abort.
+    pub const ERR_RPC_ABORT: &str = "ERR_RPC_ABORT";
+
+    /// Error code for stream idle timeout.
+    pub const ERR_STREAM_IDLE: &str = "ERR_STREAM_IDLE";
+}
+
+/// Checks if an error message indicates an abort.
+pub fn is_abort_error_message(msg: &str) -> bool {
+    msg == codes::ERR_RPC_ABORT || msg == "rpc aborted" || msg == "context cancelled"
+}
+
+/// Checks if an error message indicates a stream idle timeout.
+pub fn is_stream_idle_error_message(msg: &str) -> bool {
+    msg == codes::ERR_STREAM_IDLE || msg == "stream idle timeout exceeded"
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_error_display() {
+        assert_eq!(Error::Unimplemented.to_string(), "method not implemented");
+        assert_eq!(Error::Completed.to_string(), "unexpected packet after rpc was completed");
+        assert_eq!(Error::EmptyMethodId.to_string(), "method id empty");
+        assert_eq!(Error::Remote("test error".into()).to_string(), "remote error: test error");
+    }
+
+    #[test]
+    fn test_error_predicates() {
+        assert!(Error::Aborted.is_abort());
+        assert!(Error::Cancelled.is_abort());
+        assert!(!Error::StreamClosed.is_abort());
+
+        assert!(Error::StreamClosed.is_closed());
+        assert!(Error::Cancelled.is_closed());
+        assert!(!Error::Aborted.is_closed());
+
+        assert!(Error::StreamIdle.is_timeout());
+        assert!(!Error::Cancelled.is_timeout());
+
+        assert!(Error::Unimplemented.is_unimplemented());
+        assert!(!Error::Cancelled.is_unimplemented());
+    }
+}

package/srpc/handler.rs

@@ -0,0 +1,163 @@
+//! Handler trait for RPC service implementations.
+//!
+//! A Handler is an Invoker that also provides metadata about the service
+//! it handles. This allows the Mux to register handlers and route calls
+//! based on service and method IDs.
+
+use std::sync::Arc;
+
+use crate::invoker::Invoker;
+
+/// Trait for RPC service handlers.
+///
+/// A Handler extends Invoker with metadata methods that describe the service
+/// and methods it implements. This is the trait that generated service code
+/// typically implements.
+///
+/// # Example
+///
+/// ```rust,ignore
+/// struct MyServiceHandler {
+///     // Handler state
+/// }
+///
+/// #[async_trait]
+/// impl Invoker for MyServiceHandler {
+///     async fn invoke_method(
+///         &self,
+///         service_id: &str,
+///         method_id: &str,
+///         stream: Box<dyn Stream>,
+///     ) -> (bool, Result<()>) {
+///         match method_id {
+///             "Method1" => (true, self.method1(stream).await),
+///             "Method2" => (true, self.method2(stream).await),
+///             _ => (false, Err(Error::Unimplemented)),
+///         }
+///     }
+/// }
+///
+/// impl Handler for MyServiceHandler {
+///     fn service_id(&self) -> &'static str {
+///         "my.package.MyService"
+///     }
+///
+///     fn method_ids(&self) -> &'static [&'static str] {
+///         &["Method1", "Method2"]
+///     }
+/// }
+/// ```
+pub trait Handler: Invoker {
+    /// Returns the service ID that this handler implements.
+    ///
+    /// The service ID is typically the fully-qualified protobuf service name,
+    /// e.g., "echo.Echoer" or "my.package.MyService".
+    fn service_id(&self) -> &'static str;
+
+    /// Returns the list of method IDs that this handler implements.
+    ///
+    /// These are the method names as defined in the protobuf service definition.
+    fn method_ids(&self) -> &'static [&'static str];
+}
+
+/// Boxed Handler trait object.
+pub type BoxHandler = Box<dyn Handler>;
+
+/// Arc-wrapped Handler trait object.
+pub type ArcHandler = Arc<dyn Handler>;
+
+// Note: We can't provide blanket implementations for Arc<T> and Box<T>
+// because Handler extends Invoker which already has these implementations.
+// The Mux uses ArcHandler directly.
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::{Error, Result};
+    use crate::stream::{Context, Stream};
+    use async_trait::async_trait;
+
+    struct TestHandler;
+
+    #[async_trait]
+    impl Invoker for TestHandler {
+        async fn invoke_method(
+            &self,
+            _service_id: &str,
+            method_id: &str,
+            _stream: Box<dyn Stream>,
+        ) -> (bool, Result<()>) {
+            match method_id {
+                "Method1" | "Method2" => (true, Ok(())),
+                _ => (false, Err(Error::Unimplemented)),
+            }
+        }
+    }
+
+    impl Handler for TestHandler {
+        fn service_id(&self) -> &'static str {
+            "test.Service"
+        }
+
+        fn method_ids(&self) -> &'static [&'static str] {
+            &["Method1", "Method2"]
+        }
+    }
+
+    #[test]
+    fn test_handler_metadata() {
+        let handler = TestHandler;
+        assert_eq!(handler.service_id(), "test.Service");
+        assert_eq!(handler.method_ids(), &["Method1", "Method2"]);
+    }
+
+    #[test]
+    fn test_arc_handler() {
+        let handler: ArcHandler = Arc::new(TestHandler);
+        assert_eq!(handler.service_id(), "test.Service");
+        assert_eq!(handler.method_ids(), &["Method1", "Method2"]);
+    }
+
+    struct MockStream;
+
+    #[async_trait]
+    impl Stream for MockStream {
+        fn context(&self) -> &Context {
+            static CTX: std::sync::OnceLock<Context> = std::sync::OnceLock::new();
+            CTX.get_or_init(Context::new)
+        }
+
+        async fn send_bytes(&self, _data: bytes::Bytes) -> Result<()> {
+            Ok(())
+        }
+
+        async fn recv_bytes(&self) -> Result<bytes::Bytes> {
+            Err(Error::StreamClosed)
+        }
+
+        async fn close_send(&self) -> Result<()> {
+            Ok(())
+        }
+
+        async fn close(&self) -> Result<()> {
+            Ok(())
+        }
+    }
+
+    #[tokio::test]
+    async fn test_handler_invoke() {
+        let handler: ArcHandler = Arc::new(TestHandler);
+
+        let (found, result) = handler
+            .invoke_method("test.Service", "Method1", Box::new(MockStream))
+            .await;
+        assert!(found);
+        assert!(result.is_ok());
+
+        let (found, result) = handler
+            .invoke_method("test.Service", "Unknown", Box::new(MockStream))
+            .await;
+        assert!(!found);
+        assert!(result.is_err());
+    }
+}

package/srpc/invoker.rs

@@ -0,0 +1,192 @@
+//! Invoker trait for RPC method invocation.
+//!
+//! The Invoker trait defines the interface for dispatching RPC calls to handlers.
+//! This is the core abstraction that allows the Mux, Server, and generated code
+//! to route calls appropriately.
+
+use async_trait::async_trait;
+use std::sync::Arc;
+
+use crate::error::Result;
+use crate::stream::Stream;
+
+/// Trait for invoking RPC methods.
+///
+/// An Invoker is responsible for dispatching incoming RPC calls to the
+/// appropriate handler implementation. The Mux implements this trait to
+/// route calls based on service and method IDs.
+///
+/// # Return Value
+///
+/// The `invoke_method` method returns a tuple of `(found, result)`:
+/// - `found`: Whether the method was found and handled
+/// - `result`: The result of the invocation, or an error
+///
+/// This design allows callers to distinguish between:
+/// - Method not found: `(false, Err(Error::Unimplemented))`
+/// - Method found but failed: `(true, Err(...))`
+/// - Method found and succeeded: `(true, Ok(()))`
+///
+/// # Example
+///
+/// ```rust,ignore
+/// #[async_trait]
+/// impl Invoker for MyHandler {
+///     async fn invoke_method(
+///         &self,
+///         service_id: &str,
+///         method_id: &str,
+///         stream: Box<dyn Stream>,
+///     ) -> (bool, Result<()>) {
+///         match method_id {
+///             "MyMethod" => {
+///                 // Handle the method
+///                 (true, self.my_method(stream).await)
+///             }
+///             _ => (false, Err(Error::Unimplemented)),
+///         }
+///     }
+/// }
+/// ```
+#[async_trait]
+pub trait Invoker: Send + Sync {
+    /// Invokes an RPC method.
+    ///
+    /// # Arguments
+    ///
+    /// * `service_id` - The service identifier (e.g., "echo.Echoer")
+    /// * `method_id` - The method identifier (e.g., "Echo")
+    /// * `stream` - The bidirectional stream for this RPC
+    ///
+    /// # Returns
+    ///
+    /// A tuple of (found, result) where:
+    /// * `found` - Whether the method was found and handled
+    /// * `result` - The result of the invocation
+    async fn invoke_method(
+        &self,
+        service_id: &str,
+        method_id: &str,
+        stream: Box<dyn Stream>,
+    ) -> (bool, Result<()>);
+}
+
+/// Boxed Invoker trait object.
+pub type BoxInvoker = Box<dyn Invoker>;
+
+/// Arc-wrapped Invoker trait object.
+pub type ArcInvoker = Arc<dyn Invoker>;
+
+// Blanket implementation for Arc<T> where T: Invoker
+#[async_trait]
+impl<T: Invoker + ?Sized> Invoker for Arc<T> {
+    async fn invoke_method(
+        &self,
+        service_id: &str,
+        method_id: &str,
+        stream: Box<dyn Stream>,
+    ) -> (bool, Result<()>) {
+        (**self).invoke_method(service_id, method_id, stream).await
+    }
+}
+
+// Blanket implementation for Box<T> where T: Invoker
+#[async_trait]
+impl<T: Invoker + ?Sized> Invoker for Box<T> {
+    async fn invoke_method(
+        &self,
+        service_id: &str,
+        method_id: &str,
+        stream: Box<dyn Stream>,
+    ) -> (bool, Result<()>) {
+        (**self).invoke_method(service_id, method_id, stream).await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::Error;
+    use crate::stream::Context;
+
+    struct TestInvoker {
+        should_handle: bool,
+    }
+
+    #[async_trait]
+    impl Invoker for TestInvoker {
+        async fn invoke_method(
+            &self,
+            _service_id: &str,
+            _method_id: &str,
+            _stream: Box<dyn Stream>,
+        ) -> (bool, Result<()>) {
+            if self.should_handle {
+                (true, Ok(()))
+            } else {
+                (false, Err(Error::Unimplemented))
+            }
+        }
+    }
+
+    struct MockStream;
+
+    #[async_trait]
+    impl Stream for MockStream {
+        fn context(&self) -> &Context {
+            static CTX: std::sync::OnceLock<Context> = std::sync::OnceLock::new();
+            CTX.get_or_init(Context::new)
+        }
+
+        async fn send_bytes(&self, _data: bytes::Bytes) -> Result<()> {
+            Ok(())
+        }
+
+        async fn recv_bytes(&self) -> Result<bytes::Bytes> {
+            Err(Error::StreamClosed)
+        }
+
+        async fn close_send(&self) -> Result<()> {
+            Ok(())
+        }
+
+        async fn close(&self) -> Result<()> {
+            Ok(())
+        }
+    }
+
+    #[tokio::test]
+    async fn test_invoker_found() {
+        let invoker = TestInvoker { should_handle: true };
+        let (found, result) = invoker
+            .invoke_method("svc", "method", Box::new(MockStream))
+            .await;
+
+        assert!(found);
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_invoker_not_found() {
+        let invoker = TestInvoker {
+            should_handle: false,
+        };
+        let (found, result) = invoker
+            .invoke_method("svc", "method", Box::new(MockStream))
+            .await;
+
+        assert!(!found);
+        assert!(result.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_arc_invoker() {
+        let invoker: Arc<dyn Invoker> = Arc::new(TestInvoker { should_handle: true });
+        let (found, result) = invoker
+            .invoke_method("svc", "method", Box::new(MockStream))
+            .await;
+
+        assert!(found);
+        assert!(result.is_ok());
+    }
+}

package/srpc/lib.rs

@@ -0,0 +1,107 @@
+//! Starpc - Streaming Protobuf RPC Framework
+//!
+//! This crate provides a streaming RPC framework built on protobuf, offering
+//! full-duplex bidirectional streaming with support for unary, server-streaming,
+//! client-streaming, and bidirectional streaming RPC patterns.
+//!
+//! # Features
+//!
+//! - **Wire-compatible** with the Go and TypeScript implementations
+//! - **Streaming support** for all RPC patterns
+//! - **Transport agnostic** - works with TCP, WebSocket, or any AsyncRead/AsyncWrite
+//! - **Code generation** via starpc-build crate
+//!
+//! # Quick Start
+//!
+//! ## Client
+//!
+//! ```rust,ignore
+//! use starpc::{Client, SrpcClient};
+//! use starpc::client::transport::SingleStreamOpener;
+//! use tokio::net::TcpStream;
+//!
+//! // Connect to a server
+//! let stream = TcpStream::connect("127.0.0.1:8080").await?;
+//! let opener = SingleStreamOpener::new(stream);
+//! let client = SrpcClient::new(opener);
+//!
+//! // Make a unary call
+//! let response: MyResponse = client
+//!     .exec_call("my.Service", "MyMethod", &request)
+//!     .await?;
+//! ```
+//!
+//! ## Server
+//!
+//! ```rust,ignore
+//! use starpc::{Server, Mux, Handler};
+//! use std::sync::Arc;
+//!
+//! // Create a mux and register handlers
+//! let mux = Arc::new(Mux::new());
+//! mux.register(Arc::new(MyServiceHandler))?;
+//!
+//! // Create the server
+//! let server = Server::with_arc(mux);
+//!
+//! // Handle a connection
+//! server.handle_stream(tcp_stream).await?;
+//! ```
+//!
+//! # Wire Format
+//!
+//! Starpc uses a simple length-prefixed framing:
+//! - 4-byte little-endian u32 length prefix
+//! - Protobuf-encoded Packet message
+//!
+//! This format is compatible with the Go and TypeScript implementations.
+
+pub mod client;
+pub mod codec;
+pub mod error;
+pub mod handler;
+pub mod invoker;
+pub mod message;
+pub mod mux;
+pub mod packet;
+pub mod proto;
+pub mod rpc;
+pub mod server;
+pub mod stream;
+pub mod testing;
+pub mod transport;
+
+// Re-exports for convenience.
+pub use client::{BoxClient, Client, OpenStream, SrpcClient};
+pub use codec::{PacketCodec, MAX_MESSAGE_SIZE};
+pub use error::{Error, Result};
+pub use handler::{BoxHandler, Handler};
+pub use invoker::{BoxInvoker, Invoker};
+pub use message::Message;
+pub use mux::{Mux, QueryableInvoker};
+pub use packet::Validate;
+pub use rpc::{ClientRpc, PacketWriter, ServerRpc};
+pub use server::{Server, ServerConfig};
+pub use stream::{ArcStream, BoxStream, Context, Stream, StreamExt};
+pub use transport::{
+    create_packet_channel, decode_optional_data, encode_optional_data, TransportPacketWriter,
+};
+
+// Re-export async_trait for use in generated code.
+pub use async_trait::async_trait;
+pub use prost::Message as ProstMessage;
+
+/// Prelude module for convenient imports.
+pub mod prelude {
+    pub use crate::client::{Client, OpenStream, SrpcClient};
+    pub use crate::error::{Error, Result};
+    pub use crate::handler::Handler;
+    pub use crate::invoker::Invoker;
+    pub use crate::mux::Mux;
+    pub use crate::packet::Validate;
+    pub use crate::server::Server;
+    pub use crate::stream::{Context, Stream, StreamExt};
+
+    pub use async_trait::async_trait;
+    pub use prost::Message as ProstMessage;
+}

package/srpc/message.rs

@@ -0,0 +1,9 @@
+//! Message trait for protobuf messages.
+
+use prost::Message as ProstMessage;
+
+/// Trait for protobuf messages that can be sent over starpc.
+pub trait Message: ProstMessage + Default + Send + Sync + 'static {}
+
+// Blanket implementation for all prost messages.
+impl<T: ProstMessage + Default + Send + Sync + 'static> Message for T {}