PushkeyConcept

General

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.

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.

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.

Implementation Details

The puskey/listkeys interfaces is defined as:

  boolean pushkey  (string identifier, string key, string value, boolean force=False)
  dict    listkeys (string identifier)

The identifier determines which handler to call on the remote site. A short example:

  pushkey('bookmarks', 'my-bookmark', 'aa3dfa...')

As a result the remote site knows to forward the information to the bookmark implementation. Pushkey returns falls if an error occurs during push.

Listkeys will return a key=>value combination. Both local and remote repository have to provide the necessary "capability" to be able to push and list keys.

Push Access

The current concept does not implement any special push/pull access rules. Everybody who has allow_push rights will be able to push keys. Listing of keys is always possible.

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.

See also ArbitraryMetadata.