wireprotov2: define semantics for content redirects

When I implemented the clonebundles feature and deployed it on
hg.mozilla.org using Amazon S3 as a content server, server-side CPU
and bandwidth usage dropped off a cliff and a ton of server scaling
headaches went away pretty much the instant clients with support for
clonebundles were rolled out to Firefox CI.

An obvious takeaway from that experience was that offloading server
load to scalable file servers - potentially backed by a CDN - is a
really good idea. Another takeaway was that Mercurial's wire protocol
wasn't in a good position to support data offload generally.

In wire protocol version 1, there isn't a mechanism in the protocol to
say "grab the data from over here instead." For HTTP, we could teach
the client to follow HTTP redirects. Or we could invent a media type
that encoded redirects inline. But for SSH, we were pretty much out of
luck because that protocol wasn't very flexible.

Wire protocol version 2 offers the opportunity to do something better.

The recent generic server-side content caching layer in the wire
protocol version 2 server demonstrated that it is possible to have
drop-in caching of responses to command requests. This by itself
adds tons of value and already makes the built-in server much more
scalable. But I don't want to stop there.

The existing server-side caching implementation has a big weakness:
it requires the server to send data to the client. This means that
the Mercurial server is potentially sending gigabytes of data to
thousands of clients. This is problematic because compared to scaling
static file servers, scaling dynamic servers is *hard*.

A solution to this is to "offload" serving of content to something
that isn't the Mercurial server. By offloading content serving, you
turn the Mercurial server from a centralized monolithic service to
a distributed mostly-indexing service. Assuming high rates of content
offload, this should drastically reduce the total work performed by
the Mercurial server, both in terms of CPU and data transfer. This
will make Mercurial servers vastly easier to scale.

This commit defines the semantics for "content redirects" in wire
protocol version 2. Essentially:

* Servers advertise the set of locations a response could be served
  from.
* When making requests, clients advertise the set of locations they
  are willing to fetch content from.
* Servers can then replace the inline response with one that says
  "get the response from over here instead."

This feature - when fully implemented - will allow extending the
server-side caching layer to facilitate such things as integrating
your server-side cache with a scalable blob store (such as S3 or
a CDN) and offloading most data transfer to that external service.

This feature could also be leveraged for load balancing. e.g.
requests could come into a central server and then get redirected
to an available mirror depending on server availability or locality.
There's tons of potential :)

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

mercurial/help/internals/wireprotocolrpc.txt

@@ -1,519 +1,649 b''
 **Experimental and under development**
 
 This document describe's Mercurial's transport-agnostic remote procedure
 call (RPC) protocol which is used to perform interactions with remote
 servers. This protocol is also referred to as ``hgrpc``.
 
 The protocol has the following high-level features:
 
 * Concurrent request and response support (multiple commands can be issued
   simultaneously and responses can be streamed simultaneously).
 * Supports half-duplex and full-duplex connections.
 * All data is transmitted within *frames*, which have a well-defined
   header and encode their length.
 * Side-channels for sending progress updates and printing output. Text
   output from the remote can be localized locally.
 * Support for simultaneous and long-lived compression streams, even across
   requests.
 * Uses CBOR for data exchange.
 
 The protocol is not specific to Mercurial and could be used by other
 applications.
 
 High-level Overview
 ===================
 
 To operate the protocol, a bi-directional, half-duplex pipe supporting
 ordered sends and receives is required. That is, each peer has one pipe
 for sending data and another for receiving. Full-duplex pipes are also
 supported.
 
 All data is read and written in atomic units called *frames*. These
 are conceptually similar to TCP packets. Higher-level functionality
 is built on the exchange and processing of frames.
 
 All frames are associated with a *stream*. A *stream* provides a
 unidirectional grouping of frames. Streams facilitate two goals:
 content encoding and parallelism. There is a dedicated section on
 streams below.
 
 The protocol is request-response based: the client issues requests to
 the server, which issues replies to those requests. Server-initiated
 messaging is not currently supported, but this specification carves
 out room to implement it.
 
 All frames are associated with a numbered request. Frames can thus
 be logically grouped by their request ID.
 
 Frames
 ======
 
 Frames begin with an 8 octet header followed by a variable length
 payload::
 
     +------------------------------------------------+
     |                 Length (24)                    |
     +--------------------------------+---------------+
     |         Request ID (16)        | Stream ID (8) |
     +------------------+-------------+---------------+
     | Stream Flags (8) |
     +-----------+------+
     | Type (4)  |
     +-----------+
     | Flags (4) |
     +===========+===================================================|
     |                     Frame Payload (0...)                    ...
     +---------------------------------------------------------------+
 
 The length of the frame payload is expressed as an unsigned 24 bit
 little endian integer. Values larger than 65535 MUST NOT be used unless
 given permission by the server as part of the negotiated capabilities
 during the handshake. The frame header is not part of the advertised
 frame length. The payload length is the over-the-wire length. If there
 is content encoding applied to the payload as part of the frame's stream,
 the length is the output of that content encoding, not the input.
 
 The 16-bit ``Request ID`` field denotes the integer request identifier,
 stored as an unsigned little endian integer. Odd numbered requests are
 client-initiated. Even numbered requests are server-initiated. This
 refers to where the *request* was initiated - not where the *frame* was
 initiated, so servers will send frames with odd ``Request ID`` in
 response to client-initiated requests. Implementations are advised to
 start ordering request identifiers at ``1`` and ``0``, increment by
 ``2``, and wrap around if all available numbers have been exhausted.
 
 The 8-bit ``Stream ID`` field denotes the stream that the frame is
 associated with. Frames belonging to a stream may have content
 encoding applied and the receiver may need to decode the raw frame
 payload to obtain the original data. Odd numbered IDs are
 client-initiated. Even numbered IDs are server-initiated.
 
 The 8-bit ``Stream Flags`` field defines stream processing semantics.
 See the section on streams below.
 
 The 4-bit ``Type`` field denotes the type of frame being sent.
 
 The 4-bit ``Flags`` field defines special, per-type attributes for
 the frame.
 
 The sections below define the frame types and their behavior.
 
 Command Request (``0x01``)
 --------------------------
 
 This frame contains a request to run a command.
 
 The payload consists of a CBOR map defining the command request. The
 bytestring keys of that map are:
 
 name
    Name of the command that should be executed (bytestring).
 args
    Map of bytestring keys to various value types containing the named
    arguments to this command.
 
    Each command defines its own set of argument names and their expected
    types.
 
