Light Router

All the services developed on top of light-4j frameworks support client side service discovery, load balance and cluster natively. However, for some clients who cannot leverage our client module, we have provided the light-router, which moves the client modules on the network to allow the original client to consume services as it is today without considering how dynamic these services are in the cloud.

Another usage for the light-router is to act as a BFF(backend for frontend) for Single Page Applications or Mobile Native Applications. It is supposed to be used only for simple use cases that the client wants to access backend APIs built on top of Light Platform. Suppose there is additional logic in the business context, for example, transformation, orchestration, aggregation and integration. In that case, you need to create customized middleware handlers and wire them into the light-router request/response chain or create a microservice for the BFF using light-router as a template.

The third use case for the light-router is to act as a distributed gateway for an external client. The light-router will be responsible for security, load balance, service discovery and route traffic to the right services. We call this component EAP (External Access Point). When exposing internal microservices to an external client on the Internet, we can deploy an instance of light-router per external client in the B2B scenario. We call this component EAP (External Access Point). For organizations with limited resources and network limitations, a single instance of the light-router can be deployed for all external clients.

Along with service discovery and routing, light-router also provides other cross-cutting concerns like security, metrics, logging, validation and more.

The light-router has the following features:

  • High throughput, low latency, and small memory footprint.
  • TLS passthrough or termination
  • Discovers service with Light-Portal Controller, Consul, etc.
  • Supports environment tags for multiple testing environments deployed to the same cloud.
  • Integrates light-oauth2, oauth-kafka and third-party OAuth 2.0 providers to retrieve the access token and renew the token before expiration.
  • Built-in load balancer and cluster support
  • Can be started with Docker or standalone
  • Supports HTTP/2.0 protocol on both in/out connections
  • Supports REST, GraphQL and RPC style of APIs
  • Centralized logging to ELK with traceabilityId, and correlationId or Open Tracing
  • Collects client and service metrics into InfluxDB and view the dashboard on Grafana
  • Manages configuration with light-portal light-config-server

To learn how to use this router, please refer to

  • Getting Started to learn why we have provided this router
  • Tutorial with step by step guide for the RESTful router
  • Components router specific components and middleware handlers
  • Artifact find release artifacts and deploy options
  • Configuration for different configurations based on your situations
  • Location and Ownership for deployment and ownership decision
  • Static Content render a single page application
  • [Servic Id or URL] directives in header for downstream API invocation
  • [URL Rewrite Rules] for light-router used as an API Gateway

URL Rewrite Rule

When we use the light-router as a gateway, the incoming URL might have a different path than the outgoing URL. To support it, you can add a section called urlRewriteRules in the router.yml to define a list of regex and replacement pairs. Here is an example of the configuration for the UNIT tests. # URL rewrite rules, each line will have two parts: the regex patten and replace string separated # with a space. Read More »

Service Id Url

When using light-router to route traffic to the downstream APIs, most users will use PathPrefixServiceHandler, PathServiceHandler or ServiceDictHandler to derive the downstream API serviceId from the request attributes like the path, method or endpoint etc. The above setup works great if the downstream APIs are different with different paths and endpoints. What if we have the same API deployed with multiple instances to serve clients from different geo-locations? How can we route the traffic to different hosts when the requests are similar? Read More »

Service Dict Mapping

When using the light-router or http-sidecar, each request must have service_id in the header in order to allow the router to perform the service discovery before invoking a downstream service. The reason we have to do that is due to the unpredictable path conflicts between services. If you are sure that the path or the endpoint can uniquely identify all the downstream services, then you can use this Path to ServiceId mapping handler to uniquely identify the serviceId and put it into the header. Read More »

Static Content

In most cases, light-4j microservices will be deployed to a Kubernetes cluster in the cloud with dynamic IPs and ports. Web applications consuming these services must be able to discover the services based on the serviceIds. The light-router is built for the exact purpose. It provides a static IP access point to all the microservices in the cloud with service discovery and security addressed so that a single page application running on the browser can access the backend services through APIs. Read More »

Path Prefix Service

The original PathServiceHandler has hard dependency on Swagger or OpenAPI handlers in the light-rest-4j framework. It is feature rich, but sometimes overkill for simple use cases. For a simple mapping from a request path to a serviceId, a pattern matching will be good enough. @logi contributed this handler and it is very good if you want to replace the PathServiceHandler. When using the light-router, each request must have a serviceId in the header in order to allow the router to discover the services before invoking downstream services. Read More »

Path Service Mapping

When using the router, each request must have service_id in the header in order to allow the router to perform the service discovery before invoking a downstream service. The reason we have to do that is due to the unpredictable path conflicts between services. If you are sure that the path or the endpoint can uniquely identify all the downstream services, then you can use this Path to ServiceId mapping handler to uniquely identify the serviceId and put it into the header. Read More »

Token Handler

This is a middleware handler that is responsible for getting a JWT access token from OAuth 2.0 provider for the particular router client. The only grant type that is supported in this handler is client credentials as there is no user profile information available here. It is designed for API to API invocation and the client side API cannot use client.jar from the light-4j platform. If any user profile is needed, the original client must follow the authorization code grant flow to get a token that represents the original user. Read More »

Proxy Client

This is a simple proxy client for light-router, and it can discover and load balance the hosts from Consul or other service discovery services supported by Light. As the target servers are implemented in light-4j which is HTTP 2.0 supported, there is no need to have a connection pool to be implemented. For each host, there would be only one connection as HTTP 2.0 supports multiplexing. The RouterProxyClient implements Undertow ProxyClient interface, and it provides client-side service discovery, cluster support and load balance which are very specific to support microservices deployed in the cloud with Kubernetes. Read More »

Router Components

Light-router uses some of the middleware handles from light-4j and light-rest-4j as plugins in the request and response chain. Besides, we have implemented several middleware handlers for light-router specific requirements. These handlers are located in the light-router repository. Some of them are mandatory, and some of them are optional. RouterProxyClient TokenHandler PathServiceHandler PathPrefixServiceHandler Read More »

Location Ownership

Light-router is primarily used for service discovery. Technically, there is client-side discovery only as it is called “service discovery” and only clients need to do that. All discovery can only exist on client-side. There is a difference between the discovery code in client, on the client host, or on another static server in a data center. An additional scenario is to use light-router as BFF for SPA or Mobile. In scenario one, the code is inside of client which mean using light-4j client module give us most flexibility and performance. Read More »

Router Configuration

The light-router is a client routing server that provides a lot of features other proxy servers don’t have. This document will explain all use cases and map to specific configurations to deploy the light-router server based on the requirements. router.yml Here is an example of router.yml # Light Router Configuration# As this router is built to support discovery and security for light-4j services,# the outbound connection is always HTTP 2.0 with TLS enabled. Read More »

Router Artifact

When considering using light-router to assist the client that cannot leverage client.jar to access APIs deployed in the cloud you have two options for deployment artifacts. With each of the following option, you have to provide config files and pass them as a directory to the light-router or as Kubernetes Secret to the container. For more information on how to config the light-router, please refer to configuration. Docker The docker images can be found at https://hub. Read More »