Smart Routes

Smart Routes are routes that can change the default behavior of standard requests. With Smart Routes you can redirect, intercept, filter and also proxy requests to another server. There is five basic types of Smart Routes on Kikaha:

• Proxy Routes: where you can proxy specific requests to another server
• Rewrite Routes: permit to rewrite request paths (similar to Apache httpd's mod_rewrite)
• Redirect Routes: send redirect status (30x) for specific requests
• Filters: allow intercept and change any request before it hit the expected endpoint
• CORS: allow developers to configure how do Cross-Origin Requests should behave

Proxing requests to another server (Reverse routing)

Assume that we have a restful application that mainly process PDF and turn its pages into PNG images. Despite the several REST endpoints exposed by the application, only /api/pdf/process takes a lot of CPU time making the entire application slow while one (or more) PDF is being processed.

It is possible to delegate the request of /api/pdf/process to another server, avoiding the entire server starving from resources while PDFs is processed. The configuration bellow illustrates how is possible to achieve this.

server:
  smart-routes:
    reverse:
      - { path: "/api/pdf/process", to: "http://process.pdf.localdomain/" }

At the above example, all requests on /api/pdf/process will be delegated to the host process.pdf.localdomain.

Now, lets also assume that in our example there is also an indexing routine that takes too much CPU time of our server. Its endpoint is /api/pdf/index. It is possible to use placeholders to make a more versatile routing.

server:
  smart-routes:
    reverse:
      - { path: "/api/pdf/{routine}", to: "http://{routine}.pdf.localdomain/" }

In this example, not only /api/pdf/process will be delegated to the host process.pdf.localdomain, also /api/pdf/index will be routed to index.pdf.localdomain too.

Internally rewriting some requests URIs

The bellow configuration illustrates how you can use Kikaha's rewrite rule to serve multiple static sites in a single server instance.

server:
  smart-routes:
    rewrite:
      - { virtual-host: "{tenant}.static.net", path: "{path}", to: "{tenant}/{path}" }

In this example, once a request comes to http://customer1.static.net/products/details.html, it will render the file details.html placed at the folder customer1/products.

Redirecting URIs

Bellow is a configuration that behaves quite similar to the above configuration, but instead of internally rewriting the path to match internal endpoints, it will response a 303 response which the browse will be responsible to make another call at the just specified address.

server:
  smart-routes:
    redirect:
      - { virtual-host: "{tenant}.static.net", path: "{path}", to: "{tenant}/{path}" }

Filtering requests

If create managed implementations of kikaha.core.modules.smart.Filter interface, you would be able to intercept any incomming request before it reaches any of the internal REST endpoints. The bellow sample code shows how you can filter incoming requests and decide if you should or not avoid the browser to access a specific endpoint.

import kikaha.core.modules.smart.*;
import kikaha.urouting.*;
import javax.inject.*;

@Singleton
public class MyInterceptionFilter implements Filter {

  @Inject UndertowHelper undertow;

  public void doFilter(HttpServerExchange exchange, FilterChain chain) {
    SimpleExchange simpleExchange = undertow.simplify( exchange );
    long postId = simpleExchange.getQueryParameter( "postId", Long.class );

    if ( "/api/abc".equals( simpleExchange.getRelativePath() ) && postId > 1000 )
      simpleExchange.sendResponse( DefaultResponse.forbiden() );
    else
      chain.runNext();
  }
}

Note that it is using the Simplified Undertow API, which you can see more details Routing with Undertow API.

Cross-Origin Requests

Most of recent browsers can handle Cross-Origin Request if the server is properly configured. Kikaha provides a Filter that intercept requests and handle CORS requests. Bellow is the available parameters to configure CORS requests with Kikaha.

server:
  smart-routes:
    cors:
      enabled: false
      always-allow-origin: false
      always-allow-credentials: false
      allowed-methods: [ "GET" ]
      allowed-origins: [ "https://allowedhost.example.com", "https://kikaha.example.com" ]

All CORS-related parameters are placed inside the server.smart-routes.cors path at the configuration file:

• enabled: defines where CORS filters is enabled
• allowed-methods: define which HTTP Methods are allowed.
• allowed-origins: define which sources could make CORS requests on your application. It could be empty if the always-allow-origin is set to true.
• always-allow-origin: (optional - default false) if true, it will accept of any source
• always-allow-credentials: (optional - default false) if true, it will accept cookies from any source.