starpc 0.52.0 → 0.52.1

package/integration/cross-language/tcp-packet-stream.test.ts

@@ -0,0 +1,154 @@
+import net from 'net'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { pushable } from 'it-pushable'
+
+import { tcpSocketToPacketStream } from './tcp-packet-stream.js'
+
+const sockets: net.Socket[] = []
+const servers: net.Server[] = []
+
+afterEach(() => {
+  for (const socket of sockets) socket.destroy()
+  for (const server of servers) server.close()
+  sockets.length = 0
+  servers.length = 0
+})
+
+describe('TCP PacketStream lifecycle', () => {
+  it('settles a blocked source when the peer ends cleanly', async () => {
+    const { local, peer } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const pending = stream.source.next()
+
+    peer.end()
+
+    await expect(settleBeforeTimeout(pending)).resolves.toEqual({
+      done: true,
+      value: undefined,
+    })
+  })
+
+  it('reports a truncated frame when the peer ends', async () => {
+    const { local, peer } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const pending = stream.source.next()
+
+    peer.end(Buffer.from([4, 0, 0, 0, 10, 1]))
+
+    await expect(settleBeforeTimeout(pending)).rejects.toThrow(
+      'truncated packet frame',
+    )
+  })
+
+  it('rejects a blocked source with the abort error', async () => {
+    const { local } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const pending = stream.source.next()
+    const error = new Error('stopped')
+
+    stream.abort(error)
+
+    await expect(settleBeforeTimeout(pending)).rejects.toBe(error)
+  })
+
+  it('settles a blocked sink when closed', async () => {
+    const { local } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const input = pushable<Uint8Array>({ objectMode: true })
+    const pending = stream.sink(input)
+
+    await stream.close()
+
+    await expect(pending).resolves.toBeUndefined()
+  })
+
+  it('settles an in-flight socket write when closed', async () => {
+    const { local } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const input = pushable<Uint8Array>({ objectMode: true })
+    const writeStarted = Promise.withResolvers<void>()
+    vi.spyOn(local, 'write').mockImplementation(((
+      _data: Uint8Array,
+      _callback: (error?: Error) => void,
+    ) => {
+      writeStarted.resolve()
+      return true
+    }) as typeof local.write)
+    input.push(new Uint8Array([1]))
+    const pending = stream.sink(input)
+    await writeStarted.promise
+
+    await stream.close()
+
+    await expect(settleBeforeTimeout(pending)).resolves.toBeUndefined()
+  })
+
+  it('rejects a blocked sink with the abort error', async () => {
+    const { local } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const input = pushable<Uint8Array>({ objectMode: true })
+    const pending = stream.sink(input)
+    const error = new Error('stopped')
+
+    stream.abort(error)
+
+    await expect(pending).rejects.toBe(error)
+  })
+
+  it('does not write ready input after close', async () => {
+    const { local, peer } = await connectSockets()
+    const stream = tcpSocketToPacketStream(local)
+    const input = pushable<Uint8Array>({ objectMode: true })
+    const received: Buffer[] = []
+    peer.on('data', (data) => {
+      if (typeof data !== 'string') received.push(data)
+    })
+    input.push(new Uint8Array([1]))
+
+    const pending = stream.sink(input)
+    await stream.close()
+    await pending
+    await new Promise<void>((resolve) => peer.once('close', () => resolve()))
+
+    expect(received).toEqual([])
+  })
+})
+
+async function connectSockets(): Promise<{
+  local: net.Socket
+  peer: net.Socket
+}> {
+  const accepted = Promise.withResolvers<net.Socket>()
+  const server = net.createServer((socket) => accepted.resolve(socket))
+  servers.push(server)
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const address = server.address() as net.AddressInfo
+  const local = net.connect(address.port, address.address)
+  await new Promise<void>((resolve, reject) => {
+    local.once('connect', resolve)
+    local.once('error', reject)
+  })
+  const peer = await accepted.promise
+  sockets.push(local, peer)
+  return { local, peer }
+}
+
+async function settleBeforeTimeout<T>(promise: Promise<T>): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error('source stayed blocked')),
+          500,
+        )
+      }),
+    ])
+  } finally {
+    clearTimeout(timeout)
+  }
+}

package/integration/cross-language/tcp-packet-stream.ts

