Skip to main content

Using Armeria with Dropwizard

tip

Visit armeria-examples to find a fully working example.

Dropwizard provides many features which are necessary for building a web application, such as metrics, model validation, externalized and extensible configuration, etc. In addition, if your Dropwizard application integrates with Armeria, you can leverage the following:

  • Rich support for Apache Thrift and gRPC, including the fancy web console that enables you to send Thrift and gRPC requests from a web browser
  • Ability to run HTTP REST service and RPC service in the same port
  • Full HTTP/2 support for both server-side and client-side, including h2c (plaintext HTTP/2)
  • PROXY protocol support which provides interoperability with load balancers such as HAProxy and AWS ELB

Armeria can be plugged in as the underlying HTTP server for a Dropwizard application by adding the following dependency:

build.gradle
dependencies {
    implementation platform('com.linecorp.armeria:armeria-bom:1.34.1')
    implementation platform('io.dropwizard:dropwizard-bom:2.1.12')
    ...
    implementation 'com.linecorp.armeria:armeria-dropwizard2'
}

The above dependencies import a new ServerFactory for Dropwizard to run on by referring to the armeria type server in the Dropwizard configuration file. A user can customize the server configuration with the same properties provided by Dropwizard's SimpleServerFactory. The following is a simple example for configuring the server:

server:
  type: armeria
  applicationContextPath: /

For a user who wants to utilize Armeria, an ArmeriaBundle implementation must be added to the Application.

The user can further customize the server outside of the Configuration as follows:

public class DropwizardArmeriaApplication extends Application<DropwizardArmeriaConfiguration> {

    public static void main(final String[] args) throws Exception {
        new DropwizardArmeriaApplication().run(args);
    }

    @Override
    public void initialize(final Bootstrap<DropwizardArmeriaConfiguration> bootstrap) {
        final ArmeriaBundle bundle = new ArmeriaBundle() {
            @Override
            public void configure(final ServerBuilder builder) {
                // Customize the server using the given ServerBuilder. For example:
                builder.service("/armeria", (ctx, res) -> HttpResponse.of("Hello, Armeria!"));

                builder.annotatedService(new HelloService());

                // You can also bind asynchronous RPC services such as Thrift and gRPC:
                // builder.service(THttpService.of(...));
                // builder.service(GrpcService.builder()...build());
            }
        };
        bootstrap.addBundle(bundle);
    }
}
tip

If you are not familiar with Dropwizard, please refer to Dropwizard Getting Started Guide and Dropwizard User Manual.

Server Properties​

warning

Not all Dropwizard configurations can be passed into the Armeria server. Currently supported parameters are:

server:
  type: armeria
  gracefulShutdownQuietPeriodMillis: 5000
  gracefulShutdownTimeoutMillis: 40000
  maxRequestLength: 10485760
  maxNumConnections: 2147483647
  dateHeaderEnabled: true
  serverHeaderEnabled: false
  verboseResponses: false
  defaultHostname: 'host.name.com'
  ports:
    - port: 8080
      protocol: HTTP
    - ip: 127.0.0.1
      port: 8081
      protocol: HTTPS
    - port: 8443
      protocols:
        - HTTPS
        - PROXY
  compression:
    enabled: true
    mimeTypes:
      - text/*
      - application/json
    excludedUserAgents:
      - some-user-agent
      - another-user-agent
    minResponseSize: 1KB
  ssl:
    keyAlias: 'host.name.com'
    keyStore: 'classpath:keystore.jks'
    keyStorePassword: 'changeme'
    trustStore: 'classpath:truststore.jks'
    trustStorePassword: 'changeme'
  http1:
    maxChunkSize: 4096
    maxInitialLineLength: 4096
  http2:
    initialConnectionWindowSize: 1MB
    initialStreamWindowSize: 1MB
    maxFrameSize: 16384
    maxHeaderListSize: 8192
  proxy:
    maxTlvSize: 65319
  accessLog:
    type: common

Where defined, the Armeria ServerFactory will prefer Armeria's default properties over Dropwizard's. The following additional properties are able to be added to configure the ServerBuilder before being passed to the ArmeriaBundle.

Path
Property
Description
serverjerseyEnabledWhether to enable JAX-RS resources defined by Dropwizard (default: true)
servermaxRequestLengthThe default server-side maximum length of a request
servermaxNumConnectionsThe maximum allowed number of open connections
serverdateHeaderEnabledWhether to include default "Data" header in the response header (default: true)
serverserverHeaderEnabledWhether to include default "Server" header in the response header (default: false)
serververboseResponsesWhether the verbose response mode is enabled (default: false)
serverdefaultHostnameThe default hostname of the default VirtualHostBuilder
servergracefulShutdownQuietPeriodMillisThe number of milliseconds to wait after the last processed request to be considered safe for shutdown
servergracefulShutdownTimeoutMillisThe number of milliseconds to wait after going unhealthy before forcing the server to shutdown regardless of if it is still processing requests
server.portsportThe port to run the server on (default: 8080)
ipThe IP address to bind to
ifaceThe network interface to bind to
server.compressionenabledWhether to enable the HTTP content encoding
mimeTypesThe MIME Types of an HTTP response which are applicable for the HTTP content encoding
excludedUserAgentsThe "User-Agent" header values which are not applicable for the HTTP content encoding
minResponseSizeThe minimum bytes for encoding the content of an HTTP response
server.sslenabledWhether to enable SSL support
keyAliasThe alias that identifies the key in the key store
keyStoreThe path to the key store that holds the SSL certificate (typically a jks file)
keyStorePasswordThe password used to access the key store
trustStoreThe trust store that holds SSL certificates
trustStorePasswordThe password used to access the trust store
server.http1maxChunkSizeThe maximum length of each chunk in an HTTP/1 response content
maxInitialLineLengthThe maximum length of an HTTP/1 response initial line
server.http2initialConnectionWindowSizeThe initial connection-level HTTP/2 flow control window size
initialStreamingWindowSizeThe initial stream-level HTTP/2 flow control window size
maxFrameSizeThe maximum size of HTTP/2 frame that can be received
maxStreamsPerConnectionThe maximum number of concurrent streams per HTTP/2 connection. Unset means there is no limit on the number of concurrent streams
maxHeaderListSizeThe maximum size of headers that can be received
server.accessLogtypeThe access log type that is supposed to be one of "common", "combined" or "custom"
formatThe access log format string

Server Access Logs​

Armeria Server Access Logging <server-access-log> is enabled by default when using the Armeria Server. The default AccessLogWriter is AccessLogWriter.common(), but this can be changed via the following configuration.

common​

Use NCSA common log format.

server:
  type: armeria
armeria:
  accessLog:
    type: common

combined​

Use NCSA combined log format.

server:
  type: armeria
  accessLog:
    type: combined

custom​

Use your own log format. Refer to Customizing a log format for supported format tokens.

server:
  type: armeria
  accessLog:
    type: custom
    format: '...log format...'

Like Armeria?
Star us ⭐️

×