This is an archive of the discontinued Mercurial Phabricator instance.

Differential D333

repository: formalize wire protocol interface
ClosedPublic

Authored by indygreg on Aug 11 2017, 12:20 AM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHG558f5b2ee10e: repository: formalize wire protocol interface
Summary

There are a well-defined set of commands constituting the wire
protocol. Interaction with these and methods for calling them in
batches are exposed via methods on peer instances.

Let's formalize support for these features in abstract classes.

The command parts come from the existing wireproto.wirepeer class.
The batch methods come from peer.peerrepository.

Ample documentation has been added as part of defining the interfaces.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

indygreg created this revision.Aug 11 2017, 12:20 AM
durin42 added a subscriber: durin42.Aug 11 2017, 2:27 PM
durin42 added inline comments.
mercurial/repository.py
68

spelling: interfac

226

Probably also note that at the wireprotocol layer, it is known that not all peers stream batch responses, so it may not behave as a streaming response even though it's a generator (specifically ssh behaves this way)

indygreg updated this revision to Diff 848.Aug 13 2017, 2:18 PM
Closed by commit rHG558f5b2ee10e: repository: formalize wire protocol interface (authored by indygreg). · Explain WhyAug 15 2017, 1:51 PM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mmercurial/repository.py (165 lines)

Diff 932

mercurial/repository.py

@abc.abstractmethod @abc.abstractmethod
def close(self): def close(self):
"""Close the connection to this peer. """Close the connection to this peer.
This is called when the peer will no longer be used. Resources This is called when the peer will no longer be used. Resources
associated with the peer should be cleaned up. associated with the peer should be cleaned up.
""" """
class peer(_basepeer): class _basewirecommands(object):
"""Client-side interface for communicating over the wire protocol.
durin42Unsubmitted
Not Done

spelling: interfac

durin42: spelling: interfac
This interface is used as a gateway to the Mercurial wire protocol.
methods commonly call wire protocol commands of the same name.
"""
__metaclass__ = abc.ABCMeta
@abc.abstractmethod
def branchmap(self):
"""Obtain heads in named branches.
Returns a dict mapping branch name to an iterable of nodes that are
heads on that branch.
"""
@abc.abstractmethod
def capabilities(self):
"""Obtain capabilities of the peer.
Returns a set of string capabilities.
"""
@abc.abstractmethod
def debugwireargs(self, one, two, three=None, four=None, five=None):
"""Used to facilitate debugging of arguments passed over the wire."""
@abc.abstractmethod
def getbundle(self, source, **kwargs):
"""Obtain remote repository data as a bundle.
This command is how the bulk of repository data is transferred from
the peer to the local repository
Returns a generator of bundle data.
"""
@abc.abstractmethod
def heads(self):
"""Determine all known head revisions in the peer.
Returns an iterable of binary nodes.
"""
@abc.abstractmethod
def known(self, nodes):
"""Determine whether multiple nodes are known.
Accepts an iterable of nodes whose presence to check for.
Returns an iterable of booleans indicating of the corresponding node
at that index is known to the peer.
"""
@abc.abstractmethod
def listkeys(self, namespace):
"""Obtain all keys in a pushkey namespace.
Returns an iterable of key names.
"""
@abc.abstractmethod
def lookup(self, key):
"""Resolve a value to a known revision.
Returns a binary node of the resolved revision on success.
"""
@abc.abstractmethod
def pushkey(self, namespace, key, old, new):
"""Set a value using the ``pushkey`` protocol.
Arguments correspond to the pushkey namespace and key to operate on and
the old and new values for that key.
Returns a string with the peer result. The value inside varies by the
namespace.
"""
@abc.abstractmethod
def stream_out(self):
"""Obtain streaming clone data.
Successful result should be a generator of data chunks.
"""
@abc.abstractmethod
def unbundle(self, bundle, heads, url):
"""Transfer repository data to the peer.
This is how the bulk of data during a push is transferred.
Returns the integer number of heads added to the peer.
"""
class _baselegacywirecommands(object):
"""Interface for implementing support for legacy wire protocol commands.
Wire protocol commands transition to legacy status when they are no longer
used by modern clients. To facilitate identifying which commands are
legacy, the interfaces are split.
"""
__metaclass__ = abc.ABCMeta
@abc.abstractmethod
def between(self, pairs):
"""Obtain nodes between pairs of nodes.
``pairs`` is an iterable of node pairs.
Returns an iterable of iterables of nodes corresponding to each
requested pair.
"""
@abc.abstractmethod
def branches(self, nodes):
"""Obtain ancestor changesets of specific nodes back to a branch point.
For each requested node, the peer finds the first ancestor node that is
a DAG root or is a merge.
Returns an iterable of iterables with the resolved values for each node.
"""
@abc.abstractmethod
def changegroup(self, nodes, kind):
"""Obtain a changegroup with data for descendants of specified nodes."""
@abc.abstractmethod
def changegroupsubset(self, bases, heads, kind):
pass
class peer(_basepeer, _basewirecommands):
"""Unified interface and base class for peer repositories. """Unified interface and base class for peer repositories.
All peer instances must inherit from this class. All peer instances must inherit from this class and conform to its
interface.
""" """
@abc.abstractmethod
def iterbatch(self):
"""Obtain an object to be used for multiple method calls.
Various operations call several methods on peer instances. If each
method call were performed immediately and serially, this would
require round trips to remote peers and/or would slow down execution.
Some peers have the ability to "batch" method calls to avoid costly
round trips or to facilitate concurrent execution.
This method returns an object that can be used to indicate intent to
perform batched method calls.
The returned object is a proxy of this peer. It intercepts calls to
batchable methods and queues them instead of performing them
immediately. This proxy object has a ``submit`` method that will
perform all queued batchable method calls. A ``results()`` method
exposes the results of queued/batched method calls. It is a generator
of results in the order they were called.
durin42Unsubmitted
Not Done

Probably also note that at the wireprotocol layer, it is known that not all peers stream batch responses, so it may not behave as a streaming response even though it's a generator (specifically ssh behaves this way)

durin42: Probably also note that at the wireprotocol layer, it is known that not all peers stream batch…
Not all peers or wire protocol implementations may actually batch method
calls. However, they must all support this API.
"""
class legacypeer(peer, _baselegacywirecommands):
"""peer but with support for legacy wire protocol commands."""