starpc 0.52.0 → 0.52.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starpc",
-  "version": "0.52.0",
+  "version": "0.52.2",
   "description": "Streaming protobuf RPC service protocol over any two-way channel.",
   "license": "MIT",
   "author": {
@@ -68,12 +68,12 @@
     "deps": "depcheck --ignores 'bufferutil,utf-8-validate,rimraf,starpc,@aptre/protobuf-es-lite,tsx'",
     "codegen": "bun run gen",
     "ci": "bun run build && bun run lint:js && bun run lint:go",
-    "format": "bun run format:js && bun run format:go && bun run format:config",
+    "format": "bun run format:js && bun run format:go && bun run format:python && bun run format:config",
     "format:config": "oxfmt '*.json' '.github/**/*.json' '.github/**/*.yml' '.oxfmtrc.json' 'tsconfig.json'",
     "format:go": "bun run go:aptre -- format",
     "format:js": "oxfmt './{srpc,echo,e2e,integration,rpcstream,cmd,mock,scripts}/**/*.{ts,tsx,js,mjs,html,css,scss}' '*.{ts,tsx,js,mjs}'",
-    "gen": "bun run go:aptre -- generate && bun run format",
-    "gen:force": "bun run go:aptre -- generate --force && bun run format",
+    "gen": "bun run build && bun run go:aptre -- generate && bun run format",
+    "gen:force": "bun run build && bun run go:aptre -- generate --force && bun run format",
     "test": "bun run test:js && bun run test:go",
     "test:go": "bun run go:aptre -- test",
     "test:cpp": "mkdir -p build && cd build && cmake -G Ninja .. -DCMAKE_BUILD_TYPE=Release && cmake --build . --parallel && ctest --output-on-failure",
@@ -100,7 +100,8 @@
     "release:version": "bun scripts/release-version.ts patch",
     "release:version:minor": "bun scripts/release-version.ts minor",
     "release:commit": "version=$(bun -e 'console.log(require(\"./package.json\").version)') && git reset && git add package.json Cargo.toml && git commit -s -m \"release: v$version\" && git tag \"v$version\"",
-    "release:publish": "git push && git push --tags"
+    "release:publish": "git push && git push --tags",
+    "format:python": "files=$(find echo mock -type f \\( -name '*_srpc.py' -o -name '*_srpc.pyi' \\)); if [ -n \"$files\" ]; then uv run ruff check --fix --ignore UP026 $files && uv run ruff format $files; fi"
   },
   "preferUnplugged": true,
   "lint-staged": {
@@ -138,5 +139,18 @@
   },
   "overrides": {
     "@aptre/protobuf-es-lite": "1.1.1"
+  },
+  "aptre": {
+    "languages": [
+      "go",
+      "ts",
+      "cpp",
+      "rust",
+      "python"
+    ],
+    "rpc": [
+      "starpc",
+      "starpc-python"
+    ]
   }
 }

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`.

package/srpc/accept.go

@@ -7,14 +7,20 @@ import (
 	"github.com/libp2p/go-yamux/v5"
 )
 
-// AcceptMuxedListener accepts incoming connections from a net.Listener.
-//
-// Uses the default yamux muxer.
-// If yamux conf is nil, uses the defaults.
+// AcceptMuxedListener accepts connections until ctx is canceled or the listener
+// fails. Cancellation closes lis to interrupt Accept. A nil yamuxConf uses defaults.
 func AcceptMuxedListener(ctx context.Context, lis net.Listener, srv *Server, yamuxConf *yamux.Config) error {
+	// Interrupt a blocked Accept when its serving context ends.
+	stop := context.AfterFunc(ctx, func() { _ = lis.Close() })
+	defer stop()
+
+	// Transfer accepted connections to the server and release rejected ones.
 	for {
 		nc, err := lis.Accept()
 		if err != nil {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
 			return err
 		}
 

package/srpc/accept_test.go

@@ -0,0 +1,25 @@
+package srpc
+
+import (
+	"context"
+	"errors"
+	"net"
+	"testing"
+)
+
+func TestAcceptMuxedListenerCancellation(t *testing.T) {
+	// An idle listener must not retain a blocked Accept after cancellation.
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = listener.Close() })
+	ctx, cancel := context.WithCancel(t.Context())
+	t.Cleanup(cancel)
+	done := make(chan error, 1)
+	go func() { done <- AcceptMuxedListener(ctx, listener, nil, nil) }()
+	cancel()
+	if err := <-done; !errors.Is(err, context.Canceled) {
+		t.Fatalf("listener cancellation returned %v", err)
+	}
+}