[proposal] Redesign Custom Response Configuration

[dwisiswant0]

Summary

This proposal outlines the design changes for configuration related to custom response handling. The primary modifications involve introducing a new structure for custom response headers and replacing the html and html_file fields with content and content_file, and expression support for dynamic content generation. Additionally, it suggests the inclusion of placeholders for dynamic content generation in the response.

Motivation

The motivation behind this proposal is to enhance the flexibility and functionality of custom response configuration for rejected requests. Users can set custom headers as needed by introducing response headers as a map. The shift from html to content and content_file allows for arbitrary content types by enabling users to specify the Content-Type header. Introducing placeholders in the response content empowers users to create dynamic responses tailored to specific conditions, improving the versatility of teler-waf.

Design

The proposed design changes are as follows:

1. Custom Response Headers

Introduce a new field in the configuration called headers, which is of type map[string]string. Users can define custom response headers using this map. This change allows for greater control over the HTTP response.

2. Content Handling

Substitute the existing html and html_file fields with content and content_file. The content field is designed to accommodate response content as a string, while content_file provides the flexibility for users to specify a file from which the response content can be sourced. These updates enhance the configuration's ability to effectively manage a wide range of content types. Furthermore, these changes introduce support for expressions, enabling the creation of dynamic response content that can be tailored to specific conditions.

Consequently, the use of the DefaultHTMLResponse will be deprecated.

3. New Placeholders

To support dynamic content generation, introduce placeholders within the response content. Placeholders like {{request.Method}}, {{request.Path}}, {{request.URI}}, {{request.Headers}}, and {{request.IP}} can be used to inject request-related information into the response. This enhances the ability to tailor responses based on specific conditions.

Example

Marshalled in YAML.

# ...
response:
    status: 403
    headers:
        X-Custom-Header: foo
        X-New-Header: bar
        Content-Type: text/html
    content: |
        {{ if request.Path == "/login" && request.Method == "POST" }}
            Your request has been denied for security reasons. Ref ID: {{ID}}.
        {{ else }}
            You have been blocked from accessing our website. Contact support to unblock. (IP: {{request.IP}})
        {{ end }}
    content_file: ""
# ...

Drawbacks

The primary drawback is that these changes may require existing users to update their configurations to align with the new structure. This may temporarily cause compatibility issues for those upgrading from older versions.

Alternative Approaches

An alternative approach would be to keep the existing configuration structure as it is. However, this would limit the flexibility and customization options available to users. The proposed changes aim to provide a more versatile.

Unresolved Questions

TBD