mediasoup 3.27.1 → 3.29.0

package/worker/include/RTC/BWE/ProbeBitrateEstimator.hpp

@@ -0,0 +1,84 @@
+#ifndef MS_RTC_BWE_PROBE_BITRATE_ESTIMATOR_HPP
+#define MS_RTC_BWE_PROBE_BITRATE_ESTIMATOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <ankerl/unordered_dense.h>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Measures what a probe actually achieved.
+		 *
+		 * A probe is a burst of packets sent on purpose above the current estimate,
+		 * and the point of it is to learn the capacity of the link directly instead
+		 * of inferring it from the delay. This class gathers the feedback of the
+		 * packets of each burst and, once enough of the burst has come back, says at
+		 * what bitrate it was delivered.
+		 *
+		 * The answer is the lower of the rate it was sent at and the rate it
+		 * arrived at, because a burst that arrives faster than it was sent measures
+		 * the sender and not the link. And when it arrives clearly slower than it
+		 * was sent, that means the burst found the real capacity, so the answer is
+		 * taken slightly below what arrived in order not to overuse it right away.
+		 *
+		 * A burst that too little of came back, that was sent or received over too
+		 * long a span, or that arrived far faster than it was sent, is discarded
+		 * rather than believed.
+		 */
+		class ProbeBitrateEstimator
+		{
+		private:
+			/**
+			 * What has been gathered so far about a burst.
+			 */
+			struct AggregatedCluster
+			{
+				int64_t numProbes{ 0 };
+				std::optional<int64_t> firstSendTimeUs;
+				std::optional<int64_t> lastSendTimeUs;
+				std::optional<int64_t> firstReceiveTimeUs;
+				std::optional<int64_t> lastReceiveTimeUs;
+				// Size of the packet sent last, which the span of send times doesn't
+				// cover.
+				int64_t sizeLastSend{ 0 };
+				// Size of the packet received first, which the span of receive times
+				// doesn't cover.
+				int64_t sizeFirstReceive{ 0 };
+				int64_t sizeTotal{ 0 };
+			};
+
+		public:
+			/**
+			 * Feed the feedback of a packet that belongs to a probe.
+			 *
+			 * @returns The bitrate the probe achieved (bps), or no value while its
+			 * burst cannot be trusted yet or at all.
+			 */
+			std::optional<int64_t> HandleProbeAndEstimateBitrate(const Types::PacketResult& packetResult);
+
+			/**
+			 * Take the latest measured bitrate (bps), leaving none behind, so that a
+			 * probe is never acted upon twice.
+			 */
+			std::optional<int64_t> FetchAndResetLastEstimatedBitrate();
+
+		private:
+			/**
+			 * Forget the bursts whose last packet arrived long enough ago that they
+			 * cannot receive anything else.
+			 */
+			void EraseOldClusters(int64_t arrivalTimeUs);
+
+		private:
+			// Bursts being gathered, by their id. Nothing looks at them in any
+			// particular order.
+			ankerl::unordered_dense::map<int64_t, AggregatedCluster> clusters;
+			std::optional<int64_t> estimatedBitrate;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/ProbeController.hpp

@@ -0,0 +1,379 @@
+#ifndef MS_RTC_BWE_PROBE_CONTROLLER_HPP
+#define MS_RTC_BWE_PROBE_CONTROLLER_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <vector>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Decides when to probe and at what bitrate.
+		 *
+		 * Probing is the only way to discover capacity that is not being used,
+		 * because nothing measured while sending below the link's capacity says
+		 * anything about how much more it could carry. So this asks for bursts: at
+		 * the start of a connection to climb fast instead of waiting for the slow
+		 * ramp, periodically while the sender isn't filling the link, when the
+		 * application asks for more than is being sent, and after a large drop to
+		 * check whether it was real.
+		 *
+		 * It decides nothing else: every method returns the bursts to launch, and
+		 * emitting them is somebody else's job. And it refuses to probe whenever
+		 * something is already known to be holding the estimate back, since a burst
+		 * then measures that limit rather than the link.
+		 */
+		class ProbeController
+		{
+		public:
+			/**
+			 * Why the estimate is not free to grow, which decides whether probing
+			 * makes sense at all.
+			 */
+			enum class BandwidthLimitedCause : uint8_t
+			{
+				/**
+				 * Loss is what limits the estimate, and it's growing back.
+				 */
+				LOSS_LIMITED_BWE_INCREASING = 0,
+				/**
+				 * Loss is what limits the estimate and it isn't growing.
+				 */
+				LOSS_LIMITED_BWE,
+				/**
+				 * The delay based path is what limits the estimate.
+				 */
+				DELAY_BASED_LIMITED,
+				/**
+				 * The same, with the delay growing right now.
+				 */
+				DELAY_BASED_LIMITED_DELAY_INCREASED,
+				/**
+				 * A round trip time long enough to mean that the queues are full.
+				 */
+				RTT_BASED_BACK_OFF_HIGH_RTT
+			};
+
+			/**
+			 * @remarks
+			 * - Every constraint documented below is checked by the constructor and
+			 *   aborts when it doesn't hold. These options are set from C++ alone,
+			 *   never from the network nor from the API, so breaking one of them is a
+			 *   programming error.
+			 */
+			struct ProbeControllerOptions
+			{
+				/**
+				 * Factor applied to the start bitrate for the first burst of the
+				 * connection.
+				 */
+				double firstExponentialProbeScale{ 3.0 };
+				/**
+				 * The same for the second one, or no value to send just one.
+				 */
+				std::optional<double> secondExponentialProbeScale{ 6.0 };
+				/**
+				 * Factor applied to the measured bitrate for each burst that follows one
+				 * whose result was good enough to keep climbing.
+				 */
+				double furtherExponentialProbeScale{ 2.0 };
+				/**
+				 * Fraction of the bitrate a burst was sent at that its result has to
+				 * exceed for another one to follow it.
+				 */
+				double furtherProbeThreshold{ 0.7 };
+				/**
+				 * Whether to stop climbing as soon as the measured bitrate is already
+				 * above what the application asked for.
+				 */
+				bool abortFurtherProbeIfMaxLowerThanCurrent{ false };
+				/**
+				 * How long after the first burst the initial ones keep being repeated,
+				 * while repeated initial probing is enabled.
+				 */
+				int64_t repeatedInitialProbingTimePeriodUs{ 5 * 1000 * 1000 };
+				/**
+				 * How long each of those initial bursts lasts. It's longer than a usual
+				 * one because there is no traffic yet to measure against.
+				 */
+				int64_t initialProbeDurationUs{ 100 * 1000 };
+				/**
+				 * Time between two consecutive bursts of packets within one of those
+				 * initial probes.
+				 *
+				 * @remarks
+				 * - It cannot be zero, since it's what the bitrate of a burst is held
+				 *   over to decide how many bytes each of its shots carries.
+				 */
+				int64_t initialMinProbeDeltaUs{ 20 * 1000 };
+				/**
+				 * Whether bursts keep being sent while the sender is not filling the
+				 * link, which is the only way the estimate grows when the traffic
+				 * itself is not enough to measure with.
+				 */
+				bool enablePeriodicAlrProbing{ false };
+				/**
+				 * How often to probe while the sender is not filling the link.
+				 */
+				int64_t alrProbingIntervalUs{ 5 * 1000 * 1000 };
+				/**
+				 * Factor applied to the estimate for those bursts.
+				 */
+				double alrProbeScale{ 2.0 };
+				/**
+				 * How often to probe while an upper bound of the link capacity is known,
+				 * or no limit at all to never do it, which is what turns that whole path
+				 * off.
+				 */
+				int64_t networkStateEstimateProbingIntervalUs{ Types::TimeUsInfinite };
+				/**
+				 * Fraction of that upper bound below which the estimate is low enough to
+				 * keep probing periodically.
+				 */
+				double probeIfEstimateLowerThanNetworkStateEstimateRatio{ 0.0 };
+				/**
+				 * How often to probe while the estimate is that low.
+				 */
+				int64_t estimateLowerThanNetworkStateEstimateProbingIntervalUs{ 3 * 1000 * 1000 };
+				/**
+				 * Factor applied to that upper bound when it's what bounds the burst.
+				 */
+				double networkStateProbeScale{ 1.0 };
+				/**
+				 * How long a burst lasts when that upper bound is known and is above
+				 * what the burst aims for.
+				 */
+				int64_t networkStateProbeDurationUs{ 15 * 1000 };
+				/**
+				 * Time between two consecutive bursts of packets in that case.
+				 *
+				 * @remarks
+				 * - It cannot be zero, since it's what the bitrate of a burst is held
+				 *   over to decide how many bytes each of its shots carries.
+				 */
+				int64_t networkStateMinProbeDeltaUs{ 20 * 1000 };
+				/**
+				 * Whether to probe when the application raises how much it wants to
+				 * send.
+				 */
+				bool probeOnMaxAllocatedBitrateChange{ true };
+				/**
+				 * Whether to do it also while the sender is filling the link.
+				 */
+				bool probeOnMaxAllocatedBitrateChangeWithoutAlr{ true };
+				/**
+				 * Factor applied to what the application asks for, for the first of
+				 * those bursts, or no value to send none.
+				 */
+				std::optional<double> firstAllocationProbeScale{ 1.0 };
+				/**
+				 * The same for the second one, or no value to send just one.
+				 */
+				std::optional<double> secondAllocationProbeScale{ 2.0 };
+				/**
+				 * Factor applied to the current estimate, which is how far above it
+				 * those bursts are allowed to aim.
+				 */
+				double allocationProbeLimitByCurrentScale{ 2.0 };
+				/**
+				 * Packets a burst is meant to be made of.
+				 */
+				int64_t minProbePacketsSent{ 5 };
+				/**
+				 * How long a burst lasts.
+				 */
+				int64_t minProbeDurationUs{ 15 * 1000 };
+				/**
+				 * Time between two consecutive bursts of packets within a probe.
+				 *
+				 * @remarks
+				 * - It cannot be zero, since it's what the bitrate of a burst is held
+				 *   over to decide how many bytes each of its shots carries.
+				 */
+				int64_t minProbeDeltaUs{ 2 * 1000 };
+				/**
+				 * Factor applied to the estimate that bounds a burst while loss is what
+				 * limits it and it's growing back.
+				 */
+				double lossLimitedProbeScale{ 1.5 };
+				/**
+				 * Fraction of the maximum above which the estimate is already high
+				 * enough for a burst to be pointless. Zero never skips one.
+				 */
+				double skipIfEstimateLargerThanFractionOfMax{ 0.0 };
+				/**
+				 * Factor applied to what the application asks for when deciding that.
+				 */
+				double skipProbeMaxAllocatedScale{ 1.0 };
+				/**
+				 * Whether a large drop may be probed even while the sender is filling
+				 * the link.
+				 */
+				bool rapidRecoveryExperiment{ false };
+			};
+
+		private:
+			/**
+			 * Where the climbing that follows the first burst of a connection is.
+			 */
+			enum class State : uint8_t
+			{
+				/**
+				 * Nothing has been probed yet.
+				 */
+				INIT,
+				/**
+				 * A burst went out and its result decides whether another one follows.
+				 */
+				WAITING_FOR_PROBING_RESULT,
+				/**
+				 * There is nothing left to climb.
+				 */
+				PROBING_COMPLETE
+			};
+
+		public:
+			ProbeController();
+
+			explicit ProbeController(ProbeControllerOptions options);
+
+			/**
+			 * Bounds set by the application, plus the bitrate to start from.
+			 *
+			 * @param maxBitrate - `Types::BitrateInfinite` for no limit, in which case
+			 * the highest bitrate that may be probed applies instead.
+			 */
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> SetBitrates(
+			  int64_t minBitrate, int64_t startBitrate, int64_t maxBitrate, int64_t nowUs);
+
+			/**
+			 * Total of what the application wants to send, which is not the same as
+			 * the maximum it allows: it's the sum over the streams being sent.
+			 */
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> OnMaxTotalAllocatedBitrate(
+			  int64_t maxTotalAllocatedBitrate, int64_t nowUs);
+
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> OnNetworkAvailability(
+			  bool networkAvailable, int64_t nowUs);
+
+			/**
+			 * Feed the current estimate and what is holding it back.
+			 */
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> SetEstimatedBitrate(
+			  int64_t bitrate, BandwidthLimitedCause bandwidthLimitedCause, int64_t nowUs);
+
+			/**
+			 * Whether the initial bursts keep being repeated for a while, which only
+			 * makes sense until there is traffic of its own to measure.
+			 */
+			void EnableRepeatedInitialProbing(bool enable)
+			{
+				this->repeatedInitialProbingEnabled = enable;
+			}
+
+			void SetAlrStartTimeUs(std::optional<int64_t> alrStartTimeUs)
+			{
+				this->alrStartTimeUs = alrStartTimeUs;
+			}
+
+			void SetAlrEndedTimeUs(int64_t alrEndedTimeUs)
+			{
+				this->alrEndedTimeUs = alrEndedTimeUs;
+			}
+
+			/**
+			 * Ask for a burst after the estimate has come back up from a large drop,
+			 * to tell a real drop from a passing one.
+			 */
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> RequestProbe(int64_t nowUs);
+
+			/**
+			 * Upper bound of the link capacity as measured elsewhere (bps), which
+			 * bounds what a burst may aim for.
+			 *
+			 * @remarks
+			 * - `Types::BitrateInfinite` means that nothing measured it, which is what
+			 *   the link capacity estimator answers while it has no estimate, and is
+			 *   kept as no bound at all rather than as an enormous one.
+			 */
+			void SetLinkCapacityUpperBound(int64_t linkCapacityUpperBound)
+			{
+				this->linkCapacityUpperBound = linkCapacityUpperBound != Types::BitrateInfinite
+				                                 ? std::optional<int64_t>(linkCapacityUpperBound)
+				                                 : std::nullopt;
+			}
+
+			/**
+			 * Forget what was probed, leaving the settings alone, so that the climbing
+			 * of a new connection starts over.
+			 */
+			void Reset(int64_t nowUs);
+
+			/**
+			 * Reconsider whether a burst is due, which is what drives the periodic
+			 * ones.
+			 */
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> Process(int64_t nowUs);
+
+		private:
+			void UpdateState(State newState);
+
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> InitiateExponentialProbing(int64_t nowUs);
+
+			/**
+			 * Turn the given bitrates into bursts, bounding them by everything that
+			 * applies and refusing them altogether while something is known to be
+			 * holding the estimate back.
+			 *
+			 * @param probeFurther - Whether the result of these bursts may lead to
+			 * another one.
+			 */
+			[[nodiscard]] std::vector<Types::ProbeClusterConfig> InitiateProbing(
+			  int64_t nowUs, const std::vector<int64_t>& bitratesToProbe, bool probeFurther);
+
+			bool IsTimeForAlrProbe(int64_t nowUs) const;
+
+			bool IsTimeForNetworkStateProbe(int64_t nowUs) const;
+
+			bool IsTimeForNextRepeatedInitialProbe(int64_t nowUs) const;
+
+			Types::ProbeClusterConfig CreateProbeClusterConfig(int64_t nowUs, int64_t bitrate);
+
+		private:
+			// Passed by argument.
+			const ProbeControllerOptions options;
+			// Others.
+			State state{ State::INIT };
+			bool networkAvailable{ false };
+			bool repeatedInitialProbingEnabled{ false };
+			BandwidthLimitedCause bandwidthLimitedCause{ BandwidthLimitedCause::DELAY_BASED_LIMITED };
+			// Instant until which the initial bursts keep being repeated.
+			std::optional<int64_t> lastAllowedRepeatedInitialProbeAtUs;
+			// Bitrate a burst has to beat for another one to follow it, or
+			// `Types::BitrateInfinite` while nothing is to follow.
+			int64_t minBitrateToProbeFurther{ Types::BitrateInfinite };
+			std::optional<int64_t> lastProbingInitiatedAtUs;
+			int64_t estimatedBitrate{ 0 };
+			// Upper bound of the link capacity as measured elsewhere, or no value
+			// while nothing measured it.
+			std::optional<int64_t> linkCapacityUpperBound;
+			int64_t startBitrate{ 0 };
+			int64_t maxBitrate{ Types::BitrateInfinite };
+			std::optional<int64_t> lastBweDropProbingAtUs;
+			std::optional<int64_t> alrStartTimeUs;
+			std::optional<int64_t> alrEndedTimeUs;
+			// Instant of the latest large drop of the estimate, and what it was worth
+			// just before it.
+			std::optional<int64_t> lastLargeDropAtUs;
+			int64_t bitrateBeforeLastLargeDrop{ 0 };
+			// Total of what the application wants to send.
+			int64_t maxTotalAllocatedBitrate{ 0 };
+			// Id given to the next burst, which never repeats.
+			int64_t nextProbeClusterId{ 1 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/ProbePacketGenerator.hpp

@@ -0,0 +1,126 @@
+#ifndef MS_RTC_BWE_PROBE_PACKET_GENERATOR_HPP
+#define MS_RTC_BWE_PROBE_PACKET_GENERATOR_HPP
+
+#include "common.hpp"
+#include "RTC/RTP/Packet.hpp"
+#include <array>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Makes the RTP packets a probing burst is made of.
+		 *
+		 * A burst asks for a number of bytes to be put on the wire over a few
+		 * milliseconds, and those bytes have to travel as RTP so that the receiver
+		 * reports when each of them arrived. This turns the bytes into packets and
+		 * hands them over one by one.
+		 *
+		 * What it produces is a stream of its own that carries nothing: a fixed SSRC
+		 * the receiver has negotiated, a payload of zeroes that nothing decodes, and
+		 * the header extensions that make the packets reportable. The only thing ever
+		 * read back from them is when each one arrived.
+		 */
+		class ProbePacketGenerator
+		{
+		public:
+			class Listener
+			{
+			public:
+				virtual ~Listener() = default;
+
+			public:
+				/**
+				 * A packet of the burst is ready.
+				 *
+				 * @remarks
+				 * - The packet must be sent before returning, since the next one is
+				 *   built over the very same instance.
+				 * - It carries room for the abs-send-time and for the transport wide
+				 *   sequence number but no value for either, so both have to be written
+				 *   here.
+				 * - Whoever measures the burst has to be told how much of it went out,
+				 *   so the length of the packet is reported from here as well.
+				 * - This must not destroy the `ProbePacketGenerator`, not even
+				 *   indirectly. It goes on reading its own members after this returns.
+				 */
+				virtual void OnProbePacketGeneratorSendRtpPacket(
+				  ProbePacketGenerator* probePacketGenerator, RTC::RTP::Packet* packet) = 0;
+			};
+
+#ifdef MS_TEST
+		public:
+#else
+		private:
+#endif
+			/**
+			 * Largest a packet of a burst may be (bytes), which leaves room below the
+			 * MTU for the overhead that encrypting it adds on the way out.
+			 */
+			static constexpr size_t MaxPacketLength{ 1400 };
+
+			/**
+			 * Most bytes a single burst may be asked for (bytes), so 2.5 MB, which is
+			 * 1 Gbps held for 20 ms.
+			 *
+			 * @remarks
+			 * - A burst larger than this is taken as one that cannot be real, and
+			 *   asking for it would have this handing packets over for a very long
+			 *   while, all within a single iteration of the event loop.
+			 * - Those two are the highest bitrate the bandwidth estimation deals in
+			 *   and the longest time whoever asks for a burst leaves between two of
+			 *   its shots, neither of which this can enforce.
+			 */
+			static constexpr size_t MaxGeneratePacketsSize{ 2500000 };
+
+		public:
+			explicit ProbePacketGenerator(Listener* listener);
+
+			~ProbePacketGenerator() = default;
+
+			// NOTE: The packet is written over a buffer of this very instance, so one
+			// that was copied or moved would keep writing over the buffer of the one
+			// it came from.
+			ProbePacketGenerator(const ProbePacketGenerator&)            = delete;
+			ProbePacketGenerator& operator=(const ProbePacketGenerator&) = delete;
+
+			/**
+			 * Smallest packet this can make (bytes), which is its header and its
+			 * extensions and no payload at all.
+			 */
+			size_t GetMinPacketLength() const
+			{
+				return this->minPacketLength;
+			}
+
+			/**
+			 * Hand over the packets that carry the given count of bytes.
+			 *
+			 * @remarks
+			 * - What goes out is at least what was asked for, since a burst falling
+			 *   short of the bytes it was meant to carry measures something else, and
+			 *   the last packet can't be smaller than a header.
+			 */
+			void GeneratePackets(size_t size);
+
+		private:
+			// Passed by argument.
+			Listener* listener{ nullptr };
+			// Others.
+			// Bytes the packet is written over. It belongs to this instance rather
+			// than being shared, since the packet's header lives in it and the
+			// sequence number of the next packet is read back from there. The empty
+			// braces zero it, so the payload never carries whatever was in that
+			// memory before.
+			std::array<uint8_t, MaxPacketLength> packetBuffer{};
+			// Allocated by this.
+			std::unique_ptr<RTC::RTP::Packet> packet;
+			// Length of the packet with no payload at all, so its header and its
+			// extensions.
+			size_t minPacketLength{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif