CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-grpc--grpc-inprocess

High-performance in-process transport implementation for gRPC Java that enables direct communication between client and server within the same JVM process

Pending
Overview
Eval results
Files

server-builder.mddocs/

Server Building

The InProcessServerBuilder provides a fluent API for creating in-process servers that can be identified by name or address. It extends the standard gRPC server builder with in-process specific configurations and optimizations.

Capabilities

Factory Methods

Create server builders for different identification patterns.

/**
 * Create a server builder that will bind with the given name.
 * @param name the identity of the server for clients to connect to
 * @return a new builder
 */
public static InProcessServerBuilder forName(String name);

/**
 * Create a server builder which listens on the given address.
 * @param listenAddress The SocketAddress this server will listen on
 * @return a new builder
 */
public static InProcessServerBuilder forAddress(SocketAddress listenAddress);

/**
 * Generates a new server name that is unique each time.
 * @return a unique server name (UUID string)
 */
public static String generateName();

Usage Examples:

// Create named server
InProcessServerBuilder builder1 = InProcessServerBuilder.forName("my-service");

// Create server with socket address
InProcessSocketAddress address = new InProcessSocketAddress("service-name");
InProcessServerBuilder builder2 = InProcessServerBuilder.forAddress(address);

// Generate unique name for testing
String uniqueName = InProcessServerBuilder.generateName();
InProcessServerBuilder builder3 = InProcessServerBuilder.forName(uniqueName);

Metadata Configuration

Configure metadata size limits for the server.

/**
 * Sets the maximum size of metadata allowed to be received.
 * @param bytes the maximum size of received metadata
 * @return this builder
 * @throws IllegalArgumentException if bytes is non-positive
 */
public InProcessServerBuilder maxInboundMetadataSize(int bytes);

Executor Configuration

Configure custom executor services and deadline handling.

/**
 * Provides a custom scheduled executor service.
 * @param scheduledExecutorService the scheduled executor service to use
 * @return this builder
 */
public InProcessServerBuilder scheduledExecutorService(
    ScheduledExecutorService scheduledExecutorService);

/**
 * Provides a custom deadline ticker for creating incoming Deadlines.
 * Intended for unit tests that fake out the clock. DO NOT use in production.
 * @param ticker the deadline ticker to use
 * @return this builder
 */
public InProcessServerBuilder deadlineTicker(Deadline.Ticker ticker);

Unsupported Security Configuration

Security-related methods that are not supported for in-process transport.

/**
 * TLS is not supported in InProcessServer.
 * @param certChain certificate chain file
 * @param privateKey private key file
 * @return this builder
 * @throws UnsupportedOperationException always thrown
 */
public InProcessServerBuilder useTransportSecurity(File certChain, File privateKey);

Complete Usage Example:

import io.grpc.inprocess.InProcessServerBuilder;
import io.grpc.Server;
import java.util.concurrent.TimeUnit;

// Generate unique name for testing
String serverName = InProcessServerBuilder.generateName();

// Build and start server
Server server = InProcessServerBuilder.forName(serverName)
    .addService(new MyGrpcServiceImpl()) // Add your gRPC service implementations
    .addService(new AnotherServiceImpl())
    .maxInboundMetadataSize(8192) // Set metadata size limit
    .directExecutor() // Use direct executor for testing
    .build();

// Start the server
server.start();

// Server is now available for in-process connections using serverName

// Shutdown gracefully
server.shutdown();
try {
    if (!server.awaitTermination(5, TimeUnit.SECONDS)) {
        server.shutdownNow();
    }
} catch (InterruptedException e) {
    server.shutdownNow();
    Thread.currentThread().interrupt();
}

Testing Pattern:

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

public class MyServiceTest {
    private Server server;
    private Channel channel;
    private String serverName;

    @BeforeEach
    void setUp() throws Exception {
        // Generate unique server name for each test
        serverName = InProcessServerBuilder.generateName();
        
        // Create and start server
        server = InProcessServerBuilder.forName(serverName)
            .directExecutor()
            .addService(new MyServiceImpl())
            .build()
            .start();
        
        // Create client channel
        channel = InProcessChannelBuilder.forName(serverName)
            .directExecutor()
            .build();
    }

    @AfterEach
    void tearDown() throws Exception {
        if (channel instanceof ManagedChannel) {
            ((ManagedChannel) channel).shutdownNow();
        }
        if (server != null) {
            server.shutdownNow();
        }
    }

    @Test
    void testMyService() {
        MyServiceGrpc.MyServiceBlockingStub stub = 
            MyServiceGrpc.newBlockingStub(channel);
        
        MyResponse response = stub.myMethod(
            MyRequest.newBuilder().setMessage("test").build()
        );
        
        assertThat(response.getResult()).isEqualTo("expected");
    }
}

Error Handling

  • IllegalArgumentException - Thrown for invalid parameter values (non-positive metadata size, null arguments)
  • UnsupportedOperationException - Thrown when calling deprecated forPort() method or useTransportSecurity()
  • IOException - Can be thrown during server startup if name registration fails

Server Lifecycle

  1. Creation: Use factory methods to create builder
  2. Configuration: Set services, executors, and limits
  3. Build: Call build() to create server instance
  4. Start: Call start() to register server and accept connections
  5. Shutdown: Call shutdown() followed by awaitTermination() for graceful shutdown

Thread Safety

InProcessServerBuilder instances are not thread-safe during configuration. Each builder instance should be used by a single thread during the building phase. However, the resulting Server instances are fully thread-safe and can handle concurrent requests from multiple threads.

Performance Considerations

  • Use generateName() for test servers to avoid naming conflicts
  • The in-process transport automatically disables stats recording for optimal performance
  • Custom executor services can be shared across multiple servers for resource efficiency
  • Set appropriate metadata size limits to prevent excessive memory usage

Install with Tessl CLI

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

docs

channel-builder.md

index.md

server-builder.md

socket-addresses.md

tile.json