Client Operations

/**
 * Base class for all gRPC clients with connection management and call methods
 */
class Client {
  /**
   * Create a new gRPC client
   * @param address - Server address (host:port format)
   * @param credentials - Channel credentials for the connection
   * @param options - Optional client configuration
   */
  constructor(address: string, credentials: ChannelCredentials, options?: Partial<ClientOptions>);
  
  /**
   * Close the client and clean up resources
   */
  close(): void;
  
  /**
   * Wait for the client to be ready to make calls
   * @param deadline - When to stop waiting (Date or milliseconds from now)
   * @param callback - Called when ready or deadline exceeded
   */
  waitForReady(deadline: Date | number, callback: (error?: Error) => void): void;
  
  /**
   * Get the underlying channel for advanced operations
   * @returns The channel instance
   */
  getChannel(): Channel;
}

interface ClientOptions {
  /** Array of interceptors to apply to all calls */
  interceptors?: Interceptor[];
  /** Array of interceptor providers for dynamic interceptor creation */
  interceptor_providers?: InterceptorProvider[];
  /** Override the default channel implementation */
  channelOverride?: Channel;
  /** Factory function to create custom channels */
  channelFactoryOverride?: (
    address: string,
    credentials: ChannelCredentials,
    options: ChannelOptions
  ) => Channel;
}

interface CallOptions {
  /** When the call should timeout (Date or milliseconds from now) */
  deadline?: Date | number;
  /** Override the default host header */
  host?: string;
  /** Parent call for tracing/context propagation */
  parent?: Call;
  /** Flags controlling what gets propagated from parent call */
  propagate_flags?: number;
  /** Call-level credentials (combined with channel credentials) */
  credentials?: CallCredentials;
  /** Interceptors to apply to this specific call */
  interceptors?: Interceptor[];
  /** Interceptor providers for this specific call */
  interceptor_providers?: InterceptorProvider[];
}

interface ClientUnaryCall extends EventEmitter {
  /** Cancel the ongoing call */
  cancel(): void;
  /** Get the peer address of the server */
  getPeer(): string;
}

import { credentials, makeClientConstructor } from "@grpc/grpc-js";

const client = new ClientConstructor("localhost:50051", credentials.createInsecure());

// Unary call with callback
client.sayHello({ name: "World" }, (error, response) => {
  if (error) {
    console.error("Call failed:", error);
    return;
  }
  console.log("Response:", response.message);
});

// Unary call with options
client.sayHello(
  { name: "World" },
  { deadline: Date.now() + 5000 }, // 5 second timeout
  (error, response) => {
    console.log("Response:", response);
  }
);

interface ClientWritableStream<RequestType> extends Writable {
  /** Cancel the ongoing call */
  cancel(): void;
  /** Get the peer address of the server */
  getPeer(): string;
}

const call = client.uploadData((error, response) => {
  if (error) {
    console.error("Upload failed:", error);
    return;
  }
  console.log("Upload complete:", response);
});

// Send multiple messages
call.write({ chunk: "data1" });
call.write({ chunk: "data2" });
call.write({ chunk: "data3" });
call.end();

interface ClientReadableStream<ResponseType> extends Readable {
  /** Cancel the ongoing call */
  cancel(): void;
  /** Get the peer address of the server */
  getPeer(): string;
}

const call = client.downloadData({ query: "some data" });

call.on('data', (response) => {
  console.log("Received chunk:", response.chunk);
});

call.on('end', () => {
  console.log("Download complete");
});

call.on('error', (error) => {
  console.error("Download failed:", error);
});

interface ClientDuplexStream<RequestType, ResponseType> extends Duplex {
  /** Cancel the ongoing call */
  cancel(): void;
  /** Get the peer address of the server */
  getPeer(): string;
}

const call = client.chat();

// Handle incoming messages
call.on('data', (response) => {
  console.log("Received:", response.message);
});

// Send messages
call.write({ message: "Hello" });
call.write({ message: "How are you?" });

call.on('end', () => {
  console.log("Chat ended");
});

/**
 * Close a client instance and clean up resources
 * @param client - The client to close
 */
function closeClient(client: Client): void;

/**
 * Wait for a client to be ready to make calls
 * @param client - The client to check
 * @param deadline - When to stop waiting
 * @param callback - Called when ready or deadline exceeded
 */
function waitForClientReady(
  client: Client,
  deadline: Date | number,
  callback: (error?: Error) => void
): void;

/**
 * Get the underlying channel from a client
 * @param client - The client instance
 * @returns The channel instance
 */
function getClientChannel(client: Client): Channel;

interface ServiceError extends Error {
  /** gRPC status code */
  code: status;
  /** Detailed error message */
  details: string;
  /** Response metadata/trailers */
  metadata: Metadata;
}

client.sayHello({ name: "World" }, (error, response) => {
  if (error) {
    console.error(`gRPC call failed with status ${error.code}: ${error.details}`);
    console.error("Metadata:", error.metadata.getMap());
    return;
  }
  console.log("Success:", response);
});

interface ChannelImplementation {
  /** Get current connectivity state */
  getConnectivityState(tryToConnect: boolean): connectivityState;
  /** Watch for connectivity state changes */
  watchConnectivityState(
    currentState: connectivityState,
    deadline: Date | number,
    callback: (error?: Error) => void
  ): void;
  /** Close the channel */
  close(): void;
  /** Get target address */
  getTarget(): string;
}

interface CallProperties<RequestType, ResponseType> {
  /** The request argument/message (optional) */
  argument?: RequestType;
  /** Request metadata */
  metadata: Metadata;
  /** The surface call object */
  call: SurfaceCall;
  /** The channel being used */
  channel: Channel;
  /** The method definition */
  methodDefinition: ClientMethodDefinition<RequestType, ResponseType>;
  /** Call options */
  callOptions: CallOptions;
  /** Callback for unary calls (optional) */
  callback?: UnaryCallback<ResponseType>;
}

interface CallInvocationTransformer {
  <RequestType, ResponseType>(properties: CallProperties<RequestType, ResponseType>): CallProperties<RequestType, ResponseType>;
}