view mercurial/help/internals/config.txt @ 36858:01f6bba64424

hgweb: remove support for POST form data (BC)

Previously, we called out to cgi.parse(), which for POST requests
parsed multipart/form-data and application/x-www-form-urlencoded
Content-Type requests for form data, combined it with query string
parameters, returned a union of the values.

As far as I know, nothing in Mercurial actually uses this mechanism
to submit data to the HTTP server. The wire protocol has its own
mechanism for passing parameters. And the web interface only does
GET requests. Removing support for parsing POST data doesn't break
any tests.

Another reason to not like this feature is that cgi.parse() may
modify the QUERY_STRING environment variable as a side-effect.
In addition, it merges both POST data and the query string into
one data structure. This prevents consumers from knowing whether
a variable came from the query string or POST data. That can matter
for some operations.

I suspect we use cgi.parse() because back when this code was
initially implemented, it was the function that was readily
available. In other words, I don't think there was conscious
choice to support POST data: we just got it because cgi.parse()
supported it.

Since nothing uses the feature and it is untested, let's remove
support for parsing POST form data. We can add it back in easily
enough if we need it in the future.

.. bc::

   Hgweb no longer reads form data in POST requests from
   multipart/form-data and application/x-www-form-urlencoded
   requests. Arguments should be specified as URL path components
   or in the query string in the URL instead.

Differential Revision: https://phab.mercurial-scm.org/D2774

All config options used within Mercurial should be registered.

Config Option in Core
=====================

Config options used by Mercurial core are registered in the
``mercurial.configitems`` module.

Simple entry
------------

A registration entry typically looks like::

    coreconfigitem('section', 'option',
        default=MyDefaultValue,
    )

Once registered, Mercurial will know that ``section.option`` is a legitimate
config option and that ``MyDefaultValue`` should be used if no other values are
defined in configuration files.

Complex default value
---------------------

If the default provided is a callable, it is called to retrieve the default
value when accessing the config option. This is useful for default values that
are mutable like the empty list::

    coreconfigitem('pager', 'ignore',
        default=list,
    )

In addition, there are cases where the default is not fixed, but computed from
other properties. In this case, use the ``dynamicdefault`` object as the value
for the ``default`` parameter. A default value is then explicitly required when
reading the option::

    # registration
    coreconfigitem('web', 'name',
        default=dynamicdefault,
    )

    # usage
    ui.config('web', 'name', dirname)

Free form options
-----------------

Some config sections use free form options (e.g. ``paths``). You can register
them using the ``generic`` parameters::

    coreconfigitem('paths', '.*',
        default=None,
        generic=True,
    )

When ``generic=True`` is set, the option name is matched as a regular expression
(rooted to string start). It can be used to select specific sub parameters::

    coreconfigitem('merge-tools', br'.*\.args$',
        default="$local $base $other",
        generic=True,
        priority=-1,
    )

The ``priority`` parameter controls the order used to match the generic pattern
(lower first).

Config Option in Extensions
===========================

General case
------------

Extensions should register config items through the ``registrar`` API (also used
for commands and others)::

    configtable = {}
    configitem = registrar.configitem(configtable)

    configitem('blackbox', 'dirty',
        default=False,
    )

The ``dynamicdefault`` object is then available as
``configitem.dynamicdefault``.

Supporting older versions
-------------------------

The registrar was introduced in Mercurial 4.3, and the ``generic`` parameter was
introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
and developer warnings are emitted when accessing unregistered option.

Extensions supporting versions older than Mercurial 4.3 cannot rely on the
default value being registered. The simplest way to register an option while
still supporting an older version is to use ``dynamicdefault`` for options
requiring a default value. The existing code passing an explicit default can
then stay in use until compatibility with Mercurial 4.2 is dropped.

As reminder, here are the default values for each config type:
- config:      None
- configbool:  False
- configbytes: 0
- configdate:  None
- configint:   None
- configlist:  []
- configpath:  None