bundle2: support bundling simple parameter
This changeset add bundling capacity for simple parameters, not value or any
special case are handled.
# bundle2.py - generic container format to transmit arbitrary data.
#
# Copyright 2013 Facebook, Inc.
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.
"""Handling of the new bundle2 format
The goal of bundle2 is to act as an atomically packet to transmit a set of
payloads in an application agnostic way. It consist in a sequence of "parts"
that will be handed to and processed by the application layer.
General format architecture
===========================
The format is architectured as follow
- magic string
- stream level parameters
- payload parts (any number)
- end of stream marker.
The current implementation accept some stream level option but no part.
Details on the Binary format
============================
All numbers are unsigned and big endian.
stream level parameters
------------------------
Binary format is as follow
:params size: (16 bits integer)
The total number of Bytes used by the parameters
:params value: arbitrary number of Bytes
A blob of `params size` containing the serialized version of all stream level
parameters.
The blob contains a space separated list of parameters.
Parameter value are not supported yet.
Special character in param name are not supported yet.
Payload part
------------------------
Binary format is as follow
:header size: (16 bits inter)
The total number of Bytes used by the part headers. When the header is empty
(size = 0) this is interpreted as the end of stream marker.
Currently forced to 0 in the current state of the implementation
"""
import util
import struct
import changegroup
from i18n import _
_pack = struct.pack
_unpack = struct.unpack
_magicstring = 'HG20'
_fstreamparamsize = '>H'
class bundle20(object):
"""represent an outgoing bundle2 container
Use the `addparam` method to add stream level parameter. Then call
`getchunks` to retrieve all the binary chunks of datathat compose the
bundle2 container.
This object does not support payload part yet."""
def __init__(self):
self._params = []
self._parts = []
def addparam(self, name, value=None):
"""add a stream level parameter"""
self._params.append((name, value))
def getchunks(self):
yield _magicstring
param = self._paramchunk()
yield _pack(_fstreamparamsize, len(param))
if param:
yield param
# no support for parts
# to be obviously fixed soon.
assert not self._parts
yield '\0\0'
def _paramchunk(self):
"""return a encoded version of all stream parameters"""
blocks = []
for key, value in self._params:
# XXX no support for value yet
assert value is None
# XXX no escaping yet
blocks.append(key)
return ' '.join(blocks)
class unbundle20(object):
"""interpret a bundle2 stream
(this will eventually yield parts)"""
def __init__(self, fp):
self._fp = fp
header = self._readexact(4)
magic, version = header[0:2], header[2:4]
if magic != 'HG':
raise util.Abort(_('not a Mercurial bundle'))
if version != '20':
raise util.Abort(_('unknown bundle version %s') % version)
def _unpack(self, format):
"""unpack this struct format from the stream"""
data = self._readexact(struct.calcsize(format))
return _unpack(format, data)
def _readexact(self, size):
"""read exactly <size> bytes from the stream"""
return changegroup.readexactly(self._fp, size)
@util.propertycache
def params(self):
"""dictionnary of stream level parameters"""
paramsize = self._readexact(2)
assert paramsize == '\0\0'
return {}
def __iter__(self):
"""yield all parts contained in the stream"""
# make sure param have been loaded
self.params
part = self._readpart()
while part is not None:
yield part
part = self._readpart()
def _readpart(self):
"""return None when an end of stream markers is reach"""
headersize = self._readexact(2)
assert headersize == '\0\0'
return None