Third-Party Service Degradation/Asynchronous Gateway Plugin

Configure TOML routing rules on the gateway to implement timeout service degradation for third-party APIs and convert synchronous time-consuming interfaces to asynchronous ones.

Usage

Install Gateway and Plugin

yum install -y yum-utils

# For CentOS 8 or older
yum-config-manager --add-repo https://openresty.org/package/centos/openresty.repo
# For CentOS 9 or later
yum-config-manager --add-repo https://openresty.org/package/centos/openresty2.repo

yum install -y openresty
yum install -y openresty-opm openresty-resty

opm get sssxyd/lua-resty-downgrade

systemctl enable openresty

Edit Routing Rule File

vim /path/to/your_router_rules.toml

["/thirdpart/user/getPageData"]
# Requests for this route adapt to the timeout service degradation mode
type = "timeout"

# Upstream service address, supports https
backend_url = "http://127.0.0.1:8080"

# Timeout duration in milliseconds
timeout_ms = 250

# HTTP status code returned after timeout service degradation is triggered (default is 200)
#status_code = 200

# Content-Type returned after timeout service degradation is triggered (default is JSON)
#content_type = "application/json; charset=utf-8"

# Body content returned after timeout service degradation is triggered
resp_body = '''
{
    "code": 0,
    "msg": "success",
    "result": {
        "total": 0,
        "data": []
    }
}
'''

["/thirdpart/traffic/getTrafficNo"]
# Requests for this route adapt to the synchronous-to-asynchronous mode
type = "callback"

# Upstream service address, supports https
backend_url = "http://127.0.0.1:8080"

# Header name in the current request that stores the callback URL, default: X-Callback-Url
# The value of this header can be empty
#callback_url_header = "X-Callback-Url"

# Header name in the current request that stores the callback credentials, default: X-Callback-Credentials
# The value of this header can be empty
#callback_credentials_header = "X-Callback-Credentials"

# Callback URL to which the service will POST JSON data
# It first attempts to retrieve the callback URL from the request header, and if not set, falls back to this URL.
# If neither is provided, no callback will be triggered.
callback_url = "http://192.168.1.1:8281/handle_callback"

# HTTP status code returned immediately after triggering synchronous-to-asynchronous mode (default is 200)
#status_code = 200

# Content-Type returned immediately after triggering synchronous-to-asynchronous mode (default is JSON)
#content_type = "application/json; charset=utf-8"

# Body content returned immediately after triggering synchronous-to-asynchronous mode
resp_body = '''
{
    "code": 0,
    "msg": "success",
    "result": {
        "trafficno": "test"
    }
}
'''

Configure the Server Block

vim /usr/local/openresty/nginx/conf/nginx.conf

server {
    listen 8888;
    server_name _;
    root /usr/local/openresty/nginx/html;
    
    charset utf-8;
    index index.php index.html index.htm;

    access_log /var/log/nginx/access.downgrade.log  main;
    error_log /var/log/nginx/error.downgrade.log;

    autoindex off;

    # Static files and other path requests
    location / {
        try_files $uri $uri/ /index.html?$query_string;
        proxy_pass  http://127.0.0.1:8080; 
    }

    # Timeout degradation / synchronous-to-asynchronous
    location /thirdpart/ {
        access_by_lua_block {
            local downgrade = require "resty.downgrade"
            downgrade.load_rules("/path/to/your_route_rules.toml")
            downgrade.proxy_pass(ngx.var.uri)
        }
        # Pass through for unsupported interfaces
        proxy_pass  http://127.0.0.1:8080; 
    }
}

JSON Data Format for Callback Function

Field	Type	Description
request_time	float	The UNIX timestamp when the gateway receives the request
request_uri	string	The request path
request_params	object	Parameters of the request, parsed from the GET query string or POST FormData/JSON body
request_body	string	The request body. If request_params is successfully parsed, this field will be an empty string
callback_credentials	string	Callback credentials set via HTTP headers by the client
response_time	float	The UNIX timestamp when the gateway receives feedback from the upstream service
response_status_code	int	HTTP status code returned by the upstream service
response_http_headers	object	HTTP headers returned by the upstream service
response_body	string	HTTP response body returned by the upstream service

Plugin Function Table

Function Name	Required	Description
load_rules(toml_path)	Yes	Loads routing configuration from the specified toml_path. This method uses caching and will only load once.
proxy_pass(uri)	Yes	Finds the corresponding rule for the URI from the routing configuration and executes it. If no rule is found, the request passes through directly.
set_http_timeout(timeout)	No	Sets the timeout duration (in milliseconds) for HTTP requests created by the gateway. Default is 60,000 milliseconds.
set_http_keepalive(timeout, pool_size)	No	Sets the keepalive timeout duration (in milliseconds) and connection pool size for HTTP requests created by the gateway. Defaults are 60,000 milliseconds and a maximum of 15 connections.