DOCSEARCHbyAlgolia
Submit Docs

Armeria Documentation

repository·main·Indexed 26 days ago

https://github.com/line/armeria

Armeria is a reactive microservice framework for building high-performance microservices that support multiple protocols, including gRPC, Thrift, and HTTP/2. The project includes a DocService web client and a comprehensive Gradle-based build system for managing multi-project Java setups, dependency catalogs via dependencies.toml, and benchmarking tools using ghz and JMH.

Tokens
167.6K
Snippets
399
Records
550
Agent score
88%

What's inside Armeria

  1. Overview of Armeria microservice framework

    main
    Armeria is a reactive microservice framework designed to build microservices using various technologies. It supports protocols and frameworks such as gRPC, Thrift, Kotlin, Retrofit, Reactive Streams, Spring Boot, and Dropwizard. It is open-sourced by the creators of Netty and LINE Corporation.

  2. Overview of Armeria features

    main

    Armeria is a microservice framework designed to support various technologies including gRPC, Thrift, Kotlin, Retrofit, Reactive Streams, Spring Boot, and Dropwizard.

    Key capabilities include:

    • HTTP/2 Support: Supports both TLS and cleartext, protocol upgrades (preface and traditional HTTP/1 upgrade), and integrated PROXY protocol support for load balancers like HAProxy and AWS ELB.
    • gRPC and Thrift Integration: Run existing gRPC or Thrift implementations without modification. Supports gRPC-Web and various protocol combinations (gRPC/Thrift over HTTP/1 or HTTP/2).
    • Microservice Essentials: Provides metrics, circuit breakers, client-side health-checks, load-balancing, service discovery (DNS, ZooKeeper), and distributed tracing via Zipkin.
    • Interactive Debugging: Includes DocService for browsing RPC operations and invoking them via a web form.
    • Asynchronous/Reactive Architecture: Built on Reactive Streams and Java 8 CompletableFuture with asynchronous connection pooling and domain name resolution.
    • Java EE Compatibility: Can run Java EE applications (like Spring Boot) on the same TCP/IP port, enabling them to speak HTTP/2.
    • Linux Performance: Optimized via JNI-based socket I/O and BoringSSL-based TLS connections.

  3. Overview of Armeria gRPC features

    main

    Armeria extends standard gRPC-Java capabilities by supporting additional protocols and serialization formats. Key features include:

    Supported Protocols

    • HTTP/1.1
    • HTTP/2

    Supported Serialization Formats

    Framed:

    • gRPC protobuf: application/grpc+proto
    • gRPC JSON: application/grpc+json
    • gRPC Web: application/grpc-web+proto
    • gRPC Web JSON: application/grpc-web+json
    • gRPC Web Text: application/grpc-web-text+proto

    Unframed:

    • Protobuf: application/protobuf
    • JSON: application/json

    Additional Capabilities

    • HTTP level decorators for gRPC services
    • Richer error handling
    • HTTP-to-JSON transcoding
    • Customizing service method paths
    • gRPC documentation service
    • gRPC status monitoring with MetricCollectingService

  4. Understand Armeria's xDS proxyless approach

    main

    Armeria provides a proxyless implementation of the xDS APIs. Unlike a traditional service mesh that uses a sidecar proxy (like Envoy) to intercept traffic, Armeria's xDS module implements the data plane directly within the application's networking framework.

    Key Characteristics of Proxyless Armeria:

    • Direct request path: Requests do not traverse separate client-side or server-side proxy processes, potentially reducing latency.
    • No traffic-interception infrastructure: Works on containers, VMs, or bare metal without requiring sidecar injection or transparent redirection.
    • Reduced overhead: Avoids the memory and CPU costs of running an additional proxy process per instance.
    • Deployment: The data-plane implementation is versioned and deployed as an application dependency rather than a separate fleet.

    Trade-offs to consider:

    • Framework dependency: Requires xDS support within the application's runtime (Armeria provides this for HTTP, gRPC, and Thrift).
    • Release coupling: Upgrading the data-plane implementation requires redeploying the application.
    • Feature subset: A proxyless implementation may support fewer Envoy resources, fields, and filters compared to a full Envoy sidecar.

  5. Key Armeria features and API updates

    main

    Recent versions of Armeria have introduced several significant features:

    • HTTP/JSON-to-gRPC transcoding: Enables transcoding similar to Google's approach without requiring an API gateway server.
    • GraphQL support: Integration with GraphQL Java and Sangria.
    • Immutable Cookie API: A redesigned Cookie type focused on usability.
    • OAuth 2.0: A fully asynchronous module.
    • Reactive multipart streaming: A new API for multipart streaming.
    • WebClient Redirects: WebClient can now follow redirects using highly customizable redirect rules.
    • Stream Transformation: New APIs such as map, concat, recover, and collect for stream manipulation.
    • Dynamic Reconfiguration: Use Server#reconfigure() to reconfigure servers dynamically.
    • Scala Integration: Native support for Scala developers.

  6. Understand the xDS Threading Model

    main

    Armeria separates xDS resource management from request processing using two distinct thread types to ensure that updates do not block the request path:

    1. xDS Event Loop: By default, a single dedicated thread named xds-common-worker handles all communication with the control plane, resource parsing, and snapshot updates. This thread is shared across all XdsBootstrap instances. You can provide a custom executor via the builder.
    2. Application Thread: Request processing (filter execution, routing, load balancing) runs on the existing threads used by the client or server.

    Updates are passed via a thread-safe, lock-free handoff. When a new snapshot is published, it becomes visible to all subsequent requests immediately.

  7. Understand xDS Snapshots

    main

    A snapshot is an immutable, point-in-time view of the xDS resource tree (comprising ListenerSnapshot, RouteSnapshot, ClusterSnapshot, and EndpointSnapshot).

    Snapshots provide the following guarantees:

    • Complete: A snapshot is only published once all dependent resources (routes, clusters, endpoints) are fully resolved.
    • Error-free: If any resource in the tree fails to load, the snapshot is not published, and the application continues using the last successful snapshot.
    • Immutable: Once published, a snapshot never changes and can be read on any thread without synchronization.

  8. New features in Armeria 1.24.0 to 1.26.4

    main

    Recent versions of Armeria (between 1.24.0 and 1.26.4) introduced several key features:

    • WebSocket support: Native support for WebSocket protocols.
    • Unix domain socket support: Ability to use Unix domain sockets for communication.
    • GraalVM native image configuration: Out-of-the-box support for building native images using GraalVM.
    • gRPC Richer Error Model support: Support for enhanced error reporting in gRPC using GoogleGrpcExceptionHandlerFunction.

  9. Understand the Armeria Threading Model

    main

    Armeria uses a non-blocking I/O model based on Netty. Understanding the different thread pools is critical to prevent performance degradation and deadlocks caused by blocking the event loop.

    Thread Pool Roles

    PoolPurposeThread Name PatternDefault Size
    bossGroupAccepts incoming TCP connections (1 per server port).armeria-boss-{protocol}-{addr}1 per port
    workerGroupHandles socket I/O (reads/writes) and non-blocking service logic.armeria-common-worker-*2 * CPU cores (NIO/epoll/kqueue) or CPU cores (io_uring)
    serviceWorkerGroup(Optional) Dedicated EventLoopGroup for service execution to isolate logic from socket I/O.User-definedFalls back to workerGroup
    blockingTaskExecutorRuns long-running or blocking operations (DB, File I/O, sync APIs).armeria-common-blocking-tasks-*200

    Request Flow

    1. bossGroup: Accepts TCP connection and hands it to workerGroup.
    2. workerGroup: Reads bytes and decodes frames.
    3. Execution:
      • Non-blocking service: Runs directly on the event loop thread.
      • @Blocking / useBlockingTaskExecutor(true): Dispatched to blockingTaskExecutor.
      • serviceWorkerGroup configured: Service runs on a dedicated event loop.

  10. Understand Armeria xDS Architecture

    main

    Armeria implements the xDS protocol directly within the application, eliminating the need for a sidecar proxy. The architecture consists of two main layers managed by a Control Plane:

    • xDS Inbound (XdsServerPlugin): Manages incoming connections, including mTLS, filter chains, and HTTP filter policies.
    • xDS Outbound (Preprocessor): Manages outgoing requests, including endpoint discovery, load balancing, retries, timeouts, and mTLS.

    Both layers receive configuration from the control plane at runtime, allowing for policy updates without application redeployment.

  11. xDS Server Lifecycle and Ordering

    main

    Startup Behavior

    The server blocks during startup until the first complete xDS snapshot arrives. The default timeout is 30 seconds. If a subsequent update fails, the last successful snapshot remains active.

    Connection-time Binding

    Filter chains (including TLS config and HTTP filter decorators) are determined at the moment of connection establishment. Once a connection is established, it maintains that policy for its entire lifetime, even if the xDS snapshot updates. New connections will use the latest snapshot.

    Decorator Ordering

    xDS decorators are the outermost layer. The execution order is: [xDS filters] → [user's service decorators] → service

  12. Understand Armeria's Thread Pool Architecture

    main

    Armeria uses four distinct thread pools to manage I/O and service execution. Understanding these roles is critical to avoid blocking event loop threads, which can cause latency and deadlocks.

    PoolRoleDefault Size
    bossGroupAccepts incoming TCP connections (one per server port)1 per port
    workerGroupHandles socket I/O and non-blocking service logic2 × CPU cores
    serviceWorkerGroup(Optional) Dedicated event loop group for service execution to isolate logic from socket I/OUser-defined (falls back to workerGroup)
    blockingTaskExecutorRuns blocking operations (DB calls, file I/O, legacy sync APIs)200 threads