better-grpc 0.2.4 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ It enables seamless, **bidirectional** communication between a client and a serv
 -   **No `.proto` files:** No need to write `.proto` files or use `protoc` to generate code.
 -   **Simple API:** The API is designed to be simple and intuitive.
 -   **Symmetric Experience:** Call client-side functions from the server with the same syntax as calling server-side functions from the client.
+-   **Multi-Client Support:** Target specific clients from the server using client IDs, enabling per-client communication patterns.
 
 ## Installation
 
@@ -146,7 +147,68 @@ for await (const [message] of server.MyService.chat) {
 }
 ```
 
-### 7. Attach typed metadata
+### 7. Listen for bidi connections on the server
+
+The server can use the `.listen()` API to handle incoming bidi stream connections. This is useful for setting up handlers that respond to each client connection:
+
+```typescript
+server.MyService.chat.listen(({ context, messages, send }) => {
+    console.log(`New client connected ${context.client.id}`);
+    
+    (async () => {
+        for await (const [message] of messages) {
+            console.log('Received:', message);
+            await send(`Echo: ${message}`);
+        }
+    })();
+});
+```
+
+The `listen` handler receives:
+- `context`: A promise that resolves to the connection context (including metadata if defined)
+- `messages`: An async generator yielding incoming messages from the client
+- `send`: A function to send messages back to the client
+
+### 8. Target specific clients
+
+When multiple clients are connected, the server can target a specific client using its client ID. Each client is automatically assigned a unique ID.
+
+**Getting the client ID on the client side:**
+
+```typescript
+const client = await createGrpcClient('localhost:50051', myClientImpl);
+
+// Access the client's unique ID
+console.log(client.clientID); // e.g., 'abc123-def456-...'
+```
+
+**Getting the client ID on the server side:**
+
+In server handlers, the client ID is available via `context.client.id`:
+
+```typescript
+const GreeterServerImpl = GreeterService.Server({
+    greet: (name) => async (context) => {
+        console.log('Client ID:', context.client.id);
+        return `Hello, ${name}!`;
+    },
+});
+```
+
+**Targeting a specific client from the server:**
+
+```typescript
+// Call a specific client by ID
+const clientId = 'some-client-id';
+await server.MyService(clientId).log('Message for specific client');
+
+// For bidi streams, targeting a specific client
+await server.MyService(clientId).chat('hello to specific client');
+```
+
+By default, server calls target the first connected client. When you need to communicate with a specific client (e.g., in a multi-client scenario), use the client ID selector.
+
+### 9. Attach typed metadata
 
 Define metadata requirements with [Zod](https://github.com/colinhacks/zod) schemas, and `better-grpc` will automatically type the context on both sides and marshal the payload into gRPC metadata.
 
@@ -165,11 +227,11 @@ abstract class GreeterService extends Service('GreeterService') {
 }
 ```
 
