Flynk.Net.Services.Transmit.Grpc.Server 1.5.0

Flynk.Net.Services.Transmit.Grpc.Server

Server-side gRPC hosting library for the Flynk Transmission Service. Provides ASP.NET Core integration, service configuration, and port management utilities.

Features

• ASP.NET Core gRPC service implementation
• Cross-process request/response with automatic correlation
• Flexible port configuration (separate HTTP/gRPC or shared)
• Port availability validation on startup
• Handler registry for request routing
• Security controls for client-to-client communication

Installation

dotnet add package Flynk.Net.Services.Transmit.Grpc.Server

This package automatically includes Flynk.Net.Services.Transmit.Grpc.Common for shared types.

Quick Start

1. Create ASP.NET Core Project

dotnet new web -n MyServer
cd MyServer
dotnet add package Flynk.Net.Services.Transmit.Grpc.Server

2. Configure Program.cs

using Flynk.Net.Services.Transmit.Grpc.Server;
using Flynk.Net.Services.Transmit.Grpc.Server.Extensions;
using Flynk.Net.Services.Transmit.Grpc.Client;

var builder = WebApplication.CreateBuilder(args);

// Add transmission service on port 5001
builder.AddTransmissionService(grpcPort: 5001);

var app = builder.Build();

// Map the gRPC endpoint
app.MapTransmissionService();

// Register server handler for incoming requests
RpcHandlerRegistry.RegisterServerHandler(async (request) =>
{
    Console.WriteLine($"Received: {request.MessageType}");

    return new TransmissionResponse
    {
        Id = Guid.NewGuid().ToString(),
        CorrelationId = request.Id,
        Success = true,
        StatusCode = 200,
        Timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
    };
}, serverId: "server");

app.Run();

3. Run

dotnet run

Configuration Options

Simple gRPC-Only Setup

builder.AddTransmissionService(grpcPort: 5001);

Separate REST and gRPC Ports

builder.AddTransmissionService(httpPort: 5000, grpcPort: 5001);

Full Configuration

builder.AddTransmissionService(options =>
{
    options.HttpPort = 5000;              // REST API port (HTTP/1.1)
    options.GrpcPort = 5001;              // gRPC port (HTTP/2)
    options.Host = "0.0.0.0";             // Listen on all interfaces
    options.ValidatePorts = true;         // Check port availability
    options.ServiceName = "MyServer";     // For error messages
    options.UseHttps = false;             // Enable HTTPS
});

Server Handler Registration

Basic Handler

RpcHandlerRegistry.RegisterServerHandler(async (request) =>
{
    return request.MessageType switch
    {
        "ping" => CreateResponse(request, true, "pong"),
        "echo" => CreateResponse(request, true, payload: request.Payload),
        _ => CreateResponse(request, false, $"Unknown route: {request.MessageType}", 404)
    };
}, serverId: "server");

Using RpcClient on Server

For typed routing on the server, use RpcClient with RegisterAsServerHandler():

var loggerFactory = LoggerFactory.Create(b => b.AddConsole());
var logger = loggerFactory.CreateLogger<RpcClient>();

var serverClient = new RpcClient(
    address: "http://localhost:5001",
    id: "server",
    logger: logger,
    loggerFactory: loggerFactory  // Enables TransmissionClient logging
);

// Register typed routes
serverClient.RegisterRoute<PingRequest, PongResponse>("ping",
    async (request) =>
    {
        return Response<PongResponse>.OK(new PongResponse { Message = "pong" });
    });

serverClient.RegisterRoute<CreateUserRequest, CreateUserResponse>("user.create",
    async (request) =>
    {
        var user = await userService.CreateAsync(request);
        return Response<CreateUserResponse>.OK(new CreateUserResponse { UserId = user.Id });
    });

// Register as the server handler (handles requests without recipientId)
serverClient.RegisterAsServerHandler();

serverClient.StartListening();

Cross-Process Request/Response

When the server uses RequestAsync to send a request to a remote client (connected via the Receive stream), the server automatically waits for the client's response using correlation IDs. This enables synchronous RPC between the server and clients running in separate processes.

Server                        TransmissionServiceImpl              Client (separate process)
  |                                    |                                    |
  |-- RequestAsync(recipientId) ------>|                                    |
  |   (sets reply-to metadata)        |                                    |
  |                                    |-- Write to Receive stream -------->|
  |                                    |   (registers pending request)      |
  |                                    |                                    |-- Process request
  |                                    |                                    |
  |                                    |<-- Send(CorrelationId=requestId) --|
  |                                    |   (completes pending request)      |
  |<-- actual response ----------------|                                    |

The correlation is transparent — RequestAsync sets reply-to metadata automatically, and TransmissionServiceImpl handles the pending request lifecycle with a 120-second timeout.

Security: Client-to-Client Communication

By default, clients can only communicate with the server. This prevents unauthorized peer-to-peer messaging.

Enable Client-to-Client (if needed)

// Only enable if your application requires peer-to-peer messaging
RpcHandlerRegistry.EnableClientToClientCommunication();

Disable (default)

RpcHandlerRegistry.DisableClientToClientCommunication();

When disabled, attempts to send messages between clients return HTTP 403 (Forbidden).

Port Utilities

Check Port Availability

using Flynk.Net.Services.Transmit.Grpc.Utilities;

if (!PortUtility.IsPortAvailable(5001))
{
    Console.WriteLine(PortUtility.CreatePortConflictMessage(5001, "MyServer"));
}

Find Available Port

var port = PortUtility.FindAvailablePort(5001, 5100);
if (port.HasValue)
{
    Console.WriteLine($"Available port: {port}");
}

Adding REST Endpoints

The server can host both gRPC and REST endpoints:

var builder = WebApplication.CreateBuilder(args);

// Configure both HTTP (REST) and gRPC ports
builder.AddTransmissionService(httpPort: 5000, grpcPort: 5001);

var app = builder.Build();

// REST endpoints on port 5000
app.MapGet("/health", () => "OK");
app.MapGet("/api/status", () => new { Status = "Running" });

// gRPC endpoint on port 5001
app.MapTransmissionService();

app.Run();

Routing Priority

1. recipientId is null/empty → Server handler
2. recipientId matches serverId → Server handler
3. recipientId matches registered client → Client handler (if enabled)
4. Client-to-client disabled → 403 Forbidden
5. No match → 404 Not Found

Troubleshooting

Port Conflicts

If the server fails to start:

builder.AddTransmissionService(options =>
{
    options.GrpcPort = 5001;
    options.ValidatePorts = true;  // Will throw on conflict
    options.ServiceName = "MyServer";  // Better error messages
});

Handler Not Found

• Ensure RpcHandlerRegistry.RegisterServerHandler() is called before app.Run()
• Verify route names match exactly (case-sensitive)
• Check recipientId is null/empty or matches serverId

Connection Issues

Enable detailed logging:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.SetMinimumLevel(LogLevel.Debug);

Client Package

For client applications, install the lightweight client package:

dotnet add package Flynk.Net.Services.Transmit.Grpc.Client

See the Client package documentation for usage.

License

This software is licensed under the Flynk Freeware License.