starpc 0.52.1 → 0.52.2

package/integration/cross-language/cpp-server.cpp

@@ -1,7 +1,14 @@
 //go:build deps_only
 
-// C++ TCP integration server for cross-language testing.
-// Listens on TCP, handles one RPC per connection using length-prefixed packets.
+/*
+ * C++ TCP integration server for cross-language testing: it listens on TCP
+ * and serves one RPC per connection over length-prefixed packets.
+ */
+
+#include "echo/echo_srpc.pb.hpp"
+#include "rpcstream/rpcstream.hpp"
+#include "srpc/rpcproto.pb.h"
+#include "srpc/starpc.hpp"
 
 #include <arpa/inet.h>
 #include <csignal>
@@ -13,209 +20,238 @@
 #include <sys/socket.h>
 #include <thread>
 #include <unistd.h>
-
-#include "echo/echo_srpc.pb.hpp"
-#include "rpcstream/rpcstream.hpp"
-#include "srpc/rpcproto.pb.h"
-#include "srpc/starpc.hpp"
+#include <vector>
 
 namespace {
 
-// ReadFull reads exactly n bytes from fd.
-bool ReadFull(int fd, void *buf, size_t n) {
-  size_t total = 0;
-  while (total < n) {
-    ssize_t r = read(fd, static_cast<char *>(buf) + total, n - total);
-    if (r <= 0)
-      return false;
-    total += r;
-  }
-  return true;
+/* ReadFull reads exactly n bytes from fd, reporting short reads as false. */
+bool ReadFull(int fd, void *buf, size_t n)
+{
+	size_t total = 0;
+	while (total < n) {
+		ssize_t r =
+			read(fd, static_cast<char *>(buf) + total, n - total);
+		if (r <= 0)
+			return false;
+		total += r;
+	}
+	return true;
 }
 
-// WriteFull writes exactly n bytes to fd.
-bool WriteFull(int fd, const void *buf, size_t n) {
-  size_t total = 0;
-  while (total < n) {
-    ssize_t w = write(fd, static_cast<const char *>(buf) + total, n - total);
-    if (w <= 0)
-      return false;
-    total += w;
-  }
-  return true;
+/* WriteFull writes exactly n bytes to fd, reporting short writes as false. */
+bool WriteFull(int fd, const void *buf, size_t n)
+{
+	size_t total = 0;
+	while (total < n) {
+		ssize_t w = write(fd, static_cast<const char *>(buf) + total,
+				  n - total);
+		if (w <= 0)
+			return false;
+		total += w;
+	}
+	return true;
 }
 
-// TcpPacketWriter writes length-prefixed packets to a TCP socket.
+/*
+ * TcpPacketWriter writes length-prefixed packets to a TCP socket. The fd is
+ * borrowed and closed by the connection handler, not the writer.
+ */
 class TcpPacketWriter : public starpc::PacketWriter {
 public:
-  explicit TcpPacketWriter(int fd) : fd_(fd) {}
-
-  starpc::Error WritePacket(const srpc::Packet &pkt) override {
-    std::lock_guard<std::mutex> lock(mtx_);
-    std::string data;
-    if (!pkt.SerializeToString(&data))
-      return starpc::Error::InvalidMessage;
-
-    uint32_t len = static_cast<uint32_t>(data.size());
-    // Write LE uint32 length prefix.
-    if (!WriteFull(fd_, &len, 4))
-      return starpc::Error::EOF_;
-    if (!WriteFull(fd_, data.data(), data.size()))
-      return starpc::Error::EOF_;
-    return starpc::Error::OK;
-  }
-
-  starpc::Error Close() override {
-    shutdown(fd_, SHUT_WR);
-    return starpc::Error::OK;
-  }
+	explicit TcpPacketWriter(int fd)
+		: fd(fd)
+	{
+	}
+
+	starpc::Error WritePacket(const srpc::Packet &pkt) override
+	{
+		std::lock_guard<std::mutex> lock(mu);
+
+		std::string data;
+		if (!pkt.SerializeToString(&data))
+			return starpc::Error::InvalidMessage;
+
+		/* The length prefix is a little-endian uint32. */
+		uint32_t len = static_cast<uint32_t>(data.size());
+		if (!WriteFull(fd, &len, 4))
+			return starpc::Error::EOF_;
+		if (!WriteFull(fd, data.data(), data.size()))
+			return starpc::Error::EOF_;
+		return starpc::Error::OK;
+	}
+
+	starpc::Error Close() override
+	{
+		shutdown(fd, SHUT_WR);
+		return starpc::Error::OK;
+	}
 
 private:
-  int fd_;
-  std::mutex mtx_;
+	int fd;
+	std::mutex mu;
 };
 
-// EchoServerImpl implements the echo service.
+/* EchoServerImpl implements the echo service under test. */
 class EchoServerImpl : public echo::SRPCEchoerServer {
 public:
-  starpc::Error Echo(const echo::EchoMsg &req, echo::EchoMsg *resp) override {
-    resp->set_body(req.body());
-    return starpc::Error::OK;
-  }
-
-  starpc::Error
-  EchoServerStream(const echo::EchoMsg &req,
-                   echo::SRPCEchoer_EchoServerStreamStream *strm) override {
-    for (int i = 0; i < 5; i++) {
-      echo::EchoMsg msg;
-      msg.set_body(req.body());
-      starpc::Error err = strm->Send(msg);
-      if (err != starpc::Error::OK)
-        return err;
-    }
-    return starpc::Error::OK;
-  }
-
-  starpc::Error EchoClientStream(echo::SRPCEchoer_EchoClientStreamStream *strm,
-                                 echo::EchoMsg *resp) override {
-    echo::EchoMsg msg;
-    starpc::Error err = strm->Recv(&msg);
-    if (err != starpc::Error::OK)
-      return err;
-    resp->set_body(msg.body());
-    return starpc::Error::OK;
-  }
-
-  starpc::Error
-  EchoBidiStream(echo::SRPCEchoer_EchoBidiStreamStream *strm) override {
-    // Send initial message (matches Go server behavior).
-    echo::EchoMsg init;
-    init.set_body("hello from server");
-    starpc::Error err = strm->Send(init);
-    if (err != starpc::Error::OK)
-      return err;
-
-    while (true) {
-      echo::EchoMsg msg;
-      err = strm->Recv(&msg);
-      if (err == starpc::Error::EOF_)
-        break;
-      if (err != starpc::Error::OK)
-        return err;
-      err = strm->Send(msg);
-      if (err != starpc::Error::OK)
-        return err;
-    }
-    return starpc::Error::OK;
-  }
-
-  starpc::Error RpcStream(echo::SRPCEchoer_RpcStreamStream *) override {
-    return starpc::Error::Unimplemented;
-  }
-
-  starpc::Error DoNothing(const google::protobuf::Empty &,
-                          google::protobuf::Empty *) override {
-    return starpc::Error::OK;
-  }
+	starpc::Error Echo(const echo::EchoMsg &req,
+			   echo::EchoMsg *resp) override
+	{
+		resp->set_body(req.body());
+		return starpc::Error::OK;
+	}
+
+	starpc::Error
+	EchoServerStream(const echo::EchoMsg &req,
+			 echo::SRPCEchoer_EchoServerStreamStream *strm) override
+	{
+		for (int i = 0; i < 5; i++) {
+			echo::EchoMsg msg;
+			msg.set_body(req.body());
+			starpc::Error err = strm->Send(msg);
+			if (err != starpc::Error::OK)
+				return err;
+		}
+		return starpc::Error::OK;
+	}
+
+	starpc::Error
+	EchoClientStream(echo::SRPCEchoer_EchoClientStreamStream *strm,
+			 echo::EchoMsg *resp) override
+	{
+		echo::EchoMsg msg;
+		starpc::Error err = strm->Recv(&msg);
+		if (err != starpc::Error::OK)
+			return err;
+		resp->set_body(msg.body());
+		return starpc::Error::OK;
+	}
+
+	starpc::Error
+	EchoBidiStream(echo::SRPCEchoer_EchoBidiStreamStream *strm) override
+	{
+		/* Send the initial message the other clients expect. */
+		echo::EchoMsg init;
+		init.set_body("hello from server");
+		starpc::Error err = strm->Send(init);
+		if (err != starpc::Error::OK)
+			return err;
+
+		while (true) {
+			echo::EchoMsg msg;
+			err = strm->Recv(&msg);
+			if (err == starpc::Error::EOF_)
+				break;
+			if (err != starpc::Error::OK)
+				return err;
+			err = strm->Send(msg);
+			if (err != starpc::Error::OK)
+				return err;
+		}
+		return starpc::Error::OK;
+	}
+
+	starpc::Error RpcStream(echo::SRPCEchoer_RpcStreamStream *) override
+	{
+		return starpc::Error::Unimplemented;
+	}
+
+	starpc::Error DoNothing(const google::protobuf::Empty &,
+				google::protobuf::Empty *) override
+	{
+		return starpc::Error::OK;
+	}
 };
 
-// HandleConnection handles one TCP connection (one RPC).
-void HandleConnection(int fd, starpc::Mux *mux) {
-  auto writer = std::make_unique<TcpPacketWriter>(fd);
-  auto serverRpc = starpc::NewServerRPC(mux, writer.get());
-
-  while (true) {
-    // Read 4-byte LE uint32 length prefix.
-    uint32_t len = 0;
-    if (!ReadFull(fd, &len, 4))
-      break;
-
-    // Read the packet data.
-    std::string data(len, '\0');
-    if (!ReadFull(fd, data.data(), len))
-      break;
-
-    starpc::Error err = serverRpc->HandlePacketData(data);
-    if (err != starpc::Error::OK && err != starpc::Error::Completed)
-      break;
-  }
-
-  close(fd);
+/*
+ * HandleConnection serves one TCP connection: it reads length-prefixed
+ * packets until the socket ends, then closes the fd.
+ */
+void HandleConnection(int fd, starpc::Mux *mux)
+{
+	auto writer = std::make_unique<TcpPacketWriter>(fd);
+	auto server_rpc = starpc::NewServerRPC(mux, writer.get());
+
+	while (true) {
+		/* The length prefix is a little-endian uint32. */
+		uint32_t len = 0;
+		if (!ReadFull(fd, &len, 4))
+			break;
+
+		std::string data(len, '\0');
+		if (!ReadFull(fd, data.data(), len))
+			break;
+
+		starpc::Error err = server_rpc->HandlePacketData(data);
+		if (err != starpc::Error::OK && err != starpc::Error::Completed)
+			break;
+	}
+
+	close(fd);
 }
 
 } // namespace
 
-int main() {
-  signal(SIGPIPE, SIG_IGN);
-
-  auto mux = starpc::NewMux();
-  EchoServerImpl server;
-  auto [handler, err] = echo::SRPCRegisterEchoer(mux.get(), &server);
-  (void)handler;
-  if (err != starpc::Error::OK) {
-    std::cerr << "register error: " << starpc::ErrorString(err) << std::endl;
-    return 1;
-  }
-
-  int sockfd = socket(AF_INET, SOCK_STREAM, 0);
-  if (sockfd < 0) {
-    std::cerr << "socket error" << std::endl;
-    return 1;
-  }
-
-  int opt = 1;
-  setsockopt(sockfd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
-
-  struct sockaddr_in addr {};
-  addr.sin_family = AF_INET;
-  addr.sin_port = 0; // OS-assigned port.
-  addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
-
-  if (bind(sockfd, reinterpret_cast<struct sockaddr *>(&addr), sizeof(addr)) <
-      0) {
-    std::cerr << "bind error" << std::endl;
-    close(sockfd);
-    return 1;
-  }
-
-  if (listen(sockfd, 10) < 0) {
-    std::cerr << "listen error" << std::endl;
-    close(sockfd);
-    return 1;
-  }
-
-  // Get the assigned port.
-  socklen_t addrLen = sizeof(addr);
-  getsockname(sockfd, reinterpret_cast<struct sockaddr *>(&addr), &addrLen);
-  std::cout << "LISTENING 127.0.0.1:" << ntohs(addr.sin_port) << std::endl;
-
-  while (true) {
-    int clientFd = accept(sockfd, nullptr, nullptr);
-    if (clientFd < 0)
-      break;
-    std::thread(HandleConnection, clientFd, mux.get()).detach();
-  }
-
-  close(sockfd);
-  return 0;
+int main()
+{
+	signal(SIGPIPE, SIG_IGN);
+
+	auto mux = starpc::NewMux();
+	EchoServerImpl server;
+	auto [handler, err] = echo::SRPCRegisterEchoer(mux.get(), &server);
+	(void)handler;
+	if (err != starpc::Error::OK) {
+		std::cerr << "register error: " << starpc::ErrorString(err)
+			  << std::endl;
+		return 1;
+	}
+
+	int sockfd = socket(AF_INET, SOCK_STREAM, 0);
+	if (sockfd < 0) {
+		std::cerr << "socket error" << std::endl;
+		return 1;
+	}
+
+	int opt = 1;
+	setsockopt(sockfd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
+
+	struct sockaddr_in addr{};
+	addr.sin_family = AF_INET;
+	addr.sin_port = 0; /* OS-assigned port. */
+	addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+
+	if (bind(sockfd, reinterpret_cast<struct sockaddr *>(&addr),
+		 sizeof(addr)) < 0) {
+		std::cerr << "bind error" << std::endl;
+		close(sockfd);
+		return 1;
+	}
+
+	if (listen(sockfd, 10) < 0) {
+		std::cerr << "listen error" << std::endl;
+		close(sockfd);
+		return 1;
+	}
+
+	/* Report the assigned port so the test driver can connect. */
+	socklen_t addr_len = sizeof(addr);
+	getsockname(sockfd, reinterpret_cast<struct sockaddr *>(&addr),
+		    &addr_len);
+	std::cout << "LISTENING 127.0.0.1:" << ntohs(addr.sin_port)
+		  << std::endl;
+
+	/* Connection threads borrow mux, so join them before it ends. */
+	std::vector<std::thread> connections;
+	while (true) {
+		int client_fd = accept(sockfd, nullptr, nullptr);
+		if (client_fd < 0)
+			break;
+		connections.emplace_back(HandleConnection, client_fd,
+					 mux.get());
+	}
+
+	close(sockfd);
+	for (auto &connection : connections)
+		connection.join();
+	return 0;
 }

package/mock/mock_srpc.pb.cpp

@@ -1,7 +1,7 @@
 //go:build deps_only
 
 // Code generated by protoc-gen-starpc-cpp. DO NOT EDIT.
-// protoc-gen-starpc-cpp version: v0.49.21
+// protoc-gen-starpc-cpp version: v0.52.2-0.20260903015026-8f335488f9dc+dirty
 // source: github.com/aperturerobotics/starpc/mock/mock.proto
 
 #include "mock_srpc.pb.hpp"

package/mock/mock_srpc.pb.hpp

@@ -1,7 +1,7 @@
 //go:build deps_only && cgo
 
 // Code generated by protoc-gen-starpc-cpp. DO NOT EDIT.
-// protoc-gen-starpc-cpp version: v0.49.21
+// protoc-gen-starpc-cpp version: v0.52.2-0.20260903015026-8f335488f9dc+dirty
 // source: github.com/aperturerobotics/starpc/mock/mock.proto
 
 #pragma once

package/mock/mock_srpc.pb.rs

@@ -1,9 +1,9 @@
 // Code generated by protoc-gen-starpc-rust. DO NOT EDIT.
-// protoc-gen-starpc-rust version: v0.49.21
+// protoc-gen-starpc-rust version: (devel)
 // source: github.com/aperturerobotics/starpc/mock/mock.proto
 
 #[allow(unused_imports)]
-use starpc::StreamExt;
+use starpc::StreamExt as _;
 
 /// Service ID for Mock.
 pub const MOCK_SERVICE_ID: &str = "e2e.mock.Mock";
@@ -30,7 +30,9 @@ impl<C: starpc::Client> MockClientImpl<C> {
 #[starpc::async_trait]
 impl<C: starpc::Client + 'static> MockClient for MockClientImpl<C> {
     async fn mock_request(&self, request: &MockMsg) -> starpc::Result<MockMsg> {
-        self.client.exec_call("e2e.mock.Mock", "MockRequest", request).await
+        self.client
+            .exec_call("e2e.mock.Mock", "MockRequest", request)
+            .await
     }
 }
 
@@ -41,9 +43,7 @@ pub trait MockServer: Send + Sync {
     async fn mock_request(&self, request: MockMsg) -> starpc::Result<MockMsg>;
 }
 
-const MOCK_METHOD_IDS: &[&str] = &[
-    "MockRequest",
-];
+const MOCK_METHOD_IDS: &[&str] = &["MockRequest"];
 
 /// Handler for Mock.
 pub struct MockHandler<S: MockServer> {
@@ -53,7 +53,9 @@ pub struct MockHandler<S: MockServer> {
 impl<S: MockServer + 'static> MockHandler<S> {
     /// Creates a new handler wrapping the server implementation.
     pub fn new(server: S) -> Self {
-        Self { server: std::sync::Arc::new(server) }
+        Self {
+            server: std::sync::Arc::new(server),
+        }
     }
 
     /// Creates a new handler with a shared server.
@@ -76,7 +78,7 @@ impl<S: MockServer + 'static> starpc::Invoker for MockHandler<S> {
                     Ok(r) => r,
                     Err(e) => return (true, Err(e)),
                 };
-                match self.server.mock_request(request).await {
+                match <S as MockServer>::mock_request(self.server.as_ref(), request).await {
                     Ok(response) => {
                         if let Err(e) = stream.msg_send(&response).await {
                             return (true, Err(e));
@@ -100,4 +102,3 @@ impl<S: MockServer + 'static> starpc::Handler for MockHandler<S> {
         MOCK_METHOD_IDS
     }
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starpc",
-  "version": "0.52.1",
+  "version": "0.52.2",
   "description": "Streaming protobuf RPC service protocol over any two-way channel.",
   "license": "MIT",
   "author": {

package/srpc/CMakeLists.txt

@@ -1,59 +1,4 @@
-cmake_minimum_required(VERSION 3.14)
+cmake_minimum_required(VERSION 3.24)
 
-# C++ starpc library
-# This builds the core srpc library
-
-set(STARPC_SOURCES
-    packet.cpp
-    common-rpc.cpp
-    client-rpc.cpp
-    server-rpc.cpp
-    mux.cpp
-    client.cpp
-    rpcproto.pb.cc
-)
-
-set(STARPC_HEADERS
-    starpc.hpp
-    errors.hpp
-    message.hpp
-    writer.hpp
-    packet.hpp
-    stream.hpp
-    msg-stream.hpp
-    common-rpc.hpp
-    client-rpc.hpp
-    server-rpc.hpp
-    invoker.hpp
-    handler.hpp
-    mux.hpp
-    client.hpp
-    rpcproto.pb.h
-)
-
-add_library(starpc ${STARPC_SOURCES})
-
-target_include_directories(starpc PUBLIC
-    ${CMAKE_CURRENT_SOURCE_DIR}/..
-    ${CMAKE_CURRENT_SOURCE_DIR}
-)
-
-target_compile_features(starpc PUBLIC cxx_std_17)
-
-# Link protobuf
-find_package(Protobuf REQUIRED)
-target_link_libraries(starpc PUBLIC protobuf::libprotobuf)
-
-# Link threads
-find_package(Threads REQUIRED)
-target_link_libraries(starpc PUBLIC Threads::Threads)
-
-# Install targets
-install(TARGETS starpc
-    ARCHIVE DESTINATION lib
-    LIBRARY DESTINATION lib
-)
-
-install(FILES ${STARPC_HEADERS}
-    DESTINATION include/srpc
-)
+# Keep the historical subdirectory entry point on the same complete target.
+add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/.. ${CMAKE_CURRENT_BINARY_DIR}/starpc)

package/srpc/README-cpp.md

@@ -0,0 +1,69 @@
+# Starpc C++
+
+Starpc provides generated C++ clients and handlers for unary and streaming
+protobuf RPCs. It uses the same packets as the Go, TypeScript, Rust, and Python
+implementations. C++20 and the protobuf runtime matching the generated headers
+are required.
+
+## Build
+
+```sh
+go mod vendor
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure --timeout 60
+```
+
+A parent project can use `add_subdirectory(path/to/starpc)` and link
+`starpc::starpc`. An existing `protobuf::libprotobuf` target is reused, including
+its include paths and compile definitions. Otherwise, set
+`STARPC_USE_SYSTEM_PROTOBUF=ON` to find an installed protobuf package, or vendor
+Go dependencies before configuring. Tests and examples default to off when
+Starpc is a subdirectory. The library includes the nested RPC messages even
+when examples are disabled.
+
+Generate service bindings with `protoc-gen-starpc-cpp`. The generated streaming
+wrappers expose `Send`, `Recv`, `Close`, `CloseSend`, and `StopToken` as applicable.
+See `echo/echo.proto` and its generated bindings for each RPC shape.
+
+## Connect a transport
+
+One Starpc call uses one ordered, bidirectional packet stream. A streaming RPC
+can carry successive commands and events over a single process connection.
+Independent concurrent calls require separate streams from the transport.
+
+A C++ server lends an `Invoker` and `PacketWriter` to `ServerRPC`, then feeds
+received packets to `HandlePacketData`. Call `HandleStreamClose` when input ends,
+including errors. Serialize those input callbacks. Destruction cancels the call
+and joins its handler before the borrowed objects can be released.
+
+For a client, supply an `OpenStreamFunc` to `NewClient`. Its returned writer must
+keep receive callbacks alive until destruction. `Close` must interrupt blocked
+transport reads and writes without waiting for those callbacks; destruction must
+join any receive thread. This permits a callback to close its own transport.
+
+Packet writers serialize their writes and allow `Close` concurrently with a
+write. Close is idempotent. A byte-stream transport uses a four-byte unsigned
+little-endian length followed by the serialized `srpc.Packet`, matching Go's
+`PacketReadWriter`. Reject empty frames and frames larger than 10,000,000 bytes
+before allocating their bodies. The process-pipe integration test demonstrates
+this framing with a Go client and a C++ child process.
+
+## Cancellation and completion
+
+`CloseSend` ends outgoing messages while allowing incoming replies. Once the
+request is written, the half-close is only a notice: it fails when the call
+already ended, so generated callers ignore its error and read the outcome with
+`MsgRecv`. Explicit remote completion becomes EOF after queued messages are
+read. A disconnected
+transport without completion returns `ClosedBeforeCompletion`. Remote errors
+return `RemoteError`; `CommonRPC::RemoteErrorMessage` retains the peer's text.
+
+Handlers performing work outside `Recv` must observe their stream's `StopToken`.
+Destroying a server waits for its handler to return; it cannot forcibly terminate
+application code that ignores cancellation. Dropping a client stream closes its
+transport and releases its receive thread. Nested RPCs release their service
+only after the nested handler returns.
+
+An unread C++ call is limited to 4 MiB or 1,024 queued messages, including empty
+messages. Exceeding either bound ends the call with `ResourceExhausted`.