Skip to content

Latest commit

 

History

History
283 lines (246 loc) · 16.7 KB

advanced-dropwizard-integration.mdx

File metadata and controls

283 lines (246 loc) · 16.7 KB
Raw

import versions from '../../../gen-src/versions.json';

Using Armeria with Dropwizard

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:

<RequiredDependencies boms={[ { groupId: 'com.linecorp.armeria', artifactId: 'armeria-bom' }, { groupId: 'io.dropwizard', artifactId: 'dropwizard-bom', version: ${versions['io.dropwizard:dropwizard-core']}, }, ]} dependencies={[ { groupId: 'com.linecorp.armeria', artifactId: '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 type://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);
    }
}

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

Server Properties

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 type://ServerBuilder before being passed to the type://ArmeriaBundle.

+-----------------------------------+---------------------------------------+-------------------------------------------------+ |

Path
|
Property
| Description | +===================================+=======================================+=================================================+ | server | jerseyEnabled | Whether to enable JAX-RS resources defined by | | | | Dropwizard (default: true) | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | maxRequestLength | The default server-side maximum length of | | | | a request | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | maxNumConnections | The maximum allowed number of open connections | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | dateHeaderEnabled | Whether to include default "Data" header | | | | in the response header (default: true) | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | serverHeaderEnabled | Whether to include default "Server" header | | | | in the response header (default: false) | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | verboseResponses | Whether the verbose response mode is enabled | | | | (default: false) | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | defaultHostname | The default hostname of the default | | | | type://VirtualHostBuilder | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | gracefulShutdownQuietPeriodMillis | The number of milliseconds to wait after the | | | | last processed request to be considered safe | | | | for shutdown | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server | gracefulShutdownTimeoutMillis | The number of milliseconds to wait after going | | | | unhealthy before forcing the server to shutdown | | | | regardless of if it is still processing requests| +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server.ports | port | The port to run the server on (default: 8080) |

  •                               +---------------------------------------+-------------------------------------------------+

| | ip | The IP address to bind to |

  •                               +---------------------------------------+-------------------------------------------------+

| | iface | The network interface to bind to | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server.compression | enabled | Whether to enable the HTTP content encoding | | +---------------------------------------+-------------------------------------------------+ | | mimeTypes | The MIME Types of an HTTP response which are | | | | applicable for the HTTP content encoding | | +---------------------------------------+-------------------------------------------------+ | | excludedUserAgents | The "User-Agent" header values which are not | | | | applicable for the HTTP content encoding | | +---------------------------------------+-------------------------------------------------+ | | minResponseSize | The minimum bytes for encoding the content of | | | | an HTTP response | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server.ssl | enabled | Whether to enable SSL support | | +---------------------------------------+-------------------------------------------------+ | | keyAlias | The alias that identifies the key in | | | | the key store | | +---------------------------------------+-------------------------------------------------+ | | keyStore | The path to the key store that holds the SSL | | | | certificate (typically a jks file) | | +---------------------------------------+-------------------------------------------------+ | | keyStorePassword | The password used to access the key store | | +---------------------------------------+-------------------------------------------------+ | | trustStore | The trust store that holds SSL certificates | | +---------------------------------------+-------------------------------------------------+ | | trustStorePassword | The password used to access the trust store | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server.http1 | maxChunkSize | The maximum length of each chunk in an HTTP/1 | | | | response content | | +---------------------------------------+-------------------------------------------------+ | | maxInitialLineLength | The maximum length of an HTTP/1 response | | | | initial line | +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server.http2 | initialConnectionWindowSize | The initial connection-level HTTP/2 flow control| | | | window size | | +---------------------------------------+-------------------------------------------------+ | | initialStreamingWindowSize | The initial stream-level HTTP/2 flow control | | | | window size | | +---------------------------------------+-------------------------------------------------+ | | maxFrameSize | The maximum size of HTTP/2 frame that can be | | | | received | | +---------------------------------------+-------------------------------------------------+ | | maxStreamsPerConnection | The maximum number of concurrent streams per | | | | HTTP/2 connection. Unset means there is no limit| | | | on the number of concurrent streams | | +---------------------------------------+-------------------------------------------------+ | | maxHeaderListSize | The maximum size of headers that can be received| +-----------------------------------+---------------------------------------+-------------------------------------------------+ | server.accessLog | type | The access log type that is supposed to be one | | | | of "common", "combined" or "custom" | | +---------------------------------------+-------------------------------------------------+ | | format | The 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 type://AccessLogWriter is type://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..."