starpc 0.49.18 → 0.50.0

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

@@ -0,0 +1,127 @@
+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")
+	}
+}

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

@@ -2,10 +2,13 @@ package main
 
 import (
 	"context"
+	"encoding/binary"
 	"fmt"
 	"net"
 	"os"
 	"os/signal"
+	"sync"
+	"sync/atomic"
 
 	"github.com/aperturerobotics/starpc/echo"
 	"github.com/aperturerobotics/starpc/srpc"
@@ -15,14 +18,74 @@ func main() {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
+	receiptMode := len(os.Args) > 1 && os.Args[1] == "receipt"
+	receiptCase := ""
+	if receiptMode {
+		if len(os.Args) < 3 {
+			fmt.Fprintln(os.Stderr, "usage: go-server receipt <case>")
+			os.Exit(1)
+		}
+		receiptCase = os.Args[2]
+		switch receiptCase {
+		case "commit", "abort", "loss", "bare-close":
+		default:
+			fmt.Fprintf(os.Stderr, "unknown receipt case: %s\n", receiptCase)
+			os.Exit(1)
+		}
+	}
 	mux := srpc.NewMux()
 	echoServer := echo.NewEchoServer(mux)
 	if err := echo.SRPCRegisterEchoer(mux, echoServer); err != nil {
 		fmt.Fprintf(os.Stderr, "register error: %v\n", err)
 		os.Exit(1)
 	}
-	server := srpc.NewServer(mux)
-
+	var receiptDone <-chan struct{}
+	var finishReceipt func()
+	var receiptCommitted atomic.Bool
+	if receiptMode {
+		done := make(chan struct{})
+		var doneOnce sync.Once
+		receiptDone = done
+		finishReceipt = func() {
+			doneOnce.Do(func() {
+				close(done)
+			})
+		}
+	}
+	var invoker srpc.Invoker = mux
+	if receiptMode {
+		invoker = srpc.InvokerFunc(func(
+			serviceID, methodID string,
+			strm srpc.Stream,
+		) (bool, error) {
+			handled, err := mux.InvokeMethod(serviceID, methodID, strm)
+			if err != nil || !handled {
+				return handled, err
+			}
+			invocation, ok := srpc.GetServerInvocation(strm.Context())
+			if !ok {
+				return true, context.Canceled
+			}
+			kind, waitErr := invocation.WaitTerminal(context.Background())
+			markerErr := emitReceiptEvent(
+				fmt.Sprintf("SERVER_RECEIPT_TERMINAL %s", terminalName(kind)),
+			)
+			if waitErr != nil {
+				return true, waitErr
+			}
+			if markerErr != nil {
+				return true, markerErr
+			}
+			if kind == srpc.TerminalKind_TERMINAL_KIND_COMMITTED {
+				receiptCommitted.Store(true)
+			}
+			if kind != srpc.TerminalKind_TERMINAL_KIND_COMMITTED {
+				finishReceipt()
+			}
+			return true, nil
+		})
+	}
+	server := srpc.NewServer(invoker)
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "listen error: %v\n", err)
@@ -30,11 +93,18 @@ func main() {
 	}
 	defer ln.Close()
 
+	if receiptMode {
+		go func() {
+			<-receiptDone
+			_ = ln.Close()
+		}()
+	}
+
 	fmt.Printf("LISTENING %s\n", ln.Addr().String())
 
 	go func() {
 		<-ctx.Done()
-		ln.Close()
+		_ = ln.Close()
 	}()
 
 	for {
@@ -42,6 +112,101 @@ func main() {
 		if err != nil {
 			return
 		}
-		go server.HandleStream(ctx, conn)
+		var stream net.Conn
+		stream = conn
+		if receiptMode {
+			stream = &receiptConn{
+				Conn:          conn,
+				finishReceipt: finishReceipt,
+				committed:     &receiptCommitted,
+			}
+		}
+		go server.HandleStream(ctx, stream)
+	}
+}
+
+type receiptConn struct {
+	net.Conn
+	finishReceipt func()
+	committed     *atomic.Bool
+	inspect       []byte
+	ackPending    bool
+}
+
+func (c *receiptConn) Write(p []byte) (int, error) {
+	if !c.ackPending {
+		if err := c.observeReceiptPackets(p); err != nil {
+			return 0, err
+		}
+	}
+	n, err := c.Conn.Write(p)
+	if err != nil {
+		return n, err
+	}
+	if c.ackPending && n == len(p) {
+		c.finishReceipt()
+		c.ackPending = false
+	}
+	return n, nil
+}
+
+func (c *receiptConn) observeReceiptPackets(p []byte) error {
+	c.inspect = append(c.inspect, p...)
+	for len(c.inspect) >= 4 {
+		size := int(binary.LittleEndian.Uint32(c.inspect[:4]))
+		if len(c.inspect) < 4+size {
+			break
+		}
+		pkt := &srpc.Packet{}
+		if err := pkt.UnmarshalVT(c.inspect[4 : 4+size]); err != nil {
+			return err
+		}
+		c.inspect = c.inspect[4+size:]
+		data := pkt.GetCallData()
+		if !c.committed.Load() {
+			continue
+		}
+		if data == nil || !data.GetComplete() || data.GetError() != "" {
+			continue
+		}
+		if err := emitReceiptEvent("SERVER_RECEIPT_ACK_WRITE committed"); err != nil {
+			return err
+		}
+		c.ackPending = true
+	}
+	return nil
+}
+
+func terminalName(kind srpc.TerminalKind) string {
+	switch kind {
+	case srpc.TerminalKind_TERMINAL_KIND_COMMITTED:
+		return "committed"
+	case srpc.TerminalKind_TERMINAL_KIND_CANCELED:
+		return "canceled"
+	case srpc.TerminalKind_TERMINAL_KIND_TRANSPORT_LOST:
+		return "transportLost"
+	case srpc.TerminalKind_TERMINAL_KIND_CLOSED:
+		return "closed"
+	case srpc.TerminalKind_TERMINAL_KIND_ABANDONED:
+		return "abandoned"
+	default:
+		return "unknown"
+	}
+}
+
+func emitReceiptEvent(line string) error {
+	fmt.Println(line)
+	fifo := os.Getenv("RECEIPT_EVENT_FIFO")
+	if fifo == "" {
+		return nil
+	}
+	file, err := os.OpenFile(fifo, os.O_WRONLY, 0) //nolint:gosec // FIFO path is created by the local integration runner.
+	if err != nil {
+		return err
+	}
+	if _, err := file.WriteString(line + "\n"); err != nil {
+		_ = file.Close()
+		return err
 	}
+	return file.Close()
 }

package/integration/cross-language/run.bash

@@ -20,6 +20,8 @@ PASSED=0
 FAILED=0
 ERRORS=""
 
+SERVER_LOG=""
+
 # should_run checks if a test name matches the active filters.
 # Returns 0 (true) if the test should run, 1 (false) otherwise.
 should_run() {
@@ -77,27 +79,26 @@ RUST_CLIENT="$REPO_DIR/target/release/integration-client"
 CPP_SERVER="$REPO_DIR/build/cpp-integration-server"
 CPP_CLIENT="$REPO_DIR/build/cpp-integration-client"
 
-# Start a server and capture its address.
-# Sets SERVER_PID and SERVER_ADDR.
 start_server() {
-    local addr_file
-    addr_file=$(mktemp)
-    "$@" > "$addr_file" 2>&1 &
+    SERVER_LOG=$(mktemp)
+    "$@" > "$SERVER_LOG" 2>&1 &
     SERVER_PID=$!
     # Wait for LISTENING output (up to 3 seconds).
     local waited=0
     while [ $waited -lt 30 ]; do
-        if grep -q 'LISTENING' "$addr_file" 2>/dev/null; then
+        if grep -q 'LISTENING' "$SERVER_LOG" 2>/dev/null; then
             break
         fi
         sleep 0.1
         waited=$((waited + 1))
     done
-    SERVER_ADDR=$(grep 'LISTENING' "$addr_file" 2>/dev/null | awk '{print $2}')
-    rm -f "$addr_file"
+    SERVER_ADDR=$(grep 'LISTENING' "$SERVER_LOG" 2>/dev/null | awk '{print $2}')
     if [ -z "$SERVER_ADDR" ]; then
         echo "FAILED: server did not start"
         kill $SERVER_PID 2>/dev/null || true
+        wait $SERVER_PID 2>/dev/null || true
+        rm -f "$SERVER_LOG"
+        SERVER_LOG=""
         return 1
     fi
     return 0
@@ -110,6 +111,27 @@ stop_server() {
 
 # run_pair <test_name> <server_args...> -- <client_args...>
 # The client receives $SERVER_ADDR as its last argument.
+# check_receipt_events verifies terminal markers after the receipt server
+# naturally completes, so receipt synchronization is event/process-backed.
+check_receipt_events() {
+    local expected="$1"
+    local event_log="$2"
+    awk -v expected="$expected" '
+        $0 == "SERVER_RECEIPT_TERMINAL " expected { terminal = NR; next }
+        $0 == "SERVER_RECEIPT_ACK_WRITE " expected { ack_write = NR; next }
+        $0 == "CLIENT_RECEIPT_RESOLVED " expected { client = NR; next }
+        END {
+            if (!terminal || !client) {
+                exit 1
+            }
+            if (expected == "committed" &&
+                (!ack_write || terminal >= ack_write || ack_write >= client)) {
+                exit 1
+            }
+        }
+    ' "$event_log"
+}
+
 run_pair() {
     local test_name="$1"
     shift
@@ -134,30 +156,104 @@ run_pair() {
         fi
     done
 
+    local expected_terminal=""
+    case "$test_name" in
+        *"receipt commit") expected_terminal="committed" ;;
+        *"receipt abort") expected_terminal="canceled" ;;
+        *"receipt loss") expected_terminal="transportLost" ;;
+        *"receipt bare-close") expected_terminal="closed" ;;
+    esac
+
     echo -n "  ${test_name}... "
 
+    local event_fifo=""
+    local event_log=""
+    local event_reader=""
+    if [ -n "$expected_terminal" ]; then
+        event_fifo=$(mktemp)
+        rm -f "$event_fifo"
+        mkfifo "$event_fifo"
+        event_log=$(mktemp)
+        exec 3<>"$event_fifo"
+        (
+            exec 3>&-
+            cat "$event_fifo" > "$event_log"
+        ) &
+        event_reader=$!
+        export RECEIPT_EVENT_FIFO="$event_fifo"
+    else
+        unset RECEIPT_EVENT_FIFO
+    fi
+
     if ! start_server "${srv_args[@]}"; then
         echo "FAILED (server start)"
         FAILED=$((FAILED + 1))
         ERRORS="${ERRORS}\n  ${test_name} (server start failed)"
+        if [ -n "$event_reader" ]; then
+            exec 3>&-
+            kill "$event_reader" 2>/dev/null || true
+            wait "$event_reader" 2>/dev/null || true
+            rm -f "$event_fifo" "$event_log"
+        fi
+        unset RECEIPT_EVENT_FIFO
         return
     fi
 
     local client_out
     client_out=$(mktemp)
+    local client_ok=false
+    local server_ok=true
     if "${cli_args[@]}" "$SERVER_ADDR" > "$client_out" 2>&1; then
+        client_ok=true
+    fi
+
+    if [ -n "$event_reader" ]; then
+        if $client_ok; then
+            if ! wait "$SERVER_PID"; then
+                server_ok=false
+            fi
+        else
+            stop_server
+            wait "$SERVER_PID" 2>/dev/null || true
+            server_ok=false
+        fi
+        exec 3>&-
+        wait "$event_reader" 2>/dev/null || true
+    else
+        stop_server
+    fi
+    unset RECEIPT_EVENT_FIFO
+
+    local terminal_ok=true
+    if [ -n "$expected_terminal" ] &&
+        ! check_receipt_events "$expected_terminal" "$event_log"; then
+        terminal_ok=false
+    fi
+
+    if $client_ok && $server_ok && $terminal_ok; then
         echo "PASSED"
+        if [ -n "$expected_terminal" ]; then
+            echo "    receipt events:"
+            sed 's/^/      /' "$event_log"
+        fi
         PASSED=$((PASSED + 1))
     else
         echo "FAILED"
         FAILED=$((FAILED + 1))
         ERRORS="${ERRORS}\n  ${test_name}"
-        echo "    client output:"
-        sed 's/^/    /' "$client_out"
+        if ! $client_ok; then
+            echo "    client output:"
+            sed 's/^/    /' "$client_out"
+        fi
+        if ! $terminal_ok; then
+            echo "    receipt events:"
+            sed 's/^/    /' "$event_log"
+            echo "    server output:"
+            sed 's/^/    /' "$SERVER_LOG"
+        fi
     fi
-    rm -f "$client_out"
-
-    stop_server
+    rm -f "$client_out" "$SERVER_LOG" "$event_fifo" "$event_log"
+    SERVER_LOG=""
 }
 
 echo ""
@@ -168,6 +264,10 @@ echo ""
 run_pair "go-server + go-client"   "$GO_SERVER" -- "$GO_CLIENT"
 run_pair "go-server + rust-client" "$GO_SERVER" -- "$RUST_CLIENT"
 run_pair "go-server + ts-client"   "$GO_SERVER" -- node "$TS_CLIENT"
+run_pair "go-server + ts-client receipt commit" "$GO_SERVER" receipt commit -- node "$TS_CLIENT" receipt commit
+run_pair "go-server + ts-client receipt abort" "$GO_SERVER" receipt abort -- node "$TS_CLIENT" receipt abort
+run_pair "go-server + ts-client receipt loss" "$GO_SERVER" receipt loss -- node "$TS_CLIENT" receipt loss
+run_pair "go-server + ts-client receipt bare-close" "$GO_SERVER" receipt bare-close -- node "$TS_CLIENT" receipt bare-close
 run_pair "go-server + cpp-client"  "$GO_SERVER" -- "$CPP_CLIENT"
 
 # Rust server combinations
@@ -178,6 +278,10 @@ run_pair "rust-server + cpp-client"  "$RUST_SERVER" -- "$CPP_CLIENT"
 
 # TypeScript server combinations
 run_pair "ts-server + go-client"   node "$TS_SERVER" -- "$GO_CLIENT"
+run_pair "ts-server + go-client receipt commit" node "$TS_SERVER" receipt commit -- "$GO_CLIENT" receipt commit
+run_pair "ts-server + go-client receipt abort" node "$TS_SERVER" receipt abort -- "$GO_CLIENT" receipt abort
+run_pair "ts-server + go-client receipt loss" node "$TS_SERVER" receipt loss -- "$GO_CLIENT" receipt loss
+run_pair "ts-server + go-client receipt bare-close" node "$TS_SERVER" receipt bare-close -- "$GO_CLIENT" receipt bare-close
 run_pair "ts-server + rust-client" node "$TS_SERVER" -- "$RUST_CLIENT"
 run_pair "ts-server + ts-client"   node "$TS_SERVER" -- node "$TS_CLIENT"
 run_pair "ts-server + cpp-client"  node "$TS_SERVER" -- "$CPP_CLIENT"

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

@@ -1,4 +1,5 @@
 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'
@@ -7,9 +8,22 @@ import {
   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'
 import type { OpenStreamFunc, PacketStream } from '../../srpc/stream.js'
 import type { Source } from 'it-stream-types'
+function emitReceiptEvent(line: string): void {
+  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: net.Socket): PacketStream {
@@ -32,8 +46,7 @@ function tcpSocketToPacketStream(socket: net.Socket): PacketStream {
     source: socketSource(),
     sink: async (source: Source<Uint8Array>): Promise<void> => {
       for await (const chunk of pipe(source, prependLengthPrefixTransform())) {
-        const data =
-          chunk instanceof Uint8Array ? chunk : (chunk as any).subarray()
+        const data = chunk instanceof Uint8Array ? chunk : chunk.subarray()
         await new Promise<void>((resolve, reject) => {
           socket.write(data, (err) => {
             if (err) reject(err)
@@ -47,30 +60,98 @@ function tcpSocketToPacketStream(socket: net.Socket): PacketStream {
 }
 
 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: net.Socket | undefined
 
   const openStream: OpenStreamFunc = async (): Promise<PacketStream> => {
-    return new Promise((resolve, reject) => {
-      const socket = net.connect(port, host, () => {
-        resolve(tcpSocketToPacketStream(socket))
-      })
-      socket.on('error', reject)
+    const { promise, resolve, reject } = Promise.withResolvers<PacketStream>()
+    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: string): string {
+  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: {
+  commit(): Promise<void>
+}): Promise<void> {
+  try {
+    await receipt.commit()
+  } catch {
+    return
+  }
+  throw new Error('receipt commit unexpectedly succeeded')
 }
 
 process.on('unhandledRejection', (ev) => {