dulwich/protocol.py

   1 # protocol.py -- Shared parts of the git protocols
   2 # Copyright (C) 2008 John Carr <john.carr@unrouted.co.uk>
   3 # Copyright (C) 2008-2012 Jelmer Vernooij <jelmer@samba.org>
   4 #
   5 # This program is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU General Public License
   7 # as published by the Free Software Foundation; version 2
   8 # or (at your option) any later version of the License.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  18 # MA  02110-1301, USA.
  19
  20 """Generic functions for talking the git smart server protocol."""
  21
  22 from io import BytesIO
  23 from os import (
  24     SEEK_END,
  25     )
  26 import socket
  27
  28 from dulwich.errors import (
  29     HangupException,
  30     GitProtocolError,
  31     )
  32
  33 TCP_GIT_PORT = 9418
  34
  35 ZERO_SHA = "0" * 40
  36
  37 SINGLE_ACK = 0
  38 MULTI_ACK = 1
  39 MULTI_ACK_DETAILED = 2
  40
  41
  42 class ProtocolFile(object):
  43     """A dummy file for network ops that expect file-like objects."""
  44
  45     def __init__(self, read, write):
  46         self.read = read
  47         self.write = write
  48
  49     def tell(self):
  50         pass
  51
  52     def close(self):
  53         pass
  54
  55
  56 def pkt_line(data):
  57     """Wrap data in a pkt-line.
  58
  59     :param data: The data to wrap, as a str or None.
  60     :return: The data prefixed with its length in pkt-line format; if data was
  61         None, returns the flush-pkt ('0000').
  62     """
  63     if data is None:
  64         return '0000'
  65     return '%04x%s' % (len(data) + 4, data)
  66
  67
  68 class Protocol(object):
  69     """Class for interacting with a remote git process over the wire.
  70
  71     Parts of the git wire protocol use 'pkt-lines' to communicate. A pkt-line
  72     consists of the length of the line as a 4-byte hex string, followed by the
  73     payload data. The length includes the 4-byte header. The special line '0000'
  74     indicates the end of a section of input and is called a 'flush-pkt'.
  75
  76     For details on the pkt-line format, see the cgit distribution:
  77         Documentation/technical/protocol-common.txt
  78     """
  79
  80     def __init__(self, read, write, report_activity=None):
  81         self.read = read
  82         self.write = write
  83         self.report_activity = report_activity
  84         self._readahead = None
  85
  86     def read_pkt_line(self):
  87         """Reads a pkt-line from the remote git process.
  88
  89         This method may read from the readahead buffer; see unread_pkt_line.
  90
  91         :return: The next string from the stream, without the length prefix, or
  92             None for a flush-pkt ('0000').
  93         """
  94         if self._readahead is None:
  95             read = self.read
  96         else:
  97             read = self._readahead.read
  98             self._readahead = None
  99
 100         try:
 101             sizestr = read(4)
 102             if not sizestr:
 103                 raise HangupException()
 104             size = int(sizestr, 16)
 105             if size == 0:
 106                 if self.report_activity:
 107                     self.report_activity(4, 'read')
 108                 return None
 109             if self.report_activity:
 110                 self.report_activity(size, 'read')
 111             return read(size-4)
 112         except socket.error as e:
 113             raise GitProtocolError(e)
 114
 115     def eof(self):
 116         """Test whether the protocol stream has reached EOF.
 117
 118         Note that this refers to the actual stream EOF and not just a flush-pkt.
 119
 120         :return: True if the stream is at EOF, False otherwise.
 121         """
 122         try:
 123             next_line = self.read_pkt_line()
 124         except HangupException:
 125             return True
 126         self.unread_pkt_line(next_line)
 127         return False
 128
 129     def unread_pkt_line(self, data):
 130         """Unread a single line of data into the readahead buffer.
 131
 132         This method can be used to unread a single pkt-line into a fixed
 133         readahead buffer.
 134
 135         :param data: The data to unread, without the length prefix.
 136         :raise ValueError: If more than one pkt-line is unread.
 137         """
 138         if self._readahead is not None:
 139             raise ValueError('Attempted to unread multiple pkt-lines.')
 140         self._readahead = BytesIO(pkt_line(data))
 141
 142     def read_pkt_seq(self):
 143         """Read a sequence of pkt-lines from the remote git process.
 144
 145         :return: Yields each line of data up to but not including the next flush-pkt.
 146         """
 147         pkt = self.read_pkt_line()
 148         while pkt:
 149             yield pkt
 150             pkt = self.read_pkt_line()
 151
 152     def write_pkt_line(self, line):
 153         """Sends a pkt-line to the remote git process.
 154
 155         :param line: A string containing the data to send, without the length
 156             prefix.
 157         """
 158         try:
 159             line = pkt_line(line)
 160             self.write(line)
 161             if self.report_activity:
 162                 self.report_activity(len(line), 'write')
 163         except socket.error as e:
 164             raise GitProtocolError(e)
 165
 166     def write_file(self):
 167         """Return a writable file-like object for this protocol."""
 168
 169         class ProtocolFile(object):
 170
 171             def __init__(self, proto):
 172                 self._proto = proto
 173                 self._offset = 0
 174
 175             def write(self, data):
 176                 self._proto.write(data)
 177                 self._offset += len(data)
 178
 179             def tell(self):
 180                 return self._offset
 181
 182             def close(self):
 183                 pass
 184
 185         return ProtocolFile(self)
 186
 187     def write_sideband(self, channel, blob):
 188         """Write multiplexed data to the sideband.
 189
 190         :param channel: An int specifying the channel to write to.
 191         :param blob: A blob of data (as a string) to send on this channel.
 192         """
 193         # a pktline can be a max of 65520. a sideband line can therefore be
 194         # 65520-5 = 65515
 195         # WTF: Why have the len in ASCII, but the channel in binary.
 196         while blob:
 197             self.write_pkt_line("%s%s" % (chr(channel), blob[:65515]))
 198             blob = blob[65515:]
 199
 200     def send_cmd(self, cmd, *args):
 201         """Send a command and some arguments to a git server.
 202
 203         Only used for the TCP git protocol (git://).
 204
 205         :param cmd: The remote service to access.
 206         :param args: List of arguments to send to remove service.
 207         """
 208         self.write_pkt_line("%s %s" % (cmd, "".join(["%s\0" % a for a in args])))
 209
 210     def read_cmd(self):
 211         """Read a command and some arguments from the git client
 212
 213         Only used for the TCP git protocol (git://).
 214
 215         :return: A tuple of (command, [list of arguments]).
 216         """
 217         line = self.read_pkt_line()
 218         splice_at = line.find(" ")
 219         cmd, args = line[:splice_at], line[splice_at+1:]
 220         assert args[-1] == "\x00"
 221         return cmd, args[:-1].split(chr(0))
 222
 223
 224 _RBUFSIZE = 8192  # Default read buffer size.
 225
 226
 227 class ReceivableProtocol(Protocol):
 228     """Variant of Protocol that allows reading up to a size without blocking.
 229
 230     This class has a recv() method that behaves like socket.recv() in addition
 231     to a read() method.
 232
 233     If you want to read n bytes from the wire and block until exactly n bytes
 234     (or EOF) are read, use read(n). If you want to read at most n bytes from the
 235     wire but don't care if you get less, use recv(n). Note that recv(n) will
 236     still block until at least one byte is read.
 237     """
 238
 239     def __init__(self, recv, write, report_activity=None, rbufsize=_RBUFSIZE):
 240         super(ReceivableProtocol, self).__init__(self.read, write,
 241                                                  report_activity)
 242         self._recv = recv
 243         self._rbuf = BytesIO()
 244         self._rbufsize = rbufsize
 245
 246     def read(self, size):
 247         # From _fileobj.read in socket.py in the Python 2.6.5 standard library,
 248         # with the following modifications:
 249         #  - omit the size <= 0 branch
 250         #  - seek back to start rather than 0 in case some buffer has been
 251         #    consumed.
 252         #  - use SEEK_END instead of the magic number.
 253         # Copyright (c) 2001-2010 Python Software Foundation; All Rights Reserved
 254         # Licensed under the Python Software Foundation License.
 255         # TODO: see if buffer is more efficient than cBytesIO.
 256         assert size > 0
 257
 258         # Our use of BytesIO rather than lists of string objects returned by
 259         # recv() minimizes memory usage and fragmentation that occurs when
 260         # rbufsize is large compared to the typical return value of recv().
 261         buf = self._rbuf
 262         start = buf.tell()
 263         buf.seek(0, SEEK_END)
 264         # buffer may have been partially consumed by recv()
 265         buf_len = buf.tell() - start
 266         if buf_len >= size:
 267             # Already have size bytes in our buffer?  Extract and return.
 268             buf.seek(start)
 269             rv = buf.read(size)
 270             self._rbuf = BytesIO()
 271             self._rbuf.write(buf.read())
 272             self._rbuf.seek(0)
 273             return rv
 274
 275         self._rbuf = BytesIO()  # reset _rbuf.  we consume it via buf.
 276         while True:
 277             left = size - buf_len
 278             # recv() will malloc the amount of memory given as its
 279             # parameter even though it often returns much less data
 280             # than that.  The returned data string is short lived
 281             # as we copy it into a BytesIO and free it.  This avoids
 282             # fragmentation issues on many platforms.
 283             data = self._recv(left)
 284             if not data:
 285                 break
 286             n = len(data)
 287             if n == size and not buf_len:
 288                 # Shortcut.  Avoid buffer data copies when:
 289                 # - We have no data in our buffer.
 290                 # AND
 291                 # - Our call to recv returned exactly the
 292                 #   number of bytes we were asked to read.
 293                 return data
 294             if n == left:
 295                 buf.write(data)
 296                 del data  # explicit free
 297                 break
 298             assert n <= left, "_recv(%d) returned %d bytes" % (left, n)
 299             buf.write(data)
 300             buf_len += n
 301             del data  # explicit free
 302             #assert buf_len == buf.tell()
 303         buf.seek(start)
 304         return buf.read()
 305
 306     def recv(self, size):
 307         assert size > 0
 308
 309         buf = self._rbuf
 310         start = buf.tell()
 311         buf.seek(0, SEEK_END)
 312         buf_len = buf.tell()
 313         buf.seek(start)
 314
 315         left = buf_len - start
 316         if not left:
 317             # only read from the wire if our read buffer is exhausted
 318             data = self._recv(self._rbufsize)
 319             if len(data) == size:
 320                 # shortcut: skip the buffer if we read exactly size bytes
 321                 return data
 322             buf = BytesIO()
 323             buf.write(data)
 324             buf.seek(0)
 325             del data  # explicit free
 326             self._rbuf = buf
 327         return buf.read(size)
 328
 329
 330 def extract_capabilities(text):
 331     """Extract a capabilities list from a string, if present.
 332
 333     :param text: String to extract from
 334     :return: Tuple with text with capabilities removed and list of capabilities
 335     """
 336     if not "\0" in text:
 337         return text, []
 338     text, capabilities = text.rstrip().split("\0")
 339     return (text, capabilities.strip().split(" "))
 340
 341
 342 def extract_want_line_capabilities(text):
 343     """Extract a capabilities list from a want line, if present.
 344
 345     Note that want lines have capabilities separated from the rest of the line
 346     by a space instead of a null byte. Thus want lines have the form:
 347
 348         want obj-id cap1 cap2 ...
 349
 350     :param text: Want line to extract from
 351     :return: Tuple with text with capabilities removed and list of capabilities
 352     """
 353     split_text = text.rstrip().split(" ")
 354     if len(split_text) < 3:
 355         return text, []
 356     return (" ".join(split_text[:2]), split_text[2:])
 357
 358
 359 def ack_type(capabilities):
 360     """Extract the ack type from a capabilities list."""
 361     if 'multi_ack_detailed' in capabilities:
 362         return MULTI_ACK_DETAILED
 363     elif 'multi_ack' in capabilities:
 364         return MULTI_ACK
 365     return SINGLE_ACK
 366
 367
 368 class BufferedPktLineWriter(object):
 369     """Writer that wraps its data in pkt-lines and has an independent buffer.
 370
 371     Consecutive calls to write() wrap the data in a pkt-line and then buffers it
 372     until enough lines have been written such that their total length (including
 373     length prefix) reach the buffer size.
 374     """
 375
 376     def __init__(self, write, bufsize=65515):
 377         """Initialize the BufferedPktLineWriter.
 378
 379         :param write: A write callback for the underlying writer.
 380         :param bufsize: The internal buffer size, including length prefixes.
 381         """
 382         self._write = write
 383         self._bufsize = bufsize
 384         self._wbuf = BytesIO()
 385         self._buflen = 0
 386
 387     def write(self, data):
 388         """Write data, wrapping it in a pkt-line."""
 389         line = pkt_line(data)
 390         line_len = len(line)
 391         over = self._buflen + line_len - self._bufsize
 392         if over >= 0:
 393             start = line_len - over
 394             self._wbuf.write(line[:start])
 395             self.flush()
 396         else:
 397             start = 0
 398         saved = line[start:]
 399         self._wbuf.write(saved)
 400         self._buflen += len(saved)
 401
 402     def flush(self):
 403         """Flush all data from the buffer."""
 404         data = self._wbuf.getvalue()
 405         if data:
 406             self._write(data)
 407         self._len = 0
 408         self._wbuf = BytesIO()
 409
 410
 411 class PktLineParser(object):
 412     """Packet line parser that hands completed packets off to a callback.
 413     """
 414
 415     def __init__(self, handle_pkt):
 416         self.handle_pkt = handle_pkt
 417         self._readahead = BytesIO()
 418
 419     def parse(self, data):
 420         """Parse a fragment of data and call back for any completed packets.
 421         """
 422         self._readahead.write(data)
 423         buf = self._readahead.getvalue()
 424         if len(buf) < 4:
 425             return
 426         while len(buf) >= 4:
 427             size = int(buf[:4], 16)
 428             if size == 0:
 429                 self.handle_pkt(None)
 430                 buf = buf[4:]
 431             elif size <= len(buf):
 432                 self.handle_pkt(buf[4:size])
 433                 buf = buf[size:]
 434             else:
 435                 break
 436         self._readahead = BytesIO()
 437         self._readahead.write(buf)
 438
 439     def get_tail(self):
 440         """Read back any unused data."""
 441         return self._readahead.getvalue()