Concerns Overview

One of the design goals of light-4j is to address all the technical cross-cutting concerns in the frameworks so that service developers only need to focus on the business logic without worrying about security, auditing, logging, metrics, etc. The same pattern can be applied in the business context as well so that you can have several handlers performing different tasks within the business context. For example, the fine-grained authorization can be done as a cross-cutting concern in the business context without mixing into the real business logic within the core request handler.

Technical Cross-Cutting Concerns

When building an application, there is a functional requirement. Normally, there is always a non-functional requirement that is created to address all technical concerns. In most platforms, developers need to address these concerns in the same business handler at the same time. It makes the application very hard to maintain and to reason about as functional requirements and business requirements are implemented at the same time in the same context. The code is blended and hard to separate, hence decreasing the maintainability. Light divides these concerns into individual handlers so that multiple developers can work together. These handlers are relatively simple and easy to be shared between services, and we have provided dozens built-in handlers in the platform. Without non-functional concerns in the business logic, the main business handler will be much simpler to implement and reason about. In the long run, it is easy to maintain as any modification will be focused on the business logic only.

Here is a list of cross-cutting concerns provided by Light.

light-4j

light-rest-4j

light-graphql-4j

light-hybrid-4j

light-aws-lambda

With Lambda framework

With Light-Proxy

Business Cross-Cutting Concerns

In a system, besides of technical concerns, there are other concerns that need to be addressed within the business context. In most systems, these will be blended into the business logic implementation which makes the business rules hard to reason about. In our design, these are separated into individual handlers which wired in before or after the main business handlers. For example, fine-grained authorization based on the custom claim in the JWT token or result filter based on the client_id in the JWT token.

Env vars injected into values.yml

Most light-4j components has config files and the property values can be injected via values.yml file or environment variables. Recently, one of our customers want to inject values into values.yml from environment variables. This is due to the sensitive information is managed by Hashicorp product that can updates the environment variables automatically without checking into git repository in values.yml file. Injecting Environment Variables into values.yml for Light-4j Components Current Situation Light-4j components use config files Property values can be injected via values. Read More »

Token Limit Handler

For most OAuth 2.0 cloud service providers, customers are charged based on the number of tokens issued. When a JWT (JSON Web Token) is used, it typically expires within 10 to 20 minutes. Therefore, it’s practical for the client to cache the token within the expiration period to avoid requesting a new token for each API call. This approach also allows the API server to cache the token instead of verifying the signature for every request, as the cryptographic calculation is time-consuming. Read More »

Metrics

Introduction The metrics handler collects the API runtime information and reports it periodically to a time series database like Influx or TimeScale (5 minutes to 15 minutes, based on the API volume). Basically, the light-4j metrics module will push the metrics info to a remote server. At this moment, we have two implementations: [InfluxMetricsHandler][] and APMMetricsHandler. At the same time, some of the metrics servers will pull the metrics info from the light-4j metrics module like Prometheus. Read More »

Apm Metrics

