This PR is still very much WIP - will finish it up by applying pattern for all methods and removing usage of deprecated, adding tests, etc after getting feedback on the API.

Currently, RequestLog has some issues for maintenance and usability

• RequestLogAvailability ties different properties together in an ad-hoc way. For example, REQUEST_START has start time and session information. If we find such a relationship is not what we want (e.g., for #2272 we want to separate start time from session information), it is tedious or sometimes impossible to update availabilities in a backwards compatible way.

• Understanding the properties available for any RequestLogAvailability requires a detailed look at javadoc, and can even require jumping through multiple different availabilities

This PR proposes some changes to help with this. We don't have to apply all of them, mostly just for brainstorming.

• Replace RequestLogAvailability with fine-grained RequestLogProperty. Advanced usage can continue to listen for availability of fine-grained properties

  • There is still some sharing of RequestLogProperty for fields that are obviously equivalent semantically. Different units for start time, or end time + duration, are always equivalent so share the same enum value. On the flip side, an exception and response content are considered different since they are totally different semantically.

• Define two large callbacks - whenRequestComplete and whenComplete. These two seem to be the most standard use cases

  • In #2272 @trustin suggested request identified and response end. From what I understand, request identified is just information from context() and doesn't need a callback, and response end seems to overlap with complete.

• Add RequestRequestLog which has the accessors for information available when request completes, so users have type-safe access to those properties when using whenRequestComplete

• Deprecates many shortcut methods. I feel as if having to deal with availability for these shortcut methods makes them less useful. I guess this is most controversial, no problem adding them back if this doesn't make sense.

One change I haven't made yet is that I would like all fields to be available when request is complete, even for those that didn't get populated (transferred byte times). They could probably return -1 as a default. It seems tricky for just some fields to have a chance of never being available.

Related: #85

This commit contains a lot of changes. I'll group them into several pairs of motivations and modifications.

Use the Reactive Streams API to support HTTP content streaming

Motivation:

Reactive Streams API is the de-facto standard API for implementing object streaming these days; RxJava, gRPC, Akka and Project Reactor are the notable adoptors.

Modifications:

• Add RichPublisher and its subtypes to provide the foundation for streaming HTTP content
  • See the com.linecorp.armeria.common.reactivestreams package, most notably:
    • RichPublisher and Writer
    • QueueBasedPublisher

Decouple the core API from Netty API

Motivation:

Armeria is meant to be used by an application developer. Exposing too much detail to him or her is not the best idea.

Modifications:

• Hide all Netty HTTP types under Armeria's own HTTP/2-centric message types
  • HttpObject
  • HttpHeaders
  • HttpData
  • HttpMethod
  • HttpStatus
  • HttpStatusClass
  • HttpHeaderNames
• Introduce HttpRequest and HttpResponse whose content is a RichPublisher, our reactive streams API
• Add AggregatedHttpMessage which is the FullHttpMessage counterpart
• Add HttpRequest/ResponseWriter for easier composition of an HTTP message
• Do not expose ByteBuf in the user-facing API
• Use CompletableFuture instead of Netty Future/Promise
• Note that we still use Netty's AsciiString as header names because it's generic enough

Redefine Client, Service and their context API

Motivation:

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.

Modifications:

• Replace ServiceInvocationContext with RequestContext
  • Add ClientRequestContext and ServiceRequestContext
  • All timeout settings, maximum allowed content length and custom HTTP header options are now overridable via the setters of the context.
• 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 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 return "POST" rather than "someThriftMethod". It is because such information is available only when the full request has been received. You can get the Thrift method name from RequestLog once it's ready.
  • See LoggingClient/Server and MetricCollectingClient/Server for code example
• Remove ClientCodec, RemoteInvoker, ServiceCodec, ServiceInvocationHandler, because they are all merged into Client or Service

Overall reorganization of session layer implementation

Motivation:

Our code layout is too HTTP-centric and this will eventually make it hard to add other session protocols.

Modifications:

• Move HTTP-specific code to com.linecorp.armeria.{server,client}.http
• Move the internal classes that could be shared between client and server to com.linecorp.armeria.internal.*

Implement HTTP content streaming at the session layer

Modifications:

• Use Armeria's own HTTP/2 centric streaming-aware API instead of aggregating an HTTP/1 or 2 request into a full HTTP/1 request
  • See Http1/2RequestDecoder, HttpResponseSubscriber and HttpServerHandler to learn how this works on the server side
    • Start from Http1/2RequestDecoder to HttpServerHandler.handleRequest()
  • See Http1/2ResponseDecoder, HttpRequestSubscriber and HttpSessionHandler to learn how this works on the client side
    • Start from HttpSessionHandler.invoke()

Revamp HttpService, ThriftService and other services with the new core API

Motivation:

HttpService and ThriftService assumes a request is fully received when it is invoked, which is not true anymore. Also, they are split into two components, ServiceCodec and ServiceInvocationHandler, and they are gone now.

Modifications:

• HttpService is now an interface.
  • Add AbstractHttpService which replaces the old HttpService class
• ThriftService is now THttpService.
  • ThriftService is split into two parts: THttpService and ThriftCallService.
    • THttpService translates an HTTP request into a ThriftCall and a ThriftReply into an HTTP response. (similar to ServiceCodec)
    • ThriftCallService delegates a ThriftCall to a stub implementation. (similar to ServiceInvocationHandler)
  • Deprecate ThriftService
• Other service implementations underwent similar changes to work with the new API.

Revamp client-side service composition and decoration

Motivation:

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.

Modifications:

• 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);

