# repository.py - Interfaces and base classes for repositories and peers.

#

# Copyright 2017 Gregory Szorc <gregory.szorc@gmail.com>

#

# 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

from .i18n import _

from .thirdparty.zope import (

    interface as zi,

)

from . import (

    error,

)

class ipeerconnection(zi.Interface):

    """Represents a "connection" to a repository.

    This is the base interface for representing a connection to a repository.

    It holds basic properties and methods applicable to all peer types.

    This is not a complete interface definition and should not be used

    outside of this module.

    """

    ui = zi.Attribute("""ui.ui instance""")

    def url():

        """Returns a URL string representing this peer.

        Currently, implementations expose the raw URL used to construct the

        instance. It may contain credentials as part of the URL. The

        expectations of the value aren't well-defined and this could lead to

        data leakage.

        TODO audit/clean consumers and more clearly define the contents of this

        value.

        """

    def local():

        """Returns a local repository instance.

        If the peer represents a local repository, returns an object that

        can be used to interface with it. Otherwise returns ``None``.

        """

    def peer():

        """Returns an object conforming to this interface.

        Most implementations will ``return self``.

        """

    def canpush():

        """Returns a boolean indicating if this peer can be pushed to."""

    def close():

        """Close the connection to this peer.

        This is called when the peer will no longer be used. Resources

        associated with the peer should be cleaned up.

        """

