or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-transport.mdindex.mdprotocol-negotiation.mdserver-transport.mdsocket-support.mdssl-tls.md
tile.json

tessl/maven-io-grpc--grpc-netty

Netty-based HTTP/2 transport implementation for gRPC Java providing high-performance network communication

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.grpc/grpc-netty@1.73.x

To install, run

npx @tessl/cli install tessl/maven-io-grpc--grpc-netty@1.73.0

index.mddocs/

gRPC Netty

gRPC Netty provides a Netty-based HTTP/2 transport implementation for gRPC Java, offering high-performance network communication capabilities. It serves as the primary transport layer for production gRPC applications, enabling efficient client-server communication over HTTP/2 protocol using the Netty framework.

Package Information

  • Package Name: io.grpc:grpc-netty
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven or Gradle dependencies 
    <dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-netty</artifactId>
  <version>1.73.0</version>
</dependency>

Core Imports

import io.grpc.netty.NettyChannelBuilder;
import io.grpc.netty.NettyServerBuilder;
import io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.NegotiationType;

Basic Usage

Client Setup

import io.grpc.ManagedChannel;
import io.grpc.netty.NettyChannelBuilder;

// Create a gRPC channel using Netty transport
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
    .usePlaintext()
    .build();

// Use the channel with your gRPC stub
// MyServiceGrpc.MyServiceBlockingStub stub = 
//     MyServiceGrpc.newBlockingStub(channel);

Server Setup

import io.grpc.Server;
import io.grpc.netty.NettyServerBuilder;

// Create a gRPC server using Netty transport
Server server = NettyServerBuilder.forPort(9090)
    .addService(new MyServiceImpl())
    .build()
    .start();

TLS Configuration

import io.grpc.netty.GrpcSslContexts;
import io.netty.handler.ssl.SslContext;

// Client with TLS
SslContext sslContext = GrpcSslContexts.forClient()
    .trustManager(new File("ca-cert.pem"))
    .build();

ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
    .sslContext(sslContext)
    .build();

// Server with TLS
SslContext serverSslContext = GrpcSslContexts.forServer(
    new File("server-cert.pem"),
    new File("server-key.pem")
).build();

Server server = NettyServerBuilder.forPort(9090)
    .sslContext(serverSslContext)
    .addService(new MyServiceImpl())
    .build();

Architecture

gRPC Netty is built around several key components:

  • Transport Layer: Netty-based HTTP/2 implementation providing the communication foundation
  • Builder Pattern: Fluent API through NettyChannelBuilder and NettyServerBuilder for configuration
  • SSL/TLS Integration: Deep integration with Netty's SSL contexts and gRPC's security requirements
  • Protocol Negotiation: Support for various HTTP/2 negotiation strategies (TLS ALPN, plaintext upgrade)
  • Performance Optimization: Advanced features like flow control, connection pooling, and native socket support

Capabilities

Client Transport

Client-side channel creation and configuration for connecting to gRPC servers. Provides comprehensive control over connection parameters, SSL/TLS settings, and performance tuning.

public static NettyChannelBuilder forAddress(String host, int port);
public static NettyChannelBuilder forAddress(SocketAddress serverAddress);
public static NettyChannelBuilder forTarget(String target);

Client Transport

Server Transport

Server-side configuration for accepting gRPC connections. Offers fine-grained control over server behavior, connection limits, and transport-specific optimizations.

public static NettyServerBuilder forPort(int port);
public static NettyServerBuilder forAddress(SocketAddress address);
public NettyServerBuilder addListenAddress(SocketAddress listenAddress);

Server Transport

SSL/TLS Configuration

Comprehensive SSL/TLS support with utilities for creating properly configured SSL contexts for gRPC communication, including ALPN negotiation and certificate management.

public static SslContextBuilder forClient();
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile);
public static SslContextBuilder configure(SslContextBuilder builder);

SSL/TLS Configuration

Protocol Negotiation

HTTP/2 protocol negotiation strategies for different deployment scenarios, from TLS ALPN to plaintext upgrades and direct HTTP/2 connections.

public enum NegotiationType {
    TLS, PLAINTEXT_UPGRADE, PLAINTEXT
}

Protocol Negotiation

Socket Support

Low-level socket information access and native optimization features for advanced performance tuning and monitoring.

public static NativeSocketOptions getNativeSocketOptions(Channel ch);

Socket Support

Common Patterns

Production Server Configuration

Server server = NettyServerBuilder.forPort(9090)
    .addService(new MyServiceImpl())
    .maxConcurrentCallsPerConnection(1000)
    .maxInboundMetadataSize(8192)
    .keepAliveTime(30, TimeUnit.SECONDS)
    .keepAliveTimeout(5, TimeUnit.SECONDS)
    .maxConnectionIdle(60, TimeUnit.SECONDS)
    .build();

High-Performance Client

ManagedChannel channel = NettyChannelBuilder.forAddress("server.example.com", 443)
    .sslContext(sslContext)
    .keepAliveTime(30, TimeUnit.SECONDS)
    .keepAliveTimeout(5, TimeUnit.SECONDS)
    .keepAliveWithoutCalls(true)
    .maxInboundMetadataSize(4096)
    .build();

Types

Core Types

// From io.grpc package
interface ChannelCredentials {}
interface ServerCredentials {}
class ManagedChannel {}
class Server {}

// From io.netty.channel package  
interface Channel {}
interface ServerChannel {}
interface ChannelFactory<T extends Channel> {}
interface EventLoopGroup {}
class ChannelOption<T> {}

// From io.netty.handler.ssl package
class SslContext {}
class SslContextBuilder {}
enum SslProvider { OPENSSL, JDK }

// From java.net package
interface SocketAddress {}

// From java.util.concurrent package
enum TimeUnit { NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS }

Netty-Specific Types

// From io.grpc.netty package
enum NegotiationType { TLS, PLAINTEXT_UPGRADE, PLAINTEXT }

class NettyChannelBuilder.LocalSocketPicker {
    @Nullable
    public SocketAddress createSocketAddress(SocketAddress remoteAddress, Attributes attrs);
}

class NettySocketSupport.NativeSocketOptions {
    @Nullable
    public final TcpInfo tcpInfo;
    public final ImmutableMap<String, String> otherInfo;
}

Error Handling

gRPC Netty integrates with gRPC's standard error handling mechanisms. Transport-level errors are typically wrapped in StatusRuntimeException or StatusException and can be handled using standard gRPC error handling patterns.

Performance Considerations

  • Use connection pooling for high-throughput scenarios
  • Configure flow control windows based on your message sizes
  • Enable keep-alive for long-lived connections
  • Use native transport (epoll on Linux) for maximum performance
  • Configure appropriate thread pools for your workload