sophon/docs/source/3_dev/2_structure/3_proxy/index.rst

Modulo proxy
============

Il *modulo proxy* consiste in un webserver che riceve tutte le richieste HTTP dirette ad uno degli altri moduli e le smista in base a regole statiche e dinamiche.

È collocato all'interno del repository in ``/proxy``.


Tecnologie utilizzate
---------------------

- Il server web `Apache HTTPd`_
   - Il modulo `rewrite`_
   - Il modulo `proxy`_
   - Il modulo `proxy_http`_
   - Il modulo `proxy_wstunnel`_

.. _Apache HTTPd: https://httpd.apache.org/
.. _rewrite: https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html
.. _proxy: https://httpd.apache.org/docs/2.4/mod/mod_proxy.html
.. _proxy_http: https://httpd.apache.org/docs/2.4/mod/mod_proxy_http.html
.. _proxy_wstunnel: https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html


Funzionamento del modulo
------------------------

Il modulo proxy è composto da un file di configurazione di `Apache HTTPd`_ e di un ``Dockerfile`` che lo copia all'interno dell'immagine Docker ufficiale ``httpd:2.4``.

Il file di configurazione abilita i moduli `rewrite`_, `proxy`_, `proxy_wstunnel`_ e `proxy_http`_, impostando quest'ultimo per inoltrare l'header `Host <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host>`_ alle pagine verso cui viene effettuato reverse proxying.

Inoltre, nel file di configurazione viene abilitato il ``RewriteEngine``, che viene utilizzato per effettuare reverse proxying secondo le seguenti regole:

#. Tutte le richieste verso ``static.`` prefisso ad :ref:`\`\`APACHE_PROXY_BASE_DOMAIN\`\`` vengono processate direttamente dal webserver, utilizzando i file disponibili nella cartella ``/var/www/html/django-static`` che gli vengono forniti dal volume ``django-static`` del :ref:`modulo backend`.

   .. code-block:: apacheconf

      # If ENV:APACHE_PROXY_BASE_DOMAIN equals HTTP_HOST
      RewriteCond "static.%{ENV:APACHE_PROXY_BASE_DOMAIN} %{HTTP_HOST}" "^([^ ]+) \1$" [NC]
      # Process the request yourself
      RewriteRule ".?" - [L]

#. Tutte le richieste verso :ref:`\`\`APACHE_PROXY_BASE_DOMAIN\`\`` senza nessun sottodominio vengono inoltrate al container Docker del :ref:`modulo frontend` utilizzando la risoluzione dei nomi di dominio di Docker Compose.

   .. code-block:: apacheconf

      # If ENV:APACHE_PROXY_BASE_DOMAIN equals HTTP_HOST
      RewriteCond "%{ENV:APACHE_PROXY_BASE_DOMAIN} %{HTTP_HOST}" "^([^ ]+) \1$" [NC]
      # Capture ENV:SOPHON_FRONTEND_NAME for substitution in the rewriterule
      RewriteCond "%{ENV:SOPHON_FRONTEND_NAME}" "^(.+)$" [NC]
      # Forward to the frontend
      RewriteRule "/(.*)" "http://%1/$1" [P,L]

#. Tutte le richieste verso ``api.`` prefisso ad :ref:`\`\`APACHE_PROXY_BASE_DOMAIN\`\`` vengono inoltrate al container Docker del :ref:`modulo backend` utilizzando la risoluzione dei nomi di dominio di Docker Compose.

   .. code-block:: apacheconf

      # If api. prefixed to ENV:APACHE_PROXY_BASE_DOMAIN equals HTTP_HOST
      RewriteCond "api.%{ENV:APACHE_PROXY_BASE_DOMAIN} %{HTTP_HOST}" "^([^ ]+) \1$" [NC]
      # Capture ENV:SOPHON_BACKEND_NAME for substitution in the rewriterule
      RewriteCond "%{ENV:SOPHON_BACKEND_NAME}" "^(.+)$" [NC]
      # Forward to the backend
      RewriteRule "/(.*)" "http://%1/$1" [P,L]

#. Carica in memoria la rubrica dei notebook generata dal :ref:`modulo backend` e disponibile in ``/run/sophon/proxy/proxy.dbm`` attraverso il volume ``proxy-data``, assegnandogli il nome di ``sophonproxy``.

   .. code-block:: apacheconf

      # Create a map between the proxy file generated by Sophon and Apache
      RewriteMap "sophonproxy" "dbm=gdbm:/run/sophon/proxy/proxy.dbm"

#. Effettua il proxying dei websocket verso i notebook mappati dalla rubrica ``sophonproxy``.

   .. code-block:: apacheconf

      # If this is any other subdomain of ENV:APACHE_PROXY_BASE_DOMAIN
      RewriteCond ".%{ENV:APACHE_PROXY_BASE_DOMAIN} %{HTTP_HOST}" "^([^ ]+) [^ ]+\1$" [NC]
      # If this is a websocket connection
      RewriteCond "%{HTTP:Connection}" "Upgrade" [NC]
      RewriteCond "%{HTTP:Upgrade}" "websocket" [NC]
      # Forward to the notebook
      RewriteRule "/(.*)" "ws://${sophonproxy:%{HTTP_HOST}}/$1" [P,L]

#. Effettua il proxying delle richieste "normali" verso i notebook mappati dalla rubrica ``sophonproxy``.

   .. code-block:: apacheconf

      # If this is any other subdomain of ENV:APACHE_PROXY_BASE_DOMAIN
      RewriteCond ".%{ENV:APACHE_PROXY_BASE_DOMAIN} %{HTTP_HOST}" "^([^ ]+) [^ ]+\1$" [NC]
      # Forward to the notebook
      RewriteRule "/(.*)" "http://${sophonproxy:%{HTTP_HOST}}/$1" [P,L]

Tutte le regole usano il flag ``L`` di ``RewriteRule``, che porta il motore di rewriting a ignorare tutte le regole successive, come il ``return`` di una funzione di un linguaggio di programmazione imperativo.

.. note::

   I blocchi di codice all'interno di questa sezione sono stati inseriti manualmente e potrebbero non essere interamente aggiornati alla versione più recente del file.

   Si consiglia di consultare il file ``httpd.conf`` in caso si necessiti di informazioni aggiornate.


Continuous Deployment
---------------------

L'immagine del modulo viene automaticamente ricompilata da GitHub Actions e pubblicata su GitHub Containers ogni volta che un file all'interno della cartella del modulo viene modificato.

Questo workflow è definito all'interno del file ``.github/workflows/build-docker-proxy.yml``.

.. seealso::

   `La pagina del container <https://github.com/Steffo99/sophon/pkgs/container/sophon-proxy>`_ su GitHub Containers.