We have some customers who are using Broadcom APM for metrics handling and presentation. This AMPMetricsHandler is a customized one that can connect to the EPAgent deployed on the Kubernetes cluster as a common service or VM host for VM deployment. The APM Agent support RESTful Interface that is defined here The metrics collection is managed by the AbstractMetricsHandler and both push metrics handlers ([MetricsHandler][] and APMMetricsHandler are extended from the AbstractMetricsHandler. Read More »

Swt Verifier

A simple web token is used instead of a JSON web token for some external requests, and the light-4j server needs to send the token to the OAuth 2.0 provider for token introspection. In this case, the SwtVerifier will be used instead of JwtVerifier. The SWT introspection configuration is the same as the JWK configuration, and they share the same token key section in the client.yml file. The only difference is that the client_id and client_secret might be required for the introspection but not JWK. Read More »

Direct Registry

If you don’t have the Consul or the Light Portal deployed for the service registry and discovery, you can use the built-in DirectRegistry as a temporary solution. It is the best way to switch to an enterprise solution later. There are two ways to define the serviceId to the hosts mapping. The first option is using the service.yml and the second option is using the direct-registry.yml. service.yml It is the original way to define the parameters in the URLImpl in the service. Read More »

Proxy Health

For an API built with light-4j frameworks, it has a health check endpoint exposed for third-party monitoring systems and Kubernetes probes. If http-sidecar is used, we can use the LightProxyHandler for the health check, and it has the option to collect the health status from the backend API. Both HealthGetHandler and ProxyHealthGetHandler share the same health.yml configuration file. In the handler.yml, we can also config two different endpoints. handlers: - com. Read More »

Path Prefix Service

When using the light-gateway, each request must have service_id in the header to allow the router to discover the service before invoking downstream services. We have to do that due to the unpredictable path between services. Suppose you are sure that a unique path prefix can identify all the downstream services. In that case, you can use this Path to ServiceId mapper handler to uniquely identify the service_id and put it into the request header. Read More »

Config Reload

When a light-4j application is running in a Kubernetes cluster as a microservice or http-sidecar, it is easy to restart the server to pick up the latest configuration from the config server or local filesystem. However, when running light-gateway as a shared service for multiple consumers and providers, it is impossible to restart the server without impacting others, when onboarding a new consumer or a new provider, several middleware handlers must reload the configuration changes without shutting down the server. Read More »

Shutdown

In a production environment, the light-4j server will be started in a Kubernetes cluster or running as a Windows or Linux service. To force the server to restart, you can send a DELETE request to /adm/shutdown endpoint. Once the server is shut down, the K8s will reschedule the pod, and Linux/Windows server will restart the service automatically. Specification The specification is injected to any light-rest-4j application via openapi-inject.yml when the application specific openapi. Read More »

OAuth Server

When an organization migrates existing applications and services to the light-gateway from a monolithic gateway without changing the code for all consumer applications, we need to provide a dummy OAuth 2.0 server on the light-gateway to simulate how other gateway works. Most monolithic gateways will have a built-in OAuth 2.0 server to issue tokens to the consumer and verify the tokens for subsequent requests. Consumer applications might cache a token and go to the gateway to get a new token when the cached token is about expired. Read More »

API Key

For some legacy applications to migrate from a monolithic gateway to the light-gateway without changing any code on the consumer application, we need to support the API Key authentication/authorization on the light-gateway(LG) or client-proxy(LCP). The consumer application sends the API key in a header to authenticate/authorize itself on the light-gateway. Then the light-gateway will retrieve a JWT token to access the downstream API. Only specific paths will have API Key set up, and the header name for each application might be different. Read More »

Response Interceptor

As we all know, middleware handlers are used to address cross-cutting concerns in the request/response chain. Some middleware handlers are used to manipulate the request or response, like the header handler to update the request and response headers based on the configuration file. Although we have provided a lot of middleware handlers to help users to manipulate the request and response as cross-cutting concerns, we cannot predict all the use cases our users come up with. Read More »

Request Interceptor

As we all know, middleware handlers are used to address cross-cutting concerns in the request/response chain. Some middleware handlers are used to manipulate the request or response, like the header handler to update the request and response headers based on the configuration file. Although we have provided a lot of middleware handlers to help users to manipulate the request and response as cross-cutting concerns, we cannot predict all the use cases our users come up with. Read More »

External Handler

When using the light-gateway to access external services from the corporate network through a proxy server like McAffee WebGateway, the router handler doesn’t support the proxy configuration. We are trying to resolve the issue in the client module of light-4j; however, it will take some time, and we have to find a workaround to help some of the projects with tight schedules. The solution is to create a generic handler with JDK 11 HTTP client to connect to the external services, and it supports the proxyHost and porxyPort configuration. Read More »

Mras

This is a customized handler that is used to access an external service through a corporate network with web gateway. The reason we cannot use the generic external service handler is that the service requires two-way TLS and customized access token endpoint. This handler is located in the light-4j repo ingress-proxy module. The default config template can be customized in the values.yml file. mras.yml # Configuration for MrasHandler # Indicate if the handler is enabled or not enabled: ${mras. Read More »

SalesforceHandler

Some organizations use cloud services like Salesforce cloud service with the light-gateway as the external services gateway. The light-gateway will be responsible for addressing all the cross-cutting concerns like security, tracing, metrics, auditing, etc. Salesforce has a special authentication flow to get an access token, so we have implemented a customized SalesforceHandler to handle the authentication and invoke the real request to the target server. Here is the detailed step for the flow. Read More »

Rule Loader

In networknt, we have a rule engine YAML Rule used for some repeatable business logic shared by multiple LOBs or organizations. To ensure multiple users can share the rules, we usually publish the rules to the light-portal, and applications can subscribe to rules created by other people. Once you have subscribed to some rules for your service, you should load those rules during your service startup. The rule-loader module has a startup hook implemented to load the rules for the service from the light portal. Read More »

Ingress Proxy

The ingress-proxy module is used by the [http-sidecar][] and [light-proxy][] to address cross-cutting concerns for the incoming traffic. Read More »

Egress Router

The egress-router module is used by the http-sidecar and light-router to address cross-cutting concerns for the outgoing traffic. It depends on some of the middleware handlers from light-4j or light-rest-4j in the request and response chain. Besides, we have implemented several middleware handlers for light-router and http-sidecar specific requirements. These handlers are located in the light-4j repository and test cases are located in the light-router repository. Some of them are mandatory, and some of them are optional. Read More »

Proxy Body

The light-proxy and light-mesh/http-sidecar use this handler to parse the body into an attachment and keep the stream forwarded to the backend API. It parses the body to a list or map if the content-type is application/json in the HTTP header for POST, PUT and PATCH HTTP methods. The openapi-validator depends on this handler for parsing the request body streams to JSON and attaching it to exchange to be validated based on the request body schema definition in the specification. Read More »

Portal Registry

Most of our users are using Consul for the service registry and discovery in large scale microservices deployment. However, we found several issues with Consul and finally released our light-portal controller to replace Consul as a centralized control panel. The first issue with Consul is the local agent resource utilization and extra setup. If all services can register themselves to a centralized cluster, it would be more efficient. The second issue with Consul is the long poll or blocking query when API subscribes to the downstream API instance changes. Read More »

Response Encode and Request Decode

To reduce bandwidth usage and speed up the delivery, many clients and servers utilize gzip or deflate encoding for large requests or responses. One of our users built an API that receives batch data from iOS, and the request is encoded with gzip. It requires that we have a RequestDecodeHandler before the BodyHandler to decode the gzip stream so that subsequent handlers can handle the request as a normal JSON body. Read More »

IP Whitelist

API security is very crucial, and it is an essential part of the cross-cutting concerns provided by Light Platform. For business API endpoints, we should use the OAuth 2.0 JWT token to secure them. For some other functional endpoints that cannot be secured by OAuth 2.0, Basic Authentication or API Key is an option. For example, one of the users is using Basic Authentication to secure their API deployed on an IoT device. Read More »

Basic Auth

We know that the default security for Light is OAuth 2.0, and we have a provider, light-oauth2, to support it. However, we must support other authentication mechanisms for some exceptional use cases. One of them is basic authentication, which is constantly asked about by our customers who want to deploy the service to IoT devices. Or use it in the light-gateway to integrate legacy services into the light-4j ecosystem. Unlike JWT verification, the basic authentication can be implemented as a generic middleware handler in light-4j instead of having different implementations for different frameworks, as it has no dependencies on any framework. Read More »

Datasource

Most services have to persist data into a database. Although No-SQL databases are getting popular these days, relational databases are still used by most enterprise customers. We used to create a datasource instance from service.yml automatically just like the below configuration. - javax.sql.DataSource: - com.zaxxer.hikari.HikariDataSource: DriverClassName: org.h2.jdbcx.JdbcDataSource jdbcUrl: jdbc:h2:~/test username: sa password: sa The above config section in service.yml creates an H2 datasource automatically without any code. However, there are several drawbacks. Read More »

Resource

This is the module that handles the static content. It is built to serve Single Page Application with Javascript, CSS and images. Read More »

Prometheus

Introduction Prometheus is a tool/database that is used for monitoring. Prometheus adopts a pull based model in getting metrics data by querying each target defined in its configuration. Prometheus scrapes metrics from instrumented jobs, either directly or via an intermediary push gateway for short-lived jobs. It stores all scraped samples locally and runs rules over this data to either aggregate and record new time series from existing data or generate alerts. Read More »

Decryptor

Encrypted Configuration Values in Light-4j To keep sensitive information secure within configuration files, Light-4j allows for encryption and decryption of values in config files. This ensures that secrets like passwords and client keys remain protected, even in plain-text configuration files. Overview A Decryptor component is injected into the Light-4j framework to decrypt values stored in an encrypted format in configuration files. To set up encrypted values in a config file, you’ll need to use a command-line utility to convert plain text into encrypted text, then place this encrypted value in the config file. Read More »

Common

This is the module that contains some classes that are shared between the client and server. DecryptUtil The class is a utility to handle the encrypted sensitive values in secret.yml or other config files. Basically, when using light-4j frameworks, it is recommended to put all the secrets into one file called secret.yml so that it can be managed separately and can be mapped to Secret in the Kubernetes cluster naturally. Read More »

Audit Log

A built-in audit handler writes logs into audit.log file, which is set up in the logback appender. The end user can add more customized audit handlers if needed. For example, some customers write audit info into a relational database, while others write it into a Kafka topic. In the audit module, there is AuditHandler which is generic and configurable with the audit.yml config file. There is another audit provided by the light-4j framework called DumpHandler in the dump module. Read More »

Body Handler

Introduction Body parser is a middleware handler designed for light-rest-4j only. It will parse the body to a list or map according to the content-type in the HTTP header for POST, PUT and PATCH HTTP methods. The content-type that can be parsed includes “application/json”, “text/plain”, “multipart/form-data’’ and “application/x-www-form-urlencoded”. The “application/json” type is parsed into a list or map depending on the first character of the body. The “text/plain” will be parsed into a String object. Read More »

Client

Introduction The service-to-service communication can be done through a request/response style or messaging/event style in a microservices architecture. An efficient HTTP client is crucial in a request/response style as the number of interactions between services is high, and extra latency can kill the entire application performance, causing the failure of a microservices application. In the early days of light-4j, we had a client module based on Apache HttpClient and Apache HttpAsyncClient, which supported HTTP 1. Read More »

Cluster

This module caches all the service instances that are needed by the current service and calling underline registry(Direct, Consul and ZooKeeper) to discover the service if necessary (the first time a service is called, the registry notifies something has been changed regarding the subscription to services on Consul or ZooKeeper). Interface In this module, we have an interface called Cluster.java public interface Cluster { /** * give a service name and return a url with http or https url * the result is has been gone through the load balance with request key * * requestKey is used to control the behavior of load balance except * round robin and local first which this value is null. Read More »

Config

Config is a configuration module that supports externalized config in the official standalone deployment or docker container. It is encouraged that every module should have its own configuration file and that these files be served by light-config-server which aggregates/merges config files from a different level of organization in GitHub or other git servers. Introduction Externalized configuration from the application package is very important. It allows us to deploy the same package to the DEV/SIT/UAT/PROD environment with different configuration packages without reopening the delivery package. Read More »

Consul Client

Consul is a service registry implementation that uses HashiCorp Consul as a registry and discovery server. It implements both registry and discovery in the same module for Consul communication. The server module is responsible for registering itself during startup and deregistering during shut down. In some cases, if the server crashes, there is no chance for the server to invoke the deregister endpoint on the Consul agent. A health check must be configured to ensure that the Consul service catalog reflects the current status of the service instances. Read More »

Correlation Id

CorrelationId handler is part of the traceability of microservices architecture along with the traceabilityId handler that is used to index centralized logs collected from all containerized services or the original client. This is a middleware handler that checks if X-Correlation-Id exists in the request header. If it doesn’t exist it will generate a UUID and put it into the request header. During API to API calls, this header will be passed to the next API by the Client module. Read More »

CORS

If your API server serves a SPA (single page application) built on top of Angular or React, there is no issue when the SPA accesses APIs on the same server. However, some of the single page applications are served by another server on another domain. In this case, the API server has to handle the pre-flight options request in order to allow browser clients to access the APIs directly. Also, it has to handle the subsequent requests with the Origin header to match it with the cors. Read More »

Error Status

Introduction When deploying large-scale microservices in an organization, monitoring and alerting are very important for the operation team. The traditional way to monitor monolithic application logs to find potential error status is not feasible anymore. When all service logs are aggregated to the ELK or Splunk, we have a big melting pot of logging statements from different services. To dig useful information from it and identify problematic service instances is not an easy job. Read More »

Exception Handler

This is a middleware handler that should be put in the beginning of the request/response chain. It wraps the entire chain so that any unhandled exceptions will finally reach here and to be handled gracefully. It is encouraged to handle exceptions in business handlers because the context is clear and the exchange will be terminated at the right place. This handler is plugged in by default from light-codegen and it should be enabled on production as the last defence line. Read More »

Handler

An interface for middleware handlers. All middleware handlers must implement this interface so that the handler can be plugged into the request/response chain during server startup with SPI (Service Provider Interface). The entire light-4j framework is a core server that provides a plugin structure for hooking up all sorts of plugins to handle different cross-cutting concerns. The middleware handlers are designed based on the chain of responsibility pattern. MiddlewareHandler /** * A interface for middleware handlers. Read More »

Header Handler

When a request passes through a list of middleware handlers, chances are you want to update the request header or update the response header as part of the cross-cutting concerns. The HeaderHandler is designed for this. The very first use case is for light-proxy to update the Authorization header from Bearer token to Basic Authorization when connecting to downstream services. This allows light-proxy to verify the OAuth 2.0 JWT access token on the proxy and then change the same header to Basic so that the downstream services can be called from light-proxy. Read More »

Health Check

This is a server health check handler that outputs OK or a JSON object to indicate the server is alive. Normally, it will be used by F5/light-gateway/http-sidecar to check if the server is healthy before routing requests to it. The global registry will also use the same handler to ensure all instances are healthy for consumers to discover. Another way to check server health is to ping the IP and port, and it is the standard way to check server status for F5 or any reverse proxy servers. Read More »

Load Balance

The light-4j platform encourages client-side discovery in order to avoid proxies in front of multiple instances of services. This can reduce the network hop and subsequently reduce the latency of service calls. Client-side discovery needs a client-side load balancer to pick up one and only one available service instance from a list of available services for a particular downstream request during runtime. Currently, Round-Robin and LocalFirst have been implemented and ConsistentHashing is in progress. Read More »

Logger Config

Logger-config is a module in the Light-4j framework that will be used to get the loggers and their current logging levels. It can also change the logging level for given loggers at runtime (Example: Change logging level to DEBUG for “com.networknt” logger for troubleshooting purposes). The user can also create a brand new logger with a level for debugging issues for a specific package or class on the target server. Read More »

Mask

In the entire life cycle of the exchange, there might be a lot of logging statements written to log files or other persistence storage. These logs will be used to assist production issue identifying and resolving, and a broad group of people might have access to these logs. For confidentiality, sensitive info needs to be masked before logging, for example, credit card numbers, sin numbers, etc. StarupHookProvider The mask module depends on JsonPath which is a third party library that gives us access to the JSON strings easily. Read More »

Metrics

Introduction The metrics handler collects the API runtime information and reports it to Influxdb or Broadcom APM periodically (5 minutes to 15 minutes based on the volume of the API). For general info about the metrics, please visit here. The InfluxDB MetricsHandler is the first implementation and the default metrics handler in the light-4j frameworks. Configuration Here is an example of configuration in values.yml # metrics.yml metrics.enabled: true metrics.serverHost: localhost metrics. Read More »

Rate Limit

Although our framework can potentially handle millions of requests per second, some public-facing APIs might be a good idea to enable this handler to limit the concurrent requests to a certain level to avoid DDoS attacks. When the http-sidecar, light-router or light-proxy is used inside a corporate network for a slow backend API, this handler can be used to throttle the requests to protect the backend API from being overwhelmed. Read More »

Registry Discovery

This module contains all the interfaces needed in registry and discovery. It also implements a direct registry, which you can hard-code services into the service.yml or direct-registry.yml to simulate Consul or Portal Registry during development. Although this is for local development, many users are still using it during production when they have allocated services to the exact IP and port on virtual machines. Currently, Consul and portal-registry are supported for external service registry and discovery. Read More »

Request and Response Dump

This is a handler that dumps the entire request and response into a log file. It should only be used in development mode for debugging purposes as it is very slow. Introduction This handler can log HTTP request/response info based on configuration. This is a generic dump handler that may be useful for troubleshooting in a developing/testing environment. The dump request/response log file should be configured in logback.xml. The dumping request/response info format can be default format or json format depending on the configuration. Read More »

Sanitizer

Introduction This is a middleware handler that addresses cross-site scripting concerns. It encodes the header and body according to the configuration. As body encoding depends on BodyHandler middleware, it has to be plugged into the request/response chain after the body handler if the sanitizer.bodyEnabled is true in the values.yml If you use the http-sidecar or light-gateway, the sanitizer handler will only work with the headers. The body sanitization won’t work as the request body won’t be intercepted but transferred to the backend API directly. Read More »

Security

API security is paramount, and today most APIs don’t have security built-in at all but rely on third-party API gateways to handle the security at the network level. It assumes that it is safe within the organization or utilizes some firewall setup to ensure that only the Gateway server can access the service host. Once we move to the cloud, everything is dynamic, and firewalls won’t work anymore as services can be down on one VM but start in another VM immediately through container orchestration tools. Read More »

Server

This module is responsible for managing the life cycle of the embedded Undertow core HTTP server. It starts the server and initializes all middleware handlers/plugins along with a route handler provider when the handler chain is defined in the service.yml or OrchestrationHandler when the handler chains are defined in the handler.yml. It gracefully stops the server and allows the resources to be released and all in-flight requests to be processed before the server instance is deregistered on the service registry even someone clicks CTRL+C on the terminal. Read More »

Server Info

Introduction Almost every module in light-4j has a configuration file externalized with default in the module itself or the API implementation config folder. A special handler injected in your hander.yml gives an overview of the server runtime, system properties, specification, and configurations for each enabled module. Once this handler endpoint is called, it will output all the server info in a JSON format. Configuration info.yml # Server info endpoint that can output environment and component along with configuration # Indicate if the server info is enable or not. Read More »

Service

Why we reinvent the wheel While building a lightweight microservices platform, we need an IoC service to bind implementations to interfaces. Given light-4j has server startup and shutdown hooks, we usually only need to inject with a constructor injection during the server startup. We have evaluated several IoC containers and found them to be too heavy for my use cases. Also, most of them are still using XML as configuration or annotations which eliminate the benefit of configurable IoC. Read More »

Switcher

This module implement a switcher service interface and a local implementation. Switch is useful at system runtime to turn on or off some logic or service given certain conditions. For example, the light-4j server won’t stop handling requests but just switching off during server shutdown process. The service registry will be notified but in coming requests are still processed until all clients receives notification from service registry. Read More »

Traceability

For microservices architecture, a request sent from a client may pass through several services to the backend repository/Book of Record, and then a response is returned in the reverse path. If there is an error in the call tree, we need to identify where the problem is during runtime. Also, for some mission-critical applications, the entire call tree must be in the audit log to meet regulatory compliance requirements, for example, banking applications. Read More »

Utility

This module contains some useful classes that are shared by multiple modules within the light-* frameworks. Constants Contains all the constants shared by all modules. ModuleRegistry When the plugin modules are loaded, it will register itself to this module along with configuration. When /server/info is called, the endpoint will return all plugged in modules and their configurations. Util Some useful utility method like uuid generator etc. CollectionUtil Utility for collection Read More »

Zookeeper

A Zookeeper registry implementation uses Zookeeper as a registry and discovery server. It implements both registry and discovery in the same module for Zookeeper communication. If the API/server is delivered as a docker image, another product called registrator will be used to register it with Zookeeper server. Otherwise, the server module will be responsible to register itself during startup. Interface Here is the interface of ZooKeeper client. public interface ZooKeeperClient { void subscribeStateChanges(IZkStateListener listener); java. Read More »