starpc 0.51.0 → 0.52.0

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

@@ -26,6 +26,7 @@ import {
 } from '@aptre/protobuf-es-lite/protoplugin/ecmascript'
 
 const MessageStream = createImportSymbol('MessageStream', 'starpc')
+const ServerContext = createImportSymbol('ServerContext', 'starpc')
 const RuntimeMethodKind = createImportSymbol(
   'MethodKind',
   '@aptre/protobuf-es-lite',
@@ -128,6 +129,42 @@ function generateService(
   f.print("}");
   f.print();
 
+  // Generate the server implementation interface.
+  f.print(f.jsDoc(service));
+  f.print("export interface ", localName(service), "Handler {");
+  for (let i = 0; i < service.methods.length; i++) {
+    const method = service.methods[i];
+    f.print(f.jsDoc(method, "  "));
+    if (method.methodKind === MethodKind.Unary) {
+      f.print(
+        "  ", method.name,
+        "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        "Promise<", method.output, ">;"
+      );
+    } else if (method.methodKind === MethodKind.ServerStreaming) {
+      f.print(
+        "  ", method.name,
+        "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        MessageStream, "<", method.output, ">;"
+      );
+    } else if (method.methodKind === MethodKind.ClientStreaming) {
+      f.print(
+        "  ", method.name,
+        "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        "Promise<", method.output, ">;"
+      );
+    } else if (method.methodKind === MethodKind.BiDiStreaming) {
+      f.print(
+        "  ", method.name,
+        "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ",
+        MessageStream, "<", method.output, ">;"
+      );
+    }
+    if (i < service.methods.length - 1) f.print();
+  }
+  f.print("}");
+  f.print();
+
 
   // Generate the service name constant
   f.print("export const ", localName(service), "ServiceName = ", localName(service), "Definition.typeName");

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

@@ -15,6 +15,7 @@
 import { MethodIdempotency, MethodKind, localName, } from '@aptre/protobuf-es-lite';
 import { createImportSymbol, } from '@aptre/protobuf-es-lite/protoplugin/ecmascript';
 const MessageStream = createImportSymbol('MessageStream', 'starpc');
+const ServerContext = createImportSymbol('ServerContext', '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')
@@ -74,6 +75,29 @@ function generateService(f, service) {
     }
     f.print("}");
     f.print();
+    // Generate the server implementation interface.
+    f.print(f.jsDoc(service));
+    f.print("export interface ", localName(service), "Handler {");
+    for (let i = 0; i < service.methods.length; i++) {
+        const method = service.methods[i];
+        f.print(f.jsDoc(method, "  "));
+        if (method.methodKind === MethodKind.Unary) {
+            f.print("  ", method.name, "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ", "Promise<", method.output, ">;");
+        }
+        else if (method.methodKind === MethodKind.ServerStreaming) {
+            f.print("  ", method.name, "(request: ", method.input, ", abortSignal: AbortSignal, context: ", ServerContext, "): ", MessageStream, "<", method.output, ">;");
+        }
+        else if (method.methodKind === MethodKind.ClientStreaming) {
+            f.print("  ", method.name, "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ", "Promise<", method.output, ">;");
+        }
+        else if (method.methodKind === MethodKind.BiDiStreaming) {
+            f.print("  ", method.name, "(request: ", MessageStream, "<", method.input, ">, abortSignal: AbortSignal, context: ", ServerContext, "): ", MessageStream, "<", method.output, ">;");
+        }
+        if (i < service.methods.length - 1)
+            f.print();
+    }
+    f.print("}");
+    f.print();
     // Generate the service name constant
     f.print("export const ", localName(service), "ServiceName = ", localName(service), "Definition.typeName");
     f.print();

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

@@ -2,7 +2,7 @@ import { EchoMsg } from './echo.pb.js';
 import { MethodKind } from '@aptre/protobuf-es-lite';
 import { RpcStreamPacket } from '../rpcstream/rpcstream.pb.js';
 import { Empty } from '@aptre/protobuf-es-lite/google/protobuf/empty';
-import { MessageStream, ProtoRpc } from 'starpc';
+import { MessageStream, ProtoRpc, ServerContext } from 'starpc';
 /**
  * Echoer service returns the given message.
  *
@@ -122,6 +122,49 @@ export interface Echoer {
      */
     DoNothing(request: Empty, abortSignal?: AbortSignal): Promise<Empty>;
 }
+/**
+ * Echoer service returns the given message.
+ *
+ * @generated from service echo.Echoer
+ */
+export interface EchoerHandler {
+    /**
+     * Echo returns the given message.
+     *
+     * @generated from rpc echo.Echoer.Echo
+     */
+    Echo(request: EchoMsg, abortSignal: AbortSignal, context: ServerContext): Promise<EchoMsg>;
+    /**
+     * EchoServerStream is an example of a server -> client one-way stream.
+     *
+     * @generated from rpc echo.Echoer.EchoServerStream
+     */
+    EchoServerStream(request: EchoMsg, abortSignal: AbortSignal, context: ServerContext): MessageStream<EchoMsg>;
+    /**
+     * EchoClientStream is an example of client->server one-way stream.
+     *
+     * @generated from rpc echo.Echoer.EchoClientStream
+     */
+    EchoClientStream(request: MessageStream<EchoMsg>, abortSignal: AbortSignal, context: ServerContext): Promise<EchoMsg>;
+    /**
+     * EchoBidiStream is an example of a two-way stream.
+     *
+     * @generated from rpc echo.Echoer.EchoBidiStream
+     */
+    EchoBidiStream(request: MessageStream<EchoMsg>, abortSignal: AbortSignal, context: ServerContext): MessageStream<EchoMsg>;
+    /**
+     * RpcStream opens a nested rpc call stream.
+     *
+     * @generated from rpc echo.Echoer.RpcStream
+     */
+    RpcStream(request: MessageStream<RpcStreamPacket>, abortSignal: AbortSignal, context: ServerContext): MessageStream<RpcStreamPacket>;
+    /**
+     * DoNothing does nothing.
+     *
+     * @generated from rpc echo.Echoer.DoNothing
+     */
+    DoNothing(request: Empty, abortSignal: AbortSignal, context: ServerContext): Promise<Empty>;
+}
 export declare const EchoerServiceName: "echo.Echoer";
 export declare class EchoerClient implements Echoer {
     private readonly rpc;

package/dist/echo/server.d.ts

@@ -2,16 +2,17 @@ import { Message } from '@aptre/protobuf-es-lite';
 import { Empty } from '@aptre/protobuf-es-lite/google/protobuf/empty';
 import { EchoMsg } from './echo.pb.js';
 import { Server } from '../srpc/server.js';
+import type { ServerContext } from '../srpc/server-context.js';
 import { RpcStreamPacket } from '../rpcstream/rpcstream.pb.js';
 import { MessageStream } from '../srpc/message.js';
-import { Echoer } from './echo_srpc.pb.js';
-export declare class EchoerServer implements Echoer {
+import type { EchoerHandler } from './echo_srpc.pb.js';
+export declare class EchoerServer implements EchoerHandler {
     private proxyServer?;
     constructor(proxyServer?: Server);
-    Echo(request: EchoMsg): Promise<Message<EchoMsg>>;
-    EchoServerStream(request: EchoMsg): MessageStream<EchoMsg>;
-    EchoClientStream(request: MessageStream<EchoMsg>): Promise<Message<EchoMsg>>;
-    EchoBidiStream(request: MessageStream<EchoMsg>): MessageStream<EchoMsg>;
-    RpcStream(request: MessageStream<RpcStreamPacket>): MessageStream<RpcStreamPacket>;
-    DoNothing(): Promise<Empty>;
+    Echo(request: EchoMsg, _abortSignal: AbortSignal, _context: ServerContext): Promise<Message<EchoMsg>>;
+    EchoServerStream(request: EchoMsg, _abortSignal: AbortSignal, _context: ServerContext): MessageStream<EchoMsg>;
+    EchoClientStream(request: MessageStream<EchoMsg>, _abortSignal: AbortSignal, _context: ServerContext): Promise<Message<EchoMsg>>;
+    EchoBidiStream(request: MessageStream<EchoMsg>, _abortSignal: AbortSignal, _context: ServerContext): MessageStream<EchoMsg>;
+    RpcStream(request: MessageStream<RpcStreamPacket>, _abortSignal: AbortSignal, _context: ServerContext): MessageStream<RpcStreamPacket>;
+    DoNothing(_request: Empty, _abortSignal: AbortSignal, _context: ServerContext): Promise<Empty>;
 }

package/dist/echo/server.js

@@ -8,16 +8,16 @@ export class EchoerServer {
     constructor(proxyServer) {
         this.proxyServer = proxyServer;
     }
-    async Echo(request) {
+    async Echo(request, _abortSignal, _context) {
         return request;
     }
-    async *EchoServerStream(request) {
+    async *EchoServerStream(request, _abortSignal, _context) {
         for (let i = 0; i < 5; i++) {
             yield request;
             await new Promise((resolve) => setTimeout(resolve, 200));
         }
     }
-    async EchoClientStream(request) {
+    async EchoClientStream(request, _abortSignal, _context) {
         // return the first message sent by the client.
         const message = await first(request);
         if (!message) {
@@ -25,14 +25,14 @@ export class EchoerServer {
         }
         return message;
     }
-    EchoBidiStream(request) {
+    EchoBidiStream(request, _abortSignal, _context) {
         // build result observable
         const result = messagePushable();
         result.push({ body: 'hello from server' });
         writeToPushable(request, result);
         return result;
     }
-    RpcStream(request) {
+    RpcStream(request, _abortSignal, _context) {
         return handleRpcStream(request[Symbol.asyncIterator](), async () => {
             if (!this.proxyServer) {
                 throw new Error('rpc stream proxy server not set');
@@ -40,7 +40,7 @@ export class EchoerServer {
             return this.proxyServer.rpcStreamHandler;
         });
     }
-    async DoNothing() {
+    async DoNothing(_request, _abortSignal, _context) {
         return {};
     }
 }

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

@@ -1,6 +1,6 @@
 import { MockMsg } from './mock.pb.js';
 import { MethodKind } from '@aptre/protobuf-es-lite';
-import { ProtoRpc } from 'starpc';
+import { ProtoRpc, ServerContext } from 'starpc';
 /**
  * Mock service mocks some RPCs for the e2e tests.
  *
@@ -35,6 +35,19 @@ export interface Mock {
      */
     MockRequest(request: MockMsg, abortSignal?: AbortSignal): Promise<MockMsg>;
 }
+/**
+ * Mock service mocks some RPCs for the e2e tests.
+ *
+ * @generated from service e2e.mock.Mock
+ */
+export interface MockHandler {
+    /**
+     * MockRequest runs a mock unary request.
+     *
+     * @generated from rpc e2e.mock.Mock.MockRequest
+     */
+    MockRequest(request: MockMsg, abortSignal: AbortSignal, context: ServerContext): Promise<MockMsg>;
+}
 export declare const MockServiceName: "e2e.mock.Mock";
 export declare class MockClient implements Mock {
     private readonly rpc;

package/dist/srpc/channel.js

@@ -1,6 +1,9 @@
 import { pushable } from 'it-pushable';
 import { Watchdog } from './watchdog.js';
 import { ERR_STREAM_IDLE } from './errors.js';
+function isMessagePort(channel) {
+    return 'postMessage' in channel && 'start' in channel;
+}
 // ChannelStream implements a Stream over a BroadcastChannel duplex or MessagePort.
 //
 // NOTE: there is no way to tell if a BroadcastChannel or MessagePort is closed.
@@ -99,7 +102,7 @@ export class ChannelStream {
         this._source = source;
         // wire up the message handlers
         const onMessage = this.onMessage.bind(this);
-        if (channel instanceof MessagePort) {
+        if (isMessagePort(channel)) {
             // MessagePort
             channel.onmessage = onMessage;
             channel.start();
@@ -124,7 +127,7 @@ export class ChannelStream {
             return;
         }
         msg.from = this.localId;
-        if (this.channel instanceof MessagePort) {
+        if (isMessagePort(this.channel)) {
             this.channel.postMessage(msg);
         }
         else {
@@ -165,7 +168,7 @@ export class ChannelStream {
         this.localWriteClosed = true;
         this.remoteWriteClosed = true;
         // close channels
-        if (this.channel instanceof MessagePort) {
+        if (isMessagePort(this.channel)) {
             this.channel.onmessage = null;
             this.channel.close();
         }

package/dist/srpc/channel.test.js

@@ -1,7 +1,26 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { pushable } from 'it-pushable';
 import { ChannelStream } from './channel.js';
 describe('ChannelStream', () => {
+    it('recognizes MessagePort implementations from another realm', () => {
+        const port = {
+            close: vi.fn(),
+            onmessage: null,
+            postMessage: vi.fn(),
+            start: vi.fn(),
+        };
+        const stream = new ChannelStream('client', port);
+        try {
+            expect(port.start).toHaveBeenCalledOnce();
+            expect(port.postMessage).toHaveBeenCalledWith({
+                ack: true,
+                from: 'client',
+            });
+        }
+        finally {
+            stream.close();
+        }
+    });
     it('keeps MessagePort peer writes open after local source completes normally', async () => {
         const { port1, port2 } = new MessageChannel();
         const client = new ChannelStream('client', port1);

package/dist/srpc/handler.d.ts

@@ -1,6 +1,14 @@
 import type { Sink, Source } from 'it-stream-types';
-import { ServiceDefinition, ServiceMethodDefinitions } from './definition.js';
-export type InvokeFn = (dataSource: Source<Uint8Array>, dataSink: Sink<Source<Uint8Array>>, invocation?: AbortSignal) => Promise<void>;
+import { MethodKind, type MessageType } from '@aptre/protobuf-es-lite';
+import type { MessageStream } from './message.js';
+import { type MethodDefinition, ServiceDefinition, ServiceMethodDefinitions } from './definition.js';
+import type { ServerContext } from './server-context.js';
+type MessageOf<T> = T extends MessageType<infer M> ? M : never;
+type ServerMethod<T> = T extends MethodDefinition<infer Request, infer Response, infer Kind, infer _Idempotency> ? Kind extends MethodKind.Unary ? (request: MessageOf<Request>, abortSignal: AbortSignal, context: ServerContext) => Promise<MessageOf<Response>> : Kind extends MethodKind.ServerStreaming ? (request: MessageOf<Request>, abortSignal: AbortSignal, context: ServerContext) => MessageStream<MessageOf<Response>> : Kind extends MethodKind.ClientStreaming ? (request: MessageStream<MessageOf<Request>>, abortSignal: AbortSignal, context: ServerContext) => Promise<MessageOf<Response>> : (request: MessageStream<MessageOf<Request>>, abortSignal: AbortSignal, context: ServerContext) => MessageStream<MessageOf<Response>> : never;
+export type HandlerImplementation<T extends ServiceMethodDefinitions> = Partial<{
+    [Method in keyof T]: ServerMethod<T[Method]>;
+}>;
+export type InvokeFn = (dataSource: Source<Uint8Array>, dataSink: Sink<Source<Uint8Array>>, context: ServerContext) => Promise<void>;
 export interface Handler {
     getServiceID(): string;
     getMethodIDs(): string[];
@@ -17,4 +25,5 @@ export declare class StaticHandler implements Handler {
     getMethodIDs(): string[];
     lookupMethod(serviceID: string, methodID: string): Promise<InvokeFn | null>;
 }
-export declare function createHandler<T extends ServiceMethodDefinitions = ServiceMethodDefinitions>(definition: ServiceDefinition<T>, impl: any, serviceID?: string): Handler;
+export declare function createHandler<T extends ServiceMethodDefinitions = ServiceMethodDefinitions>(definition: ServiceDefinition<T>, impl: HandlerImplementation<T>, serviceID?: string): Handler;
+export {};

package/dist/srpc/index.d.ts

@@ -27,3 +27,5 @@ export { HandleStreamCtr } from './handle-stream-ctr.js';
 export { writeToPushable, buildPushableSink, messagePushable, } from './pushable.js';
 export { Watchdog } from './watchdog.js';
 export type { ProtoRpc } from './proto-rpc.js';
+export { createContextKey, serverContextValue, withServerContextValue, } from './server-context.js';
+export type { ContextKey, ServerContext } from './server-context.js';

package/dist/srpc/index.js

@@ -18,3 +18,4 @@ export { OpenStreamCtr } from './open-stream-ctr.js';
 export { HandleStreamCtr } from './handle-stream-ctr.js';
 export { writeToPushable, buildPushableSink, messagePushable, } from './pushable.js';
 export { Watchdog } from './watchdog.js';
+export { createContextKey, serverContextValue, withServerContextValue, } from './server-context.js';

package/dist/srpc/invoker.d.ts

@@ -1,6 +1,7 @@
 import type { MethodDefinition } from './definition.js';
+import type { ServerContext } from './server-context.js';
 import { InvokeFn } from './handler.js';
 import type { MessageType, Message } from '@aptre/protobuf-es-lite';
 import { MethodIdempotency, MethodKind } from '@aptre/protobuf-es-lite';
-export type MethodProto<R extends Message<R>, O extends Message<O>> = ((request: R, invocation?: AbortSignal) => Promise<O>) | ((request: R, invocation?: AbortSignal) => AsyncIterable<O>) | ((request: AsyncIterable<R>, invocation?: AbortSignal) => Promise<O>) | ((request: AsyncIterable<R>, invocation?: AbortSignal) => AsyncIterable<O>);
+export type MethodProto<R extends Message<R>, O extends Message<O>> = ((request: R, abortSignal: AbortSignal, context: ServerContext) => Promise<O>) | ((request: R, abortSignal: AbortSignal, context: ServerContext) => AsyncIterable<O>) | ((request: AsyncIterable<R>, abortSignal: AbortSignal, context: ServerContext) => Promise<O>) | ((request: AsyncIterable<R>, abortSignal: AbortSignal, context: ServerContext) => AsyncIterable<O>);
 export declare function createInvokeFn<R extends Message<R>, O extends Message<O>>(methodInfo: MethodDefinition<MessageType<R>, MessageType<O>, MethodKind, MethodIdempotency | undefined>, methodProto: MethodProto<R, O>): InvokeFn;

package/dist/srpc/invoker.js

@@ -6,7 +6,7 @@ import { MethodKind } from '@aptre/protobuf-es-lite';
 // createInvokeFn builds an InvokeFn from a method definition and a function prototype.
 export function createInvokeFn(methodInfo, methodProto) {
     const requestDecode = buildDecodeMessageTransform(methodInfo.I);
-    return async (dataSource, dataSink, invocation) => {
+    return async (dataSource, dataSink, context) => {
         // responseSink is a Sink for response messages.
         const responseSink = pushable({
             objectMode: true,
@@ -34,7 +34,7 @@ export function createInvokeFn(methodInfo, methodProto) {
         }
         // Call the implementation.
         try {
-            const responseObj = methodProto(requestArg, invocation);
+            const responseObj = methodProto(requestArg, context.signal, context);
             if (!responseObj) {
                 throw new Error('return value was undefined');
             }

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

@@ -0,0 +1,11 @@
+declare const contextKeyValue: unique symbol;
+export interface ContextKey<T> {
+    readonly [contextKeyValue]?: T;
+}
+export interface ServerContext {
+    readonly signal: AbortSignal;
+}
+export declare function createContextKey<T>(): ContextKey<T>;
+export declare function withServerContextValue<T>(context: ServerContext, key: ContextKey<T>, value: T): ServerContext;
+export declare function serverContextValue<T>(context: ServerContext, key: ContextKey<T>): T | undefined;
+export {};

package/dist/srpc/server-context.js

@@ -0,0 +1,28 @@
+const contextParent = Symbol('server context parent');
+const contextKey = Symbol('server context key');
+const contextStoredValue = Symbol('server context value');
+// createContextKey constructs an identity key for one server-context value.
+export function createContextKey() {
+    return {};
+}
+// withServerContextValue derives a context with one immutable typed value.
+export function withServerContextValue(context, key, value) {
+    const derived = {
+        signal: context.signal,
+        [contextParent]: context,
+        [contextKey]: key,
+        [contextStoredValue]: value,
+    };
+    return derived;
+}
+// serverContextValue retrieves the nearest value for a typed identity key.
+export function serverContextValue(context, key) {
+    let current = context;
+    while (current) {
+        if (current[contextKey] === key) {
+            return current[contextStoredValue];
+        }
+        current = current[contextParent];
+    }
+    return undefined;
+}

package/dist/srpc/server-rpc.js

@@ -38,7 +38,9 @@ export class ServerRPC extends CommonRPC {
     async invokeRPC(invokeFn) {
         const dataSink = this._createDataSink();
         try {
-            await invokeFn(this.rpcDataSource, dataSink, this.invocationSignal);
+            await invokeFn(this.rpcDataSource, dataSink, {
+                signal: this.invocationSignal,
+            });
         }
         catch (err) {
             this.close(err);

package/dist/srpc/server.test.js

@@ -1,6 +1,6 @@
 import { describe, it, beforeEach, expect, vi } from 'vitest';
 import { pipe } from 'it-pipe';
-import { createHandler, createMux, Server, Client, StreamConn, ChannelStream, combineUint8ArrayListTransform, Packet, } from '../srpc/index.js';
+import { createHandler, createMux, Server, Client, StreamConn, ChannelStream, combineUint8ArrayListTransform, Packet, createContextKey, serverContextValue, withServerContextValue, } from '../srpc/index.js';
 import { EchoerDefinition, EchoerServer, EchoerServiceName, EchoMsg, runClientTest, } from '../echo/index.js';
 import { runAbortControllerTest, runRpcStreamTest, } from '../echo/client-test.js';
 describe('srpc server', () => {
@@ -39,12 +39,17 @@ describe('srpc server', () => {
     it('should pass rpc stream tests', async () => {
         await runRpcStreamTest(client);
     });
-    it('passes the exact invocation signal after async request decode', async () => {
+    it('passes the exact invocation context after async request decode', async () => {
         const controller = new AbortController();
-        let observedSignal;
+        const callerKey = createContextKey();
+        let observedAbortSignal;
+        let observedContextSignal;
+        let observedCaller;
         const handler = createHandler(EchoerDefinition, {
-            Echo: async (request, signal) => {
-                observedSignal = signal;
+            Echo: async (request, abortSignal, context) => {
+                observedAbortSignal = abortSignal;
+                observedContextSignal = context.signal;
+                observedCaller = serverContextValue(context, callerKey);
                 return request;
             },
         });
@@ -62,8 +67,32 @@ describe('srpc server', () => {
                 // Drain the encoded response so the invocation pipeline completes.
             }
             drained.resolve();
-        }, controller.signal);
+        }, withServerContextValue({ signal: controller.signal }, callerKey, 'caller-1'));
         await drained.promise;
+        expect(observedAbortSignal).toBe(controller.signal);
+        expect(observedContextSignal).toBe(controller.signal);
+        expect(observedCaller).toBe('caller-1');
+    });
+    it('keeps two-argument server handlers compatible', async () => {
+        const controller = new AbortController();
+        let observedSignal;
+        const handler = createHandler(EchoerDefinition, {
+            Echo: async (request, abortSignal) => {
+                observedSignal = abortSignal;
+                return request;
+            },
+        });
+        const invokeFn = await handler.lookupMethod(EchoerServiceName, 'Echo');
+        if (!invokeFn)
+            throw new Error('Echo method was not found');
+        const request = EchoMsg.create({ body: 'legacy handler' });
+        await invokeFn((async function* () {
+            yield EchoMsg.toBinary(request);
+        })(), async (source) => {
+            for await (const _data of source) {
+                // Drain the response.
+            }
+        }, { signal: controller.signal });
         expect(observedSignal).toBe(controller.signal);
     });
     it('keeps detached server-streaming responses open after request source completes', async () => {

package/dist/srpc/watchdog.test.js

@@ -5,6 +5,7 @@ describe('Watchdog', () => {
         vi.useFakeTimers();
     });
     afterEach(() => {
+        vi.useRealTimers();
         vi.restoreAllMocks();
     });
     it('should call expired callback after timeout', () => {

package/echo/echo_srpc.pb.ts

@@ -11,6 +11,7 @@ import {
   buildEncodeMessageTransform,
   MessageStream,
   ProtoRpc,
+  ServerContext,
 } from 'starpc'
 
 /**
@@ -151,6 +152,79 @@ export interface Echoer {
   DoNothing(request: Empty, abortSignal?: AbortSignal): Promise<Empty>
 }
 
+/**
+ * Echoer service returns the given message.
+ *
+ * @generated from service echo.Echoer
+ */
+export interface EchoerHandler {
+  /**
+   * Echo returns the given message.
+   *
+   * @generated from rpc echo.Echoer.Echo
+   */
+  Echo(
+    request: EchoMsg,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): Promise<EchoMsg>
+
+  /**
+   * EchoServerStream is an example of a server -> client one-way stream.
+   *
+   * @generated from rpc echo.Echoer.EchoServerStream
+   */
+  EchoServerStream(
+    request: EchoMsg,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): MessageStream<EchoMsg>
+
+  /**
+   * EchoClientStream is an example of client->server one-way stream.
+   *
+   * @generated from rpc echo.Echoer.EchoClientStream
+   */
+  EchoClientStream(
+    request: MessageStream<EchoMsg>,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): Promise<EchoMsg>
+
+  /**
+   * EchoBidiStream is an example of a two-way stream.
+   *
+   * @generated from rpc echo.Echoer.EchoBidiStream
+   */
+  EchoBidiStream(
+    request: MessageStream<EchoMsg>,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): MessageStream<EchoMsg>
+
+  /**
+   * RpcStream opens a nested rpc call stream.
+   *
+   * @generated from rpc echo.Echoer.RpcStream
+   */
+  RpcStream(
+    request: MessageStream<RpcStreamPacket>,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): MessageStream<RpcStreamPacket>
+
+  /**
+   * DoNothing does nothing.
+   *
+   * @generated from rpc echo.Echoer.DoNothing
+   */
+  DoNothing(
+    request: Empty,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): Promise<Empty>
+}
+
 export const EchoerServiceName = EchoerDefinition.typeName
 
 export class EchoerClient implements Echoer {

package/echo/server.ts

@@ -3,14 +3,15 @@ import { Message } from '@aptre/protobuf-es-lite'
 import { Empty } from '@aptre/protobuf-es-lite/google/protobuf/empty'
 import { EchoMsg } from './echo.pb.js'
 import { Server } from '../srpc/server.js'
+import type { ServerContext } from '../srpc/server-context.js'
 import { messagePushable, writeToPushable } from '../srpc/pushable.js'
 import { RpcStreamPacket } from '../rpcstream/rpcstream.pb.js'
 import { MessageStream } from '../srpc/message.js'
 import { handleRpcStream, RpcStreamHandler } from '../rpcstream/rpcstream.js'
-import { Echoer } from './echo_srpc.pb.js'
+import type { EchoerHandler } from './echo_srpc.pb.js'
 
 // EchoServer implements the Echoer server.
-export class EchoerServer implements Echoer {
+export class EchoerServer implements EchoerHandler {
   // proxyServer is the server used for RpcStream requests.
   private proxyServer?: Server
 
@@ -18,11 +19,19 @@ export class EchoerServer implements Echoer {
     this.proxyServer = proxyServer
   }
 
-  public async Echo(request: EchoMsg): Promise<Message<EchoMsg>> {
+  public async Echo(
+    request: EchoMsg,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
+  ): Promise<Message<EchoMsg>> {
     return request
   }
 
-  public async *EchoServerStream(request: EchoMsg): MessageStream<EchoMsg> {
+  public async *EchoServerStream(
+    request: EchoMsg,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
+  ): MessageStream<EchoMsg> {
     for (let i = 0; i < 5; i++) {
       yield request
       await new Promise((resolve) => setTimeout(resolve, 200))
@@ -31,6 +40,8 @@ export class EchoerServer implements Echoer {
 
   public async EchoClientStream(
     request: MessageStream<EchoMsg>,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
   ): Promise<Message<EchoMsg>> {
     // return the first message sent by the client.
     const message = await first(request)
@@ -42,6 +53,8 @@ export class EchoerServer implements Echoer {
 
   public EchoBidiStream(
     request: MessageStream<EchoMsg>,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
   ): MessageStream<EchoMsg> {
     // build result observable
     const result = messagePushable<EchoMsg>()
@@ -52,6 +65,8 @@ export class EchoerServer implements Echoer {
 
   public RpcStream(
     request: MessageStream<RpcStreamPacket>,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
   ): MessageStream<RpcStreamPacket> {
     return handleRpcStream(
       request[Symbol.asyncIterator](),
@@ -64,7 +79,11 @@ export class EchoerServer implements Echoer {
     )
   }
 
-  public async DoNothing(): Promise<Empty> {
+  public async DoNothing(
+    _request: Empty,
+    _abortSignal: AbortSignal,
+    _context: ServerContext,
+  ): Promise<Empty> {
     return {}
   }
 }

package/mock/mock_srpc.pb.ts

@@ -4,7 +4,7 @@
 
 import { MockMsg } from './mock.pb.js'
 import { MethodKind } from '@aptre/protobuf-es-lite'
-import { ProtoRpc } from 'starpc'
+import { ProtoRpc, ServerContext } from 'starpc'
 
 /**
  * Mock service mocks some RPCs for the e2e tests.
@@ -42,6 +42,24 @@ export interface Mock {
   MockRequest(request: MockMsg, abortSignal?: AbortSignal): Promise<MockMsg>
 }
 
+/**
+ * Mock service mocks some RPCs for the e2e tests.
+ *
+ * @generated from service e2e.mock.Mock
+ */
+export interface MockHandler {
+  /**
+   * MockRequest runs a mock unary request.
+   *
+   * @generated from rpc e2e.mock.Mock.MockRequest
+   */
+  MockRequest(
+    request: MockMsg,
+    abortSignal: AbortSignal,
+    context: ServerContext,
+  ): Promise<MockMsg>
+}
+
 export const MockServiceName = MockDefinition.typeName
 
 export class MockClient implements Mock {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starpc",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Streaming protobuf RPC service protocol over any two-way channel.",
   "license": "MIT",
   "author": {
@@ -114,7 +114,7 @@
     "happy-dom": "^20.9.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.0",
-    "oxfmt": "0.61.0",
+    "oxfmt": "0.62.0",
     "oxlint": "^1.76.0",
     "rimraf": "^6.1.3",
     "tsx": "^4.20.4",

package/srpc/channel.test.ts

@@ -1,9 +1,29 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { pushable } from 'it-pushable'
 
 import { ChannelStream } from './channel.js'
 
 describe('ChannelStream', () => {
+  it('recognizes MessagePort implementations from another realm', () => {
+    const port = {
+      close: vi.fn(),
+      onmessage: null,
+      postMessage: vi.fn(),
+      start: vi.fn(),
+    } as unknown as MessagePort
+
+    const stream = new ChannelStream<Uint8Array>('client', port)
+    try {
+      expect(port.start).toHaveBeenCalledOnce()
+      expect(port.postMessage).toHaveBeenCalledWith({
+        ack: true,
+        from: 'client',
+      })
+    } finally {
+      stream.close()
+    }
+  })
+
   it('keeps MessagePort peer writes open after local source completes normally', async () => {
     const { port1, port2 } = new MessageChannel()
     const client = new ChannelStream<Uint8Array>('client', port1)

package/srpc/channel.ts

@@ -26,6 +26,10 @@ export type ChannelPort =
   | MessagePort
   | { tx: BroadcastChannel; rx: BroadcastChannel }
 
+function isMessagePort(channel: ChannelPort): channel is MessagePort {
+  return 'postMessage' in channel && 'start' in channel
+}
+
 // ChannelStreamOpts are options for ChannelStream.
 export interface ChannelStreamOpts {
   // remoteOpen indicates that the remote already knows the channel is open.
@@ -149,7 +153,7 @@ export class ChannelStream<T = Uint8Array> implements Duplex<
 
     // wire up the message handlers
     const onMessage = this.onMessage.bind(this)
-    if (channel instanceof MessagePort) {
+    if (isMessagePort(channel)) {
       // MessagePort
       channel.onmessage = onMessage
       channel.start()
@@ -180,7 +184,7 @@ export class ChannelStream<T = Uint8Array> implements Duplex<
       return
     }
     msg.from = this.localId
-    if (this.channel instanceof MessagePort) {
+    if (isMessagePort(this.channel)) {
       this.channel.postMessage(msg)
     } else {
       this.channel.tx.postMessage(msg)
@@ -222,7 +226,7 @@ export class ChannelStream<T = Uint8Array> implements Duplex<
     this.localWriteClosed = true
     this.remoteWriteClosed = true
     // close channels
-    if (this.channel instanceof MessagePort) {
+    if (isMessagePort(this.channel)) {
       this.channel.onmessage = null
       this.channel.close()
     } else {

package/srpc/handler.ts

@@ -1,12 +1,58 @@
 import type { Sink, Source } from 'it-stream-types'
-import { ServiceDefinition, ServiceMethodDefinitions } from './definition.js'
+import { MethodKind, type MessageType } from '@aptre/protobuf-es-lite'
+import type { MessageStream } from './message.js'
+import {
+  type MethodDefinition,
+  ServiceDefinition,
+  ServiceMethodDefinitions,
+} from './definition.js'
 import { createInvokeFn } from './invoker.js'
+import type { ServerContext } from './server-context.js'
+
+type MessageOf<T> = T extends MessageType<infer M> ? M : never
+
+type ServerMethod<T> =
+  T extends MethodDefinition<
+    infer Request,
+    infer Response,
+    infer Kind,
+    infer _Idempotency
+  >
+    ? Kind extends MethodKind.Unary
+      ? (
+          request: MessageOf<Request>,
+          abortSignal: AbortSignal,
+          context: ServerContext,
+        ) => Promise<MessageOf<Response>>
+      : Kind extends MethodKind.ServerStreaming
+        ? (
+            request: MessageOf<Request>,
+            abortSignal: AbortSignal,
+            context: ServerContext,
+          ) => MessageStream<MessageOf<Response>>
+        : Kind extends MethodKind.ClientStreaming
+          ? (
+              request: MessageStream<MessageOf<Request>>,
+              abortSignal: AbortSignal,
+              context: ServerContext,
+            ) => Promise<MessageOf<Response>>
+          : (
+              request: MessageStream<MessageOf<Request>>,
+              abortSignal: AbortSignal,
+              context: ServerContext,
+            ) => MessageStream<MessageOf<Response>>
+    : never
+
+export type HandlerImplementation<T extends ServiceMethodDefinitions> =
+  Partial<{
+    [Method in keyof T]: ServerMethod<T[Method]>
+  }>
 
 // InvokeFn describes an SRPC call method invoke function.
 export type InvokeFn = (
   dataSource: Source<Uint8Array>,
   dataSink: Sink<Source<Uint8Array>>,
-  invocation?: AbortSignal,
+  context: ServerContext,
 ) => Promise<void>
 
 // Handler describes a SRPC call handler implementation.
@@ -62,7 +108,11 @@ export class StaticHandler implements Handler {
 // if serviceID is not set, uses the fullName of the service as the identifier.
 export function createHandler<
   T extends ServiceMethodDefinitions = ServiceMethodDefinitions,
->(definition: ServiceDefinition<T>, impl: any, serviceID?: string): Handler {
+>(
+  definition: ServiceDefinition<T>,
+  impl: HandlerImplementation<T>,
+  serviceID?: string,
+): Handler {
   // serviceID defaults to the full name of the service from Protobuf.
   serviceID = serviceID || definition.typeName
 
@@ -70,7 +120,7 @@ export function createHandler<
   const methodMap: MethodMap = {}
   for (const methodInfo of Object.values(definition.methods)) {
     const methodName = methodInfo.name
-    let methodProto = impl[methodName]
+    let methodProto = impl[methodName as keyof T] as any
     if (!methodProto) {
       continue
     }

package/srpc/index.ts

@@ -83,3 +83,10 @@ export {
 } from './pushable.js'
 export { Watchdog } from './watchdog.js'
 export type { ProtoRpc } from './proto-rpc.js'
+
+export {
+  createContextKey,
+  serverContextValue,
+  withServerContextValue,
+} from './server-context.js'
+export type { ContextKey, ServerContext } from './server-context.js'

package/srpc/invoker.ts

@@ -2,6 +2,7 @@ import { Sink, Source } from 'it-stream-types'
 import { pushable } from 'it-pushable'
 import { pipe } from 'it-pipe'
 import type { MethodDefinition } from './definition.js'
+import type { ServerContext } from './server-context.js'
 import { InvokeFn } from './handler.js'
 import {
   buildDecodeMessageTransform,
@@ -13,10 +14,26 @@ import { MethodIdempotency, MethodKind } from '@aptre/protobuf-es-lite'
 
 // MethodProto is a function which matches one of the RPC signatures.
 export type MethodProto<R extends Message<R>, O extends Message<O>> =
-  | ((request: R, invocation?: AbortSignal) => Promise<O>)
-  | ((request: R, invocation?: AbortSignal) => AsyncIterable<O>)
-  | ((request: AsyncIterable<R>, invocation?: AbortSignal) => Promise<O>)
-  | ((request: AsyncIterable<R>, invocation?: AbortSignal) => AsyncIterable<O>)
+  | ((
+      request: R,
+      abortSignal: AbortSignal,
+      context: ServerContext,
+    ) => Promise<O>)
+  | ((
+      request: R,
+      abortSignal: AbortSignal,
+      context: ServerContext,
+    ) => AsyncIterable<O>)
+  | ((
+      request: AsyncIterable<R>,
+      abortSignal: AbortSignal,
+      context: ServerContext,
+    ) => Promise<O>)
+  | ((
+      request: AsyncIterable<R>,
+      abortSignal: AbortSignal,
+      context: ServerContext,
+    ) => AsyncIterable<O>)
 
 // createInvokeFn builds an InvokeFn from a method definition and a function prototype.
 export function createInvokeFn<R extends Message<R>, O extends Message<O>>(
@@ -32,7 +49,7 @@ export function createInvokeFn<R extends Message<R>, O extends Message<O>>(
   return async (
     dataSource: Source<Uint8Array>,
     dataSink: Sink<Source<Uint8Array>>,
-    invocation?: AbortSignal,
+    context: ServerContext,
   ) => {
     // responseSink is a Sink for response messages.
     const responseSink = pushable<O>({
@@ -67,7 +84,7 @@ export function createInvokeFn<R extends Message<R>, O extends Message<O>>(
 
     // Call the implementation.
     try {
-      const responseObj = methodProto(requestArg, invocation)
+      const responseObj = methodProto(requestArg, context.signal, context)
       if (!responseObj) {
         throw new Error('return value was undefined')
       }

package/srpc/server-context.ts

@@ -0,0 +1,55 @@
+declare const contextKeyValue: unique symbol
+const contextParent = Symbol('server context parent')
+const contextKey = Symbol('server context key')
+const contextStoredValue = Symbol('server context value')
+
+// ContextKey identifies one typed server-context value.
+export interface ContextKey<T> {
+  readonly [contextKeyValue]?: T
+}
+
+// ServerContext carries cancellation for one server invocation.
+export interface ServerContext {
+  readonly signal: AbortSignal
+}
+
+type StoredServerContext = ServerContext & {
+  readonly [contextParent]?: ServerContext
+  readonly [contextKey]?: ContextKey<unknown>
+  readonly [contextStoredValue]?: unknown
+}
+
+// createContextKey constructs an identity key for one server-context value.
+export function createContextKey<T>(): ContextKey<T> {
+  return {}
+}
+
+// withServerContextValue derives a context with one immutable typed value.
+export function withServerContextValue<T>(
+  context: ServerContext,
+  key: ContextKey<T>,
+  value: T,
+): ServerContext {
+  const derived: StoredServerContext = {
+    signal: context.signal,
+    [contextParent]: context,
+    [contextKey]: key as ContextKey<unknown>,
+    [contextStoredValue]: value,
+  }
+  return derived
+}
+
+// serverContextValue retrieves the nearest value for a typed identity key.
+export function serverContextValue<T>(
+  context: ServerContext,
+  key: ContextKey<T>,
+): T | undefined {
+  let current: StoredServerContext | undefined = context as StoredServerContext
+  while (current) {
+    if (current[contextKey] === key) {
+      return current[contextStoredValue] as T
+    }
+    current = current[contextParent] as StoredServerContext | undefined
+  }
+  return undefined
+}

package/srpc/server-rpc.ts

@@ -4,6 +4,7 @@ import type { CallData, CallStart } from './rpcproto.pb.js'
 import { CommonRPC } from './common-rpc.js'
 import { InvokeFn } from './handler.js'
 import { LookupMethod } from './mux.js'
+import type { ServerContext } from './server-context.js'
 
 // ServerRPC is an ongoing RPC from the server side.
 export class ServerRPC extends CommonRPC {
@@ -47,7 +48,9 @@ export class ServerRPC extends CommonRPC {
   private async invokeRPC(invokeFn: InvokeFn) {
     const dataSink = this._createDataSink()
     try {
-      await invokeFn(this.rpcDataSource, dataSink, this.invocationSignal)
+      await invokeFn(this.rpcDataSource, dataSink, {
+        signal: this.invocationSignal,
+      } satisfies ServerContext)
     } catch (err) {
       this.close(err as Error)
     }

package/srpc/server.test.ts

@@ -10,6 +10,10 @@ import {
   combineUint8ArrayListTransform,
   ChannelStreamOpts,
   Packet,
+  createContextKey,
+  serverContextValue,
+  withServerContextValue,
+  type ServerContext,
 } from '../srpc/index.js'
 import {
   EchoerDefinition,
@@ -78,12 +82,21 @@ describe('srpc server', () => {
   it('should pass rpc stream tests', async () => {
     await runRpcStreamTest(client)
   })
-  it('passes the exact invocation signal after async request decode', async () => {
+  it('passes the exact invocation context after async request decode', async () => {
     const controller = new AbortController()
-    let observedSignal: AbortSignal | undefined
+    const callerKey = createContextKey<string>()
+    let observedAbortSignal: AbortSignal | undefined
+    let observedContextSignal: AbortSignal | undefined
+    let observedCaller: string | undefined
     const handler = createHandler(EchoerDefinition, {
-      Echo: async (request: EchoMsgType, signal?: AbortSignal) => {
-        observedSignal = signal
+      Echo: async (
+        request: EchoMsgType,
+        abortSignal: AbortSignal,
+        context: ServerContext,
+      ) => {
+        observedAbortSignal = abortSignal
+        observedContextSignal = context.signal
+        observedCaller = serverContextValue(context, callerKey)
         return request
       },
     })
@@ -104,9 +117,41 @@ describe('srpc server', () => {
         }
         drained.resolve()
       },
-      controller.signal,
+      withServerContextValue(
+        { signal: controller.signal },
+        callerKey,
+        'caller-1',
+      ),
     )
     await drained.promise
+    expect(observedAbortSignal).toBe(controller.signal)
+    expect(observedContextSignal).toBe(controller.signal)
+    expect(observedCaller).toBe('caller-1')
+  })
+
+  it('keeps two-argument server handlers compatible', async () => {
+    const controller = new AbortController()
+    let observedSignal: AbortSignal | undefined
+    const handler = createHandler(EchoerDefinition, {
+      Echo: async (request: EchoMsgType, abortSignal?: AbortSignal) => {
+        observedSignal = abortSignal
+        return request
+      },
+    })
+    const invokeFn = await handler.lookupMethod(EchoerServiceName, 'Echo')
+    if (!invokeFn) throw new Error('Echo method was not found')
+    const request = EchoMsg.create({ body: 'legacy handler' })
+    await invokeFn(
+      (async function* () {
+        yield EchoMsg.toBinary(request)
+      })(),
+      async (source) => {
+        for await (const _data of source) {
+          // Drain the response.
+        }
+      },
+      { signal: controller.signal },
+    )
     expect(observedSignal).toBe(controller.signal)
   })
 

package/srpc/watchdog.test.ts

@@ -7,6 +7,7 @@ describe('Watchdog', () => {
   })
 
   afterEach(() => {
+    vi.useRealTimers()
     vi.restoreAllMocks()
   })