tor-browser

node.h (15204B)

---

// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef MOJO_CORE_PORTS_NODE_H_
#define MOJO_CORE_PORTS_NODE_H_

#include <stddef.h>
#include <stdint.h>

#include <unordered_map>

#include "mojo/core/ports/event.h"
#include "mojo/core/ports/name.h"
#include "mojo/core/ports/port.h"
#include "mojo/core/ports/port_ref.h"
#include "mojo/core/ports/user_data.h"
#include "mozilla/Mutex.h"
#include "mozilla/RefPtr.h"

namespace mojo {
namespace core {
namespace ports {

enum : int {
 OK = 0,
 ERROR_PORT_UNKNOWN = -10,
 ERROR_PORT_EXISTS = -11,
 ERROR_PORT_STATE_UNEXPECTED = -12,
 ERROR_PORT_CANNOT_SEND_SELF = -13,
 ERROR_PORT_PEER_CLOSED = -14,
 ERROR_PORT_CANNOT_SEND_PEER = -15,
 ERROR_NOT_IMPLEMENTED = -100,
};

struct PortStatus {
 bool has_messages;
 bool receiving_messages;
 bool peer_closed;
 bool peer_remote;
 size_t queued_message_count;
 size_t queued_num_bytes;
 size_t unacknowledged_message_count;
#ifdef FUZZING_SNAPSHOT
 NodeName peer_node_name;
#endif
};

struct PendingUpdatePreviousPeer {
 NodeName receiver;
 PortName port;
 PortName from_port;
 uint64_t sequence_num;
 NodeName new_prev_node;
 PortName new_prev_port;
};

class MessageFilter;
class NodeDelegate;

// A Node maintains a collection of Ports (see port.h) indexed by unique 128-bit
// addresses (names), performing routing and processing of events among the
// Ports within the Node and to or from other Nodes in the system. Typically
// (and practically, in all uses today) there is a single Node per system
// process. Thus a Node boundary effectively models a process boundary.
//
// New Ports can be created uninitialized using CreateUninitializedPort (and
// later initialized using InitializePort), or created in a fully initialized
// state using CreatePortPair(). Initialized ports have exactly one conjugate
// port which is the ultimate receiver of any user messages sent by that port.
// See SendUserMessage().
//
// In addition to routing user message events, various control events are used
// by Nodes to coordinate Port behavior and lifetime within and across Nodes.
// See Event documentation for description of different types of events used by
// a Node to coordinate behavior.
class Node {
public:
 enum class ShutdownPolicy {
   DONT_ALLOW_LOCAL_PORTS,
   ALLOW_LOCAL_PORTS,
 };

 // Does not take ownership of the delegate.
 Node(const NodeName& name, NodeDelegate* delegate);
 ~Node();

 Node(const Node&) = delete;
 void operator=(const Node&) = delete;

 // Returns true iff there are no open ports referring to another node or ports
 // in the process of being transferred from this node to another. If this
 // returns false, then to ensure clean shutdown, it is necessary to keep the
 // node alive and continue routing messages to it via AcceptMessage. This
 // method may be called again after AcceptMessage to check if the Node is now
 // ready to be destroyed.
 //
 // If |policy| is set to |ShutdownPolicy::ALLOW_LOCAL_PORTS|, this will return
 // |true| even if some ports remain alive, as long as none of them are proxies
 // to another node.
 bool CanShutdownCleanly(
     ShutdownPolicy policy = ShutdownPolicy::DONT_ALLOW_LOCAL_PORTS);

 // Lookup the named port.
 int GetPort(const PortName& port_name, PortRef* port_ref);

 // Creates a port on this node. Before the port can be used, it must be
 // initialized using InitializePort. This method is useful for bootstrapping
 // a connection between two nodes. Generally, ports are created using
 // CreatePortPair instead.
 int CreateUninitializedPort(PortRef* port_ref);

 // Initializes a newly created port.
 int InitializePort(const PortRef& port_ref, const NodeName& peer_node_name,
                    const PortName& peer_port_name,
                    const NodeName& prev_node_name,
                    const PortName& prev_port_name);

 // Generates a new connected pair of ports bound to this node. These ports
 // are initialized and ready to go.
 int CreatePortPair(PortRef* port0_ref, PortRef* port1_ref);

 // User data associated with the port.
 int SetUserData(const PortRef& port_ref, RefPtr<UserData> user_data);
 int GetUserData(const PortRef& port_ref, RefPtr<UserData>* user_data);

 // Prevents further messages from being sent from this port or delivered to
 // this port. The port is removed, and the port's peer is notified of the
 // closure after it has consumed all pending messages.
 int ClosePort(const PortRef& port_ref);

 // Returns the current status of the port.
 int GetStatus(const PortRef& port_ref, PortStatus* port_status);

