Source: util/segment-fetcher.js

  1. /**
  2.  * Copyright (C) 2015-2016 Regents of the University of California.
  3.  * @author: Jeff Thompson <jefft0@remap.ucla.edu>
  4.  * @author: From ndn-cxx util/segment-fetcher https://github.com/named-data/ndn-cxx
  5.  *
  6.  * This program is free software: you can redistribute it and/or modify
  7.  * it under the terms of the GNU Lesser General Public License as published by
  8.  * the Free Software Foundation, either version 3 of the License, or
  9.  * (at your option) any later version.
  10.  *
  11.  * This program is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU Lesser General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU Lesser General Public License
  17.  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18.  * A copy of the GNU Lesser General Public License is in the file COPYING.
  19.  */
  21. /** @ignore */
  22. var Interest = require('../interest.js').Interest; /** @ignore */
  23. var Blob = require('./blob.js').Blob; /** @ignore */
  24. var NdnCommon = require('./ndn-common.js').NdnCommon;
  26. /**
  27.  * SegmentFetcher is a utility class to fetch the latest version of segmented data.
  28.  *
  29.  * SegmentFetcher assumes that the data is named /<prefix>/<version>/<segment>,
  30.  * where:
  31.  * - <prefix> is the specified name prefix,
  32.  * - <version> is an unknown version that needs to be discovered, and
  33.  * - <segment> is a segment number. (The number of segments is unknown and is
  34.  *   controlled by the `FinalBlockId` field in at least the last Data packet.
  35.  *
  36.  * The following logic is implemented in SegmentFetcher:
  37.  *
  38.  * 1. Express the first Interest to discover the version:
  39.  *
  40.  *    >> Interest: /<prefix>?ChildSelector=1&MustBeFresh=true
  41.  *
  42.  * 2. Infer the latest version of the Data: <version> = Data.getName().get(-2)
  43.  *
  44.  * 3. If the segment number in the retrieved packet == 0, go to step 5.
  45.  *
  46.  * 4. Send an Interest for segment 0:
  47.  *
  48.  *    >> Interest: /<prefix>/<version>/<segment=0>
  49.  *
  50.  * 5. Keep sending Interests for the next segment while the retrieved Data does
  51.  *    not have a FinalBlockId or the FinalBlockId != Data.getName().get(-1).
  52.  *
  53.  *    >> Interest: /<prefix>/<version>/<segment=(N+1))>
  54.  *
  55.  * 6. Call the onComplete callback with a Blob that concatenates the content
  56.  *    from all the segmented objects.
  57.  *
  58.  * If an error occurs during the fetching process, the onError callback is called
  59.  * with a proper error code.  The following errors are possible:
  60.  *
  61.  * - `INTEREST_TIMEOUT`: if any of the Interests times out
  62.  * - `DATA_HAS_NO_SEGMENT`: if any of the retrieved Data packets don't have a segment
  63.  *   as the last component of the name (not counting the implicit digest)
  64.  * - `SEGMENT_VERIFICATION_FAILED`: if any retrieved segment fails
  65.  *   the user-provided VerifySegment callback
  66.  * - `IO_ERROR`: for I/O errors when sending an Interest.
  67.  *
  68.  * In order to validate individual segments, a verifySegment callback needs to
  69.  * be specified. If the callback returns false, the fetching process is aborted
  70.  * with SEGMENT_VERIFICATION_FAILED. If data validation is not required, the
  71.  * provided DontVerifySegment object can be used.
  72.  *
  73.  * Example:
  74.  *     var onComplete = function(content) { ... }
  75.  *
  76.  *     var onError = function(errorCode, message) { ... }
  77.  *
  78.  *     var interest = new Interest(new Name("/data/prefix"));
  79.  *     interest.setInterestLifetimeMilliseconds(1000);
  80.  *
  81.  *     SegmentFetcher.fetch
  82.  *       (face, interest, SegmentFetcher.DontVerifySegment, onComplete, onError);
  83.  *
  84.  * This is a private constructor to create a new SegmentFetcher to use the Face.
  85.  * An application should use SegmentFetcher.fetch.
  86.  * @param {Face} face This calls face.expressInterest to fetch more segments.
  87.  * @param {function} verifySegment When a Data packet is received this calls
  88.  * verifySegment(data) where data is a Data object. If it returns False then
  89.  * abort fetching and call onError with
  90.  * SegmentFetcher.ErrorCode.SEGMENT_VERIFICATION_FAILED.
  91.  * NOTE: The library will log any exceptions thrown by this callback, but for
  92.  * better error handling the callback should catch and properly handle any
  93.  * exceptions.
  94.  * @param {function} onComplete When all segments are received, call
  95.  * onComplete(content) where content is a Blob which has the concatenation of
  96.  * the content of all the segments.
  97.  * NOTE: The library will log any exceptions thrown by this callback, but for
  98.  * better error handling the callback should catch and properly handle any
  99.  * exceptions.
  100.  * @param {function} onError Call onError.onError(errorCode, message) for
  101.  * timeout or an error processing segments. errorCode is a value from
  102.  * SegmentFetcher.ErrorCode and message is a related string.
  103.  * NOTE: The library will log any exceptions thrown by this callback, but for
  104.  * better error handling the callback should catch and properly handle any
  105.  * exceptions.
  106.  * @constructor
  107.  */
  108. var SegmentFetcher = function SegmentFetcher
  109.   (face, verifySegment, onComplete, onError)
  110. {
  111.   this.face = face;
  112.   this.verifySegment = verifySegment;
  113.   this.onComplete = onComplete;
  114.   this.onError = onError;
  116.   this.contentParts = []; // of Buffer
  117. };
  119. exports.SegmentFetcher = SegmentFetcher;
  121. /**
  122.  * An ErrorCode value is passed in the onError callback.
  123.  */
  124. SegmentFetcher.ErrorCode = {
  125.   INTEREST_TIMEOUT: 1,
  126.   DATA_HAS_NO_SEGMENT: 2,
  127.   SEGMENT_VERIFICATION_FAILED: 3
  128. };
  130. /**
  131.  * DontVerifySegment may be used in fetch to skip validation of Data packets.
  132.  */
  133. SegmentFetcher.DontVerifySegment = function(data)
  134. {
  135.   return true;
  136. };
  138. /**
  139.  * Initiate segment fetching. For more details, see the documentation for the
  140.  * class.
  141.  * @param {Face} face This calls face.expressInterest to fetch more segments.
  142.  * @param {Interest} baseInterest An Interest for the initial segment of the
  143.  * requested data, where baseInterest.getName() has the name prefix. This
  144.  * interest may include a custom InterestLifetime and selectors that will
  145.  * propagate to all subsequent Interests. The only exception is that the initial
  146.  * Interest will be forced to include selectors "ChildSelector=1" and
  147.  * "MustBeFresh=true" which will be turned off in subsequent Interests.
  148.  * @param {function} verifySegment When a Data packet is received this calls
  149.  * verifySegment(data) where data is a Data object. If it returns False then
  150.  * abort fetching and call onError with
  151.  * SegmentFetcher.ErrorCode.SEGMENT_VERIFICATION_FAILED. If data validation is
  152.  * not required, use SegmentFetcher.DontVerifySegment.
  153.  * NOTE: The library will log any exceptions thrown by this callback, but for
  154.  * better error handling the callback should catch and properly handle any
  155.  * exceptions.
  156.  * @param {function} onComplete When all segments are received, call
  157.  * onComplete(content) where content is a Blob which has the concatenation of
  158.  * the content of all the segments.
  159.  * NOTE: The library will log any exceptions thrown by this callback, but for
  160.  * better error handling the callback should catch and properly handle any
  161.  * exceptions.
  162.  * @param {function} onError Call onError.onError(errorCode, message) for
  163.  * timeout or an error processing segments. errorCode is a value from
  164.  * SegmentFetcher.ErrorCode and message is a related string.
  165.  * NOTE: The library will log any exceptions thrown by this callback, but for
  166.  * better error handling the callback should catch and properly handle any
  167.  * exceptions.
  168.  */
  169. SegmentFetcher.fetch = function
  170.   (face, baseInterest, verifySegment, onComplete, onError)
  171. {
  172.   new SegmentFetcher(face, verifySegment, onComplete, onError).fetchFirstSegment
  173.     (baseInterest);
  174. };
  176. SegmentFetcher.prototype.fetchFirstSegment = function(baseInterest)
  177. {
  178.   var interest = new Interest(baseInterest);
  179.   interest.setChildSelector(1);
  180.   interest.setMustBeFresh(true);
  181.   var thisSegmentFetcher = this;
  182.   this.face.expressInterest
  183.     (interest,
  184.      function(originalInterest, data)
  185.        { thisSegmentFetcher.onData(originalInterest, data); },
  186.      function(interest) { thisSegmentFetcher.onTimeout(interest); });
  187. };
  189. SegmentFetcher.prototype.fetchNextSegment = function
  190.   (originalInterest, dataName, segment)
  191. {
  192.   // Start with the original Interest to preserve any special selectors.
  193.   var interest = new Interest(originalInterest);
  194.   // Changing a field clears the nonce so that the library will generate a new
  195.   // one.
  196.   interest.setMustBeFresh(false);
  197.   interest.setName(dataName.getPrefix(-1).appendSegment(segment));
  198.   var thisSegmentFetcher = this;
  199.   this.face.expressInterest
  200.     (interest, function(originalInterest, data)
  201.        { thisSegmentFetcher.onData(originalInterest, data); },
  202.      function(interest) { thisSegmentFetcher.onTimeout(interest); });
  203. };
  205. SegmentFetcher.prototype.onData = function(originalInterest, data)
  206. {
  207.   if (!this.verifySegment(data)) {
  208.     try {
  209.       this.onError
  210.         (SegmentFetcher.ErrorCode.SEGMENT_VERIFICATION_FAILED,
  211.          "Segment verification failed");
  212.     } catch (ex) {
  213.       console.log("Error in onError: " + NdnCommon.getErrorWithStackTrace(ex));
  214.     }
  215.     return;
  216.   }
  218.   if (!SegmentFetcher.endsWithSegmentNumber(data.getName())) {
  219.     // We don't expect a name without a segment number.  Treat it as a bad packet.
  220.     try {
  221.       this.onError
  222.         (SegmentFetcher.ErrorCode.DATA_HAS_NO_SEGMENT,
  223.          "Got an unexpected packet without a segment number: " +
  224.           data.getName().toUri());
  225.     } catch (ex) {
  226.       console.log("Error in onError: " + NdnCommon.getErrorWithStackTrace(ex));
  227.     }
  228.   }
  229.   else {
  230.     var currentSegment = 0;
  231.     try {
  232.       currentSegment = data.getName().get(-1).toSegment();
  233.     }
  234.     catch (ex) {
  235.       try {
  236.         this.onError
  237.           (SegmentFetcher.ErrorCode.DATA_HAS_NO_SEGMENT,
  238.            "Error decoding the name segment number " +
  239.            data.getName().get(-1).toEscapedString() + ": " + ex);
  240.       } catch (ex) {
  241.         console.log("Error in onError: " + NdnCommon.getErrorWithStackTrace(ex));
  242.       }
  243.       return;
  244.     }
  246.     var expectedSegmentNumber = this.contentParts.length;
  247.     if (currentSegment != expectedSegmentNumber)
  248.       // Try again to get the expected segment.  This also includes the case
  249.       // where the first segment is not segment 0.
  250.       this.fetchNextSegment
  251.         (originalInterest, data.getName(), expectedSegmentNumber);
  252.     else {
  253.       // Save the content and check if we are finished.
  254.       this.contentParts.push(data.getContent().buf());
  256.       if (data.getMetaInfo().getFinalBlockId().getValue().size() > 0) {
  257.         var finalSegmentNumber = 0;
  258.         try {
  259.           finalSegmentNumber = (data.getMetaInfo().getFinalBlockId().toSegment());
  260.         }
  261.         catch (ex) {
  262.           try {
  263.             this.onError
  264.               (SegmentFetcher.ErrorCode.DATA_HAS_NO_SEGMENT,
  265.                "Error decoding the FinalBlockId segment number " +
  266.                data.getMetaInfo().getFinalBlockId().toEscapedString() +
  267.                ": " + ex);
  268.           } catch (ex) {
  269.             console.log("Error in onError: " + NdnCommon.getErrorWithStackTrace(ex));
  270.           }
  271.           return;
  272.         }
  274.         if (currentSegment == finalSegmentNumber) {
  275.           // We are finished.
  277.           // Concatenate to get content.
  278.           var content = Buffer.concat(this.contentParts);
  279.           try {
  280.             this.onComplete(new Blob(content, false));
  281.           } catch (ex) {
  282.             console.log("Error in onComplete: " + NdnCommon.getErrorWithStackTrace(ex));
  283.           }
  284.           return;
  285.         }
  286.       }
  288.       // Fetch the next segment.
  289.       this.fetchNextSegment
  290.         (originalInterest, data.getName(), expectedSegmentNumber + 1);
  291.     }
  292.   }
  293. };
  295. SegmentFetcher.prototype.onTimeout = function(interest)
  296. {
  297.   try {
  298.     this.onError
  299.       (SegmentFetcher.ErrorCode.INTEREST_TIMEOUT,
  300.        "Time out for interest " + interest.getName().toUri());
  301.   } catch (ex) {
  302.     console.log("Error in onError: " + NdnCommon.getErrorWithStackTrace(ex));
  303.   }
  304. };
  306. /**
  307.  * Check if the last component in the name is a segment number.
  308.  * @param {Name} name The name to check.
  309.  * @returns {boolean} True if the name ends with a segment number, otherwise false.
  310.  */
  311. SegmentFetcher.endsWithSegmentNumber = function(name)
  312. {
  313.   return name.size() >= 1 &&
  314.          name.get(-1).getValue().size() >= 1 &&
  315.          name.get(-1).getValue().buf()[0] == 0;
  316. };