armeria

Bug fixes

• #213 Fix a bug where some server-side default settings are not applied
• #214 Use Host header to populate serverName and serverPort, like Tomcat does
• #217 Support unicode-encoded path parts in TomcatService and fix JettyService to follow Servlet spec where request URI is decoded

Bug fixes

• #210 #212 Set serverPort of coyote request in addition to local port.
• #211 Add quotes to javaagent path.

Warning: This release contains a lot of breaking changes. Read this release note carefully.

New features

• #201 Make TomcatService support Tomcat 8.5
• #172 Revamp the API to support content streaming and to hide Netty API from Armeria public API
• Provide a way to decorate all services
  • Add ServerBuilder.decorator() that adds a decorator to all services in a server
  • Add VirtualHostBuilder.decorator() that adds a decorator too all services in a VirtualHost

Improvements

• #209 #202 Upgrade dependencies to their latest stable versions

Known issues

• Unlike the previous releases, the public API of this release is not fully documented yet.

Breaking changes since 0.20.2

Having trouble with migration? Please feel free to ask us questions by creating a new issue or joining our Slack channel.

TL;DR

If you did not extend any classes in Armeria, you may be able to migrate relatively easily.

1. Some methods will not return Netty Future anymore but CompletableFuture. e.g. Server.start() and stop()
2. Replace the references to ThriftService with THttpService.
3. Use HttpClient in favor of SimpleHttpClient.

If you implemented any interfaces or extended any types provided by Armeria or you still have issues with migration, please read on.

Use Reactive Streams API to support HTTP content streaming

Previously, Armeria buffered full request and response in memory. It means it was not able to consume or produce a stream of large content. It also could not start processing HTTP headers until the complete HTTP content is received, which may affect latency negatively.

We chose Reactive Streams API as the foundation of HTTP content streaming because it is the de-facto standard API for implementing object streaming these days; RxJava, gRPC, Akka and Project Reactor are the notable adoptors.

Please watch Roland Kuhn's slides to learn more about Reactive Streams.

Armeria defines a new interface called com.linecorp.armeria.common.reactivestreams.RichPublisher which adds a few useful operations on top of org.reactivestreams.Publisher and uses it wherever potentially large stream is expected. com.linecorp.armeria.common.http.HttpRequest and HttpResponse are good examples that extend RichPublisher<HttpObject>.

Armeria also provides an additional interface called com.linecorp.armeria.common.reactivestreams.Writer, which is useful when you write a hot (or active) publisher in a reactive way:

// Not OK: We will see OutOfMemoryError!
Writer<HttpObject> out = ...;
for (;;) {
  out.write(httpContent);
}
// OK: The callback we specified with onDemand() is executed only when
//     the subscriber has demanded more HttpObjects.
void produceTraffic(Writer<HttpObject> out) {
  out.write(httpContent);
  out.onDemand(() -> produceTraffic(out));
}
produceTraffic(out);

Refrain from exposing Netty API in Armeria's public API

• io.netty.util.concurrent.Future and Promise has been replaced with CompletableFuture.
• Armeria does not use the following types in its public API:
  • io.netty.buffer.ByteBuf
  • io.netty.handler.codec.http.HttpRequest, HttpResponse, HttpContent and many related message types
    • io.netty.handler.codec.http.HttpHeaders
    • io.netty.handler.codec.http.HttpHeaderNames' andHttpHeaderValues`
    • io.netty.handler.codec.http.HttpResponseStatus and HttpStatusClass
    • io.netty.handler.codec.http.FullHttpRequest and FullHttpResponse
    • See here for the complete list of the HTTP-related types introduced in this version.
• Armeria still uses Netty's AsciiString as header names because it's generic enough.

HTTP/2-centric HTTP API

Taking advantage of all the breaking changes introduced in this release, we designed our new HTTP API fit better with HTTP/2 than HTTP/1. Armeria will convert the inbound HTTP/1 messages to HTTP/2 automatically before they are served by your HTTP service or client implementation.

Redefine Client, Service and their context API

Previously, we shared one context type for both client and server side: ServiceInvocationContext. This is potentially confusing and both client and server sides had to shoehorn their models into the common model provided by ServiceInvocationContext.

Also, ServiceInvocationContext assumed that a request is fully available when context is created. However, this is not true anymore with content streaming.

• Replace ServiceInvocationContext with com.linecorp.common.RequestContext
  • Add ClientRequestContext and ServiceRequestContext which extend RequestContext
  • All timeout settings, maximum allowed content length and custom HTTP header options are now overridable via the setters of the context.
    • Now that these options can be overridden by a client or a service, the option names have been prefixed with 'default'. e.g. RESPONSE_TIMEOUT_MILLIS to DEFAULT_RESPONSE_TIMEOUT_MILLIS
