Armeria — Async Microservice Framework for Java and Kotlin

Introduction

Armeria is an open-source asynchronous HTTP/2 microservice framework developed by LINE Corporation. It allows you to serve and consume gRPC, Thrift, REST, and GraphQL services all on a single server and port, making it well-suited for polyglot microservice architectures on the JVM.

What Armeria Does

• Serves multiple RPC and REST protocols simultaneously on one port with automatic protocol detection
• Provides a fully asynchronous, non-blocking architecture built on Netty and Java CompletableFuture
• Includes built-in client-side load balancing with DNS, ZooKeeper, and Eureka service discovery
• Offers automatic API documentation via a built-in DocService web UI
• Supports decorators for cross-cutting concerns like logging, metrics, retries, and circuit breakers

Architecture Overview

Armeria is built on top of Netty and uses HTTP/2 as its primary transport. Incoming requests are demultiplexed based on content type and path to the appropriate protocol handler (gRPC, Thrift, REST, or GraphQL). The decorator pattern allows composable middleware-like behavior for both servers and clients. Thread pools are managed internally with an event loop model, and blocking operations can be offloaded to a configurable executor.

Self-Hosting & Configuration

• Add the armeria dependency via Gradle or Maven to any JVM project
• Use Server.builder() to configure services, ports, TLS, and access logs programmatically
• Integrate with Spring Boot via the armeria-spring-boot3-starter module
• Configure client-side load balancing with endpoint groups and health-check-based selection
• Enable TLS with ServerBuilder.tls() using certificate files or a KeyStore

Key Features

• Automatic HTTP/1.1 and HTTP/2 protocol negotiation with cleartext (h2c) support
• Built-in DocService that generates interactive API documentation for all registered services
• Request throttling, retries with backoff, and circuit breaker decorators out of the box
• Native Kotlin coroutine support for idiomatic async programming
• Distributed tracing integration with Brave (Zipkin) and Micrometer metrics

Comparison with Similar Tools

• Spring WebFlux — Reactive but HTTP-only; Armeria natively handles gRPC and Thrift alongside REST
• gRPC-Java — gRPC-only framework; Armeria serves gRPC and REST on the same port
• Vert.x — Polyglot event-driven toolkit; Armeria has stronger RPC protocol support
• Quarkus — GraalVM-focused with faster startup; Armeria has richer multi-protocol capabilities
• Micronaut — Compile-time DI framework; Armeria focuses more on protocol flexibility and observability

FAQ

Q: Can Armeria replace Spring Boot? A: Armeria can run standalone or integrate with Spring Boot. For pure microservices needing multi-protocol support, it can replace the embedded Tomcat/Netty in Spring.

Q: Does it support Kotlin? A: Yes. Armeria has first-class Kotlin coroutine support and a Kotlin DSL for server configuration.

Q: How does the multi-protocol support work? A: Armeria uses content-type sniffing and path-based routing to dispatch requests to the correct protocol handler, all over a single HTTP/2 connection.

Q: Is it production-ready? A: Yes. Armeria is used in production at LINE, serving billions of requests daily across their messaging platform.

Sources

• https://github.com/line/armeria
• https://armeria.dev/