mediasoup 3.27.1 → 3.28.0

package/worker/include/DepLibUV.hpp

@@ -36,6 +36,19 @@ public:
 		return static_cast<int64_t>(uv_hrtime() / 1000);
 	}
 
+	/**
+	 * Time at which the current iteration of the event loop began (ms).
+	 *
+	 * @remarks
+	 * - It is taken once per iteration and cached, so every caller within the same one
+	 *   gets the very same value no matter how long the iteration takes. That is what
+	 *   tells two iterations apart, which the clocks above cannot do.
+	 */
+	static uint64_t GetLoopTimeMs()
+	{
+		return uv_now(DepLibUV::GetLoop());
+	}
+
 	/**
 	 * Offset between our own monotonic clock and the NTP epoch (us).
 	 *

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

@@ -0,0 +1,97 @@
+#ifndef MS_RTC_BWE_ALR_DETECTOR_HPP
+#define MS_RTC_BWE_ALR_DETECTOR_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/IntervalBudget.hpp"
+#include "SharedInterface.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Tells whether the sender is not sending enough to fill the link.
+		 *
+		 * While that is the case nothing measured says anything about the capacity
+		 * of the link, because what arrives is only what was sent: the delay doesn't
+		 * grow, no packet is lost, and the bitrate that gets acknowledged is the one
+		 * chosen rather than the one the link can carry. So the estimate cannot grow
+		 * on its own, and the only way out is to probe.
+		 *
+		 * The question is answered by giving the sender a budget that refills at a
+		 * fraction of the estimated bitrate and is spent as bytes go out. A budget
+		 * that keeps growing means the sender is not using what it was given.
+		 *
+		 * @remarks
+		 * - For a browser this is an odd situation, but for an SFU whose consumers
+		 *   sit on low layers it is the normal state.
+		 */
+		class AlrDetector
+		{
+		public:
+			struct AlrDetectorOptions
+			{
+				/**
+				 * Fraction of the estimated bitrate the sender is expected to be using.
+				 * The budget refills at that fraction rather than at the whole estimate,
+				 * so that staying somewhat below it doesn't count as not filling the
+				 * link.
+				 */
+				double bandwidthUsageRatio{ 0.65 };
+				/**
+				 * Level the budget has to grow past for the sender to be taken as not
+				 * filling the link.
+				 */
+				double startBudgetLevelRatio{ 0.80 };
+				/**
+				 * Level the budget has to fall back below for it to stop being taken as
+				 * such. It is lower than the one above so that a short burst doesn't end
+				 * the state.
+				 */
+				double stopBudgetLevelRatio{ 0.50 };
+			};
+
+		public:
+			explicit AlrDetector(SharedInterface* shared);
+
+			AlrDetector(SharedInterface* shared, AlrDetectorOptions options);
+
+			/**
+			 * Feed bytes that have just left towards the network.
+			 *
+			 * @param sentAtUs - Instant at which they left, which is what the span of
+			 *   time they were sent over is measured with.
+			 */
+			void OnBytesSent(int64_t bytesSent, int64_t sentAtUs);
+
+			/**
+			 * Bitrate the sender is expected to be able to use (bps).
+			 */
+			void SetEstimatedBitrate(int64_t bitrate);
+
+			/**
+			 * Instant at which the sender started not filling the link, or no value
+			 * while it is filling it.
+			 */
+			std::optional<int64_t> GetAlrStartTimeUs() const
+			{
+				return this->alrStartTimeUs;
+			}
+
+		private:
+			// Passed by argument.
+			SharedInterface* shared{ nullptr };
+			const AlrDetectorOptions options;
+			// Others.
+			// Budget of what the sender was expected to use, whose level is the whole
+			// signal this produces.
+			IntervalBudget alrBudget;
+			// Instant of the latest send, which is what the span of the next one is
+			// measured against.
+			std::optional<int64_t> lastSentAtUs;
+			std::optional<int64_t> alrStartTimeUs;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

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

@@ -0,0 +1,217 @@
+#ifndef MS_RTC_BWE_BITRATE_PROBER_HPP
+#define MS_RTC_BWE_BITRATE_PROBER_HPP
+
+#include "common.hpp"
+#include "RTC/BWE/BweTypes.hpp"
+#include <queue>
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Paces out the bursts that somebody else decided to send.
+		 *
+		 * It takes the bursts asked for, keeps them in the order they were asked for,
+		 * and answers a single question over and over: at what instant may the next
+		 * packet of the current one go out, and how many bytes should it carry. It
+		 * sends nothing itself.
+		 *
+		 * The spacing is what makes a burst worth anything. A burst is a bitrate held
+		 * for a few milliseconds, so letting the packets go as fast as the socket
+		 * takes them measures the queue of whoever is in the way rather than the link.
+		 * So each instant is computed from the start of the burst and the bytes gone
+		 * out so far, which keeps the whole of it close to the bitrate asked for even
+		 * when a packet leaves late.
+		 */
+		class BitrateProber
+		{
+		private:
+			/**
+			 * Whether bursts are being emitted, and why not when they are not.
+			 */
+			enum class State : uint8_t
+			{
+				/**
+				 * There may be bursts waiting, but none of them has started.
+				 */
+				INACTIVE,
+				/**
+				 * A burst is being emitted.
+				 */
+				ACTIVE
+			};
+
+			/**
+			 * A burst that was asked for, and how much of it has gone out.
+			 */
+			struct Cluster
+			{
+				/**
+				 * What travels with each of its packets, and what makes its result
+				 * trustworthy.
+				 */
+				Types::ProbeCluster probeCluster;
+				/**
+				 * Bitrate it is meant to be sent at (bps).
+				 */
+				int64_t sendBitrate{ 0 };
+				/**
+				 * Time between two consecutive bursts of packets within it.
+				 */
+				int64_t minProbeDeltaUs{ 0 };
+				/**
+				 * Instant at which it was asked for, which is what makes it go stale.
+				 */
+				int64_t requestedAtUs{ 0 };
+				/**
+				 * Instant at which its first packet went out, or no value while none
+				 * has.
+				 */
+				std::optional<int64_t> startedAtUs;
+				int64_t sentProbes{ 0 };
+				int64_t sentBytes{ 0 };
+			};
+
+		public:
+			struct BitrateProberOptions
+			{
+				/**
+				 * How late a packet of a burst may go out before the whole burst is
+				 * given up on, since one sent too slowly no longer measures the bitrate
+				 * it was meant to.
+				 */
+				int64_t maxProbeDelayUs{ 10 * 1000 };
+				/**
+				 * Size a packet has to reach for a burst to start on it (bytes).
+				 *
+				 * @remarks
+				 * - It only applies while the bursts are made of traffic that somebody
+				 *   else produces, since a burst that begins on a tiny packet starts
+				 *   measuring from an instant that says nothing.
+				 */
+				size_t minPacketSize{ 200 };
+				/**
+				 * Whether a burst may start without waiting for a packet of that size.
+				 */
+				bool allowStartProbingImmediately{ false };
+			};
+
+			/**
+			 * The burst being emitted, together with how much of it has gone out.
+			 */
+			struct CurrentCluster
+			{
+				/**
+				 * What travels with each of its packets.
+				 */
+				Types::ProbeCluster probeCluster;
+				/**
+				 * Bytes of the burst that have already gone out (bytes).
+				 *
+				 * @remarks
+				 * - It doesn't belong in `Types::ProbeCluster` because that one travels
+				 *   attached to every packet until its feedback comes back, and by then
+				 *   this count means nothing.
+				 */
+				int64_t sentBytes{ 0 };
+			};
+
+		public:
+			BitrateProber();
+
+			explicit BitrateProber(BitrateProberOptions options);
+
+			~BitrateProber() = default;
+
+			/**
+			 * Whether a burst is being emitted right now.
+			 */
+			bool IsProbing() const
+			{
+				return this->state == State::ACTIVE;
+			}
+
+			/**
+			 * Take a burst that has been asked for.
+			 */
+			void CreateProbeCluster(const Types::ProbeClusterConfig& clusterConfig);
+
+			/**
+			 * Instant at which the next packet of the current burst may go out, or no
+			 * value if there is nothing to send.
+			 *
+			 * @remarks
+			 * - The instant given is `nowUs` itself when the packet may go out right
+			 *   away, so that the answer is always an instant that can be operated
+			 *   with rather than a value meaning "as soon as possible".
+			 */
+			[[nodiscard]] std::optional<int64_t> GetNextProbeTimeUs(int64_t nowUs) const;
+
+			/**
+			 * The burst being emitted, or no value if there is none.
+			 *
+			 * @remarks
+			 * - It gives up on the burst, and may leave none being emitted, when the
+			 *   instant it was due at is too far behind.
+			 */
+			[[nodiscard]] std::optional<CurrentCluster> GetCurrentCluster(int64_t nowUs);
+
+			/**
+			 * Bytes the next packet of the current burst should carry, or zero if there
+			 * is no burst.
+			 *
+			 * @remarks
+			 * - Packets are allowed to be grouped into a single shot as long as they
+			 *   add up to this, which is what keeps a burst from needing a packet every
+			 *   couple of milliseconds.
+			 */
+			size_t GetRecommendedMinProbeSize() const;
+
+			/**
+			 * Report that the given bytes of the current burst have gone out.
+			 */
+			void ProbeSent(int64_t nowUs, size_t size);
+
+			/**
+			 * Feed a packet that somebody else is sending, which is what may start a
+			 * burst that is waiting for one.
+			 *
+			 * @remarks
+			 * - Only the tests call it today, because the bursts are made of packets
+			 *   fabricated for them and there is no traffic of somebody else's to wait
+			 *   for. This is the way in for the day a burst rides on real traffic
+			 *   instead, and with it `minPacketSize` starts meaning something.
+			 */
+			void OnIncomingPacket(size_t packetSize);
+
+		private:
+			/**
+			 * Start emitting if there is a burst waiting and the given packet is enough
+			 * to begin on.
+			 */
+			void MaybeSetActiveState(size_t packetSize);
+
+			bool IsReadyToSetActiveState(size_t packetSize) const;
+
+			/**
+			 * Instant at which the next packet of the given burst is due, computed from
+			 * the start of the burst so that it stays close to its bitrate.
+			 */
+			int64_t CalculateNextProbeTimeUs(const Cluster& cluster) const;
+
+		private:
+			// Passed by argument.
+			BitrateProberOptions options;
+			// Others.
+			State state{ State::INACTIVE };
+			// The bursts asked for, the first one being the one being emitted.
+			std::queue<Cluster> clusters;
+			// Instant at which the next packet is due, or no value while it is due
+			// right away.
+			std::optional<int64_t> nextProbeTimeUs;
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/{Utils.hpp → BitrateUtils.hpp}

@@ -1,5 +1,5 @@
-#ifndef MS_RTC_BWE_UTILS_HPP
-#define MS_RTC_BWE_UTILS_HPP
+#ifndef MS_RTC_BWE_BITRATE_UTILS_HPP
+#define MS_RTC_BWE_BITRATE_UTILS_HPP
 
 #include "common.hpp"
 
@@ -7,7 +7,7 @@ namespace RTC
 {
 	namespace BWE
 	{
-		class Utils
+		class BitrateUtils
 		{
 		public:
 			/**

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

@@ -22,6 +22,32 @@ namespace RTC
 			 */
 			constexpr int64_t TimeUsInfinite{ std::numeric_limits<int64_t>::max() };
 
+			/**
+			 * The two bits of the IP header with which the network tells that it is
+			 * congested instead of dropping the packet.
+			 *
+			 * @see https://www.rfc-editor.org/rfc/rfc9331.html
+			 */
+			enum class EcnMarking : uint8_t
+			{
+				/**
+				 * Not ECN capable transport.
+				 */
+				NOT_ECT = 0b00,
+				/**
+				 * ECN capable transport, which is the one L4S uses.
+				 */
+				ECT1 = 0b01,
+				/**
+				 * ECN capable transport, not used by L4S.
+				 */
+				ECT0 = 0b10,
+				/**
+				 * Congestion experienced, which is what the network sets on the way.
+				 */
+				CE = 0b11
+			};
+
 			/**
 			 * How the network is behaving according to the delay based detector.
 			 */
@@ -60,7 +86,7 @@ namespace RTC
 						return "OVERUSING";
 					}
 
-						NO_DEFAULT_GCC();
+						NO_DEFAULT();
 				}
 			}
 
@@ -95,6 +121,67 @@ namespace RTC
 				std::optional<int64_t> estimatedThroughput;
 			};
 
+			/**
+			 * The burst of packets a probe is sent as, and what makes its result
+			 * trustworthy.
+			 *
+			 * A probe is only worth believing once enough of what was sent has come
+			 * back, so the burst carries how many packets and how many bytes it was
+			 * meant to be. Whoever measures it compares those against what actually
+			 * arrived, and discards the cluster if too little of it did.
+			 */
+			struct ProbeCluster
+			{
+				/**
+				 * Identifies the burst, so that the packets of one probe are not mixed
+				 * with those of another.
+				 */
+				int64_t id{ 0 };
+				/**
+				 * Packets the burst was meant to be made of.
+				 */
+				int64_t minProbes{ 0 };
+				/**
+				 * Bytes the burst was meant to carry.
+				 */
+				int64_t minBytes{ 0 };
+			};
+
+			/**
+			 * A burst that has been asked for but not sent yet.
+			 *
+			 * It's what whoever decides to probe hands over to whoever emits the
+			 * packets: at what bitrate, for how long and in how many packets. What
+			 * travels with each of those packets afterwards is a `ProbeCluster`.
+			 */
+			struct ProbeClusterConfig
+			{
+				/**
+				 * Identifies the burst, and is what each of its packets carries.
+				 */
+				int64_t id{ 0 };
+				/**
+				 * Instant at which the burst was asked for.
+				 */
+				int64_t atUs{ 0 };
+				/**
+				 * Bitrate the burst is meant to be sent at (bps).
+				 */
+				int64_t targetBitrate{ 0 };
+				/**
+				 * How long the burst is meant to last.
+				 */
+				int64_t targetDurationUs{ 0 };
+				/**
+				 * Time between two consecutive bursts of packets within the probe.
+				 */
+				int64_t minProbeDeltaUs{ 2 * 1000 };
+				/**
+				 * Packets the burst is meant to be made of.
+				 */
+				int64_t targetProbeCount{ 0 };
+			};
+
 			/**
 			 * A packet that was sent and is being tracked until its feedback arrives.
 			 */
@@ -133,7 +220,12 @@ namespace RTC
 				/**
 				 * Whether it's an audio packet. False for video, padding and RTX.
 				 */
-				bool audio{ false };
+				bool isAudio{ false };
+				/**
+				 * The probe cluster the packet belongs to, or no value if it isn't a
+				 * probe.
+				 */
+				std::optional<ProbeCluster> probeCluster;
 			};
 
 			/**
@@ -154,6 +246,16 @@ namespace RTC
 					bool operator()(const PacketResult& lhs, const PacketResult& rhs) const;
 				};
 
+				/**
+				 * What identifies the packet on the wire.
+				 */
+				struct RtpPacketInfo
+				{
+					uint32_t ssrc{ 0 };
+					uint16_t rtpSequenceNumber{ 0 };
+					bool isRetransmission{ false };
+				};
+
 				/**
 				 * Whether the packet reached the receiver at all.
 				 */
