starpc 0.50.0 → 0.52.0

package/dist/srpc/call-receipt.js

@@ -1,106 +0,0 @@
-/// <reference lib="es2024.promise" />
-import { ERR_RPC_ABORT } from './errors.js';
-import { TerminalKind } from './rpcproto.pb.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 !== TerminalKind.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

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

package/dist/srpc/call-receipt.test.js

@@ -1,375 +0,0 @@
-/// <reference lib="es2024.promise" />
-import { describe, expect, it } from 'vitest';
-import { pushable } from 'it-pushable';
-import { EchoMsg } from '../echo/echo.pb.js';
-import { Client } from './client.js';
-import { ClientRPC } from './client-rpc.js';
-import { Server } from './server.js';
-import { CallReceipt } from './call-receipt.js';
-import { Packet, TerminalKind } from './rpcproto.pb.js';
-import { ServerRPC } from './server-rpc.js';
-const response = new Uint8Array([1, 2, 3]);
-describe('generated service compatibility', () => {
-    it('accepts plain abort signals and terminal-capable handlers', async () => {
-        const server = {
-            Echo: async (request, invocation) => {
-                void invocation;
-                return request;
-            },
-        };
-        const request = EchoMsg.create({ body: 'compatibility' });
-        const signal = new AbortController().signal;
-        await expect(server.Echo(request, signal)).resolves.toEqual(request);
-    });
-});
-describe('held unary receipt', () => {
-    it('waits for a server completion acknowledgment', async () => {
-        const sent = [];
-        const terminal = Promise.withResolvers();
-        const client = new Client(async () => ({
-            source: responseSource(terminal.promise),
-            sink: async (source) => {
-                for await (const data of source) {
-                    const packet = Packet.fromBinary(data);
-                    sent.push(packet);
-                    if (packet.body?.case === 'callData' && packet.body.value.complete) {
-                        terminal.resolve();
-                    }
-                }
-            },
-        }));
-        const held = await client.requestWithReceipt('test.Service', 'Unary', response);
-        const commit = held.receipt.commit();
-        expect(held.receipt.settled).toBe(true);
-        await expect(commit).resolves.toBeUndefined();
-        const terminalPackets = sent.filter((packet) => {
-            const body = packet.body;
-            return (body?.case === 'callCancel' ||
-                (body?.case === 'callData' && body.value.complete));
-        });
-        expect(terminalPackets).toHaveLength(1);
-        expect(terminalPackets[0]?.body?.case).toBe('callData');
-        await expect(held.receipt.done).resolves.toBeUndefined();
-    });
-    it('commits through a real TypeScript server', async () => {
-        const terminal = Promise.withResolvers();
-        const server = new Server(async () => {
-            return async (_source, dataSink, invocation) => {
-                await dataSink((async function* () {
-                    yield response;
-                    if (!invocation) {
-                        throw new Error('missing invocation');
-                    }
-                    terminal.resolve(await invocation.waitTerminal(new AbortController().signal));
-                })());
-            };
-        });
-        const client = new Client(async () => {
-            const clientToServer = pushable({ objectMode: true });
-            const serverToClient = pushable({ objectMode: true });
-            server.handlePacketStream({
-                source: clientToServer,
-                sink: async (source) => {
-                    for await (const packet of source) {
-                        serverToClient.push(packet);
-                    }
-                    serverToClient.end();
-                },
-            });
-            return {
-                source: serverToClient,
-                sink: async (source) => {
-                    for await (const packet of source) {
-                        clientToServer.push(packet);
-                    }
-                    clientToServer.end();
-                },
-            };
-        });
-        const held = await client.requestWithReceipt('test.Service', 'Unary', response);
-        await expect(held.receipt.commit()).resolves.toBeUndefined();
-        await expect(terminal.promise).resolves.toBe(TerminalKind.COMMITTED);
-    });
-    it('rejects commit after a bare remote close', async () => {
-        const call = new ClientRPC('test.Service', 'Unary');
-        const iterator = call.rpcDataSource[Symbol.asyncIterator]();
-        await call.handleCallData({
-            data: response,
-            dataIsZero: false,
-            complete: false,
-            error: '',
-        });
-        const first = await iterator.next();
-        expect(first.done).toBe(false);
-        const receipt = new CallReceipt(call, iterator);
-        await call.close();
-        await expect(receipt.commit()).rejects.toThrow();
-        await expect(receipt.done).rejects.toThrow('receipt closed before commit');
-    });
-    it('aborts a held receipt with one cancel packet', async () => {
-        const sent = [];
-        const terminal = Promise.withResolvers();
-        const cancelSeen = Promise.withResolvers();
-        const client = new Client(async () => ({
-            source: responseSource(terminal.promise),
-            sink: async (source) => {
-                for await (const data of source) {
-                    const packet = Packet.fromBinary(data);
-                    sent.push(packet);
-                    if (packet.body?.case === 'callCancel') {
-                        cancelSeen.resolve();
-                    }
-                }
-            },
-        }));
-        const held = await client.requestWithReceipt('test.Service', 'Unary', response);
-        await held.receipt.abort();
-        await cancelSeen.promise;
-        const terminalPackets = sent.filter((packet) => packet.body?.case === 'callCancel');
-        expect(terminalPackets).toHaveLength(1);
-        await expect(held.receipt.done).rejects.toThrow();
-    });
-    it('allows exactly one concurrent commit or abort terminal', async () => {
-        const sent = [];
-        const terminal = Promise.withResolvers();
-        const client = new Client(async () => ({
-            source: responseSource(terminal.promise),
-            sink: async (source) => {
-                for await (const data of source) {
-                    const packet = Packet.fromBinary(data);
-                    sent.push(packet);
-                    if (packet.body?.case === 'callData' && packet.body.value.complete) {
-                        terminal.resolve();
-                    }
-                }
-            },
-        }));
-        const held = await client.requestWithReceipt('test.Service', 'Unary', response);
-        const results = await Promise.allSettled([
-            held.receipt.commit(),
-            held.receipt.abort(),
-        ]);
-        const terminalPackets = sent.filter((packet) => {
-            const body = packet.body;
-            return (body?.case === 'callCancel' ||
-                (body?.case === 'callData' && body.value.complete));
-        });
-        expect(terminalPackets).toHaveLength(1);
-        expect(results).toHaveLength(2);
-    });
-    it('rejects a trailing response datum instead of committing', async () => {
-        const terminal = Promise.withResolvers();
-        const client = new Client(async () => ({
-            source: (async function* () {
-                yield Packet.toBinary({
-                    body: {
-                        case: 'callData',
-                        value: {
-                            data: response,
-                            dataIsZero: false,
-                            complete: false,
-                            error: '',
-                        },
-                    },
-                });
-                await terminal.promise;
-                yield Packet.toBinary({
-                    body: {
-                        case: 'callData',
-                        value: {
-                            data: new Uint8Array([9]),
-                            dataIsZero: false,
-                            complete: false,
-                            error: '',
-                        },
-                    },
-                });
-            })(),
-            sink: async (source) => {
-                for await (const data of source) {
-                    const packet = Packet.fromBinary(data);
-                    if (packet.body?.case === 'callData' && packet.body.value.complete) {
-                        terminal.resolve();
-                    }
-                }
-            },
-        }));
-        const held = await client.requestWithReceipt('test.Service', 'Unary', response);
-        await expect(held.receipt.commit()).rejects.toThrow('unexpected trailing response data');
-    });
-    it('rejects done on a remote terminal error', async () => {
-        const client = new Client(async () => ({
-            source: (async function* () {
-                yield Packet.toBinary({
-                    body: {
-                        case: 'callData',
-                        value: {
-                            data: response,
-                            dataIsZero: false,
-                            complete: false,
-                            error: '',
-                        },
-                    },
-                });
-                yield Packet.toBinary({
-                    body: {
-                        case: 'callData',
-                        value: {
-                            data: new Uint8Array(),
-                            dataIsZero: false,
-                            complete: true,
-                            error: 'remote failure',
-                        },
-                    },
-                });
-            })(),
-            sink: async (source) => {
-                for await (const _data of source) {
-                    void _data;
-                }
-            },
-        }));
-        const held = await client.requestWithReceipt('test.Service', 'Unary', response);
-        await expect(held.receipt.done).rejects.toThrow('remote failure');
-    });
-});
-describe('server invocation terminal', () => {
-    it.each([
-        ['explicit completion', TerminalKind.COMMITTED],
-        ['cancel', TerminalKind.CANCELED],
-        ['transport loss', TerminalKind.TRANSPORT_LOST],
-        ['remote error packet', TerminalKind.TRANSPORT_LOST],
-        ['bare close', TerminalKind.CLOSED],
-        ['remote error packet with completion', TerminalKind.TRANSPORT_LOST],
-    ])('%s is classified distinctly', async (_name, expected) => {
-        const captured = Promise.withResolvers();
-        const owner = new AbortController();
-        const observed = Promise.withResolvers();
-        const rpc = new ServerRPC(async () => {
-            return async (_source, _sink, invocation) => {
-                if (!invocation) {
-                    throw new Error('missing invocation');
-                }
-                captured.resolve(invocation);
-                observed.resolve(await invocation.waitTerminal(owner.signal));
-            };
-        });
-        await rpc.handleCallStart({
-            rpcService: 'test.Service',
-            rpcMethod: 'Unary',
-            data: new Uint8Array(),
-            dataIsZero: true,
-        });
-        const invocation = await captured.promise;
-        if (expected === TerminalKind.COMMITTED) {
-            await rpc.handleCallData({ complete: true });
-        }
-        else if (expected === TerminalKind.CANCELED) {
-            await rpc.handleCallCancel();
-        }
-        else if (expected === TerminalKind.TRANSPORT_LOST) {
-            if (_name === 'remote error packet' ||
-                _name === 'remote error packet with completion') {
-                await rpc.handleCallData({
-                    complete: _name === 'remote error packet with completion',
-                    error: 'remote failure',
-                });
-            }
-            else {
-                await rpc.close(new Error('transport loss'));
-            }
-        }
-        else {
-            await rpc.close();
-        }
-        await expect(observed.promise).resolves.toBe(expected);
-        owner.abort();
-        if (_name === 'remote error packet with completion') {
-            const rpcState = rpc;
-            if (!('remoteCompleted' in rpcState)) {
-                throw new Error('remote completion discriminator is missing');
-            }
-            expect(rpcState.remoteCompleted).toBe(false);
-        }
-        if (expected === TerminalKind.CLOSED ||
-            expected === TerminalKind.TRANSPORT_LOST) {
-            expect(invocation.signal.aborted).toBe(true);
-        }
-    });
-    it.each(['transport loss', 'cancel'])('keeps completion after %s', async (followUp) => {
-        const captured = Promise.withResolvers();
-        const owner = new AbortController();
-        const rpc = new ServerRPC(async () => {
-            return async (_source, _sink, invocation) => {
-                if (!invocation) {
-                    throw new Error('missing invocation');
-                }
-                captured.resolve(invocation);
-                await invocation.waitTerminal(owner.signal);
-            };
-        });
-        await rpc.handleCallStart({
-            rpcService: 'test.Service',
-            rpcMethod: 'Unary',
-            data: new Uint8Array(),
-            dataIsZero: true,
-        });
-        const invocation = await captured.promise;
-        await rpc.handleCallData({ complete: true });
-        if (followUp === 'transport loss') {
-            await rpc.close(new Error('transport loss'));
-        }
-        else {
-            await rpc.handleCallCancel();
-        }
-        await expect(invocation.waitTerminal(owner.signal)).resolves.toBe(TerminalKind.COMMITTED);
-        owner.abort();
-    });
-    it('returns abandoned only for owner cancellation without a remote terminal', async () => {
-        const captured = Promise.withResolvers();
-        const owner = new AbortController();
-        const rpc = new ServerRPC(async () => {
-            return async (_source, _sink, invocation) => {
-                if (!invocation) {
-                    throw new Error('missing invocation');
-                }
-                captured.resolve(invocation);
-                await invocation.waitTerminal(owner.signal);
-            };
-        });
-        await rpc.handleCallStart({
-            rpcService: 'test.Service',
-            rpcMethod: 'Unary',
-            data: new Uint8Array(),
-            dataIsZero: true,
-        });
-        const invocation = await captured.promise;
-        owner.abort();
-        await expect(invocation.waitTerminal(owner.signal)).resolves.toBe(TerminalKind.ABANDONED);
-    });
-});
-async function* responseSource(terminal) {
-    yield Packet.toBinary({
-        body: {
-            case: 'callData',
-            value: {
-                data: response,
-                dataIsZero: false,
-                complete: false,
-                error: '',
-            },
-        },
-    });
-    await terminal;
-    yield Packet.toBinary({
-        body: {
-            case: 'callData',
-            value: {
-                data: new Uint8Array(),
-                dataIsZero: false,
-                complete: true,
-                error: '',
-            },
-        },
-    });
-}

package/dist/srpc/server-invocation.d.ts

@@ -1,17 +0,0 @@
-import type { TerminalKind } from './rpcproto.pb.js';
-export declare class ServerInvocation implements AbortSignal {
-    readonly signal: AbortSignal;
-    private readonly waitFn;
-    constructor(signal: AbortSignal, waitFn: (ownerSignal: AbortSignal) => Promise<TerminalKind>);
-    get aborted(): boolean;
-    get onabort(): typeof this.signal.onabort;
-    set onabort(value: typeof this.signal.onabort);
-    get reason(): any;
-    throwIfAborted(): void;
-    addEventListener<K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<K extends keyof AbortSignalEventMap>(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
-    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
-    dispatchEvent(event: Event): boolean;
-    waitTerminal(ownerSignal: AbortSignal): Promise<TerminalKind>;
-}

package/dist/srpc/server-invocation.js

@@ -1,37 +0,0 @@
-// ServerInvocation exposes the invocation signal and terminal wait.
-export class ServerInvocation {
-    signal;
-    waitFn;
-    constructor(signal, waitFn) {
-        this.signal = signal;
-        this.waitFn = waitFn;
-    }
-    get aborted() {
-        return this.signal.aborted;
-    }
-    get onabort() {
-        return this.signal.onabort;
-    }
-    set onabort(value) {
-        this.signal.onabort = value;
-    }
-    get reason() {
-        return this.signal.reason;
-    }
-    throwIfAborted() {
-        this.signal.throwIfAborted();
-    }
-    addEventListener(type, listener, options) {
-        this.signal.addEventListener(type, listener, options);
-    }
-    removeEventListener(type, listener, options) {
-        this.signal.removeEventListener(type, listener, options);
-    }
-    dispatchEvent(event) {
-        return this.signal.dispatchEvent(event);
-    }
-    // waitTerminal waits for a remote terminal or owner-signal cancellation.
-    waitTerminal(ownerSignal) {
-        return this.waitFn(ownerSignal);
-    }
-}

package/integration/cross-language/go-server/fixture-owner_test.go

@@ -1,127 +0,0 @@
-package main
-
-import (
-	"go/ast"
-	"go/parser"
-	"go/token"
-	"os"
-	"strconv"
-	"testing"
-)
-
-// forbiddenFixtureCalls names the pipeline constructors that rebuild a second
-// srpc server inside a fixture. The receipt post-mortem removed a hand-built
-// ReadPump pipeline; the fixture must drive one srpc.Server through one
-// Server.HandleStream and observe framed packets by decorating net.Conn.
-var forbiddenFixtureCalls = []string{"NewServerRPC", "NewPacketReadWriter", "ReadPump"}
-
-// fixtureOwnerViolations returns the ways a cross-language Go fixture source
-// diverges from the single production server owner.
-func fixtureOwnerViolations(src string) []string {
-	fset := token.NewFileSet()
-	file, err := parser.ParseFile(fset, "fixture.go", src, 0)
-	if err != nil {
-		return []string{"parse error: " + err.Error()}
-	}
-
-	seen := map[string]bool{}
-	handleStreamCalls := 0
-	newServerCalls := 0
-	ast.Inspect(file, func(n ast.Node) bool {
-		call, ok := n.(*ast.CallExpr)
-		if !ok {
-			return true
-		}
-		sel, ok := call.Fun.(*ast.SelectorExpr)
-		if !ok {
-			return true
-		}
-		switch sel.Sel.Name {
-		case "HandleStream":
-			handleStreamCalls++
-		case "NewServer":
-			newServerCalls++
-		case "NewServerRPC", "NewPacketReadWriter", "ReadPump":
-			seen[sel.Sel.Name] = true
-		}
-		return true
-	})
-
-	var violations []string
-	for _, name := range forbiddenFixtureCalls {
-		if seen[name] {
-			violations = append(violations, "reconstructs server pipeline via "+name)
-		}
-	}
-	if newServerCalls != 1 {
-		violations = append(violations, "expected exactly one srpc.NewServer, found "+strconv.Itoa(newServerCalls))
-	}
-	if handleStreamCalls != 1 {
-		violations = append(violations, "expected exactly one Server.HandleStream entrypoint, found "+strconv.Itoa(handleStreamCalls))
-	}
-	if !decoratesNetConn(file) {
-		violations = append(violations, "no fixture type decorates net.Conn")
-	}
-	return violations
-}
-
-// decoratesNetConn reports whether the source embeds net.Conn in a struct, the
-// only sanctioned way for fixture instrumentation to observe framed packets.
-func decoratesNetConn(file *ast.File) bool {
-	found := false
-	ast.Inspect(file, func(n ast.Node) bool {
-		st, ok := n.(*ast.StructType)
-		if !ok {
-			return true
-		}
-		for _, field := range st.Fields.List {
-			if len(field.Names) != 0 {
-				continue
-			}
-			sel, ok := field.Type.(*ast.SelectorExpr)
-			if !ok {
-				continue
-			}
-			pkg, ok := sel.X.(*ast.Ident)
-			if ok && pkg.Name == "net" && sel.Sel.Name == "Conn" {
-				found = true
-			}
-		}
-		return true
-	})
-	return found
-}
-
-// TestFixtureUsesSingleServerOwner proves the shipped fixture drives one
-// srpc.Server through one Server.HandleStream and decorates net.Conn.
-func TestFixtureUsesSingleServerOwner(t *testing.T) {
-	src, err := os.ReadFile("main.go")
-	if err != nil {
-		t.Fatalf("read main.go: %v", err)
-	}
-	if violations := fixtureOwnerViolations(string(src)); len(violations) != 0 {
-		t.Fatalf("fixture diverged from single server owner: %v", violations)
-	}
-}
-
-// TestFixtureGuardDetectsSecondPipeline proves the guard fires when a fixture
-// rebuilds a second RPC server pipeline.
-func TestFixtureGuardDetectsSecondPipeline(t *testing.T) {
-	bad := `package main
-
-import (
-	"net"
-
-	"github.com/aperturerobotics/starpc/srpc"
-)
-
-func run(conn net.Conn) {
-	prw := srpc.NewPacketReadWriter(conn)
-	rpc := srpc.NewServerRPC(nil, nil)
-	_ = rpc.ReadPump(prw)
-}
-`
-	if violations := fixtureOwnerViolations(bad); len(violations) == 0 {
-		t.Fatal("guard failed to flag a second server pipeline")
-	}
-}