starpc 0.52.0 → 0.52.2

package/srpc/invoker.rs

@@ -10,59 +10,17 @@ use std::sync::Arc;
 use crate::error::Result;
 use crate::stream::Stream;
 
-/// Trait for invoking RPC methods.
+/// Dispatches incoming RPC calls to a handler implementation.
 ///
-/// 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)),
-///         }
-///     }
-/// }
-/// ```
+/// The Mux implements this trait to route calls by service and method ID.
+/// `invoke_method` returns `(found, result)`, letting a caller distinguish a
+/// method that was not found (`(false, Err(Error::Unimplemented))`) from one
+/// that was found and failed (`(true, Err(...))`).
 #[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
+    /// Invokes the RPC method, consuming `stream` whether or not the method
+    /// is found. Returns whether the method was handled and the invocation's
+    /// result.
     async fn invoke_method(
         &self,
         service_id: &str,
@@ -157,7 +115,9 @@ mod tests {
 
     #[tokio::test]
     async fn test_invoker_found() {
-        let invoker = TestInvoker { should_handle: true };
+        let invoker = TestInvoker {
+            should_handle: true,
+        };
         let (found, result) = invoker
             .invoke_method("svc", "method", Box::new(MockStream))
             .await;
@@ -181,7 +141,9 @@ mod tests {
 
     #[tokio::test]
     async fn test_arc_invoker() {
-        let invoker: Arc<dyn Invoker> = Arc::new(TestInvoker { should_handle: true });
+        let invoker: Arc<dyn Invoker> = Arc::new(TestInvoker {
+            should_handle: true,
+        });
         let (found, result) = invoker
             .invoke_method("svc", "method", Box::new(MockStream))
             .await;

package/srpc/lib.rs

@@ -57,6 +57,7 @@
 //! This format is compatible with the Go and TypeScript implementations.
 
 pub mod client;
+pub mod client_invoker;
 pub mod codec;
 pub mod error;
 pub mod handler;
@@ -82,6 +83,7 @@ pub mod yamux;
 
 // Re-exports for convenience.
 pub use client::{BoxClient, Client, OpenStream, SrpcClient};
+pub use client_invoker::ClientInvoker;
 pub use codec::{PacketCodec, MAX_MESSAGE_SIZE};
 pub use error::{Error, Result};
 pub use handler::{BoxHandler, Handler};

package/srpc/message.hpp

@@ -6,23 +6,28 @@
 
 namespace starpc {
 
-// Message is the interface for protobuf messages.
-// Matches Go Message interface in message.go
-// In C++, we use google::protobuf::MessageLite as the base.
+/*
+ * Message is the wire-message type handed across the RPC boundary. It aliases
+ * protobuf's MessageLite, matching the Go Message interface in message.go.
+ */
 using Message = google::protobuf::MessageLite;
 
-// MarshalVT serializes the message to bytes.
-// (VT suffix matches vtprotobuf convention used in Go)
-inline bool MarshalVT(const Message &msg, std::string *out) {
-  return msg.SerializeToString(out);
+/* MarshalVT serializes msg into out and reports parse success. */
+inline bool MarshalVT(const Message &msg, std::string *out)
+{
+	return msg.SerializeToString(out);
 }
 
-// UnmarshalVT deserializes the message from bytes.
-inline bool UnmarshalVT(Message *msg, const std::string &data) {
-  return msg->ParseFromString(data);
+/* UnmarshalVT parses data into msg and reports success. */
+inline bool UnmarshalVT(Message *msg, const std::string &data)
+{
+	return msg->ParseFromString(data);
 }
 
-// SizeVT returns the serialized size of the message.
-inline size_t SizeVT(const Message &msg) { return msg.ByteSizeLong(); }
+/* SizeVT returns the serialized size of msg in bytes. */
+inline size_t SizeVT(const Message &msg)
+{
+	return msg.ByteSizeLong();
+}
 
 } // namespace starpc

package/srpc/msg-stream.go

@@ -72,6 +72,7 @@ func (r *MsgStream) MsgRecv(msg Message) error {
 }
 
 // CloseSend signals to the remote that we will no longer send any messages.
+// A write error leaves received messages and the call outcome to MsgRecv.
 func (r *MsgStream) CloseSend() error {
 	return r.rw.WriteCallData(nil, false, true, nil)
 }

package/srpc/msg-stream.hpp

@@ -1,86 +1,133 @@
 #pragma once
 
-#include <functional>
-#include <string>
-
 #include "errors.hpp"
 #include "message.hpp"
 #include "stream.hpp"
 
+#include <atomic>
+#include <functional>
+#include <string>
+
 namespace starpc {
 
-// MsgStreamRw is the read-write interface for MsgStream.
-// Matches Go MsgStreamRw interface in msg-stream.go
+/*
+ * MsgStreamRw is the call-state side of MsgStream: it reads and writes one
+ * call's messages. Matches the Go msgStreamRw interface.
+ */
 class MsgStreamRw {
 public:
-  virtual ~MsgStreamRw() = default;
+	virtual ~MsgStreamRw() = default;
 
-  // ReadOne reads a single message and returns.
-  // Returns EOF_ if the stream ended.
-  virtual Error ReadOne(std::string *out) = 0;
+	/* RemoteErrorMessage returns the peer's retained diagnostic, if any. */
+	virtual std::string RemoteErrorMessage() const
+	{
+		return {};
+	}
 
-  // WriteCallData writes a call data packet.
-  virtual Error WriteCallData(const std::string &data, bool data_is_zero,
-                              bool complete, Error err) = 0;
+	/*
+	 * ReadOne returns the next message in out. Returns EOF_ after the
+	 * call completes and Canceled after local cancellation.
+	 */
+	virtual Error ReadOne(std::string *out) = 0;
 
-  // WriteCallCancel writes a call cancel (close) packet.
-  virtual Error WriteCallCancel() = 0;
+	/*
+	 * WriteCallData writes one data packet. data_is_zero marks an
+	 * intentionally empty message; complete ends the sending side; err
+	 * carries the terminal verdict.
+	 */
+	virtual Error WriteCallData(const std::string &data, bool data_is_zero,
+				    bool complete, Error err) = 0;
+
+	/* WriteCallCancel cancels the call on the remote. */
+	virtual Error WriteCallCancel() = 0;
 };
 
-// MsgStream implements the stream interface passed to implementations.
-// Matches Go MsgStream struct in msg-stream.go
+/*
+ * MsgStream is the Stream handed to handlers: it serializes messages over a
+ * MsgStreamRw and closes the call when the handler is done.
+ */
 class MsgStream : public Stream {
 public:
-  // Constructor matching NewMsgStream in Go
-  MsgStream(MsgStreamRw *rw, std::function<void()> close_cb)
-      : rw_(rw), close_cb_(std::move(close_cb)) {}
-
-  // MsgSend sends the message to the remote.
-  Error MsgSend(const Message &msg) override {
-    std::string msg_data;
-    if (!msg.SerializeToString(&msg_data)) {
-      return Error::InvalidMessage;
-    }
-    return rw_->WriteCallData(msg_data, msg_data.empty(), false, Error::OK);
-  }
-
-  // MsgRecv receives an incoming message from the remote.
-  Error MsgRecv(Message *msg) override {
-    std::string data;
-    Error err = rw_->ReadOne(&data);
-    if (err != Error::OK) {
-      return err;
-    }
-    if (!msg->ParseFromString(data)) {
-      return Error::InvalidMessage;
-    }
-    return Error::OK;
-  }
-
-  // CloseSend signals to the remote that we will no longer send any messages.
-  Error CloseSend() override {
-    return rw_->WriteCallData("", false, true, Error::OK);
-  }
-
-  // Close closes the stream.
-  Error Close() override {
-    Error err = rw_->WriteCallCancel();
-    if (close_cb_) {
-      close_cb_();
-    }
-    return err;
-  }
+	/*
+	 * MsgStream borrows rw; it must outlive the stream. close_cb, when
+	 * set, replaces the cancel write on Close; stop carries the call's
+	 * cancellation to the handler.
+	 */
+	MsgStream(MsgStreamRw *rw, std::function<void()> close_cb,
+		  std::stop_token stop = {})
+		: rw(rw),
+		  close_cb(std::move(close_cb)),
+		  stop(stop)
+	{
+	}
+
+	std::stop_token StopToken() const override
+	{
+		return stop;
+	}
+	std::string RemoteErrorMessage() const override
+	{
+		return rw->RemoteErrorMessage();
+	}
+
+	Error MsgSend(const Message &msg) override
+	{
+		std::string msg_data;
+		if (!msg.SerializeToString(&msg_data))
+			return Error::InvalidMessage;
+		return rw->WriteCallData(msg_data, msg_data.empty(), false,
+					 Error::OK);
+	}
+
+	Error MsgRecv(Message *msg) override
+	{
+		std::string data;
+		Error err = rw->ReadOne(&data);
+		if (err != Error::OK)
+			return err;
+		if (!msg->ParseFromString(data))
+			return Error::InvalidMessage;
+		return Error::OK;
+	}
+
+	/*
+	 * CloseSend half-closes the sending side. See Stream::CloseSend for
+	 * why its failure leaves the outcome to MsgRecv.
+	 */
+	Error CloseSend() override
+	{
+		return rw->WriteCallData("", false, true, Error::OK);
+	}
+
+	/*
+	 * Close ends the call once: through close_cb when the call is shared
+	 * with a transport, otherwise by writing cancel to the remote.
+	 */
+	Error Close() override
+	{
+		if (closed.exchange(true))
+			return Error::OK;
+		if (close_cb) {
+			close_cb();
+			return Error::OK;
+		}
+		return rw->WriteCallCancel();
+	}
 
 private:
-  MsgStreamRw *rw_;
-  std::function<void()> close_cb_;
+	/* rw is borrowed; the caller owns it. */
+	MsgStreamRw *rw;
+	std::function<void()> close_cb;
+	std::stop_token stop;
+	std::atomic<bool> closed{false};
 };
 
-// NewMsgStream constructs a new Stream with a MsgStreamRw.
-// Matches Go NewMsgStream function in msg-stream.go
+/* NewMsgStream constructs a Stream over rw. */
 inline std::unique_ptr<MsgStream> NewMsgStream(MsgStreamRw *rw,
-                                               std::function<void()> close_cb) {
-  return std::make_unique<MsgStream>(rw, std::move(close_cb));
+					       std::function<void()> close_cb,
+					       std::stop_token stop = {})
+{
+	return std::make_unique<MsgStream>(rw, std::move(close_cb), stop);
 }
 
 } // namespace starpc

package/srpc/mux.cpp

@@ -1,109 +1,109 @@
 //go:build deps_only
 
 #include "mux.hpp"
+
 #include <mutex>
+#include <shared_mutex>
 
 namespace starpc {
 
 Mux::Mux(std::vector<Invoker *> fallback_invokers)
-    : fallback_(std::move(fallback_invokers)) {}
+	: fallback(std::move(fallback_invokers))
+{
+}
 
-Error Mux::Register(Handler *handler) {
-  const std::string &service_id = handler->GetServiceID();
-  auto method_ids = handler->GetMethodIDs();
+Error Mux::Register(Handler *handler)
+{
+	const std::string &service_id = handler->GetServiceID();
+	auto method_ids = handler->GetMethodIDs();
 
-  if (service_id.empty()) {
-    return Error::EmptyServiceID;
-  }
+	if (service_id.empty())
+		return Error::EmptyServiceID;
 
-  std::unique_lock<std::shared_mutex> lock(mtx_);
+	std::unique_lock<std::shared_mutex> lock(mu);
 
-  auto &service_methods = services_[service_id];
-  for (const auto &method_id : method_ids) {
-    if (!method_id.empty()) {
-      service_methods[method_id] = handler;
-    }
-  }
+	auto &service_methods = services[service_id];
+	for (const auto &method_id : method_ids) {
+		if (!method_id.empty())
+			service_methods[method_id] = handler;
+	}
 
-  return Error::OK;
+	return Error::OK;
 }
 
-bool Mux::HasService(const std::string &service_id) const {
-  if (service_id.empty()) {
-    return false;
-  }
+bool Mux::HasService(const std::string &service_id) const
+{
+	if (service_id.empty())
+		return false;
 
-  std::shared_lock<std::shared_mutex> lock(mtx_);
-  auto it = services_.find(service_id);
-  return it != services_.end() && !it->second.empty();
+	std::shared_lock<std::shared_mutex> lock(mu);
+	auto it = services.find(service_id);
+	return it != services.end() && !it->second.empty();
 }
 
 bool Mux::HasServiceMethod(const std::string &service_id,
-                           const std::string &method_id) const {
-  if (service_id.empty() || method_id.empty()) {
-    return false;
-  }
-
-  std::shared_lock<std::shared_mutex> lock(mtx_);
-  auto svc_it = services_.find(service_id);
-  if (svc_it == services_.end()) {
-    return false;
-  }
-
-  for (const auto &[mid, handler] : svc_it->second) {
-    for (const auto &handler_method : handler->GetMethodIDs()) {
-      if (handler_method == method_id) {
-        return true;
-      }
-    }
-  }
-
-  return false;
+			   const std::string &method_id) const
+{
+	if (service_id.empty() || method_id.empty())
+		return false;
+
+	std::shared_lock<std::shared_mutex> lock(mu);
+	auto svc_it = services.find(service_id);
+	if (svc_it == services.end())
+		return false;
+
+	for (const auto &[mid, handler] : svc_it->second) {
+		for (const auto &handler_method : handler->GetMethodIDs()) {
+			if (handler_method == method_id)
+				return true;
+		}
+	}
+
+	return false;
 }
 
 std::pair<bool, Error> Mux::InvokeMethod(const std::string &service_id,
-                                         const std::string &method_id,
-                                         Stream *strm) {
-  Handler *handler = nullptr;
-
-  {
-    std::shared_lock<std::shared_mutex> lock(mtx_);
-
-    if (service_id.empty()) {
-      // If service string is empty, search all services
-      for (const auto &[svc_id, svc_methods] : services_) {
-        auto it = svc_methods.find(method_id);
-        if (it != svc_methods.end()) {
-          handler = it->second;
-          break;
-        }
-      }
-    } else {
-      auto svc_it = services_.find(service_id);
-      if (svc_it != services_.end()) {
-        auto method_it = svc_it->second.find(method_id);
-        if (method_it != svc_it->second.end()) {
-          handler = method_it->second;
-        }
-      }
-    }
-  }
-
-  if (handler != nullptr) {
-    return handler->InvokeMethod(service_id, method_id, strm);
-  }
-
-  // Try fallback invokers
-  for (auto *invoker : fallback_) {
-    if (invoker != nullptr) {
-      auto [handled, err] = invoker->InvokeMethod(service_id, method_id, strm);
-      if (err != Error::OK || handled) {
-        return {handled, err};
-      }
-    }
-  }
-
-  return {false, Error::OK};
+					 const std::string &method_id,
+					 Stream *strm)
+{
+	Handler *handler = nullptr;
+
+	/* Find the registered handler outside any handler call. */
+	{
+		std::shared_lock<std::shared_mutex> lock(mu);
+
+		if (service_id.empty()) {
+			for (const auto &[svc_id, svc_methods] : services) {
+				auto it = svc_methods.find(method_id);
+				if (it != svc_methods.end()) {
+					handler = it->second;
+					break;
+				}
+			}
+		} else {
+			auto svc_it = services.find(service_id);
+			if (svc_it != services.end()) {
+				auto method_it = svc_it->second.find(method_id);
+				if (method_it != svc_it->second.end())
+					handler = method_it->second;
+			}
+		}
+	}
+
+	if (handler != nullptr)
+		return handler->InvokeMethod(service_id, method_id, strm);
+
+	/* Try each fallback invoker in order. */
+	for (auto *invoker : fallback) {
+		if (invoker == nullptr)
+			continue;
+		auto [handled, err] =
+			invoker->InvokeMethod(service_id, method_id, strm);
+		if (err != Error::OK || handled)
+			return {handled, err};
+	}
+
+	return {false, Error::OK};
 }
 
 } // namespace starpc

package/srpc/mux.hpp

@@ -1,64 +1,74 @@
 #pragma once
 
+#include "errors.hpp"
+#include "handler.hpp"
+#include "invoker.hpp"
+
 #include <shared_mutex>
 #include <string>
 #include <unordered_map>
 #include <vector>
 
-#include "errors.hpp"
-#include "handler.hpp"
-#include "invoker.hpp"
-
 namespace starpc {
 
-// Mux contains a set of <service, method> handlers.
-// Matches Go Mux interface in mux.go
+/*
+ * Mux dispatches calls to registered handlers and falls back to a list of
+ * invokers when no handler matches. Matches the Go Mux in mux.go.
+ */
 class Mux : public Invoker, public QueryableInvoker {
 public:
-  // Constructor matching NewMux in Go
-  explicit Mux(std::vector<Invoker *> fallback_invokers = {});
-  ~Mux() override = default;
+	/*
+	 * Mux consults fallback_invokers, in order, when no registered
+	 * handler matches. The invokers are borrowed and must outlive the
+	 * mux.
+	 */
+	explicit Mux(std::vector<Invoker *> fallback_invokers = {});
+	~Mux() override = default;
 
-  // Register registers a new RPC method handler (service).
-  // Matches Go Register in mux.go
-  Error Register(Handler *handler);
+	/*
+	 * Register maps the handler's service and method IDs to it. An empty
+	 * service ID fails; empty method IDs are skipped.
+	 */
+	Error Register(Handler *handler);
 
-  // InvokeMethod invokes the method matching the service & method ID.
-  // Returns {found, error} - found is false if method not found.
-  // If service string is empty, ignore it.
-  // Matches Go InvokeMethod in mux.go
-  std::pair<bool, Error> InvokeMethod(const std::string &service_id,
-                                      const std::string &method_id,
-                                      Stream *strm) override;
+	/*
+	 * InvokeMethod runs the registered handler for the IDs and reports
+	 * whether it found one. An empty service_id searches every service.
+	 * Unhandled calls go to the fallback invokers.
+	 */
+	std::pair<bool, Error> InvokeMethod(const std::string &service_id,
+					    const std::string &method_id,
+					    Stream *strm) override;
 
-  // HasService checks if the service ID exists in the handlers.
-  // Matches Go HasService in mux.go
-  bool HasService(const std::string &service_id) const override;
+	/* HasService reports whether any handler registered service_id. */
+	bool HasService(const std::string &service_id) const override;
 
-  // HasServiceMethod checks if <service-id, method-id> exists in the handlers.
-  // Matches Go HasServiceMethod in mux.go
-  bool HasServiceMethod(const std::string &service_id,
-                        const std::string &method_id) const override;
+	/*
+	 * HasServiceMethod reports whether a registered handler for
+	 * service_id serves method_id.
+	 */
+	bool HasServiceMethod(const std::string &service_id,
+			      const std::string &method_id) const override;
 
 private:
-  // Mapping from method id to handler
-  using MuxMethods = std::unordered_map<std::string, Handler *>;
+	/* methods maps one method ID to the handler that registered it. */
+	using methods = std::unordered_map<std::string, Handler *>;
 
-  // Fallback invokers
-  std::vector<Invoker *> fallback_;
+	/* fallback invokers are borrowed; the caller owns them. */
+	std::vector<Invoker *> fallback;
 
-  // Read-write mutex guards services_
-  mutable std::shared_mutex mtx_;
+	/* mu guards services. */
+	mutable std::shared_mutex mu;
 
-  // Services contains a mapping from services to handlers
-  std::unordered_map<std::string, MuxMethods> services_;
+	/* services maps each service ID to its method table. */
+	std::unordered_map<std::string, methods> services;
 };
 
-// NewMux constructs a new Mux.
-// Matches Go NewMux function in mux.go
+/* NewMux constructs a Mux with the given fallback invokers. */
 inline std::unique_ptr<Mux>
-NewMux(std::vector<Invoker *> fallback_invokers = {}) {
-  return std::make_unique<Mux>(std::move(fallback_invokers));
+NewMux(std::vector<Invoker *> fallback_invokers = {})
+{
+	return std::make_unique<Mux>(std::move(fallback_invokers));
 }
 
 } // namespace starpc