@@ -168,6 +270,72 @@ namespace RTC
 				 * value if it was reported as lost.
 				 */
 				std::optional<int64_t> receiveTimeUs;
+				/**
+				 * What identifies the packet on the wire, or no value when the feedback
+				 * doesn't report on an RTP packet.
+				 */
+				std::optional<RtpPacketInfo> rtpPacketInfo;
+				/**
+				 * How long the receiver held the packet before sending the feedback
+				 * that reports it, which is what allows a round trip time per packet.
+				 *
+				 * @remark
+				 * - Only a feedback that carries it per packet has it, which is the one
+				 *   of RFC 8888 and not the transport-cc one.
+				 *
+				 * @see https://datatracker.ietf.org/doc/html/rfc8888
+				 */
+				std::optional<int64_t> arrivalTimeOffsetUs;
+				/**
+				 * The marking the packet carried when it arrived, which is how the
+				 * network reports being congested without dropping it.
+				 *
+				 * @remark
+				 * - Only a feedback that reports it has it, which is the one of RFC
+				 *   8888 and not the transport-cc one.
+				 *
+				 * @see https://datatracker.ietf.org/doc/html/rfc8888
+				 */
+				EcnMarking ecn{ EcnMarking::NOT_ECT };
+				/**
+				 * Whether the arrival time reported for this packet cannot be told from
+				 * that of another one, so it says nothing about the delay.
+				 *
+				 * @remark
+				 * - Nothing in this estimator reads it. It is only of use to SCReAM,
+				 *   another way of estimating the bandwidth.
+				 *
+				 * @link https://datatracker.ietf.org/doc/draft-johansson-ccwg-rfc8298bis-screamv2
+				 */
+				bool ambiguousReceiveTime{ false };
+				/**
+				 * Whether the packet was sent marked as ECT(1), which asks the network
+				 * to report congestion instead of dropping the packet.
+				 *
+				 * @see https://www.rfc-editor.org/rfc/rfc9331.html
+				 */
+				bool sentWithEct1{ false };
+				/**
+				 * Whether this is the first feedback to report the packet as lost.
+				 *
+				 * @remark
+				 * - Only a feedback that reports on a whole range of packets can tell,
+				 *   which is the one of RFC 8888 and not the transport-cc one.
+				 *
+				 * @see https://datatracker.ietf.org/doc/html/rfc8888
+				 */
+				bool reportedLostForTheFirstTime{ false };
+				/**
+				 * Whether this feedback reports as received a packet that an earlier
+				 * one had reported as lost.
+				 *
+				 * @remark
+				 * - Only a feedback that reports on a whole range of packets can tell,
+				 *   which is the one of RFC 8888 and not the transport-cc one.
+				 *
+				 * @see https://datatracker.ietf.org/doc/html/rfc8888
+				 */
+				bool reportedRecoveredForTheFirstTime{ false };
 			};
 
 			/**

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

@@ -43,17 +43,6 @@ namespace RTC
 			std::optional<Types::TransportPacketsFeedback> ProcessTransportFeedback(
 			  const RTCP::FeedbackRtpTransportPacket* feedback, int64_t receivedAtUs);
 
-		private:
-			/**
-			 * Recover the sequence number the history gave to a packet out of the
-			 * lowest bits of it that the wire carries.
-			 *
-			 * @param previousSequenceNumber - Sequence number the previous packet the
-			 *   feedback reported on resolved into, which the returned one is the
-			 *   closest to.
-			 */
-			static int64_t UnwrapSequenceNumber(uint16_t wideSequenceNumber, int64_t previousSequenceNumber);
-
 		private:
 			SendPacketHistory* const sendPacketHistory;
 			// Our own time the arrival times of the current feedback are given
