:py:mod:`core.request`
======================

.. py:module:: core.request

.. autoapi-nested-parse::

   This module implements the WSGI (Web Server Gateway Interface) layer for ViUR. This is the main entry
   point for incomming http requests. The main class is the :class:BrowserHandler. Each request will get it's
   own instance of that class which then holds the reference to the request and response object.
   Additionally, this module defines the RequestValidator interface which provides a very early hook into the
   request processing (useful for global ratelimiting, DDoS prevention or access control).



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   core.request.RequestValidator
   core.request.FetchMetaDataValidator
   core.request.Router




Attributes
~~~~~~~~~~

.. autoapisummary::

   core.request.TEMPLATE_STYLE_KEY


.. py:data:: TEMPLATE_STYLE_KEY
   :value: 'style'

   

.. py:class:: RequestValidator


   Bases: :py:obj:`abc.ABC`

   RequestValidators can be used to validate a request very early on. If the validate method returns a tuple,
   the request is aborted. Can be used to block requests from bots.

   To register or remove a validator, access it in main.py through
   :attr: viur.core.request.Router.requestValidators

   .. py:attribute:: name
      :value: 'RequestValidator'

      

   .. py:method:: validate(request)
      :staticmethod:
      :abstractmethod:

          The function that checks the current request. If the request is valid, simply return None.
          If the request should be blocked, it must return a tuple of
          - The HTTP status code (as int)
          - The Description of that status code (eg "Forbidden")
          - The Response Body (can be a simple string or an HTML-Page)
      :param request: The Request instance to check
      :return: None on success, an Error-Tuple otherwise



.. py:class:: FetchMetaDataValidator


   Bases: :py:obj:`RequestValidator`

   This validator examines the headers "Sec-Fetch-Site", "sec-fetch-mode" and "sec-fetch-dest" as
   recommended by https://web.dev/fetch-metadata/

   .. py:attribute:: name
      :value: 'FetchMetaDataValidator'

      

   .. py:method:: validate(request)
      :staticmethod:

          The function that checks the current request. If the request is valid, simply return None.
          If the request should be blocked, it must return a tuple of
          - The HTTP status code (as int)
          - The Description of that status code (eg "Forbidden")
          - The Response Body (can be a simple string or an HTML-Page)
      :param request: The Request instance to check
      :return: None on success, an Error-Tuple otherwise



.. py:class:: Router(environ)


   This class accepts the requests, collect its parameters and routes the request
   to its destination function.
   The basic control flow is
   - Setting up internal variables
   - Running the Request validators
   - Emitting the headers (especially the security related ones)
   - Run the TLS check (ensure it's a secure connection or check if the URL is whitelisted)
   - Load or initialize a new session
   - Set up i18n (choosing the language etc)
   - Run the request preprocessor (if any)
   - Normalize & sanity check the parameters
   - Resolve the exposed function and call it
   - Save the session / tear down the request
   - Return the response generated


   :warning: Don't instantiate! Don't subclass! DON'T TOUCH! ;)

   .. py:property:: isDevServer
      :type: bool


   .. py:attribute:: requestValidators

      

   .. py:method:: _select_language(path)

      Tries to select the best language for the current request. Depending on the value of
      conf.i18n.language_method, we'll either try to load it from the session, determine it by the domain
      or extract it from the URL.


   .. py:method:: _process()


   .. py:method:: _route(path)

      Does the actual work of sanitizing the parameter, determine which exposed-function to call
      (and with which parameters)


   .. py:method:: saveSession()