Write new HTTP client API

Motivation:

SimpleHttpClient exposes Netty API and it's not powerful enough.

Modifications:

• Add HttpClient which replaces SimpleHttpClient
• Deprecate SimpleHttpClient

Merge ThriftFunction and ThriftMethod

Motivation:

They basically do the same job slightly differently.

Modifications:

• Merge them into one implementation and move to the internal package.
  • See com.linecorp.armeria.internal.thrift.{ThriftFunction,ThriftServiceMetadata}

Provide a way to add a decorator to all services

Motivation:

Some decorators are often meant to be added to all services in a server or in a VirtualHost.

Modifications:

• 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

Rename RemoteInvokerFactory to ClientFactory

Motivation:

RemoteInvoker is now gone. ClientFactory sounds better in my opinion.

Modification:

• Rename/replace RemoteInvoker to/with ClientFactory
• Add HttpClientFactory and ThriftClientFactory
• Add AllInOneClientFactory that supports both HTTP and Thrift-over-HTTP via the two ClientFactories above
• Rename RemoveInvokerOption and its related classes to SessionOption

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 use LogCollectingClient/Service to support his/her favorite metric collecting library

Result

• HTTP content streaming works.
• Frequently used service implementations such as ThriftService, TomcatService, JettyService and HttpFileService works without modifying user code.
• Frequently used client implementations such as SimpleHttpClient and usual Thrift client stub generation works as before.

Related issue: #2268

This changeset contains the following new experimental features:

• OAuth 2.0 server-side token authorization:
  • OAuth2TokenIntrospectionAuthorizer - implementing Token Introspection [RFC7662] - https://datatracker.ietf.org/doc/rfc7662/
• OAuth 2.0 client-side authorization grants for confidential clients (OAuth2Client), including:
  • OAuth2ClientCredentialsGrant - implementing Client Credentials Grant [RFC6749], Section 4.4 - https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
  • OAuth2ResourceOwnerPasswordCredentialsGrant - implementing Resource Owner Password Credentials Grant [RFC6749], Section 4.3 - https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
• OAuth 2.0 Token Revocation [RFC7009] - https://datatracker.ietf.org/doc/rfc7009/

This changeset also adds the following to support OAuth2 authorization properly:

• Authorizer.authorizeAndSupplyHandlers()
• AuthorizationStatus
• AbstractAuthorizerWithHandlers

Try to solve https://github.com/line/armeria/issues/1223 .

Modification:

• Switching to HttpTracing.
• Create armeria's brave http parser/adapter.
• Add ArmeriaHttpTracingBuilder for user.
• Propagate scope even it's no-op.

Need to consider and TODO in this PR:

• ~We can't use RequestLog's timestamp for start and finish.~
• Span is created when calling handleSend/Receive, at that time we don't have scheme.
• Basically all use RequestLog, it's easier to get req/res related tag value.
• Test for Builder.
• JavaDoc for adapter and parser.

TODO