 // Returns the next available message on the specified port or returns a null
 // message if there are none available. Returns ERROR_PORT_PEER_CLOSED to
 // indicate that this port's peer has closed. In such cases GetMessage may
 // be called until it yields a null message, indicating that no more messages
 // may be read from the port.
 //
 // If |filter| is non-null, the next available message is returned only if it
 // is matched by the filter. If the provided filter does not match the next
 // available message, GetMessage() behaves as if there is no message
 // available. Ownership of |filter| is not taken, and it must outlive the
 // extent of this call.
 int GetMessage(const PortRef& port_ref,
                mozilla::UniquePtr<UserMessageEvent>* message,
                MessageFilter* filter);

 // Sends a message from the specified port to its peer. Note that the message
 // notification may arrive synchronously (via PortStatusChanged() on the
 // delegate) if the peer is local to this Node.
 int SendUserMessage(const PortRef& port_ref,
                     mozilla::UniquePtr<UserMessageEvent> message);

 // Makes the port send acknowledge requests to its conjugate to acknowledge
 // at least every |sequence_number_acknowledge_interval| messages as they're
 // read from the conjugate. The number of unacknowledged messages is exposed
 // in the |unacknowledged_message_count| field of PortStatus. This allows
 // bounding the number of unread and/or in-transit messages from this port
 // to its conjugate between zero and |unacknowledged_message_count|.
 int SetAcknowledgeRequestInterval(const PortRef& port_ref,
                                   uint64_t sequence_num_acknowledge_interval);

 // Corresponding to NodeDelegate::ForwardEvent.
 int AcceptEvent(const NodeName& from_node, ScopedEvent event);

 // Called to merge two ports with each other. If you have two independent
 // port pairs A <=> B and C <=> D, the net result of merging B and C is a
 // single connected port pair A <=> D.
 //
 // Note that the behavior of this operation is undefined if either port to be
 // merged (B or C above) has ever been read from or written to directly, and
 // this must ONLY be called on one side of the merge, though it doesn't matter
 // which side.
 //
 // It is safe for the non-merged peers (A and D above) to be transferred,
 // closed, and/or written to before, during, or after the merge.
 int MergePorts(const PortRef& port_ref, const NodeName& destination_node_name,
                const PortName& destination_port_name);

 // Like above but merges two ports local to this node. Because both ports are
 // local this can also verify that neither port has been written to before the
 // merge. If this fails for any reason, both ports are closed. Otherwise OK
 // is returned and the ports' receiving peers are connected to each other.
 int MergeLocalPorts(const PortRef& port0_ref, const PortRef& port1_ref);

 // Called to inform this node that communication with another node is lost
 // indefinitely. This triggers cleanup of ports bound to this node.
 int LostConnectionToNode(const NodeName& node_name);

private:
 // Helper to ensure that a Node always calls into its delegate safely, i.e.
 // without holding any internal locks.
 class DelegateHolder {
  public:
   DelegateHolder(Node* node, NodeDelegate* delegate);
   ~DelegateHolder();

   DelegateHolder(const DelegateHolder&) = delete;
   void operator=(const DelegateHolder&) = delete;

   NodeDelegate* operator->() const {
     EnsureSafeDelegateAccess();
     return delegate_;
   }

  private:
#ifdef DEBUG
   void EnsureSafeDelegateAccess() const;
#else
   void EnsureSafeDelegateAccess() const {}
#endif

   Node* const node_;
   NodeDelegate* const delegate_;
 };

 int OnUserMessage(const PortRef& port_ref, const NodeName& from_node,
                   mozilla::UniquePtr<UserMessageEvent> message);
 int OnPortAccepted(const PortRef& port_ref,
                    mozilla::UniquePtr<PortAcceptedEvent> event);
 int OnObserveProxy(const PortRef& port_ref,
                    mozilla::UniquePtr<ObserveProxyEvent> event);
 int OnObserveProxyAck(const PortRef& port_ref,
                       mozilla::UniquePtr<ObserveProxyAckEvent> event);
 int OnObserveClosure(const PortRef& port_ref,
                      mozilla::UniquePtr<ObserveClosureEvent> event);
 int OnMergePort(const PortRef& port_ref,
                 mozilla::UniquePtr<MergePortEvent> event);
 int OnUserMessageReadAckRequest(
     const PortRef& port_ref,
     mozilla::UniquePtr<UserMessageReadAckRequestEvent> event);
 int OnUserMessageReadAck(const PortRef& port_ref,
                          mozilla::UniquePtr<UserMessageReadAckEvent> event);
 int OnUpdatePreviousPeer(const PortRef& port_ref,
                          mozilla::UniquePtr<UpdatePreviousPeerEvent> event);

 int AddPortWithName(const PortName& port_name, RefPtr<Port> port);
 void ErasePort(const PortName& port_name);

 // Check if the event is sent by the previous peer of the port to decide if
 // we can check the sequence number.
 // This is not the case for example for PortAccepted or broadcasted events.
 bool IsEventFromPreviousPeer(const Event& event);

