Camel Components

Platform Http Vertx

Since Camel 3.2

The camel-platform-http-vertx is a Vert.x based implementation of the PlatformHttp SPI.

Vert.x Route

This implementation will by default lookup the instance of VertxPlatformHttpRouter on the registry, however, you can configure an existing instance using the getter/setter on the VertxPlatformHttpEngine class.

Auto-detection from classpath

To use this implementation all you need to do is to add the camel-platform-http-vertx dependency to the classpath, and the platform http component should auto-detect this.

Message Headers

Name Type Description

CamelVertxPlatformHttpAuthenticatedUser

io.vertx.ext.auth.User

If an authenticated user is present on the Vert.x Web RoutingContext, this header is populated with a User object containing the Principal.

CamelVertxPlatformHttpLocalAddress

io.vertx.core.net.SocketAddress

The local address for the connection if present on the Vert.x Web RoutingContext.

CamelVertxPlatformHttpRemoteAddress

io.vertx.core.net.SocketAddress

The remote address for the connection if present on the Vert.x Web RoutingContext.

Camel also populates all request.parameter and Camel also populates all request.headers. For example, given a client request with the URL, http://myserver/myserver?orderid=123, the exchange will contain a header named orderid with value 123.

VertxPlatformHttpServer

In addition to the implementation of the PlatformHttp SPI based on Vert.x, this module provides a Vert.x based HTTP server compatible with the VertxPlatformHttpEngine:

Java-only: programmatic VertxPlatformHttpServer setup
VertxPlatformHttpServerConfiguration conf = new VertxPlatformHttpServerConfiguration();
conf.setBindPort(port);

context.addService(new VertxPlatformHttpServer(conf));

from("platform-http:/test")
    .routeId("get")
    .setBody().constant("Hello from Camel's PlatformHttp service");

Implementing a reverse proxy

Platform HTTP component can act as a reverse proxy, in that case Exchange.HTTP_URI, Exchange.HTTP_HOST headers are populated from the absolute URL received on the request line of the HTTP request.

Here’s an example of an HTTP proxy that simply redirects the Exchange to the origin server.

Java-only: reverse proxy using string concatenation with Exchange constants
from("platform-http:proxy")
    .toD("http://"
        + "${headers." + Exchange.HTTP_HOST + "}");

Access to Request and Response

The Vertx HTTP server has its own API abstraction for HTTP request/response objects which you can access via Camel HttpMessage as shown in the custom Processor below :

Java-only: inline Processor accessing Vertx request and response objects
.process(exchange -> {
    // grab the message as HttpMessage
    HttpMessage message = exchange.getMessage(HttpMessage.class);
    // use getRequest() / getResponse() to access Vertx directly
    // you can add custom headers
    message.getResponse().putHeader("beer", "Heineken");
    // also access request details and use that in the code
    String p = message.getRequest().path();
    message.setBody("request path: " + p);
});

Response body

The body of the reply is written as text, bytes or a stream. Text is written in the charset that the response Content-Type declares (UTF-8 otherwise), and a number, a boolean, a character or an enum as its text, so setBody(constant(42)) replies with 42. A Map, a List or an object must be marshalled first (for example with marshal().json()), or the consumer answers 500.

Synchronous or asynchronous routing

Each request is routed on a thread of the Vert.x worker pool, as the first steps of a route may block. The synchronous option of the platform-http endpoint decides whether this worker thread waits until the route is complete. The same option on the platform-http component sets the default for all its endpoints.

In both modes, when the route continues on another thread (for example after an asynchronous producer such as vertx-http), the rest of the route runs on that thread, and the response is written when the route is complete. A route that is synchronous to its end (no asynchronous step) runs the same way in both modes: on the worker thread.

synchronous=false (the default)

The route runs with the asynchronous routing engine, and the worker thread is free for the next request as soon as the route continues on another thread. So the size of the worker pool does not limit how many requests of such a route are in flight. Choose this mode when a route calls an asynchronous producer that uses the same Vert.x as the HTTP server, such as vertx-http with a Vert.x instance in the registry (as in Camel Quarkus). Such a producer needs a worker thread of that Vert.x to complete its exchange, and with synchronous=true the requests in flight can hold every worker thread, so that no request completes any more. The consumer worked this way from Camel 3.6 to 4.1.

