nggorpc

NgGoRPC Client

Angular client library for NgGoRPC, enabling high-performance, bidirectional gRPC over WebSockets.

Overview

This library provides the client-side implementation of the NgGoRPC protocol. It handles:

• WebSocket connection management (reconnection, keep-alive)
• Protocol framing (serialization/deserialization)
• Stream multiplexing
• Integration with ts-proto generated code

Installation

This library is part of the NgGoRPC workspace. To use it in your Angular application within the workspace:

import { NgGoRpcClient } from '@nggorpc/client';

Usage

1. Configuration

The client can be configured with NgGoRpcConfig:

export interface NgGoRpcConfig {
    /** Keep-alive ping interval in milliseconds (default: 30000) */
    pingInterval?: number;
    /** Base delay for reconnection backoff in milliseconds (default: 1000) */
    baseReconnectDelay?: number;
    /** Maximum delay for reconnection backoff in milliseconds (default: 30000) */
    maxReconnectDelay?: number;
    /** Maximum frame size in bytes (default: 4194304 = 4MB) */
    maxFrameSize?: number;
    /** Enable debug logging (default: false) */
    enableLogging?: boolean;
}

2. Initialization

The NgGoRpcClient is designed to be instantiated manually (e.g., in a service or component) rather than provided as a global singleton service, giving you control over the connection lifecycle.

import { Injectable, NgZone, inject } from '@angular/core';
import { NgGoRpcClient } from '@nggorpc/client';

@Injectable({ providedIn: 'root' })
export class GrpcService {
  private ngZone = inject(NgZone);
  public client: NgGoRpcClient;

  constructor() {
    this.client = new NgGoRpcClient(this.ngZone, {
      enableLogging: true,
      pingInterval: 15000
    });
    
    // Connect to backend
    this.client.connect('ws://localhost:8080/rpc');
  }
}

3. Making Requests

Use the client to create a transport for ts-proto generated services.

import { Component, inject } from '@angular/core';
import { MyServiceDefinition } from './generated/myservice'; // Generated by ts-proto
import { GrpcService } from './grpc.service';

@Component({ ... })
export class UserComponent {
  private grpcService = inject(GrpcService);
  private transport = this.grpcService.client.createTransport();

  ngOnInit() {
    // Unary call
    this.transport.request(
      MyServiceDefinition,
      MyServiceDefinition.methods.getUser,
      { userId: '123' }
    ).subscribe(response => {
      console.log('User:', response);
    });

    // Streaming call
    this.transport.request(
      MyServiceDefinition,
      MyServiceDefinition.methods.streamEvents,
      { topic: 'updates' }
    ).subscribe({
      next: event => console.log('Event:', event),
      error: err => console.error('Error:', err),
      complete: () => console.log('Stream closed')
    });
  }
}

4. Authentication

You can set an authentication token (e.g., JWT) to be sent with every request:

this.client.setAuthToken('your-jwt-token');

The token will be sent in the authorization header as Bearer <token>.

Connection Management

• connect(url, enableReconnection?): Connects to the WebSocket server.
• disconnect(): Closes the connection and stops reconnection attempts.
• isConnected(): Returns the current connection status.
• connectionState$: Observable that emits connection state changes (Connected, Disconnected, Reconnecting).

Building

To build the library:

ng build client