 int AcceptEventInternal(const PortRef& port_ref, const NodeName& from_node,
                         ScopedEvent event);

 int SendUserMessageInternal(const PortRef& port_ref,
                             mozilla::UniquePtr<UserMessageEvent>* message);
 int MergePortsInternal(const PortRef& port0_ref, const PortRef& port1_ref,
                        bool allow_close_on_bad_state);
 void ConvertToProxy(Port* port, const NodeName& to_node_name,
                     PortName* port_name,
                     Event::PortDescriptor* port_descriptor,
                     PendingUpdatePreviousPeer* pending_update)
     MOZ_REQUIRES(ports_lock_);
 int AcceptPort(const PortName& port_name,
                const Event::PortDescriptor& port_descriptor);

 int PrepareToForwardUserMessage(const PortRef& forwarding_port_ref,
                                 Port::State expected_port_state,
                                 bool ignore_closed_peer,
                                 UserMessageEvent* message,
                                 NodeName* forward_to_node);
 int BeginProxying(const PortRef& port_ref);
 int ForwardUserMessagesFromProxy(const PortRef& port_ref);
 void InitiateProxyRemoval(const PortRef& port_ref);
 void TryRemoveProxy(const PortRef& port_ref);
 void DestroyAllPortsWithPeer(const NodeName& node_name,
                              const PortName& port_name);

 // Changes the peer node and port name referenced by |port|. Note that both
 // |ports_lock_| MUST be held through the extent of this method.
 // |local_port|'s lock must be held if and only if a reference to |local_port|
 // exist in |ports_|.
 void UpdatePortPeerAddress(const PortName& local_port_name, Port* local_port,
                            const NodeName& new_peer_node,
                            const PortName& new_peer_port)
     MOZ_REQUIRES(ports_lock_);

 // Removes an entry from |peer_port_map_| corresponding to |local_port|'s peer
 // address, if valid.
 void RemoveFromPeerPortMap(const PortName& local_port_name, Port* local_port)
     MOZ_REQUIRES(ports_lock_);

 // Swaps the peer information for two local ports. Used during port merges.
 // Note that |ports_lock_| must be held along with each of the two port's own
 // locks, through the extent of this method.
 void SwapPortPeers(const PortName& port0_name, Port* port0,
                    const PortName& port1_name, Port* port1)
     MOZ_REQUIRES(ports_lock_);

 // Sends an acknowledge request to the peer if the port has a non-zero
 // |sequence_num_acknowledge_interval|. This needs to be done when the port's
 // peer changes, as the previous peer proxy may not have forwarded any prior
 // acknowledge request before deleting itself.
 void MaybeResendAckRequest(const PortRef& port_ref);

 // Forwards a stored acknowledge request to the peer if the proxy has a
 // non-zero |sequence_num_acknowledge_interval|.
 void MaybeForwardAckRequest(const PortRef& port_ref);

 // Sends an acknowledge of the most recently read sequence number to the peer
 // if any messages have been read, and the port has a non-zero
 // |sequence_num_to_acknowledge|.
 void MaybeResendAck(const PortRef& port_ref);

 const NodeName name_;
 const DelegateHolder delegate_;

 // Just to clarify readability of the types below.
 using LocalPortName = PortName;
 using PeerPortName = PortName;

 // Guards access to |ports_| and |peer_port_maps_| below.
 //
 // This must never be acquired while an individual port's lock is held on the
 // same thread. Conversely, individual port locks may be acquired while this
 // one is held.
 //
 // Because UserMessage events may execute arbitrary user code during
 // destruction, it is also important to ensure that such events are never
 // destroyed while this (or any individual Port) lock is held.
 mozilla::Mutex ports_lock_{"Ports Lock"};
 std::unordered_map<LocalPortName, RefPtr<Port>> ports_
     MOZ_GUARDED_BY(ports_lock_);

 // Maps a peer port name to a list of PortRefs for all local ports which have
 // the port name key designated as their peer port. The set of local ports
 // which have the same peer port is expected to always be relatively small and
 // usually 1. Hence we just use a flat_map of local PortRefs keyed on each
 // local port's name.
 //
 // FIXME(nika): We don't have `base::flat_map` or a super equivalent type with
 // the same API, so just use a nested `std::unordered_map` for now. We should
 // probably change all of this to instead use our types eventually.
 using PeerPortMap =
     std::unordered_map<PeerPortName,
                        std::unordered_map<LocalPortName, PortRef>>;

 // A reverse mapping which can be used to find all local ports that reference
 // a given peer node or a local port that references a specific given peer
 // port on a peer node. The key to this map is the corresponding peer node
 // name.
 std::unordered_map<NodeName, PeerPortMap> peer_port_maps_
     MOZ_GUARDED_BY(ports_lock_);
};

}  // namespace ports
}  // namespace core
}  // namespace mojo

#endif  // MOJO_CORE_PORTS_NODE_H_