[PATCH 3 of 5 V3] help: document wire protocol capabilities

[Gregory Szorc]

# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1471920511 25200
#      Mon Aug 22 19:48:31 2016 -0700
# Node ID 98505b32869ea6121dfdd5a732d71fbd1548462d
# Parent  b9a07a0b9f9c78d6083d43239cafad5da90ed776
help: document wire protocol capabilities

All capabilities from the history of the project are now documented.

diff --git a/mercurial/help/internals/wireprotocol.txt b/mercurial/help/internals/wireprotocol.txt
--- a/mercurial/help/internals/wireprotocol.txt
+++ b/mercurial/help/internals/wireprotocol.txt
@@ -148,8 +148,223 @@ A ``stream`` response type consists of r
 A generic error response type is also supported. It consists of a an error
 message written to ``stderr`` followed by ``\n-\n``. In addition, ``\n`` is
 written to ``stdout``.
 
 If the server receives an unknown command, it will send an empty ``string``
 response.
 
 The server terminates if it receives an empty command (a ``\n`` character).
+
+Capabilities
+============
+
+Servers advertise supported wire protocol features. This allows clients to
+probe for server features before blindly calling a command or passing a
+specific argument.
+
+The server's features are exposed via a *capabilities* string. This is a
+space-delimited string of tokens/features. Some features are single words
+like ``lookup`` or ``batch``. Others are complicated key-value pairs
+advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word
+values are used, each feature name can define its own encoding of sub-values.
+Comma-delimited and ``x-www-form-urlencoded`` values are common.
+
+The following document capabilities defined by the canonical Mercurial server
+implementation.
+
+batch
+-----
+
+Whether the server supports the ``batch`` command.
+
+This capability/command was introduced in Mercurial 1.9 (released July 2011).
+
+branchmap
+---------
+
+Whether the server supports the ``branchmap`` command.
+
+This capability/command was introduced in Mercurial 1.3 (released July 2009).
+
+bundle2-exp
+-----------
+
+Precursor to ``bundle2`` capability that was used before bundle2 was a
+stable feature.
+
+This capability was introduced in Mercurial 3.0 behind an experimental
+flag. This capability should not be observed in the wild.
+
+bundle2
+-------
+
+Indicates whether the server supports the ``bundle2`` data exchange format.
+
+The value of the capability is a URL quoted, newline (``\n``) delimited
+list of keys or key-value pairs.
+
+A key is simply a URL encoded string.
+
+A key-value pair is a URL encoded key separated from a URL encoded value by
+an ``=``. If the value is a list, elements are delimited by a ``,`` after
+URL encoding.
+
+For example, say we have the values::
+
+  {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']}
+
+We would first construct a string::
+
+  HG20\nchangegroup=01,02\ndigests=sha1,sha512
+
+We would then URL quote this string::
+
+  HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512
+
+This capability was introduced in Mercurial 3.4 (released May 2015).
+
+changegroupsubset
+-----------------
+
+Whether the server supports the ``changegroupsubset`` command.
+
+This capability was introduced in Mercurial 0.9.2 (released December
+2006).
+
+This capability was introduced at the same time as the ``lookup``
+capability/command.
+
+getbundle
+---------
+
+Whether the server supports the ``getbundle`` command.
+
+This capability was introduced in Mercurial 1.9 (released July 2011).
+
+httpheader
+----------
+
+Whether the server supports receiving command arguments via HTTP request
+headers.
+
+The value of the capability is an integer describing the max header
+length that clients should send. Clients should ignore any content after a
+comma in the value, as this is reserved for future use.
+
+This capability was introduced in Mercurial 1.9 (released July 2011).
+
+httppostargs
+------------
+
+**Experimental**
+
+Indicates that the server supports and prefers clients send command arguments
+via a HTTP POST request as part of the request body.
+
+This capability was introduced in Mercurial 3.8 (released May 2016).
+
+known
+-----
+
+Whether the server supports the ``known`` command.
+
+This capability/command was introduced in Mercurial 1.9 (released July 2011).
+
+lookup
+------
+
+Whether the server supports the ``lookup`` command.
+
+This capability was introduced in Mercurial 0.9.2 (released December
+2006).
+
+This capability was introduced at the same time as the ``changegroupsubset``
+capability/command.
+
+pushkey
+-------
+
+Whether the server supports the ``pushkey`` and ``listkeys`` commands.
+
+This capability was introduced in Mercurial 1.6 (released July 2010).
+
+standardbundle
+--------------
+
+**Unsupported**
+
+This capability was introduced during the Mercurial 0.9.2 development cycle in
+2006. It was never present in a release, as it was replaced by the ``unbundle``
+capability. This capability should not be encountered in the wild.
+
+stream-preferred
+----------------
+
+If present the server prefers that clients clone using the streaming clone
+protocol (``hg clone --uncompressed``) rather than the standard
+changegroup/bundle based protocol.
+
+This capability was introduced in Mercurial 2.2 (released May 2012).
+
+streamreqs
+----------
+
+Indicates whether the server supports *streaming clones* and the *requirements*
+that clients must support to receive it.
+
+If present, the server supports the ``stream_out`` command, which transmits
+raw revlogs from the repository instead of changegroups. This provides a faster
+cloning mechanism at the expense of more bandwidth used.
+
+The value of this capability is a comma-delimited list of repo format
+*requirements*. These are requirements that impact the reading of data in
+the ``.hg/store`` directory. An example value is
+``streamreqs=generaldelta,revlogv1`` indicating the server repo requires
+the ``revlogv1`` and ``generaldelta`` requirements.
+
+If the only format requirement is ``revlogv1``, the server may expose the
+``stream`` capability instead of the ``streamreqs`` capability.
+
+This capability was introduced in Mercurial 1.7 (released November 2010).
+
+stream
+------
+
+Whether the server supports *streaming clones* from ``revlogv1`` repos.
+
+If present, the server supports the ``stream_out`` command, which transmits
+raw revlogs from the repository instead of changegroups. This provides a faster
+cloning mechanism at the expense of more bandwidth used.
+
+This capability was introduced in Mercurial 0.9.1 (released July 2006).
+
+When initially introduced, the value of the capability was the numeric
+revlog revision. e.g. ``stream=1``. This indicates the changegroup is using
+``revlogv1``. This simple integer value wasn't powerful enough, so the
+``streamreqs`` capability was invented to handle cases where the repo
+requirements have more than just ``revlogv1``. Newer servers omit the
+``=1`` since it was the only value supported and the value of ``1`` can
+be implied by clients.
+
+unbundlehash
+------------
+
+Whether the ``unbundle`` commands supports receiving a hash of all the
+heads instead of a list.
+
+For more, see the documentation for the ``unbundle`` command.
+
+This capability was introduced in Mercurial 1.9 (released July 2011).
+
+unbundle
+--------
+
+Whether the server supports pushing via the ``unbundle`` command.
+
+This capability/command has been present since Mercurial 0.9.1 (released
+July 2006).
+
+Mercurial 0.9.2 (released December 2006) added values to the capability
+indicating which bundle types the server supports receiving. This value is a
+comma-delimited list. e.g. ``HG10GZ,HG10BZ,HG10UN``. The order of values
+reflects the priority/preference of that type, where the first value is the
+most preferred type.