Disabling things ======================== .. objectives:: Objectives In this section we will see what a disabled variable or family is, and why it can be interesting to assign the `disabled` property to a variable or a family. We'll also learn the difference between disabling and hiding families or variables. We will: - `disable` a whole family here (yes, a family can disapear in the outerspace!) - use a new family or variable's property: the `hidden` property - reuse a value of a variable for another variable (in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS). .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` 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 `, this workshop page corresponds to the tags :tutorial:`v1.1_040 ` to :tutorial:`v1.1_044 ` in the repository. :: git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_040 A disabled family --------------------------------------------- Disabling and hiding are two families or variables properties. Let's begin with defining what a property is: .. glossary:: property A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...) of a family, a subfamily or a variable. These properties change the usual behavior of a variable or family. Here we are going to assign the `disabled` property to the `manual` family: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml :language: yaml :caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file .. %YAML 1.2 --- version: 1.1 manual: description: Manual proxy configuration disabled: true http_proxy: # HTTP Proxy address: description: HTTP address type: domainname params: allow_ip: true port: description: HTTP Port type: port default: 8080 We have this `disabled: true` property assigned to the `manual` family. .. raw:: html :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt .. rougail -m firefox/ -u yaml -yf config/02/config.yml The Rougail CLI outputs this: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html :class: output We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail. Let's first examine what this disabled property does. .. glossary:: disabled The disabled property is a property that can be assigned to a variable or a family. It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined. It simply doesn't exist. It is deactivated for the whole configuration. .. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled. If we still wanna try to assign values to variables that have been disabled: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/config.yml :language: yaml :caption: Here in the :file:`config/02/config.yml` user data file, we assign values to disabled variables If we launch the Rougail CLI: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt :class: terminal It outputs: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html :class: output We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled. That is to say, they are not taken into account at the :term:`configuration` level. If we have a closer look at our use case, we have a choice between five options in order to set the proxy mode: .. image:: images/firefox_01.png These five choices are: - No proxy - Auto-detect proxy settings for this network - Use system proxy settings - Manual proxy configuration - Automatic proxy configuration URL Actually if the `Manual proxy configuration` is not selected, we don't need to set these `address` and `port` variables, there is no point in setting them in four out of our five use cases. We could say that we disable them in order to expose the fact that we don't use them, but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`. We shall fill and use in these variables in the `Manual proxy configuration` use case context only. Otherwise, **we need to disable them when they are not necessary**. In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it. He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. .. important:: We need to **disable** variables or families that are not used in a given usage context. .. type-along:: Disabling variables one by one can be replaced by disabling a family If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable all the subfamilies and the variables in it. Note that we've placed theses variables in the `http_proxy` subfamily. We can then disable it or even the parent `manual` subfamily in order to disable the `http_proxy` family and all the variables that are placed in it, because the `manual` family variables shall be used only in the manual proxy use case context. Notice the `disabled: true` parameter set in the `manual` family: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml :linenos: :language: yaml :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here .. --- manual: description: Manual proxy configuration disabled: true http_proxy: description: HTTP Proxy address: description: HTTP address type: domainname params: allow_ip: true port: description: HTTP Port type: port default: 8080 A conditional disabled family ------------------------------ .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the `v1.1_041` version:: git switch --detach v1.1_041 What could be usefull here is a *dynamic setting* of the disable/enable property of the `manual` family. The idea in this section is to dynamically set the enable/disable property according to the chosen use case context. In rougail, we can set a property's value **depending on** the value of another variable. **It is conditioned by** another variable. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml :linenos: :language: yaml :caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled .. %YAML 1.2 --- version: 1.1 manual: description: Manual proxy configuration disabled: variable: _.proxy_mode when_not: Manual proxy configuration http_proxy: # HTTP Proxy address: description: HTTP address type: domainname params: allow_ip: true port: description: HTTP Port type: port default: 8080 Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter. This parameter specifies the target variable. The value of this target variable will be used to dynamically enable or disable our `manual` family. We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. The target variable is `_.proxy_mode`. The `.` notation means the path of the family or subfamily you're currently in. The `_.` notation means the parent path of the current family or subfamily path. Regarding the `when_not` parameter, it means that if the target variable's value is `Manual proxy configuration` then the `manual` **will not** be disabled (that is, it will be enabled). Here as the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. Let's launch the Rougail CLI on an empty user value file: .. raw:: html :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/cmd_ro.txt .. rougail -m firefox/ -u yaml -yf config/01/config.ym We have this output: .. raw:: html :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html .. 
╭──────────────────── Caption ─────────────────────╮
    │ Undocumented but modified variable Default value │
    ╰──────────────────────────────────────────────────╯
    Variables:
    ┗━━ 📓 Configure Proxy Access to the Internet: No proxy