+redirect (optional)
+   (map) Advertises client support for following response *redirects*.
+
+   This map has the following bytestring keys:
+
+   targets
+      (array of bytestring) List of named redirect targets supported by
+      this client. The names come from the targets advertised by the
+      server's *capabilities* message.
+
+   hashes
+      (array of bytestring) List of preferred hashing algorithms that can
+      be used for content integrity verification.
+
+   See the *Content Redirects* section below for more on content redirects.
+
 This frame type MUST ONLY be sent from clients to servers: it is illegal
 for a server to send this frame to a client.
 
 The following flag values are defined for this type:
 
 0x01
    New command request. When set, this frame represents the beginning
    of a new request to run a command. The ``Request ID`` attached to this
    frame MUST NOT be active.
 0x02
    Command request continuation. When set, this frame is a continuation
    from a previous command request frame for its ``Request ID``. This
    flag is set when the CBOR data for a command request does not fit
    in a single frame.
 0x04
    Additional frames expected. When set, the command request didn't fit
    into a single frame and additional CBOR data follows in a subsequent
    frame.
 0x08
    Command data frames expected. When set, command data frames are
    expected to follow the final command request frame for this request.
 
 ``0x01`` MUST be set on the initial command request frame for a
 ``Request ID``.
 
 ``0x01`` or ``0x02`` MUST be set to indicate this frame's role in
 a series of command request frames.
 
 If command data frames are to be sent, ``0x08`` MUST be set on ALL
 command request frames.
 
 Command Data (``0x02``)
 -----------------------
 
 This frame contains raw data for a command.
 
 Most commands can be executed by specifying arguments. However,
 arguments have an upper bound to their length. For commands that
 accept data that is beyond this length or whose length isn't known
 when the command is initially sent, they will need to stream
 arbitrary data to the server. This frame type facilitates the sending
 of this data.
 
 The payload of this frame type consists of a stream of raw data to be
 consumed by the command handler on the server. The format of the data
 is command specific.
 
 The following flag values are defined for this type:
 
 0x01
    Command data continuation. When set, the data for this command
    continues into a subsequent frame.
 
 0x02
    End of data. When set, command data has been fully sent to the
    server. The command has been fully issued and no new data for this
    command will be sent. The next frame will belong to a new command.
 
 Command Response Data (``0x03``)
 --------------------------------
 
 This frame contains response data to an issued command.
 
 Response data ALWAYS consists of a series of 1 or more CBOR encoded
 values. A CBOR value may be using indefinite length encoding. And the
 bytes constituting the value may span several frames.
 
 The following flag values are defined for this type:
 
 0x01
    Data continuation. When set, an additional frame containing response data
    will follow.
 0x02
    End of data. When set, the response data has been fully sent and
    no additional frames for this response will be sent.
 
 The ``0x01`` flag is mutually exclusive with the ``0x02`` flag.
 
 Error Occurred (``0x05``)
 -------------------------
 
 Some kind of error occurred.
 
 There are 3 general kinds of failures that can occur:
 
 * Command error encountered before any response issued
 * Command error encountered after a response was issued
 * Protocol or stream level error
 
 This frame type is used to capture the latter cases. (The general
 command error case is handled by the leading CBOR map in
 ``Command Response`` frames.)
 
 The payload of this frame contains a CBOR map detailing the error. That
 map has the following bytestring keys:
 
 type
    (bytestring) The overall type of error encountered. Can be one of the
    following values:
 
    protocol
       A protocol-level error occurred. This typically means someone
       is violating the framing protocol semantics and the server is
       refusing to proceed.
 
    server
       A server-level error occurred. This typically indicates some kind of
       logic error on the server, likely the fault of the server.
 
    command
       A command-level error, likely the fault of the client.
 
 message
    (array of maps) A richly formatted message that is intended for
    human consumption. See the ``Human Output Side-Channel`` frame
    section for a description of the format of this data structure.
 
 Human Output Side-Channel (``0x06``)
 ------------------------------------
 
 This frame contains a message that is intended to be displayed to
 people. Whereas most frames communicate machine readable data, this
 frame communicates textual data that is intended to be shown to
 humans.
 
 The frame consists of a series of *formatting requests*. Each formatting
 request consists of a formatting string, arguments for that formatting
 string, and labels to apply to that formatting string.
 
 A formatting string is a printf()-like string that allows variable
 substitution within the string. Labels allow the rendered text to be
 *decorated*. Assuming use of the canonical Mercurial code base, a
 formatting string can be the input to the ``i18n._`` function. This
 allows messages emitted from the server to be localized. So even if
 the server has different i18n settings, people could see messages in
 their *native* settings. Similarly, the use of labels allows
 decorations like coloring and underlining to be applied using the
 client's configured rendering settings.
 
 Formatting strings are similar to ``printf()`` strings or how
 Python's ``%`` operator works. The only supported formatting sequences
 are ``%s`` and ``%%``. ``%s`` will be replaced by whatever the string
 at that position resolves to. ``%%`` will be replaced by ``%``. All
 other 2-byte sequences beginning with ``%`` represent a literal
 ``%`` followed by that character. However, future versions of the
 wire protocol reserve the right to allow clients to opt in to receiving
 formatting strings with additional formatters, hence why ``%%`` is
 required to represent the literal ``%``.
 
 The frame payload consists of a CBOR array of CBOR maps. Each map
 defines an *atom* of text data to print. Each *atom* has the following
 bytestring keys:
 
 msg
    (bytestring) The formatting string. Content MUST be ASCII.
 args (optional)
    Array of bytestrings defining arguments to the formatting string.
 labels (optional)
    Array of bytestrings defining labels to apply to this atom.
 
 All data to be printed MUST be encoded into a single frame: this frame
 does not support spanning data across multiple frames.
 
 All textual data encoded in these frames is assumed to be line delimited.
 The last atom in the frame SHOULD end with a newline (``\n``). If it
 doesn't, clients MAY add a newline to facilitate immediate printing.
 
 Progress Update (``0x07``)
 --------------------------
 
 This frame holds the progress of an operation on the peer. Consumption
 of these frames allows clients to display progress bars, estimated
 completion times, etc.
 
 Each frame defines the progress of a single operation on the peer. The
 payload consists of a CBOR map with the following bytestring keys:
 
 topic
    Topic name (string)
 pos
    Current numeric position within the topic (integer)
 total
    Total/end numeric position of this topic (unsigned integer)
 label (optional)
    Unit label (string)
 item (optional)
    Item name (string)
 
 Progress state is created when a frame is received referencing a
 *topic* that isn't currently tracked. Progress tracking for that
 *topic* is finished when a frame is received reporting the current
 position of that topic as ``-1``.
 
 Multiple *topics* may be active at any given time.
 
 Rendering of progress information is not mandated or governed by this
 specification: implementations MAY render progress information however
 they see fit, including not at all.
 
 The string data describing the topic SHOULD be static strings to
 facilitate receivers localizing that string data. The emitter
 MUST normalize all string data to valid UTF-8 and receivers SHOULD
 validate that received data conforms to UTF-8. The topic name
 SHOULD be ASCII.
 
 Stream Encoding Settings (``0x08``)
 -----------------------------------
 
 This frame type holds information defining the content encoding
 settings for a *stream*.
 
 This frame type is likely consumed by the protocol layer and is not
 passed on to applications.
 
 This frame type MUST ONLY occur on frames having the *Beginning of Stream*
 ``Stream Flag`` set.
 
 The payload of this frame defines what content encoding has (possibly)
 been applied to the payloads of subsequent frames in this stream.
 
 The payload begins with an 8-bit integer defining the length of the
 encoding *profile*, followed by the string name of that profile, which
 must be an ASCII string. All bytes that follow can be used by that
 profile for supplemental settings definitions. See the section below
 on defined encoding profiles.
 
 Stream States and Flags
 =======================
 
 Streams can be in two states: *open* and *closed*. An *open* stream
 is active and frames attached to that stream could arrive at any time.
 A *closed* stream is not active. If a frame attached to a *closed*
 stream arrives, that frame MUST have an appropriate stream flag
 set indicating beginning of stream. All streams are in the *closed*
 state by default.
 
 The ``Stream Flags`` field denotes a set of bit flags for defining
 the relationship of this frame within a stream. The following flags
 are defined:
 
 0x01
    Beginning of stream. The first frame in the stream MUST set this
    flag. When received, the ``Stream ID`` this frame is attached to
    becomes ``open``.
 
 0x02
    End of stream. The last frame in a stream MUST set this flag. When
    received, the ``Stream ID`` this frame is attached to becomes
    ``closed``. Any content encoding context associated with this stream
    can be destroyed after processing the payload of this frame.
 
 0x04
    Apply content encoding. When set, any content encoding settings
    defined by the stream should be applied when attempting to read
    the frame. When not set, the frame payload isn't encoded.
 
 Streams
 =======
 
 Streams - along with ``Request IDs`` - facilitate grouping of frames.
 But the purpose of each is quite different and the groupings they
 constitute are independent.
 
 A ``Request ID`` is essentially a tag. It tells you which logical
 request a frame is associated with.
 
 A *stream* is a sequence of frames grouped for the express purpose
 of applying a stateful encoding or for denoting sub-groups of frames.
 
 Unlike ``Request ID``s which span the request and response, a stream
 is unidirectional and stream IDs are independent from client to
 server.
 
 There is no strict hierarchical relationship between ``Request IDs``
 and *streams*. A stream can contain frames having multiple
 ``Request IDs``. Frames belonging to the same ``Request ID`` can
 span multiple streams.
 
 One goal of streams is to facilitate content encoding. A stream can
 define an encoding to be applied to frame payloads. For example, the
 payload transmitted over the wire may contain output from a
 zstandard compression operation and the receiving end may decompress
 that payload to obtain the original data.
 
 The other goal of streams is to facilitate concurrent execution. For
 example, a server could spawn 4 threads to service a request that can
 be easily parallelized. Each of those 4 threads could write into its
 own stream. Those streams could then in turn be delivered to 4 threads
 on the receiving end, with each thread consuming its stream in near
 isolation. The *main* thread on both ends merely does I/O and
 encodes/decodes frame headers: the bulk of the work is done by worker
 threads.
 
 In addition, since content encoding is defined per stream, each
 *worker thread* could perform potentially CPU bound work concurrently
 with other threads. This approach of applying encoding at the
 sub-protocol / stream level eliminates a potential resource constraint
 on the protocol stream as a whole (it is common for the throughput of
 a compression engine to be smaller than the throughput of a network).
 
 Having multiple streams - each with their own encoding settings - also
 facilitates the use of advanced data compression techniques. For
 example, a transmitter could see that it is generating data faster
 and slower than the receiving end is consuming it and adjust its
 compression settings to trade CPU for compression ratio accordingly.
 
 While streams can define a content encoding, not all frames within
 that stream must use that content encoding. This can be useful when
 data is being served from caches and being derived dynamically. A
 cache could pre-compressed data so the server doesn't have to
 recompress it. The ability to pick and choose which frames are
 compressed allows servers to easily send data to the wire without
 involving potentially expensive encoding overhead.
 
 Content Encoding Profiles
 =========================
 
 Streams can have named content encoding *profiles* associated with
 them. A profile defines a shared understanding of content encoding
 settings and behavior.
 
 The following profiles are defined:
 
 TBD
 
 Command Protocol
 ================
 
 A client can request that a remote run a command by sending it
 frames defining that command. This logical stream is composed of
 1 or more ``Command Request`` frames and and 0 or more ``Command Data``
 frames.
 
 All frames composing a single command request MUST be associated with
 the same ``Request ID``.
 
 Clients MAY send additional command requests without waiting on the
 response to a previous command request. If they do so, they MUST ensure
 that the ``Request ID`` field of outbound frames does not conflict
 with that of an active ``Request ID`` whose response has not yet been
 fully received.
 
 Servers MAY respond to commands in a different order than they were
 sent over the wire. Clients MUST be prepared to deal with this. Servers
 also MAY start executing commands in a different order than they were
 received, or MAY execute multiple commands concurrently.
 
 If there is a dependency between commands or a race condition between
 commands executing (e.g. a read-only command that depends on the results
 of a command that mutates the repository), then clients MUST NOT send
 frames issuing a command until a response to all dependent commands has
 been received.
 TODO think about whether we should express dependencies between commands
 to avoid roundtrip latency.
 
 A command is defined by a command name, 0 or more command arguments,
 and optional command data.
 
 Arguments are the recommended mechanism for transferring fixed sets of
 parameters to a command. Data is appropriate for transferring variable
 data. Thinking in terms of HTTP, arguments would be headers and data
 would be the message body.
 
 It is recommended for servers to delay the dispatch of a command
 until all argument have been received. Servers MAY impose limits on the
 maximum argument size.
 TODO define failure mechanism.
 
 Servers MAY dispatch to commands immediately once argument data
 is available or delay until command data is received in full.
 
 Once a ``Command Request`` frame is sent, a client must be prepared to
 receive any of the following frames associated with that request:
 ``Command Response``, ``Error Response``, ``Human Output Side-Channel``,
 ``Progress Update``.
 
 The *main* response for a command will be in ``Command Response`` frames.
 The payloads of these frames consist of 1 or more CBOR encoded values.
 The first CBOR value on the first ``Command Response`` frame is special
 and denotes the overall status of the command. This CBOR map contains
 the following bytestring keys:
 
 status
    (bytestring) A well-defined message containing the overall status of
    this command request. The following values are defined:
 
    ok
       The command was received successfully and its response follows.
    error
       There was an error processing the command. More details about the
       error are encoded in the ``error`` key.