-Server implementations receive the typed metadata as the first argument:
+Server implementations can optionally return a context-aware function. The outer function receives the request args, and the returned function receives the typed context:
 
 ```typescript
 const GreeterServerImpl = GreeterService.Server({
-    async greet(context, name) {
+    greet: (name) => async (context) => {
         console.log('Request', context.metadata.requestId);
         return `Hello, ${name}!`;
     },
@@ -215,7 +277,7 @@ A factory function that creates an abstract service class.
 
 - `server<T>()`
 
-Defines a server-side unary function signature. `T` should be a function type. Call the returned descriptor with `({ metadata: z.object({...}) })` to require typed metadata for that RPC. Client code then calls `client.MyService.fn(...args).withMeta({...})`, and server handlers receive the context object as the first argument.
+Defines a server-side unary function signature. `T` should be a function type. Call the returned descriptor with `({ metadata: z.object({...}) })` to require typed metadata for that RPC. Client code then calls `client.MyService.fn(...args).withMeta({...})`, and server handlers can return a function to receive the context (or just return a value if they don't need it).
 
 - `client<T>()`
 
@@ -227,7 +289,7 @@ Defines a bidirectional stream signature. `T` should be a function type that ret
 
 - `createGrpcServer(port: number, ...services: ServiceImpl[])`
 
-Creates and starts a gRPC server.
+Creates and starts a gRPC server. Returns service callables that can be invoked directly or with a client ID selector: `server.MyService.method()` or `server.MyService(clientId).method()`.
 
 - `createGrpcClient(address: string, ...services: ServiceImpl[])`
 
@@ -237,6 +299,35 @@ Creates and starts a gRPC client using `DEFAULT_OPTIONS`.
 
 Creates and starts a gRPC client with custom gRPC channel options. `DEFAULT_OPTIONS` is exported for easy overrides.
 
+### Server-side bidi listen
+
+For bidi streams, the server exposes a `.listen()` method to handle incoming connections:
+
+```typescript
+server.MyService.bidiFn.listen((connection) => {
+    // connection.context: Promise<Context> - resolves to typed context/metadata
+    // connection.messages: AsyncGenerator - incoming messages from client
+    // connection.send: Function - send messages to the client
+});
+```
+
+## Deployment
+
+If you deploy behind Traefik (including Dokploy), make sure the **entrypoint** timeouts allow long-lived HTTP/2 streams. Otherwise, bidi streams can be cancelled around the default timeout window.
+
+This is a static Traefik setting (not the dynamic `http:` config). Add this to your Traefik config and reload:
+
+```yaml
+entryPoints:
+  websecure:
+    address: :443
+    transport:
+      respondingTimeouts:
+        readTimeout: 0s
+        writeTimeout: 0s
+        idleTimeout: 0s
+```
+
 ## Benchmarks
 
 ### Simple "Hello World"

package/dist/index.d.ts

@@ -1,39 +1,26 @@
-import { z } from 'zod';
+import z$1, { z } from 'zod';
 import { ChannelOptions } from 'nice-grpc';
 
 type Context<Meta extends z.ZodObject<any> | undefined> = {
     metadata: Meta extends z.ZodObject<any> ? z.infer<Meta> : undefined;
+    client: {
+        id: string;
+    };
 };
-type PrependContext<C extends Context<any>, Args extends any[]> = [C, ...Args];
-type DefaultContext = Context<undefined>;
-type HasMeta<C extends Context<any>> = C extends Context<infer M> ? (M extends undefined ? false : true) : false;
-type ExtractMeta<C extends Context<any>> = C extends Context<infer M> ? M : undefined;
-type ContextRequiredFn<fn extends (...args: any[]) => any, C extends Context<any>, RequireMeta extends boolean = HasMeta<C>> = RequireMeta extends true ? (...args: Parameters<fn>) => {
-    withMeta<M extends ExtractMeta<C>>(metadata: z.infer<M>): ContextRequiredFn<fn, C, false>;
-} : ReturnType<fn>;
+type AnyContext = Context<any>;
 
 declare const ScopeTag: unique symbol;
-type AnyFn<R> = (...args: any[]) => R;
-type BidiType<fn extends AnyFn<any>, C extends Context<any>, type extends "server" | "client"> = fn & AsyncGenerator<Parameters<fn>, void, unknown> & BidiContextType<C, type>;
-type BidiContextType<C extends Context<any>, type extends "server" | "client"> = type extends "client" ? {
-    context: Promise<C>;
-} : {
-    context(context: C): Promise<void>;
-};
-type serverSignature<fn extends AnyFn<any>, C extends Context<any>> = (C extends DefaultContext ? <Meta extends z.ZodObject<any> | undefined>(context: {
-    metadata?: Meta;
-}) => serverSignature<fn, Context<Meta>> : fn) & {
-    [ScopeTag]: "server";
-};
-type clientSignature<fn extends AnyFn<any>> = fn & {
-    [ScopeTag]: "client";
-};
-type bidiSignature<fn extends AnyFn<void>, C extends Context<any>> = (C extends DefaultContext ? <Meta extends z.ZodObject<any> | undefined, Ack extends boolean = false>(context: {
-    metadata?: Meta;
-    ack?: Ack;
-}) => bidiSignature<fn, Context<Meta>> : fn) & {
-    [ScopeTag]: "bidi";
+declare const FunctionTag: unique symbol;
+declare const ContextTag: unique symbol;
+type BaseSignature<type extends "server" | "client" | "bidi", fn extends (...args: any[]) => any, C extends AnyContext | undefined> = {
+    [ScopeTag]: type;
+    [FunctionTag]: fn;
+    [ContextTag]: type extends "server" ? (C extends undefined ? Context<undefined> : C) : C;
 };
+type AnyBaseSignature = BaseSignature<any, any, any>;
+type ExtractFn<S extends AnyBaseSignature> = (...args: Parameters<S[typeof FunctionTag]>) => Promise<ReturnType<S[typeof FunctionTag]>>;
+type ValidReturnType<fn extends (...args: any[]) => any> = ReturnType<fn> extends Function | Promise<any> ? never : ReturnType<fn>;
+type ExtractImplFn<S extends AnyBaseSignature> = S[typeof ScopeTag] extends "server" ? ExtractFn<S> | ((...args: Parameters<S[typeof FunctionTag]>) => (context: S[typeof ContextTag]) => Promise<ReturnType<S[typeof FunctionTag]>>) : S[typeof ScopeTag] extends "client" ? ExtractFn<S> : S[typeof ScopeTag] extends "bidi" ? undefined : never;
 type RpcMethodDescriptor = {
     serviceType: "server" | "client" | "bidi";
     methodType: "unary" | "bidi";
@@ -42,16 +29,52 @@ type RpcMethodDescriptor = {
         ack: boolean;
     };
 };
-declare function server<fn extends AnyFn<any>>(): serverSignature<(...args: Parameters<fn>) => Promise<ReturnType<fn>>, DefaultContext>;
-declare function client<fn extends AnyFn<any>>(): clientSignature<(...args: Parameters<fn>) => Promise<ReturnType<fn>>>;
-declare function bidi<fn extends AnyFn<void>>(..._: ReturnType<fn> extends void ? [] : ["Return type must be void"]): bidiSignature<(...args: Parameters<fn>) => Promise<void>, DefaultContext>;
-type Unwrap<T, type extends "server" | "client", ContextChain extends boolean = false> = T extends serverSignature<infer F, infer C> ? C extends DefaultContext ? F : ContextChain extends true ? ContextRequiredFn<F, C> : (...args: PrependContext<C, Parameters<F>>) => ReturnType<F> : T extends clientSignature<infer F> ? F : T extends bidiSignature<infer F, infer C> ? BidiType<F, C, type> : never;
-type ServerFn<T, IncludeBidi extends boolean = true, ContextChain extends boolean = false> = {
-    [K in keyof T as T[K] extends serverSignature<AnyFn<any>, any> | (IncludeBidi extends true ? bidiSignature<AnyFn<void>, any> : never) ? K : never]: Unwrap<T[K], "server", ContextChain>;
+
+type BidiSignature<fn extends (...args: any[]) => any, C extends AnyContext | undefined> = BaseSignature<"bidi", fn, C> & (C extends undefined ? <Meta extends z$1.ZodObject<any>>(context: {
+    metadata?: Meta;
+    ack?: boolean;
+}) => BidiSignature<fn, Context<Meta>> : {});
+declare function bidi<fn extends (...args: any[]) => ValidReturnType<fn>>(): BidiSignature<fn, undefined>;
+
+type ClientSignature<fn extends (...args: any[]) => any, C extends AnyContext | undefined> = BaseSignature<"client", fn, C>;
+declare function client<fn extends (...args: any[]) => ValidReturnType<fn>>(): ClientSignature<fn, undefined>;
+type ClientImpls<T> = {
+    [K in keyof T as T[K] extends BaseSignature<"client", any, any> ? K : never]: T[K] extends AnyBaseSignature ? ExtractImplFn<T[K]> : never;
+};
+type ClientCallable<T, WithListen extends boolean = true> = {
+    [K in keyof T as T[K] extends BaseSignature<"client", any, any> | BaseSignature<"bidi", any, any> ? K : never]: T[K] extends BaseSignature<"client", any, any> ? ExtractFn<T[K]> : T[K] extends BaseSignature<"bidi", any, infer C> ? WithListen extends true ? BidiCallable$1<T[K], C> : BidiCallableWithoutListen<T[K], C> : never;
 };
-type ClientFn<T, IncludeBidi extends boolean = true> = {
-    [K in keyof T as T[K] extends clientSignature<AnyFn<any>> | (IncludeBidi extends true ? bidiSignature<AnyFn<void>, any> : never) ? K : never]: Unwrap<T[K], "client">;
+type BidiContext<C extends AnyContext | undefined> = C extends undefined ? Promise<Context<undefined>> : Promise<C>;
+type BidiCallableBase<S extends BaseSignature<"bidi", any, any>, C extends AnyContext | undefined> = ExtractFn<S> & {
+    context: BidiContext<C>;
+} & AsyncGenerator<Parameters<ExtractFn<S>>, void, unknown>;
+type BidiCallable$1<S extends BaseSignature<"bidi", any, any>, C extends AnyContext | undefined> = BidiCallableBase<S, C> & {
+    listen(handler: (connection: {
+        context: BidiContext<C>;
+        messages: AsyncGenerator<Parameters<ExtractFn<S>>, void, unknown>;
+        send: ExtractFn<S>;
+    }) => void): void;
 };
+type BidiCallableWithoutListen<S extends BaseSignature<"bidi", any, any>, C extends AnyContext | undefined> = BidiCallableBase<S, C>;
+
+type ServerSignature<fn extends (...args: any[]) => any, C extends AnyContext | undefined> = BaseSignature<"server", fn, C> & (C extends undefined ? <Meta extends z$1.ZodObject<any>>(context: {
+    metadata: Meta;
+}) => ServerSignature<fn, Context<Meta>> : {});
+declare function server<fn extends (...args: any[]) => ValidReturnType<fn>>(): ServerSignature<fn, undefined>;
+type ServerImpls<T> = {
+    [K in keyof T as T[K] extends BaseSignature<"server", any, any> ? K : never]: T[K] extends AnyBaseSignature ? ExtractImplFn<T[K]> : never;
+};
+type ServerCallable<T> = {
+    [K in keyof T as T[K] extends BaseSignature<"server", any, any> | BaseSignature<"bidi", any, any> ? K : never]: T[K] extends BaseSignature<"server", any, infer C> ? (...args: Parameters<ExtractFn<T[K]>>) => CallableChain<ExtractFn<T[K]>, C> : T[K] extends BaseSignature<"bidi", any, infer C> ? BidiCallable<T[K], C> : never;
+};
+type CallableChain<fn extends (...args: any[]) => any, C extends AnyContext | undefined> = C extends Context<infer Meta> ? Meta extends z$1.ZodObject<any> ? {
+    withMeta(meta: z$1.infer<Meta>): ReturnType<fn>;
+} : ReturnType<fn> : ReturnType<fn>;
+type BidiCallable<S extends BaseSignature<"bidi", any, any>, C extends AnyContext | undefined> = (C extends Context<infer Meta> ? Meta extends z$1.ZodObject<any> ? {
+    context(context: {
+        metadata: z$1.infer<Meta>;
+    }): Promise<void>;
+} & ExtractFn<S> : ExtractFn<S> : ExtractFn<S>) & AsyncGenerator<Parameters<ExtractFn<S>>, void, unknown>;
 
 declare const ServiceNameTag: unique symbol;
 interface ServiceInstance<N extends string = string> {
@@ -70,22 +93,26 @@ declare function Service<N extends string>(name: N): (abstract new () => {
     readonly [ServiceNameTag]: N;
 }) & {
     serviceName: N;
-    Server<T extends AbstractServiceClass, Impl extends ServerFn<InstanceType<T>, false>>(this: T, implementation: Impl): ServiceImpl<T, "server">;
-    Client<T extends AbstractServiceClass, Impl extends ClientFn<InstanceType<T>, false>>(this: T, implementation: Impl): ServiceImpl<T, "client">;
+    Server<T extends AbstractServiceClass, Impl extends ServerImpls<InstanceType<T>>>(this: T, implementation: Impl): ServiceImpl<T, "server">;
+    Client<T extends AbstractServiceClass, Impl extends ClientImpls<InstanceType<T>>>(this: T, implementation: Impl): ServiceImpl<T, "client">;
 };
 type ServiceNameOf<T extends ServiceImpl<any, any>> = T extends ServiceImpl<infer ServiceClass, any> ? InstanceType<ServiceClass>[typeof ServiceNameTag] : never;
-type ServiceCallable<T> = T extends ServiceImpl<infer S, infer Mode> ? Mode extends "server" ? ClientFn<InstanceType<S>> : ServerFn<InstanceType<S>, true, true> : never;
+type ServiceCallable<T, WithListen extends boolean = true> = T extends ServiceImpl<infer S, infer Mode> ? Mode extends "server" ? ClientCallable<InstanceType<S>, WithListen> : ServerCallable<InstanceType<S>> : never;
 
 declare const DEFAULT_OPTIONS: ChannelOptions;
 declare function createGrpcClient<T extends ServiceImpl<any, "client">[]>(address: string, ...serviceImpls: T): Promise<{
     [I in T[number] as ServiceNameOf<I>]: ServiceCallable<I>;
+} & {
+    clientID: string;
 }>;
 declare function createGrpcClient<T extends ServiceImpl<any, "client">[]>(address: string, grpcOptions: ChannelOptions, ...serviceImpls: T): Promise<{
     [I in T[number] as ServiceNameOf<I>]: ServiceCallable<I>;
+} & {
+    clientID: string;
 }>;
 
 declare function createGrpcServer<T extends ServiceImpl<any, "server">[]>(port: number, ...serviceImpls: T): Promise<{
-    [I in T[number] as ServiceNameOf<I>]: ServiceCallable<I>;
+    [I in T[number] as ServiceNameOf<I>]: ServiceCallable<I> & ((clientId: string) => ServiceCallable<I, false>);
 }>;
 
 export { DEFAULT_OPTIONS, Service, bidi, client, createGrpcClient, createGrpcServer, server };