message.js

/*
  Implementation of an SSH2 "message".

  An SSH2 I{Message} is a stream of bytes that encodes some combination of
  strings, integers, bools, and infinite-precision integers (known in python
  as I{long}s).  This class builds or breaks down such a byte stream.
  
  Normally you don't need to deal with anything this low-level, but it's
  exposed for people implementing custom extensions, or features that
  paramiko doesn't support yet.
*/

paramikojs.Message = function(content) {
  /*
    Create a new SSH2 Message.

    @param content: the byte stream to use as the Message content (passed
        in only when decomposing a Message).
    @type content: string
  */
  if (content) {
    this.packet = new String(content);
  } else {
    this.packet = new String();
  }
  this.position = 0;
}

paramikojs.Message.prototype = {
  toString : function() {
    return this.packet;
  },

  /*
    Rewind the message to the beginning as if no items had been parsed
    out of it yet.
  */
  rewind : function() {
    this.position = 0;
  },

  /*
    Return the bytes of this Message that haven't already been parsed and
    returned.

    @return: a string of the bytes not parsed yet.
    @rtype: string
  */
  get_remainder : function() {
    return this.packet.substring(this.position);
  },

  /*
    Returns the bytes of this Message that have been parsed and returned.
    The string passed into a Message's constructor can be regenerated by
    concatenating C{get_so_far} and L{get_remainder}.

    @return: a string of the bytes parsed so far.
    @rtype: string
  */
  get_so_far : function() {
    return this.packet.substring(0, this.position);
  },

  /*
    Return the next C{n} bytes of the Message, without decomposing into
    an int, string, etc.  Just the raw bytes are returned.

    @return: a string of the next C{n} bytes of the Message, or a string
        of C{n} zero bytes, if there aren't C{n} bytes remaining.
    @rtype: string
  */
  get_bytes : function(n) {
    var b = this.packet.substring(this.position, this.position + n);
    this.position += n;
    var max_pad_size = 1 << 20;  // Limit padding to 1 MB
    if (b.length < n && n < max_pad_size) {
      return b + new Array(n - b.length + 1).join('\x00');
    }
    return b;
  },

  /*
    Return the next byte of the Message, without decomposing it.  This
    is equivalent to L{get_bytes(1)<get_bytes>}.

    @return: the next byte of the Message, or C{'\000'} if there aren't
        any bytes remaining.
    @rtype: string
  */
  get_byte : function() {
    return this.get_bytes(1);
  },

  /*
    Fetch a boolean from the stream.

    @return: C{True} or C{False} (from the Message).
    @rtype: bool
  */
  get_boolean : function() {
    var b = this.get_bytes(1);
    return b != '\x00';
  },

  /*
    Fetch an int from the stream.

    @return: a 32-bit unsigned integer.
    @rtype: int
  */
  get_int : function() {
    return struct.unpack('>I', this.get_bytes(4))[0];
  },
  
  /*
    Fetch a 64-bit int from the stream.

    @return: a 64-bit unsigned integer.
    @rtype: long
  */
  get_int64 : function() {
    return struct.unpack('>Q', this.get_bytes(8))[0];
  },

  /*
    Fetch a long int (mpint) from the stream.

    @return: an arbitrary-length integer.
    @rtype: long
  */
  get_mpint : function() {
    return paramikojs.util.inflate_long(this.get_string());
  },

  /*
    Fetch a string from the stream.  This could be a byte string and may
    contain unprintable characters.  (It's not unheard of for a string to
    contain another byte-stream Message.)

    @return: a string.
    @rtype: string
  */
  get_string : function() {
    return this.get_bytes(this.get_int());
  },

  /*
    Fetch a list of strings from the stream.  These are trivially encoded
    as comma-separated values in a string.

    @return: a list of strings.
    @rtype: list of strings
  */
  get_list : function() {
    return this.get_string().split(',');
  },

  /*
    Write bytes to the stream, without any formatting.
    
    @param b: bytes to add
    @type b: str
  */
  add_bytes : function(b) {
    this.packet += b;
    return this;
  },

  /*
    Write a single byte to the stream, without any formatting.
    
    @param b: byte to add
    @type b: str
  */
  add_byte : function(b) {
    this.packet += b;
    return this;
  },

  /*
    Add a boolean value to the stream.
    
    @param b: boolean value to add
    @type b: bool
  */
  add_boolean : function(b) {
    if (b) {
      this.add_byte('\x01');
    } else {
      this.add_byte('\x00');
    }
    return this;
  },

  /*
    Add an integer to the stream.
    
    @param n: integer to add
    @type n: int
  */
  add_int : function(n) {
    this.packet += struct.pack('>I', n);
    return this;
  },

  /*
    Add a 64-bit int to the stream.

    @param n: long int to add
    @type n: long
  */
  add_int64 : function(n) {
    this.packet += struct.pack('>Q', n);
    return this;
  },

  /*
    Add a long int to the stream, encoded as an infinite-precision
    integer.  This method only works on positive numbers.
    
    @param z: long int to add
    @type z: long
  */
  add_mpint : function(z) {
    this.add_string(paramikojs.util.deflate_long(z));
    return this;
  },

  /*
    Add a string to the stream.
    
    @param s: string to add
    @type s: str
  */
  add_string : function(s) {
    this.add_int(s.length);
    this.packet += s;
    return this;
  },

  /*
    Add a list of strings to the stream.  They are encoded identically to
    a single string of values separated by commas.  (Yes, really, that's
    how SSH2 does it.)
    
    @param l: list of strings to add
    @type l: list(str)
  */
  add_list : function(l) {
    this.add_string(l.join(','));
    return this;
  },
    
  _add : function(i) {
    if (typeof i == "string") {
      return this.add_string(i);
    } else if (typeof i == "number") {
      return this.add_int(i);
    } else if (i instanceof BigInteger) {
      return this.add_mpint(i);
    } else if (typeof i == "boolean") {
      return this.add_boolean(i);
    } else if (i instanceof Array) {
      return this.add_list(i);
    } else {
      throw 'Unknown type';
    }
  },

  /*
    Add a sequence of items to the stream.  The values are encoded based
    on their type: str, int, bool, list, or long.
    
    @param seq: the sequence of items
    @type seq: sequence
    
    @bug: longs are encoded non-deterministically.  Don't use this method.
  */
  add : function() {
    for (var x = 0; x < arguments.length; ++x) {
      this._add(arguments[x]);
    }
  }
};