+   redirect
+      The response for this command is available elsewhere. Details on
+      where are in the ``location`` key.
 
 error (optional)
    A map containing information about an encountered error. The map has the
    following keys:
 
    message
       (array of maps) A message describing the error. The message uses the
       same format as those in the ``Human Output Side-Channel`` frame.
 
+location (optional)
+   (map) Presence indicates that a *content redirect* has occurred. The map
+   provides the external location of the content.
+
+   This map contains the following bytestring keys:
+
+   url
+      (bytestring) URL from which this content may be requested.
+
+   mediatype
+      (bytestring) The media type for the fetched content. e.g.
+      ``application/mercurial-*``.
+
+      In some transports, this value is also advertised by the transport.
+      e.g. as the ``Content-Type`` HTTP header.
+
+   size (optional)
+      (unsigned integer) Total size of remote object in bytes. This is
+      the raw size of the entity that will be fetched, minus any
+      non-Mercurial protocol encoding (e.g. HTTP content or transfer
+      encoding.)
+
+   fullhashes (optional)
+      (array of arrays) Content hashes for the entire payload. Each entry
+      is an array of bytestrings containing the hash name and the hash value.
+
+   fullhashseed (optional)
+      (bytestring) Optional seed value to feed into hasher for full content
+      hash verification.
+
+   serverdercerts (optional)
+      (array of bytestring) DER encoded x509 certificates for the server. When
+      defined, clients MAY validate that the x509 certificate on the target
+      server exactly matches the certificate used here.
+
+   servercadercerts (optional)
+      (array of bytestring) DER encoded x509 certificates for the certificate
+      authority of the target server. When defined, clients MAY validate that
+      the x509 on the target server was signed by CA certificate in this set.
+
+   # TODO support for giving client an x509 certificate pair to be used as a
+   # client certificate.
+
+   # TODO support common authentication mechanisms (e.g. HTTP basic/digest
+   # auth).
+
+   # TODO support custom authentication mechanisms. This likely requires
+   # server to advertise required auth mechanism so client can filter.
+
+   # TODO support chained hashes. e.g. hash for each 1MB segment so client
+   # can iteratively validate data without having to consume all of it first.
+
 TODO formalize when error frames can be seen and how errors can be
 recognized midway through a command response.
