tessl/maven-io-grpc--grpc-core

Core gRPC library containing transport implementation, channel abstraction, load balancing, name resolution, and other fundamental gRPC functionalities for Java

—

Pending

Overview

Eval results

Files

Load Balancing and Name Resolution

Name: tessl/maven-io-grpc--grpc-core
Author: tessl

gRPC Core provides default implementations for load balancing and name resolution functionality. The pick-first load balancer is the default strategy, and DNS name resolution handles service discovery for gRPC clients.

Capabilities

Pick-First Load Balancer Provider

Default load balancer provider that implements the pick-first strategy.

/**
 * Provider for pick-first load balancing strategy
 * Located: io.grpc.internal.PickFirstLoadBalancerProvider
 */
class PickFirstLoadBalancerProvider extends LoadBalancerProvider {
    /**
     * Checks if this provider is available for use
     * @return true (always available)
     */
    @Override
    public boolean isAvailable() {
        return true;
    }
    
    /**
     * Gets the priority of this provider
     * @return 5 (standard priority for default providers)
     */
    @Override
    public int getPriority() {
        return 5;
    }
    
    /**
     * Gets the policy name for this load balancer
     * @return "pick_first" - used in service configuration
     */
    @Override
    public String getPolicyName() {
        return "pick_first";
    }
    
    /**
     * Creates a new pick-first load balancer instance
     * @param helper Helper providing access to channel functionality
     * @return PickFirstLoadBalancer instance
     */
    @Override
    public LoadBalancer newLoadBalancer(LoadBalancer.Helper helper) {
        return new PickFirstLoadBalancer(helper);
    }
    
    /**
     * Parses load balancing policy configuration
     * @param rawLoadBalancingPolicyConfig Raw configuration map
     * @return ConfigOrError with parsed configuration or error
     */
    @Override
    public ConfigOrError parseLoadBalancingPolicyConfig(
        Map<String, ?> rawLoadBalancingPolicyConfig
    ) {
        return ConfigOrError.fromConfig(new PickFirstConfig());
    }
}

Pick-First Load Balancer Implementation

Load balancer that connects to the first available server in the list.

/**
 * Pick-first load balancing implementation
 * Located: io.grpc.internal.PickFirstLoadBalancer
 */
class PickFirstLoadBalancer extends LoadBalancer {
    /**
     * Creates a new pick-first load balancer
     * @param helper Helper for accessing channel functionality
     */
    public PickFirstLoadBalancer(Helper helper);
    
    /**
     * Handles resolution result from name resolver
     * @param resolvedAddresses Result containing server addresses
     */
    @Override
    public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses);
    
    /**
     * Handles name resolution errors
     * @param error Status indicating the resolution error
     */
    @Override
    public void handleNameResolutionError(Status error);
    
    /**
     * Handles subchannel state changes
     * @param subchannel The subchannel that changed state
     * @param stateInfo New state information
     */
    @Override
    public void handleSubchannelState(Subchannel subchannel, ConnectivityStateInfo stateInfo);
    
    /**
     * Initiates shutdown of the load balancer
     */
    @Override
    public void shutdown();
    
    /**
     * Requests connection to be established
     */
    @Override
    public void requestConnection();
}

DNS Name Resolver Provider

Provider for DNS-based name resolution functionality.

/**
 * Provider for DNS-based name resolution
 * Located: io.grpc.internal.DnsNameResolverProvider
 */
class DnsNameResolverProvider extends NameResolverProvider {
    /**
     * Checks if DNS resolution is available
     * @return true if DNS resolution can be used
     */
    @Override
    public boolean isAvailable() {
        return true;
    }
    
    /**
     * Gets the priority of this provider
     * @return 5 (standard priority for default providers)
     */
    @Override
    public int getPriority() {
        return 5;
    }
    
    /**
     * Gets the default URI scheme handled by this provider
     * @return "dns" - the scheme for DNS-based name resolution
     */
    @Override
    public String getDefaultScheme() {
        return "dns";
    }
    
    /**
     * Creates a new DNS name resolver for the given target URI
     * @param targetUri The target URI to resolve (e.g., dns:///example.com:443)
     * @param args Arguments containing channel configuration
     * @return DnsNameResolver instance or null if URI is not supported
     */
    @Override
    public NameResolver newNameResolver(URI targetUri, NameResolver.Args args) {
        if (!"dns".equals(targetUri.getScheme())) {
            return null;
        }
        return new DnsNameResolver(targetUri, args);
    }
}

DNS Name Resolver Implementation

Resolves DNS names to IP addresses for gRPC connections.

/**
 * DNS name resolution implementation
 * Located: io.grpc.internal.DnsNameResolver
 */
class DnsNameResolver extends NameResolver {
    /**
     * Creates a new DNS name resolver
     * @param targetUri URI to resolve
     * @param args Resolution arguments
     */
    public DnsNameResolver(URI targetUri, Args args);
    