We can see that the `manual` family and all the variables into it are not present. .. type-along:: Dynamically enabling the `manual` family If the manual mode for the proxy is not selected, then the `manual` family is disabled. On the other hand, if the manual proxy's configuration mode is selected, then the `manual` family is re-activated (enabled). Now we are going to select the ** manual mode**, that is the `Manual proxy configuration` value for the `proxy_mode` variable, and things will become slightly different. .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml :linenos: :language: yaml :caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file .. --- proxy_mode: Manual proxy configuration manual: http_proxy: address: http.proxy.net port: 3128 use_for_https: false .. note:: Remember that this activation/deactivation of the `manual` family depends on the value of the `proxy_mode` variable. Here we have chosen the `Manual proxy configuration` value. .. rubric:: Explanation Here the `disabled` property **depends on** the value of the `proxy_mode` variable. It is the `variable` parameter that allows you to define the name of the target variable on which the `disabled` property depends. Copy HTTP manual proxy to HTTPS manual proxy --------------------------------------------- .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the `v1.1_042` version:: git switch --detach v1.1_042 We have split the definition of the `manual` familiy into two specific files: .. raw:: html :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html Here is the new :file:`20-manual.yml` file: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml :linenos: :language: yaml :caption: The updated `manual` family in the :file:`firefox/20-manual.yml` structure file with the `https_proxy` family. .. %YAML 1.2 --- version: 1.1 manual: use_for_https: true # Also use this proxy for HTTPS https_proxy: # HTTPS Proxy address: description: HTTPS address type: domainname params: allow_ip: true port: description: HTTPS Port type: port default: 8080 This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol. .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the `v1.1_043` version:: git switch --detach v1.1_043 Here is an example with different user values for handling HTTP and HTTPS: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/config.yml :linenos: :language: yaml :caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false .. --- proxy_mode: Manual proxy configuration manual: http_proxy: address: http.proxy.net port: 3128 use_for_https: false https_proxy: address: https.proxy.net If we launch the Rougail CLI: .. raw:: html :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/cmd_ro.txt .. rougail -m firefox/ -u yaml -yf config/01/config.yml We have this output: .. raw:: html :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/output_ro.html .. 
╭────────────── Caption ───────────────╮
    │ Variable Default value               │
    │          Modified value              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    Variables:
    ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
    ┃   configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
    ┃   proxy)
    ┗━━ 📂 manual (Manual proxy configuration)
        ┣━━ 📂 http_proxy (HTTP Proxy)
        ┃   ┣━━ 📓 address (HTTP address): http.proxy.net ◀ loaded from the YAML 
        ┃   ┃   file "config/01/config.yml"
        ┃   ┗━━ 📓 port (HTTP Port): 3128 ◀ loaded from the YAML file 
        ┃       "config/01/config.yml" (⏳ 8080)
        ┣━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
        ┃   the YAML file "config/01/config.yml" (⏳ true)
        ┗━━ 📂 https_proxy (HTTPS Proxy)
            ┣━━ 📓 address (HTTPS address): https.proxy.net ◀ loaded from the YAML 
            ┃   file "config/01/config.yml"
            ┗━━ 📓 port (HTTPS Port): 8080
Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`. We want to offer the possibility of providing an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols. Here is an example with identical HTTP and HTTPS proxy configuration: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/config.yml :linenos: :language: yaml :caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true .. --- proxy_mode: Manual proxy configuration manual: http_proxy: address: http.proxy.net port: 3128 use_for_https: true Let's launch the Rougail CLI: .. raw:: html :class: terminal :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/cmd_ro.txt .. rougail -m firefox/ -u yaml -yf config/02/config.yml We have this output: .. raw:: html :class: output :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html FIXME: il y a un dans le 

.. 
    
> [!CAUTION]
    > 
    > - manual (Manual proxy configuration)
    >   - https_proxy (HTTPS Proxy)
    >     - address (HTTPS address): :stop_sign: <span style="color: #C23636">mandatory variable but is inaccessible and has no value</span>
    


We are going to see how to point HTTPS variables to HTTPS variables
   
A conditional hidden family
----------------------------

Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.

.. image:: images/firefox_manual_https.png

We have added two other variables for the HTTPS use only: 

.. confval:: https_proxy.address
   :type: `domainname`

   This is an address setting for the manual HTTPS configuration

.. confval:: https_proxy.port
   :type: `port`

   This is a port setting for the manual HTTPS configuration

We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.

Let's introduce a new Rougail concept here:

.. glossary:: 

   context
   
       A :term:`configuration` is highly statefull and can change at any moment.
       Sometimes somes minor changes in the :term:`user datas ` may involve chain reactions 
       in the whole :term:`configuration`.
       The **context** is the state of the user datas at one moment, the set of the values of the variables
       at a given moment. This term also refers to the ability of a system to handle 
       the *statefull* state of a configuration. 
       It expresses the transition between one situation to another situation, 
       that is, the deeply **statefull** aspects of a data set.


.. type-along:: A new variable which has the `boolean` type

The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.

Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
Well, it depends on the :term:`context`. 

We have added a new variable, named `use_for_https` here:

.. confval:: use_for_https
   :type: `boolean`
   :default: `true`

   This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS

.. questions:: Question: how does it work? 

   How will this variable drive the reuse of HTTP data to HTTPS data?

With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two: 

- The http proxy's configuration will be reused for the https proxy's configuration
- The http proxy's will not be reused for the https proxy's configuration

.. questions:: Question: shall we use the `disabled` property here?

   Is it relevant to use the :term:`disabled property ` here? 
   
   **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case, 
   we simply have to point their values ​​in one direction or another depending on this or that context,
   that's why it is absolutely not a question of deactivating them. The `manual.https_proxy.address` 
   and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode. 

Let's introduce a new concept here:

.. glossary:: 

   hidden
   
       A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`. 
       Anyway, these variables can be used if the context evolves. This is the main difference 
       between the `hidden` and the `disabled` properties (with the `disabled` property, the variables are *deactivated*.

Now we can set a `hidden` property to the `https_proxy` family:

Here is our new :file:`20-manual.yml` structure file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_043/firefox/20-manual.yml
   :linenos:
   :language: yaml
   :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.

We have now a `hidden` property assigned to the `https_proxy` family. 
The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has 
a `variable` target parameter: `variable: _.use_for_https`

.. prerequisites:: Reminder

   The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent 
   family.

Variable type and parameters type are copied with default value
------------------------------------------------------------------

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the `v1.1_044` version::
     
          git switch --detach v1.1_044

.. discussion:: A contextualized default value 

   A contextualized default value is a default value (of a variable) that is driven by another variable.
   This variable type and its parameters type are copied in the default value's target variable.

There is something left in the https configuration mode of the proxy: 

- if the use of the proxy variables for https are the same of the proxy variables for http, 
  that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK. 
- if the use of the proxy variables for https **are not** the same of the proxy variables for http, 
  we would like to set their default values to the http proxy variables values.

The dynamic setting of a default can be achieved in this way: the default value is a pointer to another variable's value.
Here, the defaut value of `manual.https_proxy.address` points to `manual.http_proxy.address`.

This is the same thing for the default value of the `manual.https_proxy.port` variable, 
which points to the `manual.http_proxy.port` value.

We also say that the default value is *calculated*.

.. glossary::

   calculated
   
       We say that a variable's value or a default variable's value is calculated 
       when there is a pointer which refers to another variable's value 
       or if there is some :term:`jinja` code or a python function that calculates it. 

To summarize the HTTP and HTTPS configuration in the manual use case context, 
here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` structure files:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/10-manual.yml
   :linenos:
   :language: yaml
   :caption: The :file:`firefox/10-manual.yml` structure file with the `http_proxy` family and the `disabled` property

..
    %YAML 1.2
    ---
    version: 1.1

    manual:
      description: Manual proxy configuration
      disabled:
        variable: _.proxy_mode
        when_not: Manual proxy configuration

      http_proxy:  # HTTP Proxy

        address:
          description: HTTP address
          type: domainname
          params:
            allow_ip: true

        port:
          description: HTTP Port
          type: port
          default: 8080
    ...


.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/20-manual.yml   
   :linenos:
   :language: yaml
   :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
   
..
    %YAML 1.2
    ---
    version: 1.1

    manual:

      use_for_https: true  # Also use this proxy for HTTPS

      https_proxy:
        description: HTTPS Proxy
        hidden:
          variable: _.use_for_https

        address:
          description: HTTPS address
          default:
            variable: __.http_proxy.address

        port:
          description: HTTPS Port
          default:
            variable: __.http_proxy.port
    ...


.. keypoints:: Key points progress

    **summary**
    
    We have now the ability to build a contextual setting:

    - if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled
    - if the `proxy_mode` variable's value is `'Manual proxy configuration'` then the `manual` family is enabled

    - FIXME add the hidden steps

    We have arrived at the end of the proxy's manual configuration's section.

    **Keywords**
    
    - We now know what a *property* is, we have seen in details the :term:`disabled` property
    - We can target a variable's value in the `disabled` property's value,
      we call it a variable based contextual disabled family
    - The :term:`hidden` property set to a family
    - The fact that a property can be set dynamically
    - The conditional dependency of a `hidden` property that depends on a `boolean` variable.
    - A calculated default value