+
+Content Redirects
+=================
+
+Servers have the ability to respond to ANY command request with a
+*redirect* to another location. Such a response is referred to as a *redirect
+response*. (This feature is conceptually similar to HTTP redirects, but is
+more powerful.)
+
+A *redirect response* MUST ONLY be issued if the client advertises support
+for a redirect *target*.
+
+A *redirect response* MUST NOT be issued unless the client advertises support
+for one.
+
+Clients advertise support for *redirect responses* after looking at the server's
+*capabilities* data, which is fetched during initial server connection
+handshake. The server's capabilities data advertises named *targets* for
+potential redirects.
+
+Each target is described by a protocol name, connection and protocol features,
+etc. The server also advertises target-agnostic redirect settings, such as
+which hash algorithms are supported for content integrity checking. (See
+the documentation for the *capabilities* command for more.)
+
+Clients examine the set of advertised redirect targets for compatibility.
+When sending a command request, the client advertises the set of redirect
+target names it is willing to follow, along with some other settings influencing
+behavior.
+
+For example, say the server is advertising a ``cdn`` redirect target that
+requires SNI and TLS 1.2. If the client supports those features, it will
+send command requests stating that the ``cdn`` target is acceptable to use.
+But if the client doesn't support SNI or TLS 1.2 (or maybe it encountered an
+error using this target from a previous request), then it omits this target
+name.
+
+If the client advertises support for a redirect target, the server MAY
+substitute the normal, inline response data for a *redirect response* -
+one where the initial CBOR map has a ``status`` key with value ``redirect``.
+
+The *redirect response* at a minimum advertises the URL where the response
+can be retrieved.
+
+The *redirect response* MAY also advertise additional details about that
+content and how to retrieve it. Notably, the response may contain the
+x509 public certificates for the server being redirected to or the
+certificate authority that signed that server's certificate. Unless the
+client has existing settings that offer stronger trust validation than what
+the server advertises, the client SHOULD use the server-provided certificates
+when validating the connection to the remote server in place of any default
+connection verification checks. This is because certificates coming from
+the server SHOULD establish a stronger chain of trust than what the default
+certification validation mechanism in most environments provides. (By default,
+certificate validation ensures the signer of the cert chains up to a set of
+trusted root certificates. And if an explicit certificate or CA certificate
+is presented, that greadly reduces the set of certificates that will be
+recognized as valid, thus reducing the potential for a "bad" certificate
+to be used and trusted.)