@@ -0,0 +1,121 @@
+import net from 'net'
+import { pipe } from 'it-pipe'
+import { pushable } from 'it-pushable'
+import type { Source } from 'it-stream-types'
+
+import { combineUint8ArrayListTransform } from '../../srpc/array-list.js'
+import {
+  parseLengthPrefixTransform,
+  prependLengthPrefixTransform,
+} from '../../srpc/packet.js'
+import type { PacketStream } from '../../srpc/stream.js'
+import {
+  closeIterator,
+  sourceIterator,
+  TerminationGate,
+} from '../../srpc/termination.js'
+
+// tcpSocketToPacketStream wraps a Node.js TCP socket into a PacketStream.
+export function tcpSocketToPacketStream(socket: net.Socket): PacketStream {
+  const sourceTermination = new TerminationGate()
+  const sinkTermination = new TerminationGate()
+  const bytes = pushable<Uint8Array>({ objectMode: true })
+  let bytesEnded = false
+
+  const endBytes = (error?: Error) => {
+    if (bytesEnded) return
+    bytesEnded = true
+    bytes.end(error)
+  }
+  const terminate = (error?: Error): boolean => {
+    const first = sourceTermination.terminate(error)
+    sinkTermination.terminate(error)
+    endBytes(error)
+    return first
+  }
+
+  socket.on('data', (data: Buffer) => {
+    if (!bytesEnded) bytes.push(new Uint8Array(data))
+  })
+  socket.on('end', () => endBytes())
+  socket.on('error', (error) => terminate(error))
+  socket.on('close', () => {
+    endBytes()
+    sinkTermination.terminate()
+  })
+
+  const close = async (): Promise<void> => {
+    if (terminate()) socket.destroy()
+  }
+  const abort = (error: Error): void => {
+    if (terminate(error)) socket.destroy(error)
+  }
+
+  return {
+    close,
+    abort,
+    source: (async function* () {
+      const packets = pipe(
+        bytes,
+        parseLengthPrefixTransform(),
+        combineUint8ArrayListTransform(),
+      )[Symbol.asyncIterator]()
+      try {
+        while (true) {
+          const next = await sourceTermination.next(packets)
+          if ('terminated' in next) {
+            if (next.error) throw next.error
+            return
+          }
+          if ('error' in next) throw next.error
+          if (next.result.done) return
+          yield next.result.value
+        }
+      } finally {
+        closeIterator(packets)
+      }
+    })(),
+    sink: async (source: Source<Uint8Array>): Promise<void> => {
+      const iterator = sourceIterator(
+        pipe(source, prependLengthPrefixTransform()),
+      )
+      try {
+        while (true) {
+          const next = await sinkTermination.next(iterator)
+          if ('terminated' in next) {
+            if (next.error) throw next.error
+            return
+          }
+          if ('error' in next) throw next.error
+          if (next.result.done) {
+            socket.end()
+            return
+          }
+          const data =
+            next.result.value instanceof Uint8Array
+              ? next.result.value
+              : next.result.value.subarray()
+          const written = await sinkTermination.wait(
+            new Promise<void>((resolve, reject) => {
+              socket.write(data, (error) => {
+                if (error) reject(error)
+                else resolve()
+              })
+            }),
+          )
+          if ('terminated' in written) {
+            if (written.error) throw written.error
+            return
+          }
+          if ('error' in written) throw written.error
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err))
+        abort(error)
+        throw error
+      } finally {
+        closeIterator(iterator)
+      }
+    },
+  }
+}

package/integration/cross-language/ts-client.ts

@@ -1,59 +1,71 @@
 import net from 'net'
-import { pipe } from 'it-pipe'
 import { pushable } from 'it-pushable'
 import { Client } from '../../srpc/client.js'
 import {
-  parseLengthPrefixTransform,
-  prependLengthPrefixTransform,
-} from '../../srpc/packet.js'
-import { combineUint8ArrayListTransform } from '../../srpc/array-list.js'
-import { runClientTest } from '../../echo/index.js'
+  runClientTest,
+  runAbortControllerTest,
+  runRpcStreamTest,
+} from '../../echo/client-test.js'
+import { EchoerClient } from '../../echo/echo_srpc.pb.js'
 import type { OpenStreamFunc, PacketStream } from '../../srpc/stream.js'
-import type { Source } from 'it-stream-types'
+import { tcpSocketToPacketStream } from './tcp-packet-stream.js'
 
