starpc 0.51.0 → 0.52.1

package/echo/echo_srpc.pyi

@@ -0,0 +1,85 @@
+from collections.abc import AsyncIterable, AsyncIterator
+from typing import Protocol
+
+from google.protobuf import empty_pb2 as _google_protobuf_empty_pb2
+
+from echo import (
+    echo_pb2 as _github_com_aperturerobotics_starpc_echo_echo_pb2,
+)
+from rpcstream import (
+    rpcstream_pb2 as _github_com_aperturerobotics_starpc_rpcstream_rpcstream_pb2,
+)
+from starpc.client import Client
+from starpc.server import ServiceRegistry
+from starpc.service import ServiceDescriptor
+
+ECHOER_SERVICE: ServiceDescriptor
+
+class EchoerClient:
+    def __init__(self, client: Client, service: str | None = None) -> None: ...
+    async def echo(
+        self, request: _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+    ) -> _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg: ...
+    def echo_server_stream(
+        self, request: _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+    ) -> AsyncIterator[_github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg]: ...
+    async def echo_client_stream(
+        self,
+        requests: AsyncIterable[
+            _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+        ],
+    ) -> _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg: ...
+    def echo_bidi_stream(
+        self,
+        requests: AsyncIterable[
+            _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+        ],
+    ) -> AsyncIterator[_github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg]: ...
+    def rpc_stream(
+        self,
+        requests: AsyncIterable[
+            _github_com_aperturerobotics_starpc_rpcstream_rpcstream_pb2.RpcStreamPacket
+        ],
+    ) -> AsyncIterator[
+        _github_com_aperturerobotics_starpc_rpcstream_rpcstream_pb2.RpcStreamPacket
+    ]: ...
+    async def do_nothing(
+        self, request: _google_protobuf_empty_pb2.Empty
+    ) -> _google_protobuf_empty_pb2.Empty: ...
+
+class EchoerServer(Protocol):
+    async def echo(
+        self, request: _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+    ) -> _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg: ...
+    def echo_server_stream(
+        self, request: _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+    ) -> AsyncIterator[_github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg]: ...
+    async def echo_client_stream(
+        self,
+        requests: AsyncIterator[
+            _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+        ],
+    ) -> _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg: ...
+    def echo_bidi_stream(
+        self,
+        requests: AsyncIterator[
+            _github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg
+        ],
+    ) -> AsyncIterator[_github_com_aperturerobotics_starpc_echo_echo_pb2.EchoMsg]: ...
+    def rpc_stream(
+        self,
+        requests: AsyncIterator[
+            _github_com_aperturerobotics_starpc_rpcstream_rpcstream_pb2.RpcStreamPacket
+        ],
+    ) -> AsyncIterator[
+        _github_com_aperturerobotics_starpc_rpcstream_rpcstream_pb2.RpcStreamPacket
+    ]: ...
+    async def do_nothing(
+        self, request: _google_protobuf_empty_pb2.Empty
+    ) -> _google_protobuf_empty_pb2.Empty: ...
+
+def register_echoer(
+    registry: ServiceRegistry,
+    implementation: EchoerServer,
+    service: str = "echo.Echoer",
+) -> None: ...

package/echo/server.ts

@@ -3,14 +3,15 @@ import { Message } from '@aptre/protobuf-es-lite'
 import { Empty } from '@aptre/protobuf-es-lite/google/protobuf/empty'
 import { EchoMsg } from './echo.pb.js'
 import { Server } from '../srpc/server.js'
+import type { ServerContext } from '../srpc/server-context.js'
 import { messagePushable, writeToPushable } from '../srpc/pushable.js'
 import { RpcStreamPacket } from '../rpcstream/rpcstream.pb.js'
 import { MessageStream } from '../srpc/message.js'
 import { handleRpcStream, RpcStreamHandler } from '../rpcstream/rpcstream.js'
-import { Echoer } from './echo_srpc.pb.js'
+import type { EchoerHandler } from './echo_srpc.pb.js'
 
 // EchoServer implements the Echoer server.