@@ -62,9 +51,6 @@ namespace RTC
 			// Base time of the latest feedback processed, in the remote clock, or no
 			// value if no feedback was ever processed.
 			std::optional<int64_t> lastFeedbackBaseTimeUs;
-			// Sequence number the latest packet reported on resolved into, or no
-			// value if no feedback was ever processed.
-			std::optional<int64_t> lastUnwrappedSequenceNumber;
 		};
 	} // namespace BWE
 } // namespace RTC

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

@@ -0,0 +1,117 @@
+#ifndef MS_RTC_BWE_INTER_ARRIVAL_HPP
+#define MS_RTC_BWE_INTER_ARRIVAL_HPP
+
+#include "common.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Groups received packets into send bursts and computes the deltas between
+		 * two consecutive bursts.
+		 *
+		 * It does the same job as `InterArrivalDelta` but on the receiving side,
+		 * where the instant a packet was sent is not known: all there is is a
+		 * timestamp of the sender's own, carried by the packet, which wraps around
+		 * and whose tick is whatever the sender decided. So groups are formed by
+		 * that timestamp instead of by a real instant, and telling which of two
+		 * timestamps is the later one has to account for the wrap.
+		 *
+		 * The computed deltas are the input of the overuse estimator: if the arrival
+		 * delta grows faster than the send delta then queues are building up
+		 * somewhere in the network.
+		 */
+		class InterArrival
+		{
+		public:
+			/**
+			 * Deltas between two consecutive groups of packets sent in a burst.
+			 */
+			struct Deltas
+			{
+				/**
+				 * Ticks elapsed between the send timestamps of both groups.
+				 */
+				uint32_t timestampDelta;
+
+				/**
+				 * Time elapsed between the arrival times of both groups (us).
+				 */
+				int64_t arrivalDeltaUs;
+
+				/**
+				 * Difference of size between both groups (bytes).
+				 */
+				int64_t sizeDelta;
+			};
+
+		private:
+			struct TimestampGroup
+			{
+				bool IsFirstPacket() const
+				{
+					return !this->completeTimeUs.has_value();
+				}
+
+				size_t size{ 0 };
+				uint32_t firstTimestamp{ 0 };
+				uint32_t timestamp{ 0 };
+				int64_t firstArrivalTimeUs{ 0 };
+				std::optional<int64_t> completeTimeUs;
+				int64_t lastSystemTimeUs{ 0 };
+			};
+
+		public:
+			/**
+			 * @param timestampGroupLengthTicks - Every packet whose timestamp is
+			 *   within this many ticks of the first packet of a group belongs to that
+			 *   group.
+			 * @param timestampToUsCoeff - Microseconds a single tick of those
+			 *   timestamps is worth.
+			 */
+			InterArrival(uint32_t timestampGroupLengthTicks, double timestampToUsCoeff);
+
+			/**
+			 * Feed a received packet.
+			 *
+			 * @param timestamp - Timestamp the packet carries, in the sender's own
+			 *   units, which wraps around.
+			 * @param arrivalTimeUs - Time at which the packet arrived.
+			 * @param systemTimeUs - Time, in our own clock reference, at which the
+			 *   packet is being fed. It's used to detect that the timestamps have
+			 *   jumped by comparing how much they advanced against how much our clock
+			 *   did.
+			 * @param packetSize - Size of the packet (bytes).
+			 *
+			 * @returns The deltas between the two latest complete groups, or no value
+			 *   if they cannot be computed yet.
+			 */
+			std::optional<Deltas> ComputeDeltas(
+			  uint32_t timestamp, int64_t arrivalTimeUs, int64_t systemTimeUs, size_t packetSize);
+
+		private:
+			/**
+			 * Whether the given timestamp is not older than the first one of the
+			 * current group, so that a packet that got reordered on its way here
+			 * doesn't close a group it doesn't belong to.
+			 */
+			bool IsPacketInOrder(uint32_t timestamp) const;
+
+			bool IsNewTimestampGroup(int64_t arrivalTimeUs, uint32_t timestamp) const;
+
+			bool BelongsToBurst(int64_t arrivalTimeUs, uint32_t timestamp) const;
+
+			void Reset();
+
+		private:
+			const uint32_t timestampGroupLengthTicks;
+			const double timestampToUsCoeff;
+			TimestampGroup currentGroup;
+			TimestampGroup prevGroup;
+			size_t numConsecutiveReorderedGroups{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif