starpc 0.52.1 → 0.52.2

package/README.md

@@ -145,16 +145,18 @@ For TypeScript <-> TypeScript, see the [e2e] test.
 
 ### Rust
 
+These examples use the repository's current Rust API. Unary handlers receive the transport's cancellation context; streaming handlers obtain it from their stream.
+
 Add the dependencies to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-starpc = "0.49"
+starpc = { git = "https://github.com/aperturerobotics/starpc" }
 prost = "0.14"
-tokio = { version = "1", features = ["rt", "macros"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "io-util"] }
 
 [build-dependencies]
-starpc = { version = "0.49", features = ["build"] }
+starpc = { git = "https://github.com/aperturerobotics/starpc", features = ["build"] }
 prost-build = "0.14"
 ```
 
@@ -171,7 +173,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 Implement and use your service:
 
 ```rust
-use starpc::{Client, Mux, Server, SrpcClient};
+use starpc::{Error, Mux, Server, SrpcClient, Stream, StreamExt};
 use std::sync::Arc;
 
 // Include generated code
@@ -186,8 +188,34 @@ struct EchoServer;
 
 #[starpc::async_trait]
 impl EchoerServer for EchoServer {
-    async fn echo(&self, request: EchoMsg) -> starpc::Result<EchoMsg> {
-        Ok(request) // Echo back the message
+    async fn echo(&self, _context: &starpc::Context, request: EchoMsg) -> starpc::Result<EchoMsg> {
+        Ok(request)
+    }
+
+    async fn echo_server_stream(&self, request: EchoMsg, stream: Box<dyn Stream>) -> starpc::Result<()> {
+        stream.msg_send(&request).await
+    }
+
+    async fn echo_client_stream(&self, stream: &dyn Stream) -> starpc::Result<EchoMsg> {
+        let mut messages = Vec::new();
+        loop {
+            match stream.msg_recv::<EchoMsg>().await {
+                Ok(message) => messages.push(message.body),
+                Err(Error::StreamClosed) => break,
+                Err(error) => return Err(error),
+            }
+        }
+        Ok(EchoMsg { body: messages.join(", ") })
+    }
+
+    async fn echo_bidi_stream(&self, stream: Box<dyn Stream>) -> starpc::Result<()> {
+        loop {
+            match stream.msg_recv::<EchoMsg>().await {
+                Ok(message) => stream.msg_send(&message).await?,
+                Err(Error::StreamClosed) => return Ok(()),
+                Err(error) => return Err(error),
+            }
+        }
     }
 }
 
@@ -202,8 +230,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let (client_stream, server_stream) = tokio::io::duplex(64 * 1024);
 
     // Spawn server handler
-    tokio::spawn(async move {
-        let _ = server.handle_stream(server_stream).await;
+    let server = tokio::spawn(async move {
+        server.handle_stream(server_stream).await
     });
 
     // Create client
@@ -214,6 +242,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Make RPC call
     let response = echoer.echo(&EchoMsg { body: "Hello!".into() }).await?;
     println!("Response: {}", response.body);
+    server.await??;
 
     Ok(())
 }

package/dist/srpc/client-rpc.d.ts

@@ -4,4 +4,5 @@ export declare class ClientRPC extends CommonRPC {
     constructor(service: string, method: string);
     writeCallStart(data?: Uint8Array): Promise<void>;
     handleCallStart(packet: CallStart): Promise<void>;
+    protected handleSourceEnd(): Promise<void>;
 }

package/dist/srpc/client-rpc.js

@@ -1,4 +1,5 @@
 import { CommonRPC } from './common-rpc.js';
+import { ERR_CLOSED_BEFORE_COMPLETION } from './errors.js';
 // ClientRPC is an ongoing RPC from the client side.
 export class ClientRPC extends CommonRPC {
     constructor(service, method) {
@@ -30,4 +31,12 @@ export class ClientRPC extends CommonRPC {
         // we do not implement server -> client RPCs.
         throw new Error(`unexpected server to client rpc: ${packet.rpcService || '<empty>'}/${packet.rpcMethod || '<empty>'}`);
     }
+    // handleSourceEnd fails the call when the transport ends before the remote
+    // sent a completion or an error, so a truncated stream does not read as a
+    // complete one.
+    async handleSourceEnd() {
+        if (!this.isRemoteCompleted) {
+            await this.close(new Error(ERR_CLOSED_BEFORE_COMPLETION));
+        }
+    }
 }

package/dist/srpc/client-rpc.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/srpc/client-rpc.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { ClientRPC } from './client-rpc.js';
+import { isClosedBeforeCompletionError } from './errors.js';
+import { Packet } from './rpcproto.pb.js';
+describe('ClientRPC', () => {
+    it('fails a call whose transport ends before the remote completes it', async () => {
+        const call = new ClientRPC('svc', 'method');
+        await call.sink(packetSource(callDataPacket(new Uint8Array([1]))));
+        const received = new Array();
+        const read = async () => {
+            for await (const data of call.rpcDataSource) {
+                received.push(data[0]);
+            }
+        };
+        const err = await read().then(() => undefined, (err) => err);
+        expect(received).toEqual([1]);
+        expect(isClosedBeforeCompletionError(err)).toBe(true);
+        expect(isClosedBeforeCompletionError(call.isClosed)).toBe(true);
+    });
+    it('ends a call cleanly when the remote completes it before the transport ends', async () => {
+        const call = new ClientRPC('svc', 'method');
+        await call.sink(packetSource(callDataPacket(new Uint8Array([1])), callDataPacket(undefined, true)));
+        const received = new Array();
+        for await (const data of call.rpcDataSource) {
+            received.push(data[0]);
+        }
+        expect(received).toEqual([1]);
+        expect(call.isClosed).toBe(false);
+    });
+});
+// callDataPacket builds an incoming call-data packet.
+function callDataPacket(data, complete = false) {
+    return Packet.create({
+        body: {
+            case: 'callData',
+            value: {
+                data: data ?? new Uint8Array(0),
+                dataIsZero: false,
+                complete,
+                error: '',
+            },
+        },
+    });
+}
+// packetSource yields packets and then ends like a closed transport.
+async function* packetSource(...packets) {
+    for (const packet of packets) {
+        yield packet;
+    }
+}

package/dist/srpc/common-rpc.d.ts

@@ -10,10 +10,12 @@ export declare class CommonRPC {
     protected method?: string;
     private closed?;
     private remoteError?;
+    private remoteCompleted;
     private readonly invocationController;
     private readonly writeDrainAbort;
     constructor();
     get isClosed(): boolean | Error;
+    protected get isRemoteCompleted(): boolean;
     protected get invocationSignal(): AbortSignal;
     writeCallData(data?: Uint8Array, complete?: boolean, error?: string): Promise<void>;
     private writeCallDataPacket;
@@ -27,6 +29,9 @@ export declare class CommonRPC {
     handleCallData(packet: Partial<CallData>): Promise<void>;
     handleCallCancel(): Promise<void>;
     close(err?: Error): Promise<void>;
+    private endRpcData;
+    private readRpcData;
+    protected handleSourceEnd(): Promise<void>;
     private _createSink;
 }
 interface WritePacketOptions {

package/dist/srpc/common-rpc.js

@@ -14,7 +14,9 @@ export class CommonRPC {
     _source = pushable({
         objectMode: true,
     });
-    // _rpcDataSource is used to write to the rpc message source.
+    // _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.
     _rpcDataSource = pushable({
         objectMode: true,
     });
@@ -26,6 +28,8 @@ export class CommonRPC {
     closed;
     // remoteError records a remote error or transport failure.
     remoteError;
+    // remoteCompleted records that the remote sent a completion or an error.
+    remoteCompleted = false;
     // invocationController cancels the server invocation when the RPC closes.
     invocationController = new AbortController();
     // writeDrainAbort wakes writers waiting for outbound stream drain on close.
@@ -33,12 +37,16 @@ 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).
     get isClosed() {
         return this.closed ?? false;
     }
+    // isRemoteCompleted reports whether the remote sent a completion or an error.
+    get isRemoteCompleted() {
+        return this.remoteCompleted;
+    }
     // invocationSignal is canceled when the RPC closes.
     get invocationSignal() {
         return this.invocationController.signal;
@@ -171,11 +179,9 @@ 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.
@@ -201,7 +207,29 @@ 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.
+    endRpcData(err) {
+        if (err) {
+            this._rpcDataSource.push(err);
+        }
+        this._rpcDataSource.end();
+    }
+    // readRpcData yields the buffered rpc messages, then throws the terminal
+    // error, if any.
+    async *readRpcData() {
+        for await (const item of this._rpcDataSource) {
+            if (item instanceof Error) {
+                throw item;
+            }
+            yield item;
+        }
+    }
+    // handleSourceEnd handles the end of the incoming packet source.
+    async handleSourceEnd() {
+        // no-op
     }
     _createSink() {
         return async (source) => {
@@ -216,6 +244,7 @@ export class CommonRPC {
                         await this.handlePacket(msg);
                     }
                 }
+                await this.handleSourceEnd();
             }
             catch (err) {
                 this.close(err);

package/dist/srpc/errors.d.ts

@@ -1,5 +1,7 @@
 export declare const ERR_RPC_ABORT = "ERR_RPC_ABORT";
 export declare function isAbortError(err: unknown): boolean;
+export declare const ERR_CLOSED_BEFORE_COMPLETION = "ERR_CLOSED_BEFORE_COMPLETION";
+export declare function isClosedBeforeCompletionError(err: unknown): boolean;
 export declare const ERR_STREAM_IDLE = "ERR_STREAM_IDLE";
 export declare function isStreamIdleError(err: unknown): boolean;
 export declare class RemoteRPCError extends Error {

package/dist/srpc/errors.js

@@ -8,6 +8,20 @@ export function isAbortError(err) {
     const message = err.message;
     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) {
+    if (typeof err !== 'object') {
+        return false;
+    }
+    const message = err.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';
 // isStreamIdleError checks if the error object is ERR_STREAM_IDLE.

package/dist/srpc/index.d.ts

@@ -1,4 +1,4 @@
-export { ERR_RPC_ABORT, isAbortError, ERR_STREAM_IDLE, isStreamIdleError, castToError, } from './errors.js';
+export { ERR_RPC_ABORT, isAbortError, ERR_CLOSED_BEFORE_COMPLETION, isClosedBeforeCompletionError, ERR_STREAM_IDLE, isStreamIdleError, castToError, } from './errors.js';
 export { Client } from './client.js';
 export { Server } from './server.js';
 export { StreamConn } from './conn.js';

package/dist/srpc/index.js

@@ -1,4 +1,4 @@
-export { ERR_RPC_ABORT, isAbortError, ERR_STREAM_IDLE, isStreamIdleError, castToError, } from './errors.js';
+export { ERR_RPC_ABORT, isAbortError, ERR_CLOSED_BEFORE_COMPLETION, isClosedBeforeCompletionError, ERR_STREAM_IDLE, isStreamIdleError, castToError, } from './errors.js';
 export { Client } from './client.js';
 export { Server } from './server.js';
 export { StreamConn } from './conn.js';

package/echo/Cargo.toml

@@ -23,3 +23,11 @@ starpc = { workspace = true }
 prost = { workspace = true }
 tokio = { version = "1", features = ["full"] }
 async-trait = { workspace = true }
+futures = { workspace = true }
+
+[[test]]
+name = "half_close"
+path = "half_close_test.rs"
+
+[dev-dependencies]
+tokio-util = { workspace = true }