dispatcher.hpp

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2013-2025 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_MGMT_DISPATCHER_HPP
#define NDN_CXX_MGMT_DISPATCHER_HPP
 
#include "ndn-cxx/face.hpp"
#include "ndn-cxx/ims/in-memory-storage-fifo.hpp"
#include "ndn-cxx/mgmt/control-parameters-base.hpp"
#include "ndn-cxx/mgmt/control-response.hpp"
#include "ndn-cxx/mgmt/status-dataset-context.hpp"
#include "ndn-cxx/security/key-chain.hpp"
 
#include <unordered_map>
 
namespace ndn::mgmt {
 
// ---- AUTHORIZATION ----
 
using AcceptContinuation = std::function<void(const std::string& requester)>;
 
enum class RejectReply {
  SILENT,
  STATUS403
};
enum class RejectReply {…};
 
using RejectContinuation = std::function<void(RejectReply)>;
 
using Authorization = std::function<void(const Name& prefix, const Interest& interest,
                                         const ControlParametersBase* params,
                                         const AcceptContinuation& accept,
                                         const RejectContinuation& reject)>;
 
Authorization
makeAcceptAllAuthorization();
 
// ---- CONTROL COMMAND ----
 
using ValidateParameters = std::function<bool(ControlParametersBase& params)>;
 
using CommandContinuation = std::function<void(const ControlResponse& resp)>;
 
using ControlCommandHandler = std::function<void(const Name& prefix, const Interest& interest,
                                                 const ControlParametersBase& params,
                                                 const CommandContinuation& done)>;
 
// ---- STATUS DATASET ----
 
using StatusDatasetHandler = std::function<void(const Name& prefix, const Interest& interest,
                                                StatusDatasetContext& context)>;
 
//---- NOTIFICATION STREAM ----
 
using PostNotification = std::function<void(const Block& notification)>;
 
// ---- DISPATCHER ----
 
class Dispatcher : noncopyable
{
public:
  Dispatcher(Face& face, KeyChain& keyChain,
             const security::SigningInfo& signingInfo = security::SigningInfo(),
             size_t imsCapacity = 256);
 
  void
  addTopPrefix(const Name& prefix, bool wantRegister = true,
               const security::SigningInfo& signingInfo = security::SigningInfo());
 
  void
  removeTopPrefix(const Name& prefix);
 
public: // ControlCommand
  template<typename ParametersType,
           std::enable_if_t<std::is_convertible_v<ParametersType*, ControlParametersBase*>, int> = 0>
  void
  addControlCommand(const PartialName& relPrefix,
                    Authorization authorize,
                    ValidateParameters validate,
                    ControlCommandHandler handle)
  {
    checkPrefix(relPrefix);
 
    auto relPrefixLen = relPrefix.size();
    ParametersParser parse = [relPrefixLen] (const Name& prefix,
                                             const auto& interest) -> ControlParametersPtr {
      const name::Component& comp = interest.getName().get(prefix.size() + relPrefixLen);
      return make_shared<ParametersType>(comp.blockFromValue());
    };
 
    m_handlers[relPrefix] = [this,
                             parser = std::move(parse),
                             authorizer = std::move(authorize),
                             validator = std::move(validate),
                             handler = std::move(handle)] (const auto& prefix, const auto& interest) {
      processCommand(prefix, interest, parser, authorizer, std::move(validator), std::move(handler));
    };
  }
  addControlCommand(const PartialName& relPrefix, {…}
 
  template<typename Command>
  void
  addControlCommand(Authorization authorize, ControlCommandHandler handle)
  {
    auto relPrefix = Command::getName();
    checkPrefix(relPrefix);
 
    ParametersParser parse = [] (const Name& prefix, const auto& interest) {
      return Command::parseRequest(interest, prefix.size());
    };
    ValidateParameters validate = [] (auto& params) {
      auto& reqParams = static_cast<typename Command::RequestParameters&>(params);
      Command::validateRequest(reqParams);
      Command::applyDefaultsToRequest(reqParams);
      // for compatibility with ValidateParameters signature; consider refactoring in the future
      return true;
    };
 
    m_handlers[relPrefix] = [this,
                             parser = std::move(parse),
                             authorizer = std::move(authorize),
                             validator = std::move(validate),
                             handler = std::move(handle)] (const auto& prefix, const auto& interest) {
      processCommand(prefix, interest, parser, authorizer, std::move(validator), std::move(handler));
    };
  }
  addControlCommand(Authorization authorize, ControlCommandHandler handle) {…}
 
public: // StatusDataset
  void
  addStatusDataset(const PartialName& relPrefix,
                   Authorization authorize,
                   StatusDatasetHandler handle);
 
public: // NotificationStream
  PostNotification
  addNotificationStream(const PartialName& relPrefix);
 
private:
  using ControlParametersPtr = shared_ptr<ControlParametersBase>;
  using InterestHandler = std::function<void(const Name& prefix, const Interest&)>;
 
  using ParametersParser = std::function<ControlParametersPtr(const Name& prefix, const Interest&)>;
 
  void
  checkPrefix(const PartialName& relPrefix) const;
 
  void
  afterAuthorizationRejected(RejectReply act, const Interest& interest);
 
  void
  queryStorage(const Name& prefix, const Interest& interest, const InterestHandler& missContinuation);
 
  enum class SendDestination {
    NONE = 0,
    FACE = 1,
    IMS  = 2,
    FACE_AND_IMS = 3,
  };
 
  void
  sendData(const Name& dataName, const Block& content, const MetaInfo& metaInfo,
           SendDestination destination);
 
  void
  sendOnFace(const Data& data);
 
  void
  processCommand(const Name& prefix,
                 const Interest& interest,
                 const ParametersParser& parse,
                 const Authorization& authorize,
                 ValidateParameters validate,
                 ControlCommandHandler handler);
 
  void
  processAuthorizedCommand(const Name& prefix,
                           const Interest& interest,
                           const ControlParametersPtr& parameters,
                           const ValidateParameters& validate,
                           const ControlCommandHandler& handler);
 
  void
  sendControlResponse(const ControlResponse& resp, const Interest& interest, bool isNack = false);
 
  void
  processStatusDatasetInterest(const Name& prefix,
                               const Interest& interest,
                               const Authorization& authorize,
                               StatusDatasetHandler handler);
 
  void
  processAuthorizedStatusDatasetInterest(const Name& prefix,
                                         const Interest& interest,
                                         const StatusDatasetHandler& handler);
 
  void
  sendStatusDatasetSegment(const Name& dataName, const Block& content, bool isFinalBlock);
 
  void
  postNotification(const Block& notification, const PartialName& relPrefix);
 
private:
  Face& m_face;
  KeyChain& m_keyChain;
  security::SigningInfo m_signingInfo;
 
  struct TopPrefixEntry
  {
    ScopedRegisteredPrefixHandle registeredPrefix;
    std::vector<ScopedInterestFilterHandle> interestFilters;
  };
  std::unordered_map<Name, TopPrefixEntry> m_topLevelPrefixes;
 
  std::unordered_map<PartialName, InterestHandler> m_handlers;
 
  // NotificationStream name => next sequence number
  std::unordered_map<Name, uint64_t> m_streams;
 
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE:
  InMemoryStorageFifo m_storage;
};
class Dispatcher : noncopyable {…};
 
} // namespace ndn::mgmt
 
#endif // NDN_CXX_MGMT_DISPATCHER_HPP