routing_api.h

/*  Copyright 2012 MaidSafe.net limited

    This MaidSafe Software is licensed to you under (1) the MaidSafe.net Commercial License,
    version 1.0 or later, or (2) The General Public License (GPL), version 3, depending on which
    licence you accepted on initial access to the Software (the "Licences").

    By contributing code to the MaidSafe Software, or to this project generally, you agree to be
    bound by the terms of the MaidSafe Contributor Agreement, version 1.0, found in the root
    directory of this project at LICENSE, COPYING and CONTRIBUTOR respectively and also
    available at: http://www.maidsafe.net/licenses

    Unless required by applicable law or agreed to in writing, the MaidSafe Software distributed
    under the GPL Licence is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
    OF ANY KIND, either express or implied.

    See the Licences for the specific language governing permissions and limitations relating to
    use of the MaidSafe Software.                                                                 */

/*******************************************************************************
*Guarantees                                                                    *
*______________________________________________________________________________*
*                                                                              *
*1:  Provide NAT traversal techniques where necessary.                         *
*2:  Read and Write configuration file to allow bootstrap from known nodes.    *
*3:  Allow retrieval of bootstrap nodes from known location.                   *
*4:  Remove bad nodes from all routing tables (ban from network).              *
*5:  Inform of changes in data range to be stored and sent to each node        *
*6:  Respond to every send that requires it, either with timeout or reply      *
*******************************************************************************/

#ifndef MAIDSAFE_ROUTING_ROUTING_API_H_
#define MAIDSAFE_ROUTING_ROUTING_API_H_

#include <condition_variable>
#include <future>
#include <memory>
#include <mutex>
#include <string>
#include <vector>

#include "boost/asio/ip/udp.hpp"
#include "boost/date_time/posix_time/posix_time_config.hpp"

#include "maidsafe/common/node_id.h"
#include "maidsafe/common/rsa.h"

#include "maidsafe/passport/types.h"

#include "maidsafe/routing/api_config.h"

namespace maidsafe {

namespace routing {

struct NodeInfo;

namespace test { class GenericNode; }

namespace detail {

template <typename FobType>
struct is_client : public std::true_type {};

template <>
struct is_client<passport::Pmid> : public std::false_type {};

template <>
struct is_client<const passport::Pmid> : public std::false_type {};

}  // namespace detail

class Routing {
 public:
  // create a non-mutating client
  Routing();

  // Providing :
  // pmid as a paramater will create a non client routing object(vault).
  // maid as a paramater will create a mutating client.
  // Non-mutating client means that random keys will be generated by routing for this node.
  template <typename FobType>
  explicit Routing(const FobType& fob)
      : pimpl_() {
    asymm::Keys keys;
    keys.private_key = fob.private_key();
    keys.public_key = fob.public_key();
    InitialisePimpl(detail::is_client<FobType>::value, NodeId(fob.name()->string()), keys);
  }

  ~Routing();
  // Joins the network. Valid method for requesting public key must be provided by the functor,
  // otherwise no node will be added to the routing table and node will fail to join the network.
  void Join(Functors functors);

  // WARNING: THIS FUNCTION SHOULD BE ONLY USED TO JOIN FIRST TWO ZERO STATE NODES.
  int ZeroStateJoin(Functors functors, const boost::asio::ip::udp::endpoint& local_endpoint,
                    const boost::asio::ip::udp::endpoint& peer_endpoint, const NodeInfo& peer_info);

  // Sends message to a known destnation. (Typed Message API)
  // Throws on invalid paramaters
  template <typename T>
  void Send(const T& message);

  // Sends message to a known destnation.
  // If a valid response functor is provided, it will be called when:
  // a) the response is receieved or,
  // b) waiting time (Parameters::default_response_timeout) for receiving the response expires
  // Throws on invalid paramaters
  void SendDirect(const NodeId& destination_id,                       // ID of final destination
                  const std::string& message, bool cacheable,  // to cache message content
                  ResponseFunctor response_functor);                  // Called on response

  // Sends message to Parameters::group_size most closest nodes to destination_id. The node
  // having id equal to destination id is not considered as part of group and will not receive
  // group message
  // If a valid response functor is provided, it will be called when:
  // a) for each response receieved (Parameters::group_size responses expected) or,
  // b) waiting time (Parameters::default_response_timeout) for receiving the response expires
  // Throws on invalid paramaters
  void SendGroup(const NodeId& destination_id,  // ID of final destination or group centre
                 const std::string& message, bool cacheable,  // to cache message content
                 ResponseFunctor response_functor);                  // Called on each response

  // Compares own closeness to target against other known nodes' closeness to the target
  bool ClosestToId(const NodeId& target_id);

  // Gets a random connected node from routing table (excluding closest
  // Parameters::closest_nodes_size nodes).
  // Shouldn't be called when routing table is likely to be smaller than closest_nodes_size.
  NodeId RandomConnectedNode();

  // Evaluates whether the sender_id is a legitimate source to send a request for performing
  // an operation on info_id
  bool EstimateInGroup(const NodeId& sender_id, const NodeId& info_id) const;

  // Returns this node's id.
  NodeId kNodeId() const;

  // Returns a number between 0 to 100 representing % network health w.r.t. number of connections
  int network_status();


  // Checks if routing table contains given node id
  bool IsConnectedVault(const NodeId& node_id);

  // Checks if client routing table contains given node id
  bool IsConnectedClient(const NodeId& node_id);

  friend class test::GenericNode;

 private:
  Routing(const Routing&);
  Routing(const Routing&&);
  Routing& operator=(const Routing&);
  void InitialisePimpl(bool client_mode, const NodeId& node_id, const asymm::Keys& keys);

  class Impl;
  std::shared_ptr<Impl> pimpl_;
};

// Locks 'mutex', sets 'current_health' to 'updated_health' then calls notify_one() on 'cond_var'.
void UpdateNetworkHealth(int updated_health, int& current_health, std::mutex& mutex,
                         std::condition_variable& cond_var, const NodeId& this_node_id);

template <>
Routing::Routing(const NodeId& node_id);

template <>
void Routing::Send(const SingleToSingleMessage& message);
template <>
void Routing::Send(const SingleToGroupMessage& message);
template <>
void Routing::Send(const GroupToSingleMessage& message);
template <>
void Routing::Send(const GroupToGroupMessage& message);
template <>
void Routing::Send(const GroupToSingleRelayMessage& message);

template <typename T>
void Routing::Send(const T&) {
  T::message_type_must_be_one_of_the_specialisations_defined_as_typedefs_in_message_dot_h_file;
}

}  // namespace routing

}  // namespace maidsafe

#endif  // MAIDSAFE_ROUTING_ROUTING_API_H_