Source: encoding/protobuf-tlv.js

  1. /**
  2.  * Copyright (C) 2014-2018 Regents of the University of California.
  3.  * @author: Jeff Thompson <jefft0@remap.ucla.edu>
  4.  *
  5.  * This program is free software: you can redistribute it and/or modify
  6.  * it under the terms of the GNU Lesser General Public License as published by
  7.  * the Free Software Foundation, either version 3 of the License, or
  8.  * (at your option) any later version.
  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 Lesser General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Lesser General Public License
  16.  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17.  * A copy of the GNU Lesser General Public License is in the file COPYING.
  18.  */
  20. /** @ignore */
  21. var TlvEncoder = require('./tlv/tlv-encoder.js').TlvEncoder; /** @ignore */
  22. var TlvDecoder = require('./tlv/tlv-decoder.js').TlvDecoder; /** @ignore */
  23. var Blob = require('../util/blob.js').Blob; /** @ignore */
  24. var Name = require('../name.js').Name; /** @ignore */
  26. /**
  27.  * ProtobufTlv has static methods to encode and decode an Protobuf Message
  28.  * object as NDN-TLV. The Protobuf tag value is used as the TLV type code. A
  29.  * Protobuf message is encoded/decoded as a nested TLV encoding. Protobuf types
  30.  * uint32, uint64 and enum are encoded/decoded as TLV nonNegativeInteger. (It is
  31.  * an error if an enum value is negative.) Protobuf types bytes and string are
  32.  * encoded/decoded as TLV bytes. The Protobuf type bool is encoded/decoded as a
  33.  * TLV boolean (a zero length value for True, omitted for False). The Protobuf
  34.  * type double is encoded/decoded as an 8-byte little-endian IEEE 754 double.
  35.  * Other Protobuf types are an error.
  36.  *
  37.  * Protobuf has no "outer" message type, so you need to put your TLV message
  38.  * inside an outer "typeless" message.
  39.  * @constructor
  40.  */
  41. var ProtobufTlv = function ProtobufTlv()
  42. {
  43. };
  45. exports.ProtobufTlv = ProtobufTlv;
  47. // Load ProtoBuf.Reflect.Message.Field dynamically so that protobufjs is optional.
  48. ProtobufTlv._Field = null;
  49. ProtobufTlv.establishField = function()
  50. {
  51.   if (ProtobufTlv._Field === null) {
  52.     try {
  53.       // Using protobuf.min.js in the browser.
  54.       ProtobufTlv._Field = dcodeIO.ProtoBuf.Reflect.Message.Field;
  55.     }
  56.     catch (ex) {
  57.       // Using protobufjs in node.
  58.       ProtobufTlv._Field = require("protobufjs").Reflect.Message.Field;
  59.     }
  60.   }
  61. }
  63. /**
  64.  * Encode the Protobuf message object as NDN-TLV. This calls
  65.  * message.encodeAB() to ensure that all required fields are present and
  66.  * raises an exception if not. (This does not use the result of toArrayBuffer().)
  67.  * @param {ProtoBuf.Builder.Message} message The Protobuf message object.
  68.  * @param {ProtoBuf.Reflect.T} descriptor The reflection descriptor for the
  69.  * message. For example, if the message is of type "MyNamespace.MyMessage" then
  70.  * the descriptor is builder.lookup("MyNamespace.MyMessage").
  71.  * @return {Blob} The encoded buffer in a Blob object.
  72.  */
  73. ProtobufTlv.encode = function(message, descriptor)
  74. {
  75.   ProtobufTlv.establishField();
  77.   message.encodeAB();
  78.   var encoder = new TlvEncoder();
  79.   ProtobufTlv._encodeMessageValue(message, descriptor, encoder);
  80.   return new Blob(encoder.getOutput(), false);
  81. };
  83. /**
  84.  * Decode the input as NDN-TLV and update the fields of the Protobuf message
  85.  * object.
  86.  * @param {ProtoBuf.Builder.Message} message The Protobuf message object. This
  87.  * does not first clear the object.
  88.  * @param {ProtoBuf.Reflect.T} descriptor The reflection descriptor for the
  89.  * message. For example, if the message is of type "MyNamespace.MyMessage" then
  90.  * the descriptor is builder.lookup("MyNamespace.MyMessage").
  91.  * @param {Blob|Buffer} input The buffer with the bytes to decode.
  92.  */
  93. ProtobufTlv.decode = function(message, descriptor, input)
  94. {
  95.   ProtobufTlv.establishField();
  97.   // If input is a blob, get its buf().
  98.   var decodeBuffer = typeof input === 'object' && input instanceof Blob ?
  99.                      input.buf() : input;
  101.   var decoder = new TlvDecoder(decodeBuffer);
  102.   ProtobufTlv._decodeMessageValue
  103.     (message, descriptor, decoder, decodeBuffer.length);
  104. };
  106. ProtobufTlv._encodeMessageValue = function(message, descriptor, encoder)
  107. {
  108.   var fields = descriptor.getChildren(ProtobufTlv._Field);
  109.   // Encode the fields backwards.
  110.   for (var iField = fields.length - 1; iField >= 0; --iField) {
  111.     var field = fields[iField];
  112.     var tlvType = field.id;
  114.     var values;
  115.     if (field.repeated)
  116.       values = message[field.name];
  117.     else {
  118.       if (message[field.name] != null)
  119.         // Make a singleton list.
  120.         values = [message[field.name]];
  121.       else
  122.         continue;
  123.     }
  125.     // Encode the values backwards.
  126.     for (var iValue = values.length - 1; iValue >= 0; --iValue) {
  127.       var value = values[iValue];
  129.       if (field.type.name == "message") {
  130.         var saveLength =  encoder.getLength();
  132.         // Encode backwards.
  133.         ProtobufTlv._encodeMessageValue(value, field.resolvedType, encoder);
  134.         encoder.writeTypeAndLength(tlvType, encoder.getLength() - saveLength);
  135.       }
  136.       else if (field.type.name == "uint32" ||
  137.                field.type.name == "uint64")
  138.         encoder.writeNonNegativeIntegerTlv(tlvType, value);
  139.       else if (field.type.name == "enum") {
  140.         if (value < 0)
  141.           throw new Error("ProtobufTlv.encode: ENUM value may not be negative");
  142.         encoder.writeNonNegativeIntegerTlv(tlvType, value);
  143.       }
  144.       else if (field.type.name == "bytes") {
  145.         var buffer = value.toBuffer();
  146.         if (buffer.length == undefined)
  147.           // We are not running in Node.js, so assume we are using the dcodeIO
  148.           // browser implementation based on ArrayBuffer.
  149.           buffer = new Uint8Array(value.toArrayBuffer());
  150.         encoder.writeBlobTlv(tlvType, buffer);
  151.       }
  152.       else if (field.type.name == "string")
  153.         // Use Blob to convert.
  154.         encoder.writeBlobTlv(tlvType, new Blob(value, false).buf());
  155.       else if (field.type.name == "bool") {
  156.         if (value)
  157.           encoder.writeTypeAndLength(tlvType, 0);
  158.       }
  159.       else if (field.type.name == "double") {
  160.         var encoding = new Buffer(8);
  161.         encoding.writeDoubleLE(value, 0);
  162.         encoder.writeBlobTlv(tlvType, encoding);
  163.       }
  164.       else
  165.         throw new Error("ProtobufTlv.encode: Unknown field type");
  166.     }
  167.   }
  168. };
  170. ProtobufTlv._decodeMessageValue = function(message, descriptor, decoder, endOffset)
  171. {
  172.   var fields = descriptor.getChildren(ProtobufTlv._Field);
  173.   for (var iField = 0; iField < fields.length; ++iField) {
  174.     var field = fields[iField];
  175.     var tlvType = field.id;
  177.     if (!field.required && !decoder.peekType(tlvType, endOffset))
  178.       continue;
  180.     if (field.repeated) {
  181.       while (decoder.peekType(tlvType, endOffset)) {
  182.         if (field.type.name == "message") {
  183.           var innerEndOffset = decoder.readNestedTlvsStart(tlvType);
  184.           var value = new (field.resolvedType.build())();
  185.           message.add(field.name, value);
  186.           ProtobufTlv._decodeMessageValue
  187.             (value, field.resolvedType, decoder, innerEndOffset);
  188.           decoder.finishNestedTlvs(innerEndOffset);
  189.         }
  190.         else
  191.           message.add
  192.             (field.name,
  193.              ProtobufTlv._decodeFieldValue(field, tlvType, decoder, endOffset));
  194.       }
  195.     }
  196.     else {
  197.       if (field.type.name == "message") {
  198.         var innerEndOffset = decoder.readNestedTlvsStart(tlvType);
  199.         var value = new (field.resolvedType.build())();
  200.         message.set(field.name, value);
  201.         ProtobufTlv._decodeMessageValue
  202.           (value, field.resolvedType, decoder, innerEndOffset);
  203.         decoder.finishNestedTlvs(innerEndOffset);
  204.       }
  205.       else
  206.         message.set
  207.           (field.name,
  208.            ProtobufTlv._decodeFieldValue(field, tlvType, decoder, endOffset));
  209.     }
  210.   }
  211. };
  213. /**
  214.  * This is a helper for _decodeMessageValue. Decode a single field and return
  215.  * the value. Assume the field.type.name is not "message".
  216.  */
  217. ProtobufTlv._decodeFieldValue = function(field, tlvType, decoder, endOffset)
  218. {
  219.   if (field.type.name == "uint32" ||
  220.       field.type.name == "uint64" ||
  221.       field.type.name == "enum")
  222.     return decoder.readNonNegativeIntegerTlv(tlvType);
  223.   else if (field.type.name == "bytes")
  224.     return decoder.readBlobTlv(tlvType);
  225.   else if (field.type.name == "string")
  226.     return decoder.readBlobTlv(tlvType).toString();
  227.   else if (field.type.name == "bool")
  228.     return decoder.readBooleanTlv(tlvType, endOffset);
  229.   else if (field.type.name == "double")
  230.     return decoder.readBlobTlv(tlvType).readDoubleLE(0);
  231.   else
  232.     throw new Error("ProtobufTlv.decode: Unknown field type");
  233. };
  235. /**
  236.  * Return a Name made from the component array in a Protobuf message object,
  237.  * assuming that it was defined with "repeated bytes". For example:
  238.  * message Name {
  239.  *   repeated bytes component = 8;
  240.  * }
  241.  * @param {Array} componentArray The array from the Protobuf message object
  242.  * representing the "repeated bytes" component array.
  243.  * @return A new Name.
  244.  */
  245. ProtobufTlv.toName = function(componentArray)
  246. {
  247.   var name = new Name();
  248.   for (var i = 0; i < componentArray.length; ++i)
  249.     name.append
  250.       (new Blob(new Buffer(componentArray[i].toBinary(), "binary"), false));
  252.   return name;
  253. };