• Only expose the information that could be available when a request has just started rather than when a full request is ready.
  • Add RequestLog and ResponseLog so that a client or a service fills the properties as they are available. A user will be notified via RequestContext.requestLogFuture() and responseLogFuture() when all necessary information is ready.
  • For example, RequestContext.method() property always returns the method at the session layer. That is, in a Thrift-over-HTTP call, ctx.method() will not return "someThriftMethod" anymore but only return "POST" because such information is available only when the full request has been received. You can get the Thrift method name from RequestLog later when it's ready.
  • See LogCollectingService and its subtypes for real-world examples.
• com.linecorp.armeria.server.Service has been revamped:
  • Service now has type parameters.
  • ServiceCodec and ServiceInvocationHandler has been merged into Service.
  • Service.serve(ServiceRequestContext, Request) serves a client request.
• com.linecorp.armeria.client.Client has been revamped:
  • Client now has type parameters.
  • ClientCodec and RemoteInvoker have been merged into Client.
  • Client.execute(ClientRequestContext, Request) executes an invocation.

Revamp HttpService with the new API

Previously, HttpService assumed a request is fully available when it is invoked, which is not true anymore.

HttpService is now an interface, and we added AbstractHttpService which replaces the old HttpService class.

Revamp ThriftService with the new API

ThriftService had tight coupling with HTTP session layer and we wanted to remove that.

• ThriftService has been deprecated; use THttpService instead.
  • You will not see many differences with THttpService, however, behind the scene, serving a Thrift call is achieved by two Services now: THttpService and ThriftCallService:
    • THttpService translates an HTTP request into a ThriftCall and a ThriftReply into an HTTP response. (similar to ServiceCodec which has been removed in this release)
    • ThriftCallService delegates a ThriftCall to a stub implementation. (similar to ServiceInvocationHandler which has been removed in this release)
      • Note that the type parameters of ThriftCallService are not HttpRequest and HttpResponse anymore but ThriftCall and ThriftReply.

Client-side renames

• Rename/replace RemoteInvoker to/with ClientFactory
• Rename RemoveInvokerOptions, RemoteInvokerOption and RemoteInvokerOptionValue to SessionOptions, SessionOption and SessionOptionValue
• RemoteInvokerOption.MAX_CONTENT_LENGTH has been moved and renamed to ClientOption.DEFAULT_MAX_RESPONSE_LENGTH and can be overridden via ClientRequestContext.setMaxResponseLength().
• ClientOption.RESPONSE_TIMEOUT_MILLIS and WRITE_TIMEOUT_MILLIS have been renamed to DEFAULT_RESPONSE_TIMEOUT_MILLIS and DEFAULT_WRITE_TIMEOUT_MILLIS and can be overridden via ClientRequestContext.setResponseTimeoutMillis() and setWriteTimeoutMillis().

Revamp client-side service composition and decoration

Previous client composition and decoration was based on the assumption that the full request content is available upon its invocation, which isn't true anymore.

• Replace the option DECORATOR with DECORATION whose value type is ClientDecorations
  • A user is now expected to specify the type of the request and response he or she desires to intercept, and the ClientFactory will apply the decorator at the right place in the invocation chain:
    • builder.add(ThriftCall.class, ThriftReply.class, thriftCallDecorator);
    • builder.add(HttpRequest.class, HttpResponse.class, httpDecorator);

New HTTP client API

SimpleHttpClient and its related types exposed Netty API in its public API and it wasn't powerful enough for daily use. This release introduces a new client interface called HttpClient and deprecates SimpleHttpClient.

Refactor LoggingClient/Service and MetricCollectingClient/Service

• Rename MetricConsumer to MessageLogConsumer
• Move the classes in the metrics package to the logging package
• Add LogCollectingClient/Service
• LoggingClient/Service and MetricCollectingClient/Service extends LogCollectingClient/Service
• Rename MetricCollectingClient/Service to DropwizardMetricCollectingClient/Service because a user can extend LogCollectingClient/Service to support his or her favorite metric collecting library

Bug fixes

• #200 Fix a bug where Armeria server closes a connection without sending a response when a Thrift request is malformed

Improvements

• #191 #195 Upgrade all dependencies to their latest stable versions

Bug fixes

• #86 #190 DocService now handles struct field comments correctly when it generates documentation.

New features

• #174 Display the type, field and method description in the HTML view of DocService
  
  

Bug fixes

• #180 #181 ClassCastException at TTextProtocol.readStructBegin() when reading an ailased enum.
• #184 Fix unnecessary WARN log message by Reflections

New features

• #177 Add support for unions to Thrift TText protocol

Improvements

• #175 Support string values for enums in Thrift TText protocol

Bug fixes

• #179 Fix NoSuchMethodError when using Tomcat 7 Connector

New features

