diff mercurial/help/internals/wireprotocol.txt @ 37533:df4985497986

wireproto: implement capabilities for wire protocol v2

The capabilities mechanism for wire protocol version 2 represents a
clean break from version 1.

Instead of effectively exchanging a set of capabilities, we're
exchanging a rich data structure.

This data structure currently contains information about
every available command, including its accepted arguments. It also
contains information about supported compression formats.

Exposing information about supported commands will allow clients
to automatically generate bindings to the server. Clients will be
able to do things like detect when they are attempting to run a
command that isn't known to the server. Exposing the required
permissions to run a command can be used by clients to determine if
they have privileges to call a command before actually calling it.
We could potentially even have clients send credentials
preemptively without waiting for the server to deny the command
request. Lots of potential here.

The data returned by this command will likely evolve heavily. So we
shouldn't bikeshed the implementation just yet.

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

--- a/mercurial/help/internals/wireprotocol.txt	Sun Apr 08 09:45:45 2018 -0700
+++ b/mercurial/help/internals/wireprotocol.txt	Mon Apr 09 11:52:31 2018 -0700
@@ -1690,6 +1690,42 @@
 The response is a map with bytestring keys defining the branch name.
 Values are arrays of bytestring defining raw changeset nodes.
 
+capabilities
+------------
+
+Obtain the server's capabilities.
+
+Receives no arguments.
+
+This command is typically called only as part of the handshake during
+initial connection establishment.
+
+The response is a map with bytestring keys defining server information.
+
+The defined keys are:
+
+commands
+   A map defining available wire protocol commands on this server.
+
+   Keys in the map are the names of commands that can be invoked. Values
+   are maps defining information about that command. The bytestring keys
+   are:
+
+      args
+         An array of argument names accepted by this command.
+      permissions
+         An array of permissions required to execute this command.
+
+compression
+   An array of maps defining available compression format support.
+
+   The array is sorted from most preferred to least preferred.
+
+   Each entry has the following bytestring keys:
+
+      name
+         Name of the compression engine. e.g. ``zstd`` or ``zlib``.
+
 heads
 -----