synchronous=true

The worker thread waits until the route is complete, also while the route waits for an asynchronous step. So the size of the worker pool limits how many requests are routed at the same time, and further requests wait for a free worker thread. Choose this mode when you rely on that limit, for example to bound the number of concurrent calls to a backend, and the route does not call an asynchronous producer on the same Vert.x. The consumer worked this way from Camel 4.2 to 4.23.

  • Java

  • XML

  • YAML

from("platform-http:/orders?synchronous=true")
    .to("bean:orderService");
<route>
  <from uri="platform-http:/orders?synchronous=true"/>
  <to uri="bean:orderService"/>
</route>
- route:
    from:
      uri: platform-http:/orders
      parameters:
        synchronous: true
      steps:
        - to:
            uri: bean:orderService

To use the synchronous mode for all routes, set camel.component.platform-http.synchronous=true.

A route in the asynchronous mode that needs a bound on the requests in flight can use the Throttle EIP in concurrent requests mode with asyncDelayed, for example throttle(10).concurrentRequestsMode().asyncDelayed(). With asyncDelayed, a request that waits for a permit does not hold a worker thread either. Without it, the waiting requests hold the worker threads, and on a shared Vert.x they can again hold every worker thread that the asynchronous producer needs.

Handling large request / response payloads

When large request / response payloads are expected, there is a useStreaming option, which can be enabled to improve performance. When useStreaming is true, it will take advantage of stream caching. In conjunction with enabling disk spooling, you can avoid having to store the entire request body payload in memory.

  • Java

  • XML

  • YAML

from("platform-http:/upload?httpMethodRestrict=POST&useStreaming=true")
    .log("Processing large request body...")
    .to("file:/uploads?fileName=uploaded.txt");
<route>
  <from uri="platform-http:/upload?httpMethodRestrict=POST&amp;useStreaming=true"/>
  <log message="Processing large request body..."/>
  <to uri="file:/uploads?fileName=uploaded.txt"/>
</route>
- route:
    from:
      uri: platform-http:/upload
      parameters:
        httpMethodRestrict: POST
        useStreaming: true
      steps:
        - log:
            message: "Processing large request body..."
        - to:
            uri: file:/uploads?fileName=uploaded.txt
This requires to upload the content as application/octet-stream to leverage streaming mode. You cannot upload using multipart.

Setting up http authentication

Http authentication is disabled by default. In can be enabled by calling setEnabled(true) of AuthenticationConfig. Default http authentication takes http-basic credentials and compares them with those provided in camel-platform-http-vertx-auth.properties file. To be more specific, default http authentication

To set up authentication, you need to create AuthenticationConfigEntries, as shown in the example below. This example uses Vert.x BasicAuthHandler and PropertyFileAuthentication to configure Basic http authentication with users info stored in myPropFile.properties file. Mind that in Vert.x order of adding AuthenticationHandlers matters, so AuthenticationConfigEntries with a more specific url path are applied first.

Java-only: programmatic authentication configuration with Vertx handlers
final int port = AvailablePortFinder.getNextAvailable();
final CamelContext context = new DefaultCamelContext();

VertxPlatformHttpServerConfiguration conf = new VertxPlatformHttpServerConfiguration();
conf.setBindPort(port);

//creating custom auth settings
AuthenticationConfigEntry customEntry = new AuthenticationConfigEntry();
AuthenticationProviderFactory provider = vertx -> PropertyFileAuthentication.create(vertx, "myPropFile.properties");
AuthenticationHandlerFactory handler = BasicAuthHandler::create;
customEntry.setPath("/path/that/will/be/protected");
customEntry.setAuthenticationProviderFactory(provider);
customEntry.setAuthenticationHandlerFactory(handler);

AuthenticationConfig authenticationConfig = new AuthenticationConfig(List.of(customEntry));
authenticationConfig.setEnabled(true);

conf.setAuthenticationConfig(authenticationConfig);

context.addService(new VertxPlatformHttpServer(conf));

from("platform-http:/test")
    .routeId("get")
    .setBody().constant("Hello from Camel's PlatformHttp service");