starpc 0.52.0 → 0.52.2

package/srpc/common-rpc.ts

@@ -22,8 +22,10 @@ export class CommonRPC {
     objectMode: true,
   })
 
-  // _rpcDataSource is used to write to the rpc message source.
-  private readonly _rpcDataSource = pushable<Uint8Array>({
+  // _rpcDataSource queues incoming rpc messages and the terminal error.
+  // The error is queued as an item because ending a pushable with an error
+  // discards the messages it buffered.
+  private readonly _rpcDataSource = pushable<Uint8Array | Error>({
     objectMode: true,
   })
 
@@ -36,6 +38,8 @@ export class CommonRPC {
   private closed?: true | Error
   // remoteError records a remote error or transport failure.
   private remoteError?: Error
+  // remoteCompleted records that the remote sent a completion or an error.
+  private remoteCompleted = false
   // invocationController cancels the server invocation when the RPC closes.
   private readonly invocationController = new AbortController()
 
@@ -45,7 +49,7 @@ export class CommonRPC {
   constructor() {
     this.sink = this._createSink()
     this.source = this._source
-    this.rpcDataSource = this._rpcDataSource
+    this.rpcDataSource = this.readRpcData()
   }
 
   // isClosed returns one of: true (closed w/o error), Error (closed w/ error), or false (not closed).
@@ -53,6 +57,11 @@ export class CommonRPC {
     return this.closed ?? false
   }
 
+  // isRemoteCompleted reports whether the remote sent a completion or an error.
+  protected get isRemoteCompleted(): boolean {
+    return this.remoteCompleted
+  }
+
   // invocationSignal is canceled when the RPC closes.
   protected get invocationSignal(): AbortSignal {
     return this.invocationController.signal
@@ -214,12 +223,12 @@ export class CommonRPC {
       this.remoteError ??= remoteError
       this.invocationController.abort()
     }
-    if (packet.complete && !remoteError) {
-      this._rpcDataSource.end(remoteError)
-    } else if (remoteError) {
-      this._rpcDataSource.end(remoteError)
+    if (packet.complete || remoteError) {
+      this.remoteCompleted = true
+      this.endRpcData(remoteError)
     }
   }
+
   // handleCallCancel aborts the invocation and closes the call.
   public async handleCallCancel() {
     await this.close(new Error(ERR_RPC_ABORT))
@@ -244,7 +253,32 @@ export class CommonRPC {
     }
     this.writeDrainAbort.abort()
     this._source.end()
-    this._rpcDataSource.end(err)
+    this.endRpcData(err)
+  }
+
+  // endRpcData ends the rpc message source after its buffered messages,
+  // optionally with an error.
+  private endRpcData(err?: Error) {
+    if (err) {
+      this._rpcDataSource.push(err)
+    }
+    this._rpcDataSource.end()
+  }
+
+  // readRpcData yields the buffered rpc messages, then throws the terminal
+  // error, if any.
+  private async *readRpcData(): AsyncGenerator<Uint8Array> {
+    for await (const item of this._rpcDataSource) {
+      if (item instanceof Error) {
+        throw item
+      }
+      yield item
+    }
+  }
+
+  // handleSourceEnd handles the end of the incoming packet source.
+  protected async handleSourceEnd() {
+    // no-op
   }
 
   private _createSink(): Sink<Source<Packet>> {
@@ -259,6 +293,7 @@ export class CommonRPC {
             await this.handlePacket(msg)
           }
         }
+        await this.handleSourceEnd()
       } catch (err) {
         this.close(err as Error)
       }

package/srpc/common-rpc_test.go

@@ -504,3 +504,26 @@ func TestClientRPCCloseReportsALocalCancellation(t *testing.T) {
 		t.Fatalf("a close this side performed was blamed on the remote: %v", err)
 	}
 }
+
+func TestClientRPCCloseAfterRemoteCompletionKeepsTheResult(t *testing.T) {
+	writer := &closeCountingPacketWriter{}
+	rpc := NewClientRPC(context.Background(), "service", "method")
+	if err := rpc.Start(writer, false, nil); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+
+	// The remote answers and completes before this side closes the call, as
+	// when the RPC's own completion cancels a Start still writing CallStart.
+	if err := rpc.HandleCallData(&CallData{Data: []byte("ok"), Complete: true}); err != nil {
+		t.Fatalf("handle completion: %v", err)
+	}
+	rpc.Close()
+
+	data, err := rpc.ReadOne()
+	if err != nil || string(data) != "ok" {
+		t.Fatalf("read after a close of a completed call = %q, %v", data, err)
+	}
+	if _, err := rpc.ReadOne(); !errors.Is(err, io.EOF) {
+		t.Fatalf("read after the response reported %v, want the end of the stream", err)
+	}
+}

package/srpc/error.rs

@@ -52,6 +52,13 @@ pub enum Error {
     #[error("stream closed")]
     StreamClosed,
 
+    /// The stream closed without the remote sending a completion or an error.
+    ///
+    /// The call has no verdict: the handler may have finished with its answer
+    /// lost in the transport, or it may never have run.
+    #[error("stream closed before the remote reported completion")]
+    ClosedBeforeCompletion,
+
     /// The RPC was aborted.
     #[error("rpc aborted")]
     Aborted,
@@ -153,9 +160,19 @@ mod tests {
     #[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::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");
+        assert_eq!(
+            Error::ClosedBeforeCompletion.to_string(),
+            "stream closed before the remote reported completion"
+        );
+        assert_eq!(
+            Error::Remote("test error".into()).to_string(),
+            "remote error: test error"
+        );
     }
 
     #[test]

package/srpc/errors.hpp

@@ -5,67 +5,97 @@
 
 namespace starpc {
 
-// Error codes matching Go starpc errors (see errors.go)
+/*
+ * Error is the house error value. Every action returns one; OK is success.
+ * The codes mirror the Go starpc errors in errors.go; ErrorString holds each
+ * diagnostic text.
+ */
 enum class Error {
-  OK = 0,
-  Unimplemented, // ErrUnimplemented - RPC method was not implemented
-  Completed,     // ErrCompleted - unexpected packet after rpc was completed
-  UnrecognizedPacket, // ErrUnrecognizedPacket - unrecognized packet type
-  EmptyPacket,        // ErrEmptyPacket - invalid empty packet
-  InvalidMessage,     // ErrInvalidMessage - message failed to parse
-  EmptyMethodID,      // ErrEmptyMethodID - method id empty
-  EmptyServiceID,     // ErrEmptyServiceID - service id empty
-  NoAvailableClients, // ErrNoAvailableClients - no available rpc clients
-  NilWriter,          // ErrNilWriter - writer cannot be nil
-  Canceled,           // context.Canceled equivalent
-  EOF_,               // io.EOF equivalent (named EOF_ to avoid macro collision)
+	OK = 0,
+	Unimplemented, /* the RPC method was not implemented */
+	Completed,     /* unexpected packet after the RPC completed */
+	UnrecognizedPacket,
+	EmptyPacket,
+	InvalidMessage, /* the message failed to parse */
+	EmptyMethodID,
+	EmptyServiceID,
+	NoAvailableClients,
+	NilWriter,
+	Canceled, /* context.Canceled equivalent */
+	EOF_,	  /* io.EOF equivalent; named EOF_ to avoid the macro */
+	ClosedBeforeCompletion, /* the transport ended without a verdict */
+	ResourceExhausted, /* the receive queue or thread capacity was hit */
+	RemoteError, /* RemoteErrorMessage retains the peer's diagnostic */
 };
 
-// Convert Error to string (matches Go error messages)
-inline const char *ErrorString(Error err) {
-  switch (err) {
-  case Error::OK:
-    return "ok";
-  case Error::Unimplemented:
-    return "unimplemented";
-  case Error::Completed:
-    return "unexpected packet after rpc was completed";
-  case Error::UnrecognizedPacket:
-    return "unrecognized packet type";
-  case Error::EmptyPacket:
-    return "invalid empty packet";
-  case Error::InvalidMessage:
-    return "invalid message";
-  case Error::EmptyMethodID:
-    return "method id empty";
-  case Error::EmptyServiceID:
-    return "service id empty";
-  case Error::NoAvailableClients:
-    return "no available rpc clients";
-  case Error::NilWriter:
-    return "writer cannot be nil";
-  case Error::Canceled:
-    return "canceled";
-  case Error::EOF_:
-    return "EOF";
-  default:
-    return "unknown error";
-  }
+/* ErrorString returns the stable diagnostic text for err. */
+inline const char *ErrorString(Error err)
+{
+	switch (err) {
+	case Error::OK:
+		return "ok";
+	case Error::Unimplemented:
+		return "unimplemented";
+	case Error::Completed:
+		return "unexpected packet after rpc was completed";
+	case Error::UnrecognizedPacket:
+		return "unrecognized packet type";
+	case Error::EmptyPacket:
+		return "invalid empty packet";
+	case Error::InvalidMessage:
+		return "invalid message";
+	case Error::EmptyMethodID:
+		return "method id empty";
+	case Error::EmptyServiceID:
+		return "service id empty";
+	case Error::NoAvailableClients:
+		return "no available rpc clients";
+	case Error::NilWriter:
+		return "writer cannot be nil";
+	case Error::Canceled:
+		return "canceled";
+	case Error::EOF_:
+		return "EOF";
+	case Error::ClosedBeforeCompletion:
+		return "stream closed before the remote reported completion";
+	case Error::ResourceExhausted:
+		return "RPC resource limit exceeded";
+	case Error::RemoteError:
+		return "remote RPC error";
+	default:
+		return "unknown error";
+	}
 }
 
-// StarpcError exception for error propagation
+/*
+ * StarpcError carries an Error across a throwing boundary. Exceptions are
+ * disabled in the house build; this exists only for embedders that enable
+ * them.
+ */
 class StarpcError : public std::runtime_error {
 public:
-  explicit StarpcError(Error code)
-      : std::runtime_error(ErrorString(code)), code_(code) {}
+	explicit StarpcError(Error code)
+		: std::runtime_error(ErrorString(code)),
+		  code_(code)
+	{
+	}
 
-  StarpcError(Error code, const std::string &message)
-      : std::runtime_error(message), code_(code) {}
+	/* StarpcError reports message as the diagnostic for code. */
+	StarpcError(Error code, const std::string &message)
+		: std::runtime_error(message),
+		  code_(code)
+	{
+	}
 
-  Error code() const noexcept { return code_; }
+	/* code returns the Error this exception carries. */
+	Error code() const noexcept
+	{
+		return code_;
+	}
 
 private:
-  Error code_;
+	/* code_ keeps the Error; the getter takes the API name code(). */
+	Error code_;
 };
 
 } // namespace starpc

package/srpc/errors.ts

@@ -10,6 +10,22 @@ export function isAbortError(err: unknown): boolean {
   return message === ERR_RPC_ABORT
 }
 
+// ERR_CLOSED_BEFORE_COMPLETION is returned if the stream closed before the
+// remote sent a completion or an error. The call has no verdict: the handler
+// may have finished with its answer lost in the transport, or it may never
+// have run.
+export const ERR_CLOSED_BEFORE_COMPLETION = 'ERR_CLOSED_BEFORE_COMPLETION'
+
+// isClosedBeforeCompletionError checks if the error object is
+// ERR_CLOSED_BEFORE_COMPLETION.
+export function isClosedBeforeCompletionError(err: unknown): boolean {
+  if (typeof err !== 'object') {
+    return false
+  }
+  const message = (err as Error).message
+  return message === ERR_CLOSED_BEFORE_COMPLETION
+}
+
 // ERR_STREAM_IDLE is returned if the stream idle timeout was exceeded.
 export const ERR_STREAM_IDLE = 'ERR_STREAM_IDLE'
 

package/srpc/handler.hpp

@@ -7,17 +7,19 @@
 
 namespace starpc {
 
-// Handler describes a SRPC call handler implementation.
-// Matches Go Handler interface in handler.go
+/*
+ * Handler is one registered SRPC service: an Invoker that publishes its
+ * service ID and method list. Matches the Go Handler interface in handler.go.
+ */
 class Handler : public Invoker {
 public:
-  ~Handler() override = default;
+	~Handler() override = default;
 
-  // GetServiceID returns the ID of the service.
-  virtual const std::string &GetServiceID() const = 0;
+	/* GetServiceID returns the service this handler registers. */
+	virtual const std::string &GetServiceID() const = 0;
 
-  // GetMethodIDs returns the list of methods for the service.
-  virtual std::vector<std::string> GetMethodIDs() const = 0;
+	/* GetMethodIDs returns every method the service answers. */
+	virtual std::vector<std::string> GetMethodIDs() const = 0;
 };
 
 } // namespace starpc

package/srpc/handler.rs

@@ -8,55 +8,17 @@ use std::sync::Arc;
 
 use crate::invoker::Invoker;
 
-/// Trait for RPC service handlers.
+/// Describes the service an Invoker implements, so the Mux can register it.
 ///
-/// 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"]
-///     }
-/// }
-/// ```
+/// A Handler extends Invoker with metadata methods. This is the trait that
+/// generated service code implements.
 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".
+    /// Returns the fully-qualified protobuf service name this handler
+    /// implements, such as `echo.Echoer`.
     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.
+    /// Returns the method names, as defined in the protobuf service
+    /// definition, that this handler implements.
     fn method_ids(&self) -> &'static [&'static str];
 }
 

package/srpc/index.ts

@@ -1,6 +1,8 @@
 export {
   ERR_RPC_ABORT,
   isAbortError,
+  ERR_CLOSED_BEFORE_COMPLETION,
+  isClosedBeforeCompletionError,
   ERR_STREAM_IDLE,
   isStreamIdleError,
   castToError,

package/srpc/invoker.hpp

@@ -9,83 +9,110 @@
 
 namespace starpc {
 
-// Invoker is a function for invoking SRPC service methods.
-// Matches Go Invoker interface in invoker.go
+/*
+ * Invoker dispatches one SRPC method call. Matches the Go Invoker interface
+ * in invoker.go.
+ */
 class Invoker {
 public:
-  virtual ~Invoker() = default;
-
-  // 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.
-  virtual std::pair<bool, Error> InvokeMethod(const std::string &service_id,
-                                              const std::string &method_id,
-                                              Stream *strm) = 0;
+	virtual ~Invoker() = default;
+
+	/*
+	 * InvokeMethod runs the handler for service_id and method_id and
+	 * reports whether it found one. An empty service_id matches any
+	 * service. found is false only when no handler applies; strm carries
+	 * the call.
+	 */
+	virtual std::pair<bool, Error>
+	InvokeMethod(const std::string &service_id,
+		     const std::string &method_id, Stream *strm) = 0;
 };
 
-// QueryableInvoker can be used to check if a service and method is implemented.
-// Matches Go QueryableInvoker interface in invoker.go
+/*
+ * QueryableInvoker answers whether it implements a service or method without
+ * running one. Matches the Go QueryableInvoker interface in invoker.go.
+ */
 class QueryableInvoker {
 public:
-  virtual ~QueryableInvoker() = default;
+	virtual ~QueryableInvoker() = default;
 
-  // HasService checks if the service ID exists in the handlers.
-  virtual bool HasService(const std::string &service_id) const = 0;
+	/* HasService reports whether service_id is registered. */
+	virtual bool HasService(const std::string &service_id) const = 0;
 
-  // HasServiceMethod checks if <service-id, method-id> exists in the handlers.
-  virtual bool HasServiceMethod(const std::string &service_id,
-                                const std::string &method_id) const = 0;
+	/* HasServiceMethod reports whether the service serves method_id. */
+	virtual bool HasServiceMethod(const std::string &service_id,
+				      const std::string &method_id) const = 0;
 };
 
-// InvokerSlice is a list of invokers.
-// Matches Go InvokerSlice in invoker.go
+/*
+ * InvokerSlice tries each invoker in order and stops at the first that
+ * handles the call or fails. The invokers are borrowed and must outlive the
+ * slice. Matches Go InvokerSlice in invoker.go.
+ */
 class InvokerSlice : public Invoker {
 public:
-  InvokerSlice() = default;
-  explicit InvokerSlice(std::vector<Invoker *> invokers)
-      : invokers_(std::move(invokers)) {}
-
-  void Add(Invoker *invoker) { invokers_.push_back(invoker); }
-
-  std::pair<bool, Error> InvokeMethod(const std::string &service_id,
-                                      const std::string &method_id,
-                                      Stream *strm) override {
-    for (auto *invoker : invokers_) {
-      if (invoker == nullptr)
-        continue;
-      auto [found, err] = invoker->InvokeMethod(service_id, method_id, strm);
-      if (found || err != Error::OK) {
-        return {true, err};
-      }
-    }
-    return {false, Error::OK};
-  }
+	InvokerSlice() = default;
+	explicit InvokerSlice(std::vector<Invoker *> invokers)
+		: invokers(std::move(invokers))
+	{
+	}
+
+	/* Add appends an invoker to try after the ones already present. */
+	void Add(Invoker *invoker)
+	{
+		invokers.push_back(invoker);
+	}
+
+	std::pair<bool, Error> InvokeMethod(const std::string &service_id,
+					    const std::string &method_id,
+					    Stream *strm) override
+	{
+		for (auto *invoker : invokers) {
+			if (invoker == nullptr)
+				continue;
+			auto [found, err] = invoker->InvokeMethod(
+				service_id, method_id, strm);
+			if (found || err != Error::OK)
+				return {true, err};
+		}
+		return {false, Error::OK};
+	}
 
 private:
-  std::vector<Invoker *> invokers_;
+	/* invokers are borrowed; the caller owns them. */
+	std::vector<Invoker *> invokers;
 };
 
-// InvokerFunc is a function implementing InvokeMethod.
-// Matches Go InvokerFunc in invoker.go
+/*
+ * InvokerFunc is the callable form of Invoker::InvokeMethod. Matches Go
+ * InvokerFunc in invoker.go.
+ */
 using InvokerFunc = std::function<std::pair<bool, Error>(
-    const std::string &service_id, const std::string &method_id, Stream *strm)>;
+	const std::string &service_id, const std::string &method_id,
+	Stream *strm)>;
 
-// InvokerFuncWrapper wraps an InvokerFunc as an Invoker.
+/*
+ * InvokerFuncWrapper adapts an InvokerFunc to the Invoker interface. An empty
+ * function reports that no handler applies.
+ */
 class InvokerFuncWrapper : public Invoker {
 public:
-  explicit InvokerFuncWrapper(InvokerFunc fn) : fn_(std::move(fn)) {}
-
-  std::pair<bool, Error> InvokeMethod(const std::string &service_id,
-                                      const std::string &method_id,
-                                      Stream *strm) override {
-    if (!fn_) {
-      return {false, Error::OK};
-    }
-    return fn_(service_id, method_id, strm);
-  }
+	explicit InvokerFuncWrapper(InvokerFunc fn)
+		: fn(std::move(fn))
+	{
+	}
+
+	std::pair<bool, Error> InvokeMethod(const std::string &service_id,
+					    const std::string &method_id,
+					    Stream *strm) override
+	{
+		if (!fn)
+			return {false, Error::OK};
+		return fn(service_id, method_id, strm);
+	}
 
 private:
-  InvokerFunc fn_;
+	InvokerFunc fn;
 };
 
 } // namespace starpc