Request Transformer Advanced Policy

This Policy lets you configure transformations of requests before AI Gateway forwards them to the upstream provider. These transformations can be simple substitutions or complex ones. For example, complex transformations can match portions of incoming requests using regular expressions, save those matched strings into variables, and substitute those strings into transformed requests using flexible templates.

This Policy operates on the raw HTTP request only: headers, query string, and body fields. To transform a request based on its meaning using an LLM (for example, rewriting a prompt), use the AI Request Transformer Policy instead.

Note: The X-Forwarded-* fields are non-standard header fields written by Nginx to inform the upstream about client details and can’t be overwritten by this Policy. If you need to overwrite these header fields, see the Post-Function Policy.

The Request Transformer Advanced Policy provides features that aren’t available in the Request Transformer Policy, including the ability to limit the list of allowed parameters in the request body with the config.allow.body parameter.

The Policy performs the transformations in the following order:

1. Remove
2. Rename
3. Replace
4. Add
5. Append
6. Allow

You can use any of the current request headers and query parameters as templates to populate supported configuration fields.

To escape a template, wrap it inside quotes and pass inside another template. For example:

$('$(something_that_needs_to_escaped)')

Note: The Policy creates a non-mutable table of request headers and query strings before transformation. Therefore, removing or updating any parameters used in a template doesn’t affect the rendered value of a template.

Advanced templates

The content of the placeholder $(...) is evaluated as a Lua expression, so you can use logical operators. For example:

$(query_params["user"] or "unknown")

This example looks for a query parameter named user. If it doesn’t exist, it returns the default value "unknown".

Constant parts can be specified as part of the template outside the dynamic placeholders. For example, this creates a basic-auth header from a query parameter called auth that only contains the base64-encoded part:

Basic $(query_params["auth"])

Lambdas are also supported if wrapped as an expression like this:

$((function() ... implementation here ... end)())

Here’s a complete Lambda example for prefixing a header value with Basic if it’s not already included:

$((function()
    local value = headers.Authorization
    if not value then
      return
    end
    if value:sub(1, 6) == "Basic " then
      return value            -- was already properly formed
    end
    return "Basic " .. value  -- added proper prefix
  end)())

The environment is sandboxed, meaning that Lambdas won’t have access to any library functions, except for the string methods (like sub() in this example).

Note: Make sure not to add any trailing whitespace or newlines, especially in multi-line templates. These would be outside the placeholders and would be considered part of the template, and hence would be appended to the generated value.

The Policy allows navigating complex JSON objects (arrays and nested objects) when config.dots_in_keys is set to false (the default is true):

• array[*]: Loops through all elements of the array.
• array[N]: Navigates to the nth element of the array (the index of the first element is 1).
• top.sub: Navigates to the sub property of the top object.

These can be combined. For example, config.remove.body: customers[*].info.phone removes all phone properties from inside the info object of all entries in the customers array.

Body transformations are only performed for requests where the Content-Type header is set to application/json.

Define which JSON body fields a client can send, then move a query parameter into the body before AI Gateway forwards the request upstream:

ai_gateway_policies:
  - ref: transform-multiple-request-elements
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Transform multiple request elements
    name: transform-multiple-request-elements
    type: request-transformer-advanced
    enabled: true
    global: false
    config:
      allow:
        body:
        - customer_id
        - customer_name
        - customer_zipcode
      remove:
        querystring:
        - customer_id
      add:
        body:
        - customer_id:$(query_params["customer_id"])

Make sure to replace the following placeholders with your own values:

• AI_GATEWAY_ID: The id of your AI Gateway.