[RFC] Pushkey Concept

Brodie Rao dackze at gmail.com
Tue Sep 22 18:47:22 CDT 2009


On Sep 20, 2009, at 5:37 PM, David Soria Parra wrote:

> As you might have already noticed, I'm currently working on an
> implementation for pushable bookmarks. As the current wire protocol
> doesn't allow to push and pull unversioned changes we need a extension
> to the wire protocol to do this. The following proposal should give  
> you
> an idea how it should work and what other usages the so called  
> 'pushkey'
> concept might have.
>
> As earlier attemps by me to implement pushable bookmarks raised
> concerns, I would prefer if we can first discusst he RFC before I can
> finish the implementation.
>
> Goal:
> I think it is good to have a very strict wire protocol. This will make
> it more robust and forward compatible. Also, the extension should not
> break any existing code and should be 100% backward compatible.
>
> Idea:
> I suggest to add a mechanism to push and pull key-value-pairs of  
> encoded
> strings, e.g.: {'mybookmark': 'a3bc45a...'}.
> The transfer encoding is utf-8. key-value-pairs are grouped into  
> namespaces
> to make it easier to distinguish bookmarks from other usages.

What do you mean by transfer encoding? Will the on-disk encoding be  
undefined? If so, why would it matter how it goes over the wire? I  
assume it'll be serialized before it goes over anyway.

> A 'pushkey' capable remote repository implements a pushkey()
> call and a listkey() call. A call to listkey() returns a dictionary of
> key-value-pairs matching a given namespace. A pushkey() call pushes a
> given key-value-pair to the remote.
>
> - puskey(string namespace, string key, string value, boolean  
> force=False)
> - listkeys(string namespace)

I agree with djc that pushkey() should accept a dict of dicts.

Also, shouldn't they be named pushkeys() and listkeys()?

> The logic to handle a pushed or pulled key is done by the code that  
> uses
> the key. In other words, bookmarks handle bookmark keys. This is  
> needed
> as for example bookmark might react in other ways to a --force than
> ohter uses of pushkey. To keep the protocol strict it is not planned  
> to
> let extensions hook into the handling, meaning that all code dealing  
> with
> pushkey and listkey remain in mercurials core.
>
> A new 'puskey' capability is added to check if source and remote  
> support
> the protocol extension.
>
> Storage:
> Unlike earlier suggestions, I think that storing key and values should
> be done by the code that uses them. This means that bookmarks will  
> still store
> the bookmarks in .hg/bookmarks, ensuring backward compatibiltiy and
> efficient storage. This is particularly useful if we want to use the
> pushkey concept for example with localtags.

Some questions:

- So if I'm reading this right, the burden of keys being pushed out is  
placed on the extension/user of the API? And there won't be any sort  
of central store for this data?

- When an extension does localrepo.pushkeys({'foo': {...}, 'bar':  
{...}), .hg/foo and .hg/bar will be created if they don't exist, and  
then modified/updated?

- How exactly does the force parameter work?

> Other usages:
> Other parts of the code might also benefit from the protocol  
> extension.
> I can imagine that it might be useful to be able to push and pull
> lightweigt tags (currently called localtags).
>
> Other open questions:
> I'm not sure how to handle large dictionaries returned by listkeys().
> Should they be pickled() or split into chunks?
>
> I'll update the wiki page at http://mercurial.selenic.com/wiki/PushkeyConcept
>
> Once we discussed a good transfer mechanism I'll come up with some  
> more
> details about pushable bookmarks in general.
>
> So please discuss.

Other thoughts:

- It'd be nice to see a brief outline of use cases on the wiki (e.g.  
bookmarks, bugmap, signing, hg-git, etc). You can inform your  
decisions on the pushkey spec/implementation based on the requirements  
of the different use cases.

- I agree that pickle is a bad idea. JSON sounds fine. Using zlib  
seems reasonable too.

- Having a meta-repo definitely sounds like the wrong approach.

- Some basic example code on the extension side would be nice to have  
in the spec.


More information about the Mercurial-devel mailing list