lp: introduce PIT token

PIT token is a hop-by-hop header field that identifies an
Interest-Data exchange. The downstream node can assign an
opaque token to an outgoing Interest, and the upstream node
is expected to return the same token on the Data or Nack in
reply to that Interest. This would allow the downstream node
to accelerate its processing, especially in PIT lookup.

This commit adds basic encoding and decoding support for
PIT token, as an NDNLPv2 header field as well as a Tag.

refs #4532

Change-Id: I633fc451393746ebe199f41e44e245361b058d5e
diff --git a/ndn-cxx/lp/fields.hpp b/ndn-cxx/lp/fields.hpp
index 5c25e64..f705b36 100644
--- a/ndn-cxx/lp/fields.hpp
+++ b/ndn-cxx/lp/fields.hpp
@@ -1,6 +1,6 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /*
- * Copyright (c) 2013-2018 Regents of the University of California.
+ * Copyright (c) 2013-2019 Regents of the University of California.
  *
  * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
  *
@@ -55,6 +55,11 @@
 BOOST_CONCEPT_ASSERT((Field<FragCountField>));
 
 typedef FieldDecl<field_location_tags::Header,
+                  std::pair<Buffer::const_iterator, Buffer::const_iterator>,
+                  tlv::PitToken> PitTokenField;
+BOOST_CONCEPT_ASSERT((Field<PitTokenField>));
+
+typedef FieldDecl<field_location_tags::Header,
                   NackHeader,
                   tlv::Nack> NackField;
 BOOST_CONCEPT_ASSERT((Field<NackField>));
@@ -126,10 +131,11 @@
   SequenceField,
   FragIndexField,
   FragCountField,
+  PitTokenField,
   NackField,
   NextHopFaceIdField,
-  CachePolicyField,
   IncomingFaceIdField,
+  CachePolicyField,
   CongestionMarkField,
   AckField,
   TxSequenceField,
diff --git a/ndn-cxx/lp/pit-token.cpp b/ndn-cxx/lp/pit-token.cpp
new file mode 100644
index 0000000..2448579
--- /dev/null
+++ b/ndn-cxx/lp/pit-token.cpp
@@ -0,0 +1,49 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2013-2019 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#include "ndn-cxx/lp/pit-token.hpp"
+#include "ndn-cxx/encoding/tlv.hpp"
+#include "ndn-cxx/util/string-helper.hpp"
+
+namespace ndn {
+namespace lp {
+
+static constexpr size_t LENGTH_MIN = 1;
+static constexpr size_t LENGTH_MAX = 32;
+
+void
+PitToken::validate() const
+{
+  if (size() < LENGTH_MIN || size() > LENGTH_MAX) {
+    NDN_THROW(ndn::tlv::Error("PitToken length must be between " +
+      to_string(LENGTH_MIN) + " and " + to_string(LENGTH_MAX)));
+  }
+}
+
+std::ostream&
+operator<<(std::ostream& os, const PitToken& pitToken)
+{
+  printHex(os, pitToken, false);
+  return os;
+}
+
+} // namespace lp
+} // namespace ndn
diff --git a/ndn-cxx/lp/pit-token.hpp b/ndn-cxx/lp/pit-token.hpp
new file mode 100644
index 0000000..fa61593
--- /dev/null
+++ b/ndn-cxx/lp/pit-token.hpp
@@ -0,0 +1,73 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2013-2019 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#ifndef NDN_CXX_LP_PIT_TOKEN_HPP
+#define NDN_CXX_LP_PIT_TOKEN_HPP
+
+#include "ndn-cxx/encoding/buffer.hpp"
+#include "ndn-cxx/tag.hpp"
+
+namespace ndn {
+namespace lp {
+
+/** \brief represent a PIT token field
+ *  \sa https://redmine.named-data.net/projects/nfd/wiki/NDNLPv2#PIT-Token
+ */
+class PitToken : public Buffer, public Tag
+{
+public:
+  static constexpr int
+  getTypeId() noexcept
+  {
+    return 98;
+  }
+
+  /** \brief Construct from header field.
+   *  \throw ndn::tlv::Error element length is out of range.
+   */
+  explicit
+  PitToken(const std::pair<Buffer::const_iterator, Buffer::const_iterator>& value)
+    : Buffer(value.first, value.second)
+  {
+    validate();
+  }
+
+  /** \brief Convert to header field.
+   *  \throw ndn::tlv::Error element length is out of range.
+   */
+  operator std::pair<Buffer::const_iterator, Buffer::const_iterator>() const
+  {
+    validate();
+    return std::make_pair(begin(), end());
+  }
+
+private:
+  void
+  validate() const;
+};
+
+std::ostream&
+operator<<(std::ostream& os, const PitToken& pitToken);
+
+} // namespace lp
+} // namespace ndn
+
+#endif // NDN_CXX_LP_PIT_TOKEN_HPP
diff --git a/ndn-cxx/lp/tlv.hpp b/ndn-cxx/lp/tlv.hpp
index 1b409ca..d524bcf 100644
--- a/ndn-cxx/lp/tlv.hpp
+++ b/ndn-cxx/lp/tlv.hpp
@@ -1,6 +1,6 @@
 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
 /*
- * Copyright (c) 2013-2018 Regents of the University of California.
+ * Copyright (c) 2013-2019 Regents of the University of California.
  *
  * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
  *
@@ -35,6 +35,7 @@
   Sequence = 81,
   FragIndex = 82,
   FragCount = 83,
+  PitToken = 98,
   Nack = 800,
   NackReason = 801,
   NextHopFaceId = 816,
diff --git a/tests/unit/lp/pit-token.t.cpp b/tests/unit/lp/pit-token.t.cpp
new file mode 100644
index 0000000..48ef8d6
--- /dev/null
+++ b/tests/unit/lp/pit-token.t.cpp
@@ -0,0 +1,80 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2013-2019 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file.  If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#include "ndn-cxx/lp/pit-token.hpp"
+#include "ndn-cxx/lp/packet.hpp"
+
+#include "tests/boost-test.hpp"
+#include <boost/lexical_cast.hpp>
+
+namespace ndn {
+namespace lp {
+namespace tests {
+
+BOOST_AUTO_TEST_SUITE(Lp)
+BOOST_AUTO_TEST_SUITE(TestPitToken)
+
+BOOST_AUTO_TEST_CASE(Decode)
+{
+  Packet pkt("6405 pit-token=6200 fragment=5001C0"_block);
+  BOOST_CHECK_THROW(PitToken(pkt.get<PitTokenField>()), ndn::tlv::Error);
+
+  pkt.wireDecode("6406 pit-token=6201A0 fragment=5001C0"_block);
+  PitToken pitToken1(pkt.get<PitTokenField>());
+  BOOST_CHECK_EQUAL(boost::lexical_cast<std::string>(pitToken1), "a0");
+
+  pkt.wireDecode("640A pit-token=6205A0A1A2A3A4 fragment=5001C0"_block);
+  PitToken pitToken5(pkt.get<PitTokenField>());
+  BOOST_CHECK_EQUAL(boost::lexical_cast<std::string>(pitToken5), "a0a1a2a3a4");
+
+  pkt.wireDecode("640D pit-token=6208A0A1A2A3A4A5A6A7 fragment=5001C0"_block);
+  PitToken pitToken8(pkt.get<PitTokenField>());
+  BOOST_CHECK_EQUAL(boost::lexical_cast<std::string>(pitToken8), "a0a1a2a3a4a5a6a7");
+
+  pkt.wireDecode("6425 pit-token=6220A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBF"
+                 " fragment=5001C0"_block);
+  PitToken pitToken32(pkt.get<PitTokenField>());
+  BOOST_CHECK_EQUAL(boost::lexical_cast<std::string>(pitToken32),
+                    "a0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebf");
+
+  pkt.wireDecode("6426 pit-token=6221A0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0"
+                 " fragment=5001C0"_block);
+  BOOST_CHECK_THROW(PitToken(pkt.get<PitTokenField>()), ndn::tlv::Error);
+
+  BOOST_CHECK_EQUAL(pitToken1, pitToken1);
+  BOOST_CHECK_NE(pitToken1, pitToken5);
+
+  pkt.wireDecode("640A pit-token=6205B0B1B2B3B4 fragment=5001C0"_block);
+  PitToken pitToken5b(pkt.get<PitTokenField>());
+  BOOST_CHECK_NE(pitToken5, pitToken5b);
+
+  pkt.set<PitTokenField>(pitToken5);
+  BOOST_CHECK_EQUAL(pkt.wireEncode(), "640A pit-token=6205A0A1A2A3A4 fragment=5001C0"_block);
+  PitToken pitToken5a(pkt.get<PitTokenField>());
+  BOOST_CHECK_EQUAL(pitToken5, pitToken5a);
+}
+
+BOOST_AUTO_TEST_SUITE_END() // TestPitToken
+BOOST_AUTO_TEST_SUITE_END() // Lp
+
+} // namespace tests
+} // namespace lp
+} // namespace ndn