blob: 4e5379f68b140d1c2ae856e961feca729d23eee3 [file] [log] [blame]
/*
* Copyright (c) 2019 The WebRTC project authors. All Rights Reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
#ifndef API_TEST_NETWORK_EMULATION_MANAGER_H_
#define API_TEST_NETWORK_EMULATION_MANAGER_H_
#include <memory>
#include <vector>
#include "api/test/network_emulation/network_emulation_interfaces.h"
#include "api/test/simulated_network.h"
#include "api/units/timestamp.h"
#include "rtc_base/network.h"
#include "rtc_base/thread.h"
namespace webrtc {
// This API is still in development and can be changed without prior notice.
// These classes are forward declared here, because they used as handles, to
// make it possible for client code to operate with these abstractions and build
// required network configuration. With forward declaration here implementation
// is more readable, than with interfaces approach and cause user needn't any
// API methods on these abstractions it is acceptable here.
// EmulatedNetworkNode is an abstraction for some network in the real world,
// like 3G network between peers, or Wi-Fi for one peer and LTE for another.
// Multiple networks can be joined into chain emulating a network path from
// one peer to another.
class EmulatedNetworkNode;
// EmulatedRoute is handle for single route from one network interface on one
// peer device to another network interface on another peer device.
class EmulatedRoute;
struct EmulatedEndpointConfig {
enum class IpAddressFamily { kIpv4, kIpv6 };
IpAddressFamily generated_ip_family = IpAddressFamily::kIpv4;
// If specified will be used as IP address for endpoint node. Must be unique
// among all created nodes.
absl::optional<rtc::IPAddress> ip;
// Should endpoint be enabled or not, when it will be created.
// Enabled endpoints will be available for webrtc to send packets.
bool start_as_enabled = true;
};
// Provide interface to obtain all required objects to inject network emulation
// layer into PeerConnection. Also contains information about network interfaces
// accessible by PeerConnection.
class EmulatedNetworkManagerInterface {
public:
virtual ~EmulatedNetworkManagerInterface() = default;
virtual rtc::Thread* network_thread() = 0;
virtual rtc::NetworkManager* network_manager() = 0;
// Returns summarized network stats for endpoints for this manager.
virtual void GetStats(
std::function<void(EmulatedNetworkStats)> stats_callback) const = 0;
};
// Provides an API for creating and configuring emulated network layer.
// All objects returned by this API are owned by NetworkEmulationManager itself
// and will be deleted when manager will be deleted.
class NetworkEmulationManager {
public:
// Helper struct to simplify creation of simulated network behaviors. Contains
// non-owning pointers as the underlying instances are owned by the manager.
struct SimulatedNetworkNode {
SimulatedNetworkInterface* simulation;
EmulatedNetworkNode* node;
class Builder {
public:
explicit Builder(NetworkEmulationManager* net) : net_(net) {}
Builder() : net_(nullptr) {}
Builder(const Builder&) = default;
// Sets the config state, note that this will replace any previously set
// values.
Builder& config(BuiltInNetworkBehaviorConfig config);
Builder& delay_ms(int queue_delay_ms);
Builder& capacity_kbps(int link_capacity_kbps);
Builder& capacity_Mbps(int link_capacity_Mbps);
Builder& loss(double loss_rate);
Builder& packet_queue_length(int max_queue_length_in_packets);
SimulatedNetworkNode Build() const;
SimulatedNetworkNode Build(NetworkEmulationManager* net) const;
private:
NetworkEmulationManager* const net_;
BuiltInNetworkBehaviorConfig config_;
};
};
virtual ~NetworkEmulationManager() = default;
// Creates an emulated network node, which represents single network in
// the emulated network layer.
virtual EmulatedNetworkNode* CreateEmulatedNode(
BuiltInNetworkBehaviorConfig config) = 0;
virtual EmulatedNetworkNode* CreateEmulatedNode(
std::unique_ptr<NetworkBehaviorInterface> network_behavior) = 0;
virtual SimulatedNetworkNode::Builder NodeBuilder() = 0;
// Creates an emulated endpoint, which represents single network interface on
// the peer's device.
virtual EmulatedEndpoint* CreateEndpoint(EmulatedEndpointConfig config) = 0;
// Enable emulated endpoint to make it available for webrtc.
// Caller mustn't enable currently enabled endpoint.
virtual void EnableEndpoint(EmulatedEndpoint* endpoint) = 0;
// Disable emulated endpoint to make it unavailable for webrtc.
// Caller mustn't disable currently disabled endpoint.
virtual void DisableEndpoint(EmulatedEndpoint* endpoint) = 0;
// Creates a route between endpoints going through specified network nodes.
// This route is single direction only and describe how traffic that was
// sent by network interface |from| have to be delivered to the network
// interface |to|. Return object can be used to remove created route. The
// route must contains at least one network node inside it.
//
// Assume that E{0-9} are endpoints and N{0-9} are network nodes, then
// creation of the route have to follow these rules:
// 1. A route consists of a source endpoint, an ordered list of one or
// more network nodes, and a destination endpoint.
// 2. If (E1, ..., E2) is a route, then E1 != E2.
// In other words, the source and the destination may not be the same.
// 3. Given two simultaneously existing routes (E1, ..., E2) and
// (E3, ..., E4), either E1 != E3 or E2 != E4.
// In other words, there may be at most one route from any given source
// endpoint to any given destination endpoint.
// 4. Given two simultaneously existing routes (E1, ..., N1, ..., E2)
// and (E3, ..., N2, ..., E4), either N1 != N2 or E2 != E4.
// In other words, a network node may not belong to two routes that lead
// to the same destination endpoint.
virtual EmulatedRoute* CreateRoute(
EmulatedEndpoint* from,
const std::vector<EmulatedNetworkNode*>& via_nodes,
EmulatedEndpoint* to) = 0;
// Creates a route over the given |via_nodes| creating the required endpoints
// in the process. The returned EmulatedRoute pointer can be used in other
// calls as a transport route for message or cross traffic.
virtual EmulatedRoute* CreateRoute(
const std::vector<EmulatedNetworkNode*>& via_nodes) = 0;
// Removes route previously created by CreateRoute(...).
// Caller mustn't call this function with route, that have been already
// removed earlier.
virtual void ClearRoute(EmulatedRoute* route) = 0;
// Creates a simulated TCP connection using |send_route| for traffic and
// |ret_route| for feedback. This can be used to emulate HTTP cross traffic
// and to implement realistic reliable signaling over lossy networks.
// TODO(srte): Handle clearing of the routes involved.
virtual TcpMessageRoute* CreateTcpRoute(EmulatedRoute* send_route,
EmulatedRoute* ret_route) = 0;
// Creates EmulatedNetworkManagerInterface which can be used then to inject
// network emulation layer into PeerConnection. |endpoints| - are available
// network interfaces for PeerConnection. If endpoint is enabled, it will be
// immediately available for PeerConnection, otherwise user will be able to
// enable endpoint later to make it available for PeerConnection.
virtual EmulatedNetworkManagerInterface*
CreateEmulatedNetworkManagerInterface(
const std::vector<EmulatedEndpoint*>& endpoints) = 0;
};
} // namespace webrtc
#endif // API_TEST_NETWORK_EMULATION_MANAGER_H_