mozilla-central/third_party/libwebrtc/test/network/g3doc/index.md

Source code

Revision control

Copy as Markdown

Other Tools

<!-- go/cmark -->
<!--* freshness: {owner: 'titovartem' reviewed: '2021-03-01'} *-->
# Network Emulation Framework
[TOC]
## Disclamer
This documentation explain the implementation details of Network Emulation
Framework. Framework's public APIs are located in:
## Overview
Network Emulation Framework provides an ability to emulate network behavior
between different clients, including a WebRTC PeerConnection client. To
configure network behavior, the user can choose different options:
* Use predefined implementation that can be configured with parameters such as
packet loss, bandwidth, delay, etc.
* Custom implementation
Conceptually the framework provides the ability to define multiple endpoints and
routes used to connect them. All network related entities are created and
managed by single factory class `webrtc::NetworkEmulationManager` which is
implemented by `webrtc::test::NetworkEmulationManagerImpl` and can work in two
modes:
* Real time
* Simulated time
The manager has a dedicated task queue which pipes all packets through all
network routes from senders to receivers. This task queue behaviour is
determined by `webrtc::TimeController`, which is based on either in real time or
simulated time mode.
The network operates on IP level and supports only UDP for now.
## Abstractions
The framework contains the following public abstractions:
* `webrtc::NetworkBehaviorInterface` - defines how emulated network should
behave. It operates on packets metadata level and is responsible for telling
which packet at which time have to be delivered to the next receiver.
* `webrtc::EmulatedIpPacket` - represents a single packet that can be sent or
received via emulated network. It has source and destination address and
payload to transfer.
* `webrtc::EmulatedNetworkReceiverInterface` - generic packet receiver
interface.
* `webrtc::EmulatedEndpoint` - primary user facing abstraction of the
framework. It represents a network interface on client's machine. It has its
own unique IP address and can be used to send and receive packets.
`EmulatedEndpoint` implements `EmulatedNetworkReceiverInterface` to receive
packets from the network and provides an API to send packets to the network
and API to bind other `EmulatedNetworkReceiverInterface` which will be able
to receive packets from the endpoint. `EmulatedEndpoint` interface has the
only implementation: `webrtc::test::EmulatedEndpointImpl`.
* `webrtc::EmulatedNetworkNode` - represents single network in the real world,
like a 3G network between peers, or Wi-Fi for one peer and LTE for another.
Each `EmulatedNetworkNode` is a single direction connetion and to form
bidirectional connection between endpoints two nodes should be used.
Multiple nodes can be joined into chain emulating a network path from one
peer to another.
In public API this class is forward declared and fully accessible only by
the framework implementation.
Internally consist of two parts: `LinkEmulation`, which is responsible for
behavior of current `EmulatedNetworkNode` and `NetworkRouterNode` which is
responsible for routing packets to the next node or to the endpoint.
* `webrtc::EmulatedRoute` - represents single route from one network interface
on one device to another network interface on another device.
In public API this class is forward declared and fully accessible only by
the framework implementation.
It contains start and end endpoint and ordered list of `EmulatedNetworkNode`
which forms the single directional route between those endpoints.
The framework has also the following private abstractions:
* `webrtc::test::NetworkRouterNode` - an `EmulatedNetworkReceiverInterface`
that can route incoming packets to the next receiver based on internal IP
routing table.
* `webrtc::test::LinkEmulation` - an `EmulatedNetworkReceiverInterface` that
can emulate network leg behavior via `webrtc::NetworkBehaviorInterface`
interface.
For integrating with `webrtc::PeerConnection` there are helper abstractions:
* `webrtc::EmulatedNetworkManagerInterface` which is implemented by
`webrtc::test::EmulatedNetworkManager` and provides `rtc::Thread` and
`rtc::NetworkManager` for WebRTC to use as network thread for
`PeerConnection` and for `cricket::BasicPortAllocator`.
Implementation represent framework endpoints as `rtc::Network` to WebRTC.
## Architecture
Let's take a look on how framework's abstractions are connected to each other.
When the user wants to setup emulated network, first of all, they should create
an instance of `NetworkEmulationManager` using
`webrtc::CreateNetworkEmulationManager(...)` API. Then user should use a manager
to create at least one `EmulatedEndpoint` for each client. After endpoints, the
user should create required `EmulatedNetworkNode`s and with help of manager
chain them into `EmulatedRoute`s conecting desired endpoints.
Here is a visual overview of the emulated network architecture:
![Architecture](network_emulation_framework.png "Architecture")
When network is hooked into `PeerConnection` it is done through network thread
and `NetworkManager`. In the network thread the custom `rtc::SocketServer` is
provided: `webrtc::test::FakeNetworkSocketServer`. This custom socket server
will construct custom sockets (`webrtc::test::FakeNetworkSocket`), which
internally bind themselves to the required endpoint. All packets processing
inside socket have to be done on the `PeerConnection`'s network thread. When
packet is going from `PeerConnection` to the network it's already comming from
the network thread and when it's comming from the emulated network switch from
the Network Emulation Framework internal task queue and `PeerConnection`'s
network thread is done inside socket's `OnPacketReceived(...)` method.
![Network Injection](network_injection_into_peer_connection.png "Network Injection")