mercurial/help/internals/wireprotocolv2.txt

@@ -1,507 +1,539 b''
 **Experimental and under active development**
 
 This section documents the wire protocol commands exposed to transports
 using the frame-based protocol. The set of commands exposed through
 these transports is distinct from the set of commands exposed to legacy
 transports.
 
 The frame-based protocol uses CBOR to encode command execution requests.
 All command arguments must be mapped to a specific or set of CBOR data
 types.
 
 The response to many commands is also CBOR. There is no common response
 format: each command defines its own response format.
 
 TODOs
 =====
 
 * Add "node namespace" support to each command. In order to support
   SHA-1 hash transition, we want servers to be able to expose different
   "node namespaces" for the same data. Every command operating on nodes
   should specify which "node namespace" it is operating on and responses
   should encode the "node namespace" accordingly.
 
 Commands
 ========
 
 The sections below detail all commands available to wire protocol version
 2.
 
 branchmap
 ---------
 
 Obtain heads in named branches.
 
 Receives no arguments.
 
 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
          (map) Describes arguments accepted by the command.
 
          Keys are bytestrings denoting the argument name.
 
          Values are maps describing the argument. The map has the following
          bytestring keys:
 
          default
             (varied) The default value for this argument if not specified. Only
             present if ``required`` is not true.
 
          required
             (boolean) Whether the argument must be specified. Failure to send
             required arguments will result in an error executing the command.
 
          type
             (bytestring) The type of the argument. e.g. ``bytes`` or ``bool``.
 
          validvalues
             (set) Values that are recognized for this argument. Some arguments
             only allow a fixed set of values to be specified. These arguments
             may advertise that set in this key. If this set is advertised and
             a value not in this set is specified, the command should result
             in error.
 
       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``.
 
 framingmediatypes
    An array of bytestrings defining the supported framing protocol
    media types. Servers will not accept media types not in this list.
 
 pathfilterprefixes
    (set of bytestring) Matcher prefixes that are recognized when performing
    path filtering. Specifying a path filter whose type/prefix does not
    match one in this set will likely be rejected by the server.
 
 rawrepoformats
    An array of storage formats the repository is using. This set of
    requirements can be used to determine whether a client can read a
    *raw* copy of file data available.
 
