starpc 0.49.18 → 0.49.20

package/README.md

@@ -3,14 +3,12 @@
 [![npm](https://img.shields.io/npm/v/starpc?style=flat-square)](https://www.npmjs.com/package/starpc)
 [![crates.io](https://img.shields.io/crates/v/starpc.svg?style=flat-square)](https://crates.io/crates/starpc)
 [![Build status](https://img.shields.io/github/actions/workflow/status/aperturerobotics/starpc/tests.yml?style=flat-square&branch=master)](https://github.com/aperturerobotics/starpc/actions)
-[![GoDoc Widget]][GoDoc] [![Go Report Card Widget]][Go Report Card]
+[![GoDoc Widget]][GoDoc]
 
 > Streaming Protobuf RPC with bidirectional streaming over any multiplexed transport.
 
 [GoDoc]: https://godoc.org/github.com/aperturerobotics/starpc
 [GoDoc Widget]: https://godoc.org/github.com/aperturerobotics/starpc?status.svg
-[Go Report Card Widget]: https://goreportcard.com/badge/github.com/aperturerobotics/starpc
-[Go Report Card]: https://goreportcard.com/report/github.com/aperturerobotics/starpc
 
 ## Table of Contents
 

package/cmd/protoc-gen-es-starpc/typescript.ts

@@ -26,6 +26,14 @@ import {
 } from '@aptre/protobuf-es-lite/protoplugin/ecmascript'
 
 const MessageStream = createImportSymbol('MessageStream', 'starpc')
+const RuntimeMethodKind = createImportSymbol(
+  'MethodKind',
+  '@aptre/protobuf-es-lite',
+)
+const RuntimeMethodIdempotency = createImportSymbol(
+  'MethodIdempotency',
+  '@aptre/protobuf-es-lite',
+)
 // const Message = createImportSymbol('Message', '@aptre/protobuf-es-lite')
 
 export function generateTs(schema: Schema) {
@@ -33,19 +41,16 @@ export function generateTs(schema: Schema) {
     const file = schema.generateFile(protoFile.name + '_srpc.pb.ts')
     file.preamble(protoFile)
     for (const service of protoFile.services) {
-      generateService(schema, file, service)
+      generateService(file, service)
     }
   }
 }
 
 // prettier-ignore
 function generateService(
-  schema: Schema,
   f: GeneratedFile,
   service: DescService
 ) {
-  const { MethodKind: rtMethodKind, MethodIdempotency: rtMethodIdempotency } =
-    schema.runtime;
 
 // NOTE: This matches generateService from @connectrpc/protoc-gen-connect-es.
   f.print(f.jsDoc(service));
@@ -60,7 +65,7 @@ function generateService(
     f.print("      O: ", method.output, ",");
     f.print(
       "      kind: ",
-      rtMethodKind,
+      RuntimeMethodKind,
       ".",
       MethodKind[method.methodKind],
       ","
@@ -68,7 +73,7 @@ function generateService(
     if (method.idempotency !== undefined) {
       f.print(
         "      idempotency: ",
-        rtMethodIdempotency,
+        RuntimeMethodIdempotency,
         ".",
         MethodIdempotency[method.idempotency],
         ","

package/dist/cmd/protoc-gen-es-starpc/typescript.js

@@ -15,19 +15,20 @@
 import { MethodIdempotency, MethodKind, localName, } from '@aptre/protobuf-es-lite';
 import { createImportSymbol, } from '@aptre/protobuf-es-lite/protoplugin/ecmascript';
 const MessageStream = createImportSymbol('MessageStream', 'starpc');
+const RuntimeMethodKind = createImportSymbol('MethodKind', '@aptre/protobuf-es-lite');
+const RuntimeMethodIdempotency = createImportSymbol('MethodIdempotency', '@aptre/protobuf-es-lite');
 // const Message = createImportSymbol('Message', '@aptre/protobuf-es-lite')
 export function generateTs(schema) {
     for (const protoFile of schema.files) {
         const file = schema.generateFile(protoFile.name + '_srpc.pb.ts');
         file.preamble(protoFile);
         for (const service of protoFile.services) {
-            generateService(schema, file, service);
+            generateService(file, service);
         }
     }
 }
 // prettier-ignore
-function generateService(schema, f, service) {
-    const { MethodKind: rtMethodKind, MethodIdempotency: rtMethodIdempotency } = schema.runtime;
+function generateService(f, service) {
     // NOTE: This matches generateService from @connectrpc/protoc-gen-connect-es.
     f.print(f.jsDoc(service));
     f.print(f.exportDecl("const", localName(service)), "Definition = {");
@@ -39,9 +40,9 @@ function generateService(schema, f, service) {
         f.print(`      name: `, f.string(method.name), `,`);
         f.print("      I: ", method.input, ",");
         f.print("      O: ", method.output, ",");
-        f.print("      kind: ", rtMethodKind, ".", MethodKind[method.methodKind], ",");
+        f.print("      kind: ", RuntimeMethodKind, ".", MethodKind[method.methodKind], ",");
         if (method.idempotency !== undefined) {
-            f.print("      idempotency: ", rtMethodIdempotency, ".", MethodIdempotency[method.idempotency], ",");
+            f.print("      idempotency: ", RuntimeMethodIdempotency, ".", MethodIdempotency[method.idempotency], ",");
         }
         // In case we start supporting options, we have to surface them here
         f.print("    },");

package/dist/echo/echo.pb.d.ts

@@ -1,4 +1,4 @@
-import type { MessageType } from '@aptre/protobuf-es-lite';
+import type { MessageType } from '@aptre/protobuf-es-lite/message';
 export declare const protobufPackage = "echo";
 /**
  * EchoMsg is the message body for Echo.

package/dist/echo/echo.pb.js

@@ -1,10 +1,10 @@
 // @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
 // @generated from file github.com/aperturerobotics/starpc/echo/echo.proto (package echo, syntax proto3)
 /* eslint-disable */
-import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';
+import { createMessageType } from '@aptre/protobuf-es-lite/message';
+import { ScalarType } from '@aptre/protobuf-es-lite/scalar';
 export const protobufPackage = 'echo';
-// EchoMsg contains the message type declaration for EchoMsg.
-export const EchoMsg = createMessageType({
+export const EchoMsg = /* @__PURE__ */ createMessageType({
     typeName: 'echo.EchoMsg',
     fields: [
         { no: 1, name: 'body', kind: 'scalar', T: ScalarType.STRING },

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

@@ -1,10 +1,25 @@
 import net from 'net';
+import { closeSync, openSync, writeSync } from 'node:fs';
 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/client-test.js';
+import { EchoMsg, runClientTest } from '../../echo/index.js';
+function emitReceiptEvent(line) {
+    console.log(line);
+    const fifo = process.env.RECEIPT_EVENT_FIFO;
+    if (!fifo) {
+        return;
+    }
+    const fd = openSync(fifo, 'w');
+    try {
+        writeSync(fd, `${line}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 // tcpSocketToPacketStream wraps a Node.js TCP socket into a PacketStream.
 function tcpSocketToPacketStream(socket) {
     const socketSource = async function* () {
@@ -36,26 +51,84 @@ function tcpSocketToPacketStream(socket) {
     };
 }
 async function main() {
-    const addr = process.argv[2];
+    const receiptMode = process.argv[2] === 'receipt';
+    const receiptCase = receiptMode ? process.argv[3] : undefined;
+    const addr = receiptMode ? process.argv[4] : process.argv[2];
     if (!addr) {
-        console.error('usage: ts-client <host:port>');
+        console.error('usage: ts-client [receipt <case>] <host:port>');
         process.exit(1);
     }
+    if (receiptMode &&
+        !['commit', 'abort', 'loss', 'bare-close'].includes(receiptCase ?? '')) {
+        throw new Error(`unknown receipt case: ${receiptCase}`);
+    }
     const [host, portStr] = addr.split(':');
     const port = parseInt(portStr, 10);
+    let activeSocket;
     const openStream = async () => {
-        return new Promise((resolve, reject) => {
-            const socket = net.connect(port, host, () => {
-                resolve(tcpSocketToPacketStream(socket));
-            });
-            socket.on('error', reject);
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const socket = net.connect(port, host, () => {
+            activeSocket = socket;
+            resolve(tcpSocketToPacketStream(socket));
         });
+        socket.on('error', reject);
+        return promise;
     };
     const client = new Client(openStream);
-    console.log('Running client test via TCP...');
-    await runClientTest(client);
+    if (receiptMode) {
+        console.log(`Running held receipt test via TCP (${receiptCase})...`);
+        const request = EchoMsg.create({ body: 'held receipt' });
+        const held = await client.requestWithReceipt('echo.Echoer', 'Echo', EchoMsg.toBinary(request));
+        const result = EchoMsg.fromBinary(held.response);
+        if (result.body !== request.body) {
+            throw new Error(`expected ${request.body}, got ${result.body}`);
+        }
+        switch (receiptCase) {
+            case 'commit':
+                await held.receipt.commit();
+                break;
+            case 'abort':
+                await held.receipt.abort();
+                break;
+            case 'loss':
+                activeSocket?.resetAndDestroy();
+                await expectReceiptFailure(held.receipt);
+                break;
+            case 'bare-close':
+                activeSocket?.end();
+                await expectReceiptFailure(held.receipt);
+                break;
+        }
+        emitReceiptEvent(`CLIENT_RECEIPT_RESOLVED ${receiptTerminalName(receiptCase ?? '')}`);
+    }
+    else {
+        console.log('Running client test via TCP...');
+        await runClientTest(client);
+    }
     console.log('All tests passed.');
-    process.exit(0);
+}
+function receiptTerminalName(receiptCase) {
+    switch (receiptCase) {
+        case 'commit':
+            return 'committed';
+        case 'abort':
+            return 'canceled';
+        case 'loss':
+            return 'transportLost';
+        case 'bare-close':
+            return 'closed';
+        default:
+            return 'unknown';
+    }
+}
+async function expectReceiptFailure(receipt) {
+    try {
+        await receipt.commit();
+    }
+    catch {
+        return;
+    }
+    throw new Error('receipt commit unexpectedly succeeded');
 }
 process.on('unhandledRejection', (ev) => {
     console.error('Unhandled rejection', ev);

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

@@ -1,11 +1,27 @@
 import net from 'net';
+import { closeSync, openSync, writeSync } from 'node:fs';
 import { pipe } from 'it-pipe';
 import { pushable } from 'it-pushable';
 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/server.js';
+import { EchoerServer, EchoMsg } from '../../echo/index.js';
 import { EchoerDefinition } from '../../echo/echo_srpc.pb.js';
+import { Packet } from '../../srpc/rpcproto.pb.js';
+function emitReceiptEvent(line) {
+    console.log(line);
+    const fifo = process.env.RECEIPT_EVENT_FIFO;
+    if (!fifo) {
+        return;
+    }
+    const fd = openSync(fifo, 'w');
+    try {
+        writeSync(fd, `${line}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 // tcpSocketToPacketStream wraps a Node.js TCP socket into a PacketStream.
 // Each Uint8Array in source/sink is one packet (no length prefix).
 function tcpSocketToPacketStream(socket) {
@@ -25,7 +41,12 @@ function tcpSocketToPacketStream(socket) {
         sink: async (source) => {
             for await (const chunk of pipe(source, prependLengthPrefixTransform())) {
                 const data = chunk instanceof Uint8Array ? chunk : chunk.subarray();
-                await new Promise((resolve, reject) => {
+                const packet = Packet.fromBinary(data.subarray(4));
+                const receiptCompletion = receiptMode &&
+                    packet.body?.case === 'callData' &&
+                    packet.body.value.complete &&
+                    !packet.body.value.error;
+                const writeDone = new Promise((resolve, reject) => {
                     socket.write(data, (err) => {
                         if (err)
                             reject(err);
@@ -33,15 +54,69 @@ function tcpSocketToPacketStream(socket) {
                             resolve();
                     });
                 });
+                if (receiptCompletion) {
+                    emitReceiptEvent('SERVER_RECEIPT_ACK committed');
+                }
+                await writeDone;
+                if (receiptCompletion) {
+                    finishReceiptServer();
+                }
             }
             socket.end();
         },
     };
 }
 const mux = createMux();
+const receiptMode = process.argv[2] === 'receipt';
+const receiptCase = receiptMode ? process.argv[3] : undefined;
+if (receiptMode &&
+    !['commit', 'abort', 'loss', 'bare-close'].includes(receiptCase ?? '')) {
+    console.error(`unknown receipt case: ${receiptCase}`);
+    process.exit(1);
+}
+const receiptServerDone = Promise.withResolvers();
+let receiptServerFinished = false;
+function finishReceiptServer() {
+    if (!receiptServerFinished) {
+        receiptServerFinished = true;
+        receiptServerDone.resolve();
+    }
+}
+if (receiptMode) {
+    mux.registerLookupMethod(async (serviceID, methodID) => {
+        if (serviceID !== 'echo.Echoer' || methodID !== 'Echo') {
+            return null;
+        }
+        return async (dataSource, dataSink, invocation) => {
+            let requestData;
+            for await (const data of dataSource) {
+                requestData = data;
+                break;
+            }
+            if (!requestData) {
+                throw new Error('receipt request was empty');
+            }
+            const requestMsg = EchoMsg.fromBinary(requestData);
+            await dataSink((async function* () {
+                yield EchoMsg.toBinary(requestMsg);
+                if (!invocation) {
+                    throw new Error('receipt invocation was missing');
+                }
+                emitReceiptEvent('SERVER_RECEIPT_WAITING');
+                const terminal = await invocation.waitTerminal(new AbortController().signal);
+                emitReceiptEvent(`SERVER_RECEIPT_TERMINAL ${terminal}`);
+                if (terminal !== 'committed') {
+                    finishReceiptServer();
+                }
+            })());
+        };
+    });
+}
 const server = new Server(mux.lookupMethod);
-const echoer = new EchoerServer(server);
-mux.register(createHandler(EchoerDefinition, echoer));
+if (!receiptMode) {
+    const echoer = new EchoerServer(server);
+    mux.register(createHandler(EchoerDefinition, echoer));
+}
 const tcpServer = net.createServer((socket) => {
     const stream = tcpSocketToPacketStream(socket);
     server.handlePacketStream(stream);
@@ -50,6 +125,11 @@ tcpServer.listen(0, '127.0.0.1', () => {
     const addr = tcpServer.address();
     console.log(`LISTENING ${addr.address}:${addr.port}`);
 });
+if (receiptMode) {
+    void receiptServerDone.promise.then(() => {
+        tcpServer.close();
+    });
+}
 process.on('SIGINT', () => {
     tcpServer.close();
     process.exit(0);

package/dist/mock/mock.pb.d.ts

@@ -1,4 +1,4 @@
-import type { MessageType } from '@aptre/protobuf-es-lite';
+import type { MessageType } from '@aptre/protobuf-es-lite/message';
 export declare const protobufPackage = "e2e.mock";
 /**
  * MockMsg is the mock message body.

package/dist/mock/mock.pb.js

@@ -1,10 +1,10 @@
 // @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
 // @generated from file github.com/aperturerobotics/starpc/mock/mock.proto (package e2e.mock, syntax proto3)
 /* eslint-disable */
-import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';
+import { createMessageType } from '@aptre/protobuf-es-lite/message';
+import { ScalarType } from '@aptre/protobuf-es-lite/scalar';
 export const protobufPackage = 'e2e.mock';
-// MockMsg contains the message type declaration for MockMsg.
-export const MockMsg = createMessageType({
+export const MockMsg = /* @__PURE__ */ createMessageType({
     typeName: 'e2e.mock.MockMsg',
     fields: [
         { no: 1, name: 'body', kind: 'scalar', T: ScalarType.STRING },

package/dist/rpcstream/rpcstream.pb.d.ts

@@ -1,4 +1,4 @@
-import type { MessageType } from '@aptre/protobuf-es-lite';
+import type { MessageType } from '@aptre/protobuf-es-lite/message';
 export declare const protobufPackage = "rpcstream";
 /**
  * RpcStreamInit is the first message in a RPC stream.

package/dist/rpcstream/rpcstream.pb.js

@@ -1,26 +1,26 @@
 // @generated by protoc-gen-es-lite unknown with parameter "target=ts,ts_nocheck=false"
 // @generated from file github.com/aperturerobotics/starpc/rpcstream/rpcstream.proto (package rpcstream, syntax proto3)
 /* eslint-disable */
-import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite';
+import { createMessageType } from '@aptre/protobuf-es-lite/message';
+import { ScalarType } from '@aptre/protobuf-es-lite/scalar';
 export const protobufPackage = 'rpcstream';
-// RpcStreamInit contains the message type declaration for RpcStreamInit.
-export const RpcStreamInit = createMessageType({
+export const RpcStreamInit = 
+/* @__PURE__ */ createMessageType({
     typeName: 'rpcstream.RpcStreamInit',
     fields: [
         { no: 1, name: 'component_id', kind: 'scalar', T: ScalarType.STRING },
     ],
     packedByDefault: true,
 });
-// RpcAck contains the message type declaration for RpcAck.
-export const RpcAck = createMessageType({
+export const RpcAck = /* @__PURE__ */ createMessageType({
     typeName: 'rpcstream.RpcAck',
     fields: [
         { no: 1, name: 'error', kind: 'scalar', T: ScalarType.STRING },
     ],
     packedByDefault: true,
 });
-// RpcStreamPacket contains the message type declaration for RpcStreamPacket.
-export const RpcStreamPacket = createMessageType({
+export const RpcStreamPacket = 
+/* @__PURE__ */ createMessageType({
     typeName: 'rpcstream.RpcStreamPacket',
     fields: [
         {
@@ -31,7 +31,13 @@ export const RpcStreamPacket = createMessageType({
             oneof: 'body',
         },
         { no: 2, name: 'ack', kind: 'message', T: () => RpcAck, oneof: 'body' },
-        { no: 3, name: 'data', kind: 'scalar', T: ScalarType.BYTES, oneof: 'body' },
+        {
+            no: 3,
+            name: 'data',
+            kind: 'scalar',
+            T: ScalarType.BYTES,
+            oneof: 'body',
+        },
     ],
     packedByDefault: true,
 });

package/dist/srpc/call-receipt.d.ts

@@ -0,0 +1,17 @@
+import { ClientRPC } from './client-rpc.js';
+export interface ReceiptRpc {
+    requestWithReceipt(service: string, method: string, data: Uint8Array, abortSignal?: AbortSignal): Promise<HeldCall>;
+}
+export interface HeldCall {
+    readonly response: Uint8Array;
+    readonly receipt: CallReceipt;
+}
+export declare class CallReceipt {
+    #private;
+    constructor(call: ClientRPC, iterator: AsyncIterator<Uint8Array>);
+    get done(): Promise<void>;
+    get settled(): boolean;
+    commit(): Promise<void>;
+    abort(reason?: Error): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/srpc/call-receipt.js

@@ -0,0 +1,105 @@
+/// <reference lib="es2024.promise" />
+import { ERR_RPC_ABORT } from './errors.js';
+// CallReceipt holds a unary call until it is committed or aborted.
+export class CallReceipt {
+    #call;
+    #iterator;
+    #terminalPromise;
+    #terminal;
+    #done;
+    #requestCommitted = false;
+    #resolveDone;
+    #rejectDone;
+    constructor(call, iterator) {
+        this.#call = call;
+        this.#iterator = iterator;
+        const { promise, resolve, reject } = Promise.withResolvers();
+        this.#done = promise;
+        this.#resolveDone = resolve;
+        this.#rejectDone = reject;
+        this.#done.catch(() => undefined);
+        this.#terminalPromise = this.#observeTerminal();
+        this.#terminalPromise.catch(() => undefined);
+    }
+    async #observeTerminal() {
+        try {
+            const result = await this.#iterator.next();
+            if (!result.done) {
+                throw new Error('unexpected trailing response data');
+            }
+            const terminal = this.#call.getTerminalKind();
+            if (terminal !== 'committed' ||
+                !this.#requestCommitted ||
+                this.#terminal !== 'committed') {
+                throw new Error('receipt closed before commit');
+            }
+            return result;
+        }
+        catch (err) {
+            this.#rejectDone(err);
+            const error = err instanceof Error ? err : new Error('receipt terminal failed');
+            try {
+                await this.#call.close(error);
+            }
+            catch {
+                // The primary terminal error is already recorded on the receipt.
+            }
+            throw err;
+        }
+    }
+    // done resolves after committed close and rejects on terminal failure.
+    get done() {
+        return this.#done;
+    }
+    // settled reports whether a terminal transition has been claimed.
+    get settled() {
+        return this.#terminal !== undefined;
+    }
+    // commit sends request completion and waits for server finalization.
+    async commit() {
+        if (this.#terminal === 'aborted') {
+            throw new Error(ERR_RPC_ABORT);
+        }
+        if (this.#terminal === 'committed') {
+            return this.#done;
+        }
+        this.#terminal = 'committed';
+        this.#requestCommitted = true;
+        try {
+            await this.#call.writeCallData(undefined, true);
+            await this.#terminalPromise;
+            await this.#call.close();
+            this.#resolveDone();
+        }
+        catch (err) {
+            await this.#call.close(err instanceof Error ? err : new Error('receipt commit failed'));
+            this.#rejectDone(err);
+            throw err;
+        }
+    }
+    // abort sends request cancellation and never rejects.
+    async abort(reason) {
+        if (this.#terminal !== undefined) {
+            return;
+        }
+        this.#terminal = 'aborted';
+        let terminalError = reason;
+        try {
+            await this.#call.writeCallCancel(true);
+        }
+        catch (err) {
+            terminalError ??= err;
+        }
+        try {
+            await this.#call.close();
+        }
+        catch (err) {
+            terminalError ??= err;
+        }
+        this.#rejectDone(terminalError ?? new Error(ERR_RPC_ABORT));
+    }
+    // asyncDispose aborts a receipt that has not reached a terminal.
+    async [Symbol.asyncDispose]() {
+        await this.abort();
+    }
+}

package/dist/srpc/call-receipt.test.d.ts

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