Spring gRPC 1.1 Migration Guide

This document is meant to help you migrate your application to Spring gRPC 1.1.

Note	This is a preview draft of the migration guide. It will be completed when Spring gRPC 1.1 is released.

Server

Servlet Server

To use your servlet container as a gRPC server you must now explicitly set the server.http2.enabled property to true and include the required dependencies as the org.springframework.grpc:spring-grpc-server-web-spring-boot-starter no longer exists. Follow the steps in the Servlet Server section of the reference docs.

ServerInterceptorFilter and ServerServiceDefinitionFilter Beans

In Spring gRPC 1.0: * Applied to in-process servers * Not applied to regular servers

This is inconsistent with Spring Boot conventions.

Proposed approach: * Use GrpcServerFactoryCustomizer * Allow users to conditionally apply filters

Host/Port/Address Properties

Maintaining separate host/port properties has caused issues (e.g., Redis support).

Proposed approach: * Use only address

Example:

spring:
  grpc:
    server:
      address: "${my-grpc-host}:${my-grpc-port}"

Distinct GrpcServletRegistration Class

Spring Boot will introduce GrpcServletRegistration instead of using DynamicRegistrationBean.

Benefits: * Better auto-configuration control * Ability to stop configuration when existing beans are detected

Internal Condition and Auto-Configuration Updates

Changes include: * Consolidating auto-configuration classes * Replacing custom conditions

No expected user impact unless excluding configurations.

Property Restructuring

New server properties

spring:
  grpc:
    server:
      address: "*:9090"
      shutdown:
        grace-period: 30s
      inbound:
        message:
          max-size: 4m
        metadata:
          max-size: 8kb
      inprocess:
        name: "something"
      keepalive:
        time: 2h
        timeout: 20s
        permit:
          time: 5m
          without-calls: false
        connection:
          max-idle-time:
          max-age:
          grace-period: 30s
      ssl:
        enabled:
        client-auth: optional
        bundle: my-bundle
        secure: true
      servlet:
        enabled:
        validate-http2: true
      health:
        enabled:
        include-overall-health: true
        services:
          validate-membership: true
        service:
          <name>:
            include: *
            exclude:
        status:
          order:
          mapping:
            up: serving
            down: not-serving
        scheduler:
          enabled: true
          period: 5s
          delay: 5s

Previous server properties

spring:
  grpc:
    server:
      address: "*:9090"
      host:
      port:
      max-inbound-message-size:
      max-inbound-metadata-size:
      inprocess:
        name:
      keep-alive:
        time:
        timeout:
        max-idle:
        max-age:
        max-age-grace:
        permit-time:
        permit-without-calls:
      ssl:
        enabled:
        client-auth: optional
        bundle: my-bundle
        secure: true
      health:
        enabled:
        actuator:
          enabled:
          update-overall-health:
          update-rate:
          update-initial-delay:
          health-indicator-paths:

Client

Automatic Scanning

Original behavior: * Automatically scans .proto generated classes

Proposed approach: * Use @ImportGrpcClients

Anemic Properties

Current GrpcClientProperties contains logic (e.g., getChannel mutates state).

Proposed: * Keep properties simple (anemic) * Move logic to mapper classes

GrpcClientDefaultServiceConfigCustomizer

Problem: * Cannot merge multiple defaultServiceConfig customizers

Solution: * Introduce GrpcClientDefaultServiceConfigCustomizer * Allows mutation before final application

Service Config Properties

Problems with generic service-config:

• Poor relaxed binding support

• No type safety

• Conversion issues (e.g., durations)

Proposed: * Remove generic map * Use strongly typed configuration or customizers

Property Restructuring

New client properties

spring:
  grpc:
    client:
      channel:
        <name>:
          target:
          user-agent:
          bypass-certificate-validation:
          inbound:
            message:
              max-size:
            metadata:
              max-size:
          default:
            deadline:
            load-balancing-policy:
          idle:
            timeout:
          keepalive:
            time:
            timeout:
            without-calls: true
          health:
            enabled:
            service-name:

Previous client properties

spring:
  grpc:
    client:
      channels:
        <name>:
          address:
          default-deadline:
          default-load-balancing-policy:
          enable-keep-alive:
          health:
            enabled:
            service-name:
          idle-timeout:
          inherit-defaults:
          keep-alive-time:
          keep-alive-timeout:
          keep-alive-without-calls:
          max-inbound-message-size:
          max-inbound-metadata-size:
          negotiation-type:
          secure:
          service:config:
            <key>: <value>
          ssl:
          user-agent:
      default-channel:
      channel-defaults:
      defaultStubFactory:

Testing

Test Specific Factory Classes

Original approach: * Extend in-process factories

Problem: * Confusion with production customizers

Solution: * Introduce: * TestGrpcChannelFactory * TestGrpcServerFactory

Removal of ContextCustomizerFactory

• Remove InProcessTransportContextCustomizerFactory

• Simplify via property tweaks

Class Renames

• @AutoConfigureInProcessTransport → @AutoConfigureTestGrpcTransport

• @LocalGrpcPort → @LocalGrpcServerPort

Health Check

Removing Actuator Dependency

• Use core health indicator support

• Avoid actuator dependency

Scheduler Use

• Use shared task scheduler

• Align with Spring Integration

Observation

No significant changes.

Security

TBD

Other

TBD