+redirect
+   A map declaring potential *content redirects* that may be used by this
+   server. Contains the following bytestring keys:
+
+   targets
+      (array of maps) Potential redirect targets. Values are maps describing
+      this target in more detail. Each map has the following bytestring keys:
+
+      name
+         (bytestring) Identifier for this target. The identifier will be used
+         by clients to uniquely identify this target.
+
+      protocol
+         (bytestring) High-level network protocol. Values can be
+         ``http``, ```https``, ``ssh``, etc.
+
+      uris
+          (array of bytestrings) Representative URIs for this target.
+
+      snirequired (optional)
+          (boolean) Indicates whether Server Name Indication is required
+          to use this target. Defaults to False.
+
+      tlsversions (optional)
+          (array of bytestring) Indicates which TLS versions are supported by
+          this target. Values are ``1.1``, ``1.2``, ``1.3``, etc.
+
+   hashes
+      (array of bytestring) Indicates support for hashing algorithms that are
+      used to ensure content integrity. Values include ``sha1``, ``sha256``,
+      etc.
+
 changesetdata
 -------------
 
 Obtain various data related to changesets.
 
 The command accepts the following arguments:
 
 noderange
    (array of arrays of bytestrings) An array of 2 elements, each being an
    array of node bytestrings. The first array denotes the changelog revisions
    that are already known to the client. The second array denotes the changelog
    revision DAG heads to fetch. The argument essentially defines a DAG range
    bounded by root and head nodes to fetch.
 
    The roots array may be empty. The heads array must be defined.
 
 nodes
    (array of bytestrings) Changelog revisions to request explicitly.
 
 nodesdepth
    (unsigned integer) Number of ancestor revisions of elements in ``nodes``
    to also fetch. When defined, for each element in ``nodes``, DAG ancestors
    will be walked until at most N total revisions are emitted.
 
 fields
    (set of bytestring) Which data associated with changelog revisions to
    fetch. The following values are recognized:
 
    bookmarks
       Bookmarks associated with a revision.
 
    parents
       Parent revisions.
 
    phase
       The phase state of a revision.
 
    revision
       The raw, revision data for the changelog entry. The hash of this data
       will match the revision's node value.
 
 The server resolves the set of revisions relevant to the request by taking
 the union of the ``noderange`` and ``nodes`` arguments. At least one of these
 arguments must be defined.
 
 The response bytestream starts with a CBOR map describing the data that follows.
 This map has the following bytestring keys:
 
 totalitems
    (unsigned integer) Total number of changelog revisions whose data is being
    transferred. This maps to the set of revisions in the requested node
    range, not the total number of records that follow (see below for why).
 
 Following the map header is a series of 0 or more CBOR values. If values
 are present, the first value will always be a map describing a single changeset
 revision.
 
 If the ``fieldsfollowing`` key is present, the map will immediately be followed
 by N CBOR bytestring values, where N is the number of elements in
 ``fieldsfollowing``. Each bytestring value corresponds to a field denoted
 by ``fieldsfollowing``.
 
 Following the optional bytestring field values is the next revision descriptor
 map, or end of stream.
 
 Each revision descriptor map has the following bytestring keys:
 
 node
    (bytestring) The node value for this revision. This is the SHA-1 hash of
    the raw revision data.
 
 bookmarks (optional)
    (array of bytestrings) Bookmarks attached to this revision. Only present
    if ``bookmarks`` data is being requested and the revision has bookmarks
    attached.
 
 fieldsfollowing (optional)
    (array of 2-array) Denotes what fields immediately follow this map. Each
    value is an array with 2 elements: the bytestring field name and an unsigned
    integer describing the length of the data, in bytes.
 
    If this key isn't present, no special fields will follow this map.
 
    The following fields may be present:
 
    revision
       Raw, revision data for the changelog entry. Contains a serialized form
       of the changeset data, including the author, date, commit message, set
       of changed files, manifest node, and other metadata.
 
       Only present if the ``revision`` field was requested.
 
 parents (optional)
    (array of bytestrings) The nodes representing the parent revisions of this
    revision. Only present if ``parents`` data is being requested.
 
 phase (optional)
    (bytestring) The phase that a revision is in. Recognized values are
    ``secret``, ``draft``, and ``public``. Only present if ``phase`` data
    is being requested.
 
 If nodes are requested via ``noderange``, they will be emitted in DAG order,
 parents always before children.
 
 If nodes are requested via ``nodes``, they will be emitted in requested order.
 
 Nodes from ``nodes`` are emitted before nodes from ``noderange``.
 
 The set of changeset revisions emitted may not match the exact set of
 changesets requested. Furthermore, the set of keys present on each
 map may vary. This is to facilitate emitting changeset updates as well
 as new revisions.
 
 For example, if the request wants ``phase`` and ``revision`` data,
 the response may contain entries for each changeset in the common nodes
 set with the ``phase`` key and without the ``revision`` key in order
 to reflect a phase-only update.
 
 TODO support different revision selection mechanisms (e.g. non-public, specific
 revisions)
 TODO support different hash "namespaces" for revisions (e.g. sha-1 versus other)
 TODO support emitting obsolescence data
 TODO support filtering based on relevant paths (narrow clone)
 TODO support hgtagsfnodes cache / tags data
 TODO support branch heads cache
 TODO consider unify query mechanism. e.g. as an array of "query descriptors"
 rather than a set of top-level arguments that have semantics when combined.
 
 filedata
 --------
 
 Obtain various data related to an individual tracked file.
 
 The command accepts the following arguments:
 
 fields
    (set of bytestring) Which data associated with a file to fetch.
    The following values are recognized:
 
    parents
       Parent nodes for the revision.
 
    revision
       The raw revision data for a file.
 
 haveparents
    (bool) Whether the client has the parent revisions of all requested
    nodes. If set, the server may emit revision data as deltas against
    any parent revision. If not set, the server MUST only emit deltas for
    revisions previously emitted by this command.
 
    False is assumed in the absence of any value.
 
 nodes
    (array of bytestrings) File nodes whose data to retrieve.
 
 path
    (bytestring) Path of the tracked file whose data to retrieve.
 
 TODO allow specifying revisions via alternate means (such as from
 changeset revisions or ranges)
 
 The response bytestream starts with a CBOR map describing the data that
 follows. It has the following bytestream keys:
 
 totalitems
    (unsigned integer) Total number of file revisions whose data is
    being returned.
 
 Following the map header is a series of 0 or more CBOR values. If values
 are present, the first value will always be a map describing a single changeset
 revision.
 
 If the ``fieldsfollowing`` key is present, the map will immediately be followed
 by N CBOR bytestring values, where N is the number of elements in
 ``fieldsfollowing``. Each bytestring value corresponds to a field denoted
 by ``fieldsfollowing``.
 
 Following the optional bytestring field values is the next revision descriptor
 map, or end of stream.
 
 Each revision descriptor map has the following bytestring keys:
 
 Each map has the following bytestring keys:
 
 node
    (bytestring) The node of the file revision whose data is represented.
 
 deltabasenode
    (bytestring) Node of the file revision the following delta is against.
 
    Only present if the ``revision`` field is requested and delta data
    follows this map.
 
 fieldsfollowing
    (array of 2-array) Denotes extra bytestring fields that following this map.
    See the documentation for ``changesetdata`` for semantics.
 
    The following named fields may be present:
 
    ``delta``
       The delta data to use to construct the fulltext revision.
 
       Only present if the ``revision`` field is requested and a delta is
       being emitted. The ``deltabasenode`` top-level key will also be
       present if this field is being emitted.
 
    ``revision``
       The fulltext revision data for this manifest. Only present if the
       ``revision`` field is requested and a fulltext revision is being emitted.
 
 parents
    (array of bytestring) The nodes of the parents of this file revision.
 
    Only present if the ``parents`` field is requested.
 
 When ``revision`` data is requested, the server chooses to emit either fulltext
 revision data or a delta. What the server decides can be inferred by looking
 for the presence of the ``delta`` or ``revision`` keys in the
 ``fieldsfollowing`` array.
 
 heads
 -----
 
 Obtain DAG heads in the repository.
 
 The command accepts the following arguments:
 
 publiconly (optional)
    (boolean) If set, operate on the DAG for public phase changesets only.
    Non-public (i.e. draft) phase DAG heads will not be returned.
 
 The response is a CBOR array of bytestrings defining changeset nodes
 of DAG heads. The array can be empty if the repository is empty or no
 changesets satisfied the request.
 
 TODO consider exposing phase of heads in response
 
 known
 -----
 
 Determine whether a series of changeset nodes is known to the server.
 
 The command accepts the following arguments:
 
 nodes
    (array of bytestrings) List of changeset nodes whose presence to
    query.
 
 The response is a bytestring where each byte contains a 0 or 1 for the
 corresponding requested node at the same index.
 
 TODO use a bit array for even more compact response
 
 listkeys
 --------
 
 List values in a specified ``pushkey`` namespace.
 
 The command receives the following arguments:
 
 namespace
    (bytestring) Pushkey namespace to query.
 
 The response is a map with bytestring keys and values.
 
 TODO consider using binary to represent nodes in certain pushkey namespaces.
 
 lookup
 ------
 
 Try to resolve a value to a changeset revision.
 
 Unlike ``known`` which operates on changeset nodes, lookup operates on
 node fragments and other names that a user may use.
 
 The command receives the following arguments:
 
 key
    (bytestring) Value to try to resolve.
 
 On success, returns a bytestring containing the resolved node.
 
 manifestdata
 ------------
 
 Obtain various data related to manifests (which are lists of files in
 a revision).
 
 The command accepts the following arguments:
 
 fields
    (set of bytestring) Which data associated with manifests to fetch.
    The following values are recognized:
 
    parents
       Parent nodes for the manifest.
 
    revision
       The raw revision data for the manifest.
 
 haveparents
    (bool) Whether the client has the parent revisions of all requested
    nodes. If set, the server may emit revision data as deltas against
    any parent revision. If not set, the server MUST only emit deltas for
    revisions previously emitted by this command.
 
    False is assumed in the absence of any value.
 
 nodes
    (array of bytestring) Manifest nodes whose data to retrieve.
 
 tree
    (bytestring) Path to manifest to retrieve. The empty bytestring represents
    the root manifest. All other values represent directories/trees within
    the repository.
 
 TODO allow specifying revisions via alternate means (such as from changeset
 revisions or ranges)
 TODO consider recursive expansion of manifests (with path filtering for
 narrow use cases)
 
 The response bytestream starts with a CBOR map describing the data that
 follows. It has the following bytestring keys:
 
 totalitems
    (unsigned integer) Total number of manifest revisions whose data is
    being returned.
 
 Following the map header is a series of 0 or more CBOR values. If values
 are present, the first value will always be a map describing a single manifest
 revision.
 
 If the ``fieldsfollowing`` key is present, the map will immediately be followed
 by N CBOR bytestring values, where N is the number of elements in
 ``fieldsfollowing``. Each bytestring value corresponds to a field denoted
 by ``fieldsfollowing``.
 
 Following the optional bytestring field values is the next revision descriptor
 map, or end of stream.
 
 Each revision descriptor map has the following bytestring keys:
 
 node
    (bytestring) The node of the manifest revision whose data is represented.
 
 deltabasenode
    (bytestring) The node that the delta representation of this revision is
    computed against. Only present if the ``revision`` field is requested and
    a delta is being emitted.
 
 fieldsfollowing
    (array of 2-array) Denotes extra bytestring fields that following this map.
    See the documentation for ``changesetdata`` for semantics.
 
    The following named fields may be present:
 
    ``delta``
       The delta data to use to construct the fulltext revision.
 
       Only present if the ``revision`` field is requested and a delta is
       being emitted. The ``deltabasenode`` top-level key will also be
       present if this field is being emitted.
 
    ``revision``
       The fulltext revision data for this manifest. Only present if the
       ``revision`` field is requested and a fulltext revision is being emitted.
 
 parents
    (array of bytestring) The nodes of the parents of this manifest revision.
    Only present if the ``parents`` field is requested.
 
 When ``revision`` data is requested, the server chooses to emit either fulltext
 revision data or a delta. What the server decides can be inferred by looking
 for the presence of ``delta`` or ``revision`` in the ``fieldsfollowing`` array.
 
 pushkey
 -------
 
 Set a value using the ``pushkey`` protocol.
 
 The command receives the following arguments:
 
 namespace
    (bytestring) Pushkey namespace to operate on.
 key
    (bytestring) The pushkey key to set.
 old
    (bytestring) Old value for this key.
 new
    (bytestring) New value for this key.
 
 TODO consider using binary to represent nodes is certain pushkey namespaces.
 TODO better define response type and meaning.