Spring Cloud Gateway에서 발생한 UnsupportedOperationException

문제 상황

초기 구현 코드

@Component
public class JwtIssuanceGlobalFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = generateJwtToken();

        ServerHttpRequest modifiedRequest = exchange.getRequest()
                .mutate()
                .header("Authorization", "Bearer " + token)
                .build();

        ServerWebExchange modifiedExchange = exchange.mutate()
                .request(modifiedRequest)
                .build();

        return chain.filter(modifiedExchange);
    }
}

발생한 에러

java.lang.UnsupportedOperationException: null

원인 분석

• Cloud Gateway 4.1.5 with Spring Boot 3.3.5: mutated request cannot change request headers

• HttpHeaders.writeableHttpHeaders(new HttpHeaders(readOnlyHttpHeaders)) is not writeable

header()

/**
 * Set or override the specified header values under the given name.
 * <p>If you need to add header values, remove headers, etc., use
 * {@link #headers(Consumer)} for greater control.
 * @param headerName the header name
 * @param headerValues the header values
 * @since 5.1.9
 * @see #headers(Consumer)
 */
Builder header(String headerName, String... headerValues);

근본 원인: ReadOnlyHttpHeaders

@Test
void writeHttpHeadersWhenNewHttpHeadersFails() {
    HttpHeaders originalExchangeHeaders = HttpHeaders.readOnlyHttpHeaders(new HttpHeaders());
    HttpHeaders firewallHeaders = new HttpHeaders(originalExchangeHeaders);
    HttpHeaders writeable = HttpHeaders.writableHttpHeaders(firewallHeaders);
    writeable.set("test", "this"); // UnsupportedOperationException 발생
}

Spring Security와 Spring Cloud Gateway의 충돌

1. *Spring Security 6.0+**에서 StrictServerWebExchangeFirewall이 보안 강화를 위해 HttpHeaders를 읽기 전용으로 래핑합니다.

2. Spring Framework 6.0 이전 버전에서 HttpHeaders.writableHttpHeaders() 메서드가 중첩된 읽기 전용 헤더를 제대로 처리하지 못했습니다.

3. 결과적으로 Builder 내부로 넘어온 HttpHeaders는 사실상 "읽기 전용" 상태가 되어, header() 메서드나 headers(Consumer<HttpHeaders>) 방식 모두 UnsupportedOperationException을 발생시켰습니다.

해결 과정

1차 시도: Workaround 적용 (실패)

@Bean
@Order(Ordered.HIGHEST_PRECEDENCE)
WebFilter writeableHeaders() {
    return (exchange, chain) -> {
        // 원본 요청의 헤더를 복사하여 수정 가능한(writable) 헤더 객체를 생성
        HttpHeaders writeableHeaders = HttpHeaders.writableHttpHeaders(
                exchange.getRequest().getHeaders());

        // 기존 요청 객체를 래핑
        // getHeaders() 메서드만 오버라이드하여 수정 가능한 헤더를 반환
        ServerHttpRequestDecorator writeableRequest = new ServerHttpRequestDecorator(
                exchange.getRequest()) {
            @Override
            public HttpHeaders getHeaders() {
                return writeableHeaders;
            }
        };

        ServerWebExchange writeableExchange = exchange.mutate()
            .request(writeableRequest)
            .build();

        return chain.filter(writeableExchange);
    };
}

2차 시도: 버전 변경 (성공)

// 이전 버전
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.11'
    id 'io.spring.dependency-management' version '1.1.4'
}

ext {
    springCloudVersion = '2023.0.3'
}

// 변경 후 버전
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.12'
    id 'io.spring.dependency-management' version '1.1.7'
}

ext {
    springCloudVersion = '2023.0.3'
}

최종 해결 코드

@Component
@RequiredArgsConstructor
@Slf4j
@Order(-50)
public class JwtIssuanceGlobalFilter implements GlobalFilter {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        return JwtStaticProvider
                .createAccToken("gateway")
                .flatMap(token -> {
                    HttpHeaders writableHeaders = HttpHeaders.writableHttpHeaders(
                            exchange.getRequest().getHeaders());

                    writableHeaders.set("Authorization", "Bearer " + token);

 
                    ServerHttpRequest modifiedRequest = new ServerHttpRequestDecorator(
                            exchange.getRequest()) {
                        @Override
                        public HttpHeaders getHeaders() {
                            return writableHeaders;
                        }
                    };

                    ServerWebExchange modifiedExchange = exchange.mutate()
                            .request(modifiedRequest)
                            .build();

                    return chain.filter(modifiedExchange);
                }).onErrorResume(error -> {
                    log.error("Failed to issue JWT token for : {}", error.getMessage());

                    return chain.filter(exchange);
                });
    }

}

왜 버전 변경이 필요했을까?

Spring Framework의 버그 수정

버전별 호환성

1. 버전 업그레이드: Spring Framework 6.1.15 버전 이상의 버전 세팅

2. 코드 패턴 변경: ServerHttpRequestDecorator를 사용한 헤더 재정의

요약

1. ServerHttpRequest.Builder의 header() 메서드는 헤더를 설정/덮어쓰도록 설계

2. 하지만 HttpHeaders.writableHttpHeaders()가 중첩된 읽기 전용 헤더를 제대로 언래핑하지 못하는 버그가 있음

3. Spring Security의 StrictServerWebExchangeFirewall과 Spring Cloud Gateway가 함께 사용될 때 이 문제가 발생

4. 버전 변경

참고 자료

• Spring Cloud Gateway Issues - UnsupportedOperationException

• Spring Framework Issue #33789

• Spring Security Issue #15989

• Spring Cloud 버전 호환성