Skip to main content
Version: 0.8.x

Lunar Interceptors


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.

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.


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

Supported Languages​

  • Python3+
  • SDK8+
  • Nodejs v16.0.0+
  • Nodejs v15.7.0+
  • Nodejs v14.18.0+
  • Coming Soon

Direct Mode​

Direct mode enables routing requests through Lunar’s Proxy without requiring any interceptor to be installed. More information about the Direct Mode can be found here.

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.

"Modified design elements from [Tool] Cloud Diagram Activity, Figma Community Resources Original resource: Creator: Scaleway Copyright Β© Scaleway Licensed under CC BY 4.0,"

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.


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




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​

Click me for guidance πŸ˜€