mediasoup 3.27.0 → 3.28.0

package/worker/test/src/RTC/BWE/TestProbePacketGenerator.cpp

@@ -0,0 +1,265 @@
+#include "common.hpp"
+#include "RTC/BWE/ProbePacketGenerator.hpp"
+#include "RTC/Consts.hpp"
+#include "RTC/RTP/Packet.hpp"
+#include "Utils.hpp"
+#include <catch2/catch_test_macros.hpp>
+#include <limits>
+#include <string>
+#include <vector>
+
+SCENARIO("BWE ProbePacketGenerator", "[bwe][probepacketgenerator]")
+{
+	// What a packet of a burst was when it was handed over, kept by value because
+	// every one of them is the very same instance.
+	struct HandedPacket
+	{
+		size_t length{ 0 };
+		uint16_t sequenceNumber{ 0 };
+		uint32_t timestamp{ 0 };
+		uint32_t ssrc{ 0 };
+		uint8_t payloadType{ 0 };
+		std::string mid;
+		bool hasAbsSendTime{ false };
+		bool hasTransportWideCc01{ false };
+		bool isPaddedTo4Bytes{ false };
+	};
+
+	class TestProbePacketGeneratorListener : public RTC::BWE::ProbePacketGenerator::Listener
+	{
+	public:
+		bool OnProbePacketGeneratorSendRtpPacket(
+		  RTC::BWE::ProbePacketGenerator* /*probePacketGenerator*/, RTC::RTP::Packet* packet) override
+		{
+			HandedPacket handedPacket;
+
+			handedPacket.length         = packet->GetLength();
+			handedPacket.sequenceNumber = packet->GetSequenceNumber();
+			handedPacket.timestamp      = packet->GetTimestamp();
+			handedPacket.ssrc           = packet->GetSsrc();
+			handedPacket.payloadType    = packet->GetPayloadType();
+
+			packet->ReadMid(handedPacket.mid);
+
+			uint32_t absSendTime;
+			uint16_t wideSeqNumber;
+
+			handedPacket.hasAbsSendTime       = packet->ReadAbsSendTime(absSendTime);
+			handedPacket.hasTransportWideCc01 = packet->ReadTransportWideCc01(wideSeqNumber);
+			handedPacket.isPaddedTo4Bytes     = packet->IsPaddedTo4Bytes();
+
+			this->handedPackets.push_back(handedPacket);
+
+			return this->handedPackets.size() < this->stopAfter;
+		}
+
+	public:
+		std::vector<HandedPacket> handedPackets;
+		// Packets after which the burst is given up on.
+		size_t stopAfter{ std::numeric_limits<size_t>::max() };
+	};
+
+	// How far the sequence number moved between two packets.
+	//
+	// NOTE: The subtraction is done back in 16 bits because the two operands are
+	// promoted to int, and the sequence number starts at a random value, so one
+	// run in every 65536 has it wrapping around right here.
+	const auto sequenceNumberDelta = [](const HandedPacket& from, const HandedPacket& to) -> uint16_t
+	{
+		return static_cast<uint16_t>(to.sequenceNumber - from.sequenceNumber);
+	};
+
+	// Total of what the given packets carried.
+	const auto totalLength = [](const std::vector<HandedPacket>& handedPackets) -> size_t
+	{
+		size_t total{ 0 };
+
+		for (const auto& handedPacket : handedPackets)
+		{
+			total += handedPacket.length;
+		}
+
+		return total;
+	};
+
+	TestProbePacketGeneratorListener listener;
+	RTC::BWE::ProbePacketGenerator probePacketGenerator(std::addressof(listener));
+
+	SECTION("a packet carries what makes it reportable")
+	{
+		probePacketGenerator.GeneratePackets(1);
+
+		REQUIRE(listener.handedPackets.size() == 1);
+
+		const auto& handedPacket = listener.handedPackets.at(0);
+
+		REQUIRE(handedPacket.ssrc == RTC::Consts::BweProbeRtpSsrc);
+		REQUIRE(handedPacket.payloadType == RTC::Consts::BweProbeRtpPayloadType);
+		REQUIRE(handedPacket.mid == RTC::Consts::BweProbeRtpMid);
+		REQUIRE(handedPacket.hasAbsSendTime);
+		REQUIRE(handedPacket.hasTransportWideCc01);
+	}
+
+	SECTION("and the room it leaves for them is one the sender can write into")
+	{
+		class WritingListener : public RTC::BWE::ProbePacketGenerator::Listener
+		{
+		public:
+			bool OnProbePacketGeneratorSendRtpPacket(
+			  RTC::BWE::ProbePacketGenerator* /*probePacketGenerator*/, RTC::RTP::Packet* packet) override
+			{
+				this->sentAtUs += 1000;
+				this->wideSeqNumber++;
+
+				REQUIRE(packet->UpdateAbsSendTime(Utils::Time::TimeUsToAbsSendTime(this->sentAtUs)));
+				REQUIRE(packet->UpdateTransportWideCc01(this->wideSeqNumber));
+
+				uint32_t readAbsSendTime;
+				uint16_t readWideSeqNumber;
+
+				REQUIRE(packet->ReadAbsSendTime(readAbsSendTime));
+				REQUIRE(readAbsSendTime == Utils::Time::TimeUsToAbsSendTime(this->sentAtUs));
+
+				REQUIRE(packet->ReadTransportWideCc01(readWideSeqNumber));
+				REQUIRE(readWideSeqNumber == this->wideSeqNumber);
+
+				return true;
+			}
+
+		public:
+			int64_t sentAtUs{ 100000000 };
+			uint16_t wideSeqNumber{ 0 };
+		};
+
+		WritingListener writingListener;
+		RTC::BWE::ProbePacketGenerator writingProbePacketGenerator(std::addressof(writingListener));
+
+		writingProbePacketGenerator.GeneratePackets(5000);
+
+		REQUIRE(writingListener.wideSeqNumber > 1);
+	}
+
+	SECTION("and is padded to 4 bytes whatever its size")
+	{
+		probePacketGenerator.GeneratePackets(5000);
+
+		REQUIRE(listener.handedPackets.size() > 1);
+
+		for (const auto& handedPacket : listener.handedPackets)
+		{
+			REQUIRE(handedPacket.isPaddedTo4Bytes);
+		}
+	}
+
+	SECTION("a burst that fits in one packet is exactly as long as it was asked for")
+	{
+		probePacketGenerator.GeneratePackets(1000);
+
+		REQUIRE(listener.handedPackets.size() == 1);
+		REQUIRE(listener.handedPackets.at(0).length == 1000);
+	}
+
+	SECTION("asking for less than a header still sends a whole one")
+	{
+		probePacketGenerator.GeneratePackets(1);
+
+		REQUIRE(listener.handedPackets.size() == 1);
+		REQUIRE(listener.handedPackets.at(0).length > 1);
+	}
+
+	SECTION("asking for nothing sends nothing")
+	{
+		probePacketGenerator.GeneratePackets(0);
+
+		REQUIRE(listener.handedPackets.empty());
+	}
+
+	SECTION("what is asked for is split into packets that carry at least that much")
+	{
+		constexpr size_t Size{ 5000 };
+
+		probePacketGenerator.GeneratePackets(Size);
+
+		REQUIRE(listener.handedPackets.size() > 1);
+		REQUIRE(totalLength(listener.handedPackets) >= Size);
+
+		for (const auto& handedPacket : listener.handedPackets)
+		{
+			REQUIRE(handedPacket.length <= RTC::BWE::ProbePacketGenerator::MaxPacketLength);
+		}
+	}
+
+	SECTION("and one that no burst could ever be is brought down to something sendable")
+	{
+		probePacketGenerator.GeneratePackets(std::numeric_limits<size_t>::max());
+
+		REQUIRE(!listener.handedPackets.empty());
+		REQUIRE(
+		  totalLength(listener.handedPackets) <= RTC::BWE::ProbePacketGenerator::MaxGeneratePacketsSize +
+		                                           RTC::BWE::ProbePacketGenerator::MaxPacketLength);
+	}
+
+	SECTION("and a burst of a single packet is not split")
+	{
+		probePacketGenerator.GeneratePackets(RTC::BWE::ProbePacketGenerator::MaxPacketLength);
+
+		REQUIRE(listener.handedPackets.size() == 1);
+		REQUIRE(listener.handedPackets.at(0).length == RTC::BWE::ProbePacketGenerator::MaxPacketLength);
+	}
+
+	SECTION("every packet moves the sequence number and the timestamp on")
+	{
+		probePacketGenerator.GeneratePackets(5000);
+
+		REQUIRE(listener.handedPackets.size() > 1);
+
+		for (size_t i{ 1 }; i < listener.handedPackets.size(); ++i)
+		{
+			const auto& previous = listener.handedPackets.at(i - 1);
+			const auto& current  = listener.handedPackets.at(i);
+
+			REQUIRE(sequenceNumberDelta(previous, current) == 1);
+			REQUIRE(current.timestamp != previous.timestamp);
+		}
+	}
+
+	SECTION("and the ones of a later burst carry on from the ones before")
+	{
+		probePacketGenerator.GeneratePackets(1);
+		probePacketGenerator.GeneratePackets(1);
+
+		REQUIRE(listener.handedPackets.size() == 2);
+
+		const auto& first  = listener.handedPackets.at(0);
+		const auto& second = listener.handedPackets.at(1);
+
+		REQUIRE(sequenceNumberDelta(first, second) == 1);
+	}
+
+	SECTION("and two of them count their own packets rather than each other's")
+	{
+		TestProbePacketGeneratorListener otherListener;
+		RTC::BWE::ProbePacketGenerator otherProbePacketGenerator(std::addressof(otherListener));
+
+		probePacketGenerator.GeneratePackets(1);
+		otherProbePacketGenerator.GeneratePackets(1);
+		probePacketGenerator.GeneratePackets(1);
+		otherProbePacketGenerator.GeneratePackets(1);
+
+		REQUIRE(listener.handedPackets.size() == 2);
+		REQUIRE(otherListener.handedPackets.size() == 2);
+
+		REQUIRE(sequenceNumberDelta(listener.handedPackets.at(0), listener.handedPackets.at(1)) == 1);
+		REQUIRE(
+		  sequenceNumberDelta(otherListener.handedPackets.at(0), otherListener.handedPackets.at(1)) == 1);
+	}
+
+	SECTION("a packet that cannot be sent stops the ones behind it")
+	{
+		listener.stopAfter = 2;
+
+		probePacketGenerator.GeneratePackets(50000);
+
+		REQUIRE(listener.handedPackets.size() == 2);
+	}
+}

