Skip to main content
Version: Next

Lunar Interceptor

You can install the Lunar Interceptor either via the Lunar Control Plane for a guided process or manually by following the specific installation documentation for your environment.

Supported Languages:

  • Python: Python 3+, AioHttp 3.8.3+, Requests v2.15.1+, Tornado 6.0+
  • Java: SDK8+, OkHTTP 3.14.9+
  • Node.js: Node.js v14.18.0+, v15.7.0+, v16.0.0+, v18.0.0+, Axios v1.0.0+, http/https/fetch (v18+)

How Lunar Interceptors Work​

Lunar Interceptors capture outgoing HTTP/S requests from your application, route them through the Lunar.dev Gateway, and return the API provider's response back to the application. If the Gateway is unavailable, traffic defaults to the original destination.

For more details on the Failsafe Mechanism, refer to the Failsafe Mechanism documentation.

Interceptor Installation and Configuration​

Installation:

pip3 install 'lunar-interceptor==0.4.*'

Configuration:

The only required configuration is the LUNAR_PROXY_HOST environment variable. This variable should be set to the host or IP of Lunar Proxy, including the port it is listening on.

For example:

export LUNAR_PROXY_HOST="localhost:8000"

note

This environment variable sets the host and port for Lunar Gateway. Set this to localhost:8000 if you're running Lunar Proxy in a local Docker container. The value assigned to LUNAR_PROXY_HOST should only include the hostname and port, without the HTTP prefix. For example, use localhost:8000 and not http://localhost:8000.

Usage​

Import Lunar Interceptor into the application entry point at the beginning of the file.

import lunar_interceptor
# imports ...

# your code
def main():

Run Your App and Validate Proxy/Interceptor Linkage​

Run your app and consume API traffic. Then, use the Discover command to validate that the requests were passed through Lunar Proxy, and that your installed interceptor is correctly listed.

kubectl exec <lunar-proxy-pod-name> -- discover

Java-Specific Usage: Enable the instrumentation agent by using the -javaagent flag with the JVM.

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/lunarInterceptor.jar"

Or

java -javaagent:PATH/TO/lunarInterceptor.jar -jar PATH/TO/YOURS.jar

[Optional] Controlling Traffic Forwarding with the x-lunar-allow Header​

You can manage whether traffic is routed through the Lunar.dev API Consumption Gateway by using the x-lunar-allow header. Ensure that the value of this header is passed as a string:

  • "true": The Interceptor forwards the request to the Lunar.dev API Consumption Gateway.
  • "false": The Interceptor bypasses the gateway and sends the request directly to the API provider.

[Optional] Identifying Your Consumer by the x-lunar-consumer-tag Header​

Add the x-lunar-consumer-tag header to your requests with a value indicating the originating application or service. This header will be removed before the request is forwarded to third-party providers.