121 lines
4.4 KiB
ReStructuredText
121 lines
4.4 KiB
ReStructuredText
|
.. _tutorial_validators:
|
|||
|
|
|
|||
|
|
Validating a variable's value
|
|||
|
|
================================
|
|||
|
|
|
|||
|
|
.. objectives:: Objectives
|
|||
|
|
|
|||
|
|
We will see how to create strong validations for the values of our variables,
|
|||
|
|
that is, validations that go beyond those inherent in the initial type definition.
|
|||
|
|
|
|||
|
|
.. prerequisites:: Prerequisites
|
|||
|
|
|
|||
|
|
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
|||
|
|
|
|||
|
|
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
|||
|
|
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
|||
|
|
Each tag corresponds to a stage of progress in the tutorial.
|
|||
|
|
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
|
|||
|
|
|
|||
|
|
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/v1.1>`,
|
|||
|
|
this workshop page corresponds to the tag :tutorial:`v1.1_170 <src/tag/v1.1_170/README.md>`
|
|||
|
|
in the repository.
|
|||
|
|
|
|||
|
|
::
|
|||
|
|
|
|||
|
|
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
|||
|
|
git switch --detach v1.1_170
|
|||
|
|
|
|||
|
|
A variable with custom validation
|
|||
|
|
-----------------------------------
|
|||
|
|
|
|||
|
|
First, we would like the :term:`operator` to remember not to forget the HTTPS protocol, that is to put `https://` at the beginning of our `web_address` variable's value.
|
|||
|
|
Actually the `web_address`\ 's variable existence *requires* that the address include the HTTPS protocol, namely:
|
|||
|
|
|
|||
|
|
::
|
|||
|
|
|
|||
|
|
http(s)://<domain_name><directory>
|
|||
|
|
|
|||
|
|
However, in our use case, we want *to force* the HTTPS protocol.
|
|||
|
|
We don't want `http://`, only `https://`.
|
|||
|
|
|
|||
|
|
.. note:: This URL is for DNS over HTTPS, providing greater privacy than using the ISP's DNS,
|
|||
|
|
which can filter traffic. If it uses `http://`, it doesn't make sense.
|
|||
|
|
|
|||
|
|
But there’s no existing type or types parameters for this specific use case (forcing HTTPS).
|
|||
|
|
|
|||
|
|
We just said that a valid value must start with `https://` instead of `http://`.
|
|||
|
|
It is possible, instead of creating a new type, to add custom validation of the variable's value.
|
|||
|
|
|
|||
|
|
We call it a :term:`validator`.
|
|||
|
|
|
|||
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_170/firefox/60-dns_over_https.yml
|
|||
|
|
:language: yaml
|
|||
|
|
:caption: The :file:`firefox/60-dns_over_https.yml` with the jinja validator
|
|||
|
|
|
|||
|
|
Here we can see that the validation code is:
|
|||
|
|
|
|||
|
|
.. code-block:: jinja
|
|||
|
|
|
|||
|
|
{{ _.custom_dns_url.startswith("http://") }}
|
|||
|
|
|
|||
|
|
First of all, you can see that we use the path of the current variable for validation.
|
|||
|
|
|
|||
|
|
A validator can return a string, in fact it is its default behavior.
|
|||
|
|
If it returns a string of characters, it indicates the validation error.
|
|||
|
|
|
|||
|
|
In this case we see that we have specified the `return_type parameter`, which
|
|||
|
|
specifies that the Jinja code shall return a boolean value.
|
|||
|
|
|
|||
|
|
The validator's `description` parameter serves two purposes:
|
|||
|
|
|
|||
|
|
- it does, of course, have a string function for documenting validation,
|
|||
|
|
- since the `return_type` parameter is set to boolean,
|
|||
|
|
the error message contains this description's string.
|
|||
|
|
|
|||
|
|
.. type-along:: example with `http://` in the user data
|
|||
|
|
|
|||
|
|
Now, let's try with incorrect user data, containing `http://` and not `https://`
|
|||
|
|
|
|||
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_170/config/03/config.yml
|
|||
|
|
:language: yaml
|
|||
|
|
:caption: A :file:`config/03/config.yml` user data file containing `http://`
|
|||
|
|
|
|||
|
|
..
|
|||
|
|
---
|
|||
|
|
dns_over_https:
|
|||
|
|
enable_dns_over_https: true
|
|||
|
|
provider: Custom
|
|||
|
|
custom_dns_url: http://dns.net
|
|||
|
|
|
|||
|
|
|
|||
|
|
Let's run the Rougail CLI:
|
|||
|
|
|
|||
|
|
.. raw:: html
|
|||
|
|
:class: terminal
|
|||
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_170/config/03/cmd_ro.txt
|
|||
|
|
|
|||
|
|
..
|
|||
|
|
rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/03/config.yml
|
|||
|
|
|
|||
|
|
The result is:
|
|||
|
|
|
|||
|
|
.. raw:: html
|
|||
|
|
:class: output
|
|||
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_170/config/03/output_ro.html
|
|||
|
|
|
|||
|
|
The warning indicates that the validator did not allow an HTTP protocol to pass:
|
|||
|
|
|
|||
|
|
::
|
|||
|
|
|
|||
|
|
┃ the value "http://dns.net" is an invalid URL, must starts with
|
|||
|
|
┃ 'https://' only, it will be ignored when loading from the YAML file
|
|||
|
|
┃ "config/03/config.yml"
|
|||
|
|
|
|||
|
|
.. keypoints:: Let's review the key points
|
|||
|
|
|
|||
|
|
We explained the use of validations to refine the type definition of a variable.
|
|||
|
|
|
|||
|
|
The variable's parameter is `validator`.
|
|||
|
|
|