.. This file is distributed under the MIT License. If a copy of the
.. MIT License was not distributed with this file, you can obtain one
.. at https://opensource.org/licenses/MIT.

Configuration
=============

Settings
--------

:HTCPCP_ALLOW_DEPRECATED_POST:
    Default: ``True``

    Whether to allow clients to use the POST method for brewing requests.

    The use of the POST method for HTCPCP requests is officially deprecated in `RFC 2324 section 2.1.1`_. However, the standard also stipulates that, HTCPCP servers must accept POST and BREW requests equivalently, and so setting this configuration to ``False`` is not recommended.

.. _RFC 2324 section 2.1.1: https://tools.ietf.org/html/rfc2324#section-2.1.1

:HTCPCP_DISABLE_CSRF:
    Default: ``True``

    When set to ``True``, this app's views will be exempt from `Django's CSRF protection`_.

    In order for HTCPCP requests to pass the CSRF checks, clients would need to set valid Referrer headers and correctly store and transmit CSRF tokens. For most use cases, this is an unnecessary burden, and so these checks are disabled by default.

    If you set this configuration to ``False``, you will need to update the templates to include CSRF tokens and ensure that your clients know to include the required headers and data in their requests.

.. _Django's CSRF protection: https://docs.djangoproject.com/en/2.2/ref/csrf/

:HTCPCP_GET_ADDITIONS:
    Default: ``True``

    When set to ``True``, clients will be able to request beverage additions by listing additions after the ``?`` in a url.

    The URI scheme specified in `RFC 2324 section 3`_ suggests that beverage additions can be provided as list in the query string of the request uri. When this setting is enabled, additions requested in the Accept-Additions header and in the query string are given equal precedence.

    Do note that setting this configuration to ``True`` may enable CSBF (Cross-Site Beverage Forgery) attacks as HTCPCP urls could contain malicious beverage additions that will be requeted with the client knowledge (such as Sea-Salt).

    Setting this option to ``True`` *does not* enable HTCPCP GET requests.


.. _RFC 2324 section 3: https://tools.ietf.org/html/rfc2324#section-3

:HTCPCP_POT_SESSIONS:
    Default: ``True``

    Whether to track user interactions with the server's pots using the `Django session framework`_.

    When set to ``True``, this app will track when beverage a particular user from each pot to enable statefull interactions with the server. Clients will need to follow a complete HTCPCP request cycle, including a start, stop, and optional 'WHEN' request for each beverage the client requests. Invalid HTCPC request sequences (such as requesting a new beverage in a pot that is already brewing a beverage) will result in errors.

    When set to ``False``, this app will naively simulate an HTCPCP server without tracking user sessions. Start, stop, and 'WHEN' requests will be accepted even if their ordering is not logical (e.g. saying 'WHEN' before requesting any beverage).



.. _Django session framework: .. _Django sessions framework: https://docs.djangoproject.com/en/2.2/topics/http/sessions/

:HTCPCP_STRICT_MIME_TYPE:
    Default: ``True``

    When set to ``True``, HTCPCP requests will be ignored unless they have a content type of either ``message/coffeepot`` or ``message/teapot``.

    Set this configuration to ``False`` if modifying HTTP Content-Type header for HTTP requests is not convenient for your use case.

:STRICT_REQUEST_BODY:
    Default: ``False``

    When set to ``True``, HTCPCP requests must have a body constistly solely of ``start`` or ``stop``.

    By default, this configuration is set to ``False`` since it is understood that some clients may want to include additional content in the request entity, such as "please" and "thank you".
