Paralax gRPC Library

The Paralax gRPC Library extends the Paralax Framework with gRPC functionality, allowing high-performance, language-agnostic communication between services. It is designed for seamless integration with .NET and optimized for low-latency, high-throughput applications in distributed microservice environments. The library includes options for configuring gRPC and REST endpoints, health checks, and efficient resource usage monitoring.

---

Table of Contents

• Overview
• Installation
• Getting Started
• Core Configuration Options
• Usage Examples
• Advanced Options

---

Overview

Paralax gRPC provides:

• Dual-Protocol Support: Simultaneous gRPC and RESTful endpoints with flexible configuration.
• Monitoring Services: Built-in utilities for uptime, CPU usage, and memory usage monitoring.
• Reflection Support: Allows clients to discover gRPC services and messages dynamically, useful for debugging and development.
• Customizable Message Sizes: Configure message size limits for optimized performance.

---

Installation

Add the Paralax gRPC package to your project using NuGet:

dotnet add package Paralax.gRPC

---

Getting Started

To start using Paralax gRPC, configure it within your Program.cs or Startup.cs files using the provided AddParalaxGrpc and UseParalaxGrpc extension methods.

Step 1: Configure gRPC Services

In Program.cs or Startup.cs, use AddParalaxGrpc to set up gRPC services with default or custom configurations.

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    // Add Paralax gRPC services
    builder.Services.AddParalaxGrpc();

    var app = builder.Build();

    // Configure gRPC middleware
    app.UseParalaxGrpc();

    app.Run();
}

---

Core Configuration Options

By default, AddParalaxGrpc reads settings from the GrpcOptions section of appsettings.json. You can customize options such as ports, message size limits, and environment. Below is an example configuration in appsettings.json:

{
  "GrpcOptions": [
    {
      "ServiceName": "ExampleService",
      "ServiceVersion": "1.0.0",
      "Environment": "Production",
      "RestPort": 5045,
      "GrpcPort": 7146,
      "EnableReflection": true,
      "MaxReceiveMessageSize": 8388608,
      "MaxSendMessageSize": 8388608
    }
  ]
}

Configuration Fields

• ServiceName: Name of the gRPC service.
• ServiceVersion: Version of the service.
• Environment: Deployment environment (e.g., Production, Staging).
• RestPort: Port for RESTful endpoint (HTTP/1.1).
• GrpcPort: Port for gRPC endpoint (HTTP/2).
• EnableReflection: Enables gRPC reflection for service discovery.
• MaxReceiveMessageSize: Maximum size (bytes) for incoming messages.
• MaxSendMessageSize: Maximum size (bytes) for outgoing messages.

Step 2: Use gRPC Middleware

Use the UseParalaxGrpc extension to activate gRPC endpoints. Optionally, define custom endpoints or enable reflection services.

app.UseParalaxGrpc(endpoints =>
{
    // Configure custom gRPC endpoints if needed
});

---

Usage Examples

Basic gRPC Service Setup

builder.Services.AddParalaxGrpc("GrpcOptions", options =>
{
    options.ConfigureKestrel(kestrelOptions =>
    {
        kestrelOptions.ListenAnyIP(5045, listenOptions =>
        {
            listenOptions.Protocols = HttpProtocols.Http1;
        });
        kestrelOptions.ListenAnyIP(7146, listenOptions =>
        {
            listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
        });
    });
});

Enabling Reflection for Service Discovery

Reflection is useful for debugging and for clients to dynamically discover the services and methods provided by your gRPC server.

{
  "GrpcOptions": [
    {
      "EnableReflection": true
    }
  ]
}

app.UseParalaxGrpc(endpoints =>
{
    endpoints.MapGrpcReflectionService();
});

---

Advanced Options

The AddParalaxGrpc method allows customization via the GrpcOptionsBuilder. Here are additional configuration examples:

Customizing Message Size Limits

To support larger or smaller payloads, adjust the MaxReceiveMessageSize and MaxSendMessageSize:

{
  "GrpcOptions": [
    {
      "MaxReceiveMessageSize": 16777216, // 16 MB
      "MaxSendMessageSize": 16777216     // 16 MB
    }
  ]
}

Performance Monitoring Services

Paralax gRPC includes services to monitor uptime, CPU, and memory usage. These can be registered automatically when AddParalaxGrpc is called.

builder.Services.AddParalaxGrpc();

These services provide basic diagnostics that are useful in production environments to ensure services are running efficiently.

---

Conclusion

The Paralax gRPC Library is a flexible and powerful tool for building high-performance microservices with both gRPC and REST support. With built-in reflection, diagnostics, and customizable configurations, it provides the essential infrastructure for robust and efficient communication in distributed systems.

For more details, visit the Paralax Framework Documentation or check out additional examples in the Paralax repository.