armeria-0.21.0.Final

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