package/worker/test/src/RTC/BWE/TestProbingScheduler.cpp

@@ -0,0 +1,260 @@
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include "RTC/BWE/ProbingScheduler.hpp"
+#include "mocks/include/MockShared.hpp"
+#include <catch2/catch_test_macros.hpp>
+#include <string_view>
+#include <vector>
+
+SCENARIO("BWE ProbingScheduler", "[bwe][probingscheduler]")
+{
+	// The clock starts well away from zero so that a mistake taking a time for a
+	// duration doesn't go unnoticed.
+	constexpr int64_t InitialTimeUs{ 100000000 };
+	constexpr std::string_view TimerLabel{ "probing-scheduler-next-probe" };
+
+	int64_t nowUs{ InitialTimeUs };
+
+	mocks::MockShared shared(/*getTimeUs*/
+	                         [&nowUs]() -> int64_t
+	                         {
+		                         return nowUs;
+	                         });
+
+	class TestProbingSchedulerListener : public RTC::BWE::ProbingScheduler::Listener
+	{
+	public:
+		bool OnProbingSchedulerSendRtpPacket(
+		  RTC::BWE::ProbingScheduler* /*probingScheduler*/,
+		  RTC::RTP::Packet* packet,
+		  const RTC::BWE::Types::ProbeCluster& probeCluster) override
+		{
+			if (!this->sendPackets)
+			{
+				return false;
+			}
+
+			this->sentLengths.push_back(packet->GetLength());
+			this->sentClusterIds.push_back(probeCluster.id);
+
+			return true;
+		}
+
+		size_t GetSentBytes() const
+		{
+			size_t sentBytes{ 0 };
+
+			for (const auto length : this->sentLengths)
+			{
+				sentBytes += length;
+			}
+
+			return sentBytes;
+		}
+
+	public:
+		std::vector<size_t> sentLengths;
+		// The burst each of those packets was handed over as part of.
+		std::vector<int64_t> sentClusterIds;
+		bool sendPackets{ true };
+	};
+
+	TestProbingSchedulerListener listener;
+
+	const auto makeClusterConfig = [](
+	                                 int64_t id,
+	                                 int64_t atUs,
+	                                 int64_t targetBitrate,
+	                                 int64_t minProbeDeltaUs) -> RTC::BWE::Types::ProbeClusterConfig
+	{
+		return RTC::BWE::Types::ProbeClusterConfig{ .id               = id,
+		                                            .atUs             = atUs,
+		                                            .targetBitrate    = targetBitrate,
+		                                            .targetDurationUs = 15 * 1000,
+		                                            .minProbeDeltaUs  = minProbeDeltaUs,
+		                                            .targetProbeCount = 5 };
+	};
+
+	// Move the clock to when the next shot is due and let it out. Answers whether
+	// there was one to begin with.
+	const auto emitNextShot = [&nowUs, &shared, TimerLabel]() -> bool
+	{
+		auto* timer = shared.GetTimer(TimerLabel);
+
+		if (!timer->IsActive())
+		{
+			return false;
+		}
+
+		nowUs = std::max(nowUs, timer->GetExpiresAtMs() * 1000);
+
+		return timer->EvaluateHasExpired();
+	};
+
+	SECTION("a burst is emitted on the turn of the loop that follows asking for it")
+	{
+		RTC::BWE::ProbingScheduler probingScheduler(std::addressof(listener), std::addressof(shared));
+
+		REQUIRE(!probingScheduler.IsProbing());
+		REQUIRE(listener.sentLengths.empty());
+
+		probingScheduler.CreateProbeClusters({ makeClusterConfig(0, nowUs, 900000, 2 * 1000) });
+
+		auto* timer = shared.GetTimer(TimerLabel);
+
+		REQUIRE(timer != nullptr);
+		// Asking for it doesn't put the send path in the caller's stack.
+		REQUIRE(listener.sentLengths.empty());
+		// But nothing is waited for either: it's due right away.
+		REQUIRE(timer->IsActive());
+		REQUIRE(timer->GetTimeoutMs() == 0);
+
+		REQUIRE(emitNextShot());
+
+		REQUIRE(!listener.sentLengths.empty());
+		REQUIRE(probingScheduler.IsProbing());
+		// Every packet is handed over as part of the burst it belongs to.
+		REQUIRE(listener.sentClusterIds.front() == 0);
+	}
+
+	SECTION("a burst goes out in as many shots as it was asked for")
+	{
+		constexpr int64_t TestBitrate{ 900000 };
+		constexpr int64_t MinProbeDeltaUs{ 2 * 1000 };
+		// What the burst is meant to carry, which is its bitrate held for the time
+		// it is meant to last, rounded to the nearest byte.
+		constexpr size_t MinBytes{ ((TestBitrate * (15 * 1000)) + 4000000) / (8 * 1000000) };
+
+		RTC::BWE::ProbingScheduler probingScheduler(std::addressof(listener), std::addressof(shared));
+
+		probingScheduler.CreateProbeClusters(
+		  { makeClusterConfig(0, nowUs, TestBitrate, MinProbeDeltaUs) });
+
+		size_t shots{ 0 };
+
+		while (emitNextShot())
+		{
+			++shots;
+		}
+
+		// Both counts have to be reached, since a burst of too few packets says
+		// nothing however many bytes it carried, and the other way round.
+		REQUIRE(shots >= 5);
+		REQUIRE(listener.GetSentBytes() >= MinBytes);
+
+		// And once it is done there is nothing left running.
+		REQUIRE(!probingScheduler.IsProbing());
+		REQUIRE(!shared.GetTimer(TimerLabel)->IsActive());
+	}
+
+	SECTION("the shots that piled up while the loop was held up go out together")
+	{
+		constexpr int64_t TestBitrate{ 900000 };
+		constexpr int64_t MinProbeDeltaUs{ 2 * 1000 };
+
+		RTC::BWE::ProbingScheduler probingScheduler(std::addressof(listener), std::addressof(shared));
+
+		probingScheduler.CreateProbeClusters(
+		  { makeClusterConfig(0, nowUs, TestBitrate, MinProbeDeltaUs) });
+
+		REQUIRE(emitNextShot());
+
+		const size_t packetsAfterFirstShot = listener.sentLengths.size();
+
+		REQUIRE(packetsAfterFirstShot > 0);
+
+		// The loop gives no sign of life for the time of several shots.
+		//
+		// NOTE: The span has to sit between two bounds, which is the only window
+		// where piling up happens at all. Below the time between two shots nothing
+		// piles up, and above `BitrateProberOptions::maxProbeDelayUs`, which
+		// defaults to 10 ms, the burst is given up on rather than emitted late, so
+		// there would be nothing left to send. Six milliseconds is inside both.
+		nowUs += 3 * MinProbeDeltaUs;
+
+		auto* timer = shared.GetTimer(TimerLabel);
+
+		REQUIRE(timer->IsActive());
+		REQUIRE(timer->EvaluateHasExpired());
+
+		// All of them went out on that single tick instead of one per turn of the
+		// loop, which would have stretched the burst well below its bitrate.
+		REQUIRE(listener.sentLengths.size() > packetsAfterFirstShot + 1);
+	}
+
+	SECTION("the shots of a burst are spaced by the time it asked for")
+	{
+		constexpr int64_t TestBitrate{ 900000 };
+		constexpr int64_t MinProbeDeltaUs{ 10 * 1000 };
+
+		RTC::BWE::ProbingScheduler probingScheduler(std::addressof(listener), std::addressof(shared));
+
+		probingScheduler.CreateProbeClusters(
+		  { makeClusterConfig(0, nowUs, TestBitrate, MinProbeDeltaUs) });
+
+		REQUIRE(emitNextShot());
+
+		// The burst is measured from when its first packet went out.
+		const int64_t startTimeUs = nowUs;
+		auto* timer               = shared.GetTimer(TimerLabel);
+
+		// The next shot is due once the bytes already gone out have been carried at
+		// the bitrate asked for, measured from the start of the burst.
+		const int64_t expectedNextUs =
+		  startTimeUs + ((static_cast<int64_t>(listener.GetSentBytes()) * 8 * 1000000) / TestBitrate);
+
+		REQUIRE(timer->IsActive());
+		// The tick lands just before the shot is due rather than just after, since
+		// what is left of the wait by then is under a millisecond and goes out
+		// anyway. A burst whose shots all left late would measure a bitrate below
+		// the one it was asked for.
+		REQUIRE(timer->GetExpiresAtMs() * 1000 <= expectedNextUs);
+		REQUIRE(expectedNextUs - (timer->GetExpiresAtMs() * 1000) < 1000);
+	}
+
+	SECTION("a listener that cannot send stops the burst")
+	{
+		RTC::BWE::ProbingScheduler probingScheduler(std::addressof(listener), std::addressof(shared));
+
+		listener.sendPackets = false;
+
+		probingScheduler.CreateProbeClusters({ makeClusterConfig(0, nowUs, 900000, 2 * 1000) });
+
+		REQUIRE(emitNextShot());
+		REQUIRE(listener.sentLengths.empty());
+
+		// Nothing went out, so there is no reason to believe that trying again
+		// would do any better.
+		REQUIRE(!shared.GetTimer(TimerLabel)->IsActive());
+	}
+
+	SECTION("a burst asked for while another one is being emitted waits for it")
+	{
+		constexpr int64_t TestBitrate{ 900000 };
+
+		RTC::BWE::ProbingScheduler probingScheduler(std::addressof(listener), std::addressof(shared));
+
+		// Both at once, which is what the controller does when it asks for the two
+		// bursts the connection opens with.
+		probingScheduler.CreateProbeClusters(
+		  { makeClusterConfig(0, nowUs, TestBitrate, 2 * 1000),
+			  makeClusterConfig(1, nowUs, TestBitrate, 2 * 1000) });
+
+		while (emitNextShot())
+		{
+			// Nothing to do, the shots go out on their own.
+		}
+
+		// Two whole bursts went out, not one.
+		constexpr size_t MinBytes{ ((TestBitrate * (15 * 1000)) + 4000000) / (8 * 1000000) };
+
+		REQUIRE(listener.GetSentBytes() >= 2 * MinBytes);
+		REQUIRE(!probingScheduler.IsProbing());
+
+		// And each of them was handed over as its own, in the order they were asked
+		// for and without mixing their packets.
+		REQUIRE(listener.sentClusterIds.front() == 0);
+		REQUIRE(listener.sentClusterIds.back() == 1);
+		REQUIRE(std::ranges::is_sorted(listener.sentClusterIds));
+	}
+}