starpc 0.52.0 → 0.52.1

package/dist/srpc/stream.test.js

@@ -1,5 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { pipe } from 'it-pipe';
+import { pushable } from 'it-pushable';
+import { streamToPacketStream } from './stream.js';
 import { ChannelStream, combineUint8ArrayListTransform, StreamConn, } from '../srpc/index.js';
 describe('StreamConn packet stream', () => {
     it('keeps yamux peer writes open after local packet source completes normally', async () => {
@@ -48,6 +50,113 @@ describe('StreamConn packet stream', () => {
         await serverDone;
         expect(serverError).toBeUndefined();
     });
+    it('settles a blocked packet source when closed', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const pending = stream.source.next();
+            await stream.close();
+            await expect(pending).resolves.toEqual({ done: true, value: undefined });
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('settles a blocked packet source when aborted', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const pending = stream.source.next();
+            const error = new Error('stopped');
+            stream.abort(error);
+            await expect(pending).rejects.toBe(error);
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('settles a blocked packet sink when closed', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const input = pushable({ objectMode: true });
+            const pending = stream.sink(input);
+            await stream.close();
+            await expect(pending).resolves.toBeUndefined();
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('settles a packet sink blocked in the underlying write', async () => {
+        const sinkStarted = Promise.withResolvers();
+        const transport = {
+            source: (async function* () { })(),
+            sink: async (source) => {
+                for await (const _chunk of source) {
+                    sinkStarted.resolve();
+                    await new Promise(() => { });
+                }
+            },
+            close: vi.fn(async () => { }),
+            closeRead: vi.fn(async () => { }),
+            closeWrite: vi.fn(async () => { }),
+            abort: vi.fn(),
+        };
+        const stream = streamToPacketStream(transport);
+        const input = pushable({ objectMode: true });
+        input.push(new Uint8Array([1]));
+        const pending = stream.sink(input);
+        await sinkStarted.promise;
+        await stream.close();
+        await expect(pending).resolves.toBeUndefined();
+    });
+    it('rejects a blocked packet sink with the abort error', async () => {
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream() { },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const input = pushable({ objectMode: true });
+            const pending = stream.sink(input);
+            const error = new Error('stopped');
+            stream.abort(error);
+            await expect(pending).rejects.toBe(error);
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('does not write ready input after close', async () => {
+        const serverStream = Promise.withResolvers();
+        const { clientConn, cleanup } = connectStreamConns({
+            handlePacketStream(stream) {
+                serverStream.resolve(stream);
+            },
+        });
+        try {
+            const stream = await clientConn.openStream();
+            const peer = await serverStream.promise;
+            const input = pushable({ objectMode: true });
+            input.push(new Uint8Array([1]));
+            const pending = stream.sink(input);
+            await stream.close();
+            await expect(pending).resolves.toBeUndefined();
+            await expect(nextWithTimeout(peer.source, 'server eof')).resolves.toEqual({
+                done: true,
+                value: undefined,
+            });
+        }
+        finally {
+            cleanup();
+        }
+    });
     it('aborts the yamux stream when the packet source errors', async () => {
         const request = new TextEncoder().encode('request');
         const sourceError = new Error('source failed');

package/dist/srpc/termination.d.ts

@@ -0,0 +1,27 @@
+import type { Source } from 'it-stream-types';
+type Terminated = {
+    terminated: true;
+    error?: Error;
+};
+type Received<T> = {
+    result: IteratorResult<T>;
+} | {
+    error: unknown;
+};
+type WaitResult<T> = {
+    result: T;
+} | {
+    error: unknown;
+};
+export declare class TerminationGate {
+    private readonly _waiters;
+    private _error;
+    private _terminated;
+    get terminated(): boolean;
+    terminate(error?: Error): boolean;
+    wait<T>(promise: Promise<T>): Promise<WaitResult<T> | Terminated>;
+    next<T>(iterator: AsyncIterator<T>): Promise<Received<T> | Terminated>;
+}
+export declare function sourceIterator<T>(source: Source<T>): AsyncIterator<T>;
+export declare function closeIterator<T>(iterator: AsyncIterator<T>): void;
+export {};

package/dist/srpc/termination.js

@@ -0,0 +1,56 @@
+// TerminationGate makes the first clean close or abort visible to blocked I/O.
+export class TerminationGate {
+    _waiters = new Set();
+    _error;
+    _terminated = false;
+    get terminated() {
+        return this._terminated;
+    }
+    terminate(error) {
+        if (this._terminated)
+            return false;
+        this._terminated = true;
+        this._error = error;
+        for (const waiter of this._waiters)
+            waiter(error);
+        this._waiters.clear();
+        return true;
+    }
+    async wait(promise) {
+        if (this._terminated)
+            return { terminated: true, error: this._error };
+        let notify;
+        const terminated = new Promise((resolve) => {
+            notify = (error) => resolve({ terminated: true, error });
+            this._waiters.add(notify);
+        });
+        const received = promise.then((result) => ({ result }), (error) => ({ error }));
+        try {
+            const result = await Promise.race([received, terminated]);
+            if (this._terminated) {
+                return { terminated: true, error: this._error };
+            }
+            return result;
+        }
+        finally {
+            this._waiters.delete(notify);
+        }
+    }
+    next(iterator) {
+        return this.wait(iterator.next());
+    }
+}
+export function sourceIterator(source) {
+    if (Symbol.asyncIterator in source)
+        return source[Symbol.asyncIterator]();
+    const iterator = source[Symbol.iterator]();
+    return { next: async () => iterator.next() };
+}
+// closeIterator asks an abandoned iterator to release its upstream resources.
+// Async generators may wait for an active next call before running return;
+// rejection is observed here so cleanup cannot create an unhandled promise.
+export function closeIterator(iterator) {
+    if (!iterator.return)
+        return;
+    void Promise.resolve(iterator.return()).catch(() => undefined);
+}

package/dist/srpc/termination.test.d.ts

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

package/dist/srpc/termination.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { TerminationGate } from './termination.js';
+describe('TerminationGate', () => {
+    it('prioritizes termination over an already-ready result', async () => {
+        const gate = new TerminationGate();
+        const iterator = (async function* () {
+            yield 1;
+        })();
+        const pending = gate.next(iterator);
+        const error = new Error('stopped');
+        gate.terminate(error);
+        await expect(pending).resolves.toEqual({ terminated: true, error });
+    });
+    it('keeps the first termination result', async () => {
+        const gate = new TerminationGate();
+        const error = new Error('stopped');
+        expect(gate.terminate(error)).toBe(true);
+        expect(gate.terminate()).toBe(false);
+        await expect(gate.wait(new Promise(() => { }))).resolves.toEqual({
+            terminated: true,
+            error,
+        });
+    });
+});

package/dist/testdata/packet-codec-vectors.json

@@ -0,0 +1,64 @@
+{
+    "version": 1,
+    "max_message_size": 10000000,
+    "frame_prefix": "uint32 little-endian",
+    "cases": [
+        {
+            "name": "call_start_data",
+            "packet_hex": "0a120a0373766312066d6574686f641a03616263",
+            "frame_hex": "140000000a120a0373766312066d6574686f641a03616263"
+        },
+        {
+            "name": "call_start_absent_empty",
+            "packet_hex": "0a0d0a0373766312066d6574686f64",
+            "frame_hex": "0f0000000a0d0a0373766312066d6574686f64"
+        },
+        {
+            "name": "call_start_present_empty",
+            "packet_hex": "0a0f0a0373766312066d6574686f642001",
+            "frame_hex": "110000000a0f0a0373766312066d6574686f642001"
+        },
+        {
+            "name": "call_data_terminal",
+            "packet_hex": "12070a036f75741801",
+            "frame_hex": "0900000012070a036f75741801"
+        },
+        {
+            "name": "call_data_error",
+            "packet_hex": "120a180122066661696c6564",
+            "frame_hex": "0c000000120a180122066661696c6564"
+        },
+        {
+            "name": "call_cancel",
+            "packet_hex": "1801",
+            "frame_hex": "020000001801"
+        },
+        {
+            "name": "malformed_complete",
+            "frame_hex": "030000000a01ff",
+            "expect_error": "malformed_packet"
+        },
+        {
+            "name": "invalid_zero_length",
+            "frame_hex": "00000000",
+            "expect_error": "invalid_length"
+        },
+        {
+            "name": "invalid_oversized_prefix",
+            "frame_hex": "81969800",
+            "expect_error": "oversized_frame"
+        },
+        {
+            "name": "invalid_empty_packet",
+            "packet_hex": "",
+            "expect_error": "empty_packet"
+        },
+        { "name": "invalid_empty_service_id", "expect_error": "empty_service_id" },
+        { "name": "invalid_empty_method_id", "expect_error": "empty_method_id" },
+        {
+            "name": "truncated_body",
+            "frame_hex": "040000000a01",
+            "expect_error": "truncated_frame"
+        }
+    ]
+}

package/echo/client-test.ts

@@ -2,7 +2,10 @@ import { Client, ERR_RPC_ABORT } from '../srpc/index.js'
 import { EchoMsg } from './echo.pb.js'
 import { EchoerClient } from './echo_srpc.pb.js'
 import { pushable } from 'it-pushable'
-import { buildRpcStreamOpenStream } from '../rpcstream/rpcstream.js'
+import {
+  buildRpcStreamOpenStream,
+  openRpcStream,
+} from '../rpcstream/rpcstream.js'
 import { Message } from '@aptre/protobuf-es-lite'
 
 export async function runClientTest(client: Client) {
@@ -89,8 +92,19 @@ export async function runAbortControllerTest(client: Client) {
   })
 }
 
+function requireError(
+  error: unknown,
+  label: string,
+  fragments: string[],
+): void {
+  const message = error instanceof Error ? error.message : String(error)
+  if (!fragments.some((fragment) => message.includes(fragment))) {
+    throw new Error(`${label} returned unexpected error: ${message}`)
+  }
+}
+
 // runRpcStreamTest tests a RPCStream.
-export async function runRpcStreamTest(client: Client) {
+export async function runRpcStreamTest(client: Client, release = false) {
   console.log('Calling RpcStream to open a RPC stream client...')
   const service = new EchoerClient(client)
   const openStreamFn = buildRpcStreamOpenStream(
@@ -106,4 +120,112 @@ export async function runRpcStreamTest(client: Client) {
 
   console.log('Running client test over RPC stream...')
   await runClientTest(proxiedClient)
+
+  if (release) {
+    let unknownRejected = false
+    try {
+      await openRpcStream('missing', service.RpcStream.bind(service), true)
+    } catch (error) {
+      unknownRejected = true
+      requireError(error, 'unknown component', ['unknown component: missing'])
+    }
+    if (!unknownRejected) {
+      throw new Error('unknown component unexpectedly succeeded')
+    }
+  }
+
+  let methodRejected = false
+  try {
+    await proxiedClient.request('missing.Service', 'Missing', new Uint8Array())
+  } catch (error) {
+    methodRejected = true
+    requireError(error, 'unknown nested method', [
+      'missing.Service',
+      'unimplemented',
+    ])
+  }
+  if (!methodRejected) {
+    throw new Error('unknown nested method unexpectedly succeeded')
+  }
+
+  if (release) {
+    const terminalService = new EchoerClient(proxiedClient)
+    let terminalFailed = false
+    try {
+      await terminalService.Echo({ body: '__nested_error__' })
+    } catch (error) {
+      terminalFailed = true
+      requireError(error, 'terminal nested error', ['nested terminal error'])
+    }
+    if (!terminalFailed) {
+      throw new Error('terminal nested error unexpectedly succeeded')
+    }
+  }
+
+  if (release) {
+    const releaseClient = new Client(
+      buildRpcStreamOpenStream('release', service.RpcStream.bind(service)),
+    )
+    let releaseFailed = false
+    const releaseService = new EchoerClient(releaseClient)
+    try {
+      await releaseService.Echo({ body: '__nested_release__' })
+    } catch (error) {
+      releaseFailed = true
+      requireError(error, 'release during active call', [
+        'closed before completion',
+        'stream closed',
+        'abort',
+        'cancel',
+      ])
+    }
+    if (!releaseFailed) {
+      throw new Error('release during active call unexpectedly succeeded')
+    }
+    const releaseStatus = await service.Echo({
+      body: '__nested_release_status__',
+    })
+    if (releaseStatus.body !== 'released') {
+      throw new Error(`release completion returned ${releaseStatus.body}`)
+    }
+    let releasedRejected = false
+    try {
+      await releaseService.Echo({})
+    } catch (error) {
+      releasedRejected = true
+      requireError(error, 'released component', ['unknown component: release'])
+    }
+    if (!releasedRejected) {
+      throw new Error('released component unexpectedly remained available')
+    }
+  }
+
+  const cancelled = new AbortController()
+  const cancelledStream = proxiedClient.bidirectionalStreamingRequest(
+    'echo.Echoer',
+    'EchoBidiStream',
+    (async function* () {
+      yield new Uint8Array()
+      await new Promise(() => undefined)
+    })(),
+    cancelled.signal,
+  )
+  const cancelledIterator = cancelledStream[Symbol.asyncIterator]()
+  const firstNestedResponse = await cancelledIterator.next()
+  if (firstNestedResponse.done) {
+    throw new Error('nested cancellation call ended before its first response')
+  }
+  cancelled.abort()
+  let cancelRejected = false
+  try {
+    while (!(await cancelledIterator.next()).done) {
+      // Drain until the abort reaches the nested call.
+    }
+  } catch (error) {
+    cancelRejected = true
+    requireError(error, 'nested cancellation', [ERR_RPC_ABORT])
+  }
+  if (!cancelRejected) {
+    throw new Error('nested cancellation unexpectedly completed normally')
+  }
 }

package/echo/echo_pb2.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: github.com/aperturerobotics/starpc/echo/echo.proto
+# Protobuf Python Version: 6.33.4
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    4,
+    '',
+    'github.com/aperturerobotics/starpc/echo/echo.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from rpcstream import rpcstream_pb2 as github_dot_com_dot_aperturerobotics_dot_starpc_dot_rpcstream_dot_rpcstream__pb2
+from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n2github.com/aperturerobotics/starpc/echo/echo.proto\x12\x04\x65\x63ho\x1a<github.com/aperturerobotics/starpc/rpcstream/rpcstream.proto\x1a\x1bgoogle/protobuf/empty.proto\"\x17\n\x07\x45\x63hoMsg\x12\x0c\n\x04\x62ody\x18\x01 \x01(\t2\xd0\x02\n\x06\x45\x63hoer\x12$\n\x04\x45\x63ho\x12\r.echo.EchoMsg\x1a\r.echo.EchoMsg\x12\x32\n\x10\x45\x63hoServerStream\x12\r.echo.EchoMsg\x1a\r.echo.EchoMsg0\x01\x12\x32\n\x10\x45\x63hoClientStream\x12\r.echo.EchoMsg\x1a\r.echo.EchoMsg(\x01\x12\x32\n\x0e\x45\x63hoBidiStream\x12\r.echo.EchoMsg\x1a\r.echo.EchoMsg(\x01\x30\x01\x12G\n\tRpcStream\x12\x1a.rpcstream.RpcStreamPacket\x1a\x1a.rpcstream.RpcStreamPacket(\x01\x30\x01\x12;\n\tDoNothing\x12\x16.google.protobuf.Empty\x1a\x16.google.protobuf.Emptyb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'github.com.aperturerobotics.starpc.echo.echo_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_ECHOMSG']._serialized_start=151
+  _globals['_ECHOMSG']._serialized_end=174
+  _globals['_ECHOER']._serialized_start=177
+  _globals['_ECHOER']._serialized_end=513
+# @@protoc_insertion_point(module_scope)

package/echo/echo_pb2.pyi

@@ -0,0 +1,13 @@
+from rpcstream import rpcstream_pb2 as _rpcstream_pb2
+from google.protobuf import empty_pb2 as _empty_pb2
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class EchoMsg(_message.Message):
+    __slots__ = ("body",)
+    BODY_FIELD_NUMBER: _ClassVar[int]
+    body: str
+    def __init__(self, body: _Optional[str] = ...) -> None: ...