wireproto: add streams to frame-based protocol

Previously, the frame-based protocol was just a series of frames,
with each frame associated with a request ID.

In order to scale the protocol, we'll want to enable the use of
compression. While it is possible to enable compression at the
socket/pipe level, this has its disadvantages. The big one is it
undermines the point of frames being standalone, atomic units that
can be read and written: if you add compression above the framing
protocol, you are back to having a stream-based protocol as opposed
to something frame-based.

So in order to preserve frames, compression needs to occur at
the frame payload level.

Compressing each frame's payload individually will limit compression
ratios because the window size of the compressor will be limited
by the max frame size, which is 32-64kb as currently defined. It
will also add CPU overhead, as it is more efficient for compressors
to operate on fewer, larger blocks of data than more, smaller blocks.

So compressing each frame independently is out.

This means we need to compress each frame's payload as if it is part
of a larger stream.

The simplest approach is to have 1 stream per connection. This
could certainly work. However, it has disadvantages (documented below).

We could also have 1 stream per RPC/command invocation. (This is the
model HTTP/2 goes with.) This also has disadvantages.

The main disadvantage to one global stream is that it has the very
real potential to create CPU bottlenecks doing compression. Networks
are only getting faster and the performance of single CPU cores has
been relatively flat. Newer compression formats like zstandard offer
better CPU cycle efficiency than predecessors like zlib. But it still
all too common to saturate your CPU with compression overhead long
before you saturate the network pipe.

The main disadvantage with streams per request is that you can't
reap the benefits of the compression context for multiple requests.
For example, if you send 1000 RPC requests (or HTTP/2 requests for
that matter), the response to each would have its own compression
context. The overall size of the raw responses would be larger because
compression contexts wouldn't be able to reference data from another
request or response.

The approach for streams as implemented in this commit is to support
N streams per connection and for streams to potentially span requests
and responses. As explained by the added internals docs, this
facilitates servers and clients delegating independent streams and
compression to independent threads / CPU cores. This helps alleviate
the CPU bottleneck of compression. This design also allows compression
contexts to be reused across requests/responses. This can result in
improved compression ratios and less overhead for compressors and
decompressors having to build new contexts.

Another feature that was defined was the ability for individual frames
within a stream to declare whether that individual frame's payload
uses the content encoding (read: compression) defined by the stream.
The idea here is that some servers may serve data from a combination
of caches and dynamic resolution. Data coming from caches may be
pre-compressed. We want to facilitate servers being able to essentially
stream bytes from caches to the wire with minimal overhead. Being
able to mix and match with frames are compressed within a stream
enables these types of advanced server functionality.

This commit defines the new streams mechanism. Basic code for
supporting streams in frames has been added. But that code is
seriously lacking and doesn't fully conform to the defined protocol.
For example, we don't close any streams. And support for content
encoding within streams is not yet implemented. The change was
rather invasive and I didn't think it would be reasonable to implement
the entire feature in a single commit.

For the record, I would have loved to reuse an existing multiplexing
protocol to build the new wire protocol on top of. However, I couldn't
find a protocol that offers the performance and scaling characteristics
that I desired. Namely, it should support multiple compression
contexts to facilitate scaling out to multiple CPU cores and
compression contexts should be able to live longer than single RPC
requests. HTTP/2 *almost* fits the bill. But the semantics of HTTP
message exchange state that streams can only live for a single
request-response. We /could/ tunnel on top of HTTP/2 streams and
frames with HEADER and DATA frames. But there's no guarantee that
HTTP/2 libraries and proxies would allow us to use HTTP/2 streams
and frames without the HTTP message exchange semantics defined in
RFC 7540 Section 8. Other RPC protocols like gRPC tunnel are built
on top of HTTP/2 and thus preserve its semantics of stream per
RPC invocation. Even QUIC does this. We could attempt to invent a
higher-level stream that spans HTTP/2 streams. But this would be
violating HTTP/2 because there is no guarantee that HTTP/2 streams
are routed to the same server. The best we can do - which is what
this protocol does - is shoehorn all request and response data into
a single HTTP message and create streams within. At that point, we've
defined a Content-Type in HTTP parlance. It just so happens our
media type can also work as a standalone, stream-based protocol,
without leaning on HTTP or similar protocol.

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

mercurial/debugcommands.py