• [x] http-tests-server
• [x] http-tests-client
• [x] Tests for parser and adapter

For #1703

Tried extracting a package within the armeria-grpc artifact that only contains wire format logic, but it is fragile due to accidental dependencies and classpath magic like service loaders, which we use. So now we extract to a separate artifact entirely.

AbstractUnaryGrpcService allows defining unary gRPC services that are provided the direct bytes of a single gRPC message and return the bytes of a single gRPC message, and the base class takes cafe of the gRPC wire protocol. As this is an advanced use case, it doesn't attempt to implement everything in gRPC but should hopefully provide enough for most armeria-grpc users that are concerned about having dependencies on stub libraries.

@adriancole can you check whether this works for you or provide any suggestions?

Motivation: It will be nice if Armeria supports servlet.

Modifications:

• Added servlet4 module and implemented the minimum features.

Result:

• Support the part of servlet APIs

…ard ones while assuring all operations use pooled objects.

Currently APIs that use unsafe patterns, exposing reference counted objects, are mixed with the normal API. Because they're dangerous, we should hide them as much as possible, so this makes using the unsafe API explicit by requiring using the unsafe API entry points. Unsafe API users also get a QOL increase at the same time by adding the ability to use this API with try/resources.

See #1938 for prior discussion.

Motivation:

• Issue: #194 Service discovery support (serversets, k8s, ..).
• Service discovery supports Consul.

Modifications:

• Creates consul module
• Add dependencies for consul and consul test server
• Add base client for consul
• Add test cases

To dos:

• Add detail clients corresponding to the each Consul API
• Add cached client for health checking
• Add ConsulEndpointGroup

Result:

• Supports Consul discovery service

Support prefix option <exportPrefix> for Logback integration to specify the prefix of exported MDC properties.

For example, if this xml is loaded

  <appender name="RCEA" class="com.linecorp.armeria.common.logback.RequestContextExportingAppender">
    <!-- specify the prefix of exported MDC properties -->
    <exportPrefix>armeria</exportPrefix>
    <export>req.*</export>
    <export>res.*</export>
    ...
  </appender>

then RequestContextExportingAppender exports armeria.req.path, armeria.req.service_name, armeria.res.status_code, etc.

Motivation:

• #1567

Modifications:

• Fork our HTTP headers API into:
  • QueryParams
  • QueryParamGetters
  • QueryParamsBase
  • QueryParamsBuilder
• Extract the common logic and API between HTTP API and query params API into:
  • StringMultimap
  • StringMultimapGetters
• Add support for QueryParams to annotated services.
• Update documentation.
• Deprecate HttpParameters.
• Replace the usage of Netty QueryString{Encoder,Decoder} with:
  • QueryParamGetter.toQueryString() and appendQueryString()
  • QueryParams.fromQueryString()
• Add microbenchmarks for QueryString{Encoder,Decoder}.

Result:

• Closes #1567
• Nicer and faster way to decode/encode a query string.

Adding module for dropwizard integration

Why

1. I use Dropwizard at work, currently, I'm sure others do as well, and trust it's built-in Jetty http server, but might want other features. There already is a Dropwizard gRPC Bundle, but doesn't handle Thrift, AFAIK (not that that is a major feature for me, anyway).
2. Wanted to see how difficult swapping out Dropwizard Jetty servers would be. 😄
3. I am curious how much "faster" Dropwizard would be with Armeria. src: https://www.techempower.com/benchmarks/#section=data-r18&hw=ph&test=plaintext&l=zik0vz-f

Progress

• [x] Dropwizard Bundle
  • [x] Buildable Source
  • Tests
    • [x] YAML configurations
    • [x] Dropwizard lifecycle of Armeria server
    • [x] Testing of services within an Dropwizard application instance (maybe via AccessLog capture)
• [x] Runnable Example
• [x] Docs

Closes #2165

Motivation:

Currently, armeria is unable to create annotated service dependencies specified in @Decorator, @DecoratorFactory, @RequestConverter, @ResponseConverter and @ExceptionHandler using the default constructor of the dependent classes when DependencyInjector is configured.

Related issues: #4521, #4534

Modifications:

• Add CreationMode to @Decorator, @DecoratorFactory, @RequestConverter, @ResponseConverter and @ExceptionHandler.
• Breaking) Use DependencyInjector only when the CreationMode.INJECTION is specified for annotated service dependencies.
• Do not close dependencies create by their default constructor upon server shutdown.

