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.

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 »

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 »

Jwt Verifier

This is a class in the security module in the light-4j repository. It is responsible for verifying a JWT token passed from the authorization header in a request. If your consumer is using a simple web token, please refer to the SwtVerifier handler. The following validations are performed in the handler: Expiration Signature Audience For some cloud OAuth 2.0 providers, there is only one tenant for an organization with multiple APIs and consumers. Read More »

Router Handler

The router handler is the primary handler of the http-sidecar and light-gateway. It is responsible for forwarding requests to different backend APIs according to the calculated serviceId or serviceURL. Read More »

Response Transformer Interceptor

Request Transformer Interceptor

Response Body Interceptor

Request Body Interceptor

Request Body Interceptor is an interceptor implementation that is injected into the request/response chain via the RequestInterceptorInjectionHandler. There are to light-4j built-in request interceptors. RequestBodyInterceptor is used to intercept the request body in the http-sidecar and light-gateway to support the body transformation and log the request body into the audit log for debugging. RequestTransformerInterceptor is used to transform the request body to another format in order to bridge the difference between the consumer and provider. 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 »

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 »

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 »

Response Interceptor Injection Handler

Request Interceptor

Request Interceptor Injection Handler

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 »

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 »

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 »

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 »

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 »

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 »

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 »

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 »