starpc 0.49.17 → 0.49.20

package/srpc/rpcproto.pb.ts

@@ -2,8 +2,10 @@
 // @generated from file github.com/aperturerobotics/starpc/srpc/rpcproto.proto (package srpc, syntax proto3)
 /* eslint-disable */
 
-import type { MessageType, PartialFieldInfo } from '@aptre/protobuf-es-lite'
-import { createMessageType, ScalarType } from '@aptre/protobuf-es-lite'
+import type { MessageType } from '@aptre/protobuf-es-lite/message'
+import { createMessageType } from '@aptre/protobuf-es-lite/message'
+import { ScalarType } from '@aptre/protobuf-es-lite/scalar'
+import type { PartialFieldInfo } from '@aptre/protobuf-es-lite/field'
 
 export const protobufPackage = 'srpc'
 
@@ -42,17 +44,17 @@ export interface CallStart {
   dataIsZero?: boolean
 }
 
-// CallStart contains the message type declaration for CallStart.
-export const CallStart: MessageType<CallStart> = createMessageType({
-  typeName: 'srpc.CallStart',
-  fields: [
-    { no: 1, name: 'rpc_service', kind: 'scalar', T: ScalarType.STRING },
-    { no: 2, name: 'rpc_method', kind: 'scalar', T: ScalarType.STRING },
-    { no: 3, name: 'data', kind: 'scalar', T: ScalarType.BYTES },
-    { no: 4, name: 'data_is_zero', kind: 'scalar', T: ScalarType.BOOL },
-  ] as readonly PartialFieldInfo[],
-  packedByDefault: true,
-})
+export const CallStart: MessageType<CallStart> =
+  /* @__PURE__ */ createMessageType({
+    typeName: 'srpc.CallStart',
+    fields: [
+      { no: 1, name: 'rpc_service', kind: 'scalar', T: ScalarType.STRING },
+      { no: 2, name: 'rpc_method', kind: 'scalar', T: ScalarType.STRING },
+      { no: 3, name: 'data', kind: 'scalar', T: ScalarType.BYTES },
+      { no: 4, name: 'data_is_zero', kind: 'scalar', T: ScalarType.BOOL },
+    ] satisfies readonly PartialFieldInfo[],
+    packedByDefault: true,
+  })
 
 /**
  * CallData contains a message in a streaming RPC sequence.
@@ -87,17 +89,17 @@ export interface CallData {
   error?: string
 }
 
-// CallData contains the message type declaration for CallData.
-export const CallData: MessageType<CallData> = createMessageType({
-  typeName: 'srpc.CallData',
-  fields: [
-    { no: 1, name: 'data', kind: 'scalar', T: ScalarType.BYTES },
-    { no: 2, name: 'data_is_zero', kind: 'scalar', T: ScalarType.BOOL },
-    { no: 3, name: 'complete', kind: 'scalar', T: ScalarType.BOOL },
-    { no: 4, name: 'error', kind: 'scalar', T: ScalarType.STRING },
-  ] as readonly PartialFieldInfo[],
-  packedByDefault: true,
-})
+export const CallData: MessageType<CallData> =
+  /* @__PURE__ */ createMessageType({
+    typeName: 'srpc.CallData',
+    fields: [
+      { no: 1, name: 'data', kind: 'scalar', T: ScalarType.BYTES },
+      { no: 2, name: 'data_is_zero', kind: 'scalar', T: ScalarType.BOOL },
+      { no: 3, name: 'complete', kind: 'scalar', T: ScalarType.BOOL },
+      { no: 4, name: 'error', kind: 'scalar', T: ScalarType.STRING },
+    ] satisfies readonly PartialFieldInfo[],
+    packedByDefault: true,
+  })
 
 /**
  * Packet is a message sent over a srpc packet connection.
@@ -144,8 +146,7 @@ export interface Packet {
       }
 }
 
-// Packet contains the message type declaration for Packet.
-export const Packet: MessageType<Packet> = createMessageType({
+export const Packet: MessageType<Packet> = /* @__PURE__ */ createMessageType({
   typeName: 'srpc.Packet',
   fields: [
     {
@@ -169,6 +170,6 @@ export const Packet: MessageType<Packet> = createMessageType({
       T: ScalarType.BOOL,
       oneof: 'body',
     },
-  ] as readonly PartialFieldInfo[],
+  ] satisfies readonly PartialFieldInfo[],
   packedByDefault: true,
 })

package/srpc/server-invocation.go

@@ -0,0 +1,58 @@
+package srpc
+
+import (
+	"context"
+)
+
+// TerminalKind is the terminal state of a held unary invocation.
+type TerminalKind int
+
+const (
+	// TerminalCommitted identifies an explicit remote CallData completion.
+	TerminalCommitted TerminalKind = iota
+	// TerminalCanceled identifies a remote CallCancel packet.
+	TerminalCanceled
+	// TerminalLost identifies a remote error or transport failure.
+	TerminalLost
+	// TerminalClosed identifies a bare remote close without completion.
+	TerminalClosed
+	// TerminalAbandoned identifies owner-context expiry without a remote terminal.
+	TerminalAbandoned
+)
+
+// ServerInvocation exposes the terminal of a held unary server invocation.
+type ServerInvocation interface {
+	// WaitTerminal waits for a remote terminal or owner-context expiry. The
+	// owner context must outlive the invocation context.
+	WaitTerminal(ownerCtx context.Context) (TerminalKind, error)
+	// Done returns the invocation context cancellation channel for diagnostics.
+	Done() <-chan struct{}
+}
+
+type serverInvocationKey struct{}
+
+func withServerInvocation(ctx context.Context, invocation ServerInvocation) context.Context {
+	return context.WithValue(ctx, serverInvocationKey{}, invocation)
+}
+
+// GetServerInvocation returns the held unary invocation attached to a context.
+func GetServerInvocation(ctx context.Context) (ServerInvocation, bool) {
+	if ctx == nil {
+		return nil, false
+	}
+	invocation, ok := ctx.Value(serverInvocationKey{}).(ServerInvocation)
+	return invocation, ok
+}
+
+// WaitTerminal waits for and classifies the terminal of a held unary invocation.
+func (r *ServerRPC) WaitTerminal(ownerCtx context.Context) (TerminalKind, error) {
+	return r.commonRPC.WaitTerminal(ownerCtx)
+}
+
+// Done returns the invocation context cancellation channel for diagnostics.
+func (r *ServerRPC) Done() <-chan struct{} {
+	return r.ctx.Done()
+}
+
+// _ is a type assertion.
+var _ ServerInvocation = (*ServerRPC)(nil)

package/srpc/server-invocation.ts

@@ -0,0 +1,82 @@
+// TerminalKind is the terminal state of a held unary invocation.
+export type TerminalKind =
+  | 'committed'
+  | 'canceled'
+  | 'transportLost'
+  | 'closed'
+  | 'abandoned'
+
+// ServerInvocation exposes the invocation signal and terminal wait.
+export class ServerInvocation implements AbortSignal {
+  public constructor(
+    public readonly signal: AbortSignal,
+    private readonly waitFn: (
+      ownerSignal: AbortSignal,
+    ) => Promise<TerminalKind>,
+  ) {}
+
+  public get aborted(): boolean {
+    return this.signal.aborted
+  }
+
+  public get onabort() {
+    return this.signal.onabort
+  }
+
+  public set onabort(value: typeof this.signal.onabort) {
+    this.signal.onabort = value
+  }
+
+  public get reason() {
+    return this.signal.reason
+  }
+
+  public throwIfAborted(): void {
+    this.signal.throwIfAborted()
+  }
+
+  public addEventListener<K extends keyof AbortSignalEventMap>(
+    type: K,
+    listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void
+  public addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void
+  public addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void {
+    this.signal.addEventListener(type, listener, options)
+  }
+
+  public removeEventListener<K extends keyof AbortSignalEventMap>(
+    type: K,
+    listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => unknown,
+    options?: boolean | EventListenerOptions,
+  ): void
+  public removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void
+  public removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void {
+    this.signal.removeEventListener(type, listener, options)
+  }
+
+  public dispatchEvent(event: Event): boolean {
+    return this.signal.dispatchEvent(event)
+  }
+
+  // waitTerminal waits for a remote terminal or owner-signal cancellation.
+  public waitTerminal(ownerSignal: AbortSignal): Promise<TerminalKind> {
+    return this.waitFn(ownerSignal)
+  }
+}

package/srpc/server-rpc-invoke.go

@@ -0,0 +1,7 @@
+//go:build !goscript
+
+package srpc
+
+func startServerRPCInvoke(fn func()) {
+	go fn()
+}

package/srpc/server-rpc-invoke_goscript.go

@@ -0,0 +1,12 @@
+//go:build goscript
+
+package srpc
+
+import "time"
+
+func startServerRPCInvoke(fn func()) {
+	if fn == nil {
+		return
+	}
+	time.AfterFunc(0, fn)
+}

package/srpc/server-rpc-invoke_goscript_test.go

@@ -0,0 +1,27 @@
+//go:build goscript
+
+package srpc
+
+import (
+	"testing"
+	"time"
+)
+
+func TestStartServerRPCInvokeDefersGoscriptWork(t *testing.T) {
+	ran := make(chan struct{}, 1)
+	startServerRPCInvoke(func() {
+		ran <- struct{}{}
+	})
+
+	select {
+	case <-ran:
+		t.Fatal("server rpc invoke ran inline")
+	default:
+	}
+
+	select {
+	case <-ran:
+	case <-time.After(time.Second):
+		t.Fatal("server rpc invoke did not run")
+	}
+}

package/srpc/server-rpc.go

@@ -80,9 +80,16 @@ func (r *ServerRPC) HandleCallStart(pkt *CallStart) error {
 		r.dataQueue = append(r.dataQueue, data)
 	}
 
+	// Wait is used as a resource lifetime barrier by rpcstream components.
+	// Mark the method active before scheduling it so cancellation cannot make
+	// Wait return and release a mux while invokeRPC is still running user code.
+	r.localActive = true
+
 	// invoke the rpc
 	locked.Broadcast()
-	go r.invokeRPC(service, method)
+	startServerRPCInvoke(func() {
+		r.invokeRPC(service, method)
+	})
 	locked.Unlock()
 
 	return err
@@ -91,7 +98,7 @@ func (r *ServerRPC) HandleCallStart(pkt *CallStart) error {
 // invokeRPC invokes the RPC after CallStart is received.
 func (r *ServerRPC) invokeRPC(serviceID, methodID string) {
 	// on the server side, the writer is closed by invokeRPC.
-	strm := NewMsgStream(r.ctx, r, r.cancelContext)
+	strm := NewMsgStream(withServerInvocation(r.ctx, r), r, r.cancelContext)
 	ok, err := r.invoker.InvokeMethod(serviceID, methodID, strm)
 	if err == nil && !ok {
 		err = ErrUnimplemented

package/srpc/server-rpc.ts

@@ -3,6 +3,7 @@ import type { Sink, Source } from 'it-stream-types'
 import type { CallData, CallStart } from './rpcproto.pb.js'
 import { CommonRPC } from './common-rpc.js'
 import { InvokeFn } from './handler.js'
+import { ServerInvocation } from './server-invocation.js'
 import { LookupMethod } from './mux.js'
 
 // ServerRPC is an ongoing RPC from the server side.
@@ -43,12 +44,15 @@ export class ServerRPC extends CommonRPC {
     }
     return super.handleCallData(packet)
   }
-
   // invokeRPC starts invoking the RPC handler.
   private async invokeRPC(invokeFn: InvokeFn) {
     const dataSink = this._createDataSink()
+    const invocation = new ServerInvocation(
+      this.invocationSignal,
+      (ownerSignal) => this.waitTerminal(ownerSignal),
+    )
     try {
-      await invokeFn(this.rpcDataSource, dataSink)
+      await invokeFn(this.rpcDataSource, dataSink, invocation)
     } catch (err) {
       this.close(err as Error)
     }

package/srpc/stream.go

@@ -23,6 +23,10 @@ type Stream interface {
 	Close() error
 }
 
+type receiptTerminalStream interface {
+	receiptTerminalKind() (TerminalKind, bool)
+}
+
 // StreamRecv is a stream that can receive typed messages.
 //
 // T is the response type.
@@ -69,6 +73,14 @@ func (s *streamWithClose) Close() error {
 	return err2
 }
 
+func (s *streamWithClose) receiptTerminalKind() (TerminalKind, bool) {
+	receipt, ok := s.Stream.(receiptTerminalStream)
+	if !ok {
+		return 0, false
+	}
+	return receipt.receiptTerminalKind()
+}
+
 // streamWithContext is a Stream with a wrapped Context function.
 type streamWithContext struct {
 	Stream
@@ -85,6 +97,14 @@ func (s *streamWithContext) Context() context.Context {
 	return s.ctx
 }
 
+func (s *streamWithContext) receiptTerminalKind() (TerminalKind, bool) {
+	receipt, ok := s.Stream.(receiptTerminalStream)
+	if !ok {
+		return 0, false
+	}
+	return receipt.receiptTerminalKind()
+}
+
 // _ is a type assertion
 var (
 	_ Stream = (*streamWithClose)(nil)