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).



Attributes
----------

.. autoapisummary::

   core.request.TEMPLATE_STYLE_KEY


Classes
-------

.. autoapisummary::

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


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

.. 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:


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



.. 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:attribute:: requestValidators


   .. py:attribute:: startTime


   .. py:attribute:: request


   .. py:attribute:: response


   .. py:attribute:: maxLogLevel
      :value: 10



   .. py:attribute:: _traceID


   .. py:attribute:: is_deferred
      :value: False



   .. py:attribute:: path
      :value: ''



   .. py:attribute:: path_list
      :value: ()



   .. py:attribute:: skey_checked
      :value: False



   .. py:attribute:: internalRequest
      :value: False



   .. py:attribute:: disableCache
      :value: False



   .. py:attribute:: pendingTasks
      :value: []



   .. py:attribute:: args
      :value: ()



   .. py:attribute:: kwargs


   .. py:attribute:: context


   .. py:attribute:: template_style
      :type:  str | None
      :value: None



   .. py:attribute:: cors_headers
      :value: ()



   .. py:attribute:: method


   .. py:attribute:: isPostRequest


   .. py:attribute:: isSSLConnection


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



   .. 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:: _cors()

      Set CORS headers to the HTTP response.

      .. seealso::

          Option :attr:`core.config.Security.cors_origins`, etc.
          for cors settings.

          https://fetch.spec.whatwg.org/#http-cors-protocol

          https://enable-cors.org/server.html

          https://www.html5rocks.com/static/images/cors_server_flowchart.png



   .. py:method:: saveSession()