v1.34.0

November 28, 2025

🌟 New features

Model Context Protocol (MCP) Server: You can now build MCP services on top of Armeria using the armeria-ai-mcp module. #6513 #6492

// Create an MCP server transport
var transport =
      ArmeriaStreamableServerTransportProvider
              .builder()
              .jsonMapper(...)
              .contextExtractor(...)
              .build();
// Build the MCP server with your tools and resources
McpServer mcpServer = McpServer.async(transport)
                               .tools(myTool)
                               .resources(myResource)
                               .build();
// Serve MCP via Armeria
Server server =
  Server.builder()
        .service("/mcp/message", transport.httpService()) // 👈👈👈
        .build();

Retry Limiting: You can now limit retry requests using RetryLimiter to prevent system overload during prolonged service degradation. #6409

RetryRule rule = ...
RetryConfig config =
  RetryConfig.builder(rule)
             .retryLimiter(RetryLimiter.concurrencyLimiting(3)) // 👈👈👈
             .build();
var retryingClient = RetryingClient.newDecorator(config);

JSON-RPC 2.0 Protocol Support: You can now build JSON-RPC services using the armeria-jsonrpc module. #6504 #6487 #6289

JsonRpcService jsonRpcService = JsonRpcService
      .builder()
      .methodHandler("echo", (ctx, req) -> {
          // handle the request
      })
      .build();

ServerBuilder sb = Server
      .builder()
      .service("/json-rpc", jsonRpcService); // 👈👈👈

Support for Multipart Requests with Duplicate Names: You can now handle multipart requests that contain multiple parts with the same form field name. #6419 #6430
```
@Post("/upload")
public void upload(@Param("file") List<MultipartFile> files) { // 👈👈👈
  ...
}
```

AnnotatedService with JSpecify: You can now use AnnotatedService with JSpecify's @Nullable annotations. #6454 #6457

public class MyAnnotatedService {
  @Get("/hello")
  public String hello(@org.jspecify.annotations.Nullable String value) {
      ...
  }
}

HTTP Compression Algorithm Control: You can now configure which compression algorithms to use with EncodingService. #6390 #6398

EncodingService encodingService =
  EncodingService.builder()
                 .encoderFactories( // 👈👈👈
                   StreamEncoderFactories.GZIP,
                   StreamEncoderFactories.DEFLATE,
                   new MyCustomBrotliEncoderFactory())
                 .build();

Athenz Authentication Metrics: armeria-athenz exports metrics of your Athenz-secured services by default. #6423 #6517

You may also configure the metrics:

var ztsBaseClient =
      ZtsBaseClient.builder(ztsUri)
                   .enableMetrics(meterRegistry, meterIdPrefixFunction) // 👈👈👈
                   ...
                   .build();
// For services
var decoratorFactory = AthenzServiceDecoratorFactory
        .builder(ztsBaseClient)
        .meterIdPrefix(myMeterIdPrefix) // 👈👈👈
        ...
        .build();
// For clients
var athenzClient = AthenzClient
      .builder(ztsBaseClient)
      .meterIdPrefix(myMeterIdPrefix) // 👈👈👈
      ...
      .newDecorator();

Multipart File Upload Encoding Configuration: You can now configure how multipart filenames are decoded. #6465
- Use -Dcom.linecorp.armeria.defaultMultipartFilenameDecodingMode with utf_8, iso_8859_1, or url_decoding.

SAML RelayState Length Configuration: You can now configure the maximum length for SAML RelayState parameters. #6381

SamlServiceProvider sp =
  SamlServiceProvider
      .builder()
      .relayStateMaxLength(256) // 👈👈👈 Default is 80
      ...

Easier Certificate Chain Testing: You can now use SignedCertificateExtension to generate certificate chains. #6519

  @Order(1)
  @RegisterExtension
  static var caCert = new SelfSignedCertificateExtension();

  @Order(2)
  @RegisterExtension
  static var leafCert = new SignedCertificateExtension(caCert);

📈 Improvements

Comprehensive improvements to the armeria-xds module. #6470 #6469 #6468 #6474 #6475 #6403 #6366 #6461
- Improved logs and metrics for better observability.
- protoc-gen-validate is applied for all xDS resources by default.
- Support for Envoy's RetryPolicy has been added.
- You may adjust stacktrace generation for CancelledSubscriptionException using verboseExceptionSampler. #6525

🛠️ Bug fixes

ServiceRequestContext validation has been improved to avoid false-positive exceptions. #6420 #6479
- Pushing a ServiceRequestContext-based RequestContext to a thread that does not already have a ServiceRequestContext no longer emits an IllegalStateException.
Resolved duplicate decorator registration in ZtsBaseClient when using ArmeriaAutoConfiguration. #6424
ContentPreviewerFactory no longer unnecessarily logs content for binary types. #6485
Trailers-only gRPC responses no longer include incorrect Content-Length headers #6511
A closing WebSocket session no longer sends an unnecessary RST_STREAM frame. #6375
RejectedRouterHandler.FAIL correctly throws an exception when duplicate routes are detected. #6498 #6499
JSON formatting has been fixed in the DocService debug console. #6434
DocService no longer sends Content-Type headers for HTTP methods that don't have request bodies. #6442
A warning log is no longer emitted for certificates missing both a Subject Alternative Name (SAN) and a Common Name (CN). #6477
armeria-logback's MDC export works correctly when -Dcom.linecorp.armeria.warnNettyVersions is set to false. #6428

☢️ Breaking changes

The default decoding mode for multipart request filenames is now UTF-8 instead of ISO-8859-1.
- For the previous behavior, set the system property -Dcom.linecorp.armeria.defaultMultipartFilenameDecodingMode=iso_8859_1. #6465
Dropwizard 1.x integration is no longer supported. #6515