Call Context and Configuration

/**
 * Immutable context object for gRPC calls
 * Encapsulates channel, timeout, retry, and metadata configuration
 */
public final class GrpcCallContext implements ApiCallContext {
    /** Create a default call context */
    public static GrpcCallContext createDefault();
    
    /** Create context with specific channel and call options */
    public static GrpcCallContext of(Channel channel, CallOptions callOptions);
    
    /** Create context with credentials */
    public GrpcCallContext withCredentials(Credentials credentials);
    
    /** Create context with transport channel */
    public GrpcCallContext withTransportChannel(TransportChannel inputChannel);
    
    /** Create context with timeout duration */
    public GrpcCallContext withTimeoutDuration(Duration timeout);
    
    /** Create context with stream wait timeout */
    public GrpcCallContext withStreamWaitTimeoutDuration(Duration streamWaitTimeout);
    
    /** Create context with stream idle timeout */
    public GrpcCallContext withStreamIdleTimeoutDuration(Duration streamIdleTimeout);
    
    /** Create context with channel affinity for sticky routing */
    public GrpcCallContext withChannelAffinity(Integer affinity);
    
    /** Create context with extra headers */
    public GrpcCallContext withExtraHeaders(Map<String, List<String>> extraHeaders);
    
    /** Create context with retry settings */
    public GrpcCallContext withRetrySettings(RetrySettings retrySettings);
    
    /** Create context with retryable status codes */
    public GrpcCallContext withRetryableCodes(Set<StatusCode.Code> retryableCodes);
    
    /** Get the gRPC channel */
    public Channel getChannel();
    
    /** Get the call options */
    public CallOptions getCallOptions();
    
    /** Get timeout duration */
    public Duration getTimeoutDuration();
    
    /** Get the API tracer */
    public ApiTracer getTracer();
    
    /** Merge with another call context */
    public GrpcCallContext merge(ApiCallContext inputCallContext);
}

/**
 * gRPC-specific settings for creating callables
 * Contains method descriptor and parameter extraction configuration
 */
public class GrpcCallSettings<RequestT, ResponseT> {
    /** Create a new builder for call settings */
    public static <RequestT, ResponseT> Builder<RequestT, ResponseT> newBuilder();
    
    /** Create call settings with method descriptor */
    public static <RequestT, ResponseT> GrpcCallSettings<RequestT, ResponseT> 
        create(MethodDescriptor<RequestT, ResponseT> methodDescriptor);
    
    /** Get the gRPC method descriptor */
    public MethodDescriptor<RequestT, ResponseT> getMethodDescriptor();
    
    /** Get the request parameters extractor */
    public RequestParamsExtractor<RequestT> getParamsExtractor();
    
    /** Get the request mutator */
    public RequestMutator<RequestT> getRequestMutator();
    
    /** Check if should await response trailers */
    public boolean shouldAwaitTrailers();
    
    /** Create a builder from these settings */
    public Builder<RequestT, ResponseT> toBuilder();
}

/**
 * Builder for GrpcCallSettings with method and parameter configuration
 */
public static class GrpcCallSettings.Builder<RequestT, ResponseT> {
    /** Set the gRPC method descriptor */
    public Builder<RequestT, ResponseT> setMethodDescriptor(MethodDescriptor<RequestT, ResponseT> methodDescriptor);
    
    /** Set request parameters extractor for routing */
    public Builder<RequestT, ResponseT> setParamsExtractor(RequestParamsExtractor<RequestT> paramsExtractor);
    
    /** Set request mutator for modifying requests */
    public Builder<RequestT, ResponseT> setRequestMutator(RequestMutator<RequestT> requestMutator);
    
    /** Set whether to await response trailers */
    public Builder<RequestT, ResponseT> setAwaitTrailers(boolean awaitTrailers);
    
    /** Build the call settings */
    public GrpcCallSettings<RequestT, ResponseT> build();
}

/**
 * Utilities for managing gRPC CallOptions
 */
public class CallOptionsUtil {
    /** Put API tracer in call options */
    public static CallOptions putApiTracerInCallOptions(ApiTracer tracer, CallOptions options);
    