Result:

• Annotated service dependencies can be created with their default constructors even though a DependencyInjector is configured.
• DependencyInjector is used only for those dependencies whose CreationMode is INJECTION.

Motivation:

Setting multiple example requests aren't displayed contrary to multiple headers/queries/paths.

Modifications:

• Add a select component which allows users to select a request.
• Truncate the displayed value in case the example request is too long.

Result:

• #4576

Description

The current implementation of the ExceptionHandler for annotated HTTP services looks pretty good. I have found the following issue for rpc-based services:

• #2044

The answer here is more than enough but I think we can still add a decorator for

1. Specialized exception handling per method/service.
2. Separation of concern and consistency.

This topic is similar to rate limiting, timeouts, or logging. Each has a default setting and can be changed from ServerBuilder or GrpcService. But I think it makes more sense to see them in the actual controller implementations using decorators.

For specialized exception handling, I think the following cases make sense:

• The same exception can mean different things for different endpoints. (E.g. IOException can mean both an invalid parameter, internal error, or not found).
• We might want to hide some important endpoints by returning Not found instead of Unauthorized. (E.g. if there are path parameters)

Example use cases

@ExceptionHandlerDecorator(ExceptionHandlerFunction::class)

or

@ExceptionMappingDecorator(IllegalArgumentException::class, Status.UNAUTHENTICATED)

It could be nice to add some specialized information from exception.message if possible too.

The ServerExtension is widely used and very useful for testing like a real environment. However, it is sometimes inconvenient because the configuration of the server is too far away from the test code. The more test cases, the longer configuration of the server. For example, RetryingClient has 193 lines for configuration. The distance between subscriber-cancel's configuration and the test is 372 lines.

https://github.com/line/armeria/blob/ecc0e89b99b486709722210ac4fcbe6c77764a56/core/src/test/java/com/linecorp/armeria/client/retry/RetryingClientTest.java#L303

https://github.com/line/armeria/blob/ecc0e89b99b486709722210ac4fcbe6c77764a56/core/src/test/java/com/linecorp/armeria/client/retry/RetryingClientTest.java#L674

Rather than configuring the ServerExtension at one place, configuring at each unit test would be easy to read and write because the context is gathered in one place. reconfigure may be a good option to achieve. Simply, runs a Server and reconfigures the server at each unit test:

@RegisterExtension
static ServerExtension server = new ServerExtension();

@Test
void myTest() {
    try (SafeCloseable ignored = useServer(server, builder -> /* configure the server */ )) {
        // test code
    }
    useServer(server, builder -> /* configure the server */)
        .run(() -> {
            // test code
        });
}

Before running the test code block, call the Server's reconfigure with the configure the server block.

We may need an option to allow running the server without any service.

Motivation:

Improve JSON Schema support for AnnotatedService to ramp up DocService.

Parent PR:

• #4518

Requirements:

• [ ] Support @Param bodies to appear in schema
• [ ] Support non-object bodies (such as string or number)
• [x] Support nested containers (e.g. map<map<...>)
• [ ] Support anonymous classes
• [ ] (Optional) Http headers
• [ ] (Optional) Query params

Testing

Run AnnotatedDocServiceTest in demo mode.

We might need more examples in the annotated doc service.

Latest status of schemas.json as of 31.12.2022:

• https://gist.github.com/Dogacel/5b6067cbcbc78c206a955d5e206ded4f

Motivation:

Improve JSON Schema support for Thrift TText protocol to ramp up DocService.

Parent PR:

• #4518

Requirements:

• [ ] Typedef support (currently they are only object).
• [x] map<..., Enum> support (container types sometimes miss enum definitions)
• [ ] Numerated enum support
• [x] Union support
• [x] binary support

Note: It seems like typedefs are unresolved types in ServiceSpecification

• #413

so we first need to fix that.

Testing

Compared schemas for

• FooService
• HelloService
• OnewayHelloService
• SleepService

We can compare using HBase and Cassandra but I got kinda lazy and my Thrift knowledge is very low.

Here is the current status of the schema as of 31.12.2022:

• https://gist.github.com/Dogacel/143b1185b54973a54e11b89c219ca6d3