-// tcpSocketToPacketStream wraps a Node.js TCP socket into a PacketStream.
-function tcpSocketToPacketStream(socket: net.Socket): PacketStream {
-  const socketSource = async function* (): AsyncGenerator<Uint8Array> {
-    const source = pushable<Uint8Array>({ objectMode: true })
-    socket.on('data', (data: Buffer) => {
-      source.push(new Uint8Array(data))
-    })
-    socket.on('end', () => source.end())
-    socket.on('error', (err) => source.end(err))
-    socket.on('close', () => source.end())
-    yield* pipe(
-      source,
-      parseLengthPrefixTransform(),
-      combineUint8ArrayListTransform(),
-    )
+async function runEchoBidiStreamTest(client: Client): Promise<void> {
+  const request = pushable<{ body: string }>({ objectMode: true })
+  const stream = new EchoerClient(client).EchoBidiStream(request)
+  const iterator = stream[Symbol.asyncIterator]()
+
+  const initial = await iterator.next()
+  if (initial.done || initial.value.body !== 'hello from server') {
+    throw new Error('expected initial bidi message "hello from server"')
+  }
+
+  const body = 'hello from TypeScript bidi client'
+  request.push({ body })
+  request.end()
+
+  const echo = await iterator.next()
+  if (echo.done || echo.value.body !== body) {
+    throw new Error(`expected bidi echo ${JSON.stringify(body)}`)
   }
 
-  return {
-    source: socketSource(),
-    sink: async (source: Source<Uint8Array>): Promise<void> => {
-      for await (const chunk of pipe(source, prependLengthPrefixTransform())) {
-        const data = chunk instanceof Uint8Array ? chunk : chunk.subarray()
-        await new Promise<void>((resolve, reject) => {
-          socket.write(data, (err) => {
-            if (err) reject(err)
-            else resolve()
-          })
-        })
-      }
-      socket.end()
-    },
+  const terminal = await iterator.next()
+  if (!terminal.done) {
+    throw new Error('expected bidi stream to terminate after input closes')
   }
 }
 
+function parseAddr(addr: string): { host: string; port: number } {
+  const match = /^(?:\[([^\]]+)\]|([^:]+)):(\d+)$/.exec(addr)
+  if (!match) {
+    throw new Error(`invalid host:port address: ${addr}`)
+  }
+
+  const port = Number(match[3])
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid port: ${match[3]}`)
+  }
+
+  return { host: match[1] ?? match[2], port }
+}
+
 async function main() {
-  const addr = process.argv[2]
+  const args = process.argv.slice(2)
+  const lifecycle = args.includes('lifecycle')
+  const nested = args.includes('--nested') || args.includes('--nested-release')
+  const nestedRelease = args.includes('--nested-release')
+  const addr = args.find(
+    (arg) =>
+      arg !== 'lifecycle' && arg !== '--nested' && arg !== '--nested-release',
+  )
   if (!addr) {
-    console.error('usage: ts-client <host:port>')
+    console.error(
+      'usage: ts-client [--nested] [--nested-release] [lifecycle] <host:port>',
+    )
     process.exit(1)
   }
 
-  const [host, portStr] = addr.split(':')
-  const port = parseInt(portStr, 10)
+  const { host, port } = parseAddr(addr)
   const openStream: OpenStreamFunc = async (): Promise<PacketStream> => {
     const { promise, resolve, reject } = Promise.withResolvers<PacketStream>()
     const socket = net.connect(port, host, () => {
@@ -66,6 +78,16 @@ async function main() {
   const client = new Client(openStream)
   console.log('Running client test via TCP...')
   await runClientTest(client)
+  console.log('Running EchoBidiStream test via TCP...')
+  await runEchoBidiStreamTest(client)
+  if (lifecycle) {
+    console.log('Running abort controller test via TCP...')
+    await runAbortControllerTest(client)
+  }
+  if (nested) {
+    console.log('Running RpcStream test via TCP...')
+    await runRpcStreamTest(client, nestedRelease)
+  }
   console.log('All tests passed.')
 }
 

package/integration/cross-language/ts-server.ts

@@ -1,53 +1,9 @@
 import net from 'net'
-import { pipe } from 'it-pipe'
-import { pushable } from 'it-pushable'
-import type { Source } from 'it-stream-types'
 
 import { createMux, createHandler, Server } from '../../srpc/index.js'
-import {
-  parseLengthPrefixTransform,
-  prependLengthPrefixTransform,
-} from '../../srpc/packet.js'
-import { combineUint8ArrayListTransform } from '../../srpc/array-list.js'
 import { EchoerServer } from '../../echo/index.js'
 import { EchoerDefinition } from '../../echo/echo_srpc.pb.js'
-import type { PacketStream } from '../../srpc/stream.js'
-
-// tcpSocketToPacketStream wraps a Node.js TCP socket into a PacketStream.
-// Each Uint8Array in source/sink is one packet (no length prefix).
-function tcpSocketToPacketStream(socket: net.Socket): PacketStream {
-  // Source: read from socket, strip length prefix, yield individual packets.
-  const socketSource = async function* (): AsyncGenerator<Uint8Array> {
-    const source = pushable<Uint8Array>({ objectMode: true })
-    socket.on('data', (data: Buffer) => {
-      source.push(new Uint8Array(data))
-    })
-    socket.on('end', () => source.end())
-    socket.on('error', (err) => source.end(err))
-    socket.on('close', () => source.end())
-    yield* pipe(
-      source,
-      parseLengthPrefixTransform(),
-      combineUint8ArrayListTransform(),
-    )
-  }
-
-  return {
-    source: socketSource(),
-    sink: async (source: Source<Uint8Array>): Promise<void> => {
-      for await (const chunk of pipe(source, prependLengthPrefixTransform())) {
-        const data = chunk instanceof Uint8Array ? chunk : chunk.subarray()
-        await new Promise<void>((resolve, reject) => {
-          socket.write(data, (err) => {
-            if (err) reject(err)
-            else resolve()
-          })
-        })
-      }
-      socket.end()
-    },
-  }
-}
+import { tcpSocketToPacketStream } from './tcp-packet-stream.js'
 
 const mux = createMux()
 const server = new Server(mux.lookupMethod)

package/mock/mock_pb2.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: github.com/aperturerobotics/starpc/mock/mock.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/mock/mock.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n2github.com/aperturerobotics/starpc/mock/mock.proto\x12\x08\x65\x32\x65.mock\"\x17\n\x07MockMsg\x12\x0c\n\x04\x62ody\x18\x01 \x01(\t2;\n\x04Mock\x12\x33\n\x0bMockRequest\x12\x11.e2e.mock.MockMsg\x1a\x11.e2e.mock.MockMsgb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'github.com.aperturerobotics.starpc.mock.mock_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_MOCKMSG']._serialized_start=64
+  _globals['_MOCKMSG']._serialized_end=87
+  _globals['_MOCK']._serialized_start=89
+  _globals['_MOCK']._serialized_end=148
+# @@protoc_insertion_point(module_scope)

package/mock/mock_pb2.pyi

@@ -0,0 +1,11 @@
+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 MockMsg(_message.Message):
+    __slots__ = ("body",)
+    BODY_FIELD_NUMBER: _ClassVar[int]
+    body: str
+    def __init__(self, body: _Optional[str] = ...) -> None: ...

package/mock/mock_srpc.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from mock import (
+    mock_pb2 as _github_com_aperturerobotics_starpc_mock_mock_pb2,
+)
+from starpc.call import Call, CallProtocolError
+from starpc.client import Client
+from starpc.server import ServiceRegistry
+from starpc.service import MethodDescriptor, ServiceDescriptor
+
+MOCK_SERVICE = ServiceDescriptor(
+    "e2e.mock.Mock",
+    (
+        MethodDescriptor(
+            "MockRequest",
+            _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg,
+            _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg,
+            False,
+            False,
+        ),
+    ),
+)
+
+
+class MockClient:
+    def __init__(self, client: Client, service: str | None = None) -> None:
+        self._client = client
+        self._service = service or "e2e.mock.Mock"
+
+    async def mock_request(
+        self, request: _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg
+    ) -> _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg:
+        call = await self._client.open_call(
+            self._service, "MockRequest", request.SerializeToString(deterministic=True)
+        )
+        try:
+            data = await call.receive()
+            if data is None:
+                raise CallProtocolError("missing unary response")
+            response = _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg()
+            response.ParseFromString(data)
+            if await call.receive() is not None:
+                raise CallProtocolError("extra unary response")
+            return response
+        finally:
+            await call.aclose()
+
+
+class MockServer(Protocol):
+    async def mock_request(
+        self, request: _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg
+    ) -> _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg: ...
+
+
+def register_mock(
+    registry: ServiceRegistry,
+    implementation: MockServer,
+    service: str = "e2e.mock.Mock",
+) -> None:
+    async def mock_request_handler(call: Call) -> None:
+        first = await call.receive()
+        if first is None:
+            raise CallProtocolError("missing initial request")
+        request = _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg()
+        request.ParseFromString(first)
+        response = await implementation.mock_request(request)
+        await call.send(response.SerializeToString(deterministic=True))
+
+    registry.register(service, "MockRequest", mock_request_handler)

package/mock/mock_srpc.pyi

@@ -0,0 +1,27 @@
+from typing import Protocol
+
+from mock import (
+    mock_pb2 as _github_com_aperturerobotics_starpc_mock_mock_pb2,
+)
+from starpc.client import Client
+from starpc.server import ServiceRegistry
+from starpc.service import ServiceDescriptor
+
+MOCK_SERVICE: ServiceDescriptor
+
+class MockClient:
+    def __init__(self, client: Client, service: str | None = None) -> None: ...
+    async def mock_request(
+        self, request: _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg
+    ) -> _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg: ...
+
+class MockServer(Protocol):
+    async def mock_request(
+        self, request: _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg
+    ) -> _github_com_aperturerobotics_starpc_mock_mock_pb2.MockMsg: ...
+
+def register_mock(
+    registry: ServiceRegistry,
+    implementation: MockServer,
+    service: str = "e2e.mock.Mock",
+) -> None: ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starpc",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "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"
+    ]
   }
 }