    /** Get API tracer from call options */
    public static ApiTracer getApiTracerFromCallOptions(CallOptions options);
}

/**
 * Extracts routing parameters from requests
 * Used for load balancing and routing decisions
 */
public interface RequestParamsExtractor<RequestT> {
    /** Extract routing parameters from request */
    Map<String, String> extract(RequestT request);
}

/**
 * Mutates requests before sending
 * Used for adding headers, authentication, or transforming data
 */
public interface RequestMutator<RequestT> {
    /** Mutate the request before sending */
    RequestT mutate(RequestT request);
}

/**
 * Call context constants and keys
 */
public final class GrpcCallContext {
    /** CallOptions key for API tracer */
    public static final CallOptions.Key<ApiTracer> TRACER_KEY;
}

import com.google.api.gax.grpc.GrpcCallContext;
import java.time.Duration;

// Create default context
GrpcCallContext context = GrpcCallContext.createDefault();

// Create context with timeout
GrpcCallContext contextWithTimeout = context
    .withTimeoutDuration(Duration.ofSeconds(30));

// Create context with retry settings
RetrySettings retrySettings = RetrySettings.newBuilder()
    .setInitialRetryDelay(Duration.ofMillis(100))
    .setMaxRetryDelay(Duration.ofSeconds(60))
    .setRetryDelayMultiplier(1.3)
    .setMaxAttempts(5)
    .build();

GrpcCallContext contextWithRetry = context
    .withRetrySettings(retrySettings)
    .withRetryableCodes(Set.of(StatusCode.Code.UNAVAILABLE, StatusCode.Code.DEADLINE_EXCEEDED));

import com.google.api.gax.grpc.GrpcCallContext;
import io.grpc.Channel;
import io.grpc.CallOptions;
import java.util.Map;
import java.util.List;

// Create context with channel and options
Channel channel = // ... your gRPC channel
CallOptions callOptions = CallOptions.DEFAULT
    .withDeadlineAfter(30, TimeUnit.SECONDS);

GrpcCallContext context = GrpcCallContext.of(channel, callOptions);

// Add extra headers
Map<String, List<String>> headers = Map.of(
    "x-custom-header", List.of("custom-value"),
    "x-request-id", List.of("req-12345")
);

GrpcCallContext contextWithHeaders = context
    .withExtraHeaders(headers)
    .withChannelAffinity(42); // For sticky routing

import com.google.api.gax.grpc.GrpcCallSettings;
import io.grpc.MethodDescriptor;

// Create method descriptor (typically generated)
MethodDescriptor<MyRequest, MyResponse> methodDescriptor = 
    // ... your method descriptor

// Create call settings
GrpcCallSettings<MyRequest, MyResponse> callSettings = 
    GrpcCallSettings.<MyRequest, MyResponse>newBuilder()
        .setMethodDescriptor(methodDescriptor)
        .setParamsExtractor(request -> {
            // Extract routing parameters
            return Map.of("project_id", request.getProjectId());
        })
        .setRequestMutator(request -> {
            // Add authentication or transform request
            return request.toBuilder()
                .setTimestamp(System.currentTimeMillis())
                .build();
        })
        .build();

import com.google.api.gax.grpc.GrpcCallContext;
import java.time.Duration;

// Configure context for streaming calls
GrpcCallContext streamingContext = GrpcCallContext.createDefault()
    .withStreamWaitTimeoutDuration(Duration.ofMinutes(5))
    .withStreamIdleTimeoutDuration(Duration.ofMinutes(2))
    .withTimeoutDuration(Duration.ofMinutes(10));

import com.google.api.gax.grpc.GrpcCallContext;

// Create base context
GrpcCallContext baseContext = GrpcCallContext.createDefault()
    .withTimeoutDuration(Duration.ofSeconds(30));

// Create override context
GrpcCallContext overrideContext = GrpcCallContext.createDefault()
    .withRetrySettings(retrySettings);

// Merge contexts (override takes precedence)
GrpcCallContext mergedContext = baseContext.merge(overrideContext);