Skip to content

# `special_rules`

PyFunceble tries to be as flexible as possible. This is why we now allow you to define special rules that PyFunceble should follow.

The special rules are defined in the `special_rules` section of the configuration file.

## Overview

.PyFunceble.overwrite.yaml

    special_rules:
      # Let end-user define or integrate their own special rules.
      #
      # The idea: We want to give the end-user the possibility to define their own
      # rules. This is useful when they want to switch the status of a subject based
      # on a specific pattern, header, body, or status code.
      #
      # The structure:
      #    subject_pattern:
      #      -> The pattern to match against the subject.
      #    validation_type:
      #      -> The type of validation to perform. It can be one of the following:
      #         - all: A combination of everything (first match wins).
      #         - status_code: Only the status code.
      #         - headers: Only the headers.
      #         - body: Only the body.
      #         - headers+body: Match against the headers and the body.
      #    state_transition:
      #      -> The state to switch to when the validation is successful.
      #         When set to `down`, the status will be switched to INACTIVE. When set
      #         to `up`, the status will be switched to ACTIVE.
      #    required_status_code:
      #      -> A list of status code to match against.
      #    required_headers_patterns:
      #      -> A dictionary of headers to match against. The key is the header name
      #         and the value is a list of patterns to match against.
      #    required_body_patterns:
      #      -> A list of patterns to match against the body.
      #
      # Examples:
      #    When testing httpbin.org, we want to switch the status to down when the
      #    status code is 403 and the server header contains "gunicorn".
      #
      #    - subject_pattern: "^httpbin\\.org$"
      #      validation_type: all
      #      state_transition: down
      #      required_status_code:
      #        - 403
      #      required_headers_patterns:
      #        server:
      #          - gunicorn
      #
      #    When testing example.org, we want to switch the status to down when the
      #    status code is 404.
      #
      #    - subject_pattern: "^example\\.org$"
      #      validation_type: status_code
      #      state_transition: down
      #      required_status_code:
      #        - 404
      #
      #    When testing example.com, we want to switch The body and headers.the status to down when the
      #    header `server` contains `nginx`.
      #
      #    - subject_pattern: "^example\\.com$"
      #      validation_type: headers
      #      state_transition: down
      #      required_headers_patterns:
      #        server:
      #          - nginx
      #
      #    When testing example.net, we want to switch the status to down when the
      #    body contains "Hello, World!".
      #
      #    - subject_pattern: "^example\\.net$"
      #      validation_type: body
      #      state_transition: down
      #      required_body_patterns:
      #        - Hello, World!
      #
      #    When testing example.dev, we want to switch the status to down when the
      #    headers server contains `nginx` or the body contains "Hello, World!".
      #
      #    - subject_pattern: "^example\\.dev$"
      #      validation_type: headers+body
      #      state_transition: down
      #      required_headers_patterns:
      #        server:
      #          - nginx
      #      required_body_patterns:
      #        - Hello, World!
      []

## Examples

### `validation_type`: `all`

When testing httpbin.org, we want to switch the status to down when the status code is 403 and the server header contains "gunicorn".

.PyFunceble.overwrite.yaml

    special_rules:
      - subject_pattern: "^httpbin\\.org$"
        validation_type: all
        state_transition: down
        required_status_code:
          - 403
        required_headers_patterns:
          server:
            - gunicorn

### `validation_type`: `status_code`

When testing example.org, we want to switch the status to down when the status code is 404.

.PyFunceble.overwrite.yaml

    special_rules:
      - subject_pattern: "^example\\.org$"
        validation_type: status_code
        state_transition: down
        required_status_code:
          - 404

### `validation_type`: `headers`

When testing example.com, we want to switch the status to down when the header `server` contains `nginx`.

.PyFunceble.overwrite.yaml

    special_rules:
      - subject_pattern: "^example\\.com$"
        validation_type: headers
        state_transition: down
        required_headers_patterns:
          server:
            - nginx

### `validation_type`: `body`

When testing example.net, we want to switch the status to down when the body contains `Hello, World!`.

.PyFunceble.overwrite.yaml

    special_rules:
      - subject_pattern: "^example\\.net$"
        validation_type: body
        state_transition: down
        required_body_patterns:
          - Hello, World!

### `validation_type`: `headers+body`

When testing example.dev, we want to switch the status to down when the header `server` contains `nginx` or the body contains `Hello, World!`.

.PyFunceble.overwrite.yaml

    special_rules:
      - subject_pattern: "^example\\.dev$"
        validation_type: headers+body
        state_transition: down
        required_headers_patterns:
          server:
            - nginx
        required_body_patterns:
          - Hello, World!