@@ -1,3075 +1,3076 b''
 # debugcommands.py - command processing for debug* commands
 #
 # Copyright 2005-2016 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from __future__ import absolute_import
 
 import codecs
 import collections
 import difflib
 import errno
 import operator
 import os
 import random
 import re
 import socket
 import ssl
 import stat
 import string
 import subprocess
 import sys
 import tempfile
 import time
 
 from .i18n import _
 from .node import (
     bin,
     hex,
     nullhex,
     nullid,
     nullrev,
     short,
 )
 from . import (
     bundle2,
     changegroup,
     cmdutil,
     color,
     context,
     dagparser,
     dagutil,
     encoding,
     error,
     exchange,
     extensions,
     filemerge,
     fileset,
     formatter,
     hg,
     httppeer,
     localrepo,
     lock as lockmod,
     logcmdutil,
     merge as mergemod,
     obsolete,
     obsutil,
     phases,
     policy,
     pvec,
     pycompat,
     registrar,
     repair,
     revlog,
     revset,
     revsetlang,
     scmutil,
     setdiscovery,
     simplemerge,
     smartset,
     sshpeer,
     sslutil,
     streamclone,
     templater,
     treediscovery,
     upgrade,
     url as urlmod,
     util,
     vfs as vfsmod,
     wireprotoframing,
     wireprotoserver,
 )
 from .utils import (
     dateutil,
     procutil,
     stringutil,
 )
 
 release = lockmod.release
 
 command = registrar.command()
 
 @command('debugancestor', [], _('[INDEX] REV1 REV2'), optionalrepo=True)
 def debugancestor(ui, repo, *args):
     """find the ancestor revision of two revisions in a given index"""
     if len(args) == 3:
         index, rev1, rev2 = args
         r = revlog.revlog(vfsmod.vfs(pycompat.getcwd(), audit=False), index)
         lookup = r.lookup
     elif len(args) == 2:
         if not repo:
             raise error.Abort(_('there is no Mercurial repository here '
                                 '(.hg not found)'))
         rev1, rev2 = args
         r = repo.changelog
         lookup = repo.lookup
     else:
         raise error.Abort(_('either two or three arguments required'))
     a = r.ancestor(lookup(rev1), lookup(rev2))
     ui.write('%d:%s\n' % (r.rev(a), hex(a)))
 
 @command('debugapplystreamclonebundle', [], 'FILE')
 def debugapplystreamclonebundle(ui, repo, fname):
     """apply a stream clone bundle file"""
     f = hg.openpath(ui, fname)
     gen = exchange.readbundle(ui, f, fname)
     gen.apply(repo)
 
 @command('debugbuilddag',
     [('m', 'mergeable-file', None, _('add single file mergeable changes')),
     ('o', 'overwritten-file', None, _('add single file all revs overwrite')),
     ('n', 'new-file', None, _('add new file at each rev'))],
     _('[OPTION]... [TEXT]'))
 def debugbuilddag(ui, repo, text=None,
                   mergeable_file=False,
                   overwritten_file=False,
                   new_file=False):
     """builds a repo with a given DAG from scratch in the current empty repo
 
     The description of the DAG is read from stdin if not given on the
     command line.
 
     Elements:
 
      - "+n" is a linear run of n nodes based on the current default parent
      - "." is a single node based on the current default parent
      - "$" resets the default parent to null (implied at the start);
            otherwise the default parent is always the last node created
      - "<p" sets the default parent to the backref p
      - "*p" is a fork at parent p, which is a backref
      - "*p1/p2" is a merge of parents p1 and p2, which are backrefs
      - "/p2" is a merge of the preceding node and p2
      - ":tag" defines a local tag for the preceding node
      - "@branch" sets the named branch for subsequent nodes
      - "#...\\n" is a comment up to the end of the line
 
     Whitespace between the above elements is ignored.
 
     A backref is either
 
      - a number n, which references the node curr-n, where curr is the current
        node, or
      - the name of a local tag you placed earlier using ":tag", or
      - empty to denote the default parent.
 
     All string valued-elements are either strictly alphanumeric, or must
     be enclosed in double quotes ("..."), with "\\" as escape character.
     """
 
     if text is None:
         ui.status(_("reading DAG from stdin\n"))
         text = ui.fin.read()
 
     cl = repo.changelog
     if len(cl) > 0:
         raise error.Abort(_('repository is not empty'))
 
     # determine number of revs in DAG
     total = 0
     for type, data in dagparser.parsedag(text):
         if type == 'n':
             total += 1
 
     if mergeable_file:
         linesperrev = 2
         # make a file with k lines per rev
         initialmergedlines = ['%d' % i for i in xrange(0, total * linesperrev)]
         initialmergedlines.append("")
 
     tags = []
 
     wlock = lock = tr = None
     try:
         wlock = repo.wlock()
         lock = repo.lock()
         tr = repo.transaction("builddag")
 
         at = -1
         atbranch = 'default'
         nodeids = []
         id = 0
         ui.progress(_('building'), id, unit=_('revisions'), total=total)
         for type, data in dagparser.parsedag(text):
             if type == 'n':
                 ui.note(('node %s\n' % pycompat.bytestr(data)))
                 id, ps = data
 
                 files = []
                 filecontent = {}
 
                 p2 = None
                 if mergeable_file:
                     fn = "mf"
                     p1 = repo[ps[0]]
                     if len(ps) > 1:
                         p2 = repo[ps[1]]
                         pa = p1.ancestor(p2)
                         base, local, other = [x[fn].data() for x in (pa, p1,
                                                                      p2)]
                         m3 = simplemerge.Merge3Text(base, local, other)
                         ml = [l.strip() for l in m3.merge_lines()]
                         ml.append("")
                     elif at > 0:
                         ml = p1[fn].data().split("\n")
                     else:
                         ml = initialmergedlines
                     ml[id * linesperrev] += " r%i" % id
                     mergedtext = "\n".join(ml)
                     files.append(fn)
                     filecontent[fn] = mergedtext
 
                 if overwritten_file:
                     fn = "of"
                     files.append(fn)
                     filecontent[fn] = "r%i\n" % id
 
                 if new_file:
                     fn = "nf%i" % id
                     files.append(fn)
                     filecontent[fn] = "r%i\n" % id
                     if len(ps) > 1:
                         if not p2:
                             p2 = repo[ps[1]]
                         for fn in p2:
                             if fn.startswith("nf"):
                                 files.append(fn)
                                 filecontent[fn] = p2[fn].data()
 
                 def fctxfn(repo, cx, path):
                     if path in filecontent:
                         return context.memfilectx(repo, cx, path,
                                                   filecontent[path])
                     return None
 
                 if len(ps) == 0 or ps[0] < 0:
                     pars = [None, None]
                 elif len(ps) == 1:
                     pars = [nodeids[ps[0]], None]
                 else:
                     pars = [nodeids[p] for p in ps]
                 cx = context.memctx(repo, pars, "r%i" % id, files, fctxfn,
                                     date=(id, 0),
                                     user="debugbuilddag",
                                     extra={'branch': atbranch})
                 nodeid = repo.commitctx(cx)
                 nodeids.append(nodeid)
                 at = id
             elif type == 'l':
                 id, name = data
                 ui.note(('tag %s\n' % name))
                 tags.append("%s %s\n" % (hex(repo.changelog.node(id)), name))
             elif type == 'a':
                 ui.note(('branch %s\n' % data))
                 atbranch = data
             ui.progress(_('building'), id, unit=_('revisions'), total=total)
         tr.close()
 
         if tags:
             repo.vfs.write("localtags", "".join(tags))
     finally:
         ui.progress(_('building'), None)
         release(tr, lock, wlock)
 
 def _debugchangegroup(ui, gen, all=None, indent=0, **opts):
     indent_string = ' ' * indent
     if all:
         ui.write(("%sformat: id, p1, p2, cset, delta base, len(delta)\n")
                  % indent_string)
 
         def showchunks(named):
             ui.write("\n%s%s\n" % (indent_string, named))
             for deltadata in gen.deltaiter():
                 node, p1, p2, cs, deltabase, delta, flags = deltadata
                 ui.write("%s%s %s %s %s %s %d\n" %
                          (indent_string, hex(node), hex(p1), hex(p2),
                           hex(cs), hex(deltabase), len(delta)))
 
         chunkdata = gen.changelogheader()
         showchunks("changelog")
         chunkdata = gen.manifestheader()
         showchunks("manifest")
         for chunkdata in iter(gen.filelogheader, {}):
             fname = chunkdata['filename']
             showchunks(fname)
     else:
         if isinstance(gen, bundle2.unbundle20):
             raise error.Abort(_('use debugbundle2 for this file'))
         chunkdata = gen.changelogheader()
         for deltadata in gen.deltaiter():
             node, p1, p2, cs, deltabase, delta, flags = deltadata
             ui.write("%s%s\n" % (indent_string, hex(node)))
 
 def _debugobsmarkers(ui, part, indent=0, **opts):
     """display version and markers contained in 'data'"""
     opts = pycompat.byteskwargs(opts)
     data = part.read()
     indent_string = ' ' * indent
     try:
         version, markers = obsolete._readmarkers(data)
     except error.UnknownVersion as exc:
         msg = "%sunsupported version: %s (%d bytes)\n"
         msg %= indent_string, exc.version, len(data)
         ui.write(msg)
     else:
         msg = "%sversion: %d (%d bytes)\n"
         msg %= indent_string, version, len(data)
         ui.write(msg)
         fm = ui.formatter('debugobsolete', opts)
         for rawmarker in sorted(markers):
             m = obsutil.marker(None, rawmarker)
             fm.startitem()
             fm.plain(indent_string)
             cmdutil.showmarker(fm, m)
         fm.end()
 
 def _debugphaseheads(ui, data, indent=0):
     """display version and markers contained in 'data'"""
     indent_string = ' ' * indent
     headsbyphase = phases.binarydecode(data)
     for phase in phases.allphases:
         for head in headsbyphase[phase]:
             ui.write(indent_string)
             ui.write('%s %s\n' % (hex(head), phases.phasenames[phase]))
 
 def _quasirepr(thing):
     if isinstance(thing, (dict, util.sortdict, collections.OrderedDict)):
         return '{%s}' % (
             b', '.join(b'%s: %s' % (k, thing[k]) for k in sorted(thing)))
     return pycompat.bytestr(repr(thing))
 
 def _debugbundle2(ui, gen, all=None, **opts):
     """lists the contents of a bundle2"""
     if not isinstance(gen, bundle2.unbundle20):
         raise error.Abort(_('not a bundle2 file'))
     ui.write(('Stream params: %s\n' % _quasirepr(gen.params)))
     parttypes = opts.get(r'part_type', [])
     for part in gen.iterparts():
         if parttypes and part.type not in parttypes:
             continue
         ui.write('%s -- %s\n' % (part.type, _quasirepr(part.params)))
         if part.type == 'changegroup':
             version = part.params.get('version', '01')
             cg = changegroup.getunbundler(version, part, 'UN')
             if not ui.quiet:
                 _debugchangegroup(ui, cg, all=all, indent=4, **opts)
         if part.type == 'obsmarkers':
             if not ui.quiet:
                 _debugobsmarkers(ui, part, indent=4, **opts)
         if part.type == 'phase-heads':
             if not ui.quiet:
                 _debugphaseheads(ui, part, indent=4)
 
 @command('debugbundle',
         [('a', 'all', None, _('show all details')),
          ('', 'part-type', [], _('show only the named part type')),
          ('', 'spec', None, _('print the bundlespec of the bundle'))],
         _('FILE'),
         norepo=True)
 def debugbundle(ui, bundlepath, all=None, spec=None, **opts):
     """lists the contents of a bundle"""
     with hg.openpath(ui, bundlepath) as f:
         if spec:
             spec = exchange.getbundlespec(ui, f)
             ui.write('%s\n' % spec)
             return
 
         gen = exchange.readbundle(ui, f, bundlepath)
         if isinstance(gen, bundle2.unbundle20):
             return _debugbundle2(ui, gen, all=all, **opts)
         _debugchangegroup(ui, gen, all=all, **opts)
 
 @command('debugcapabilities',
         [], _('PATH'),
         norepo=True)
 def debugcapabilities(ui, path, **opts):
     """lists the capabilities of a remote peer"""
     opts = pycompat.byteskwargs(opts)
     peer = hg.peer(ui, opts, path)
     caps = peer.capabilities()
     ui.write(('Main capabilities:\n'))
     for c in sorted(caps):
         ui.write(('  %s\n') % c)
     b2caps = bundle2.bundle2caps(peer)
     if b2caps:
         ui.write(('Bundle2 capabilities:\n'))
         for key, values in sorted(b2caps.iteritems()):
             ui.write(('  %s\n') % key)
             for v in values:
                 ui.write(('    %s\n') % v)
 
 @command('debugcheckstate', [], '')
 def debugcheckstate(ui, repo):
     """validate the correctness of the current dirstate"""
     parent1, parent2 = repo.dirstate.parents()
     m1 = repo[parent1].manifest()
     m2 = repo[parent2].manifest()
     errors = 0
     for f in repo.dirstate:
         state = repo.dirstate[f]
         if state in "nr" and f not in m1:
             ui.warn(_("%s in state %s, but not in manifest1\n") % (f, state))
             errors += 1
         if state in "a" and f in m1:
             ui.warn(_("%s in state %s, but also in manifest1\n") % (f, state))
             errors += 1
         if state in "m" and f not in m1 and f not in m2:
             ui.warn(_("%s in state %s, but not in either manifest\n") %
                     (f, state))
             errors += 1
     for f in m1:
         state = repo.dirstate[f]
         if state not in "nrm":
             ui.warn(_("%s in manifest1, but listed as state %s") % (f, state))
             errors += 1
     if errors:
         error = _(".hg/dirstate inconsistent with current parent's manifest")
         raise error.Abort(error)
 
 @command('debugcolor',
         [('', 'style', None, _('show all configured styles'))],
         'hg debugcolor')
 def debugcolor(ui, repo, **opts):
     """show available color, effects or style"""
     ui.write(('color mode: %s\n') % ui._colormode)
     if opts.get(r'style'):
         return _debugdisplaystyle(ui)
     else:
         return _debugdisplaycolor(ui)
 
 def _debugdisplaycolor(ui):
     ui = ui.copy()
     ui._styles.clear()
     for effect in color._activeeffects(ui).keys():
         ui._styles[effect] = effect
     if ui._terminfoparams:
         for k, v in ui.configitems('color'):
             if k.startswith('color.'):
                 ui._styles[k] = k[6:]
             elif k.startswith('terminfo.'):
                 ui._styles[k] = k[9:]
     ui.write(_('available colors:\n'))
     # sort label with a '_' after the other to group '_background' entry.
     items = sorted(ui._styles.items(),
                    key=lambda i: ('_' in i[0], i[0], i[1]))
     for colorname, label in items:
         ui.write(('%s\n') % colorname, label=label)
 
 def _debugdisplaystyle(ui):
     ui.write(_('available style:\n'))
     width = max(len(s) for s in ui._styles)
     for label, effects in sorted(ui._styles.items()):
         ui.write('%s' % label, label=label)
         if effects:
             # 50
             ui.write(': ')
             ui.write(' ' * (max(0, width - len(label))))
             ui.write(', '.join(ui.label(e, e) for e in effects.split()))
         ui.write('\n')
 
 @command('debugcreatestreamclonebundle', [], 'FILE')
 def debugcreatestreamclonebundle(ui, repo, fname):
     """create a stream clone bundle file
 
     Stream bundles are special bundles that are essentially archives of
     revlog files. They are commonly used for cloning very quickly.
     """
     # TODO we may want to turn this into an abort when this functionality
     # is moved into `hg bundle`.
     if phases.hassecret(repo):
         ui.warn(_('(warning: stream clone bundle will contain secret '
                   'revisions)\n'))
 
     requirements, gen = streamclone.generatebundlev1(repo)
     changegroup.writechunks(ui, gen, fname)
 
     ui.write(_('bundle requirements: %s\n') % ', '.join(sorted(requirements)))
 
 @command('debugdag',
     [('t', 'tags', None, _('use tags as labels')),
     ('b', 'branches', None, _('annotate with branch names')),
     ('', 'dots', None, _('use dots for runs')),
     ('s', 'spaces', None, _('separate elements by spaces'))],
     _('[OPTION]... [FILE [REV]...]'),
     optionalrepo=True)
 def debugdag(ui, repo, file_=None, *revs, **opts):
     """format the changelog or an index DAG as a concise textual description
 
     If you pass a revlog index, the revlog's DAG is emitted. If you list
     revision numbers, they get labeled in the output as rN.
 
     Otherwise, the changelog DAG of the current repo is emitted.
     """
     spaces = opts.get(r'spaces')
     dots = opts.get(r'dots')
     if file_:
         rlog = revlog.revlog(vfsmod.vfs(pycompat.getcwd(), audit=False),
                              file_)
         revs = set((int(r) for r in revs))
         def events():
             for r in rlog:
                 yield 'n', (r, list(p for p in rlog.parentrevs(r)
                                         if p != -1))
                 if r in revs:
                     yield 'l', (r, "r%i" % r)
     elif repo:
         cl = repo.changelog
         tags = opts.get(r'tags')
         branches = opts.get(r'branches')
         if tags:
             labels = {}
             for l, n in repo.tags().items():
                 labels.setdefault(cl.rev(n), []).append(l)
         def events():
             b = "default"
             for r in cl:
                 if branches:
                     newb = cl.read(cl.node(r))[5]['branch']
                     if newb != b:
                         yield 'a', newb
                         b = newb
                 yield 'n', (r, list(p for p in cl.parentrevs(r)
                                         if p != -1))
                 if tags:
                     ls = labels.get(r)
                     if ls:
                         for l in ls:
                             yield 'l', (r, l)
     else:
         raise error.Abort(_('need repo for changelog dag'))
 
     for line in dagparser.dagtextlines(events(),
                                        addspaces=spaces,
                                        wraplabels=True,
                                        wrapannotations=True,
                                        wrapnonlinear=dots,
                                        usedots=dots,
                                        maxlinewidth=70):
         ui.write(line)
         ui.write("\n")
 
 @command('debugdata', cmdutil.debugrevlogopts, _('-c|-m|FILE REV'))
 def debugdata(ui, repo, file_, rev=None, **opts):
     """dump the contents of a data file revision"""
     opts = pycompat.byteskwargs(opts)
     if opts.get('changelog') or opts.get('manifest') or opts.get('dir'):
         if rev is not None:
             raise error.CommandError('debugdata', _('invalid arguments'))
         file_, rev = None, file_
     elif rev is None:
         raise error.CommandError('debugdata', _('invalid arguments'))
     r = cmdutil.openrevlog(repo, 'debugdata', file_, opts)
     try:
         ui.write(r.revision(r.lookup(rev), raw=True))
     except KeyError:
         raise error.Abort(_('invalid revision identifier %s') % rev)
 
 @command('debugdate',
     [('e', 'extended', None, _('try extended date formats'))],
     _('[-e] DATE [RANGE]'),
     norepo=True, optionalrepo=True)
 def debugdate(ui, date, range=None, **opts):
     """parse and display a date"""
     if opts[r"extended"]:
         d = dateutil.parsedate(date, util.extendeddateformats)
     else:
         d = dateutil.parsedate(date)
     ui.write(("internal: %d %d\n") % d)
     ui.write(("standard: %s\n") % dateutil.datestr(d))
     if range:
         m = dateutil.matchdate(range)
         ui.write(("match: %s\n") % m(d[0]))
 
 @command('debugdeltachain',
     cmdutil.debugrevlogopts + cmdutil.formatteropts,
     _('-c|-m|FILE'),
     optionalrepo=True)
 def debugdeltachain(ui, repo, file_=None, **opts):
     """dump information about delta chains in a revlog
 
     Output can be templatized. Available template keywords are:
 
     :``rev``:       revision number
     :``chainid``:   delta chain identifier (numbered by unique base)
     :``chainlen``:  delta chain length to this revision
     :``prevrev``:   previous revision in delta chain
     :``deltatype``: role of delta / how it was computed
     :``compsize``:  compressed size of revision
     :``uncompsize``: uncompressed size of revision
     :``chainsize``: total size of compressed revisions in chain
     :``chainratio``: total chain size divided by uncompressed revision size
                     (new delta chains typically start at ratio 2.00)
     :``lindist``:   linear distance from base revision in delta chain to end
                     of this revision
     :``extradist``: total size of revisions not part of this delta chain from
                     base of delta chain to end of this revision; a measurement
                     of how much extra data we need to read/seek across to read
                     the delta chain for this revision
     :``extraratio``: extradist divided by chainsize; another representation of
                     how much unrelated data is needed to load this delta chain
 
     If the repository is configured to use the sparse read, additional keywords
     are available:
 
     :``readsize``:     total size of data read from the disk for a revision
                        (sum of the sizes of all the blocks)
     :``largestblock``: size of the largest block of data read from the disk
     :``readdensity``:  density of useful bytes in the data read from the disk
     :``srchunks``:  in how many data hunks the whole revision would be read
 
     The sparse read can be enabled with experimental.sparse-read = True
     """
     opts = pycompat.byteskwargs(opts)
     r = cmdutil.openrevlog(repo, 'debugdeltachain', file_, opts)
     index = r.index
     generaldelta = r.version & revlog.FLAG_GENERALDELTA
     withsparseread = getattr(r, '_withsparseread', False)
 
     def revinfo(rev):
         e = index[rev]
         compsize = e[1]
         uncompsize = e[2]
         chainsize = 0
 
         if generaldelta:
             if e[3] == e[5]:
                 deltatype = 'p1'
             elif e[3] == e[6]:
                 deltatype = 'p2'
             elif e[3] == rev - 1:
                 deltatype = 'prev'
             elif e[3] == rev:
                 deltatype = 'base'
             else:
                 deltatype = 'other'
         else:
             if e[3] == rev:
                 deltatype = 'base'
             else:
                 deltatype = 'prev'
 
         chain = r._deltachain(rev)[0]
         for iterrev in chain:
             e = index[iterrev]
             chainsize += e[1]
 
         return compsize, uncompsize, deltatype, chain, chainsize
 
     fm = ui.formatter('debugdeltachain', opts)
 
     fm.plain('    rev  chain# chainlen     prev   delta       '
              'size    rawsize  chainsize     ratio   lindist extradist '
              'extraratio')
     if withsparseread:
         fm.plain('   readsize largestblk rddensity srchunks')
     fm.plain('\n')
 
     chainbases = {}
     for rev in r:
         comp, uncomp, deltatype, chain, chainsize = revinfo(rev)
         chainbase = chain[0]
         chainid = chainbases.setdefault(chainbase, len(chainbases) + 1)
         start = r.start
         length = r.length
         basestart = start(chainbase)
         revstart = start(rev)
         lineardist = revstart + comp - basestart
         extradist = lineardist - chainsize
         try:
             prevrev = chain[-2]
         except IndexError:
             prevrev = -1
 
         chainratio = float(chainsize) / float(uncomp)
         extraratio = float(extradist) / float(chainsize)
 
         fm.startitem()
         fm.write('rev chainid chainlen prevrev deltatype compsize '
                  'uncompsize chainsize chainratio lindist extradist '
                  'extraratio',
                  '%7d %7d %8d %8d %7s %10d %10d %10d %9.5f %9d %9d %10.5f',
                  rev, chainid, len(chain), prevrev, deltatype, comp,
                  uncomp, chainsize, chainratio, lineardist, extradist,
                  extraratio,
                  rev=rev, chainid=chainid, chainlen=len(chain),
                  prevrev=prevrev, deltatype=deltatype, compsize=comp,
                  uncompsize=uncomp, chainsize=chainsize,
                  chainratio=chainratio, lindist=lineardist,
                  extradist=extradist, extraratio=extraratio)
         if withsparseread:
             readsize = 0
             largestblock = 0
             srchunks = 0
 
             for revschunk in revlog._slicechunk(r, chain):
                 srchunks += 1
                 blkend = start(revschunk[-1]) + length(revschunk[-1])
                 blksize = blkend - start(revschunk[0])
 
                 readsize += blksize
                 if largestblock < blksize:
                     largestblock = blksize
 
             readdensity = float(chainsize) / float(readsize)
 
             fm.write('readsize largestblock readdensity srchunks',
                      ' %10d %10d %9.5f %8d',
                      readsize, largestblock, readdensity, srchunks,
                      readsize=readsize, largestblock=largestblock,
                      readdensity=readdensity, srchunks=srchunks)
 
         fm.plain('\n')
 
     fm.end()
 
 @command('debugdirstate|debugstate',
     [('', 'nodates', None, _('do not display the saved mtime')),
     ('', 'datesort', None, _('sort by saved mtime'))],
     _('[OPTION]...'))
 def debugstate(ui, repo, **opts):
     """show the contents of the current dirstate"""
 
     nodates = opts.get(r'nodates')
     datesort = opts.get(r'datesort')
 
     timestr = ""
     if datesort:
         keyfunc = lambda x: (x[1][3], x[0]) # sort by mtime, then by filename
     else:
         keyfunc = None # sort by filename
     for file_, ent in sorted(repo.dirstate._map.iteritems(), key=keyfunc):
         if ent[3] == -1:
             timestr = 'unset               '
         elif nodates:
             timestr = 'set                 '
         else:
             timestr = time.strftime(r"%Y-%m-%d %H:%M:%S ",
                                     time.localtime(ent[3]))
             timestr = encoding.strtolocal(timestr)
         if ent[1] & 0o20000:
             mode = 'lnk'
         else:
             mode = '%3o' % (ent[1] & 0o777 & ~util.umask)
         ui.write("%c %s %10d %s%s\n" % (ent[0], mode, ent[2], timestr, file_))
     for f in repo.dirstate.copies():
         ui.write(_("copy: %s -> %s\n") % (repo.dirstate.copied(f), f))
 
 @command('debugdiscovery',
     [('', 'old', None, _('use old-style discovery')),
     ('', 'nonheads', None,
      _('use old-style discovery with non-heads included')),
     ('', 'rev', [], 'restrict discovery to this set of revs'),
     ] + cmdutil.remoteopts,
     _('[--rev REV] [OTHER]'))
 def debugdiscovery(ui, repo, remoteurl="default", **opts):
     """runs the changeset discovery protocol in isolation"""
     opts = pycompat.byteskwargs(opts)
     remoteurl, branches = hg.parseurl(ui.expandpath(remoteurl))
     remote = hg.peer(repo, opts, remoteurl)
     ui.status(_('comparing with %s\n') % util.hidepassword(remoteurl))
 
     # make sure tests are repeatable
     random.seed(12323)
 
     def doit(pushedrevs, remoteheads, remote=remote):
         if opts.get('old'):
             if not util.safehasattr(remote, 'branches'):
                 # enable in-client legacy support
                 remote = localrepo.locallegacypeer(remote.local())
             common, _in, hds = treediscovery.findcommonincoming(repo, remote,
                                                                 force=True)
             common = set(common)
             if not opts.get('nonheads'):
                 ui.write(("unpruned common: %s\n") %
                          " ".join(sorted(short(n) for n in common)))
                 dag = dagutil.revlogdag(repo.changelog)
                 all = dag.ancestorset(dag.internalizeall(common))
                 common = dag.externalizeall(dag.headsetofconnecteds(all))
         else:
             nodes = None
             if pushedrevs:
                 revs = scmutil.revrange(repo, pushedrevs)
                 nodes = [repo[r].node() for r in revs]
             common, any, hds = setdiscovery.findcommonheads(ui, repo, remote,
                                                             ancestorsof=nodes)
         common = set(common)
         rheads = set(hds)
         lheads = set(repo.heads())
         ui.write(("common heads: %s\n") %
                  " ".join(sorted(short(n) for n in common)))
         if lheads <= common:
             ui.write(("local is subset\n"))
         elif rheads <= common:
             ui.write(("remote is subset\n"))
 
     remoterevs, _checkout = hg.addbranchrevs(repo, remote, branches, revs=None)
     localrevs = opts['rev']
     doit(localrevs, remoterevs)
 
 _chunksize = 4 << 10
 
 @command('debugdownload',
     [
         ('o', 'output', '', _('path')),
     ],
     optionalrepo=True)
 def debugdownload(ui, repo, url, output=None, **opts):
     """download a resource using Mercurial logic and config
     """
     fh = urlmod.open(ui, url, output)
 
     dest = ui
     if output:
         dest = open(output, "wb", _chunksize)
     try:
         data = fh.read(_chunksize)
         while data:
             dest.write(data)
             data = fh.read(_chunksize)
     finally:
         if output:
             dest.close()
 
 @command('debugextensions', cmdutil.formatteropts, [], norepo=True)
 def debugextensions(ui, **opts):
     '''show information about active extensions'''
     opts = pycompat.byteskwargs(opts)
     exts = extensions.extensions(ui)
     hgver = util.version()
     fm = ui.formatter('debugextensions', opts)
     for extname, extmod in sorted(exts, key=operator.itemgetter(0)):
         isinternal = extensions.ismoduleinternal(extmod)
         extsource = pycompat.fsencode(extmod.__file__)
         if isinternal:
             exttestedwith = []  # never expose magic string to users
         else:
             exttestedwith = getattr(extmod, 'testedwith', '').split()
         extbuglink = getattr(extmod, 'buglink', None)
 
         fm.startitem()
 
         if ui.quiet or ui.verbose:
             fm.write('name', '%s\n', extname)
         else:
             fm.write('name', '%s', extname)
             if isinternal or hgver in exttestedwith:
                 fm.plain('\n')
             elif not exttestedwith:
                 fm.plain(_(' (untested!)\n'))
             else:
                 lasttestedversion = exttestedwith[-1]
                 fm.plain(' (%s!)\n' % lasttestedversion)
 
         fm.condwrite(ui.verbose and extsource, 'source',
                  _('  location: %s\n'), extsource or "")
 
         if ui.verbose:
             fm.plain(_('  bundled: %s\n') % ['no', 'yes'][isinternal])
         fm.data(bundled=isinternal)
 
         fm.condwrite(ui.verbose and exttestedwith, 'testedwith',
                      _('  tested with: %s\n'),
                      fm.formatlist(exttestedwith, name='ver'))
 
         fm.condwrite(ui.verbose and extbuglink, 'buglink',
                  _('  bug reporting: %s\n'), extbuglink or "")
 
     fm.end()
 
 @command('debugfileset',
     [('r', 'rev', '', _('apply the filespec on this revision'), _('REV'))],
     _('[-r REV] FILESPEC'))
 def debugfileset(ui, repo, expr, **opts):
     '''parse and apply a fileset specification'''
     ctx = scmutil.revsingle(repo, opts.get(r'rev'), None)
     if ui.verbose:
         tree = fileset.parse(expr)
         ui.note(fileset.prettyformat(tree), "\n")
 
     for f in ctx.getfileset(expr):
         ui.write("%s\n" % f)
 
 @command('debugformat',
          [] + cmdutil.formatteropts,
         _(''))
 def debugformat(ui, repo, **opts):
     """display format information about the current repository
 
     Use --verbose to get extra information about current config value and
     Mercurial default."""
     opts = pycompat.byteskwargs(opts)
     maxvariantlength = max(len(fv.name) for fv in upgrade.allformatvariant)
     maxvariantlength = max(len('format-variant'), maxvariantlength)
 
     def makeformatname(name):
         return '%s:' + (' ' * (maxvariantlength - len(name)))
 
     fm = ui.formatter('debugformat', opts)
     if fm.isplain():
         def formatvalue(value):
             if util.safehasattr(value, 'startswith'):
                 return value
             if value:
                 return 'yes'
             else:
                 return 'no'
     else:
         formatvalue = pycompat.identity
 
     fm.plain('format-variant')
     fm.plain(' ' * (maxvariantlength - len('format-variant')))
     fm.plain(' repo')
     if ui.verbose:
         fm.plain(' config default')
     fm.plain('\n')
     for fv in upgrade.allformatvariant:
         fm.startitem()
         repovalue = fv.fromrepo(repo)
         configvalue = fv.fromconfig(repo)
 
         if repovalue != configvalue:
             namelabel = 'formatvariant.name.mismatchconfig'
             repolabel = 'formatvariant.repo.mismatchconfig'
         elif repovalue != fv.default:
             namelabel = 'formatvariant.name.mismatchdefault'
             repolabel = 'formatvariant.repo.mismatchdefault'
         else:
             namelabel = 'formatvariant.name.uptodate'
             repolabel = 'formatvariant.repo.uptodate'
 
         fm.write('name', makeformatname(fv.name), fv.name,
                  label=namelabel)
         fm.write('repo', ' %3s', formatvalue(repovalue),
                  label=repolabel)
         if fv.default != configvalue:
             configlabel = 'formatvariant.config.special'
         else:
             configlabel = 'formatvariant.config.default'
         fm.condwrite(ui.verbose, 'config', ' %6s', formatvalue(configvalue),
                      label=configlabel)
         fm.condwrite(ui.verbose, 'default', ' %7s', formatvalue(fv.default),
                      label='formatvariant.default')
         fm.plain('\n')
     fm.end()
 
 @command('debugfsinfo', [], _('[PATH]'), norepo=True)
 def debugfsinfo(ui, path="."):
     """show information detected about current filesystem"""
     ui.write(('path: %s\n') % path)
     ui.write(('mounted on: %s\n') % (util.getfsmountpoint(path) or '(unknown)'))
     ui.write(('exec: %s\n') % (util.checkexec(path) and 'yes' or 'no'))
     ui.write(('fstype: %s\n') % (util.getfstype(path) or '(unknown)'))
     ui.write(('symlink: %s\n') % (util.checklink(path) and 'yes' or 'no'))
     ui.write(('hardlink: %s\n') % (util.checknlink(path) and 'yes' or 'no'))
     casesensitive = '(unknown)'
     try:
         with tempfile.NamedTemporaryFile(prefix='.debugfsinfo', dir=path) as f:
             casesensitive = util.fscasesensitive(f.name) and 'yes' or 'no'
     except OSError:
         pass
     ui.write(('case-sensitive: %s\n') % casesensitive)
 
 @command('debuggetbundle',
     [('H', 'head', [], _('id of head node'), _('ID')),
     ('C', 'common', [], _('id of common node'), _('ID')),
     ('t', 'type', 'bzip2', _('bundle compression type to use'), _('TYPE'))],
     _('REPO FILE [-H|-C ID]...'),
     norepo=True)
 def debuggetbundle(ui, repopath, bundlepath, head=None, common=None, **opts):
     """retrieves a bundle from a repo
 
     Every ID must be a full-length hex node id string. Saves the bundle to the
     given file.
     """
     opts = pycompat.byteskwargs(opts)
     repo = hg.peer(ui, opts, repopath)
     if not repo.capable('getbundle'):
         raise error.Abort("getbundle() not supported by target repository")
     args = {}
     if common:
         args[r'common'] = [bin(s) for s in common]
     if head:
         args[r'heads'] = [bin(s) for s in head]
     # TODO: get desired bundlecaps from command line.
     args[r'bundlecaps'] = None
     bundle = repo.getbundle('debug', **args)
 
     bundletype = opts.get('type', 'bzip2').lower()
     btypes = {'none': 'HG10UN',
               'bzip2': 'HG10BZ',
               'gzip': 'HG10GZ',
               'bundle2': 'HG20'}
     bundletype = btypes.get(bundletype)
     if bundletype not in bundle2.bundletypes:
         raise error.Abort(_('unknown bundle type specified with --type'))
     bundle2.writebundle(ui, bundle, bundlepath, bundletype)
 
 @command('debugignore', [], '[FILE]')
 def debugignore(ui, repo, *files, **opts):
     """display the combined ignore pattern and information about ignored files
 
     With no argument display the combined ignore pattern.
 
     Given space separated file names, shows if the given file is ignored and
     if so, show the ignore rule (file and line number) that matched it.
     """
     ignore = repo.dirstate._ignore
     if not files:
         # Show all the patterns
         ui.write("%s\n" % pycompat.byterepr(ignore))
     else:
         m = scmutil.match(repo[None], pats=files)
         for f in m.files():
             nf = util.normpath(f)
             ignored = None
             ignoredata = None
             if nf != '.':
                 if ignore(nf):
                     ignored = nf
                     ignoredata = repo.dirstate._ignorefileandline(nf)
                 else:
                     for p in util.finddirs(nf):
                         if ignore(p):
                             ignored = p
                             ignoredata = repo.dirstate._ignorefileandline(p)
                             break
             if ignored:
                 if ignored == nf:
                     ui.write(_("%s is ignored\n") % m.uipath(f))
                 else:
                     ui.write(_("%s is ignored because of "
                                "containing folder %s\n")
                              % (m.uipath(f), ignored))
                 ignorefile, lineno, line = ignoredata
                 ui.write(_("(ignore rule in %s, line %d: '%s')\n")
                          % (ignorefile, lineno, line))
             else:
                 ui.write(_("%s is not ignored\n") % m.uipath(f))
 
 @command('debugindex', cmdutil.debugrevlogopts +
     [('f', 'format', 0, _('revlog format'), _('FORMAT'))],
     _('[-f FORMAT] -c|-m|FILE'),
     optionalrepo=True)
 def debugindex(ui, repo, file_=None, **opts):
     """dump the contents of an index file"""
     opts = pycompat.byteskwargs(opts)
     r = cmdutil.openrevlog(repo, 'debugindex', file_, opts)
     format = opts.get('format', 0)
     if format not in (0, 1):
         raise error.Abort(_("unknown format %d") % format)
 
     if ui.debugflag:
         shortfn = hex
     else:
         shortfn = short
 
     # There might not be anything in r, so have a sane default
     idlen = 12
     for i in r:
         idlen = len(shortfn(r.node(i)))
         break
 
     if format == 0:
         if ui.verbose:
             ui.write(("   rev    offset  length linkrev"
                      " %s %s p2\n") % ("nodeid".ljust(idlen),
                                        "p1".ljust(idlen)))
         else:
             ui.write(("   rev linkrev %s %s p2\n") % (
                 "nodeid".ljust(idlen), "p1".ljust(idlen)))
     elif format == 1:
         if ui.verbose:
             ui.write(("   rev flag   offset   length     size   link     p1"
                       "     p2 %s\n") % "nodeid".rjust(idlen))
         else:
             ui.write(("   rev flag     size   link     p1     p2 %s\n") %
                      "nodeid".rjust(idlen))
 
     for i in r:
         node = r.node(i)
         if format == 0:
             try:
                 pp = r.parents(node)
             except Exception:
                 pp = [nullid, nullid]
             if ui.verbose:
                 ui.write("% 6d % 9d % 7d % 7d %s %s %s\n" % (
                         i, r.start(i), r.length(i), r.linkrev(i),
                         shortfn(node), shortfn(pp[0]), shortfn(pp[1])))
             else:
                 ui.write("% 6d % 7d %s %s %s\n" % (
                     i, r.linkrev(i), shortfn(node), shortfn(pp[0]),
                     shortfn(pp[1])))
         elif format == 1:
             pr = r.parentrevs(i)
             if ui.verbose:
                 ui.write("% 6d %04x % 8d % 8d % 8d % 6d % 6d % 6d %s\n" % (
                         i, r.flags(i), r.start(i), r.length(i), r.rawsize(i),
                         r.linkrev(i), pr[0], pr[1], shortfn(node)))
             else:
                 ui.write("% 6d %04x % 8d % 6d % 6d % 6d %s\n" % (
                     i, r.flags(i), r.rawsize(i), r.linkrev(i), pr[0], pr[1],
                     shortfn(node)))
 
 @command('debugindexdot', cmdutil.debugrevlogopts,
     _('-c|-m|FILE'), optionalrepo=True)
 def debugindexdot(ui, repo, file_=None, **opts):
     """dump an index DAG as a graphviz dot file"""
     opts = pycompat.byteskwargs(opts)
     r = cmdutil.openrevlog(repo, 'debugindexdot', file_, opts)
     ui.write(("digraph G {\n"))
     for i in r:
         node = r.node(i)
         pp = r.parents(node)
         ui.write("\t%d -> %d\n" % (r.rev(pp[0]), i))
         if pp[1] != nullid:
             ui.write("\t%d -> %d\n" % (r.rev(pp[1]), i))
     ui.write("}\n")
 
 @command('debuginstall', [] + cmdutil.formatteropts, '', norepo=True)
 def debuginstall(ui, **opts):
     '''test Mercurial installation
 
     Returns 0 on success.
     '''
     opts = pycompat.byteskwargs(opts)
 
     def writetemp(contents):
         (fd, name) = tempfile.mkstemp(prefix="hg-debuginstall-")
         f = os.fdopen(fd, r"wb")
         f.write(contents)
         f.close()
         return name
 
     problems = 0
 
     fm = ui.formatter('debuginstall', opts)
     fm.startitem()
 
     # encoding
     fm.write('encoding', _("checking encoding (%s)...\n"), encoding.encoding)
     err = None
     try:
         codecs.lookup(pycompat.sysstr(encoding.encoding))
     except LookupError as inst:
         err = stringutil.forcebytestr(inst)
         problems += 1
     fm.condwrite(err, 'encodingerror', _(" %s\n"
                  " (check that your locale is properly set)\n"), err)
 
     # Python
     fm.write('pythonexe', _("checking Python executable (%s)\n"),
              pycompat.sysexecutable)
     fm.write('pythonver', _("checking Python version (%s)\n"),
              ("%d.%d.%d" % sys.version_info[:3]))
     fm.write('pythonlib', _("checking Python lib (%s)...\n"),
              os.path.dirname(pycompat.fsencode(os.__file__)))
 
     security = set(sslutil.supportedprotocols)
     if sslutil.hassni:
         security.add('sni')
 
     fm.write('pythonsecurity', _("checking Python security support (%s)\n"),
              fm.formatlist(sorted(security), name='protocol',
                            fmt='%s', sep=','))
 
     # These are warnings, not errors. So don't increment problem count. This
     # may change in the future.
     if 'tls1.2' not in security:
         fm.plain(_('  TLS 1.2 not supported by Python install; '
                    'network connections lack modern security\n'))
     if 'sni' not in security:
         fm.plain(_('  SNI not supported by Python install; may have '
                    'connectivity issues with some servers\n'))
 
     # TODO print CA cert info
 
     # hg version
     hgver = util.version()
     fm.write('hgver', _("checking Mercurial version (%s)\n"),
              hgver.split('+')[0])
     fm.write('hgverextra', _("checking Mercurial custom build (%s)\n"),
              '+'.join(hgver.split('+')[1:]))
 
     # compiled modules
     fm.write('hgmodulepolicy', _("checking module policy (%s)\n"),
              policy.policy)
     fm.write('hgmodules', _("checking installed modules (%s)...\n"),
              os.path.dirname(pycompat.fsencode(__file__)))
 
     if policy.policy in ('c', 'allow'):
         err = None
         try:
             from .cext import (
                 base85,
                 bdiff,
                 mpatch,
                 osutil,
             )
             dir(bdiff), dir(mpatch), dir(base85), dir(osutil) # quiet pyflakes
         except Exception as inst:
             err = stringutil.forcebytestr(inst)
             problems += 1
         fm.condwrite(err, 'extensionserror', " %s\n", err)
 
     compengines = util.compengines._engines.values()
     fm.write('compengines', _('checking registered compression engines (%s)\n'),
              fm.formatlist(sorted(e.name() for e in compengines),
                            name='compengine', fmt='%s', sep=', '))
     fm.write('compenginesavail', _('checking available compression engines '
                                    '(%s)\n'),
              fm.formatlist(sorted(e.name() for e in compengines
                                   if e.available()),
                            name='compengine', fmt='%s', sep=', '))
     wirecompengines = util.compengines.supportedwireengines(util.SERVERROLE)
     fm.write('compenginesserver', _('checking available compression engines '
                                     'for wire protocol (%s)\n'),
              fm.formatlist([e.name() for e in wirecompengines
                             if e.wireprotosupport()],
                            name='compengine', fmt='%s', sep=', '))
     re2 = 'missing'
     if util._re2:
         re2 = 'available'
     fm.plain(_('checking "re2" regexp engine (%s)\n') % re2)
     fm.data(re2=bool(util._re2))
 
     # templates
     p = templater.templatepaths()
     fm.write('templatedirs', 'checking templates (%s)...\n', ' '.join(p))
     fm.condwrite(not p, '', _(" no template directories found\n"))
     if p:
         m = templater.templatepath("map-cmdline.default")
         if m:
             # template found, check if it is working
             err = None
             try:
                 templater.templater.frommapfile(m)
             except Exception as inst:
                 err = stringutil.forcebytestr(inst)
                 p = None
             fm.condwrite(err, 'defaulttemplateerror', " %s\n", err)
         else:
             p = None
         fm.condwrite(p, 'defaulttemplate',
                      _("checking default template (%s)\n"), m)
         fm.condwrite(not m, 'defaulttemplatenotfound',
                      _(" template '%s' not found\n"), "default")
     if not p:
         problems += 1
     fm.condwrite(not p, '',
                  _(" (templates seem to have been installed incorrectly)\n"))
 
     # editor
     editor = ui.geteditor()
     editor = util.expandpath(editor)
     editorbin = procutil.shellsplit(editor)[0]
     fm.write('editor', _("checking commit editor... (%s)\n"), editorbin)
     cmdpath = procutil.findexe(editorbin)
     fm.condwrite(not cmdpath and editor == 'vi', 'vinotfound',
                  _(" No commit editor set and can't find %s in PATH\n"
                    " (specify a commit editor in your configuration"
                    " file)\n"), not cmdpath and editor == 'vi' and editorbin)
     fm.condwrite(not cmdpath and editor != 'vi', 'editornotfound',
                  _(" Can't find editor '%s' in PATH\n"
                    " (specify a commit editor in your configuration"
                    " file)\n"), not cmdpath and editorbin)
     if not cmdpath and editor != 'vi':
         problems += 1
 
     # check username
     username = None
     err = None
     try:
         username = ui.username()
     except error.Abort as e:
         err = stringutil.forcebytestr(e)
         problems += 1
 
     fm.condwrite(username, 'username',  _("checking username (%s)\n"), username)
     fm.condwrite(err, 'usernameerror', _("checking username...\n %s\n"
         " (specify a username in your configuration file)\n"), err)
 
     fm.condwrite(not problems, '',
                  _("no problems detected\n"))
     if not problems:
         fm.data(problems=problems)
     fm.condwrite(problems, 'problems',
                  _("%d problems detected,"
                    " please check your install!\n"), problems)
     fm.end()
 
     return problems
 
 @command('debugknown', [], _('REPO ID...'), norepo=True)
 def debugknown(ui, repopath, *ids, **opts):
     """test whether node ids are known to a repo
 
     Every ID must be a full-length hex node id string. Returns a list of 0s
     and 1s indicating unknown/known.
     """
     opts = pycompat.byteskwargs(opts)
     repo = hg.peer(ui, opts, repopath)
     if not repo.capable('known'):
         raise error.Abort("known() not supported by target repository")
     flags = repo.known([bin(s) for s in ids])
     ui.write("%s\n" % ("".join([f and "1" or "0" for f in flags])))
 
 @command('debuglabelcomplete', [], _('LABEL...'))
 def debuglabelcomplete(ui, repo, *args):
     '''backwards compatibility with old bash completion scripts (DEPRECATED)'''
     debugnamecomplete(ui, repo, *args)
 
 @command('debuglocks',
          [('L', 'force-lock', None, _('free the store lock (DANGEROUS)')),
           ('W', 'force-wlock', None,
            _('free the working state lock (DANGEROUS)')),
           ('s', 'set-lock', None, _('set the store lock until stopped')),
           ('S', 'set-wlock', None,
            _('set the working state lock until stopped'))],
          _('[OPTION]...'))
 def debuglocks(ui, repo, **opts):
     """show or modify state of locks
 
     By default, this command will show which locks are held. This
     includes the user and process holding the lock, the amount of time
     the lock has been held, and the machine name where the process is
     running if it's not local.
 
     Locks protect the integrity of Mercurial's data, so should be
     treated with care. System crashes or other interruptions may cause
     locks to not be properly released, though Mercurial will usually
     detect and remove such stale locks automatically.
 
     However, detecting stale locks may not always be possible (for
     instance, on a shared filesystem). Removing locks may also be
     blocked by filesystem permissions.
 
     Setting a lock will prevent other commands from changing the data.
     The command will wait until an interruption (SIGINT, SIGTERM, ...) occurs.
     The set locks are removed when the command exits.
 
     Returns 0 if no locks are held.
 
     """
 
     if opts.get(r'force_lock'):
         repo.svfs.unlink('lock')
     if opts.get(r'force_wlock'):
         repo.vfs.unlink('wlock')
     if opts.get(r'force_lock') or opts.get(r'force_wlock'):
         return 0
 
     locks = []
     try:
         if opts.get(r'set_wlock'):
             try:
                 locks.append(repo.wlock(False))
             except error.LockHeld:
                 raise error.Abort(_('wlock is already held'))
         if opts.get(r'set_lock'):
             try:
                 locks.append(repo.lock(False))
             except error.LockHeld:
                 raise error.Abort(_('lock is already held'))
         if len(locks):
             ui.promptchoice(_("ready to release the lock (y)? $$ &Yes"))
             return 0
     finally:
         release(*locks)
 
     now = time.time()
     held = 0
 
     def report(vfs, name, method):
         # this causes stale locks to get reaped for more accurate reporting
         try:
             l = method(False)
         except error.LockHeld:
             l = None
 
         if l:
             l.release()
         else:
             try:
                 st = vfs.lstat(name)
                 age = now - st[stat.ST_MTIME]
                 user = util.username(st.st_uid)
                 locker = vfs.readlock(name)
                 if ":" in locker:
                     host, pid = locker.split(':')
                     if host == socket.gethostname():
                         locker = 'user %s, process %s' % (user, pid)
                     else:
                         locker = 'user %s, process %s, host %s' \
                                  % (user, pid, host)
                 ui.write(("%-6s %s (%ds)\n") % (name + ":", locker, age))
                 return 1
             except OSError as e:
                 if e.errno != errno.ENOENT:
                     raise
 
         ui.write(("%-6s free\n") % (name + ":"))
         return 0
 
     held += report(repo.svfs, "lock", repo.lock)
     held += report(repo.vfs, "wlock", repo.wlock)
 
     return held
 
 @command('debugmergestate', [], '')
 def debugmergestate(ui, repo, *args):
     """print merge state
 
     Use --verbose to print out information about whether v1 or v2 merge state
     was chosen."""
     def _hashornull(h):
         if h == nullhex:
             return 'null'
         else:
             return h
 
     def printrecords(version):
         ui.write(('* version %d records\n') % version)
         if version == 1:
             records = v1records
         else:
             records = v2records
 
         for rtype, record in records:
             # pretty print some record types
             if rtype == 'L':
                 ui.write(('local: %s\n') % record)
             elif rtype == 'O':
                 ui.write(('other: %s\n') % record)
             elif rtype == 'm':
                 driver, mdstate = record.split('\0', 1)
                 ui.write(('merge driver: %s (state "%s")\n')
                          % (driver, mdstate))
             elif rtype in 'FDC':
                 r = record.split('\0')
                 f, state, hash, lfile, afile, anode, ofile = r[0:7]
                 if version == 1:
                     onode = 'not stored in v1 format'
                     flags = r[7]
                 else:
                     onode, flags = r[7:9]
                 ui.write(('file: %s (record type "%s", state "%s", hash %s)\n')
                          % (f, rtype, state, _hashornull(hash)))
                 ui.write(('  local path: %s (flags "%s")\n') % (lfile, flags))
                 ui.write(('  ancestor path: %s (node %s)\n')
                          % (afile, _hashornull(anode)))
                 ui.write(('  other path: %s (node %s)\n')
                          % (ofile, _hashornull(onode)))
             elif rtype == 'f':
                 filename, rawextras = record.split('\0', 1)
                 extras = rawextras.split('\0')
                 i = 0
                 extrastrings = []
                 while i < len(extras):
                     extrastrings.append('%s = %s' % (extras[i], extras[i + 1]))
                     i += 2
 
                 ui.write(('file extras: %s (%s)\n')
                          % (filename, ', '.join(extrastrings)))
             elif rtype == 'l':
                 labels = record.split('\0', 2)
                 labels = [l for l in labels if len(l) > 0]
                 ui.write(('labels:\n'))
                 ui.write(('  local: %s\n' % labels[0]))
                 ui.write(('  other: %s\n' % labels[1]))
                 if len(labels) > 2:
                     ui.write(('  base:  %s\n' % labels[2]))
             else:
                 ui.write(('unrecognized entry: %s\t%s\n')
                          % (rtype, record.replace('\0', '\t')))
 
     # Avoid mergestate.read() since it may raise an exception for unsupported
     # merge state records. We shouldn't be doing this, but this is OK since this
     # command is pretty low-level.
     ms = mergemod.mergestate(repo)
 
     # sort so that reasonable information is on top
     v1records = ms._readrecordsv1()
     v2records = ms._readrecordsv2()
     order = 'LOml'
     def key(r):
         idx = order.find(r[0])
         if idx == -1:
             return (1, r[1])
         else:
             return (0, idx)
     v1records.sort(key=key)
     v2records.sort(key=key)
 
     if not v1records and not v2records:
         ui.write(('no merge state found\n'))
     elif not v2records:
         ui.note(('no version 2 merge state\n'))
         printrecords(1)
     elif ms._v1v2match(v1records, v2records):
         ui.note(('v1 and v2 states match: using v2\n'))
         printrecords(2)
     else:
         ui.note(('v1 and v2 states mismatch: using v1\n'))
         printrecords(1)
         if ui.verbose:
             printrecords(2)
 
 @command('debugnamecomplete', [], _('NAME...'))
 def debugnamecomplete(ui, repo, *args):
     '''complete "names" - tags, open branch names, bookmark names'''
 
     names = set()
     # since we previously only listed open branches, we will handle that
     # specially (after this for loop)
     for name, ns in repo.names.iteritems():
         if name != 'branches':
             names.update(ns.listnames(repo))
     names.update(tag for (tag, heads, tip, closed)
                  in repo.branchmap().iterbranches() if not closed)
     completions = set()
     if not args:
         args = ['']
     for a in args:
         completions.update(n for n in names if n.startswith(a))
     ui.write('\n'.join(sorted(completions)))
     ui.write('\n')
 
 @command('debugobsolete',
         [('', 'flags', 0, _('markers flag')),
          ('', 'record-parents', False,
           _('record parent information for the precursor')),
          ('r', 'rev', [], _('display markers relevant to REV')),
          ('', 'exclusive', False, _('restrict display to markers only '
                                     'relevant to REV')),
          ('', 'index', False, _('display index of the marker')),
          ('', 'delete', [], _('delete markers specified by indices')),
         ] + cmdutil.commitopts2 + cmdutil.formatteropts,
          _('[OBSOLETED [REPLACEMENT ...]]'))
 def debugobsolete(ui, repo, precursor=None, *successors, **opts):
     """create arbitrary obsolete marker
 
     With no arguments, displays the list of obsolescence markers."""
 
     opts = pycompat.byteskwargs(opts)
 
     def parsenodeid(s):
         try:
             # We do not use revsingle/revrange functions here to accept
             # arbitrary node identifiers, possibly not present in the
             # local repository.
             n = bin(s)
             if len(n) != len(nullid):
                 raise TypeError()
             return n
         except TypeError:
             raise error.Abort('changeset references must be full hexadecimal '
                              'node identifiers')
 
     if opts.get('delete'):
         indices = []
         for v in opts.get('delete'):
             try:
                 indices.append(int(v))
             except ValueError:
                 raise error.Abort(_('invalid index value: %r') % v,
                                   hint=_('use integers for indices'))
 
         if repo.currenttransaction():
             raise error.Abort(_('cannot delete obsmarkers in the middle '
                                 'of transaction.'))
 
         with repo.lock():
             n = repair.deleteobsmarkers(repo.obsstore, indices)
             ui.write(_('deleted %i obsolescence markers\n') % n)
 
         return
 
     if precursor is not None:
         if opts['rev']:
             raise error.Abort('cannot select revision when creating marker')
         metadata = {}
         metadata['user'] = opts['user'] or ui.username()
         succs = tuple(parsenodeid(succ) for succ in successors)
         l = repo.lock()
         try:
             tr = repo.transaction('debugobsolete')
             try:
                 date = opts.get('date')
                 if date:
                     date = dateutil.parsedate(date)
                 else:
                     date = None
                 prec = parsenodeid(precursor)
                 parents = None
                 if opts['record_parents']:
                     if prec not in repo.unfiltered():
                         raise error.Abort('cannot used --record-parents on '
                                          'unknown changesets')
                     parents = repo.unfiltered()[prec].parents()
                     parents = tuple(p.node() for p in parents)
                 repo.obsstore.create(tr, prec, succs, opts['flags'],
                                      parents=parents, date=date,
                                      metadata=metadata, ui=ui)
                 tr.close()
             except ValueError as exc:
                 raise error.Abort(_('bad obsmarker input: %s') %
                                   pycompat.bytestr(exc))
             finally:
                 tr.release()
         finally:
             l.release()
     else:
         if opts['rev']:
             revs = scmutil.revrange(repo, opts['rev'])
             nodes = [repo[r].node() for r in revs]
             markers = list(obsutil.getmarkers(repo, nodes=nodes,
                                                exclusive=opts['exclusive']))
             markers.sort(key=lambda x: x._data)
         else:
             markers = obsutil.getmarkers(repo)
 
         markerstoiter = markers
         isrelevant = lambda m: True
         if opts.get('rev') and opts.get('index'):
             markerstoiter = obsutil.getmarkers(repo)
             markerset = set(markers)
             isrelevant = lambda m: m in markerset
 
         fm = ui.formatter('debugobsolete', opts)
         for i, m in enumerate(markerstoiter):
             if not isrelevant(m):
                 # marker can be irrelevant when we're iterating over a set
                 # of markers (markerstoiter) which is bigger than the set
                 # of markers we want to display (markers)
                 # this can happen if both --index and --rev options are
                 # provided and thus we need to iterate over all of the markers
                 # to get the correct indices, but only display the ones that
                 # are relevant to --rev value
                 continue
             fm.startitem()
             ind = i if opts.get('index') else None
             cmdutil.showmarker(fm, m, index=ind)
         fm.end()
 
 @command('debugpathcomplete',
          [('f', 'full', None, _('complete an entire path')),
           ('n', 'normal', None, _('show only normal files')),
           ('a', 'added', None, _('show only added files')),
           ('r', 'removed', None, _('show only removed files'))],
          _('FILESPEC...'))
 def debugpathcomplete(ui, repo, *specs, **opts):
     '''complete part or all of a tracked path
 
     This command supports shells that offer path name completion. It
     currently completes only files already known to the dirstate.
 
     Completion extends only to the next path segment unless
     --full is specified, in which case entire paths are used.'''
 
     def complete(path, acceptable):
         dirstate = repo.dirstate
         spec = os.path.normpath(os.path.join(pycompat.getcwd(), path))
         rootdir = repo.root + pycompat.ossep
         if spec != repo.root and not spec.startswith(rootdir):
             return [], []
         if os.path.isdir(spec):
             spec += '/'
         spec = spec[len(rootdir):]
         fixpaths = pycompat.ossep != '/'
         if fixpaths:
             spec = spec.replace(pycompat.ossep, '/')
         speclen = len(spec)
         fullpaths = opts[r'full']
         files, dirs = set(), set()
         adddir, addfile = dirs.add, files.add
         for f, st in dirstate.iteritems():
             if f.startswith(spec) and st[0] in acceptable:
                 if fixpaths:
                     f = f.replace('/', pycompat.ossep)
                 if fullpaths:
                     addfile(f)
                     continue
                 s = f.find(pycompat.ossep, speclen)
                 if s >= 0:
                     adddir(f[:s])
                 else:
                     addfile(f)
         return files, dirs
 
     acceptable = ''
     if opts[r'normal']:
         acceptable += 'nm'
     if opts[r'added']:
         acceptable += 'a'
     if opts[r'removed']:
         acceptable += 'r'
     cwd = repo.getcwd()
     if not specs:
         specs = ['.']
 
     files, dirs = set(), set()
     for spec in specs:
         f, d = complete(spec, acceptable or 'nmar')
         files.update(f)
         dirs.update(d)
     files.update(dirs)
     ui.write('\n'.join(repo.pathto(p, cwd) for p in sorted(files)))
     ui.write('\n')
 
 @command('debugpeer', [], _('PATH'), norepo=True)
 def debugpeer(ui, path):
     """establish a connection to a peer repository"""
     # Always enable peer request logging. Requires --debug to display
     # though.
     overrides = {
         ('devel', 'debug.peer-request'): True,
     }
 
     with ui.configoverride(overrides):
         peer = hg.peer(ui, {}, path)
 
         local = peer.local() is not None
         canpush = peer.canpush()
 
         ui.write(_('url: %s\n') % peer.url())
         ui.write(_('local: %s\n') % (_('yes') if local else _('no')))
         ui.write(_('pushable: %s\n') % (_('yes') if canpush else _('no')))
 
 @command('debugpickmergetool',
         [('r', 'rev', '', _('check for files in this revision'), _('REV')),
          ('', 'changedelete', None, _('emulate merging change and delete')),
         ] + cmdutil.walkopts + cmdutil.mergetoolopts,
         _('[PATTERN]...'),
         inferrepo=True)
 def debugpickmergetool(ui, repo, *pats, **opts):
     """examine which merge tool is chosen for specified file
 
     As described in :hg:`help merge-tools`, Mercurial examines
     configurations below in this order to decide which merge tool is
     chosen for specified file.
 
     1. ``--tool`` option
     2. ``HGMERGE`` environment variable
     3. configurations in ``merge-patterns`` section
     4. configuration of ``ui.merge``
     5. configurations in ``merge-tools`` section
     6. ``hgmerge`` tool (for historical reason only)
     7. default tool for fallback (``:merge`` or ``:prompt``)
 
     This command writes out examination result in the style below::
 
         FILE = MERGETOOL
 
     By default, all files known in the first parent context of the
     working directory are examined. Use file patterns and/or -I/-X
     options to limit target files. -r/--rev is also useful to examine
     files in another context without actual updating to it.
 
     With --debug, this command shows warning messages while matching
     against ``merge-patterns`` and so on, too. It is recommended to
     use this option with explicit file patterns and/or -I/-X options,
     because this option increases amount of output per file according
     to configurations in hgrc.
 
     With -v/--verbose, this command shows configurations below at
     first (only if specified).
 
     - ``--tool`` option
     - ``HGMERGE`` environment variable
     - configuration of ``ui.merge``
 
     If merge tool is chosen before matching against
     ``merge-patterns``, this command can't show any helpful
     information, even with --debug. In such case, information above is
     useful to know why a merge tool is chosen.
     """
     opts = pycompat.byteskwargs(opts)
     overrides = {}
     if opts['tool']:
         overrides[('ui', 'forcemerge')] = opts['tool']
         ui.note(('with --tool %r\n') % (pycompat.bytestr(opts['tool'])))
 
     with ui.configoverride(overrides, 'debugmergepatterns'):
         hgmerge = encoding.environ.get("HGMERGE")
         if hgmerge is not None:
             ui.note(('with HGMERGE=%r\n') % (pycompat.bytestr(hgmerge)))
         uimerge = ui.config("ui", "merge")
         if uimerge:
             ui.note(('with ui.merge=%r\n') % (pycompat.bytestr(uimerge)))
 
         ctx = scmutil.revsingle(repo, opts.get('rev'))
         m = scmutil.match(ctx, pats, opts)
         changedelete = opts['changedelete']
         for path in ctx.walk(m):
             fctx = ctx[path]
             try:
                 if not ui.debugflag:
                     ui.pushbuffer(error=True)
                 tool, toolpath = filemerge._picktool(repo, ui, path,
                                                      fctx.isbinary(),
                                                      'l' in fctx.flags(),
                                                      changedelete)
             finally:
                 if not ui.debugflag:
                     ui.popbuffer()
             ui.write(('%s = %s\n') % (path, tool))
 
 @command('debugpushkey', [], _('REPO NAMESPACE [KEY OLD NEW]'), norepo=True)
 def debugpushkey(ui, repopath, namespace, *keyinfo, **opts):
     '''access the pushkey key/value protocol
 
     With two args, list the keys in the given namespace.
 
     With five args, set a key to new if it currently is set to old.
     Reports success or failure.
     '''
 
     target = hg.peer(ui, {}, repopath)
     if keyinfo:
         key, old, new = keyinfo
         r = target.pushkey(namespace, key, old, new)
         ui.status(pycompat.bytestr(r) + '\n')
         return not r
     else:
         for k, v in sorted(target.listkeys(namespace).iteritems()):
             ui.write("%s\t%s\n" % (stringutil.escapestr(k),
                                    stringutil.escapestr(v)))
 
 @command('debugpvec', [], _('A B'))
 def debugpvec(ui, repo, a, b=None):
     ca = scmutil.revsingle(repo, a)
     cb = scmutil.revsingle(repo, b)
     pa = pvec.ctxpvec(ca)
     pb = pvec.ctxpvec(cb)
     if pa == pb:
         rel = "="
     elif pa > pb:
         rel = ">"
     elif pa < pb:
         rel = "<"
     elif pa | pb:
         rel = "|"
     ui.write(_("a: %s\n") % pa)
     ui.write(_("b: %s\n") % pb)
     ui.write(_("depth(a): %d depth(b): %d\n") % (pa._depth, pb._depth))
     ui.write(_("delta: %d hdist: %d distance: %d relation: %s\n") %
              (abs(pa._depth - pb._depth), pvec._hamming(pa._vec, pb._vec),
               pa.distance(pb), rel))
 
 @command('debugrebuilddirstate|debugrebuildstate',
     [('r', 'rev', '', _('revision to rebuild to'), _('REV')),
      ('', 'minimal', None, _('only rebuild files that are inconsistent with '
                              'the working copy parent')),
     ],
     _('[-r REV]'))
 def debugrebuilddirstate(ui, repo, rev, **opts):
     """rebuild the dirstate as it would look like for the given revision
 
     If no revision is specified the first current parent will be used.
 
     The dirstate will be set to the files of the given revision.
     The actual working directory content or existing dirstate
     information such as adds or removes is not considered.
 
     ``minimal`` will only rebuild the dirstate status for files that claim to be
     tracked but are not in the parent manifest, or that exist in the parent
     manifest but are not in the dirstate. It will not change adds, removes, or
     modified files that are in the working copy parent.
 
     One use of this command is to make the next :hg:`status` invocation
     check the actual file content.
     """
     ctx = scmutil.revsingle(repo, rev)
     with repo.wlock():
         dirstate = repo.dirstate
         changedfiles = None
         # See command doc for what minimal does.
         if opts.get(r'minimal'):
             manifestfiles = set(ctx.manifest().keys())
             dirstatefiles = set(dirstate)
             manifestonly = manifestfiles - dirstatefiles
             dsonly = dirstatefiles - manifestfiles
             dsnotadded = set(f for f in dsonly if dirstate[f] != 'a')
             changedfiles = manifestonly | dsnotadded
 
         dirstate.rebuild(ctx.node(), ctx.manifest(), changedfiles)
 
 @command('debugrebuildfncache', [], '')
 def debugrebuildfncache(ui, repo):
     """rebuild the fncache file"""
     repair.rebuildfncache(ui, repo)
 
 @command('debugrename',
     [('r', 'rev', '', _('revision to debug'), _('REV'))],
     _('[-r REV] FILE'))
 def debugrename(ui, repo, file1, *pats, **opts):
     """dump rename information"""
 
     opts = pycompat.byteskwargs(opts)
     ctx = scmutil.revsingle(repo, opts.get('rev'))
     m = scmutil.match(ctx, (file1,) + pats, opts)
     for abs in ctx.walk(m):
         fctx = ctx[abs]
         o = fctx.filelog().renamed(fctx.filenode())
         rel = m.rel(abs)
         if o:
             ui.write(_("%s renamed from %s:%s\n") % (rel, o[0], hex(o[1])))
         else:
             ui.write(_("%s not renamed\n") % rel)
 
 @command('debugrevlog', cmdutil.debugrevlogopts +
     [('d', 'dump', False, _('dump index data'))],
     _('-c|-m|FILE'),
     optionalrepo=True)
 def debugrevlog(ui, repo, file_=None, **opts):
     """show data and statistics about a revlog"""
     opts = pycompat.byteskwargs(opts)
     r = cmdutil.openrevlog(repo, 'debugrevlog', file_, opts)
 
     if opts.get("dump"):
         numrevs = len(r)
         ui.write(("# rev p1rev p2rev start   end deltastart base   p1   p2"
                  " rawsize totalsize compression heads chainlen\n"))
         ts = 0
         heads = set()
 
         for rev in xrange(numrevs):
             dbase = r.deltaparent(rev)
             if dbase == -1:
                 dbase = rev
             cbase = r.chainbase(rev)
             clen = r.chainlen(rev)
             p1, p2 = r.parentrevs(rev)
             rs = r.rawsize(rev)
             ts = ts + rs
             heads -= set(r.parentrevs(rev))
             heads.add(rev)
             try:
                 compression = ts / r.end(rev)
             except ZeroDivisionError:
                 compression = 0
             ui.write("%5d %5d %5d %5d %5d %10d %4d %4d %4d %7d %9d "
                      "%11d %5d %8d\n" %
                      (rev, p1, p2, r.start(rev), r.end(rev),
                       r.start(dbase), r.start(cbase),
                       r.start(p1), r.start(p2),
                       rs, ts, compression, len(heads), clen))
         return 0
 
     v = r.version
     format = v & 0xFFFF
     flags = []
     gdelta = False
     if v & revlog.FLAG_INLINE_DATA:
         flags.append('inline')
     if v & revlog.FLAG_GENERALDELTA:
         gdelta = True
         flags.append('generaldelta')
     if not flags:
         flags = ['(none)']
 
     nummerges = 0
     numfull = 0
     numprev = 0
     nump1 = 0
     nump2 = 0
     numother = 0
     nump1prev = 0
     nump2prev = 0
     chainlengths = []
     chainbases = []
     chainspans = []
 
     datasize = [None, 0, 0]
     fullsize = [None, 0, 0]
     deltasize = [None, 0, 0]
     chunktypecounts = {}
     chunktypesizes = {}
 
     def addsize(size, l):
         if l[0] is None or size < l[0]:
             l[0] = size
         if size > l[1]:
             l[1] = size
         l[2] += size
 
     numrevs = len(r)
     for rev in xrange(numrevs):
         p1, p2 = r.parentrevs(rev)
         delta = r.deltaparent(rev)
         if format > 0:
             addsize(r.rawsize(rev), datasize)
         if p2 != nullrev:
             nummerges += 1
         size = r.length(rev)
         if delta == nullrev:
             chainlengths.append(0)
             chainbases.append(r.start(rev))
             chainspans.append(size)
             numfull += 1
             addsize(size, fullsize)
         else:
             chainlengths.append(chainlengths[delta] + 1)
             baseaddr = chainbases[delta]
             revaddr = r.start(rev)
             chainbases.append(baseaddr)
             chainspans.append((revaddr - baseaddr) + size)
             addsize(size, deltasize)
             if delta == rev - 1:
                 numprev += 1
                 if delta == p1:
                     nump1prev += 1
                 elif delta == p2:
                     nump2prev += 1
             elif delta == p1:
                 nump1 += 1
             elif delta == p2:
                 nump2 += 1
             elif delta != nullrev:
                 numother += 1
 
         # Obtain data on the raw chunks in the revlog.
         segment = r._getsegmentforrevs(rev, rev)[1]
         if segment:
             chunktype = bytes(segment[0:1])
         else:
             chunktype = 'empty'
 
         if chunktype not in chunktypecounts:
             chunktypecounts[chunktype] = 0
             chunktypesizes[chunktype] = 0
 
         chunktypecounts[chunktype] += 1
         chunktypesizes[chunktype] += size
 
     # Adjust size min value for empty cases
     for size in (datasize, fullsize, deltasize):
         if size[0] is None:
             size[0] = 0
 
     numdeltas = numrevs - numfull
     numoprev = numprev - nump1prev - nump2prev
     totalrawsize = datasize[2]
     datasize[2] /= numrevs
     fulltotal = fullsize[2]
     fullsize[2] /= numfull
     deltatotal = deltasize[2]
     if numrevs - numfull > 0:
         deltasize[2] /= numrevs - numfull
     totalsize = fulltotal + deltatotal
     avgchainlen = sum(chainlengths) / numrevs
     maxchainlen = max(chainlengths)
     maxchainspan = max(chainspans)
     compratio = 1
     if totalsize:
         compratio = totalrawsize / totalsize
 
     basedfmtstr = '%%%dd\n'
     basepcfmtstr = '%%%dd %s(%%5.2f%%%%)\n'
 
     def dfmtstr(max):
         return basedfmtstr % len(str(max))
     def pcfmtstr(max, padding=0):
         return basepcfmtstr % (len(str(max)), ' ' * padding)
 
     def pcfmt(value, total):
         if total:
             return (value, 100 * float(value) / total)
         else:
             return value, 100.0
 
     ui.write(('format : %d\n') % format)
     ui.write(('flags  : %s\n') % ', '.join(flags))
 
     ui.write('\n')
     fmt = pcfmtstr(totalsize)
     fmt2 = dfmtstr(totalsize)
     ui.write(('revisions     : ') + fmt2 % numrevs)
     ui.write(('    merges    : ') + fmt % pcfmt(nummerges, numrevs))
     ui.write(('    normal    : ') + fmt % pcfmt(numrevs - nummerges, numrevs))
     ui.write(('revisions     : ') + fmt2 % numrevs)
     ui.write(('    full      : ') + fmt % pcfmt(numfull, numrevs))
     ui.write(('    deltas    : ') + fmt % pcfmt(numdeltas, numrevs))
     ui.write(('revision size : ') + fmt2 % totalsize)
     ui.write(('    full      : ') + fmt % pcfmt(fulltotal, totalsize))
     ui.write(('    deltas    : ') + fmt % pcfmt(deltatotal, totalsize))
 
     def fmtchunktype(chunktype):
         if chunktype == 'empty':
             return '    %s     : ' % chunktype
         elif chunktype in pycompat.bytestr(string.ascii_letters):
             return '    0x%s (%s)  : ' % (hex(chunktype), chunktype)
         else:
             return '    0x%s      : ' % hex(chunktype)
 
     ui.write('\n')
     ui.write(('chunks        : ') + fmt2 % numrevs)
     for chunktype in sorted(chunktypecounts):
         ui.write(fmtchunktype(chunktype))
         ui.write(fmt % pcfmt(chunktypecounts[chunktype], numrevs))
     ui.write(('chunks size   : ') + fmt2 % totalsize)
     for chunktype in sorted(chunktypecounts):
         ui.write(fmtchunktype(chunktype))
         ui.write(fmt % pcfmt(chunktypesizes[chunktype], totalsize))
 
     ui.write('\n')
     fmt = dfmtstr(max(avgchainlen, maxchainlen, maxchainspan, compratio))
     ui.write(('avg chain length  : ') + fmt % avgchainlen)
     ui.write(('max chain length  : ') + fmt % maxchainlen)
     ui.write(('max chain reach   : ') + fmt % maxchainspan)
     ui.write(('compression ratio : ') + fmt % compratio)
 
     if format > 0:
         ui.write('\n')
         ui.write(('uncompressed data size (min/max/avg) : %d / %d / %d\n')
                  % tuple(datasize))
     ui.write(('full revision size (min/max/avg)     : %d / %d / %d\n')
              % tuple(fullsize))
     ui.write(('delta size (min/max/avg)             : %d / %d / %d\n')
              % tuple(deltasize))
 
     if numdeltas > 0:
         ui.write('\n')
         fmt = pcfmtstr(numdeltas)
         fmt2 = pcfmtstr(numdeltas, 4)
         ui.write(('deltas against prev  : ') + fmt % pcfmt(numprev, numdeltas))
         if numprev > 0:
             ui.write(('    where prev = p1  : ') + fmt2 % pcfmt(nump1prev,
                                                               numprev))
             ui.write(('    where prev = p2  : ') + fmt2 % pcfmt(nump2prev,
                                                               numprev))
             ui.write(('    other            : ') + fmt2 % pcfmt(numoprev,
                                                               numprev))
         if gdelta:
             ui.write(('deltas against p1    : ')
                      + fmt % pcfmt(nump1, numdeltas))
             ui.write(('deltas against p2    : ')
                      + fmt % pcfmt(nump2, numdeltas))
             ui.write(('deltas against other : ') + fmt % pcfmt(numother,
                                                              numdeltas))
 
 @command('debugrevspec',
     [('', 'optimize', None,
       _('print parsed tree after optimizing (DEPRECATED)')),
      ('', 'show-revs', True, _('print list of result revisions (default)')),
      ('s', 'show-set', None, _('print internal representation of result set')),
      ('p', 'show-stage', [],
       _('print parsed tree at the given stage'), _('NAME')),
      ('', 'no-optimized', False, _('evaluate tree without optimization')),
      ('', 'verify-optimized', False, _('verify optimized result')),
      ],
     ('REVSPEC'))
 def debugrevspec(ui, repo, expr, **opts):
     """parse and apply a revision specification
 
     Use -p/--show-stage option to print the parsed tree at the given stages.
     Use -p all to print tree at every stage.
 
     Use --no-show-revs option with -s or -p to print only the set
     representation or the parsed tree respectively.
 
     Use --verify-optimized to compare the optimized result with the unoptimized
     one. Returns 1 if the optimized result differs.
     """
     opts = pycompat.byteskwargs(opts)
     aliases = ui.configitems('revsetalias')
     stages = [
         ('parsed', lambda tree: tree),
         ('expanded', lambda tree: revsetlang.expandaliases(tree, aliases,
                                                            ui.warn)),
         ('concatenated', revsetlang.foldconcat),
         ('analyzed', revsetlang.analyze),
         ('optimized', revsetlang.optimize),
     ]
     if opts['no_optimized']:
         stages = stages[:-1]
     if opts['verify_optimized'] and opts['no_optimized']:
         raise error.Abort(_('cannot use --verify-optimized with '
                             '--no-optimized'))
     stagenames = set(n for n, f in stages)
 
     showalways = set()
     showchanged = set()
     if ui.verbose and not opts['show_stage']:
         # show parsed tree by --verbose (deprecated)
         showalways.add('parsed')
         showchanged.update(['expanded', 'concatenated'])
         if opts['optimize']:
             showalways.add('optimized')
     if opts['show_stage'] and opts['optimize']:
         raise error.Abort(_('cannot use --optimize with --show-stage'))
     if opts['show_stage'] == ['all']:
         showalways.update(stagenames)
     else:
         for n in opts['show_stage']:
             if n not in stagenames:
                 raise error.Abort(_('invalid stage name: %s') % n)
         showalways.update(opts['show_stage'])
 
     treebystage = {}
     printedtree = None
     tree = revsetlang.parse(expr, lookup=repo.__contains__)
     for n, f in stages:
         treebystage[n] = tree = f(tree)
         if n in showalways or (n in showchanged and tree != printedtree):
             if opts['show_stage'] or n != 'parsed':
                 ui.write(("* %s:\n") % n)
             ui.write(revsetlang.prettyformat(tree), "\n")
             printedtree = tree
 
     if opts['verify_optimized']:
         arevs = revset.makematcher(treebystage['analyzed'])(repo)
         brevs = revset.makematcher(treebystage['optimized'])(repo)
         if opts['show_set'] or (opts['show_set'] is None and ui.verbose):
             ui.write(("* analyzed set:\n"), smartset.prettyformat(arevs), "\n")
             ui.write(("* optimized set:\n"), smartset.prettyformat(brevs), "\n")
         arevs = list(arevs)
         brevs = list(brevs)
         if arevs == brevs:
             return 0
         ui.write(('--- analyzed\n'), label='diff.file_a')
         ui.write(('+++ optimized\n'), label='diff.file_b')
         sm = difflib.SequenceMatcher(None, arevs, brevs)
         for tag, alo, ahi, blo, bhi in sm.get_opcodes():
             if tag in ('delete', 'replace'):
                 for c in arevs[alo:ahi]:
                     ui.write('-%s\n' % c, label='diff.deleted')
             if tag in ('insert', 'replace'):
                 for c in brevs[blo:bhi]:
                     ui.write('+%s\n' % c, label='diff.inserted')
             if tag == 'equal':
                 for c in arevs[alo:ahi]:
                     ui.write(' %s\n' % c)
         return 1
 
     func = revset.makematcher(tree)
     revs = func(repo)
     if opts['show_set'] or (opts['show_set'] is None and ui.verbose):
         ui.write(("* set:\n"), smartset.prettyformat(revs), "\n")
     if not opts['show_revs']:
         return
     for c in revs:
         ui.write("%d\n" % c)
 
 @command('debugserve', [
     ('', 'sshstdio', False, _('run an SSH server bound to process handles')),
     ('', 'logiofd', '', _('file descriptor to log server I/O to')),
     ('', 'logiofile', '', _('file to log server I/O to')),
 ], '')
 def debugserve(ui, repo, **opts):
     """run a server with advanced settings
 
     This command is similar to :hg:`serve`. It exists partially as a
     workaround to the fact that ``hg serve --stdio`` must have specific
     arguments for security reasons.
     """
     opts = pycompat.byteskwargs(opts)
 
     if not opts['sshstdio']:
         raise error.Abort(_('only --sshstdio is currently supported'))
 
     logfh = None
 
     if opts['logiofd'] and opts['logiofile']:
         raise error.Abort(_('cannot use both --logiofd and --logiofile'))
 
     if opts['logiofd']:
         # Line buffered because output is line based.
         logfh = os.fdopen(int(opts['logiofd']), r'ab', 1)
     elif opts['logiofile']:
         logfh = open(opts['logiofile'], 'ab', 1)
 
     s = wireprotoserver.sshserver(ui, repo, logfh=logfh)
     s.serve_forever()
 
 @command('debugsetparents', [], _('REV1 [REV2]'))
 def debugsetparents(ui, repo, rev1, rev2=None):
     """manually set the parents of the current working directory
 
     This is useful for writing repository conversion tools, but should
     be used with care. For example, neither the working directory nor the
     dirstate is updated, so file status may be incorrect after running this
     command.
 
     Returns 0 on success.
     """
 
     node1 = scmutil.revsingle(repo, rev1).node()
     node2 = scmutil.revsingle(repo, rev2, 'null').node()
 
     with repo.wlock():
         repo.setparents(node1, node2)
 
 @command('debugssl', [], '[SOURCE]', optionalrepo=True)
 def debugssl(ui, repo, source=None, **opts):
     '''test a secure connection to a server
 
     This builds the certificate chain for the server on Windows, installing the
     missing intermediates and trusted root via Windows Update if necessary.  It
     does nothing on other platforms.
 
     If SOURCE is omitted, the 'default' path will be used.  If a URL is given,
     that server is used. See :hg:`help urls` for more information.
 
     If the update succeeds, retry the original operation.  Otherwise, the cause
     of the SSL error is likely another issue.
     '''
     if not pycompat.iswindows:
         raise error.Abort(_('certificate chain building is only possible on '
                             'Windows'))
 
     if not source:
         if not repo:
             raise error.Abort(_("there is no Mercurial repository here, and no "
                                 "server specified"))
         source = "default"
 
     source, branches = hg.parseurl(ui.expandpath(source))
     url = util.url(source)
     addr = None
 
     defaultport = {'https': 443, 'ssh': 22}
     if url.scheme in defaultport:
         try:
             addr = (url.host, int(url.port or defaultport[url.scheme]))
         except ValueError:
             raise error.Abort(_("malformed port number in URL"))
     else:
         raise error.Abort(_("only https and ssh connections are supported"))
 
     from . import win32
 
     s = ssl.wrap_socket(socket.socket(), ssl_version=ssl.PROTOCOL_TLS,
                         cert_reqs=ssl.CERT_NONE, ca_certs=None)
 
     try:
         s.connect(addr)
         cert = s.getpeercert(True)
 
         ui.status(_('checking the certificate chain for %s\n') % url.host)
 
         complete = win32.checkcertificatechain(cert, build=False)
 
         if not complete:
             ui.status(_('certificate chain is incomplete, updating... '))
 
             if not win32.checkcertificatechain(cert):
                 ui.status(_('failed.\n'))
             else:
                 ui.status(_('done.\n'))
         else:
             ui.status(_('full certificate chain is available\n'))
     finally:
         s.close()
 
 @command('debugsub',
     [('r', 'rev', '',
      _('revision to check'), _('REV'))],
     _('[-r REV] [REV]'))
 def debugsub(ui, repo, rev=None):
     ctx = scmutil.revsingle(repo, rev, None)
     for k, v in sorted(ctx.substate.items()):
         ui.write(('path %s\n') % k)
         ui.write((' source   %s\n') % v[0])
         ui.write((' revision %s\n') % v[1])
 
 @command('debugsuccessorssets',
     [('', 'closest', False, _('return closest successors sets only'))],
     _('[REV]'))
 def debugsuccessorssets(ui, repo, *revs, **opts):
     """show set of successors for revision
 
     A successors set of changeset A is a consistent group of revisions that
     succeed A. It contains non-obsolete changesets only unless closests
     successors set is set.
 
     In most cases a changeset A has a single successors set containing a single
     successor (changeset A replaced by A').
 
     A changeset that is made obsolete with no successors are called "pruned".
     Such changesets have no successors sets at all.
 
     A changeset that has been "split" will have a successors set containing
     more than one successor.
 
     A changeset that has been rewritten in multiple different ways is called
     "divergent". Such changesets have multiple successor sets (each of which
     may also be split, i.e. have multiple successors).
 
     Results are displayed as follows::
 
         <rev1>
             <successors-1A>
         <rev2>
             <successors-2A>
             <successors-2B1> <successors-2B2> <successors-2B3>
 
     Here rev2 has two possible (i.e. divergent) successors sets. The first
     holds one element, whereas the second holds three (i.e. the changeset has
     been split).
     """
     # passed to successorssets caching computation from one call to another
     cache = {}
     ctx2str = bytes
     node2str = short
     for rev in scmutil.revrange(repo, revs):
         ctx = repo[rev]
         ui.write('%s\n'% ctx2str(ctx))
         for succsset in obsutil.successorssets(repo, ctx.node(),
                                                 closest=opts[r'closest'],
                                                 cache=cache):
             if succsset:
                 ui.write('    ')
                 ui.write(node2str(succsset[0]))
                 for node in succsset[1:]:
                     ui.write(' ')
                     ui.write(node2str(node))
             ui.write('\n')
 
 @command('debugtemplate',
     [('r', 'rev', [], _('apply template on changesets'), _('REV')),
      ('D', 'define', [], _('define template keyword'), _('KEY=VALUE'))],
     _('[-r REV]... [-D KEY=VALUE]... TEMPLATE'),
     optionalrepo=True)
 def debugtemplate(ui, repo, tmpl, **opts):
     """parse and apply a template
 
     If -r/--rev is given, the template is processed as a log template and
     applied to the given changesets. Otherwise, it is processed as a generic
     template.
 
     Use --verbose to print the parsed tree.
     """
     revs = None
     if opts[r'rev']:
         if repo is None:
             raise error.RepoError(_('there is no Mercurial repository here '
                                     '(.hg not found)'))
         revs = scmutil.revrange(repo, opts[r'rev'])
 
     props = {}
     for d in opts[r'define']:
         try:
             k, v = (e.strip() for e in d.split('=', 1))
             if not k or k == 'ui':
                 raise ValueError
             props[k] = v
         except ValueError:
             raise error.Abort(_('malformed keyword definition: %s') % d)
 
     if ui.verbose:
         aliases = ui.configitems('templatealias')
         tree = templater.parse(tmpl)
         ui.note(templater.prettyformat(tree), '\n')
         newtree = templater.expandaliases(tree, aliases)
         if newtree != tree:
             ui.note(("* expanded:\n"), templater.prettyformat(newtree), '\n')
 
     if revs is None:
         tres = formatter.templateresources(ui, repo)
         t = formatter.maketemplater(ui, tmpl, resources=tres)
         ui.write(t.renderdefault(props))
     else:
         displayer = logcmdutil.maketemplater(ui, repo, tmpl)
         for r in revs:
             displayer.show(repo[r], **pycompat.strkwargs(props))
         displayer.close()
 
 @command('debuguigetpass', [
     ('p', 'prompt', '', _('prompt text'), _('TEXT')),
 ], _('[-p TEXT]'), norepo=True)
 def debuguigetpass(ui, prompt=''):
     """show prompt to type password"""
     r = ui.getpass(prompt)
     ui.write(('respose: %s\n') % r)
 
 @command('debuguiprompt', [
     ('p', 'prompt', '', _('prompt text'), _('TEXT')),
 ], _('[-p TEXT]'), norepo=True)
 def debuguiprompt(ui, prompt=''):
     """show plain prompt"""
     r = ui.prompt(prompt)
     ui.write(('response: %s\n') % r)
 
 @command('debugupdatecaches', [])
 def debugupdatecaches(ui, repo, *pats, **opts):
     """warm all known caches in the repository"""
     with repo.wlock(), repo.lock():
         repo.updatecaches(full=True)
 
 @command('debugupgraderepo', [
     ('o', 'optimize', [], _('extra optimization to perform'), _('NAME')),
     ('', 'run', False, _('performs an upgrade')),
 ])
 def debugupgraderepo(ui, repo, run=False, optimize=None):
     """upgrade a repository to use different features
 
     If no arguments are specified, the repository is evaluated for upgrade
     and a list of problems and potential optimizations is printed.
 
     With ``--run``, a repository upgrade is performed. Behavior of the upgrade
     can be influenced via additional arguments. More details will be provided
     by the command output when run without ``--run``.
 
     During the upgrade, the repository will be locked and no writes will be
     allowed.
 
     At the end of the upgrade, the repository may not be readable while new
     repository data is swapped in. This window will be as long as it takes to
     rename some directories inside the ``.hg`` directory. On most machines, this
     should complete almost instantaneously and the chances of a consumer being
     unable to access the repository should be low.
     """
     return upgrade.upgraderepo(ui, repo, run=run, optimize=optimize)
 
 @command('debugwalk', cmdutil.walkopts, _('[OPTION]... [FILE]...'),
          inferrepo=True)
 def debugwalk(ui, repo, *pats, **opts):
     """show how files match on given patterns"""
     opts = pycompat.byteskwargs(opts)
     m = scmutil.match(repo[None], pats, opts)
     ui.write(('matcher: %r\n' % m))
     items = list(repo[None].walk(m))
     if not items:
         return
     f = lambda fn: fn
     if ui.configbool('ui', 'slash') and pycompat.ossep != '/':
         f = lambda fn: util.normpath(fn)
     fmt = 'f  %%-%ds  %%-%ds  %%s' % (
         max([len(abs) for abs in items]),
         max([len(m.rel(abs)) for abs in items]))
     for abs in items:
         line = fmt % (abs, f(m.rel(abs)), m.exact(abs) and 'exact' or '')
         ui.write("%s\n" % line.rstrip())
 
 @command('debugwhyunstable', [], _('REV'))
 def debugwhyunstable(ui, repo, rev):
     """explain instabilities of a changeset"""
     for entry in obsutil.whyunstable(repo, repo[rev]):
         dnodes = ''
         if entry.get('divergentnodes'):
             dnodes = ' '.join('%s (%s)' % (ctx.hex(), ctx.phasestr())
                               for ctx in entry['divergentnodes']) + ' '
         ui.write('%s: %s%s %s\n' % (entry['instability'], dnodes,
                                     entry['reason'], entry['node']))
 
 @command('debugwireargs',
     [('', 'three', '', 'three'),
     ('', 'four', '', 'four'),
     ('', 'five', '', 'five'),
     ] + cmdutil.remoteopts,
     _('REPO [OPTIONS]... [ONE [TWO]]'),
     norepo=True)
 def debugwireargs(ui, repopath, *vals, **opts):
     opts = pycompat.byteskwargs(opts)
     repo = hg.peer(ui, opts, repopath)
     for opt in cmdutil.remoteopts:
         del opts[opt[1]]
     args = {}
     for k, v in opts.iteritems():
         if v:
             args[k] = v
     args = pycompat.strkwargs(args)
     # run twice to check that we don't mess up the stream for the next command
     res1 = repo.debugwireargs(*vals, **args)
     res2 = repo.debugwireargs(*vals, **args)
     ui.write("%s\n" % res1)
     if res1 != res2:
         ui.warn("%s\n" % res2)
 
 def _parsewirelangblocks(fh):
     activeaction = None
     blocklines = []
 
     for line in fh:
         line = line.rstrip()
         if not line:
             continue
 
         if line.startswith(b'#'):
             continue
 
         if not line.startswith(' '):
             # New block. Flush previous one.
             if activeaction:
                 yield activeaction, blocklines
 
             activeaction = line
             blocklines = []
             continue
 
         # Else we start with an indent.
 
         if not activeaction:
             raise error.Abort(_('indented line outside of block'))
 
         blocklines.append(line)
 
     # Flush last block.
     if activeaction:
         yield activeaction, blocklines
 
 @command('debugwireproto',
     [
         ('', 'localssh', False, _('start an SSH server for this repo')),
         ('', 'peer', '', _('construct a specific version of the peer')),
         ('', 'noreadstderr', False, _('do not read from stderr of the remote')),
     ] + cmdutil.remoteopts,
     _('[PATH]'),
     optionalrepo=True)
 def debugwireproto(ui, repo, path=None, **opts):
     """send wire protocol commands to a server
 
     This command can be used to issue wire protocol commands to remote
     peers and to debug the raw data being exchanged.
 
     ``--localssh`` will start an SSH server against the current repository
     and connect to that. By default, the connection will perform a handshake
     and establish an appropriate peer instance.
 
     ``--peer`` can be used to bypass the handshake protocol and construct a
     peer instance using the specified class type. Valid values are ``raw``,
     ``ssh1``, and ``ssh2``. ``raw`` instances only allow sending raw data
     payloads and don't support higher-level command actions.
 
     ``--noreadstderr`` can be used to disable automatic reading from stderr
     of the peer (for SSH connections only). Disabling automatic reading of
     stderr is useful for making output more deterministic.
 
     Commands are issued via a mini language which is specified via stdin.
     The language consists of individual actions to perform. An action is
     defined by a block. A block is defined as a line with no leading
     space followed by 0 or more lines with leading space. Blocks are
     effectively a high-level command with additional metadata.
 
     Lines beginning with ``#`` are ignored.
 
     The following sections denote available actions.
 
     raw
     ---
 
     Send raw data to the server.
 
     The block payload contains the raw data to send as one atomic send
     operation. The data may not actually be delivered in a single system
     call: it depends on the abilities of the transport being used.
 
     Each line in the block is de-indented and concatenated. Then, that
     value is evaluated as a Python b'' literal. This allows the use of
     backslash escaping, etc.
 
     raw+
     ----
 
     Behaves like ``raw`` except flushes output afterwards.
 
     command <X>
     -----------
 
     Send a request to run a named command, whose name follows the ``command``
     string.
 
     Arguments to the command are defined as lines in this block. The format of
     each line is ``<key> <value>``. e.g.::
 
        command listkeys
            namespace bookmarks
 
     Values are interpreted as Python b'' literals. This allows encoding
     special byte sequences via backslash escaping.
 
     The following arguments have special meaning:
 
     ``PUSHFILE``
         When defined, the *push* mechanism of the peer will be used instead
         of the static request-response mechanism and the content of the
         file specified in the value of this argument will be sent as the
         command payload.
 
         This can be used to submit a local bundle file to the remote.
 
     batchbegin
     ----------
 
     Instruct the peer to begin a batched send.
 
     All ``command`` blocks are queued for execution until the next
     ``batchsubmit`` block.
 
     batchsubmit
     -----------
 
     Submit previously queued ``command`` blocks as a batch request.
 
     This action MUST be paired with a ``batchbegin`` action.
 
     httprequest <method> <path>
     ---------------------------
 
     (HTTP peer only)
 
     Send an HTTP request to the peer.
 
     The HTTP request line follows the ``httprequest`` action. e.g. ``GET /foo``.
 
     Arguments of the form ``<key>: <value>`` are interpreted as HTTP request
     headers to add to the request. e.g. ``Accept: foo``.
 
     The following arguments are special:
 
     ``BODYFILE``
         The content of the file defined as the value to this argument will be
         transferred verbatim as the HTTP request body.
 
     ``frame <type> <flags> <payload>``
         Send a unified protocol frame as part of the request body.
 
         All frames will be collected and sent as the body to the HTTP
         request.
 
     close
     -----
 
     Close the connection to the server.
 
     flush
     -----
 
     Flush data written to the server.
 
     readavailable
     -------------
 
     Close the write end of the connection and read all available data from
     the server.
 
     If the connection to the server encompasses multiple pipes, we poll both
     pipes and read available data.
 
     readline
     --------
 
     Read a line of output from the server. If there are multiple output
     pipes, reads only the main pipe.
 
     ereadline
     ---------
 
     Like ``readline``, but read from the stderr pipe, if available.
 
     read <X>
     --------
 
     ``read()`` N bytes from the server's main output pipe.
 
     eread <X>
     ---------
 
     ``read()`` N bytes from the server's stderr pipe, if available.
 
     Specifying Unified Frame-Based Protocol Frames
     ----------------------------------------------
 
     It is possible to emit a *Unified Frame-Based Protocol* by using special
     syntax.
 
     A frame is composed as a type, flags, and payload. These can be parsed
-    from a string of the form ``<requestid> <type> <flags> <payload>``. That is,
-    4 space-delimited strings.
-
-    ``payload`` is the simplest: it is evaluated as a Python byte string
-    literal.
-
-    ``requestid`` is an integer defining the request identifier.
+    from a string of the form:
+
+       <request-id> <stream-id> <stream-flags> <type> <flags> <payload>
+
+    ``request-id`` and ``stream-id`` are integers defining the request and
+    stream identifiers.
 
     ``type`` can be an integer value for the frame type or the string name
     of the type. The strings are defined in ``wireprotoframing.py``. e.g.
     ``command-name``.
 
-    ``flags`` is a ``|`` delimited list of flag components. Each component
-    (and there can be just one) can be an integer or a flag name for the
-    specified frame type. Values are resolved to integers and then bitwise
-    OR'd together.
+    ``stream-flags`` and ``flags`` are a ``|`` delimited list of flag
+    components. Each component (and there can be just one) can be an integer
+    or a flag name for stream flags or frame flags, respectively. Values are
+    resolved to integers and then bitwise OR'd together.
+
+    ``payload`` is is evaluated as a Python byte string literal.
     """
     opts = pycompat.byteskwargs(opts)
 
     if opts['localssh'] and not repo:
         raise error.Abort(_('--localssh requires a repository'))
 
     if opts['peer'] and opts['peer'] not in ('raw', 'ssh1', 'ssh2'):
         raise error.Abort(_('invalid value for --peer'),
                           hint=_('valid values are "raw", "ssh1", and "ssh2"'))
 
     if path and opts['localssh']:
         raise error.Abort(_('cannot specify --localssh with an explicit '
                             'path'))
 
     if ui.interactive():
         ui.write(_('(waiting for commands on stdin)\n'))
 
     blocks = list(_parsewirelangblocks(ui.fin))
 
     proc = None
     stdin = None
     stdout = None
     stderr = None
     opener = None
 
     if opts['localssh']:
         # We start the SSH server in its own process so there is process
         # separation. This prevents a whole class of potential bugs around
         # shared state from interfering with server operation.
         args = procutil.hgcmd() + [
             '-R', repo.root,
             'debugserve', '--sshstdio',
         ]
         proc = subprocess.Popen(args, stdin=subprocess.PIPE,
                                 stdout=subprocess.PIPE, stderr=subprocess.PIPE,
                                 bufsize=0)
 
         stdin = proc.stdin
         stdout = proc.stdout
         stderr = proc.stderr
 
         # We turn the pipes into observers so we can log I/O.
         if ui.verbose or opts['peer'] == 'raw':
             stdin = util.makeloggingfileobject(ui, proc.stdin, b'i',
                                                logdata=True)
             stdout = util.makeloggingfileobject(ui, proc.stdout, b'o',
                                                 logdata=True)
             stderr = util.makeloggingfileobject(ui, proc.stderr, b'e',
                                                 logdata=True)
 
         # --localssh also implies the peer connection settings.
 
         url = 'ssh://localserver'
         autoreadstderr = not opts['noreadstderr']
 
         if opts['peer'] == 'ssh1':
             ui.write(_('creating ssh peer for wire protocol version 1\n'))
             peer = sshpeer.sshv1peer(ui, url, proc, stdin, stdout, stderr,
                                      None, autoreadstderr=autoreadstderr)
         elif opts['peer'] == 'ssh2':
             ui.write(_('creating ssh peer for wire protocol version 2\n'))
             peer = sshpeer.sshv2peer(ui, url, proc, stdin, stdout, stderr,
                                      None, autoreadstderr=autoreadstderr)
         elif opts['peer'] == 'raw':
             ui.write(_('using raw connection to peer\n'))
             peer = None
         else:
             ui.write(_('creating ssh peer from handshake results\n'))
             peer = sshpeer.makepeer(ui, url, proc, stdin, stdout, stderr,
                                     autoreadstderr=autoreadstderr)
 
     elif path:
         # We bypass hg.peer() so we can proxy the sockets.
         # TODO consider not doing this because we skip
         # ``hg.wirepeersetupfuncs`` and potentially other useful functionality.
         u = util.url(path)
         if u.scheme != 'http':
             raise error.Abort(_('only http:// paths are currently supported'))
 
         url, authinfo = u.authinfo()
         openerargs = {}
 
         # Turn pipes/sockets into observers so we can log I/O.
         if ui.verbose:
             openerargs = {
                 r'loggingfh': ui,
                 r'loggingname': b's',
                 r'loggingopts': {
                     r'logdata': True,
                     r'logdataapis': False,
                 },
             }
 
         if ui.debugflag:
             openerargs[r'loggingopts'][r'logdataapis'] = True
 
         # Don't send default headers when in raw mode. This allows us to
         # bypass most of the behavior of our URL handling code so we can
         # have near complete control over what's sent on the wire.
         if opts['peer'] == 'raw':
             openerargs[r'sendaccept'] = False
 
         opener = urlmod.opener(ui, authinfo, **openerargs)
 
         if opts['peer'] == 'raw':
             ui.write(_('using raw connection to peer\n'))
             peer = None
         elif opts['peer']:
             raise error.Abort(_('--peer %s not supported with HTTP peers') %
                               opts['peer'])
         else:
             peer = httppeer.httppeer(ui, path, url, opener)
             peer._fetchcaps()
 
         # We /could/ populate stdin/stdout with sock.makefile()...
     else:
         raise error.Abort(_('unsupported connection configuration'))
 
     batchedcommands = None
 
     # Now perform actions based on the parsed wire language instructions.
     for action, lines in blocks:
         if action in ('raw', 'raw+'):
             if not stdin:
                 raise error.Abort(_('cannot call raw/raw+ on this peer'))
 
             # Concatenate the data together.
             data = ''.join(l.lstrip() for l in lines)
             data = stringutil.unescapestr(data)
             stdin.write(data)
 
             if action == 'raw+':
                 stdin.flush()
         elif action == 'flush':
             if not stdin:
                 raise error.Abort(_('cannot call flush on this peer'))
             stdin.flush()
         elif action.startswith('command'):
             if not peer:
                 raise error.Abort(_('cannot send commands unless peer instance '
                                     'is available'))
 
             command = action.split(' ', 1)[1]
 
             args = {}
             for line in lines:
                 # We need to allow empty values.
                 fields = line.lstrip().split(' ', 1)
                 if len(fields) == 1:
                     key = fields[0]
                     value = ''
                 else:
                     key, value = fields
 
                 args[key] = stringutil.unescapestr(value)
 
             if batchedcommands is not None:
                 batchedcommands.append((command, args))
                 continue
 
             ui.status(_('sending %s command\n') % command)
 
             if 'PUSHFILE' in args:
                 with open(args['PUSHFILE'], r'rb') as fh:
                     del args['PUSHFILE']
                     res, output = peer._callpush(command, fh,
                                                  **pycompat.strkwargs(args))
                     ui.status(_('result: %s\n') % stringutil.escapedata(res))
                     ui.status(_('remote output: %s\n') %
                               stringutil.escapedata(output))
             else:
                 res = peer._call(command, **pycompat.strkwargs(args))
                 ui.status(_('response: %s\n') % stringutil.escapedata(res))
 
         elif action == 'batchbegin':
             if batchedcommands is not None:
                 raise error.Abort(_('nested batchbegin not allowed'))
 
             batchedcommands = []
         elif action == 'batchsubmit':
             # There is a batching API we could go through. But it would be
             # difficult to normalize requests into function calls. It is easier
             # to bypass this layer and normalize to commands + args.
             ui.status(_('sending batch with %d sub-commands\n') %
                       len(batchedcommands))
             for i, chunk in enumerate(peer._submitbatch(batchedcommands)):
                 ui.status(_('response #%d: %s\n') %
                           (i, stringutil.escapedata(chunk)))
 
             batchedcommands = None
 
         elif action.startswith('httprequest '):
             if not opener:
                 raise error.Abort(_('cannot use httprequest without an HTTP '
                                     'peer'))
 
             request = action.split(' ', 2)
             if len(request) != 3:
                 raise error.Abort(_('invalid httprequest: expected format is '
                                     '"httprequest <method> <path>'))
 
             method, httppath = request[1:]
             headers = {}
             body = None
             frames = []
             for line in lines:
                 line = line.lstrip()
                 m = re.match(b'^([a-zA-Z0-9_-]+): (.*)$', line)
                 if m:
                     headers[m.group(1)] = m.group(2)
                     continue
 
                 if line.startswith(b'BODYFILE '):
                     with open(line.split(b' ', 1), 'rb') as fh:
                         body = fh.read()
                 elif line.startswith(b'frame '):
                     frame = wireprotoframing.makeframefromhumanstring(
                         line[len(b'frame '):])
 
                     frames.append(frame)
                 else:
                     raise error.Abort(_('unknown argument to httprequest: %s') %
                                       line)
 
             url = path + httppath
 
             if frames:
                 body = b''.join(bytes(f) for f in frames)
 
             req = urlmod.urlreq.request(pycompat.strurl(url), body, headers)
 
             # urllib.Request insists on using has_data() as a proxy for
             # determining the request method. Override that to use our
             # explicitly requested method.
             req.get_method = lambda: method
 
             try:
                 opener.open(req).read()
             except util.urlerr.urlerror as e:
                 e.read()
 
         elif action == 'close':
             peer.close()
         elif action == 'readavailable':
             if not stdout or not stderr:
                 raise error.Abort(_('readavailable not available on this peer'))
 
             stdin.close()
             stdout.read()
             stderr.read()
 
         elif action == 'readline':
             if not stdout:
                 raise error.Abort(_('readline not available on this peer'))
             stdout.readline()
         elif action == 'ereadline':
             if not stderr:
                 raise error.Abort(_('ereadline not available on this peer'))
             stderr.readline()
         elif action.startswith('read '):
             count = int(action.split(' ', 1)[1])
             if not stdout:
                 raise error.Abort(_('read not available on this peer'))
             stdout.read(count)
         elif action.startswith('eread '):
             count = int(action.split(' ', 1)[1])
             if not stderr:
                 raise error.Abort(_('eread not available on this peer'))
             stderr.read(count)
         else:
             raise error.Abort(_('unknown action: %s') % action)
 
     if batchedcommands is not None:
         raise error.Abort(_('unclosed "batchbegin" request'))
 
     if peer:
         peer.close()
 
     if proc:
         proc.kill()

