feat!: if conditional statements for error pipeline mechanisms

[dadrus]

Related issue(s)

closes #1048

Checklist

• I agree to follow this project's Code of Conduct.
• I have read, and I am following this repository's Contributing Guidelines.
• I have read the Security Policy.
• I have referenced an issue describing the bug/feature request.
• I have added tests that prove the correctness of my implementation.
• I have updated the documentation.

Description

This PR removes support for the when clause in the configs of the available error handler mechanisms and makes the if clause available as already supported for the regular pipeline mechanisms as requested in #1048.

So the following error pipeline definition

error_handlers:
- id: basic_authenticate
  type: www_authenticate
  config:
    realm: "My fancy app"
    when:
      - error:
          - type: precondition_error
            # OR
          - type: authorization_error
            raised_by: basic_auth_authenticator
        # AND
        request_cidr:
          - 192.168.0.0/16
             # OR
          - 10.0.0.0/8
        # AND
        request_headers:
          accept:
            - text/html
              # OR
            - text/plain
          # OR
          Content-Type:
            - application/json

would become

error_handlers:
- id: basic_authenticate
  type: www_authenticate
  config:
    realm: "My fancy app"
  if: |
    (type(Error) == precondition_error ||
     type(Error) == authorization_error && Error.Source == "basic_auth_authenticator") &&

     // some of the IPs in Request.ClientIPAddresses array come from the given networks
     Request.ClientIPAddresses.exists(ip, ip in networks(["192.168.0.0/16", "10.0.0.0/8"])) &&

    (req.Header("Accept").matches("(text/html|text/plain)") || 
     Request.Header("Content-Type").contains("application/json"))

as in the past, only the error handler of the default type does not require execution conditions to be specified.

As can be seen form the above example, there are some new objects, the CEL expressions can make use of:

• Error object, supporting the following property:

  • Source property giving access to the ID of the mechanism which raised that error.

• type(Error) returns the type of the Error object and supports the operators

  • == and != to allow checking if an error is either one or another type, like shown in the example above.
    If you need to check just types, like type(Error) == precondition_error || type(Error) == authorization_error, you can simplify it with type(Error) in [precondition_error, authorization_error]

  The error types, one can check the Error type object against are the authentication_error, authorization_error, communication_error, internal_error and the precondition_error types (as already available to the yaml based error pipeline definition).

• networks() function accepting either a single CIDR or an array of CIDR definitions, e.g. networks("10.0.0.0/16") or networks(["10.0.0.0/16", "172.0.0.0/16"]). The created objects are singletons (for the given CIDR/CIDRs) and supports/exposes the following operators:

  • in (Containment) to check whether a specific IP or all IPs from an array do come from the given networks. Latter you can see in action in the example above (Request.ClientIPAddressesis a property containing the IP addresses of all known network hops - from the IP of the ultimate client to the IP of the service, which forwarded the request to heimdall.)

  To check if only a specific address from the given set comes from a specific network or a set of networks, one can use existing macros, like
  ["192.168.1.10", "10.0.1.1"].exists(ip, ip in networks(["10.0.0.0/16", "172.0.0.0/16"]))
  Since networks(["10.0.0.0/16", "172.0.0.0/16"]) returns a singleton for the given CIDRs, there is no performance penalty in place.

To check whether a specific header is set to a particular value or contains a specific mime type, you can just use the available string related functions, like also shown in the example above.

[codecov]

Codecov Report

Attention: 60 lines in your changes are missing coverage. Please review.

Comparison is base (0f9484f) 89.56% compared to head (31d2300) 89.14%.

❗ Current head 31d2300 differs from pull request most recent head ee3bd16. Consider uploading reports for the commit ee3bd16 to get more accurate results

Files	Patch %	Lines
internal/rules/mechanisms/cellib/networks.go	58.41%	35 Missing and 7 partials ⚠️
internal/rules/mechanisms/cellib/errors.go	81.48%	15 Missing ⚠️
...les/mechanisms/errorhandlers/base_error_handler.go	88.00%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1055      +/-   ##
==========================================
- Coverage   89.56%   89.14%   -0.42%     
==========================================
  Files         248      245       -3     
  Lines       10217    10265      +48     
==========================================
  Hits         9151     9151              
- Misses        833      877      +44     
- Partials      233      237       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.