    /**
     * Gets the service authority for this resolver
     * @return Service authority string
     */
    @Override
    public String getServiceAuthority();
    
    /**
     * Starts name resolution with the given listener
     * @param listener Listener to receive resolution results
     */
    @Override
    public void start(Listener2 listener);
    
    /**
     * Shuts down the name resolver
     */
    @Override
    public void shutdown();
    
    /**
     * Refreshes the name resolution
     */
    @Override
    public void refresh();
}

Load Balancing Strategies

Pick-First Strategy

The pick-first load balancing strategy connects to the first available server:

Address Ordering: Servers are tried in the order provided by name resolution
Connection Attempt: Attempts connection to the first server in the list
Fallback: If connection fails, tries the next server in the list
Sticky Connection: Once connected, all RPCs use the same connection
Reconnection: If connection is lost, restarts the process from the beginning

Configuration:

{
  "loadBalancingPolicy": "pick_first"
}

Usage Example:

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

// Pick-first is the default load balancing policy
ManagedChannel channel = ManagedChannelBuilder
    .forTarget("dns:///example.com:443")
    .build();

// Explicitly specify pick-first policy
ManagedChannel channel2 = ManagedChannelBuilder  
    .forTarget("dns:///example.com:443")
    .defaultLoadBalancingPolicy("pick_first")
    .build();

Name Resolution

DNS Resolution Process

DNS name resolution converts domain names to IP addresses:

URI Parsing: Extracts hostname and port from target URI
DNS Query: Performs DNS lookup to resolve hostname to IP addresses
Address List: Returns list of resolved IP addresses with ports
Updates: Periodically refreshes DNS resolution to handle changes
Error Handling: Reports resolution failures to the load balancer

Supported URI Formats

// DNS scheme with explicit host and port
"dns:///example.com:443"

// DNS scheme with default port
"dns:///example.com"

// Implicit DNS (default scheme)
"example.com:443"

// IPv4 address with port
"192.168.1.100:443"

// IPv6 address with port
"[2001:db8::1]:443"

DNS Configuration

import io.grpc.NameResolverRegistry;
import io.grpc.internal.DnsNameResolverProvider;

// DNS resolver is automatically registered via SPI
// Manual registration (not typically needed):
NameResolverRegistry.getDefaultRegistry()
    .register(new DnsNameResolverProvider());

Advanced Load Balancing

Custom Load Balancer Integration

While pick-first is the default, gRPC Core's architecture supports custom load balancers:

// Custom load balancer provider
public class CustomLoadBalancerProvider extends LoadBalancerProvider {
    @Override
    public boolean isAvailable() {
        return true;
    }
    
    @Override
    public int getPriority() {
        return 10; // Higher priority than default
    }
    
    @Override
    public String getPolicyName() {
        return "custom_policy";
    }
    
    @Override
    public LoadBalancer newLoadBalancer(Helper helper) {
        return new CustomLoadBalancer(helper);
    }
}

Service Configuration

Load balancing can be configured via service configuration:

{
  "loadBalancingConfig": [
    {
      "pick_first": {}
    }
  ],
  "methodConfig": [
    {
      "name": [
        {
          "service": "example.Service"
        }
      ],
      "timeout": "30s"
    }
  ]
}

Error Handling and Resilience

Load Balancer Error Handling

Connection Failures: Load balancer tries alternative servers
Service Unavailable: Reports appropriate status to clients
Network Partitions: Handles temporary connectivity issues
Address Updates: Adapts to changes in server addresses

Name Resolution Error Handling

DNS Failures: Reports resolution errors to load balancer
Network Issues: Retries DNS queries with exponential backoff
Invalid Addresses: Filters out unreachable or invalid addresses
Cache Management: Uses cached results when resolution fails

Example Error Handling:

// Load balancer handles resolution errors
@Override
public void handleNameResolutionError(Status error) {
    if (subchannel != null) {
        subchannel.shutdown();
        subchannel = null;
    }
    
    // Report error to channel
    helper.updateBalancingState(TRANSIENT_FAILURE, 
        new ErrorPicker(error));
}

Performance Considerations

Load Balancing Performance

Connection Reuse: Pick-first maintains single connection per target
Lazy Connection: Connections established only when needed
Health Checking: Optional health checking for server availability
Flow Control: Respects gRPC flow control mechanisms

Name Resolution Performance

DNS Caching: Results cached to reduce DNS queries
Resolution Frequency: Configurable refresh intervals
Parallel Resolution: Multiple addresses resolved concurrently
IPv6 Support: Handles both IPv4 and IPv6 addresses efficiently

Install with Tessl CLI

npx tessl i tessl/maven-io-grpc--grpc-core

docs

buffer-management.md

builders-factories.md

core-utilities.md

index.md

load-balancing-name-resolution.md

service-providers.md

transport-layer.md

tile.json