blob: 5e20be567f6b6baf5aaca15007992073e22b789d [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 <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>
#include "absl/strings/string_view.h"
#include "api/array_view.h"
#include "api/field_trials_view.h"
#include "api/packet_socket_factory.h"
#include "api/test/network_emulation/cross_traffic.h"
#include "api/test/network_emulation/network_emulation_interfaces.h"
#include "api/test/peer_network_dependencies.h"
#include "api/test/simulated_network.h"
#include "api/test/time_controller.h"
#include "api/units/data_rate.h"
#include "rtc_base/ip_address.h"
#include "rtc_base/network.h"
#include "rtc_base/network_constants.h"
#include "rtc_base/socket_address.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;
enum class EmulatedNetworkStatsGatheringMode {
// Gather main network stats counters. See more details on which particular
// metrics are collected in the `EmulatedNetworkStats` and
// `EmulatedNetworkNodeStats` documentation.
kDefault,
// kDefault + also gather per packet statistics. In this mode more memory
// will be used.
kDebug
};
struct EmulatedEndpointConfig {
enum class IpAddressFamily { kIpv4, kIpv6 };
// If specified will be used to name endpoint for logging purposes.
std::optional<std::string> name = std::nullopt;
IpAddressFamily generated_ip_family = IpAddressFamily::kIpv4;
// If specified will be used as IP address for endpoint node. Must be unique
// among all created nodes.
std::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;
// Network type which will be used to represent endpoint to WebRTC.
rtc::AdapterType type = rtc::AdapterType::ADAPTER_TYPE_UNKNOWN;
// Allow endpoint to send packets specifying source IP address different to
// the current endpoint IP address. If false endpoint will crash if attempt
// to send such packet will be done.
bool allow_send_packet_with_different_source_ip = false;
// Allow endpoint to receive packet with destination IP address different to
// the current endpoint IP address. If false endpoint will crash if such
// packet will arrive.
bool allow_receive_packets_with_different_dest_ip = false;
};
struct EmulatedTURNServerConfig {
EmulatedEndpointConfig client_config;
EmulatedEndpointConfig peer_config;
};
// EmulatedTURNServer is an abstraction for a TURN server.
class EmulatedTURNServerInterface {
public:
struct IceServerConfig {
std::string username;
std::string password;
std::string url;
};
virtual ~EmulatedTURNServerInterface() {}
// Get an IceServer configuration suitable to add to a PeerConnection.
virtual IceServerConfig GetIceServerConfig() const = 0;
// Get non-null client endpoint, an endpoint that accepts TURN allocations.
// This shall typically be connected to one or more webrtc endpoint.
virtual EmulatedEndpoint* GetClientEndpoint() const = 0;
// Returns socket address, which client should use to connect to TURN server
// and do TURN allocation.
virtual rtc::SocketAddress GetClientEndpointAddress() const = 0;
// Get non-null peer endpoint, that is "connected to the internet".
// This shall typically be connected to another TURN server.
virtual EmulatedEndpoint* GetPeerEndpoint() const = 0;
};
// 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;
// Returns non-null pointer to thread that have to be used as network thread
// for WebRTC to properly setup network emulation. Returned thread is owned
// by EmulatedNetworkManagerInterface implementation.
virtual rtc::Thread* network_thread() = 0;
// Returns non-null pointer to network manager that have to be injected into
// WebRTC to properly setup network emulation. Returned manager is owned by
// EmulatedNetworkManagerInterface implementation.
virtual rtc::NetworkManager* network_manager() = 0;
// Returns non-null pointer to packet socket factory that have to be injected
// into WebRTC to properly setup network emulation. Returned factory is owned
// by EmulatedNetworkManagerInterface implementation.
virtual rtc::PacketSocketFactory* packet_socket_factory() = 0;
webrtc::webrtc_pc_e2e::PeerNetworkDependencies network_dependencies() {
return {network_thread(), network_manager(), packet_socket_factory()};
}
// Returns list of endpoints that are associated with this instance. Pointers
// are guaranteed to be non-null and are owned by NetworkEmulationManager.
virtual std::vector<EmulatedEndpoint*> endpoints() const = 0;
// Passes summarized network stats for endpoints for this manager into
// specified `stats_callback`. Callback will be executed on network emulation
// internal task queue.
virtual void GetStats(
std::function<void(EmulatedNetworkStats)> stats_callback) const = 0;
};
enum class TimeMode { kRealTime, kSimulated };
// Called implicitly when parsing an ABSL_FLAG of type TimeMode.
// from the command line flag value `text`.
// Returns `true` and sets `*mode` on success;
// returns `false` and sets `*error` on failure.
bool AbslParseFlag(absl::string_view text, TimeMode* mode, std::string* error);
// AbslUnparseFlag returns a textual flag value corresponding to the TimeMode
// `mode`.
std::string AbslUnparseFlag(TimeMode mode);
// The construction-time configuration options for NetworkEmulationManager.
struct NetworkEmulationManagerConfig {
// The mode of the underlying time controller.
TimeMode time_mode = TimeMode::kRealTime;
// The mode that determines the set of metrics to collect into
// `EmulatedNetworkStats` and `EmulatedNetworkNodeStats`.
EmulatedNetworkStatsGatheringMode stats_gathering_mode =
EmulatedNetworkStatsGatheringMode::kDefault;
// Field trials that can alter the behavior of NetworkEmulationManager.
const FieldTrialsView* field_trials = nullptr;
// If this flag is set, NetworkEmulationManager ignores the sizes of peers'
// DTLS handshake packets when determining when to let the packets through
// a constrained emulated network. Actual hanshake's packet size is ignored
// and a hardcoded fake size is used to compute packet's use of link capacity.
// This is useful for tests that require deterministic packets scheduling
// timing-wise even when the sizes of DTLS hadshake packets are not
// deterministic. This mode make sense only together with the simulated time.
bool fake_dtls_handshake_sizes = false;
};
// 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(DataRate link_capacity);
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);
Builder& delay_standard_deviation_ms(int delay_standard_deviation_ms);
Builder& allow_reordering();
Builder& avg_burst_loss_length(int avg_burst_loss_length);
Builder& packet_overhead(int packet_overhead);
SimulatedNetworkNode Build(uint64_t random_seed = 1) const;
SimulatedNetworkNode Build(NetworkEmulationManager* net,
uint64_t random_seed = 1) const;
private:
NetworkEmulationManager* const net_;
BuiltInNetworkBehaviorConfig config_;
};
};
virtual ~NetworkEmulationManager() = default;
virtual TimeController* time_controller() = 0;
// Returns a mode in which underlying time controller operates.
virtual TimeMode time_mode() const = 0;
// Creates an emulated network node, which represents ideal network with
// unlimited capacity, no delay and no packet loss.
EmulatedNetworkNode* CreateUnconstrainedEmulatedNode() {
return CreateEmulatedNode(BuiltInNetworkBehaviorConfig());
}
// Creates an emulated network node, which represents single network in
// the emulated network layer. Uses default implementation on network behavior
// which can be configured with `config`. `random_seed` can be provided to
// alter randomization behavior.
virtual EmulatedNetworkNode* CreateEmulatedNode(
BuiltInNetworkBehaviorConfig config,
uint64_t random_seed = 1) = 0;
// Creates an emulated network node, which represents single network in
// the emulated network layer. `network_behavior` determines how created node
// will forward incoming packets to the next receiver.
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;
// Creates a default route between endpoints going through specified network
// nodes. Default route is used for packet when there is no known route for
// packet's destination IP.
//
// This route is single direction only and describe how traffic that was
// sent by network interface `from` have to be delivered in case if routing
// was unspecified. 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.
// 5. Any node N can belong to only one default route.
virtual EmulatedRoute* CreateDefaultRoute(
EmulatedEndpoint* from,
const std::vector<EmulatedNetworkNode*>& via_nodes,
EmulatedEndpoint* to) = 0;
// Removes route previously created by CreateRoute(...).
// Caller mustn't call this function with route, that have been already
// removed earlier. Removing a route that is currently in use will lead to
// packets being dropped.
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 a route over the given `via_nodes`. Returns an object that can be
// used to emulate network load with cross traffic over the created route.
virtual CrossTrafficRoute* CreateCrossTrafficRoute(
const std::vector<EmulatedNetworkNode*>& via_nodes) = 0;
// Starts generating cross traffic using given `generator`. Takes ownership
// over the generator.
virtual CrossTrafficGenerator* StartCrossTraffic(
std::unique_ptr<CrossTrafficGenerator> generator) = 0;
// Stops generating cross traffic that was started using given `generator`.
// The `generator` shouldn't be used after and the reference may be invalid.
virtual void StopCrossTraffic(CrossTrafficGenerator* generator) = 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;
// Passes combined network stats for all specified `endpoints` into specified
// `stats_callback`. Callback will be executed on network emulation
// internal task queue.
virtual void GetStats(
rtc::ArrayView<EmulatedEndpoint* const> endpoints,
std::function<void(EmulatedNetworkStats)> stats_callback) = 0;
// Passes combined network stats for all specified `nodes` into specified
// `stats_callback`. Callback will be executed on network emulation
// internal task queue.
virtual void GetStats(
rtc::ArrayView<EmulatedNetworkNode* const> nodes,
std::function<void(EmulatedNetworkNodeStats)> stats_callback) = 0;
// Create a EmulatedTURNServer.
// The TURN server has 2 endpoints that need to be connected with routes,
// - GetClientEndpoint() - the endpoint that accepts TURN allocations.
// - GetPeerEndpoint() - the endpoint that is "connected to the internet".
virtual EmulatedTURNServerInterface* CreateTURNServer(
EmulatedTURNServerConfig config) = 0;
// Create a pair of EmulatedNetworkManagerInterfaces connected to each other.
std::pair<EmulatedNetworkManagerInterface*, EmulatedNetworkManagerInterface*>
CreateEndpointPairWithTwoWayRoutes(
const BuiltInNetworkBehaviorConfig& config);
};
} // namespace webrtc
#endif // API_TEST_NETWORK_EMULATION_MANAGER_H_