mercurial/help/internals/wireprotocol.txt

@@ -1,1472 +1,1612 b''
 The Mercurial wire protocol is a request-response based protocol
 with multiple wire representations.
 
 Each request is modeled as a command name, a dictionary of arguments, and
 optional raw input. Command arguments and their types are intrinsic
 properties of commands. So is the response type of the command. This means
 clients can't always send arbitrary arguments to servers and servers can't
 return multiple response types.
 
 The protocol is synchronous and does not support multiplexing (concurrent
 commands).
 
 Handshake
 =========
 
 It is required or common for clients to perform a *handshake* when connecting
 to a server. The handshake serves the following purposes:
 
 * Negotiating protocol/transport level options
 * Allows the client to learn about server capabilities to influence
   future requests
 * Ensures the underlying transport channel is in a *clean* state
 
 An important goal of the handshake is to allow clients to use more modern
 wire protocol features. By default, clients must assume they are talking
 to an old version of Mercurial server (possibly even the very first
 implementation). So, clients should not attempt to call or utilize modern
 wire protocol features until they have confirmation that the server
 supports them. The handshake implementation is designed to allow both
 ends to utilize the latest set of features and capabilities with as
 few round trips as possible.
 
 The handshake mechanism varies by transport and protocol and is documented
 in the sections below.
 
 HTTP Protocol
 =============
 
 Handshake
 ---------
 
 The client sends a ``capabilities`` command request (``?cmd=capabilities``)
 as soon as HTTP requests may be issued.
 
 The server responds with a capabilities string, which the client parses to
 learn about the server's abilities.
 
 HTTP Version 1 Transport
 ------------------------
 
 Commands are issued as HTTP/1.0 or HTTP/1.1 requests. Commands are
 sent to the base URL of the repository with the command name sent in
 the ``cmd`` query string parameter. e.g.
 ``https://example.com/repo?cmd=capabilities``. The HTTP method is ``GET``
 or ``POST`` depending on the command and whether there is a request
 body.
 
 Command arguments can be sent multiple ways.
 
 The simplest is part of the URL query string using ``x-www-form-urlencoded``
 encoding (see Python's ``urllib.urlencode()``. However, many servers impose
 length limitations on the URL. So this mechanism is typically only used if
 the server doesn't support other mechanisms.
 
 If the server supports the ``httpheader`` capability, command arguments can
 be sent in HTTP request headers named ``X-HgArg-<N>`` where ``<N>`` is an
 integer starting at 1. A ``x-www-form-urlencoded`` representation of the
 arguments is obtained. This full string is then split into chunks and sent
 in numbered ``X-HgArg-<N>`` headers. The maximum length of each HTTP header
 is defined by the server in the ``httpheader`` capability value, which defaults
 to ``1024``. The server reassembles the encoded arguments string by
 concatenating the ``X-HgArg-<N>`` headers then URL decodes them into a
 dictionary.
 
 The list of ``X-HgArg-<N>`` headers should be added to the ``Vary`` request
 header to instruct caches to take these headers into consideration when caching
 requests.
 
 If the server supports the ``httppostargs`` capability, the client
 may send command arguments in the HTTP request body as part of an
 HTTP POST request. The command arguments will be URL encoded just like
 they would for sending them via HTTP headers. However, no splitting is
 performed: the raw arguments are included in the HTTP request body.
 
 The client sends a ``X-HgArgs-Post`` header with the string length of the
 encoded arguments data. Additional data may be included in the HTTP
 request body immediately following the argument data. The offset of the
 non-argument data is defined by the ``X-HgArgs-Post`` header. The
 ``X-HgArgs-Post`` header is not required if there is no argument data.
 
 Additional command data can be sent as part of the HTTP request body. The
 default ``Content-Type`` when sending data is ``application/mercurial-0.1``.
 A ``Content-Length`` header is currently always sent.
 
 Example HTTP requests::
 
     GET /repo?cmd=capabilities
     X-HgArg-1: foo=bar&baz=hello%20world
 
 The request media type should be chosen based on server support. If the
 ``httpmediatype`` server capability is present, the client should send
 the newest mutually supported media type. If this capability is absent,
 the client must assume the server only supports the
 ``application/mercurial-0.1`` media type.
 
 The ``Content-Type`` HTTP response header identifies the response as coming
 from Mercurial and can also be used to signal an error has occurred.
 
 The ``application/mercurial-*`` media types indicate a generic Mercurial
 data type.
 
 The ``application/mercurial-0.1`` media type is raw Mercurial data. It is the
 predecessor of the format below.
 
 The ``application/mercurial-0.2`` media type is compression framed Mercurial
 data. The first byte of the payload indicates the length of the compression
 format identifier that follows. Next are N bytes indicating the compression
 format. e.g. ``zlib``. The remaining bytes are compressed according to that
 compression format. The decompressed data behaves the same as with
 ``application/mercurial-0.1``.
 
 The ``application/hg-error`` media type indicates a generic error occurred.
 The content of the HTTP response body typically holds text describing the
 error.
 
 The ``application/hg-changegroup`` media type indicates a changegroup response
 type.
 
 Clients also accept the ``text/plain`` media type. All other media
 types should cause the client to error.
 
 Behavior of media types is further described in the ``Content Negotiation``
 section below.
 
 Clients should issue a ``User-Agent`` request header that identifies the client.
 The server should not use the ``User-Agent`` for feature detection.
 
 A command returning a ``string`` response issues a
 ``application/mercurial-0.*`` media type and the HTTP response body contains
 the raw string value (after compression decoding, if used). A
 ``Content-Length`` header is typically issued, but not required.
 
 A command returning a ``stream`` response issues a
 ``application/mercurial-0.*`` media type and the HTTP response is typically
 using *chunked transfer* (``Transfer-Encoding: chunked``).
 
 HTTP Version 2 Transport
 ------------------------
 
 **Experimental - feature under active development**
 
 Version 2 of the HTTP protocol is exposed under the ``/api/*`` URL space.
 It's final API name is not yet formalized.
 
 Commands are triggered by sending HTTP POST requests against URLs of the
 form ``<permission>/<command>``, where ``<permission>`` is ``ro`` or
 ``rw``, meaning read-only and read-write, respectively and ``<command>``
 is a named wire protocol command.
 
 Non-POST request methods MUST be rejected by the server with an HTTP
 405 response.
 
 Commands that modify repository state in meaningful ways MUST NOT be
 exposed under the ``ro`` URL prefix. All available commands MUST be
 available under the ``rw`` URL prefix.
 
 Server adminstrators MAY implement blanket HTTP authentication keyed
 off the URL prefix. For example, a server may require authentication
 for all ``rw/*`` URLs and let unauthenticated requests to ``ro/*``
 URL proceed. A server MAY issue an HTTP 401, 403, or 407 response
 in accordance with RFC 7235. Clients SHOULD recognize the HTTP Basic
 (RFC 7617) and Digest (RFC 7616) authentication schemes. Clients SHOULD
 make an attempt to recognize unknown schemes using the
 ``WWW-Authenticate`` response header on a 401 response, as defined by
 RFC 7235.
 
 Read-only commands are accessible under ``rw/*`` URLs so clients can
 signal the intent of the operation very early in the connection
 lifecycle. For example, a ``push`` operation - which consists of
 various read-only commands mixed with at least one read-write command -
 can perform all commands against ``rw/*`` URLs so that any server-side
 authentication requirements are discovered upon attempting the first
 command - not potentially several commands into the exchange. This
 allows clients to fail faster or prompt for credentials as soon as the
 exchange takes place. This provides a better end-user experience.
 
 Requests to unknown commands or URLS result in an HTTP 404.
 TODO formally define response type, how error is communicated, etc.
 
 HTTP request and response bodies use the *Unified Frame-Based Protocol*
 (defined below) for media exchange. The entirety of the HTTP message
 body is 0 or more frames as defined by this protocol.
 
 Clients and servers MUST advertise the ``TBD`` media type via the
 ``Content-Type`` request and response headers. In addition, clients MUST
 advertise this media type value in their ``Accept`` request header in all
 requests.
 TODO finalize the media type. For now, it is defined in wireprotoserver.py.
 
 Servers receiving requests without an ``Accept`` header SHOULD respond with
 an HTTP 406.
 
 Servers receiving requests with an invalid ``Content-Type`` header SHOULD
 respond with an HTTP 415.
 
 The command to run is specified in the POST payload as defined by the
 *Unified Frame-Based Protocol*. This is redundant with data already
 encoded in the URL. This is by design, so server operators can have
 better understanding about server activity from looking merely at
 HTTP access logs.
 
 In most circumstances, the command specified in the URL MUST match
 the command specified in the frame-based payload or the server will
 respond with an error. The exception to this is the special
 ``multirequest`` URL. (See below.) In addition, HTTP requests
 are limited to one command invocation. The exception is the special
 ``multirequest`` URL.
 
 The ``multirequest`` command endpoints (``ro/multirequest`` and
 ``rw/multirequest``) are special in that they allow the execution of
 *any* command and allow the execution of multiple commands. If the
 HTTP request issues multiple commands across multiple frames, all
 issued commands will be processed by the server. Per the defined
 behavior of the *Unified Frame-Based Protocol*, commands may be
 issued interleaved and responses may come back in a different order
 than they were issued. Clients MUST be able to deal with this.
 
 SSH Protocol
 ============
 
 Handshake
 ---------
 
 For all clients, the handshake consists of the client sending 1 or more
 commands to the server using version 1 of the transport. Servers respond
 to commands they know how to respond to and send an empty response (``0\n``)
 for unknown commands (per standard behavior of version 1 of the transport).
 Clients then typically look for a response to the newest sent command to
 determine which transport version to use and what the available features for
 the connection and server are.
 
 Preceding any response from client-issued commands, the server may print
 non-protocol output. It is common for SSH servers to print banners, message
 of the day announcements, etc when clients connect. It is assumed that any
 such *banner* output will precede any Mercurial server output. So clients
 must be prepared to handle server output on initial connect that isn't
 in response to any client-issued command and doesn't conform to Mercurial's
 wire protocol. This *banner* output should only be on stdout. However,
 some servers may send output on stderr.
 
 Pre 0.9.1 clients issue a ``between`` command with the ``pairs`` argument
 having the value
 ``0000000000000000000000000000000000000000-0000000000000000000000000000000000000000``.
 
 The ``between`` command has been supported since the original Mercurial
 SSH server. Requesting the empty range will return a ``\n`` string response,
 which will be encoded as ``1\n\n`` (value length of ``1`` followed by a newline
 followed by the value, which happens to be a newline).
 
 For pre 0.9.1 clients and all servers, the exchange looks like::
 
    c: between\n
    c: pairs 81\n
    c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
    s: 1\n
    s: \n
 
 0.9.1+ clients send a ``hello`` command (with no arguments) before the
 ``between`` command. The response to this command allows clients to
 discover server capabilities and settings.
 
 An example exchange between 0.9.1+ clients and a ``hello`` aware server looks
 like::
 
    c: hello\n
    c: between\n
    c: pairs 81\n
    c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
    s: 324\n
    s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
    s: 1\n
    s: \n
 
 And a similar scenario but with servers sending a banner on connect::
 
    c: hello\n
    c: between\n
    c: pairs 81\n
    c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
    s: welcome to the server\n
    s: if you find any issues, email [e-mail]\n
    s: 324\n
    s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
    s: 1\n
    s: \n
 
 Note that output from the ``hello`` command is terminated by a ``\n``. This is
 part of the response payload and not part of the wire protocol adding a newline
 after responses. In other words, the length of the response contains the
 trailing ``\n``.
 
 Clients supporting version 2 of the SSH transport send a line beginning
 with ``upgrade`` before the ``hello`` and ``between`` commands. The line
 (which isn't a well-formed command line because it doesn't consist of a
 single command name) serves to both communicate the client's intent to
 switch to transport version 2 (transports are version 1 by default) as
 well as to advertise the client's transport-level capabilities so the
 server may satisfy that request immediately.
 
 The upgrade line has the form:
 
     upgrade <token> <transport capabilities>
 
 That is the literal string ``upgrade`` followed by a space, followed by
 a randomly generated string, followed by a space, followed by a string
 denoting the client's transport capabilities.
 
 The token can be anything. However, a random UUID is recommended. (Use
 of version 4 UUIDs is recommended because version 1 UUIDs can leak the
 client's MAC address.)
 
 The transport capabilities string is a URL/percent encoded string
 containing key-value pairs defining the client's transport-level
 capabilities. The following capabilities are defined:
 
 proto
    A comma-delimited list of transport protocol versions the client
    supports. e.g. ``ssh-v2``.
 
 If the server does not recognize the ``upgrade`` line, it should issue
 an empty response and continue processing the ``hello`` and ``between``
 commands. Here is an example handshake between a version 2 aware client
 and a non version 2 aware server:
 
    c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2
    c: hello\n
    c: between\n
    c: pairs 81\n
    c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
    s: 0\n
    s: 324\n
    s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
    s: 1\n
    s: \n
 
 (The initial ``0\n`` line from the server indicates an empty response to
 the unknown ``upgrade ..`` command/line.)
 
 If the server recognizes the ``upgrade`` line and is willing to satisfy that
 upgrade request, it replies to with a payload of the following form:
 
    upgraded <token> <transport name>\n
 
 This line is the literal string ``upgraded``, a space, the token that was
 specified by the client in its ``upgrade ...`` request line, a space, and the
 name of the transport protocol that was chosen by the server. The transport
 name MUST match one of the names the client specified in the ``proto`` field
 of its ``upgrade ...`` request line.
 
 If a server issues an ``upgraded`` response, it MUST also read and ignore
 the lines associated with the ``hello`` and ``between`` command requests
 that were issued by the server. It is assumed that the negotiated transport
 will respond with equivalent requested information following the transport
 handshake.
 
 All data following the ``\n`` terminating the ``upgraded`` line is the
 domain of the negotiated transport. It is common for the data immediately
 following to contain additional metadata about the state of the transport and
 the server. However, this isn't strictly speaking part of the transport
 handshake and isn't covered by this section.
 
 Here is an example handshake between a version 2 aware client and a version
 2 aware server:
 
    c:  upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2
    c:  hello\n
    c:  between\n
    c:  pairs 81\n
    c:  0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
    s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n
    s: <additional transport specific data>
 
 The client-issued token that is echoed in the response provides a more
 resilient mechanism for differentiating *banner* output from Mercurial
 output. In version 1, properly formatted banner output could get confused
 for Mercurial server output. By submitting a randomly generated token
 that is then present in the response, the client can look for that token
 in response lines and have reasonable certainty that the line did not
 originate from a *banner* message.
 
 SSH Version 1 Transport
 -----------------------
 
 The SSH transport (version 1) is a custom text-based protocol suitable for
 use over any bi-directional stream transport. It is most commonly used with
 SSH.
 
 A SSH transport server can be started with ``hg serve --stdio``. The stdin,
 stderr, and stdout file descriptors of the started process are used to exchange
 data. When Mercurial connects to a remote server over SSH, it actually starts
 a ``hg serve --stdio`` process on the remote server.
 
 Commands are issued by sending the command name followed by a trailing newline
 ``\n`` to the server. e.g. ``capabilities\n``.
 
 Command arguments are sent in the following format::
 
     <argument> <length>\n<value>
 
 That is, the argument string name followed by a space followed by the
 integer length of the value (expressed as a string) followed by a newline
 (``\n``) followed by the raw argument value.
 
 Dictionary arguments are encoded differently::
 
     <argument> <# elements>\n
     <key1> <length1>\n<value1>
     <key2> <length2>\n<value2>
     ...
 
 Non-argument data is sent immediately after the final argument value. It is
 encoded in chunks::
 
     <length>\n<data>
 
 Each command declares a list of supported arguments and their types. If a
 client sends an unknown argument to the server, the server should abort
 immediately. The special argument ``*`` in a command's definition indicates
 that all argument names are allowed.
 
 The definition of supported arguments and types is initially made when a
 new command is implemented. The client and server must initially independently
 agree on the arguments and their types. This initial set of arguments can be
 supplemented through the presence of *capabilities* advertised by the server.
 
 Each command has a defined expected response type.
 
 A ``string`` response type is a length framed value. The response consists of
 the string encoded integer length of a value followed by a newline (``\n``)
 followed by the value. Empty values are allowed (and are represented as
 ``0\n``).
 
 A ``stream`` response type consists of raw bytes of data. There is no framing.
 
 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).
 
 SSH Version 2 Transport
 -----------------------
 
 **Experimental and under development**
 
 Version 2 of the SSH transport behaves identically to version 1 of the SSH
 transport with the exception of handshake semantics. See above for how
 version 2 of the SSH transport is negotiated.
 
 Immediately following the ``upgraded`` line signaling a switch to version
 2 of the SSH protocol, the server automatically sends additional details
 about the capabilities of the remote server. This has the form:
 
    <integer length of value>\n
    capabilities: ...\n
 
 e.g.
 
    s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n
    s: 240\n
    s: capabilities: known getbundle batch ...\n
 
 Following capabilities advertisement, the peers communicate using version
 1 of the SSH transport.
 
 Unified Frame-Based Protocol
 ============================
 
 **Experimental and under development**
 
 The *Unified Frame-Based Protocol* is a communications protocol between
 Mercurial peers. The protocol aims to be mostly transport agnostic
 (works similarly on HTTP, SSH, etc).
 
 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.
 
+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 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 numbered request. Frames can thus
 be logically grouped by their request ID.
 
-Frames begin with a 6 octet header followed by a variable length
+Frames begin with an 8 octet header followed by a variable length
 payload::
 
-    +-----------------------------------------------+
-    |                 Length (24)                   |
-    +---------------------------------+-------------+
-    |         Request ID (16)         |
-    +----------+-----------+----------+
-    | Type (4) | Flags (4) |
-    +==========+===========+========================================|
+    +------------------------------------------------+
+    |                 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.
+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 4-bit ``Type`` field denotes the type of message being sent.
+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 name of the command to run constitutes the entirety of the frame
 payload.
 
 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
    End of command data. When set, the client will not send any command
    arguments or additional command data. When set, the command has been
    fully issued and the server has the full context to process the command.
    The next frame issued by the client is not part of this command.
 0x02
    Command argument frames expected. When set, the client will send
    *Command Argument* frames containing command argument data.
 0x04
    Command data frames expected. When set, the client will send
    *Command Data* frames containing a raw stream of data for this
    command.
 
 The ``0x01`` flag is mutually exclusive with both the ``0x02`` and ``0x04``
 flags.
 
 Command Argument (``0x02``)
 ---------------------------
 
 This frame contains a named argument for a command.
 
 The frame type MUST ONLY be sent from clients to servers: it is illegal
 for a server to send this frame to a client.
 
 The payload consists of:
 
 * A 16-bit little endian integer denoting the length of the
   argument name.
 * A 16-bit little endian integer denoting the length of the
   argument value.
 * N bytes of ASCII data containing the argument name.
 * N bytes of binary data containing the argument value.
 
 The payload MUST hold the entirety of the 32-bit header and the
 argument name. The argument value MAY span multiple frames. If this
 occurs, the appropriate frame flag should be set to indicate this.
 
 The following flag values are defined for this type:
 
 0x01
    Argument data continuation. When set, the data for this argument did
    not fit in a single frame and the next frame will contain additional
    argument data.
 
 0x02
    End of arguments data. When set, the client will not send any more
    command arguments for the command this frame is associated with.
    The next frame issued by the client will be command data or
    belong to a separate request.
 
 Command Data (``0x03``)
 -----------------------
 
 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.
 
 Bytes Response Data (``0x04``)
 ------------------------------
 
 This frame contains raw bytes response data to an issued command.
 
 The following flag values are defined for this type:
 
 0x01
    Data continuation. When set, an additional frame containing raw
    response data will follow.
 0x02
    End of data. When sent, 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 Response (``0x05``)
 -------------------------
 
 An error occurred when processing a request. This could indicate
 a protocol-level failure or an application level failure depending
 on the flags for this message type.
 
 The payload for this type is an error message that should be
 displayed to the user.
 
 The following flag values are defined for this type:
 
 0x01
    The error occurred at the transport/protocol level. If set, the
    connection should be closed.
 0x02
    The error occurred at the application level. e.g. invalid command.
 
 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 raw frame consists of a series of data structures representing
 textual atoms to print. Each atom begins with a struct defining the
 size of the data that follows:
 
 * A 16-bit little endian unsigned integer denoting the length of the
   formatting string.
 * An 8-bit unsigned integer denoting the number of label strings
   that follow.
 * An 8-bit unsigned integer denoting the number of formatting string
   arguments strings that follow.
 * An array of 8-bit unsigned integers denoting the lengths of
   *labels* data.
 * An array of 16-bit unsigned integers denoting the lengths of
   formatting strings.
 * The formatting string, encoded as UTF-8.
 * 0 or more ASCII strings defining labels to apply to this atom.
 * 0 or more UTF-8 strings that will be used as arguments to the
   formatting string.
 
 TODO use ASCII for formatting string.
 
 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.
 
+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
+
 Issuing Commands
 ----------------
 
 A client can request that a remote run a command by sending it
 frames defining that command. This logical stream is composed of
 1 ``Command Request`` frame, 0 or more ``Command Argument`` frames,
 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.
 
 Argument frames are the recommended mechanism for transferring fixed
 sets of parameters to a command. Data frames are appropriate for
 transferring variable data. A similar comparison would be to HTTP:
 argument frames are headers and the message body is data frames.
 
 It is recommended for servers to delay the dispatch of a command
 until all argument frames for that command 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.
 
 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.
 
 compression
 -----------
 
 Declares support for negotiating compression formats.
 
 Presence of this capability indicates the server supports dynamic selection
 of compression formats based on the client request.
 
 Servers advertising this capability are required to support the
 ``application/mercurial-0.2`` media type in response to commands returning
 streams. Servers may support this media type on any command.
 
 The value of the capability is a comma-delimited list of strings declaring
 supported compression formats. The order of the compression formats is in
 server-preferred order, most preferred first.
 
 The identifiers used by the official Mercurial distribution are:
 
 bzip2
    bzip2
 none
    uncompressed / raw data
 zlib
    zlib (no gzip header)
 zstd
    zstd
 
 This capability was introduced in Mercurial 4.1 (released February 2017).
 
 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).
 
 httpmediatype
 -------------
 
 Indicates which HTTP media types (``Content-Type`` header) the server is
 capable of receiving and sending.
 
 The value of the capability is a comma-delimited list of strings identifying
 support for media type and transmission direction. The following strings may
 be present:
 
 0.1rx
    Indicates server support for receiving ``application/mercurial-0.1`` media
    types.
 
 0.1tx
    Indicates server support for sending ``application/mercurial-0.1`` media
    types.
 
 0.2rx
    Indicates server support for receiving ``application/mercurial-0.2`` media
    types.
 
 0.2tx
    Indicates server support for sending ``application/mercurial-0.2`` media
    types.
 
 minrx=X
    Minimum media type version the server is capable of receiving. Value is a
    string like ``0.2``.
 
    This capability can be used by servers to limit connections from legacy
    clients not using the latest supported media type. However, only clients
    with knowledge of this capability will know to consult this value. This
    capability is present so the client may issue a more user-friendly error
    when the server has locked out a legacy client.
 
 mintx=X
    Minimum media type version the server is capable of sending. Value is a
    string like ``0.1``.
 
 Servers advertising support for the ``application/mercurial-0.2`` media type
 should also advertise the ``compression`` capability.
 
 This capability was introduced in Mercurial 4.1 (released February 2017).
 
 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 --stream``) 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.
 
 Content Negotiation
 ===================
 
 The wire protocol has some mechanisms to help peers determine what content
 types and encoding the other side will accept. Historically, these mechanisms
 have been built into commands themselves because most commands only send a
 well-defined response type and only certain commands needed to support
 functionality like compression.
 
 Currently, only the HTTP version 1 transport supports content negotiation
 at the protocol layer.
 
 HTTP requests advertise supported response formats via the ``X-HgProto-<N>``
 request header, where ``<N>`` is an integer starting at 1 allowing the logical
 value to span multiple headers. This value consists of a list of
 space-delimited parameters. Each parameter denotes a feature or capability.
 
 The following parameters are defined:
 
 0.1
    Indicates the client supports receiving ``application/mercurial-0.1``
    responses.
 
 0.2
    Indicates the client supports receiving ``application/mercurial-0.2``
    responses.
 
 comp
    Indicates compression formats the client can decode. Value is a list of
    comma delimited strings identifying compression formats ordered from
    most preferential to least preferential. e.g. ``comp=zstd,zlib,none``.
 
    This parameter does not have an effect if only the ``0.1`` parameter
    is defined, as support for ``application/mercurial-0.2`` or greater is
    required to use arbitrary compression formats.
 
    If this parameter is not advertised, the server interprets this as
    equivalent to ``zlib,none``.
 
 Clients may choose to only send this header if the ``httpmediatype``
 server capability is present, as currently all server-side features
 consulting this header require the client to opt in to new protocol features
 advertised via the ``httpmediatype`` capability.
 
 A server that doesn't receive an ``X-HgProto-<N>`` header should infer a
 value of ``0.1``. This is compatible with legacy clients.
 
 A server receiving a request indicating support for multiple media type
 versions may respond with any of the supported media types. Not all servers
 may support all media types on all commands.
 
 Commands
 ========
 
 This section contains a list of all wire protocol commands implemented by
 the canonical Mercurial server.
 
 batch
 -----
 
 Issue multiple commands while sending a single command request. The purpose
 of this command is to allow a client to issue multiple commands while avoiding
 multiple round trips to the server therefore enabling commands to complete
 quicker.
 
 The command accepts a ``cmds`` argument that contains a list of commands to
 execute.
 
 The value of ``cmds`` is a ``;`` delimited list of strings. Each string has the
 form ``<command> <arguments>``. That is, the command name followed by a space
 followed by an argument string.
 
 The argument string is a ``,`` delimited list of ``<key>=<value>`` values
 corresponding to command arguments. Both the argument name and value are
 escaped using a special substitution map::
 
    : -> :c
    , -> :o
    ; -> :s
    = -> :e
 
 The response type for this command is ``string``. The value contains a
 ``;`` delimited list of responses for each requested command. Each value
 in this list is escaped using the same substitution map used for arguments.
 
 If an error occurs, the generic error response may be sent.
 
 between
 -------
 
 (Legacy command used for discovery in old clients)
 
 Obtain nodes between pairs of nodes.
 
 The ``pairs`` arguments contains a space-delimited list of ``-`` delimited
 hex node pairs. e.g.::
 
    a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18
 
 Return type is a ``string``. Value consists of lines corresponding to each
 requested range. Each line contains a space-delimited list of hex nodes.
 A newline ``\n`` terminates each line, including the last one.
 
 branchmap
 ---------
 
 Obtain heads in named branches.
 
 Accepts no arguments. Return type is a ``string``.
 
 Return value contains lines with URL encoded branch names followed by a space
 followed by a space-delimited list of hex nodes of heads on that branch.
 e.g.::
 
     default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18
     stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc
 
 There is no trailing newline.
 
 branches
 --------
 
 (Legacy command used for discovery in old clients. Clients with ``getbundle``
 use the ``known`` and ``heads`` commands instead.)
 
 Obtain ancestor changesets of specific nodes back to a branch point.
 
 Despite the name, this command has nothing to do with Mercurial named branches.
 Instead, it is related to DAG branches.
 
 The command accepts a ``nodes`` argument, which is a string of space-delimited
 hex nodes.
 
 For each node requested, the server will find the first ancestor node that is
 a DAG root or is a merge.
 
 Return type is a ``string``. Return value contains lines with result data for
 each requested node. Each line contains space-delimited nodes followed by a
 newline (``\n``). The 4 nodes reported on each line correspond to the requested
 node, the ancestor node found, and its 2 parent nodes (which may be the null
 node).
 
 capabilities
 ------------
 
 Obtain the capabilities string for the repo.
 
 Unlike the ``hello`` command, the capabilities string is not prefixed.
 There is no trailing newline.
 
 This command does not accept any arguments. Return type is a ``string``.
 
 This command was introduced in Mercurial 0.9.1 (released July 2006).
 
 changegroup
 -----------
 
 (Legacy command: use ``getbundle`` instead)
 
 Obtain a changegroup version 1 with data for changesets that are
 descendants of client-specified changesets.
 
 The ``roots`` arguments contains a list of space-delimited hex nodes.
 
 The server responds with a changegroup version 1 containing all
 changesets between the requested root/base nodes and the repo's head nodes
 at the time of the request.
 
 The return type is a ``stream``.
 
 changegroupsubset
 -----------------
 
 (Legacy command: use ``getbundle`` instead)
 
 Obtain a changegroup version 1 with data for changesetsets between
 client specified base and head nodes.
 
 The ``bases`` argument contains a list of space-delimited hex nodes.
 The ``heads`` argument contains a list of space-delimited hex nodes.
 
 The server responds with a changegroup version 1 containing all
 changesets between the requested base and head nodes at the time of the
 request.
 
 The return type is a ``stream``.
 
 clonebundles
 ------------
 
 Obtains a manifest of bundle URLs available to seed clones.
 
 Each returned line contains a URL followed by metadata. See the
 documentation in the ``clonebundles`` extension for more.
 
 The return type is a ``string``.
 
 getbundle
 ---------
 
 Obtain a bundle containing repository data.
 
 This command accepts the following arguments:
 
 heads
    List of space-delimited hex nodes of heads to retrieve.
 common
    List of space-delimited hex nodes that the client has in common with the
    server.
 obsmarkers
    Boolean indicating whether to include obsolescence markers as part
    of the response. Only works with bundle2.
 bundlecaps
    Comma-delimited set of strings defining client bundle capabilities.
 listkeys
    Comma-delimited list of strings of ``pushkey`` namespaces. For each
    namespace listed, a bundle2 part will be included with the content of
    that namespace.
 cg
    Boolean indicating whether changegroup data is requested.
 cbattempted
    Boolean indicating whether the client attempted to use the *clone bundles*
    feature before performing this request.
 bookmarks
    Boolean indicating whether bookmark data is requested.
 phases
    Boolean indicating whether phases data is requested.
 
 The return type on success is a ``stream`` where the value is bundle.
 On the HTTP version 1 transport, the response is zlib compressed.
 
 If an error occurs, a generic error response can be sent.
 
 Unless the client sends a false value for the ``cg`` argument, the returned
 bundle contains a changegroup with the nodes between the specified ``common``
 and ``heads`` nodes. Depending on the command arguments, the type and content
 of the returned bundle can vary significantly.
 
 The default behavior is for the server to send a raw changegroup version
 ``01`` response.
 
 If the ``bundlecaps`` provided by the client contain a value beginning
 with ``HG2``, a bundle2 will be returned. The bundle2 data may contain
 additional repository data, such as ``pushkey`` namespace values.
 
 heads
 -----
 
 Returns a list of space-delimited hex nodes of repository heads followed
 by a newline. e.g.
 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n``
 
 This command does not accept any arguments. The return type is a ``string``.
 
 hello
 -----
 
 Returns lines describing interesting things about the server in an RFC-822
 like format.
 
 Currently, the only line defines the server capabilities. It has the form::
 
     capabilities: <value>
 
 See above for more about the capabilities string.
 
 SSH clients typically issue this command as soon as a connection is
 established.
 
 This command does not accept any arguments. The return type is a ``string``.
 
 This command was introduced in Mercurial 0.9.1 (released July 2006).
 
 listkeys
 --------
 
 List values in a specified ``pushkey`` namespace.
 
 The ``namespace`` argument defines the pushkey namespace to operate on.
 
 The return type is a ``string``. The value is an encoded dictionary of keys.
 
 Key-value pairs are delimited by newlines (``\n``). Within each line, keys and
 values are separated by a tab (``\t``). Keys and values are both strings.
 
 lookup
 ------
 
 Try to resolve a value to a known repository revision.
 
 The ``key`` argument is converted from bytes to an
 ``encoding.localstr`` instance then passed into
 ``localrepository.__getitem__`` in an attempt to resolve it.
 
 The return type is a ``string``.
 
 Upon successful resolution, returns ``1 <hex node>\n``. On failure,
 returns ``0 <error string>\n``. e.g.::
 
    1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n
 
    0 unknown revision 'foo'\n
 
 known
 -----
 
 Determine whether multiple nodes are known.
 
 The ``nodes`` argument is a list of space-delimited hex nodes to check
 for existence.
 
 The return type is ``string``.
 
 Returns a string consisting of ``0``s and ``1``s indicating whether nodes
 are known. If the Nth node specified in the ``nodes`` argument is known,
 a ``1`` will be returned at byte offset N. If the node isn't known, ``0``
 will be present at byte offset N.
 
 There is no trailing newline.
 
 pushkey
 -------
 
 Set a value using the ``pushkey`` protocol.
 
 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which
 correspond to the pushkey namespace to operate on, the key within that
 namespace to change, the old value (which may be empty), and the new value.
 All arguments are string types.
 
 The return type is a ``string``. The value depends on the transport protocol.
 
 The SSH version 1 transport sends a string encoded integer followed by a
 newline (``\n``) which indicates operation result. The server may send
 additional output on the ``stderr`` stream that should be displayed to the
 user.
 
 The HTTP version 1 transport sends a string encoded integer followed by a
 newline followed by additional server output that should be displayed to
 the user. This may include output from hooks, etc.
 
 The integer result varies by namespace. ``0`` means an error has occurred
 and there should be additional output to display to the user.
 
 stream_out
 ----------
 
 Obtain *streaming clone* data.
 
 The return type is either a ``string`` or a ``stream``, depending on
 whether the request was fulfilled properly.
 
 A return value of ``1\n`` indicates the server is not configured to serve
 this data. If this is seen by the client, they may not have verified the
 ``stream`` capability is set before making the request.
 
 A return value of ``2\n`` indicates the server was unable to lock the
 repository to generate data.
 
 All other responses are a ``stream`` of bytes. The first line of this data
 contains 2 space-delimited integers corresponding to the path count and
 payload size, respectively::
 
     <path count> <payload size>\n
 
 The ``<payload size>`` is the total size of path data: it does not include
 the size of the per-path header lines.
 
 Following that header are ``<path count>`` entries. Each entry consists of a
 line with metadata followed by raw revlog data. The line consists of::
 
     <store path>\0<size>\n
 
 The ``<store path>`` is the encoded store path of the data that follows.
 ``<size>`` is the amount of data for this store path/revlog that follows the
 newline.
 
 There is no trailer to indicate end of data. Instead, the client should stop
 reading after ``<path count>`` entries are consumed.
 
 unbundle
 --------
 
 Send a bundle containing data (usually changegroup data) to the server.
 
 Accepts the argument ``heads``, which is a space-delimited list of hex nodes
 corresponding to server repository heads observed by the client. This is used
 to detect race conditions and abort push operations before a server performs
 too much work or a client transfers too much data.
 
 The request payload consists of a bundle to be applied to the repository,
 similarly to as if :hg:`unbundle` were called.
 
 In most scenarios, a special ``push response`` type is returned. This type
 contains an integer describing the change in heads as a result of the
 operation. A value of ``0`` indicates nothing changed. ``1`` means the number
 of heads remained the same. Values ``2`` and larger indicate the number of
 added heads minus 1. e.g. ``3`` means 2 heads were added. Negative values
 indicate the number of fewer heads, also off by 1. e.g. ``-2`` means there
 is 1 fewer head.
 
 The encoding of the ``push response`` type varies by transport.
 
 For the SSH version 1 transport, this type is composed of 2 ``string``
 responses: an empty response (``0\n``) followed by the integer result value.
 e.g. ``1\n2``. So the full response might be ``0\n1\n2``.
 
 For the HTTP version 1 transport, the response is a ``string`` type composed
 of an integer result value followed by a newline (``\n``) followed by string
 content holding server output that should be displayed on the client (output
 hooks, etc).
 
 In some cases, the server may respond with a ``bundle2`` bundle. In this
 case, the response type is ``stream``. For the HTTP version 1 transport, the
 response is zlib compressed.
 
 The server may also respond with a generic error type, which contains a string
 indicating the failure.

mercurial/wireprotoframing.py

@@ -1,732 +1,813 b''
 # wireprotoframing.py - unified framing protocol for wire protocol
 #
 # Copyright 2018 Gregory Szorc <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 # This file contains functionality to support the unified frame-based wire
 # protocol. For details about the protocol, see
 # `hg help internals.wireprotocol`.
 
 from __future__ import absolute_import
 
 import struct
 
 from .i18n import _
 from .thirdparty import (
     attr,
 )
 from . import (
     error,
     util,
 )
 from .utils import (
     stringutil,
 )
 
-FRAME_HEADER_SIZE = 6
+FRAME_HEADER_SIZE = 8
 DEFAULT_MAX_FRAME_SIZE = 32768
 
+STREAM_FLAG_BEGIN_STREAM = 0x01
+STREAM_FLAG_END_STREAM = 0x02
+STREAM_FLAG_ENCODING_APPLIED = 0x04
+
+STREAM_FLAGS = {
+    b'stream-begin': STREAM_FLAG_BEGIN_STREAM,
+    b'stream-end': STREAM_FLAG_END_STREAM,
+    b'encoded': STREAM_FLAG_ENCODING_APPLIED,
+}
+
 FRAME_TYPE_COMMAND_NAME = 0x01
 FRAME_TYPE_COMMAND_ARGUMENT = 0x02
 FRAME_TYPE_COMMAND_DATA = 0x03
 FRAME_TYPE_BYTES_RESPONSE = 0x04
 FRAME_TYPE_ERROR_RESPONSE = 0x05
 FRAME_TYPE_TEXT_OUTPUT = 0x06
+FRAME_TYPE_STREAM_SETTINGS = 0x08
 
 FRAME_TYPES = {
     b'command-name': FRAME_TYPE_COMMAND_NAME,
     b'command-argument': FRAME_TYPE_COMMAND_ARGUMENT,
     b'command-data': FRAME_TYPE_COMMAND_DATA,
     b'bytes-response': FRAME_TYPE_BYTES_RESPONSE,
     b'error-response': FRAME_TYPE_ERROR_RESPONSE,
     b'text-output': FRAME_TYPE_TEXT_OUTPUT,
+    b'stream-settings': FRAME_TYPE_STREAM_SETTINGS,
 }
 
 FLAG_COMMAND_NAME_EOS = 0x01
 FLAG_COMMAND_NAME_HAVE_ARGS = 0x02
 FLAG_COMMAND_NAME_HAVE_DATA = 0x04
 
 FLAGS_COMMAND = {
     b'eos': FLAG_COMMAND_NAME_EOS,
     b'have-args': FLAG_COMMAND_NAME_HAVE_ARGS,
     b'have-data': FLAG_COMMAND_NAME_HAVE_DATA,
 }
 
 FLAG_COMMAND_ARGUMENT_CONTINUATION = 0x01
 FLAG_COMMAND_ARGUMENT_EOA = 0x02
 
 FLAGS_COMMAND_ARGUMENT = {
     b'continuation': FLAG_COMMAND_ARGUMENT_CONTINUATION,
     b'eoa': FLAG_COMMAND_ARGUMENT_EOA,
 }
 
 FLAG_COMMAND_DATA_CONTINUATION = 0x01
 FLAG_COMMAND_DATA_EOS = 0x02
 
 FLAGS_COMMAND_DATA = {
     b'continuation': FLAG_COMMAND_DATA_CONTINUATION,
     b'eos': FLAG_COMMAND_DATA_EOS,
 }
 
 FLAG_BYTES_RESPONSE_CONTINUATION = 0x01
 FLAG_BYTES_RESPONSE_EOS = 0x02
 
 FLAGS_BYTES_RESPONSE = {
     b'continuation': FLAG_BYTES_RESPONSE_CONTINUATION,
     b'eos': FLAG_BYTES_RESPONSE_EOS,
 }
 
 FLAG_ERROR_RESPONSE_PROTOCOL = 0x01
 FLAG_ERROR_RESPONSE_APPLICATION = 0x02
 
 FLAGS_ERROR_RESPONSE = {
     b'protocol': FLAG_ERROR_RESPONSE_PROTOCOL,
     b'application': FLAG_ERROR_RESPONSE_APPLICATION,
 }
 
 # Maps frame types to their available flags.
 FRAME_TYPE_FLAGS = {
     FRAME_TYPE_COMMAND_NAME: FLAGS_COMMAND,
     FRAME_TYPE_COMMAND_ARGUMENT: FLAGS_COMMAND_ARGUMENT,
     FRAME_TYPE_COMMAND_DATA: FLAGS_COMMAND_DATA,
     FRAME_TYPE_BYTES_RESPONSE: FLAGS_BYTES_RESPONSE,
     FRAME_TYPE_ERROR_RESPONSE: FLAGS_ERROR_RESPONSE,
     FRAME_TYPE_TEXT_OUTPUT: {},
+    FRAME_TYPE_STREAM_SETTINGS: {},
 }
 
 ARGUMENT_FRAME_HEADER = struct.Struct(r'<HH')
 
 @attr.s(slots=True)
 class frameheader(object):
     """Represents the data in a frame header."""
 
     length = attr.ib()
     requestid = attr.ib()
+    streamid = attr.ib()
+    streamflags = attr.ib()
     typeid = attr.ib()
     flags = attr.ib()
 
 @attr.s(slots=True)
 class frame(object):
     """Represents a parsed frame."""
 
     requestid = attr.ib()
+    streamid = attr.ib()
+    streamflags = attr.ib()
     typeid = attr.ib()
     flags = attr.ib()
     payload = attr.ib()
 
-def makeframe(requestid, typeid, flags, payload):
+def makeframe(requestid, streamid, streamflags, typeid, flags, payload):
     """Assemble a frame into a byte array."""
     # TODO assert size of payload.
     frame = bytearray(FRAME_HEADER_SIZE + len(payload))
 
     # 24 bits length
     # 16 bits request id
+    # 8 bits stream id
+    # 8 bits stream flags
     # 4 bits type
     # 4 bits flags
 
     l = struct.pack(r'<I', len(payload))
     frame[0:3] = l[0:3]
-    struct.pack_into(r'<H', frame, 3, requestid)
-    frame[5] = (typeid << 4) | flags
-    frame[6:] = payload
+    struct.pack_into(r'<HBB', frame, 3, requestid, streamid, streamflags)
+    frame[7] = (typeid << 4) | flags
+    frame[8:] = payload
 
     return frame
 
 def makeframefromhumanstring(s):
     """Create a frame from a human readable string
 
     Strings have the form:
 
-        <request-id> <type> <flags> <payload>
+        <request-id> <stream-id> <stream-flags> <type> <flags> <payload>
 
     This can be used by user-facing applications and tests for creating
     frames easily without having to type out a bunch of constants.
 
-    Request ID is an integer.
+    Request ID and stream IDs are integers.
 
-    Frame type and flags can be specified by integer or named constant.
+    Stream flags, frame type, and flags can be specified by integer or
+    named constant.
 
     Flags can be delimited by `|` to bitwise OR them together.
     """
-    requestid, frametype, frameflags, payload = s.split(b' ', 3)
+    fields = s.split(b' ', 5)
+    requestid, streamid, streamflags, frametype, frameflags, payload = fields
 
     requestid = int(requestid)
+    streamid = int(streamid)
+
+    finalstreamflags = 0
+    for flag in streamflags.split(b'|'):
+        if flag in STREAM_FLAGS:
+            finalstreamflags |= STREAM_FLAGS[flag]
+        else:
+            finalstreamflags |= int(flag)
 
     if frametype in FRAME_TYPES:
         frametype = FRAME_TYPES[frametype]
     else:
         frametype = int(frametype)
 
     finalflags = 0
     validflags = FRAME_TYPE_FLAGS[frametype]
     for flag in frameflags.split(b'|'):
         if flag in validflags:
             finalflags |= validflags[flag]
         else:
             finalflags |= int(flag)
 
     payload = stringutil.unescapestr(payload)
 
-    return makeframe(requestid=requestid, typeid=frametype,
+    return makeframe(requestid=requestid, streamid=streamid,
+                     streamflags=finalstreamflags, typeid=frametype,
                      flags=finalflags, payload=payload)
 
 def parseheader(data):
     """Parse a unified framing protocol frame header from a buffer.
 
     The header is expected to be in the buffer at offset 0 and the
     buffer is expected to be large enough to hold a full header.
     """
     # 24 bits payload length (little endian)
+    # 16 bits request ID
+    # 8 bits stream ID
+    # 8 bits stream flags
     # 4 bits frame type
     # 4 bits frame flags
     # ... payload
     framelength = data[0] + 256 * data[1] + 16384 * data[2]
-    requestid = struct.unpack_from(r'<H', data, 3)[0]
-    typeflags = data[5]
+    requestid, streamid, streamflags = struct.unpack_from(r'<HBB', data, 3)
+    typeflags = data[7]
 
     frametype = (typeflags & 0xf0) >> 4
     frameflags = typeflags & 0x0f
 
-    return frameheader(framelength, requestid, frametype, frameflags)
+    return frameheader(framelength, requestid, streamid, streamflags,
+                       frametype, frameflags)
 
 def readframe(fh):
     """Read a unified framing protocol frame from a file object.
 
     Returns a 3-tuple of (type, flags, payload) for the decoded frame or
     None if no frame is available. May raise if a malformed frame is
     seen.
     """
     header = bytearray(FRAME_HEADER_SIZE)
 
     readcount = fh.readinto(header)
 
     if readcount == 0:
         return None
 
     if readcount != FRAME_HEADER_SIZE:
         raise error.Abort(_('received incomplete frame: got %d bytes: %s') %
                           (readcount, header))
 
     h = parseheader(header)
 
     payload = fh.read(h.length)
     if len(payload) != h.length:
         raise error.Abort(_('frame length error: expected %d; got %d') %
                           (h.length, len(payload)))
 
-    return frame(h.requestid, h.typeid, h.flags, payload)
+    return frame(h.requestid, h.streamid, h.streamflags, h.typeid, h.flags,
+                 payload)
 
 def createcommandframes(stream, requestid, cmd, args, datafh=None):
     """Create frames necessary to transmit a request to run a command.
 
     This is a generator of bytearrays. Each item represents a frame
     ready to be sent over the wire to a peer.
     """
     flags = 0
     if args:
         flags |= FLAG_COMMAND_NAME_HAVE_ARGS
     if datafh:
         flags |= FLAG_COMMAND_NAME_HAVE_DATA
 
     if not flags:
         flags |= FLAG_COMMAND_NAME_EOS
 
     yield stream.makeframe(requestid=requestid, typeid=FRAME_TYPE_COMMAND_NAME,
                            flags=flags, payload=cmd)
 
     for i, k in enumerate(sorted(args)):
         v = args[k]
         last = i == len(args) - 1
 
         # TODO handle splitting of argument values across frames.
         payload = bytearray(ARGUMENT_FRAME_HEADER.size + len(k) + len(v))
         offset = 0
         ARGUMENT_FRAME_HEADER.pack_into(payload, offset, len(k), len(v))
         offset += ARGUMENT_FRAME_HEADER.size
         payload[offset:offset + len(k)] = k
         offset += len(k)
         payload[offset:offset + len(v)] = v
 
         flags = FLAG_COMMAND_ARGUMENT_EOA if last else 0
         yield stream.makeframe(requestid=requestid,
                                typeid=FRAME_TYPE_COMMAND_ARGUMENT,
                                flags=flags,
                                payload=payload)
 
     if datafh:
         while True:
             data = datafh.read(DEFAULT_MAX_FRAME_SIZE)
 
             done = False
             if len(data) == DEFAULT_MAX_FRAME_SIZE:
                 flags = FLAG_COMMAND_DATA_CONTINUATION
             else:
                 flags = FLAG_COMMAND_DATA_EOS
                 assert datafh.read(1) == b''
                 done = True
 
             yield stream.makeframe(requestid=requestid,
                                    typeid=FRAME_TYPE_COMMAND_DATA,
                                    flags=flags,
                                    payload=data)
 
             if done:
                 break
 
 def createbytesresponseframesfrombytes(stream, requestid, data,
                                        maxframesize=DEFAULT_MAX_FRAME_SIZE):
     """Create a raw frame to send a bytes response from static bytes input.
 
     Returns a generator of bytearrays.
     """
 
     # Simple case of a single frame.
     if len(data) <= maxframesize:
         yield stream.makeframe(requestid=requestid,
                                typeid=FRAME_TYPE_BYTES_RESPONSE,
                                flags=FLAG_BYTES_RESPONSE_EOS,
                                payload=data)
         return
 
     offset = 0
     while True:
         chunk = data[offset:offset + maxframesize]
         offset += len(chunk)
         done = offset == len(data)
 
         if done:
             flags = FLAG_BYTES_RESPONSE_EOS
         else:
             flags = FLAG_BYTES_RESPONSE_CONTINUATION
 
         yield stream.makeframe(requestid=requestid,
                                typeid=FRAME_TYPE_BYTES_RESPONSE,
                                flags=flags,
                                payload=chunk)
 
         if done:
             break
 
 def createerrorframe(stream, requestid, msg, protocol=False, application=False):
     # TODO properly handle frame size limits.
     assert len(msg) <= DEFAULT_MAX_FRAME_SIZE
 
     flags = 0
     if protocol:
         flags |= FLAG_ERROR_RESPONSE_PROTOCOL
     if application:
         flags |= FLAG_ERROR_RESPONSE_APPLICATION
 
     yield stream.makeframe(requestid=requestid,
                            typeid=FRAME_TYPE_ERROR_RESPONSE,
                            flags=flags,
                            payload=msg)
 
 def createtextoutputframe(stream, requestid, atoms):
     """Create a text output frame to render text to people.
 
     ``atoms`` is a 3-tuple of (formatting string, args, labels).
 
     The formatting string contains ``%s`` tokens to be replaced by the
     corresponding indexed entry in ``args``. ``labels`` is an iterable of
     formatters to be applied at rendering time. In terms of the ``ui``
     class, each atom corresponds to a ``ui.write()``.
     """
     bytesleft = DEFAULT_MAX_FRAME_SIZE
     atomchunks = []
 
     for (formatting, args, labels) in atoms:
         if len(args) > 255:
             raise ValueError('cannot use more than 255 formatting arguments')
         if len(labels) > 255:
             raise ValueError('cannot use more than 255 labels')
 
         # TODO look for localstr, other types here?
 
         if not isinstance(formatting, bytes):
             raise ValueError('must use bytes formatting strings')
         for arg in args:
             if not isinstance(arg, bytes):
                 raise ValueError('must use bytes for arguments')
         for label in labels:
             if not isinstance(label, bytes):
                 raise ValueError('must use bytes for labels')
 
         # Formatting string must be UTF-8.
         formatting = formatting.decode(r'utf-8', r'replace').encode(r'utf-8')
 
         # Arguments must be UTF-8.
         args = [a.decode(r'utf-8', r'replace').encode(r'utf-8') for a in args]
 
         # Labels must be ASCII.
         labels = [l.decode(r'ascii', r'strict').encode(r'ascii')
                   for l in labels]
 
         if len(formatting) > 65535:
             raise ValueError('formatting string cannot be longer than 64k')
 
         if any(len(a) > 65535 for a in args):
             raise ValueError('argument string cannot be longer than 64k')
 
         if any(len(l) > 255 for l in labels):
             raise ValueError('label string cannot be longer than 255 bytes')
 
         chunks = [
             struct.pack(r'<H', len(formatting)),
             struct.pack(r'<BB', len(labels), len(args)),
             struct.pack(r'<' + r'B' * len(labels), *map(len, labels)),
             struct.pack(r'<' + r'H' * len(args), *map(len, args)),
         ]
         chunks.append(formatting)
         chunks.extend(labels)
         chunks.extend(args)
 
         atom = b''.join(chunks)
         atomchunks.append(atom)
         bytesleft -= len(atom)
 
     if bytesleft < 0:
         raise ValueError('cannot encode data in a single frame')
 
     yield stream.makeframe(requestid=requestid,
                            typeid=FRAME_TYPE_TEXT_OUTPUT,
                            flags=0,
                            payload=b''.join(atomchunks))
 
 class stream(object):
     """Represents a logical unidirectional series of frames."""
 
+    def __init__(self, streamid, active=False):
+        self.streamid = streamid
+        self._active = False
+
     def makeframe(self, requestid, typeid, flags, payload):
         """Create a frame to be sent out over this stream.
 
         Only returns the frame instance. Does not actually send it.
         """
-        return makeframe(requestid, typeid, flags, payload)
+        streamflags = 0
+        if not self._active:
+            streamflags |= STREAM_FLAG_BEGIN_STREAM
+            self._active = True
+
+        return makeframe(requestid, self.streamid, streamflags, typeid, flags,
+                         payload)
+
+def ensureserverstream(stream):
+    if stream.streamid % 2:
+        raise error.ProgrammingError('server should only write to even '
+                                     'numbered streams; %d is not even' %
+                                     stream.streamid)
 
 class serverreactor(object):
     """Holds state of a server handling frame-based protocol requests.
 
     This class is the "brain" of the unified frame-based protocol server
     component. While the protocol is stateless from the perspective of
     requests/commands, something needs to track which frames have been
     received, what frames to expect, etc. This class is that thing.
 
     Instances are modeled as a state machine of sorts. Instances are also
     reactionary to external events. The point of this class is to encapsulate
     the state of the connection and the exchange of frames, not to perform
     work. Instead, callers tell this class when something occurs, like a
     frame arriving. If that activity is worthy of a follow-up action (say
     *run a command*), the return value of that handler will say so.
 
     I/O and CPU intensive operations are purposefully delegated outside of
     this class.
 
     Consumers are expected to tell instances when events occur. They do so by
     calling the various ``on*`` methods. These methods return a 2-tuple
     describing any follow-up action(s) to take. The first element is the
     name of an action to perform. The second is a data structure (usually
     a dict) specific to that action that contains more information. e.g.
     if the server wants to send frames back to the client, the data structure
     will contain a reference to those frames.
 
     Valid actions that consumers can be instructed to take are:
 
     sendframes
        Indicates that frames should be sent to the client. The ``framegen``
        key contains a generator of frames that should be sent. The server
        assumes that all frames are sent to the client.
 
     error
        Indicates that an error occurred. Consumer should probably abort.
 
     runcommand
        Indicates that the consumer should run a wire protocol command. Details
        of the command to run are given in the data structure.
 
     wantframe
        Indicates that nothing of interest happened and the server is waiting on
        more frames from the client before anything interesting can be done.
 
     noop
        Indicates no additional action is required.
 
     Known Issues
     ------------
 
     There are no limits to the number of partially received commands or their
     size. A malicious client could stream command request data and exhaust the
     server's memory.
 
     Partially received commands are not acted upon when end of input is
     reached. Should the server error if it receives a partial request?
     Should the client send a message to abort a partially transmitted request
     to facilitate graceful shutdown?
 
     Active requests that haven't been responded to aren't tracked. This means
     that if we receive a command and instruct its dispatch, another command
     with its request ID can come in over the wire and there will be a race
     between who responds to what.
     """
 
     def __init__(self, deferoutput=False):
         """Construct a new server reactor.
 
         ``deferoutput`` can be used to indicate that no output frames should be
         instructed to be sent until input has been exhausted. In this mode,
         events that would normally generate output frames (such as a command
         response being ready) will instead defer instructing the consumer to
         send those frames. This is useful for half-duplex transports where the
         sender cannot receive until all data has been transmitted.
         """
         self._deferoutput = deferoutput
         self._state = 'idle'
         self._bufferedframegens = []
+        # stream id -> stream instance for all active streams from the client.
+        self._incomingstreams = {}
         # request id -> dict of commands that are actively being received.
         self._receivingcommands = {}
         # Request IDs that have been received and are actively being processed.
         # Once all output for a request has been sent, it is removed from this
         # set.
         self._activecommands = set()
 
     def onframerecv(self, frame):
         """Process a frame that has been received off the wire.
 
         Returns a dict with an ``action`` key that details what action,
         if any, the consumer should take next.
         """
+        if not frame.streamid % 2:
+            self._state = 'errored'
+            return self._makeerrorresult(
+                _('received frame with even numbered stream ID: %d') %
+                  frame.streamid)
+
+        if frame.streamid not in self._incomingstreams:
+            if not frame.streamflags & STREAM_FLAG_BEGIN_STREAM:
+                self._state = 'errored'
+                return self._makeerrorresult(
+                    _('received frame on unknown inactive stream without '
+                      'beginning of stream flag set'))
+
+            self._incomingstreams[frame.streamid] = stream(frame.streamid)
+
+        if frame.streamflags & STREAM_FLAG_ENCODING_APPLIED:
+            # TODO handle decoding frames
+            self._state = 'errored'
+            raise error.ProgrammingError('support for decoding stream payloads '
+                                         'not yet implemented')
+
+        if frame.streamflags & STREAM_FLAG_END_STREAM:
+            del self._incomingstreams[frame.streamid]
+
         handlers = {
             'idle': self._onframeidle,
             'command-receiving': self._onframecommandreceiving,
             'errored': self._onframeerrored,
         }
 
         meth = handlers.get(self._state)
         if not meth:
             raise error.ProgrammingError('unhandled state: %s' % self._state)
 
         return meth(frame)
 
     def onbytesresponseready(self, stream, requestid, data):
         """Signal that a bytes response is ready to be sent to the client.
 
         The raw bytes response is passed as an argument.
         """
+        ensureserverstream(stream)
+
         def sendframes():
             for frame in createbytesresponseframesfrombytes(stream, requestid,
                                                             data):
                 yield frame
 
             self._activecommands.remove(requestid)
 
         result = sendframes()
 
         if self._deferoutput:
             self._bufferedframegens.append(result)
             return 'noop', {}
         else:
             return 'sendframes', {
                 'framegen': result,
             }
 
     def oninputeof(self):
         """Signals that end of input has been received.
 
         No more frames will be received. All pending activity should be
         completed.
         """
         # TODO should we do anything about in-flight commands?
 
         if not self._deferoutput or not self._bufferedframegens:
             return 'noop', {}
 
         # If we buffered all our responses, emit those.
         def makegen():
             for gen in self._bufferedframegens:
                 for frame in gen:
                     yield frame
 
         return 'sendframes', {
             'framegen': makegen(),
         }
 
     def onapplicationerror(self, stream, requestid, msg):
+        ensureserverstream(stream)
+
         return 'sendframes', {
             'framegen': createerrorframe(stream, requestid, msg,
                                          application=True),
         }
 
     def _makeerrorresult(self, msg):
         return 'error', {
             'message': msg,
         }
 
     def _makeruncommandresult(self, requestid):
         entry = self._receivingcommands[requestid]
         del self._receivingcommands[requestid]
 
         if self._receivingcommands:
             self._state = 'command-receiving'
         else:
             self._state = 'idle'
 
         assert requestid not in self._activecommands
         self._activecommands.add(requestid)
 
         return 'runcommand', {
             'requestid': requestid,
             'command': entry['command'],
             'args': entry['args'],
             'data': entry['data'].getvalue() if entry['data'] else None,
         }
 
     def _makewantframeresult(self):
         return 'wantframe', {
             'state': self._state,
         }
 
     def _onframeidle(self, frame):
         # The only frame type that should be received in this state is a
         # command request.
         if frame.typeid != FRAME_TYPE_COMMAND_NAME:
             self._state = 'errored'
             return self._makeerrorresult(
                 _('expected command frame; got %d') % frame.typeid)
 
         if frame.requestid in self._receivingcommands:
             self._state = 'errored'
             return self._makeerrorresult(
                 _('request with ID %d already received') % frame.requestid)
 
         if frame.requestid in self._activecommands:
             self._state = 'errored'
             return self._makeerrorresult((
                 _('request with ID %d is already active') % frame.requestid))
 
         expectingargs = bool(frame.flags & FLAG_COMMAND_NAME_HAVE_ARGS)
         expectingdata = bool(frame.flags & FLAG_COMMAND_NAME_HAVE_DATA)
 
         self._receivingcommands[frame.requestid] = {
             'command': frame.payload,
             'args': {},
             'data': None,
             'expectingargs': expectingargs,
             'expectingdata': expectingdata,
         }
 
         if frame.flags & FLAG_COMMAND_NAME_EOS:
             return self._makeruncommandresult(frame.requestid)
 
         if expectingargs or expectingdata:
             self._state = 'command-receiving'
             return self._makewantframeresult()
         else:
             self._state = 'errored'
             return self._makeerrorresult(_('missing frame flags on '
                                            'command frame'))
 
     def _onframecommandreceiving(self, frame):
         # It could be a new command request. Process it as such.
         if frame.typeid == FRAME_TYPE_COMMAND_NAME:
             return self._onframeidle(frame)
 
         # All other frames should be related to a command that is currently
         # receiving but is not active.
         if frame.requestid in self._activecommands:
             self._state = 'errored'
             return self._makeerrorresult(
                 _('received frame for request that is still active: %d') %
                 frame.requestid)
 
         if frame.requestid not in self._receivingcommands:
             self._state = 'errored'
             return self._makeerrorresult(
                 _('received frame for request that is not receiving: %d') %
                   frame.requestid)
 
         entry = self._receivingcommands[frame.requestid]
 
         if frame.typeid == FRAME_TYPE_COMMAND_ARGUMENT:
             if not entry['expectingargs']:
                 self._state = 'errored'
                 return self._makeerrorresult(_(
                     'received command argument frame for request that is not '
                     'expecting arguments: %d') % frame.requestid)
 
             return self._handlecommandargsframe(frame, entry)
 
         elif frame.typeid == FRAME_TYPE_COMMAND_DATA:
             if not entry['expectingdata']:
                 self._state = 'errored'
                 return self._makeerrorresult(_(
                     'received command data frame for request that is not '
                     'expecting data: %d') % frame.requestid)
 
             if entry['data'] is None:
                 entry['data'] = util.bytesio()
 
             return self._handlecommanddataframe(frame, entry)
 
     def _handlecommandargsframe(self, frame, entry):
         # The frame and state of command should have already been validated.
         assert frame.typeid == FRAME_TYPE_COMMAND_ARGUMENT
 
         offset = 0
         namesize, valuesize = ARGUMENT_FRAME_HEADER.unpack_from(frame.payload)
         offset += ARGUMENT_FRAME_HEADER.size
 
         # The argument name MUST fit inside the frame.
         argname = bytes(frame.payload[offset:offset + namesize])
         offset += namesize
 
         if len(argname) != namesize:
             self._state = 'errored'
             return self._makeerrorresult(_('malformed argument frame: '
                                            'partial argument name'))
 
         argvalue = bytes(frame.payload[offset:])
 
         # Argument value spans multiple frames. Record our active state
         # and wait for the next frame.
         if frame.flags & FLAG_COMMAND_ARGUMENT_CONTINUATION:
             raise error.ProgrammingError('not yet implemented')
 
         # Common case: the argument value is completely contained in this
         # frame.
 
         if len(argvalue) != valuesize:
             self._state = 'errored'
             return self._makeerrorresult(_('malformed argument frame: '
                                            'partial argument value'))
 
         entry['args'][argname] = argvalue
 
         if frame.flags & FLAG_COMMAND_ARGUMENT_EOA:
             if entry['expectingdata']:
                 # TODO signal request to run a command once we don't
                 # buffer data frames.
                 return self._makewantframeresult()
             else:
                 return self._makeruncommandresult(frame.requestid)
         else:
             return self._makewantframeresult()
 
     def _handlecommanddataframe(self, frame, entry):
         assert frame.typeid == FRAME_TYPE_COMMAND_DATA
 
         # TODO support streaming data instead of buffering it.
         entry['data'].write(frame.payload)
 
         if frame.flags & FLAG_COMMAND_DATA_CONTINUATION:
             return self._makewantframeresult()
         elif frame.flags & FLAG_COMMAND_DATA_EOS:
             entry['data'].seek(0)
             return self._makeruncommandresult(frame.requestid)
         else:
             self._state = 'errored'
             return self._makeerrorresult(_('command data frame without '
                                            'flags'))
 
     def _onframeerrored(self, frame):
         return self._makeerrorresult(_('server already errored'))

mercurial/wireprotoserver.py

@@ -1,1049 +1,1049 b''
 # Copyright 21 May 2005 - (c) 2005 Jake Edge <[e-mail]>
 # Copyright 2005-2007 Matt Mackall <[e-mail]>
 #
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
 from __future__ import absolute_import
 
 import contextlib
 import struct
 import sys
 import threading
 
 from .i18n import _
 from . import (
     encoding,
     error,
     hook,
     pycompat,
     util,
     wireproto,
     wireprotoframing,
     wireprototypes,
 )
 from .utils import (
     procutil,
 )
 
 stringio = util.stringio
 
 urlerr = util.urlerr
 urlreq = util.urlreq
 
 HTTP_OK = 200
 
 HGTYPE = 'application/mercurial-0.1'
 HGTYPE2 = 'application/mercurial-0.2'
 HGERRTYPE = 'application/hg-error'
 FRAMINGTYPE = b'application/mercurial-exp-framing-0002'
 
 HTTPV2 = wireprototypes.HTTPV2
 SSHV1 = wireprototypes.SSHV1
 SSHV2 = wireprototypes.SSHV2
 
 def decodevaluefromheaders(req, headerprefix):
     """Decode a long value from multiple HTTP request headers.
 
     Returns the value as a bytes, not a str.
     """
     chunks = []
     i = 1
     while True:
         v = req.headers.get(b'%s-%d' % (headerprefix, i))
         if v is None:
             break
         chunks.append(pycompat.bytesurl(v))
         i += 1
 
     return ''.join(chunks)
 
 class httpv1protocolhandler(wireprototypes.baseprotocolhandler):
     def __init__(self, req, ui, checkperm):
         self._req = req
         self._ui = ui
         self._checkperm = checkperm
 
     @property
     def name(self):
         return 'http-v1'
 
     def getargs(self, args):
         knownargs = self._args()
         data = {}
         keys = args.split()
         for k in keys:
             if k == '*':
                 star = {}
                 for key in knownargs.keys():
                     if key != 'cmd' and key not in keys:
                         star[key] = knownargs[key][0]
                 data['*'] = star
             else:
                 data[k] = knownargs[k][0]
         return [data[k] for k in keys]
 
     def _args(self):
         args = self._req.qsparams.asdictoflists()
         postlen = int(self._req.headers.get(b'X-HgArgs-Post', 0))
         if postlen:
             args.update(urlreq.parseqs(
                 self._req.bodyfh.read(postlen), keep_blank_values=True))
             return args
 
         argvalue = decodevaluefromheaders(self._req, b'X-HgArg')
         args.update(urlreq.parseqs(argvalue, keep_blank_values=True))
         return args
 
     def forwardpayload(self, fp):
         # Existing clients *always* send Content-Length.
         length = int(self._req.headers[b'Content-Length'])
 
         # If httppostargs is used, we need to read Content-Length
         # minus the amount that was consumed by args.
         length -= int(self._req.headers.get(b'X-HgArgs-Post', 0))
         for s in util.filechunkiter(self._req.bodyfh, limit=length):
             fp.write(s)
 
     @contextlib.contextmanager
     def mayberedirectstdio(self):
         oldout = self._ui.fout
         olderr = self._ui.ferr
 
         out = util.stringio()
 
         try:
             self._ui.fout = out
             self._ui.ferr = out
             yield out
         finally:
             self._ui.fout = oldout
             self._ui.ferr = olderr
 
     def client(self):
         return 'remote:%s:%s:%s' % (
             self._req.urlscheme,
             urlreq.quote(self._req.remotehost or ''),
             urlreq.quote(self._req.remoteuser or ''))
 
     def addcapabilities(self, repo, caps):
         caps.append(b'batch')
 
         caps.append('httpheader=%d' %
                     repo.ui.configint('server', 'maxhttpheaderlen'))
         if repo.ui.configbool('experimental', 'httppostargs'):
             caps.append('httppostargs')
 
         # FUTURE advertise 0.2rx once support is implemented
         # FUTURE advertise minrx and mintx after consulting config option
         caps.append('httpmediatype=0.1rx,0.1tx,0.2tx')
 
         compengines = wireproto.supportedcompengines(repo.ui, util.SERVERROLE)
         if compengines:
             comptypes = ','.join(urlreq.quote(e.wireprotosupport().name)
                                  for e in compengines)
             caps.append('compression=%s' % comptypes)
 
         return caps
 
     def checkperm(self, perm):
         return self._checkperm(perm)
 
 # This method exists mostly so that extensions like remotefilelog can
 # disable a kludgey legacy method only over http. As of early 2018,
 # there are no other known users, so with any luck we can discard this
 # hook if remotefilelog becomes a first-party extension.
 def iscmd(cmd):
     return cmd in wireproto.commands
 
 def handlewsgirequest(rctx, req, res, checkperm):
     """Possibly process a wire protocol request.
 
     If the current request is a wire protocol request, the request is
     processed by this function.
 
     ``req`` is a ``parsedrequest`` instance.
     ``res`` is a ``wsgiresponse`` instance.
 
     Returns a bool indicating if the request was serviced. If set, the caller
     should stop processing the request, as a response has already been issued.
     """
     # Avoid cycle involving hg module.
     from .hgweb import common as hgwebcommon
 
     repo = rctx.repo
 
     # HTTP version 1 wire protocol requests are denoted by a "cmd" query
     # string parameter. If it isn't present, this isn't a wire protocol
     # request.
     if 'cmd' not in req.qsparams:
         return False
 
     cmd = req.qsparams['cmd']
 
     # The "cmd" request parameter is used by both the wire protocol and hgweb.
     # While not all wire protocol commands are available for all transports,
     # if we see a "cmd" value that resembles a known wire protocol command, we
     # route it to a protocol handler. This is better than routing possible
     # wire protocol requests to hgweb because it prevents hgweb from using
     # known wire protocol commands and it is less confusing for machine
     # clients.
     if not iscmd(cmd):
         return False
 
     # The "cmd" query string argument is only valid on the root path of the
     # repo. e.g. ``/?cmd=foo``, ``/repo?cmd=foo``. URL paths within the repo
     # like ``/blah?cmd=foo`` are not allowed. So don't recognize the request
     # in this case. We send an HTTP 404 for backwards compatibility reasons.
     if req.dispatchpath:
         res.status = hgwebcommon.statusmessage(404)
         res.headers['Content-Type'] = HGTYPE
         # TODO This is not a good response to issue for this request. This
         # is mostly for BC for now.
         res.setbodybytes('0\n%s\n' % b'Not Found')
         return True
 
     proto = httpv1protocolhandler(req, repo.ui,
                                   lambda perm: checkperm(rctx, req, perm))
 
     # The permissions checker should be the only thing that can raise an
     # ErrorResponse. It is kind of a layer violation to catch an hgweb
     # exception here. So consider refactoring into a exception type that
     # is associated with the wire protocol.
     try:
         _callhttp(repo, req, res, proto, cmd)
     except hgwebcommon.ErrorResponse as e:
         for k, v in e.headers:
             res.headers[k] = v
         res.status = hgwebcommon.statusmessage(e.code, pycompat.bytestr(e))
         # TODO This response body assumes the failed command was
         # "unbundle." That assumption is not always valid.
         res.setbodybytes('0\n%s\n' % pycompat.bytestr(e))
 
     return True
 
 def handlewsgiapirequest(rctx, req, res, checkperm):
     """Handle requests to /api/*."""
     assert req.dispatchparts[0] == b'api'
 
     repo = rctx.repo
 
     # This whole URL space is experimental for now. But we want to
     # reserve the URL space. So, 404 all URLs if the feature isn't enabled.
     if not repo.ui.configbool('experimental', 'web.apiserver'):
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('Experimental API server endpoint not enabled'))
         return
 
     # The URL space is /api/<protocol>/*. The structure of URLs under varies
     # by <protocol>.
 
     # Registered APIs are made available via config options of the name of
     # the protocol.
     availableapis = set()
     for k, v in API_HANDLERS.items():
         section, option = v['config']
         if repo.ui.configbool(section, option):
             availableapis.add(k)
 
     # Requests to /api/ list available APIs.
     if req.dispatchparts == [b'api']:
         res.status = b'200 OK'
         res.headers[b'Content-Type'] = b'text/plain'
         lines = [_('APIs can be accessed at /api/<name>, where <name> can be '
                    'one of the following:\n')]
         if availableapis:
             lines.extend(sorted(availableapis))
         else:
             lines.append(_('(no available APIs)\n'))
         res.setbodybytes(b'\n'.join(lines))
         return
 
     proto = req.dispatchparts[1]
 
     if proto not in API_HANDLERS:
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('Unknown API: %s\nKnown APIs: %s') % (
             proto, b', '.join(sorted(availableapis))))
         return
 
     if proto not in availableapis:
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('API %s not enabled\n') % proto)
         return
 
     API_HANDLERS[proto]['handler'](rctx, req, res, checkperm,
                                    req.dispatchparts[2:])
 
 def _handlehttpv2request(rctx, req, res, checkperm, urlparts):
     from .hgweb import common as hgwebcommon
 
     # URL space looks like: <permissions>/<command>, where <permission> can
     # be ``ro`` or ``rw`` to signal read-only or read-write, respectively.
 
     # Root URL does nothing meaningful... yet.
     if not urlparts:
         res.status = b'200 OK'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('HTTP version 2 API handler'))
         return
 
     if len(urlparts) == 1:
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('do not know how to process %s\n') %
                          req.dispatchpath)
         return
 
     permission, command = urlparts[0:2]
 
     if permission not in (b'ro', b'rw'):
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('unknown permission: %s') % permission)
         return
 
     if req.method != 'POST':
         res.status = b'405 Method Not Allowed'
         res.headers[b'Allow'] = b'POST'
         res.setbodybytes(_('commands require POST requests'))
         return
 
     # At some point we'll want to use our own API instead of recycling the
     # behavior of version 1 of the wire protocol...
     # TODO return reasonable responses - not responses that overload the
     # HTTP status line message for error reporting.
     try:
         checkperm(rctx, req, 'pull' if permission == b'ro' else 'push')
     except hgwebcommon.ErrorResponse as e:
         res.status = hgwebcommon.statusmessage(e.code, pycompat.bytestr(e))
         for k, v in e.headers:
             res.headers[k] = v
         res.setbodybytes('permission denied')
         return
 
     # We have a special endpoint to reflect the request back at the client.
     if command == b'debugreflect':
         _processhttpv2reflectrequest(rctx.repo.ui, rctx.repo, req, res)
         return
 
     # Extra commands that we handle that aren't really wire protocol
     # commands. Think extra hard before making this hackery available to
     # extension.
     extracommands = {'multirequest'}
 
     if command not in wireproto.commands and command not in extracommands:
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('unknown wire protocol command: %s\n') % command)
         return
 
     repo = rctx.repo
     ui = repo.ui
 
     proto = httpv2protocolhandler(req, ui)
 
     if (not wireproto.commands.commandavailable(command, proto)
         and command not in extracommands):
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('invalid wire protocol command: %s') % command)
         return
 
     # TODO consider cases where proxies may add additional Accept headers.
     if req.headers.get(b'Accept') != FRAMINGTYPE:
         res.status = b'406 Not Acceptable'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('client MUST specify Accept header with value: %s\n')
                            % FRAMINGTYPE)
         return
 
     if req.headers.get(b'Content-Type') != FRAMINGTYPE:
         res.status = b'415 Unsupported Media Type'
         # TODO we should send a response with appropriate media type,
         # since client does Accept it.
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('client MUST send Content-Type header with '
                            'value: %s\n') % FRAMINGTYPE)
         return
 
     _processhttpv2request(ui, repo, req, res, permission, command, proto)
 
 def _processhttpv2reflectrequest(ui, repo, req, res):
     """Reads unified frame protocol request and dumps out state to client.
 
     This special endpoint can be used to help debug the wire protocol.
 
     Instead of routing the request through the normal dispatch mechanism,
     we instead read all frames, decode them, and feed them into our state
     tracker. We then dump the log of all that activity back out to the
     client.
     """
     import json
 
     # Reflection APIs have a history of being abused, accidentally disclosing
     # sensitive data, etc. So we have a config knob.
     if not ui.configbool('experimental', 'web.api.debugreflect'):
         res.status = b'404 Not Found'
         res.headers[b'Content-Type'] = b'text/plain'
         res.setbodybytes(_('debugreflect service not available'))
         return
 
     # We assume we have a unified framing protocol request body.
 
     reactor = wireprotoframing.serverreactor()
     states = []
 
     while True:
         frame = wireprotoframing.readframe(req.bodyfh)
 
         if not frame:
             states.append(b'received: <no frame>')
             break
 
         states.append(b'received: %d %d %d %s' % (frame.typeid, frame.flags,
                                                   frame.requestid,
                                                   frame.payload))
 
         action, meta = reactor.onframerecv(frame)
         states.append(json.dumps((action, meta), sort_keys=True,
                                  separators=(', ', ': ')))
 
     action, meta = reactor.oninputeof()
     meta['action'] = action
     states.append(json.dumps(meta, sort_keys=True, separators=(', ',': ')))
 
     res.status = b'200 OK'
     res.headers[b'Content-Type'] = b'text/plain'
     res.setbodybytes(b'\n'.join(states))
 
 def _processhttpv2request(ui, repo, req, res, authedperm, reqcommand, proto):
     """Post-validation handler for HTTPv2 requests.
 
     Called when the HTTP request contains unified frame-based protocol
     frames for evaluation.
     """
     # TODO Some HTTP clients are full duplex and can receive data before
     # the entire request is transmitted. Figure out a way to indicate support
     # for that so we can opt into full duplex mode.
     reactor = wireprotoframing.serverreactor(deferoutput=True)
     seencommand = False
 
     while True:
         frame = wireprotoframing.readframe(req.bodyfh)
         if not frame:
             break
 
         action, meta = reactor.onframerecv(frame)
 
         if action == 'wantframe':
             # Need more data before we can do anything.
             continue
         elif action == 'runcommand':
             sentoutput = _httpv2runcommand(ui, repo, req, res, authedperm,
                                            reqcommand, reactor, meta,
                                            issubsequent=seencommand)
 
             if sentoutput:
                 return
 
             seencommand = True
 
         elif action == 'error':
             # TODO define proper error mechanism.
             res.status = b'200 OK'
             res.headers[b'Content-Type'] = b'text/plain'
             res.setbodybytes(meta['message'] + b'\n')
             return
         else:
             raise error.ProgrammingError(
                 'unhandled action from frame processor: %s' % action)
 
     action, meta = reactor.oninputeof()
     if action == 'sendframes':
         # We assume we haven't started sending the response yet. If we're
         # wrong, the response type will raise an exception.
         res.status = b'200 OK'
         res.headers[b'Content-Type'] = FRAMINGTYPE
         res.setbodygen(meta['framegen'])
     elif action == 'noop':
         pass
     else:
         raise error.ProgrammingError('unhandled action from frame processor: %s'
                                      % action)
 
 def _httpv2runcommand(ui, repo, req, res, authedperm, reqcommand, reactor,
                       command, issubsequent):
     """Dispatch a wire protocol command made from HTTPv2 requests.
 
     The authenticated permission (``authedperm``) along with the original
     command from the URL (``reqcommand``) are passed in.
     """
     # We already validated that the session has permissions to perform the
     # actions in ``authedperm``. In the unified frame protocol, the canonical
     # command to run is expressed in a frame. However, the URL also requested
     # to run a specific command. We need to be careful that the command we
     # run doesn't have permissions requirements greater than what was granted
     # by ``authedperm``.
     #
     # Our rule for this is we only allow one command per HTTP request and
     # that command must match the command in the URL. However, we make
     # an exception for the ``multirequest`` URL. This URL is allowed to
     # execute multiple commands. We double check permissions of each command
     # as it is invoked to ensure there is no privilege escalation.
     # TODO consider allowing multiple commands to regular command URLs
     # iff each command is the same.
 
     proto = httpv2protocolhandler(req, ui, args=command['args'])
 
     if reqcommand == b'multirequest':
         if not wireproto.commands.commandavailable(command['command'], proto):
             # TODO proper error mechanism
             res.status = b'200 OK'
             res.headers[b'Content-Type'] = b'text/plain'
             res.setbodybytes(_('wire protocol command not available: %s') %
                              command['command'])
             return True
 
         # TODO don't use assert here, since it may be elided by -O.
         assert authedperm in (b'ro', b'rw')
         wirecommand = wireproto.commands[command['command']]
         assert wirecommand.permission in ('push', 'pull')
 
         if authedperm == b'ro' and wirecommand.permission != 'pull':
             # TODO proper error mechanism
             res.status = b'403 Forbidden'
             res.headers[b'Content-Type'] = b'text/plain'
             res.setbodybytes(_('insufficient permissions to execute '
                                'command: %s') % command['command'])
             return True
 
         # TODO should we also call checkperm() here? Maybe not if we're going
         # to overhaul that API. The granted scope from the URL check should
         # be good enough.
 
     else:
         # Don't allow multiple commands outside of ``multirequest`` URL.
         if issubsequent:
             # TODO proper error mechanism
             res.status = b'200 OK'
             res.headers[b'Content-Type'] = b'text/plain'
             res.setbodybytes(_('multiple commands cannot be issued to this '
                                'URL'))
             return True
 
         if reqcommand != command['command']:
             # TODO define proper error mechanism
             res.status = b'200 OK'
             res.headers[b'Content-Type'] = b'text/plain'
             res.setbodybytes(_('command in frame must match command in URL'))
             return True
 
     rsp = wireproto.dispatch(repo, proto, command['command'])
 
     res.status = b'200 OK'
     res.headers[b'Content-Type'] = FRAMINGTYPE
-    stream = wireprotoframing.stream()
+    stream = wireprotoframing.stream(2)
 
     if isinstance(rsp, wireprototypes.bytesresponse):
         action, meta = reactor.onbytesresponseready(stream,
                                                     command['requestid'],
                                                     rsp.data)
     else:
         action, meta = reactor.onapplicationerror(
             _('unhandled response type from wire proto command'))
 
     if action == 'sendframes':
         res.setbodygen(meta['framegen'])
         return True
     elif action == 'noop':
         return False
     else:
         raise error.ProgrammingError('unhandled event from reactor: %s' %
                                      action)
 
 # Maps API name to metadata so custom API can be registered.
 API_HANDLERS = {
     HTTPV2: {
         'config': ('experimental', 'web.api.http-v2'),
         'handler': _handlehttpv2request,
     },
 }
 
 class httpv2protocolhandler(wireprototypes.baseprotocolhandler):
     def __init__(self, req, ui, args=None):
         self._req = req
         self._ui = ui
         self._args = args
 
     @property
     def name(self):
         return HTTPV2
 
     def getargs(self, args):
         data = {}
         for k in args.split():
             if k == '*':
                 raise NotImplementedError('do not support * args')
             else:
                 data[k] = self._args[k]
 
         return [data[k] for k in args.split()]
 
     def forwardpayload(self, fp):
         raise NotImplementedError
 
     @contextlib.contextmanager
     def mayberedirectstdio(self):
         raise NotImplementedError
 
     def client(self):
         raise NotImplementedError
 
     def addcapabilities(self, repo, caps):
         return caps
 
     def checkperm(self, perm):
         raise NotImplementedError
 
 def _httpresponsetype(ui, req, prefer_uncompressed):
     """Determine the appropriate response type and compression settings.
 
     Returns a tuple of (mediatype, compengine, engineopts).
     """
     # Determine the response media type and compression engine based
     # on the request parameters.
     protocaps = decodevaluefromheaders(req, 'X-HgProto').split(' ')
 
     if '0.2' in protocaps:
         # All clients are expected to support uncompressed data.
         if prefer_uncompressed:
             return HGTYPE2, util._noopengine(), {}
 
         # Default as defined by wire protocol spec.
         compformats = ['zlib', 'none']
         for cap in protocaps:
             if cap.startswith('comp='):
                 compformats = cap[5:].split(',')
                 break
 
         # Now find an agreed upon compression format.
         for engine in wireproto.supportedcompengines(ui, util.SERVERROLE):
             if engine.wireprotosupport().name in compformats:
                 opts = {}
                 level = ui.configint('server', '%slevel' % engine.name())
                 if level is not None:
                     opts['level'] = level
 
                 return HGTYPE2, engine, opts
 
         # No mutually supported compression format. Fall back to the
         # legacy protocol.
 
     # Don't allow untrusted settings because disabling compression or
     # setting a very high compression level could lead to flooding
     # the server's network or CPU.
     opts = {'level': ui.configint('server', 'zliblevel')}
     return HGTYPE, util.compengines['zlib'], opts
 
 def _callhttp(repo, req, res, proto, cmd):
     # Avoid cycle involving hg module.
     from .hgweb import common as hgwebcommon
 
     def genversion2(gen, engine, engineopts):
         # application/mercurial-0.2 always sends a payload header
         # identifying the compression engine.
         name = engine.wireprotosupport().name
         assert 0 < len(name) < 256
         yield struct.pack('B', len(name))
         yield name
 
         for chunk in gen:
             yield chunk
 
     def setresponse(code, contenttype, bodybytes=None, bodygen=None):
         if code == HTTP_OK:
             res.status = '200 Script output follows'
         else:
             res.status = hgwebcommon.statusmessage(code)
 
         res.headers['Content-Type'] = contenttype
 
         if bodybytes is not None:
             res.setbodybytes(bodybytes)
         if bodygen is not None:
             res.setbodygen(bodygen)
 
     if not wireproto.commands.commandavailable(cmd, proto):
         setresponse(HTTP_OK, HGERRTYPE,
                     _('requested wire protocol command is not available over '
                       'HTTP'))
         return
 
     proto.checkperm(wireproto.commands[cmd].permission)
 
     rsp = wireproto.dispatch(repo, proto, cmd)
 
     if isinstance(rsp, bytes):
         setresponse(HTTP_OK, HGTYPE, bodybytes=rsp)
     elif isinstance(rsp, wireprototypes.bytesresponse):
         setresponse(HTTP_OK, HGTYPE, bodybytes=rsp.data)
     elif isinstance(rsp, wireprototypes.streamreslegacy):
         setresponse(HTTP_OK, HGTYPE, bodygen=rsp.gen)
     elif isinstance(rsp, wireprototypes.streamres):
         gen = rsp.gen
 
         # This code for compression should not be streamres specific. It
         # is here because we only compress streamres at the moment.
         mediatype, engine, engineopts = _httpresponsetype(
             repo.ui, req, rsp.prefer_uncompressed)
         gen = engine.compressstream(gen, engineopts)
 
         if mediatype == HGTYPE2:
             gen = genversion2(gen, engine, engineopts)
 
         setresponse(HTTP_OK, mediatype, bodygen=gen)
     elif isinstance(rsp, wireprototypes.pushres):
         rsp = '%d\n%s' % (rsp.res, rsp.output)
         setresponse(HTTP_OK, HGTYPE, bodybytes=rsp)
     elif isinstance(rsp, wireprototypes.pusherr):
         rsp = '0\n%s\n' % rsp.res
         res.drain = True
         setresponse(HTTP_OK, HGTYPE, bodybytes=rsp)
     elif isinstance(rsp, wireprototypes.ooberror):
         setresponse(HTTP_OK, HGERRTYPE, bodybytes=rsp.message)
     else:
         raise error.ProgrammingError('hgweb.protocol internal failure', rsp)
 
 def _sshv1respondbytes(fout, value):
     """Send a bytes response for protocol version 1."""
     fout.write('%d\n' % len(value))
     fout.write(value)
     fout.flush()
 
 def _sshv1respondstream(fout, source):
     write = fout.write
     for chunk in source.gen:
         write(chunk)
     fout.flush()
 
 def _sshv1respondooberror(fout, ferr, rsp):
     ferr.write(b'%s\n-\n' % rsp)
     ferr.flush()
     fout.write(b'\n')
     fout.flush()
 
 class sshv1protocolhandler(wireprototypes.baseprotocolhandler):
     """Handler for requests services via version 1 of SSH protocol."""
     def __init__(self, ui, fin, fout):
         self._ui = ui
         self._fin = fin
         self._fout = fout
 
     @property
     def name(self):
         return wireprototypes.SSHV1
 
     def getargs(self, args):
         data = {}
         keys = args.split()
         for n in xrange(len(keys)):
             argline = self._fin.readline()[:-1]
             arg, l = argline.split()
             if arg not in keys:
                 raise error.Abort(_("unexpected parameter %r") % arg)
             if arg == '*':
                 star = {}
                 for k in xrange(int(l)):
                     argline = self._fin.readline()[:-1]
                     arg, l = argline.split()
                     val = self._fin.read(int(l))
                     star[arg] = val
                 data['*'] = star
             else:
                 val = self._fin.read(int(l))
                 data[arg] = val
         return [data[k] for k in keys]
 
     def forwardpayload(self, fpout):
         # We initially send an empty response. This tells the client it is
         # OK to start sending data. If a client sees any other response, it
         # interprets it as an error.
         _sshv1respondbytes(self._fout, b'')
 
         # The file is in the form:
         #
         # <chunk size>\n<chunk>
         # ...
         # 0\n
         count = int(self._fin.readline())
         while count:
             fpout.write(self._fin.read(count))
             count = int(self._fin.readline())
 
     @contextlib.contextmanager
     def mayberedirectstdio(self):
         yield None
 
     def client(self):
         client = encoding.environ.get('SSH_CLIENT', '').split(' ', 1)[0]
         return 'remote:ssh:' + client
 
     def addcapabilities(self, repo, caps):
         caps.append(b'batch')
         return caps
 
     def checkperm(self, perm):
         pass
 
 class sshv2protocolhandler(sshv1protocolhandler):
     """Protocol handler for version 2 of the SSH protocol."""
 
     @property
     def name(self):
         return wireprototypes.SSHV2
 
 def _runsshserver(ui, repo, fin, fout, ev):
     # This function operates like a state machine of sorts. The following
     # states are defined:
     #
     # protov1-serving
     #    Server is in protocol version 1 serving mode. Commands arrive on
     #    new lines. These commands are processed in this state, one command
     #    after the other.
     #
     # protov2-serving
     #    Server is in protocol version 2 serving mode.
     #
     # upgrade-initial
     #    The server is going to process an upgrade request.
     #
     # upgrade-v2-filter-legacy-handshake
     #    The protocol is being upgraded to version 2. The server is expecting
     #    the legacy handshake from version 1.
     #
     # upgrade-v2-finish
     #    The upgrade to version 2 of the protocol is imminent.
     #
     # shutdown
     #    The server is shutting down, possibly in reaction to a client event.
     #
     # And here are their transitions:
     #
     # protov1-serving -> shutdown
     #    When server receives an empty request or encounters another
     #    error.
     #
     # protov1-serving -> upgrade-initial
     #    An upgrade request line was seen.
     #
     # upgrade-initial -> upgrade-v2-filter-legacy-handshake
     #    Upgrade to version 2 in progress. Server is expecting to
     #    process a legacy handshake.
     #
     # upgrade-v2-filter-legacy-handshake -> shutdown
     #    Client did not fulfill upgrade handshake requirements.
     #
     # upgrade-v2-filter-legacy-handshake -> upgrade-v2-finish
     #    Client fulfilled version 2 upgrade requirements. Finishing that
     #    upgrade.
     #
     # upgrade-v2-finish -> protov2-serving
     #    Protocol upgrade to version 2 complete. Server can now speak protocol
     #    version 2.
     #
     # protov2-serving -> protov1-serving
     #    Ths happens by default since protocol version 2 is the same as
     #    version 1 except for the handshake.
 
     state = 'protov1-serving'
     proto = sshv1protocolhandler(ui, fin, fout)
     protoswitched = False
 
     while not ev.is_set():
         if state == 'protov1-serving':
             # Commands are issued on new lines.
             request = fin.readline()[:-1]
 
             # Empty lines signal to terminate the connection.
             if not request:
                 state = 'shutdown'
                 continue
 
             # It looks like a protocol upgrade request. Transition state to
             # handle it.
             if request.startswith(b'upgrade '):
                 if protoswitched:
                     _sshv1respondooberror(fout, ui.ferr,
                                           b'cannot upgrade protocols multiple '
                                           b'times')
                     state = 'shutdown'
                     continue
 
                 state = 'upgrade-initial'
                 continue
 
             available = wireproto.commands.commandavailable(request, proto)
 
             # This command isn't available. Send an empty response and go
             # back to waiting for a new command.
             if not available:
                 _sshv1respondbytes(fout, b'')
                 continue
 
             rsp = wireproto.dispatch(repo, proto, request)
 
             if isinstance(rsp, bytes):
                 _sshv1respondbytes(fout, rsp)
             elif isinstance(rsp, wireprototypes.bytesresponse):
                 _sshv1respondbytes(fout, rsp.data)
             elif isinstance(rsp, wireprototypes.streamres):
                 _sshv1respondstream(fout, rsp)
             elif isinstance(rsp, wireprototypes.streamreslegacy):
                 _sshv1respondstream(fout, rsp)
             elif isinstance(rsp, wireprototypes.pushres):
                 _sshv1respondbytes(fout, b'')
                 _sshv1respondbytes(fout, b'%d' % rsp.res)
             elif isinstance(rsp, wireprototypes.pusherr):
                 _sshv1respondbytes(fout, rsp.res)
             elif isinstance(rsp, wireprototypes.ooberror):
                 _sshv1respondooberror(fout, ui.ferr, rsp.message)
             else:
                 raise error.ProgrammingError('unhandled response type from '
                                              'wire protocol command: %s' % rsp)
 
         # For now, protocol version 2 serving just goes back to version 1.
         elif state == 'protov2-serving':
             state = 'protov1-serving'
             continue
 
         elif state == 'upgrade-initial':
             # We should never transition into this state if we've switched
             # protocols.
             assert not protoswitched
             assert proto.name == wireprototypes.SSHV1
 
             # Expected: upgrade <token> <capabilities>
             # If we get something else, the request is malformed. It could be
             # from a future client that has altered the upgrade line content.
             # We treat this as an unknown command.
             try:
                 token, caps = request.split(b' ')[1:]
             except ValueError:
                 _sshv1respondbytes(fout, b'')
                 state = 'protov1-serving'
                 continue
 
             # Send empty response if we don't support upgrading protocols.
             if not ui.configbool('experimental', 'sshserver.support-v2'):
                 _sshv1respondbytes(fout, b'')
                 state = 'protov1-serving'
                 continue
 
             try:
                 caps = urlreq.parseqs(caps)
             except ValueError:
                 _sshv1respondbytes(fout, b'')
                 state = 'protov1-serving'
                 continue
 
             # We don't see an upgrade request to protocol version 2. Ignore
             # the upgrade request.
             wantedprotos = caps.get(b'proto', [b''])[0]
             if SSHV2 not in wantedprotos:
                 _sshv1respondbytes(fout, b'')
                 state = 'protov1-serving'
                 continue
 
             # It looks like we can honor this upgrade request to protocol 2.
             # Filter the rest of the handshake protocol request lines.
             state = 'upgrade-v2-filter-legacy-handshake'
             continue
 
         elif state == 'upgrade-v2-filter-legacy-handshake':
             # Client should have sent legacy handshake after an ``upgrade``
             # request. Expected lines:
             #
             #    hello
             #    between
             #    pairs 81
             #    0000...-0000...
 
             ok = True
             for line in (b'hello', b'between', b'pairs 81'):
                 request = fin.readline()[:-1]
 
                 if request != line:
                     _sshv1respondooberror(fout, ui.ferr,
                                           b'malformed handshake protocol: '
                                           b'missing %s' % line)
                     ok = False
                     state = 'shutdown'
                     break
 
             if not ok:
                 continue
 
             request = fin.read(81)
             if request != b'%s-%s' % (b'0' * 40, b'0' * 40):
                 _sshv1respondooberror(fout, ui.ferr,
                                       b'malformed handshake protocol: '
                                       b'missing between argument value')
                 state = 'shutdown'
                 continue
 
             state = 'upgrade-v2-finish'
             continue
 
         elif state == 'upgrade-v2-finish':
             # Send the upgrade response.
             fout.write(b'upgraded %s %s\n' % (token, SSHV2))
             servercaps = wireproto.capabilities(repo, proto)
             rsp = b'capabilities: %s' % servercaps.data
             fout.write(b'%d\n%s\n' % (len(rsp), rsp))
             fout.flush()
 
             proto = sshv2protocolhandler(ui, fin, fout)
             protoswitched = True
 
             state = 'protov2-serving'
             continue
 
         elif state == 'shutdown':
             break
 
         else:
             raise error.ProgrammingError('unhandled ssh server state: %s' %
                                          state)
 
 class sshserver(object):
     def __init__(self, ui, repo, logfh=None):
         self._ui = ui
         self._repo = repo
         self._fin = ui.fin
         self._fout = ui.fout
 
         # Log write I/O to stdout and stderr if configured.
         if logfh:
             self._fout = util.makeloggingfileobject(
                 logfh, self._fout, 'o', logdata=True)
             ui.ferr = util.makeloggingfileobject(
                 logfh, ui.ferr, 'e', logdata=True)
 
         hook.redirect(True)
         ui.fout = repo.ui.fout = ui.ferr
 
         # Prevent insertion/deletion of CRs
         procutil.setbinary(self._fin)
         procutil.setbinary(self._fout)
 
     def serve_forever(self):
         self.serveuntil(threading.Event())
         sys.exit(0)
 
     def serveuntil(self, ev):
         """Serve until a threading.Event is set."""
         _runsshserver(self._ui, self._repo, self._fin, self._fout, ev)

tests/test-http-api-httpv2.t

@@ -1,564 +1,564 b''
   $ HTTPV2=exp-http-v2-0001
   $ MEDIATYPE=application/mercurial-exp-framing-0002
 
   $ send() {
   >   hg --verbose debugwireproto --peer raw http://$LOCALIP:$HGPORT/
   > }
 
   $ cat > dummycommands.py << EOF
   > from mercurial import wireprototypes, wireproto
   > @wireproto.wireprotocommand('customreadonly', permission='pull')
   > def customreadonly(repo, proto):
   >     return wireprototypes.bytesresponse(b'customreadonly bytes response')
   > @wireproto.wireprotocommand('customreadwrite', permission='push')
   > def customreadwrite(repo, proto):
   >     return wireprototypes.bytesresponse(b'customreadwrite bytes response')
   > EOF
 
   $ cat >> $HGRCPATH << EOF
   > [extensions]
   > dummycommands = $TESTTMP/dummycommands.py
   > EOF
 
   $ hg init server
   $ cat > server/.hg/hgrc << EOF
   > [experimental]
   > web.apiserver = true
   > EOF
   $ hg -R server serve -p $HGPORT -d --pid-file hg.pid
   $ cat hg.pid > $DAEMON_PIDS
 
 HTTP v2 protocol not enabled by default
 
   $ send << EOF
   > httprequest GET api/$HTTPV2
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     GET /api/exp-http-v2-0001 HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 404 Not Found\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 33\r\n
   s>     \r\n
   s>     API exp-http-v2-0001 not enabled\n
 
 Restart server with support for HTTP v2 API
 
   $ killdaemons.py
   $ cat > server/.hg/hgrc << EOF
   > [experimental]
   > web.apiserver = true
   > web.api.http-v2 = true
   > EOF
 
   $ hg -R server serve -p $HGPORT -d --pid-file hg.pid
   $ cat hg.pid > $DAEMON_PIDS
 
 Request to unknown command yields 404
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/badcommand
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/badcommand HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 404 Not Found\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 42\r\n
   s>     \r\n
   s>     unknown wire protocol command: badcommand\n
 
 GET to read-only command yields a 405
 
   $ send << EOF
   > httprequest GET api/$HTTPV2/ro/customreadonly
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     GET /api/exp-http-v2-0001/ro/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 405 Method Not Allowed\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Allow: POST\r\n
   s>     Content-Length: 30\r\n
   s>     \r\n
   s>     commands require POST requests
 
 Missing Accept header results in 406
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/customreadonly
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 406 Not Acceptable\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 85\r\n
   s>     \r\n
   s>     client MUST specify Accept header with value: application/mercurial-exp-framing-0002\n
 
 Bad Accept header results in 406
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/customreadonly
   >     accept: invalid
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: invalid\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 406 Not Acceptable\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 85\r\n
   s>     \r\n
   s>     client MUST specify Accept header with value: application/mercurial-exp-framing-0002\n
 
 Bad Content-Type header results in 415
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/customreadonly
   >     accept: $MEDIATYPE
   >     user-agent: test
   >     content-type: badmedia
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: badmedia\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 415 Unsupported Media Type\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 88\r\n
   s>     \r\n
   s>     client MUST send Content-Type header with value: application/mercurial-exp-framing-0002\n
 
 Request to read-only command works out of the box
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/customreadonly
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
   >     user-agent: test
-  >     frame 1 command-name eos customreadonly
+  >     frame 1 1 stream-begin command-name eos customreadonly
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
   s>     *\r\n (glob)
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x0e\x00\x00\x01\x00\x11customreadonly
+  s>     \x0e\x00\x00\x01\x00\x01\x01\x11customreadonly
   s> makefile('rb', None)
   s>     HTTP/1.1 200 OK\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: application/mercurial-exp-framing-0002\r\n
   s>     Transfer-Encoding: chunked\r\n
   s>     \r\n
-  s>     23\r\n
-  s>     \x1d\x00\x00\x01\x00Bcustomreadonly bytes response
+  s>     25\r\n
+  s>     \x1d\x00\x00\x01\x00\x02\x01Bcustomreadonly bytes response
   s>     \r\n
   s>     0\r\n
   s>     \r\n
 
 Request to read-write command fails because server is read-only by default
 
 GET to read-write request yields 405
 
   $ send << EOF
   > httprequest GET api/$HTTPV2/rw/customreadonly
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     GET /api/exp-http-v2-0001/rw/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 405 Method Not Allowed\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Allow: POST\r\n
   s>     Content-Length: 30\r\n
   s>     \r\n
   s>     commands require POST requests
 
 Even for unknown commands
 
   $ send << EOF
   > httprequest GET api/$HTTPV2/rw/badcommand
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     GET /api/exp-http-v2-0001/rw/badcommand HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 405 Method Not Allowed\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Allow: POST\r\n
   s>     Content-Length: 30\r\n
   s>     \r\n
   s>     commands require POST requests
 
 SSL required by default
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/rw/customreadonly
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/rw/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 403 ssl required\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Length: 17\r\n
   s>     \r\n
   s>     permission denied
 
 Restart server to allow non-ssl read-write operations
 
   $ killdaemons.py
   $ cat > server/.hg/hgrc << EOF
   > [experimental]
   > web.apiserver = true
   > web.api.http-v2 = true
   > [web]
   > push_ssl = false
   > allow-push = *
   > EOF
 
   $ hg -R server serve -p $HGPORT -d --pid-file hg.pid -E error.log
   $ cat hg.pid > $DAEMON_PIDS
 
 Authorized request for valid read-write command works
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/rw/customreadonly
   >     user-agent: test
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
-  >     frame 1 command-name eos customreadonly
+  >     frame 1 1 stream-begin command-name eos customreadonly
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/rw/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
-  s>     content-length: 20\r\n
+  s>     content-length: 22\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x0e\x00\x00\x01\x00\x11customreadonly
+  s>     \x0e\x00\x00\x01\x00\x01\x01\x11customreadonly
   s> makefile('rb', None)
   s>     HTTP/1.1 200 OK\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: application/mercurial-exp-framing-0002\r\n
   s>     Transfer-Encoding: chunked\r\n
   s>     \r\n
-  s>     23\r\n
-  s>     \x1d\x00\x00\x01\x00Bcustomreadonly bytes response
+  s>     25\r\n
+  s>     \x1d\x00\x00\x01\x00\x02\x01Bcustomreadonly bytes response
   s>     \r\n
   s>     0\r\n
   s>     \r\n
 
 Authorized request for unknown command is rejected
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/rw/badcommand
   >     user-agent: test
   >     accept: $MEDIATYPE
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/rw/badcommand HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 404 Not Found\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 42\r\n
   s>     \r\n
   s>     unknown wire protocol command: badcommand\n
 
 debugreflect isn't enabled by default
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/debugreflect
   >     user-agent: test
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/debugreflect HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     user-agent: test\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
   s> makefile('rb', None)
   s>     HTTP/1.1 404 Not Found\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 34\r\n
   s>     \r\n
   s>     debugreflect service not available
 
 Restart server to get debugreflect endpoint
 
   $ killdaemons.py
   $ cat > server/.hg/hgrc << EOF
   > [experimental]
   > web.apiserver = true
   > web.api.debugreflect = true
   > web.api.http-v2 = true
   > [web]
   > push_ssl = false
   > allow-push = *
   > EOF
 
   $ hg -R server serve -p $HGPORT -d --pid-file hg.pid -E error.log
   $ cat hg.pid > $DAEMON_PIDS
 
 Command frames can be reflected via debugreflect
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/debugreflect
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
   >     user-agent: test
-  >     frame 1 command-name have-args command1
-  >     frame 1 command-argument 0 \x03\x00\x04\x00fooval1
-  >     frame 1 command-argument eoa \x04\x00\x03\x00bar1val
+  >     frame 1 1 stream-begin command-name have-args command1
+  >     frame 1 1 0 command-argument 0 \x03\x00\x04\x00fooval1
+  >     frame 1 1 0 command-argument eoa \x04\x00\x03\x00bar1val
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/debugreflect HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
-  s>     content-length: 48\r\n
+  s>     content-length: 54\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x08\x00\x00\x01\x00\x12command1\x0b\x00\x00\x01\x00 \x03\x00\x04\x00fooval1\x0b\x00\x00\x01\x00"\x04\x00\x03\x00bar1val
+  s>     \x08\x00\x00\x01\x00\x01\x01\x12command1\x0b\x00\x00\x01\x00\x01\x00 \x03\x00\x04\x00fooval1\x0b\x00\x00\x01\x00\x01\x00"\x04\x00\x03\x00bar1val
   s> makefile('rb', None)
   s>     HTTP/1.1 200 OK\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 322\r\n
   s>     \r\n
   s>     received: 1 2 1 command1\n
   s>     ["wantframe", {"state": "command-receiving"}]\n
   s>     received: 2 0 1 \x03\x00\x04\x00fooval1\n
   s>     ["wantframe", {"state": "command-receiving"}]\n
   s>     received: 2 2 1 \x04\x00\x03\x00bar1val\n
   s>     ["runcommand", {"args": {"bar1": "val", "foo": "val1"}, "command": "command1", "data": null, "requestid": 1}]\n
   s>     received: <no frame>\n
   s>     {"action": "noop"}
 
 Multiple requests to regular command URL are not allowed
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/customreadonly
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
   >     user-agent: test
-  >     frame 1 command-name eos customreadonly
-  >     frame 3 command-name eos customreadonly
+  >     frame 1 1 stream-begin command-name eos customreadonly
+  >     frame 3 1 0 command-name eos customreadonly
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/customreadonly HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
-  s>     content-length: 40\r\n
+  s>     content-length: 44\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x0e\x00\x00\x01\x00\x11customreadonly\x0e\x00\x00\x03\x00\x11customreadonly
+  s>     \x0e\x00\x00\x01\x00\x01\x01\x11customreadonly\x0e\x00\x00\x03\x00\x01\x00\x11customreadonly
   s> makefile('rb', None)
   s>     HTTP/1.1 200 OK\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 46\r\n
   s>     \r\n
   s>     multiple commands cannot be issued to this URL
 
 Multiple requests to "multirequest" URL are allowed
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/multirequest
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
   >     user-agent: test
-  >     frame 1 command-name eos customreadonly
-  >     frame 3 command-name eos customreadonly
+  >     frame 1 1 stream-begin command-name eos customreadonly
+  >     frame 3 1 0 command-name eos customreadonly
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/multirequest HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
   s>     *\r\n (glob)
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x0e\x00\x00\x01\x00\x11customreadonly\x0e\x00\x00\x03\x00\x11customreadonly
+  s>     \x0e\x00\x00\x01\x00\x01\x01\x11customreadonly\x0e\x00\x00\x03\x00\x01\x00\x11customreadonly
   s> makefile('rb', None)
   s>     HTTP/1.1 200 OK\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: application/mercurial-exp-framing-0002\r\n
   s>     Transfer-Encoding: chunked\r\n
   s>     \r\n
   s>     *\r\n (glob)
-  s>     \x1d\x00\x00\x01\x00Bcustomreadonly bytes response
+  s>     \x1d\x00\x00\x01\x00\x02\x01Bcustomreadonly bytes response
   s>     \r\n
-  s>     23\r\n
-  s>     \x1d\x00\x00\x03\x00Bcustomreadonly bytes response
+  s>     25\r\n
+  s>     \x1d\x00\x00\x03\x00\x02\x01Bcustomreadonly bytes response
   s>     \r\n
   s>     0\r\n
   s>     \r\n
 
 Interleaved requests to "multirequest" are processed
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/multirequest
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
   >     user-agent: test
-  >     frame 1 command-name have-args listkeys
-  >     frame 3 command-name have-args listkeys
-  >     frame 3 command-argument eoa \x09\x00\x09\x00namespacebookmarks
-  >     frame 1 command-argument eoa \x09\x00\x0a\x00namespacenamespaces
+  >     frame 1 1 stream-begin command-name have-args listkeys
+  >     frame 3 1 0 command-name have-args listkeys
+  >     frame 3 1 0 command-argument eoa \x09\x00\x09\x00namespacebookmarks
+  >     frame 1 1 0 command-argument eoa \x09\x00\x0a\x00namespacenamespaces
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/multirequest HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
-  s>     content-length: 85\r\n
+  s>     content-length: 93\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x08\x00\x00\x01\x00\x12listkeys\x08\x00\x00\x03\x00\x12listkeys\x16\x00\x00\x03\x00"	\x00	\x00namespacebookmarks\x17\x00\x00\x01\x00"	\x00\n
+  s>     \x08\x00\x00\x01\x00\x01\x01\x12listkeys\x08\x00\x00\x03\x00\x01\x00\x12listkeys\x16\x00\x00\x03\x00\x01\x00"	\x00	\x00namespacebookmarks\x17\x00\x00\x01\x00\x01\x00"	\x00\n
   s>     \x00namespacenamespaces
   s> makefile('rb', None)
   s>     HTTP/1.1 200 OK\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: application/mercurial-exp-framing-0002\r\n
   s>     Transfer-Encoding: chunked\r\n
   s>     \r\n
-  s>     6\r\n
-  s>     \x00\x00\x00\x03\x00B
+  s>     8\r\n
+  s>     \x00\x00\x00\x03\x00\x02\x01B
   s>     \r\n
-  s>     24\r\n
-  s>     \x1e\x00\x00\x01\x00Bbookmarks	\n
+  s>     26\r\n
+  s>     \x1e\x00\x00\x01\x00\x02\x01Bbookmarks	\n
   s>     namespaces	\n
   s>     phases	
   s>     \r\n
   s>     0\r\n
   s>     \r\n
 
 Restart server to disable read-write access
 
   $ killdaemons.py
   $ cat > server/.hg/hgrc << EOF
   > [experimental]
   > web.apiserver = true
   > web.api.debugreflect = true
   > web.api.http-v2 = true
   > [web]
   > push_ssl = false
   > EOF
 
   $ hg -R server serve -p $HGPORT -d --pid-file hg.pid -E error.log
   $ cat hg.pid > $DAEMON_PIDS
 
 Attempting to run a read-write command via multirequest on read-only URL is not allowed
 
   $ send << EOF
   > httprequest POST api/$HTTPV2/ro/multirequest
   >     accept: $MEDIATYPE
   >     content-type: $MEDIATYPE
   >     user-agent: test
-  >     frame 1 command-name eos unbundle
+  >     frame 1 1 stream-begin command-name eos unbundle
   > EOF
   using raw connection to peer
   s>     POST /api/exp-http-v2-0001/ro/multirequest HTTP/1.1\r\n
   s>     Accept-Encoding: identity\r\n
   s>     accept: application/mercurial-exp-framing-0002\r\n
   s>     content-type: application/mercurial-exp-framing-0002\r\n
   s>     user-agent: test\r\n
-  s>     content-length: 14\r\n
+  s>     content-length: 16\r\n
   s>     host: $LOCALIP:$HGPORT\r\n (glob)
   s>     \r\n
-  s>     \x08\x00\x00\x01\x00\x11unbundle
+  s>     \x08\x00\x00\x01\x00\x01\x01\x11unbundle
   s> makefile('rb', None)
   s>     HTTP/1.1 403 Forbidden\r\n
   s>     Server: testing stub value\r\n
   s>     Date: $HTTP_DATE$\r\n
   s>     Content-Type: text/plain\r\n
   s>     Content-Length: 53\r\n
   s>     \r\n
   s>     insufficient permissions to execute command: unbundle
 
   $ cat error.log

tests/test-wireproto-serverreactor.py

@@ -1,678 +1,684 b''
 from __future__ import absolute_import, print_function
 
 import unittest
 
 from mercurial import (
     util,
     wireprotoframing as framing,
 )
 
 ffs = framing.makeframefromhumanstring
 
 def makereactor(deferoutput=False):
     return framing.serverreactor(deferoutput=deferoutput)
 
 def sendframes(reactor, gen):
     """Send a generator of frame bytearray to a reactor.
 
     Emits a generator of results from ``onframerecv()`` calls.
     """
     for frame in gen:
         header = framing.parseheader(frame)
         payload = frame[framing.FRAME_HEADER_SIZE:]
         assert len(payload) == header.length
 
         yield reactor.onframerecv(framing.frame(header.requestid,
+                                                header.streamid,
+                                                header.streamflags,
                                                 header.typeid,
                                                 header.flags,
                                                 payload))
 
 def sendcommandframes(reactor, stream, rid, cmd, args, datafh=None):
     """Generate frames to run a command and send them to a reactor."""
     return sendframes(reactor,
                       framing.createcommandframes(stream, rid, cmd, args,
                                                   datafh))
 
 class FrameTests(unittest.TestCase):
     def testdataexactframesize(self):
         data = util.bytesio(b'x' * framing.DEFAULT_MAX_FRAME_SIZE)
 
-        stream = framing.stream()
+        stream = framing.stream(1)
         frames = list(framing.createcommandframes(stream, 1, b'command',
                                                   {}, data))
         self.assertEqual(frames, [
-            ffs(b'1 command-name have-data command'),
-            ffs(b'1 command-data continuation %s' % data.getvalue()),
-            ffs(b'1 command-data eos ')
+            ffs(b'1 1 stream-begin command-name have-data command'),
+            ffs(b'1 1 0 command-data continuation %s' % data.getvalue()),
+            ffs(b'1 1 0 command-data eos ')
         ])
 
     def testdatamultipleframes(self):
         data = util.bytesio(b'x' * (framing.DEFAULT_MAX_FRAME_SIZE + 1))
 
-        stream = framing.stream()
+        stream = framing.stream(1)
         frames = list(framing.createcommandframes(stream, 1, b'command', {},
                                                   data))
         self.assertEqual(frames, [
-            ffs(b'1 command-name have-data command'),
-            ffs(b'1 command-data continuation %s' % (
+            ffs(b'1 1 stream-begin command-name have-data command'),
+            ffs(b'1 1 0 command-data continuation %s' % (
                 b'x' * framing.DEFAULT_MAX_FRAME_SIZE)),
-            ffs(b'1 command-data eos x'),
+            ffs(b'1 1 0 command-data eos x'),
         ])
 
     def testargsanddata(self):
         data = util.bytesio(b'x' * 100)
 
-        stream = framing.stream()
+        stream = framing.stream(1)
         frames = list(framing.createcommandframes(stream, 1, b'command', {
             b'key1': b'key1value',
             b'key2': b'key2value',
             b'key3': b'key3value',
         }, data))
 
         self.assertEqual(frames, [
-            ffs(b'1 command-name have-args|have-data command'),
-            ffs(br'1 command-argument 0 \x04\x00\x09\x00key1key1value'),
-            ffs(br'1 command-argument 0 \x04\x00\x09\x00key2key2value'),
-            ffs(br'1 command-argument eoa \x04\x00\x09\x00key3key3value'),
-            ffs(b'1 command-data eos %s' % data.getvalue()),
+            ffs(b'1 1 stream-begin command-name have-args|have-data command'),
+            ffs(br'1 1 0 command-argument 0 \x04\x00\x09\x00key1key1value'),
+            ffs(br'1 1 0 command-argument 0 \x04\x00\x09\x00key2key2value'),
+            ffs(br'1 1 0 command-argument eoa \x04\x00\x09\x00key3key3value'),
+            ffs(b'1 1 0 command-data eos %s' % data.getvalue()),
         ])
 
     def testtextoutputexcessiveargs(self):
         """At most 255 formatting arguments are allowed."""
         with self.assertRaisesRegexp(ValueError,
                                      'cannot use more than 255 formatting'):
             args = [b'x' for i in range(256)]
             list(framing.createtextoutputframe(None, 1,
                                                [(b'bleh', args, [])]))
 
     def testtextoutputexcessivelabels(self):
         """At most 255 labels are allowed."""
         with self.assertRaisesRegexp(ValueError,
                                      'cannot use more than 255 labels'):
             labels = [b'l' for i in range(256)]
             list(framing.createtextoutputframe(None, 1,
                                                [(b'bleh', [], labels)]))
 
     def testtextoutputformattingstringtype(self):
         """Formatting string must be bytes."""
         with self.assertRaisesRegexp(ValueError, 'must use bytes formatting '):
             list(framing.createtextoutputframe(None, 1, [
                 (b'foo'.decode('ascii'), [], [])]))
 
     def testtextoutputargumentbytes(self):
         with self.assertRaisesRegexp(ValueError, 'must use bytes for argument'):
             list(framing.createtextoutputframe(None, 1, [
                 (b'foo', [b'foo'.decode('ascii')], [])]))
 
     def testtextoutputlabelbytes(self):
         with self.assertRaisesRegexp(ValueError, 'must use bytes for labels'):
             list(framing.createtextoutputframe(None, 1, [
                 (b'foo', [], [b'foo'.decode('ascii')])]))
 
     def testtextoutputtoolongformatstring(self):
         with self.assertRaisesRegexp(ValueError,
                                      'formatting string cannot be longer than'):
             list(framing.createtextoutputframe(None, 1, [
                 (b'x' * 65536, [], [])]))
 
     def testtextoutputtoolongargumentstring(self):
         with self.assertRaisesRegexp(ValueError,
                                      'argument string cannot be longer than'):
             list(framing.createtextoutputframe(None, 1, [
                 (b'bleh', [b'x' * 65536], [])]))
 
     def testtextoutputtoolonglabelstring(self):
         with self.assertRaisesRegexp(ValueError,
                                      'label string cannot be longer than'):
             list(framing.createtextoutputframe(None, 1, [
                 (b'bleh', [], [b'x' * 65536])]))
 
     def testtextoutput1simpleatom(self):
-        stream = framing.stream()
+        stream = framing.stream(1)
         val = list(framing.createtextoutputframe(stream, 1, [
             (b'foo', [], [])]))
 
         self.assertEqual(val, [
-            ffs(br'1 text-output 0 \x03\x00\x00\x00foo'),
+            ffs(br'1 1 stream-begin text-output 0 \x03\x00\x00\x00foo'),
         ])
 
     def testtextoutput2simpleatoms(self):
-        stream = framing.stream()
+        stream = framing.stream(1)
         val = list(framing.createtextoutputframe(stream, 1, [
             (b'foo', [], []),
             (b'bar', [], []),
         ]))
 
         self.assertEqual(val, [
-            ffs(br'1 text-output 0 \x03\x00\x00\x00foo\x03\x00\x00\x00bar'),
+            ffs(br'1 1 stream-begin text-output 0 '
+                br'\x03\x00\x00\x00foo\x03\x00\x00\x00bar'),
         ])
 
     def testtextoutput1arg(self):
-        stream = framing.stream()
+        stream = framing.stream(1)
         val = list(framing.createtextoutputframe(stream, 1, [
             (b'foo %s', [b'val1'], []),
         ]))
 
         self.assertEqual(val, [
-            ffs(br'1 text-output 0 \x06\x00\x00\x01\x04\x00foo %sval1'),
+            ffs(br'1 1 stream-begin text-output 0 '
+                br'\x06\x00\x00\x01\x04\x00foo %sval1'),
         ])
 
     def testtextoutput2arg(self):
-        stream = framing.stream()
+        stream = framing.stream(1)
         val = list(framing.createtextoutputframe(stream, 1, [
             (b'foo %s %s', [b'val', b'value'], []),
         ]))
 
         self.assertEqual(val, [
-            ffs(br'1 text-output 0 \x09\x00\x00\x02\x03\x00\x05\x00'
-                br'foo %s %svalvalue'),
+            ffs(br'1 1 stream-begin text-output 0 '
+                br'\x09\x00\x00\x02\x03\x00\x05\x00foo %s %svalvalue'),
         ])
 
     def testtextoutput1label(self):
-        stream = framing.stream()
+        stream = framing.stream(1)
         val = list(framing.createtextoutputframe(stream, 1, [
             (b'foo', [], [b'label']),
         ]))
 
         self.assertEqual(val, [
-            ffs(br'1 text-output 0 \x03\x00\x01\x00\x05foolabel'),
+            ffs(br'1 1 stream-begin text-output 0 '
+                br'\x03\x00\x01\x00\x05foolabel'),
         ])
 
     def testargandlabel(self):
-        stream = framing.stream()
+        stream = framing.stream(1)
         val = list(framing.createtextoutputframe(stream, 1, [
             (b'foo %s', [b'arg'], [b'label']),
         ]))
 
         self.assertEqual(val, [
-            ffs(br'1 text-output 0 \x06\x00\x01\x01\x05\x03\x00foo %slabelarg'),
+            ffs(br'1 1 stream-begin text-output 0 '
+                br'\x06\x00\x01\x01\x05\x03\x00foo %slabelarg'),
         ])
 
 class ServerReactorTests(unittest.TestCase):
     def _sendsingleframe(self, reactor, f):
         results = list(sendframes(reactor, [f]))
         self.assertEqual(len(results), 1)
 
         return results[0]
 
     def assertaction(self, res, expected):
         self.assertIsInstance(res, tuple)
         self.assertEqual(len(res), 2)
         self.assertIsInstance(res[1], dict)
         self.assertEqual(res[0], expected)
 
     def assertframesequal(self, frames, framestrings):
         expected = [ffs(s) for s in framestrings]
         self.assertEqual(list(frames), expected)
 
     def test1framecommand(self):
         """Receiving a command in a single frame yields request to run it."""
         reactor = makereactor()
-        stream = framing.stream()
+        stream = framing.stream(1)
         results = list(sendcommandframes(reactor, stream, 1, b'mycommand', {}))
         self.assertEqual(len(results), 1)
         self.assertaction(results[0], 'runcommand')
         self.assertEqual(results[0][1], {
             'requestid': 1,
             'command': b'mycommand',
             'args': {},
             'data': None,
         })
 
         result = reactor.oninputeof()
         self.assertaction(result, 'noop')
 
     def test1argument(self):
         reactor = makereactor()
-        stream = framing.stream()
+        stream = framing.stream(1)
         results = list(sendcommandframes(reactor, stream, 41, b'mycommand',
                                          {b'foo': b'bar'}))
         self.assertEqual(len(results), 2)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'runcommand')
         self.assertEqual(results[1][1], {
             'requestid': 41,
             'command': b'mycommand',
             'args': {b'foo': b'bar'},
             'data': None,
         })
 
     def testmultiarguments(self):
         reactor = makereactor()
-        stream = framing.stream()
+        stream = framing.stream(1)
         results = list(sendcommandframes(reactor, stream, 1, b'mycommand',
                                          {b'foo': b'bar', b'biz': b'baz'}))
         self.assertEqual(len(results), 3)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'wantframe')
         self.assertaction(results[2], 'runcommand')
         self.assertEqual(results[2][1], {
             'requestid': 1,
             'command': b'mycommand',
             'args': {b'foo': b'bar', b'biz': b'baz'},
             'data': None,
         })
 
     def testsimplecommanddata(self):
         reactor = makereactor()
-        stream = framing.stream()
+        stream = framing.stream(1)
         results = list(sendcommandframes(reactor, stream, 1, b'mycommand', {},
                                          util.bytesio(b'data!')))
         self.assertEqual(len(results), 2)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'runcommand')
         self.assertEqual(results[1][1], {
             'requestid': 1,
             'command': b'mycommand',
             'args': {},
             'data': b'data!',
         })
 
     def testmultipledataframes(self):
         frames = [
-            ffs(b'1 command-name have-data mycommand'),
-            ffs(b'1 command-data continuation data1'),
-            ffs(b'1 command-data continuation data2'),
-            ffs(b'1 command-data eos data3'),
+            ffs(b'1 1 stream-begin command-name have-data mycommand'),
+            ffs(b'1 1 0 command-data continuation data1'),
+            ffs(b'1 1 0 command-data continuation data2'),
+            ffs(b'1 1 0 command-data eos data3'),
         ]
 
         reactor = makereactor()
         results = list(sendframes(reactor, frames))
         self.assertEqual(len(results), 4)
         for i in range(3):
             self.assertaction(results[i], 'wantframe')
         self.assertaction(results[3], 'runcommand')
         self.assertEqual(results[3][1], {
             'requestid': 1,
             'command': b'mycommand',
             'args': {},
             'data': b'data1data2data3',
         })
 
     def testargumentanddata(self):
         frames = [
-            ffs(b'1 command-name have-args|have-data command'),
-            ffs(br'1 command-argument 0 \x03\x00\x03\x00keyval'),
-            ffs(br'1 command-argument eoa \x03\x00\x03\x00foobar'),
-            ffs(b'1 command-data continuation value1'),
-            ffs(b'1 command-data eos value2'),
+            ffs(b'1 1 stream-begin command-name have-args|have-data command'),
+            ffs(br'1 1 0 command-argument 0 \x03\x00\x03\x00keyval'),
+            ffs(br'1 1 0 command-argument eoa \x03\x00\x03\x00foobar'),
+            ffs(b'1 1 0 command-data continuation value1'),
+            ffs(b'1 1 0 command-data eos value2'),
         ]
 
         reactor = makereactor()
         results = list(sendframes(reactor, frames))
 
         self.assertaction(results[-1], 'runcommand')
         self.assertEqual(results[-1][1], {
             'requestid': 1,
             'command': b'command',
             'args': {
                 b'key': b'val',
                 b'foo': b'bar',
             },
             'data': b'value1value2',
         })
 
     def testunexpectedcommandargument(self):
         """Command argument frame when not running a command is an error."""
-        result = self._sendsingleframe(makereactor(),
-                                       ffs(b'1 command-argument 0 ignored'))
+        result = self._sendsingleframe(
+            makereactor(), ffs(b'1 1 stream-begin command-argument 0 ignored'))
         self.assertaction(result, 'error')
         self.assertEqual(result[1], {
             'message': b'expected command frame; got 2',
         })
 
     def testunexpectedcommandargumentreceiving(self):
         """Same as above but the command is receiving."""
         results = list(sendframes(makereactor(), [
-            ffs(b'1 command-name have-data command'),
-            ffs(b'1 command-argument eoa ignored'),
+            ffs(b'1 1 stream-begin command-name have-data command'),
+            ffs(b'1 1 0 command-argument eoa ignored'),
         ]))
 
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': b'received command argument frame for request that is '
                        b'not expecting arguments: 1',
         })
 
     def testunexpectedcommanddata(self):
         """Command argument frame when not running a command is an error."""
-        result = self._sendsingleframe(makereactor(),
-                                       ffs(b'1 command-data 0 ignored'))
+        result = self._sendsingleframe(
+            makereactor(), ffs(b'1 1 stream-begin command-data 0 ignored'))
         self.assertaction(result, 'error')
         self.assertEqual(result[1], {
             'message': b'expected command frame; got 3',
         })
 
     def testunexpectedcommanddatareceiving(self):
         """Same as above except the command is receiving."""
         results = list(sendframes(makereactor(), [
-            ffs(b'1 command-name have-args command'),
-            ffs(b'1 command-data eos ignored'),
+            ffs(b'1 1 stream-begin command-name have-args command'),
+            ffs(b'1 1 0 command-data eos ignored'),
         ]))
 
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': b'received command data frame for request that is not '
                        b'expecting data: 1',
         })
 
     def testmissingcommandframeflags(self):
         """Command name frame must have flags set."""
-        result = self._sendsingleframe(makereactor(),
-                                       ffs(b'1 command-name 0 command'))
+        result = self._sendsingleframe(
+            makereactor(), ffs(b'1 1 stream-begin command-name 0 command'))
         self.assertaction(result, 'error')
         self.assertEqual(result[1], {
             'message': b'missing frame flags on command frame',
         })
 
     def testconflictingrequestidallowed(self):
         """Multiple fully serviced commands with same request ID is allowed."""
         reactor = makereactor()
         results = []
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         results.append(self._sendsingleframe(
-            reactor, ffs(b'1 command-name eos command')))
+            reactor, ffs(b'1 1 stream-begin command-name eos command')))
         result = reactor.onbytesresponseready(outstream, 1, b'response1')
         self.assertaction(result, 'sendframes')
         list(result[1]['framegen'])
         results.append(self._sendsingleframe(
-            reactor, ffs(b'1 command-name eos command')))
+            reactor, ffs(b'1 1 0 command-name eos command')))
         result = reactor.onbytesresponseready(outstream, 1, b'response2')
         self.assertaction(result, 'sendframes')
         list(result[1]['framegen'])
         results.append(self._sendsingleframe(
-            reactor, ffs(b'1 command-name eos command')))
+            reactor, ffs(b'1 1 0 command-name eos command')))
         result = reactor.onbytesresponseready(outstream, 1, b'response3')
         self.assertaction(result, 'sendframes')
         list(result[1]['framegen'])
 
         for i in range(3):
             self.assertaction(results[i], 'runcommand')
             self.assertEqual(results[i][1], {
                 'requestid': 1,
                 'command': b'command',
                 'args': {},
                 'data': None,
             })
 
     def testconflictingrequestid(self):
         """Request ID for new command matching in-flight command is illegal."""
         results = list(sendframes(makereactor(), [
-            ffs(b'1 command-name have-args command'),
-            ffs(b'1 command-name eos command'),
+            ffs(b'1 1 stream-begin command-name have-args command'),
+            ffs(b'1 1 0 command-name eos command'),
         ]))
 
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': b'request with ID 1 already received',
         })
 
     def testinterleavedcommands(self):
         results = list(sendframes(makereactor(), [
-            ffs(b'1 command-name have-args command1'),
-            ffs(b'3 command-name have-args command3'),
-            ffs(br'1 command-argument 0 \x03\x00\x03\x00foobar'),
-            ffs(br'3 command-argument 0 \x03\x00\x03\x00bizbaz'),
-            ffs(br'3 command-argument eoa \x03\x00\x03\x00keyval'),
-            ffs(br'1 command-argument eoa \x04\x00\x03\x00key1val'),
+            ffs(b'1 1 stream-begin command-name have-args command1'),
+            ffs(b'3 1 0 command-name have-args command3'),
+            ffs(br'1 1 0 command-argument 0 \x03\x00\x03\x00foobar'),
+            ffs(br'3 1 0 command-argument 0 \x03\x00\x03\x00bizbaz'),
+            ffs(br'3 1 0 command-argument eoa \x03\x00\x03\x00keyval'),
+            ffs(br'1 1 0 command-argument eoa \x04\x00\x03\x00key1val'),
         ]))
 
         self.assertEqual([t[0] for t in results], [
             'wantframe',
             'wantframe',
             'wantframe',
             'wantframe',
             'runcommand',
             'runcommand',
         ])
 
         self.assertEqual(results[4][1], {
             'requestid': 3,
             'command': 'command3',
             'args': {b'biz': b'baz', b'key': b'val'},
             'data': None,
         })
         self.assertEqual(results[5][1], {
             'requestid': 1,
             'command': 'command1',
             'args': {b'foo': b'bar', b'key1': b'val'},
             'data': None,
         })
 
     def testmissingargumentframe(self):
         # This test attempts to test behavior when reactor has an incomplete
         # command request waiting on argument data. But it doesn't handle that
         # scenario yet. So this test does nothing of value.
         frames = [
-            ffs(b'1 command-name have-args command'),
+            ffs(b'1 1 stream-begin command-name have-args command'),
         ]
 
         results = list(sendframes(makereactor(), frames))
         self.assertaction(results[0], 'wantframe')
 
     def testincompleteargumentname(self):
         """Argument frame with incomplete name."""
         frames = [
-            ffs(b'1 command-name have-args command1'),
-            ffs(br'1 command-argument eoa \x04\x00\xde\xadfoo'),
+            ffs(b'1 1 stream-begin command-name have-args command1'),
+            ffs(br'1 1 0 command-argument eoa \x04\x00\xde\xadfoo'),
         ]
 
         results = list(sendframes(makereactor(), frames))
         self.assertEqual(len(results), 2)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': b'malformed argument frame: partial argument name',
         })
 
     def testincompleteargumentvalue(self):
         """Argument frame with incomplete value."""
         frames = [
-            ffs(b'1 command-name have-args command'),
-            ffs(br'1 command-argument eoa \x03\x00\xaa\xaafoopartialvalue'),
+            ffs(b'1 1 stream-begin command-name have-args command'),
+            ffs(br'1 1 0 command-argument eoa \x03\x00\xaa\xaafoopartialvalue'),
         ]
 
         results = list(sendframes(makereactor(), frames))
         self.assertEqual(len(results), 2)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': b'malformed argument frame: partial argument value',
         })
 
     def testmissingcommanddataframe(self):
         # The reactor doesn't currently handle partially received commands.
         # So this test is failing to do anything with request 1.
         frames = [
-            ffs(b'1 command-name have-data command1'),
-            ffs(b'3 command-name eos command2'),
+            ffs(b'1 1 stream-begin command-name have-data command1'),
+            ffs(b'3 1 0 command-name eos command2'),
         ]
         results = list(sendframes(makereactor(), frames))
         self.assertEqual(len(results), 2)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'runcommand')
 
     def testmissingcommanddataframeflags(self):
         frames = [
-            ffs(b'1 command-name have-data command1'),
-            ffs(b'1 command-data 0 data'),
+            ffs(b'1 1 stream-begin command-name have-data command1'),
+            ffs(b'1 1 0 command-data 0 data'),
         ]
         results = list(sendframes(makereactor(), frames))
         self.assertEqual(len(results), 2)
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': b'command data frame without flags',
         })
 
     def testframefornonreceivingrequest(self):
         """Receiving a frame for a command that is not receiving is illegal."""
         results = list(sendframes(makereactor(), [
-            ffs(b'1 command-name eos command1'),
-            ffs(b'3 command-name have-data command3'),
-            ffs(b'5 command-argument eoa ignored'),
+            ffs(b'1 1 stream-begin command-name eos command1'),
+            ffs(b'3 1 0 command-name have-data command3'),
+            ffs(b'5 1 0 command-argument eoa ignored'),
         ]))
         self.assertaction(results[2], 'error')
         self.assertEqual(results[2][1], {
             'message': b'received frame for request that is not receiving: 5',
         })
 
     def testsimpleresponse(self):
         """Bytes response to command sends result frames."""
         reactor = makereactor()
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'mycommand', {}))
 
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         result = reactor.onbytesresponseready(outstream, 1, b'response')
         self.assertaction(result, 'sendframes')
         self.assertframesequal(result[1]['framegen'], [
-            b'1 bytes-response eos response',
+            b'1 2 stream-begin bytes-response eos response',
         ])
 
     def testmultiframeresponse(self):
         """Bytes response spanning multiple frames is handled."""
         first = b'x' * framing.DEFAULT_MAX_FRAME_SIZE
         second = b'y' * 100
 
         reactor = makereactor()
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'mycommand', {}))
 
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         result = reactor.onbytesresponseready(outstream, 1, first + second)
         self.assertaction(result, 'sendframes')
         self.assertframesequal(result[1]['framegen'], [
-            b'1 bytes-response continuation %s' % first,
-            b'1 bytes-response eos %s' % second,
+            b'1 2 stream-begin bytes-response continuation %s' % first,
+            b'1 2 0 bytes-response eos %s' % second,
         ])
 
     def testapplicationerror(self):
         reactor = makereactor()
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'mycommand', {}))
 
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         result = reactor.onapplicationerror(outstream, 1, b'some message')
         self.assertaction(result, 'sendframes')
         self.assertframesequal(result[1]['framegen'], [
-            b'1 error-response application some message',
+            b'1 2 stream-begin error-response application some message',
         ])
 
     def test1commanddeferresponse(self):
         """Responses when in deferred output mode are delayed until EOF."""
         reactor = makereactor(deferoutput=True)
-        instream = framing.stream()
+        instream = framing.stream(1)
         results = list(sendcommandframes(reactor, instream, 1, b'mycommand',
                                          {}))
         self.assertEqual(len(results), 1)
         self.assertaction(results[0], 'runcommand')
 
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         result = reactor.onbytesresponseready(outstream, 1, b'response')
         self.assertaction(result, 'noop')
         result = reactor.oninputeof()
         self.assertaction(result, 'sendframes')
         self.assertframesequal(result[1]['framegen'], [
-            b'1 bytes-response eos response',
+            b'1 2 stream-begin bytes-response eos response',
         ])
 
     def testmultiplecommanddeferresponse(self):
         reactor = makereactor(deferoutput=True)
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'command1', {}))
         list(sendcommandframes(reactor, instream, 3, b'command2', {}))
 
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         result = reactor.onbytesresponseready(outstream, 1, b'response1')
         self.assertaction(result, 'noop')
         result = reactor.onbytesresponseready(outstream, 3, b'response2')
         self.assertaction(result, 'noop')
         result = reactor.oninputeof()
         self.assertaction(result, 'sendframes')
         self.assertframesequal(result[1]['framegen'], [
-            b'1 bytes-response eos response1',
-            b'3 bytes-response eos response2'
+            b'1 2 stream-begin bytes-response eos response1',
+            b'3 2 0 bytes-response eos response2'
         ])
 
     def testrequestidtracking(self):
         reactor = makereactor(deferoutput=True)
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'command1', {}))
         list(sendcommandframes(reactor, instream, 3, b'command2', {}))
         list(sendcommandframes(reactor, instream, 5, b'command3', {}))
 
         # Register results for commands out of order.
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         reactor.onbytesresponseready(outstream, 3, b'response3')
         reactor.onbytesresponseready(outstream, 1, b'response1')
         reactor.onbytesresponseready(outstream, 5, b'response5')
 
         result = reactor.oninputeof()
         self.assertaction(result, 'sendframes')
         self.assertframesequal(result[1]['framegen'], [
-            b'3 bytes-response eos response3',
-            b'1 bytes-response eos response1',
-            b'5 bytes-response eos response5',
+            b'3 2 stream-begin bytes-response eos response3',
+            b'1 2 0 bytes-response eos response1',
+            b'5 2 0 bytes-response eos response5',
         ])
 
     def testduplicaterequestonactivecommand(self):
         """Receiving a request ID that matches a request that isn't finished."""
         reactor = makereactor()
-        stream = framing.stream()
+        stream = framing.stream(1)
         list(sendcommandframes(reactor, stream, 1, b'command1', {}))
         results = list(sendcommandframes(reactor, stream, 1, b'command1', {}))
 
         self.assertaction(results[0], 'error')
         self.assertEqual(results[0][1], {
             'message': b'request with ID 1 is already active',
         })
 
     def testduplicaterequestonactivecommandnosend(self):
         """Same as above but we've registered a response but haven't sent it."""
         reactor = makereactor()
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'command1', {}))
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         reactor.onbytesresponseready(outstream, 1, b'response')
 
         # We've registered the response but haven't sent it. From the
         # perspective of the reactor, the command is still active.
 
         results = list(sendcommandframes(reactor, instream, 1, b'command1', {}))
         self.assertaction(results[0], 'error')
         self.assertEqual(results[0][1], {
             'message': b'request with ID 1 is already active',
         })
 
     def testduplicaterequestargumentframe(self):
         """Variant on above except we sent an argument frame instead of name."""
         reactor = makereactor()
-        stream = framing.stream()
+        stream = framing.stream(1)
         list(sendcommandframes(reactor, stream, 1, b'command', {}))
         results = list(sendframes(reactor, [
-            ffs(b'3 command-name have-args command'),
-            ffs(b'1 command-argument 0 ignored'),
+            ffs(b'3 1 stream-begin command-name have-args command'),
+            ffs(b'1 1 0 command-argument 0 ignored'),
         ]))
         self.assertaction(results[0], 'wantframe')
         self.assertaction(results[1], 'error')
         self.assertEqual(results[1][1], {
             'message': 'received frame for request that is still active: 1',
         })
 
     def testduplicaterequestaftersend(self):
         """We can use a duplicate request ID after we've sent the response."""
         reactor = makereactor()
-        instream = framing.stream()
+        instream = framing.stream(1)
         list(sendcommandframes(reactor, instream, 1, b'command1', {}))
-        outstream = framing.stream()
+        outstream = framing.stream(2)
         res = reactor.onbytesresponseready(outstream, 1, b'response')
         list(res[1]['framegen'])
 
         results = list(sendcommandframes(reactor, instream, 1, b'command1', {}))
         self.assertaction(results[0], 'runcommand')
 
 if __name__ == '__main__':
     import silenttestrunner
     silenttestrunner.main(__name__)