Lunar Interceptors

Overview

The Lunar Interceptor is a core component of Lunar's architecture, enabling seamless integration with Lunar Proxy.
It provides different methodologies for intercepting outgoing HTTP/S requests and capturing responses.
The Interceptor ensures efficient and lightweight operation, and allows Lunar Proxy do its work by covering the following functionalities:

1. Redirection - forward 3rd party API׳s HTTP/S requests to Lunar Proxy instead of original destination
   • Only outbound traffic will be redirected to Lunar Proxy.
   • To redirect Internal traffic, add the relevant host or IP to the Allow List
2. Fail-Safe - recover from failures originated in Lunar Proxy and set the request as unmodified, returning it back to its original state instead. You can refer it as a fallback mechanism as well.
   • See: Failsafe Mechanism

Our Interceptors are designed to run as close as possible to our user's code and need to be as light as possible so they don׳t increase any resources consumption.

note

The communication between Lunar Interceptor and Lunar Proxy is not encrypted (HTTP).

Direct Mode - No Installation Needed

Direct Mode in Lunar Proxy allows you to route your HTTP requests through the Lunar Proxy without needing any interceptor installation. This mode works by simply modifying your HTTP requests with specific headers and altering the request URL. More information about the Direct Mode can be found here.

Installation

The simplest installation process is through the Lunar Control Plane. Once the Control Plane is launched, begin by installing a Lunar Proxy. Next, follow the step-by-step instructions prompted upon clicking the "Continue" button. From the graphical user interface (GUI), select the appropriate Interceptor type tailored to your software environment. After selecting the desired Interceptor, follow the guided steps provided by the GUI.

To access manual installation instructions, click on the name of the Lunar Interceptor located on the left-hand side of the documentation.

Supported Languages

Language	Support	Frameworks
Python	Python3+	AioHttp 3.8.3+ Requests v2.15.1+ Tornado 6.0+
Java	SDK8+	OkHTTP 3.14.9+
Node.js	Nodejs v18.0.0+ Nodejs v16.0.0+ Nodejs v15.7.0+ Nodejs v14.18.0+	Axios v1.0.0+ http\https\fetch (v18+)
eBPF	Coming Soon

How it works?

1. Lunar Interceptor captures outgoing HTTP/S requests on the application layer.
2. Forward the HTTP/S requests through Lunar Proxy.
3. Lunar Proxy does its magic and sends the request (if needed to the original destination).
4. Lunar Proxy receives the response.
5. Lunar Proxy returns the response to Lunar Interceptor.
6. Lunar Interceptor returns the response to the application seamlessly as expected.

In case of an error while using Lunar Proxy, the Interceptor will use the original destination instead.

Failsafe Mechanism

Lunar designed a Failsafe Mechanism to avoid downtime or point of failure if something goes wrong between the interceptor and proxy in the rare case when the proxy is not available.

In case the pre-configured number of failed connection attempts to the Proxy was exceeded, a cooldown period will be initiated during which all the traffic will be directed to the original Provider.

If a connection still can not be restored after the cooldown period ended, then the Failsafe Mechanism will initiate another cooldown period after a single connectivity error.

By using this approach, the Failsafe Mechanism ensures that traffic flow is uninterrupted, and any possible delay is minimized. Additionally, the use of configurable cooldown and failed attempt parameters provides the flexibility to adjust the system according to specific needs.

note

If not configured the Failsafe Mechanism will load with the following default values

LUNAR_ENTER_COOLDOWN_AFTER_ATTEMPTS="5"
LUNAR_EXIT_COOLDOWN_AFTER_SEC="10"

Identifying Your Consumer by the x-lunar-consumer-tag Header

Lunar supports the ability to identify and segment requests based on the x-lunar-consumer-tag header. This feature allows users to add a custom header to their HTTP requests, enabling better visibility and control in Lunar Control Plane.

When a request is sent with the x-lunar-consumer-tag header, Lunar Proxy captures this header and uses it for segmentation and filtering:

• Segmentation: In the discovery command, Lunar segments results by different consumer tags, providing a detailed view of traffic per consumer. For example, requests tagged with x-lunar-consumer-tag: example-app will be grouped under the example-app consumer segment.
• Filtering: In the control plane dashboards, users can filter views according to specific consumer tags. This allows for more focused monitoring and troubleshooting based on the origin of requests. Implementation

To use this feature, add the x-lunar-consumer-tag header to your outgoing HTTP requests. The header value should be a short, informative string indicating the name of the application, service, or job from which the request originated.

note

The x-lunar-consumer-tag header (as with any other header prefixed with x-lunar-) will be removed from the request before it is sent to a third-party provider. This ensures that the header is used solely for internal purposes within the Lunar ecosystem and does not affect the behavior of external APIs.

Configuration

• To configure the Lunar Interceptor, refer to our Configuration Guide

Validation

During the loading process, Lunar Interceptor attempts to establish a connection with the Lunar Proxy. By default, there is no explicit indication if the connection is successful. However, in the event of an error while trying to communicate with the Lunar Proxy, Lunar Interceptor will generate an error message and print it to the stdout. This error message serves as an indication that something has deviated from the expected behavior.

Additionally, if the interceptor is operating in debug mode, there may be additional logging or indicators provided to help identify the status of the connection to the Lunar Proxy.

Troubleshooting and FAQs

• If you encounter any issues or require additional assistance, check out our Frequently Asked Questions or shoot us an email at info@lunar.dev.