class ipeercommands(zi.Interface):

    """Client-side interface for communicating over the wire protocol.

    This interface is used as a gateway to the Mercurial wire protocol.

    methods commonly call wire protocol commands of the same name.

    """

    def branchmap():

        """Obtain heads in named branches.

        Returns a dict mapping branch name to an iterable of nodes that are

        heads on that branch.

        """

    def capabilities():

        """Obtain capabilities of the peer.

        Returns a set of string capabilities.

        """

    def debugwireargs(one, two, three=None, four=None, five=None):

        """Used to facilitate debugging of arguments passed over the wire."""

    def getbundle(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.

        """

    def heads():

        """Determine all known head revisions in the peer.

        Returns an iterable of binary nodes.

        """

    def known(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.

        """

    def listkeys(namespace):

        """Obtain all keys in a pushkey namespace.

        Returns an iterable of key names.

        """

    def lookup(key):

        """Resolve a value to a known revision.

        Returns a binary node of the resolved revision on success.

        """

    def pushkey(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.

        """

    def stream_out():

        """Obtain streaming clone data.

        Successful result should be a generator of data chunks.

        """

    def unbundle(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 ipeerlegacycommands(zi.Interface):

    """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.

    """

    def between(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.

        """

    def branches(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.

        """

    def changegroup(nodes, kind):

        """Obtain a changegroup with data for descendants of specified nodes."""

    def changegroupsubset(bases, heads, kind):

        pass

    """Unified interface for peer repositories.

    All peer instances must conform to this interface.

    """

    def iterbatch():

        """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.

        Not all peers or wire protocol implementations may actually batch method

        calls. However, they must all support this API.

        """

class ipeerbaselegacycommands(ipeerbase, ipeerlegacycommands):

    """Unified peer interface that supports legacy commands."""

@zi.implementer(ipeerbase)

class peer(object):

    """Base class for peer repositories."""

    def capable(self, name):

        caps = self.capabilities()

        if name in caps:

            return True

        name = '%s=' % name

        for cap in caps:

            if cap.startswith(name):

                return cap[len(name):]

        return False

    def requirecap(self, name, purpose):

        if self.capable(name):

            return

        raise error.CapabilityError(

            _('cannot %s; remote repository does not support the %r '

              'capability') % (purpose, name))

@zi.implementer(ipeerbaselegacycommands)

class legacypeer(peer):

    """peer but with support for legacy wire protocol commands."""

class ifilerevisionssequence(zi.Interface):

    """Contains index data for all revisions of a file.

    Types implementing this behave like lists of tuples. The index

    in the list corresponds to the revision number. The values contain

    index metadata.

    The *null* revision (revision number -1) is always the last item

    in the index.

    """

    def __len__():

        """The total number of revisions."""

    def __getitem__(rev):

        """Returns the object having a specific revision number.

        Returns an 8-tuple with the following fields:

        offset+flags

           Contains the offset and flags for the revision. 64-bit unsigned

           integer where first 6 bytes are the offset and the next 2 bytes

           are flags. The offset can be 0 if it is not used by the store.

        compressed size

            Size of the revision data in the store. It can be 0 if it isn't

            needed by the store.

        uncompressed size

            Fulltext size. It can be 0 if it isn't needed by the store.

        base revision

            Revision number of revision the delta for storage is encoded

            against. -1 indicates not encoded against a base revision.

        link revision

            Revision number of changelog revision this entry is related to.

        p1 revision

            Revision number of 1st parent. -1 if no 1st parent.

        p2 revision

            Revision number of 2nd parent. -1 if no 1st parent.

        node

            Binary node value for this revision number.

        Negative values should index off the end of the sequence. ``-1``

        should return the null revision. ``-2`` should return the most

        recent revision.

        """

    def __contains__(rev):

        """Whether a revision number exists."""

    def insert(self, i, entry):

        """Add an item to the index at specific revision."""

class ifileindex(zi.Interface):

    """Storage interface for index data of a single file.

    File storage data is divided into index metadata and data storage.

    This interface defines the index portion of the interface.

    The index logically consists of:

    * A mapping between revision numbers and nodes.

    * DAG data (storing and querying the relationship between nodes).

    * Metadata to facilitate storage.

    """

    index = zi.Attribute(

        """An ``ifilerevisionssequence`` instance.""")

    def __len__():

        """Obtain the number of revisions stored for this file."""

    def __iter__():

        """Iterate over revision numbers for this file."""

    def revs(start=0, stop=None):

        """Iterate over revision numbers for this file, with control."""

    def parents(node):

        """Returns a 2-tuple of parent nodes for a revision.

        Values will be ``nullid`` if the parent is empty.

        """

    def parentrevs(rev):

        """Like parents() but operates on revision numbers."""

    def rev(node):

        """Obtain the revision number given a node.

        Raises ``error.LookupError`` if the node is not known.

        """

    def node(rev):

        """Obtain the node value given a revision number.

        Raises ``IndexError`` if the node is not known.

        """

    def lookup(node):

        """Attempt to resolve a value to a node.

        Value can be a binary node, hex node, revision number, or a string

        that can be converted to an integer.

        Raises ``error.LookupError`` if a node could not be resolved.

        """

    def linkrev(rev):

        """Obtain the changeset revision number a revision is linked to."""

    def flags(rev):

        """Obtain flags used to affect storage of a revision."""

    def iscensored(rev):

        """Return whether a revision's content has been censored."""

    def commonancestorsheads(node1, node2):

        """Obtain an iterable of nodes containing heads of common ancestors.

        See ``ancestor.commonancestorsheads()``.

        """

    def descendants(revs):

        """Obtain descendant revision numbers for a set of revision numbers.

        If ``nullrev`` is in the set, this is equivalent to ``revs()``.

        """

    def headrevs():

        """Obtain a list of revision numbers that are DAG heads.

        The list is sorted oldest to newest.

        TODO determine if sorting is required.

        """

    def heads(start=None, stop=None):

        """Obtain a list of nodes that are DAG heads, with control.

        The set of revisions examined can be limited by specifying

        ``start`` and ``stop``. ``start`` is a node. ``stop`` is an

        iterable of nodes. DAG traversal starts at earlier revision

        ``start`` and iterates forward until any node in ``stop`` is

        encountered.

        """

    def children(node):

        """Obtain nodes that are children of a node.

        Returns a list of nodes.

        """

    def deltaparent(rev):

        """"Return the revision that is a suitable parent to delta against."""

    def candelta(baserev, rev):

        """"Whether a delta can be generated between two revisions."""

class ifiledata(zi.Interface):

    """Storage interface for data storage of a specific file.

    This complements ``ifileindex`` and provides an interface for accessing

    data for a tracked file.

    """

    def rawsize(rev):

        """The size of the fulltext data for a revision as stored."""

    def size(rev):

        """Obtain the fulltext size of file data.

        Any metadata is excluded from size measurements. Use ``rawsize()`` if

        metadata size is important.

        """

    def checkhash(fulltext, node, p1=None, p2=None, rev=None):

        """Validate the stored hash of a given fulltext and node.

        Raises ``error.RevlogError`` is hash validation fails.

        """

    def revision(node, raw=False):

        """"Obtain fulltext data for a node.

        By default, any storage transformations are applied before the data

        is returned. If ``raw`` is True, non-raw storage transformations

        are not applied.

        The fulltext data may contain a header containing metadata. Most

        consumers should use ``read()`` to obtain the actual file data.

        """

    def read(node):