3652dd30db
Bug: b/362492031, b/362492070, b/362492356, b/364207037, b/364831690 Change-Id: Ic889c731b98f8876c0ee31c0bda91a5a18b3add1 Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/362100 Reviewed-by: Mirko Bonadei <mbonadei@webrtc.org> Commit-Queue: Artem Titov <titovartem@webrtc.org> Cr-Commit-Position: refs/heads/main@{#42981}
138 lines
6.4 KiB
Markdown
138 lines
6.4 KiB
Markdown
<!-- go/cmark -->
|
|
<!--* freshness: {owner: 'titovartem' reviewed: '2024-09-09'} *-->
|
|
|
|
# Network Emulation Framework
|
|
|
|
[TOC]
|
|
|
|
## Disclamer
|
|
|
|
This documentation explain the implementation details of Network Emulation
|
|
Framework. Framework's public APIs are located in:
|
|
|
|
* [`/api/test/network_emulation_manager.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fnetwork_emulation_manager.h)
|
|
* [`/api/test/create_network_emulation_manager.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fcreate_network_emulation_manager.h)
|
|
* [`/api/test/network_emulation/network_emulation_interfaces.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fnetwork_emulation%2Fnetwork_emulation_interfaces.h)
|
|
* [`/api/test/simulated_network.h`](https://source.chromium.org/search?q=%2Fapi%2Ftest%2Fsimulated_network.h)
|
|
|
|
## 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:
|
|
|
|
|
|
|
|
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.
|
|
|
|
|