Content rewriting

A typical way of integrating services with a reverse-proxy ist to rewrite content before it is delivered to clients. For instance, internal URLs must be translated to external URLs. The Airlock Microgateway offers different rewriting options in section apps[].mappings[].response.rewrites:

  • Rewrite types
  • location_header
  • html (for HTML content)
  • any (for any content types)
  • json (for JSON content)

For a comprehensive list of options for the different rewrite types, please refer to the DSL reference .

Rewrite response redirect location header

Rewrite option to modify the HTTP redirect location header sent from the back-end server before it is sent to the client. Rewriting the location redirect header may be necessary if the application creates absolute or incorrect location headers because it is not reverse proxy compatible.

This example translates absolute and relative back-end URLs into an external absolute path.

apps:
- mappings:
  - name: test
    response:
      rewrites:
        location_header:
            - url:
                pattern: "^(https?://%BACKENDHOST%)?/%BACKENDPATH%(/.*)?$"
              to: "/%ENTRYPATH%$2"
   

Rewrite response body (HTML only)

In addition to rewriting HTTP header fields Airlock Microgateway also provides a powerful HTML content rewriting engine. Rewriting HTML content may be necessary to modify URLs in the HTML content if the application creates absolute or incorrect links because it is not reverse proxy compatible.

For each rule, the following options can be selected:

  • URI (apply rule to linked HTML elements like href, src, etc.)
  • Events (apply rule to JavaScript event strings such as onsubmit, onload, etc.)
  • Embedded (apply rule to <script> and <style> blocks embedded in the HTML page)

Note: The options Events and Embedded apply the rule to text elements that may contain other text than just a URL. To help Airlock Microgateway correctly detect URLs within that text, the following syntax should be used. The type specifier ?<URL> right after the opening parenthesis indicates a URL. If URL encryption is enabled, this URL will also be encrypted.

The following example replaces absolute image references by references using the actual entry path:

apps:
- mappings:
  - name: test
    response:
      rewrites:
        html:
        - url:
            pattern: "^/images(/.*)?"
          to: "/%ENTRYPATH%/images$1"
          options: "url"

Rewrite response body (any content)

In addition to rewriting the response body for HTML, where the HTML parser of Airlock Microgateway lets you define rewrite rules for different semantic parts of HTML, such as URLs and JavaScript, you can configure Microgateway to generally rewrite the body of HTTP responses.

To specify what bodies shall be rewritten, each rule is accompanied by a Content type field. If a HTTP request or response contains a Content-Type header that matches the regular expression in that field, the rule will be applied.

Note: The rewrite rules will be executed in sequence if the content type field is identical – the relative order of rewrite rules with the same regular expression in the content type field is essential. If the content type field differs, but matches in both cases, the order is undefined.

The following example rewrites URLs in CSS import statements, both in HTML and CSS documents:

apps:
- mappings:
  - name: test
    response:
      rewrites:
        any:
        - content_type: "^(?:text|application)/(?:html|xhtml|css)"
          content:
            pattern: "(@import[\h\v]*["'])(?<URL>[^"']+)(["'])"
          to: "$1$2$3"

Rewrite response body (JSON)

Airlock Microgateway provides a JSON content rewriter for values in JSON documents.

  • Recommended use:
  • Use JSONPath (XPath for JSON) and content pattern (which work as regular expressions) to rewrite any URLs of the JSON content.

To define which field to rewrite, JSON Path syntax is used.

JSON Document:

  { 
    "data": { 
        "services": [ 
            { 
                "name": "path1", 
                "url": "http://backend-server/path1" 
            }, 
            { 
                "name": "path2", 
                "url": "http://backend-server/path2" 
            } 
        ] 
    } 
  }

JSON Paths:

  * $.data.services[0].name 
    selects the value "path1" 
  * $.*.services[0].name 
    selects the value "path1" 
  * $.data.services[:].name 
    selects the values ["path1", "path2"] 
  * $..url 
    selects all URLs

The following example translates absolute back-end URLs in JSON objects to external paths:

apps:
- mappings:
  - name: test
    response:
      rewrites:
       json:
       - path: "$..url"
         content:
            pattern: "^(https?://%BACKENDHOST%)?/%BACKENDPATH%(/.*)?$"
         replace: "/%ENTRYPATH%$2"