-export class EchoerServer implements Echoer {
+export class EchoerServer implements EchoerHandler {
   // proxyServer is the server used for RpcStream requests.
   private proxyServer?: Server
 
@@ -18,11 +19,19 @@ export class EchoerServer implements Echoer {
     this.proxyServer = proxyServer
   }
 
-  public async Echo(request: EchoMsg): Promise<Message<EchoMsg>> {
+  public async Echo(
+    request: EchoMsg,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
+  ): Promise<Message<EchoMsg>> {
     return request
   }
 
-  public async *EchoServerStream(request: EchoMsg): MessageStream<EchoMsg> {
+  public async *EchoServerStream(
+    request: EchoMsg,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
+  ): MessageStream<EchoMsg> {
     for (let i = 0; i < 5; i++) {
       yield request
       await new Promise((resolve) => setTimeout(resolve, 200))
@@ -31,6 +40,8 @@ export class EchoerServer implements Echoer {
 
   public async EchoClientStream(
     request: MessageStream<EchoMsg>,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
   ): Promise<Message<EchoMsg>> {
     // return the first message sent by the client.
     const message = await first(request)
@@ -42,6 +53,8 @@ export class EchoerServer implements Echoer {
 
   public EchoBidiStream(
     request: MessageStream<EchoMsg>,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
   ): MessageStream<EchoMsg> {
     // build result observable
     const result = messagePushable<EchoMsg>()
@@ -52,6 +65,8 @@ export class EchoerServer implements Echoer {
 
   public RpcStream(
     request: MessageStream<RpcStreamPacket>,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
   ): MessageStream<RpcStreamPacket> {
     return handleRpcStream(
       request[Symbol.asyncIterator](),
@@ -64,7 +79,11 @@ export class EchoerServer implements Echoer {
     )
   }
 
-  public async DoNothing(): Promise<Empty> {
+  public async DoNothing(
+    _request: Empty,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
+  ): Promise<Empty> {
     return {}
   }
 }

package/go.mod

@@ -3,7 +3,7 @@ module github.com/aperturerobotics/starpc
 go 1.25.0
 
 require (
-	github.com/aperturerobotics/common v0.35.0 // latest
+	github.com/aperturerobotics/common v0.35.1-0.20260808123156-c77af26f63bd // latest
 	github.com/aperturerobotics/protobuf-go-lite v0.16.0 // latest
 	github.com/aperturerobotics/util v1.34.9 // latest
 )
@@ -12,7 +12,7 @@ require (
 	github.com/aperturerobotics/abseil-cpp v0.0.0-20260131110040-4bb56e2f9017 // aperture-2
 	github.com/aperturerobotics/cli v1.1.0 // indirect
 	github.com/aperturerobotics/go-protoc-gen-prost v0.0.0-20260705010911-9f53feac967b // indirect
-	github.com/aperturerobotics/go-protoc-wasi v0.0.0-20260712054757-d8078c296c17 // indirect
+	github.com/aperturerobotics/go-protoc-wasi v0.0.0-20260808023521-7b1595380c3f // indirect
 	github.com/aperturerobotics/go-websocket v1.8.15-0.20260619192713-a096778f08c1 // master
 	github.com/aperturerobotics/json-iterator-lite v1.1.0 // indirect
 	github.com/aperturerobotics/protobuf v0.0.0-20260203024654-8201686529c4 // wasi

package/go.sum

@@ -6,10 +6,24 @@ github.com/aperturerobotics/common v0.34.4 h1:RQTOm6LxEnucXkED/kruhKKAOL6tbaPzMg
 github.com/aperturerobotics/common v0.34.4/go.mod h1:xnb1VBRs3x2o1PaKg0OlP7SqDaC9Hmrmt9xH85rOS+A=
 github.com/aperturerobotics/common v0.35.0 h1:VU4OPMXJyqT37lTOtNEMa3QLW5tR8YIBAKbjgxSzuZs=
 github.com/aperturerobotics/common v0.35.0/go.mod h1:xnb1VBRs3x2o1PaKg0OlP7SqDaC9Hmrmt9xH85rOS+A=
+github.com/aperturerobotics/common v0.35.1-0.20260808094909-49d3232b4f83 h1:QkFoyeJ0QBw21a+1YR0kB+JaBSY2mHFiIGiFwWUJ/wQ=
+github.com/aperturerobotics/common v0.35.1-0.20260808094909-49d3232b4f83/go.mod h1:sPjrQZeS/yr9kBro4rN2BrYvG9TCn1eIGk7dMH/E2NQ=
+github.com/aperturerobotics/common v0.35.1-0.20260808095531-8f6fd4367389 h1:J/vc+AKFh8hIVJJ2LrAJVwEgIYvFeQ5XANg3dK3OnYk=
+github.com/aperturerobotics/common v0.35.1-0.20260808095531-8f6fd4367389/go.mod h1:sPjrQZeS/yr9kBro4rN2BrYvG9TCn1eIGk7dMH/E2NQ=
+github.com/aperturerobotics/common v0.35.1-0.20260808100945-fe2b561bec93 h1:Bc7ThfLt5ekHZmOH9vGW0PiiuVUl1R+vneFH/G0j5D4=
+github.com/aperturerobotics/common v0.35.1-0.20260808100945-fe2b561bec93/go.mod h1:sPjrQZeS/yr9kBro4rN2BrYvG9TCn1eIGk7dMH/E2NQ=
+github.com/aperturerobotics/common v0.35.1-0.20260808101203-caeb6303ba93 h1:JoERBAX9HuOzopNLZQCT851YnYz9h9nYSpEe6XjcP0o=
+github.com/aperturerobotics/common v0.35.1-0.20260808101203-caeb6303ba93/go.mod h1:sPjrQZeS/yr9kBro4rN2BrYvG9TCn1eIGk7dMH/E2NQ=
+github.com/aperturerobotics/common v0.35.1-0.20260808102028-33a08259dd38 h1:c3IXUqJHt1EAlCyD0d0IrI7YYf4txwICtoh+ylQV6tU=
+github.com/aperturerobotics/common v0.35.1-0.20260808102028-33a08259dd38/go.mod h1:sPjrQZeS/yr9kBro4rN2BrYvG9TCn1eIGk7dMH/E2NQ=
+github.com/aperturerobotics/common v0.35.1-0.20260808123156-c77af26f63bd h1:BTfB1V2X+u3/56negSjrx+AWg+Uk84rFFryvpGTj7f4=
+github.com/aperturerobotics/common v0.35.1-0.20260808123156-c77af26f63bd/go.mod h1:sPjrQZeS/yr9kBro4rN2BrYvG9TCn1eIGk7dMH/E2NQ=
 github.com/aperturerobotics/go-protoc-gen-prost v0.0.0-20260705010911-9f53feac967b h1:MMk+AbWPCMfqc2Lm2bJl8lCCsuvlM2+C0CP10fpE3bc=
 github.com/aperturerobotics/go-protoc-gen-prost v0.0.0-20260705010911-9f53feac967b/go.mod h1:OBb/beWmr/pDIZAUfi86j/4tBh2v5ctTxKMqSnh9c/4=
 github.com/aperturerobotics/go-protoc-wasi v0.0.0-20260712054757-d8078c296c17 h1:WT1YmZjJf8fUF1zKbeNNKXFA+t8Wtbr8AVMAmdKcrUU=
 github.com/aperturerobotics/go-protoc-wasi v0.0.0-20260712054757-d8078c296c17/go.mod h1:vEq8i7EKb32+KXGtIEZjjhNns+BdsL2dUMw4uhy3578=
+github.com/aperturerobotics/go-protoc-wasi v0.0.0-20260808023521-7b1595380c3f h1:UszdpmKBfQd0LdOZjypeRGrHz2tcPpmKpw6SV3DYyN0=
+github.com/aperturerobotics/go-protoc-wasi v0.0.0-20260808023521-7b1595380c3f/go.mod h1:vEq8i7EKb32+KXGtIEZjjhNns+BdsL2dUMw4uhy3578=
 github.com/aperturerobotics/go-websocket v1.8.15-0.20260619192713-a096778f08c1 h1:q2qkdNOrnhAFf6B7TBeUoAYstYWxPvozN+3vJi2jgp0=
 github.com/aperturerobotics/go-websocket v1.8.15-0.20260619192713-a096778f08c1/go.mod h1:9KnSGuqxSXbdB/Oi0I6vvfPLkclfJwMGAQaDDGVgGow=
 github.com/aperturerobotics/json-iterator-lite v1.1.0 h1:ZLLqHhHTKYlmCAP873ras2e/yVU/THtwC+ji3tXLMMg=

package/integration/cross-language/go-client/main.go

@@ -6,19 +6,23 @@ import (
 	"io"
 	"net"
 	"os"
+	"strings"
 
 	"github.com/aperturerobotics/starpc/echo"
+	"github.com/aperturerobotics/starpc/rpcstream"
 	"github.com/aperturerobotics/starpc/srpc"
 )
 
 const bodyTxt = "hello world via starpc cross-language e2e test"
 
 func main() {
-	if len(os.Args) <= 1 {
-		fmt.Fprintf(os.Stderr, "usage: go-client <addr>\n")
+	nested := len(os.Args) >= 3 && os.Args[1] == "--nested"
+	nestedRelease := len(os.Args) >= 3 && os.Args[1] == "--nested-release"
+	if len(os.Args) != 2 && !nested && !nestedRelease {
+		fmt.Fprintf(os.Stderr, "usage: go-client [--nested] <addr>\n")
 		os.Exit(1)
 	}
-	addr := os.Args[1]
+	addr := os.Args[len(os.Args)-1]
 	openStream := func(ctx context.Context, msgHandler srpc.PacketDataHandler, closeHandler srpc.CloseHandler) (srpc.PacketWriter, error) {
 		conn, err := net.Dial("tcp", addr) //nolint:gosec
 		if err != nil {
@@ -48,6 +52,12 @@ func main() {
 		fmt.Fprintf(os.Stderr, "bidi stream test failed: %v\n", err)
 		os.Exit(1)
 	}
+	if nested || nestedRelease {
+		if err := testNested(ctx, echoClient, nestedRelease); err != nil {
+			fmt.Fprintf(os.Stderr, "nested lifecycle test failed: %v\n", err)
+			os.Exit(1)
+		}
+	}
 	fmt.Println("All tests passed.")
 }
 
@@ -143,3 +153,69 @@ func testBidiStream(ctx context.Context, client echo.SRPCEchoerClient) error {
 	fmt.Println("  PASSED")
 	return nil
 }
+
+func testNested(ctx context.Context, parent echo.SRPCEchoerClient, release bool) error {
+	proxy := rpcstream.NewRpcStreamClient(parent.RpcStream, "test", true)
+	if err := testUnary(ctx, echo.NewSRPCEchoerClient(proxy)); err != nil {
+		return fmt.Errorf("nested unary: %w", err)
+	}
+
+	if release {
+		missing := rpcstream.NewRpcStreamClient(parent.RpcStream, "missing", true)
+		var missingOut echo.EchoMsg
+		if err := missing.ExecCall(ctx, "echo.Echoer", "Echo", &echo.EchoMsg{}, &missingOut); err == nil || !strings.Contains(err.Error(), "unknown component: missing") {
+			return fmt.Errorf("unknown component returned wrong result: %v", err)
+		}
+	}
+
+	stream, err := proxy.NewStream(ctx, "echo.Echoer", "EchoBidiStream", nil)
+	if err != nil {
+		return fmt.Errorf("nested bidi: %w", err)
+	}
+	if err := stream.MsgSend(&echo.EchoMsg{Body: "nested later data"}); err != nil {
+		return fmt.Errorf("nested later data: %w", err)
+	}
+	if err := stream.Close(); err != nil {
+		return fmt.Errorf("nested cancel: %w", err)
+	}
+
+	var terminal echo.EchoMsg
+	if err := proxy.ExecCall(ctx, "missing.Service", "Missing", &echo.EchoMsg{}, &terminal); err == nil || !strings.Contains(err.Error(), "missing.Service") {
+		return fmt.Errorf("unknown nested method returned wrong result: %v", err)
+	}
+
+	if release {
+		var terminalError echo.EchoMsg
+		if err := proxy.ExecCall(ctx, "echo.Echoer", "Echo", &echo.EchoMsg{Body: "__nested_error__"}, &terminalError); err == nil || !strings.Contains(err.Error(), "nested terminal error") {
+			return fmt.Errorf("terminal nested error returned wrong result: %v", err)
+		}
+	}
+
+	if release {
+		releaseClient := rpcstream.NewRpcStreamClient(parent.RpcStream, "release", true)
+		var released echo.EchoMsg
+		err := releaseClient.ExecCall(ctx, "echo.Echoer", "Echo", &echo.EchoMsg{Body: "__nested_release__"}, &released)
+		if err == nil || (!strings.Contains(err.Error(), "stream closed before the remote reported completion") && !strings.Contains(err.Error(), "EOF") && !strings.Contains(err.Error(), "canceled")) {
+			return fmt.Errorf("release during active call returned wrong result: %v", err)
+		}
+		status, err := parent.Echo(ctx, &echo.EchoMsg{Body: "__nested_release_status__"})
+		if err != nil {
+			return fmt.Errorf("release completion status failed: %w", err)
+		}
+		if status.GetBody() != "released" {
+			return fmt.Errorf("release completion returned %q", status.GetBody())
+		}
+		if err := releaseClient.ExecCall(ctx, "echo.Echoer", "Echo", &echo.EchoMsg{}, &released); err == nil || !strings.Contains(err.Error(), "unknown component: release") {
+			return fmt.Errorf("released component returned wrong result: %v", err)
+		}
+	}
+
+	direct, err := rpcstream.OpenRpcStream(ctx, parent.RpcStream, "test", true)
+	if err != nil {
+		return fmt.Errorf("nested direct open: %w", err)
+	}
+	if err := direct.Close(); err != nil {
+		return fmt.Errorf("nested abrupt close: %w", err)
+	}
+	return nil
+}

package/integration/cross-language/python-client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+# The checkout supplies generated message packages outside the installed wheel.
+import asyncio
+import sys
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+from google.protobuf import empty_pb2
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from echo import echo_pb2
+from echo.echo_srpc import EchoerClient
+from starpc.call import CallCancelledError, RemoteCallError
+from starpc.client import Client
+from starpc.stream import open_tcp_stream
+
+
+async def main() -> None:
+    args = sys.argv[1:]
+    nested = args[:1] in (["--nested"], ["--nested-release"])
+    strict_nested = args[:1] == ["--nested-release"]
+    if nested:
+        args = args[1:]
+    if len(args) != 1 or ":" not in args[0]:
+        raise ValueError("usage: python-client.py [--nested] host:port")
+    host, port_text = args[0].rsplit(":", 1)
+    port = int(port_text)
+    raw_client = Client(lambda: open_tcp_stream(host, port))
+    client = EchoerClient(raw_client)
+    body = "hello world via python"
+    response = await client.echo(echo_pb2.EchoMsg(body=body))
+    if response.body != body:
+        raise RuntimeError(f"unexpected unary response: {response.body!r}")
+    empty_response = await client.echo(echo_pb2.EchoMsg())
+    if empty_response.body:
+        raise RuntimeError(f"unexpected empty unary response: {empty_response.body!r}")
+    received = [
+        message
+        async for message in client.echo_server_stream(echo_pb2.EchoMsg(body=body))
+    ]
+    if len(received) != 5 or any(message.body != body for message in received):
+        raise RuntimeError("unexpected server-stream response")
+    client_stream = await client.echo_client_stream(_one_request(body))
+    if client_stream.body != body:
+        raise RuntimeError("unexpected client-stream response")
+    bidi = client.echo_bidi_stream(_one_request(body))
+    initial = await bidi.__anext__()
+    if initial.body != "hello from server":
+        raise RuntimeError("unexpected bidi initial response")
+    echoed = await bidi.__anext__()
+    if echoed.body != body:
+        raise RuntimeError("unexpected bidi echo")
+    try:
+        await bidi.__anext__()
+    except StopAsyncIteration:
+        pass
+    else:
+        raise RuntimeError("bidi stream did not terminate")
+    empty = await client.do_nothing(empty_pb2.Empty())
+    if empty.ByteSize() != 0:
+        raise RuntimeError("unexpected DoNothing response")
+
+    unknown = await raw_client.open_call("missing.Service", "Missing")
+    try:
+        await unknown.finish()
+        try:
+            await unknown.receive()
+        except RemoteCallError:
+            pass
+        else:
+            raise RuntimeError("unknown method did not return a remote error")
+    finally:
+        await unknown.aclose()
+
+    cancelled = await raw_client.open_call("echo.Echoer", "EchoBidiStream")
+    await cancelled.cancel()
+    try:
+        await cancelled.wait_closed()
+    except CallCancelledError:
+        pass
+    await cancelled.aclose()
+    if nested:
+        await run_nested_test(client, strict_nested)
+    print("All tests passed.")
+
+
+async def run_nested_test(client: EchoerClient, strict: bool = False) -> None:
+    from starpc.rpcstream import (
+        RpcStreamRemoteError,
+        build_rpc_stream_open_stream,
+    )
+
+    nested_client = Client(build_rpc_stream_open_stream("test", client.rpc_stream))
+    nested_echo = EchoerClient(nested_client)
+    body = "hello world via nested python"
+    response = await nested_echo.echo(echo_pb2.EchoMsg(body=body))
+    if response.body != body:
+        raise RuntimeError(f"unexpected nested unary response: {response.body!r}")
+
+    if strict:
+        try:
+            await nested_echo.echo(echo_pb2.EchoMsg(body="__nested_error__"))
+        except RemoteCallError:
+            pass
+        else:
+            raise RuntimeError("terminal nested error unexpectedly succeeded")
+
+    if strict:
+        missing = Client(build_rpc_stream_open_stream("missing", client.rpc_stream))
+        try:
+            await missing.open_call("echo.Echoer", "Echo")
+        except RpcStreamRemoteError:
+            pass
+        else:
+            raise RuntimeError("unknown component unexpectedly succeeded")
+
+    terminal = await nested_client.open_call("missing.Service", "Missing")
+    try:
+        await terminal.receive()
+    except RemoteCallError:
+        pass
+    else:
+        raise RuntimeError("unknown nested method unexpectedly succeeded")
+    finally:
+        await terminal.aclose()
+
+    cancelled = await nested_client.open_call("echo.Echoer", "EchoBidiStream")
+    await cancelled.send(
+        echo_pb2.EchoMsg(body="nested later data").SerializeToString(deterministic=True)
+    )
+    await cancelled.cancel()
+    try:
+        await cancelled.wait_closed()
+    except CallCancelledError:
+        pass
+    await cancelled.aclose()
+
+
+async def _one_request(body: str) -> AsyncIterator[echo_pb2.EchoMsg]:
+    yield echo_pb2.EchoMsg(body=body)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/integration/cross-language/python-server.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+# The checkout supplies generated message packages outside the installed wheel.
+import asyncio
+import signal
+import sys
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+from google.protobuf import empty_pb2
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from echo import echo_pb2
+from echo.echo_srpc import register_echoer
+from rpcstream import rpcstream_pb2
+from starpc.rpcstream import ComponentRegistry, handle_rpc_stream
+from starpc.server import Server, ServiceRegistry
+from starpc.stream import TCPStreamServer
+
+
+class Implementation:
+    def __init__(self, components: ComponentRegistry) -> None:
+        self._components = components
+        self._release_task: asyncio.Task[None] | None = None
+        self._release_complete = asyncio.Event()
+
+    async def _release_component(self) -> None:
+        try:
+            await self._components.unregister("release")
+        finally:
+            self._release_complete.set()
+
+    async def wait_for_release(self) -> None:
+        task = self._release_task
+        if task is not None:
+            await task
+
+    async def echo(self, request: echo_pb2.EchoMsg) -> echo_pb2.EchoMsg:
+        if request.body == "__nested_error__":
+            raise RuntimeError("nested terminal error")
+        if request.body == "__nested_release__":
+            if self._release_task is None:
+                self._release_task = asyncio.create_task(self._release_component())
+            await asyncio.Future()
+        if request.body == "__nested_release_status__":
+            await self._release_complete.wait()
+            await self.wait_for_release()
+            return echo_pb2.EchoMsg(body="released")
+        return echo_pb2.EchoMsg(body=request.body)
+
+    async def echo_server_stream(
+        self, request: echo_pb2.EchoMsg
+    ) -> AsyncIterator[echo_pb2.EchoMsg]:
+        for _ in range(5):
+            yield echo_pb2.EchoMsg(body=request.body)
+            await asyncio.sleep(0.2)
+
+    async def echo_client_stream(
+        self, requests: AsyncIterator[echo_pb2.EchoMsg]
+    ) -> echo_pb2.EchoMsg:
+        async for request in requests:
+            return request
+        return echo_pb2.EchoMsg()
+
+    async def echo_bidi_stream(
+        self, requests: AsyncIterator[echo_pb2.EchoMsg]
+    ) -> AsyncIterator[echo_pb2.EchoMsg]:
+        yield echo_pb2.EchoMsg(body="hello from server")
+        async for request in requests:
+            yield request
+
+    def rpc_stream(
+        self, requests: AsyncIterator[rpcstream_pb2.RpcStreamPacket]
+    ) -> AsyncIterator[rpcstream_pb2.RpcStreamPacket]:
+        return handle_rpc_stream(requests, self._components)
+
+    async def do_nothing(self, request: empty_pb2.Empty) -> empty_pb2.Empty:
+        return request
+
+
+async def main() -> None:
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 0
+    registry = ServiceRegistry()
+    components = ComponentRegistry()
+    await components.register("test", Server(registry))
+    await components.register("release", Server(registry))
+    implementation = Implementation(components)
+    register_echoer(registry, implementation)
+    server = TCPStreamServer()
+    await server.start("127.0.0.1", port)
+    host, bound_port = server.address
+    print(f"LISTENING {host}:{bound_port}", flush=True)
+    rpc_server = Server(registry)
+    tasks: set[asyncio.Task[None]] = set()
+    errors: list[BaseException] = []
+    stopping = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stopping.set)
+
+    def observe_task(task: asyncio.Task[None]) -> None:
+        tasks.discard(task)
+        if not task.cancelled() and (error := task.exception()) is not None:
+            errors.append(error)
+
+    try:
+        while not stopping.is_set():
+            accepting = asyncio.create_task(server.accept())
+            stopped = asyncio.create_task(stopping.wait())
+            done, _ = await asyncio.wait(
+                {accepting, stopped}, return_when=asyncio.FIRST_COMPLETED
+            )
+            if stopped in done:
+                accepting.cancel()
+                await asyncio.gather(accepting, return_exceptions=True)
+                break
+            stopped.cancel()
+            await asyncio.gather(stopped, return_exceptions=True)
+            stream = accepting.result()
+            task = asyncio.create_task(rpc_server.serve(stream))
+            tasks.add(task)
+            task.add_done_callback(observe_task)
+    finally:
+        await server.aclose()
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await implementation.wait_for_release()
+        await components.unregister("test")
+        await components.unregister("release")
+        if errors:
+            raise ExceptionGroup("cross-language server tasks failed", errors)
+        if components._components or components._retired:
+            raise RuntimeError("nested component cleanup is incomplete")
+        print("NESTED_CLEAN", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())