• #144 Preliminary client-side load balancer
  • The first non-trivial external contribution for Armeria; thank you, @shelocks!
  • Note that this feature is not complete. More changes will follow.

Improvements

• #170 Upgrade tcnative-boringssl to the latest version

Bug fixes

• #171 Fix broken interface discovery for Thrift services in DocService
• #173 Fix incomplete TTextProtocol.reset()

New features

• #156 Add 'the number of active requests' to metrics
  • You will see a new property activeRequests if you are using DropwizardMetricConsumer.
• #159 Add doc strings to the JSON data generated by DocService
  • DocService will provide the comments in the IDL files if you put the .json files produced by the nightly build of the official Thrift compiler into the META-INF/armeria/thrift directory.
  • Note the comments are not visible in your browser yet. This is only a preparatory step for it.
• #160 Add JettyService
  • You can now embed Jetty as well as Tomcat!
• #163 Add VirtualHost.defaultHostname() and Server.defaultHostname()
  • Try using Server.defaultHostname() to get the hostname of your machine reliably.
  • TomcatService.forConnector() does not require hostname anymore thanks to this new feature.

Improvements

• #169 Log meaningful identifier of embedded Tomcat

Bug fixes

• #163 #167 TomcatService does not call Server.destroy() when it stops.
• #166 Do not propagate IdleStateEvent to suppress misleading 'unexpected user event' message.

Clean-ups

• #164 Add missing license files and notices
• #165 Reduce the amount of log messages while testing

Bug fixes

• #158 Fix backward compatibility with old Armeria servers
  • An Armeria client uses a HEAD / HTTP/1.1 upgrade request for H1C-to-H2C upgrade by default again.
  • To use the HTTP/2 connection preface string as the default, set com.linecorp.armeria.defaultUseHttp2Preface to true.

Features

• #152 Give full control over the metric name of Dropwizard Metrics integration

  • NB: This breaks the API backward compatibility of the newDropwizardDecorator() method.

    // Before:
    MetricCollectingClient.newDropwizardDecorator("serviceName", registry);
    MetricCollectingService.newDropwizardDecorator("serviceName", registry);
    // After:
    import static com.codahale.metrics.MetricRegistry.name;
    MetricCollectingClient.newDropwizardDecorator(registry, name("client", "serviceName"));
    MetricCollectingService.newDropwizardDecorator(registry, name("server", "serviceName"));
    

Bug fixes

• #151 Use SessionProtocolNegotiationException when protocol upgrade fails due to timeout
• #155 Do not send duplicate DNS queries when the same one is in progress
• #157 Fix the broken links for classes in DocService

New features

• #149 #142 Use PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n for h1c-to-h2c upgrade
  • An Armeria client now by default sends the HTTP/2 preface string instead of the traditional HTTP/1 upgrade request when HTTP/2 is preferred. This is because sending many HEAD / HTTP/1.1 requests can cause unexpected load on an Armeria server if a user bound a service at / and the service does not handle the HEAD method specially.
  • Upgrade your Armeria servers before upgrading your Armeria clients so that all servers are ready to handle the new upgrade mechanism.
  • If you prefer the old upgrade mechanism, you can set RemoteInvokerOption.USE_HTTP2_PREFACE option to false. You can also change the default value of this option from true to false by setting the system property com.linecorp.armeria.defaultUseHttp2Preface to `false.

New features

• #139 Add circuit breaker metrics

Improvements

• #145 Add more debug information to HTTP/2 GOAWAY frame

Bug fixes

• #147 Fix NPE when Server startup fails
• #146 Make Tomcat allow a .JAR file that contains a webapp

Clean-up

• #143 Upgrade dependencies

Bug fixes

• #140 Add 'Content-Length' header to the last response
• #141 Do not attempt to send a response to a closed connection/stream

Bug fixes

• #138 Fix delayed notification of session creation failure and log GOAWAY frames

Bug fixes

• #136 Use singleton list instead of array list for SimpleHttpInvocation.params()
• #131 Fix 'exceptionCaught/inbound message reached at the tail of the pipeline' warnings

New features

• #134 Add system properties to disable /dev/epoll or OpenSSL
  • It is not recommended to disable them unless you experience a problem. Please work with us to fix the problem.

Improvements

• #132 Upgrade dependencies to their latest stable versions

Bug fixes

• #135 Upgrade to Netty 4.1.0.CR6 to fix DNS resolver issues
• #133 Avoid NPE when tracing failed client invocations without messages

New features

• #124 Circuit breaker
• #129 Upgrade to Netty 4.1.0.CR5
• #129 Use epoll and BoringSSL when running on linux-x86_64

Bug fixes

• #128 Disconnect before HTTP/2 stream ID overflows

Bug fixes

• #130 Fix NPE while recording tracing annotations

Bug Fixes

• #127 Propagate all non-null ServerSpans (Zipkin integration)