exit-transformer Enterprise

The exit-transformer plugin supports the customization of gateway responses based on the status codes, headers, and bodies returned from APISIX plugins. When configured as a global plugin, it also supports the response customization when a route that does not exist is requested.

The transformation logics are defined in the plugin using Lua functions, following the syntax:

return (function(code, body, header) if {{ condition }} then return {{ modified_resp }} end return code, body, header end)(...)

Examples​

The examples below demonstrate how you can use exit-transformer for different scenarios.

Modify 404 Route Not Found Response​

The following example demonstrates how you can use the plugin to update the 404 Not Found response code and header when the route does not exist. In this case, the plugin needs to be configured as a global rule plugin.

Create a global rule with the exit-transformer plugin, in which the function updates the response status code to 405 and add a custom X-Custom-Header header if the original status code was 404:

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "transform-404-not-found",
    "plugins": {
      "exit-transformer": {
        "functions": ["return (function(code, body, header) if code == 404 then header[\"X-Custom-Header\"] = \"Modified\" return 405, body, header end return code, body, header end)(...)"]
      }
    }
  }'

Send a request to a route that does not exist:

curl -i "http://127.0.0.1:9080/non-existent"

You should receive an HTTP/1.1 405 Not Allowed response and observe the X-Custom-Header: Modified header.

Modify 401 Unauthorized Response for Failed Authentication​

The following example demonstrates how you can use the plugin to update the 401 Unauthorized response when authentication fails.

Create a route with the exit-transformer plugin, in which the function updates the response status code to 402 if the original status code was 401; and enable key-auth:

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "transform-auth-route",
    "uri": "/get",
    "plugins": {
      "exit-transformer": {
        "functions": ["return (function(code, body, header) if code == 401 then return 402, body, header end return code, body, header end)(...)"]
      },
      "key-auth":{}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Create a consumer john:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "john"
  }'

Configure key-auth credential for the consumer:

curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    }
  }'

Send a request to the route without the credential:

curl -i "http://127.0.0.1:9080/get"

You should receive an HTTP/1.1 402 Payment Required response for unauthorized access, where the response status code has been modified.

Modify Response Conditionally on Request Headers​

The following example demonstrates how you can use the plugin to conditionally modify responses based on request headers.

Create a route with the exit-transformer plugin, in which the function updates the response status code by Content-Type header. If the header value is application/json and the original status code is 404, update the response status code to 405. Print warning messages inside and outside the condition evaluation for demonstration purpose.

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "transform-by-header-condition",
    "plugins": {
      "exit-transformer": {
        "functions": [
          "return
            (function(code, body, header, ctx)
              local core = require(\"apisix.core\")
              local ct = core.request.headers(ctx)[\"Content-Type\"]
              core.log.warn(\"exit transformer logics running outside the condition\")
              if ct == \"application/json\" and code == 404 then
                core.log.warn(\"exit transformer logics running inside the condition\")
                return 405
              end
                return code, body, header
              end)
          (...)"
        ]
      }
    }
  }'

Send a request to a route that does not exist, without any header:

curl -i "http://127.0.0.1:9080/non-existent"

You should receive an HTTP/1.1 404 Not Found response and see the following message in the log:

exit transformer logics running outside the condition

Send a request to the non-existent route with the JSON Content-Type header:

curl -i "http://127.0.0.1:9080/non-existent" -H "Content-Type: application/json"

You should receive an HTTP/1.1 405 Not Allowed response, where the response status code has been modified, and see the following message in the log:

exit transformer logics running outside the condition
exit transformer logics running inside the condition