AI: Add more utests for kernel module. v7.0.81 (ossrs#4478)

winlinvip · ossrs-ai · web-flow · commit 7c1e87ef5c61 · 2025-09-06T12:39:46.000-04:00
This PR significantly enhances the kernel module by adding comprehensive
unit test coverage and improving interface design for core buffer and
load balancer components.

- **ISrsDecoder**: New interface for decoding/deserialization operations
- **ISrsLbRoundRobin**: Extracted interface from concrete
SrsLbRoundRobin class for better abstraction
- **Enhanced Documentation**: Added comprehensive inline documentation
for ISrsEncoder, ISrsCodec, SrsBuffer, and SrsBitBuffer classes

---------

Co-authored-by: OSSRS-AI &lt;winlinam@gmail.com&gt;
diff --git a/.augment-guidelines b/.augment-guidelines
@@ -162,6 +162,60 @@ code_patterns:
     - pattern: "srs_freepa"
       description: "Custom macro for freeing arrays - use only when smart pointers are not suitable"
 
+  naming_conventions:
+    - pattern: "field_naming"
+      description: "MANDATORY - All class and struct fields must end with underscore (_)"
+      usage: |
+        WRONG: Fields without underscore
+        class SrsBuffer {
+        private:
+            char *p;
+            int size;
+        public:
+            bool enabled;
+        };
+
+        CORRECT: Fields with underscore
+        class SrsBuffer {
+        private:
+            char *p_;
+            int size_;
+        public:
+            bool enabled_;
+        };
+      scope: "Applies to ALL fields (private, protected, public) in both classes and structs"
+      exceptions: "Only applies to SRS-defined classes/structs - do NOT change 3rd party code like llhttp"
+      rationale: "Consistent naming convention across SRS codebase for better code readability and maintenance"
+
+  commenting_style:
+    - pattern: "C++ style comments"
+      description: "MANDATORY - Use C++ style comments (//) instead of C style comments (/* */)"
+      usage: |
+        WRONG: C style comments
+        /* This is a comment */
+        /**
+         * Multi-line comment
+         * with multiple lines
+         */
+
+        CORRECT: C++ style comments
+        // This is a comment
+        // Multi-line comment
+        // with multiple lines
+      rationale: "Consistent with SRS codebase style and better for single-line documentation"
+
+    - pattern: "No thread-safety comments"
+      description: "Do NOT describe thread-safety in comments since SRS is a single-threaded application"
+      usage: |
+        WRONG: Mentioning thread-safety
+        // This implementation is thread-safe for single-threaded usage but may
+        // require external synchronization in multi-threaded environments.
+
+        CORRECT: Focus on functionality without thread-safety mentions
+        // This implementation maintains state between calls for consistent
+        // round-robin behavior across multiple selections.
+      rationale: "SRS uses single-threaded coroutine-based architecture, so thread-safety discussions are irrelevant and confusing"
+
   error_handling:
     - pattern: "srs_error_t"
       description: "Custom error handling system - MANDATORY for all functions that return srs_error_t"
diff --git a/trunk/doc/CHANGELOG.md b/trunk/doc/CHANGELOG.md
@@ -7,6 +7,7 @@ The changelog for SRS.
 <a name="v7-changes"></a>
 
 ## SRS 7.0 Changelog
+* v7.0, 2025-09-06, Merge [#4478](https://github.com/ossrs/srs/pull/4478): AI: Add more utests for kernel module. v7.0.81 (#4478)
 * v7.0, 2025-09-06, Merge [#4475](https://github.com/ossrs/srs/pull/4475): AI: Support anonymous coroutine with code block. v7.0.80 (#4475)
 * v7.0, 2025-09-05, Merge [#4474](https://github.com/ossrs/srs/pull/4474): WebRTC: Fix race condition in RTC nack timer callbacks. v7.0.79 (#4474)
 * v7.0, 2025-09-04, Merge [#4467](https://github.com/ossrs/srs/pull/4467): WebRTC: Fix NACK recovered packets not being added to receive queue. v7.0.78 (#4467)
diff --git a/trunk/src/app/srs_app_edge.cpp b/trunk/src/app/srs_app_edge.cpp
@@ -62,7 +62,7 @@ SrsEdgeRtmpUpstream::~SrsEdgeRtmpUpstream()
     close();
 }
 
-srs_error_t SrsEdgeRtmpUpstream::connect(ISrsRequest *r, SrsLbRoundRobin *lb)
+srs_error_t SrsEdgeRtmpUpstream::connect(ISrsRequest *r, ISrsLbRoundRobin *lb)
 {
     srs_error_t err = srs_success;
 
@@ -173,7 +173,7 @@ SrsEdgeFlvUpstream::~SrsEdgeFlvUpstream()
     close();
 }
 
-srs_error_t SrsEdgeFlvUpstream::connect(ISrsRequest *r, SrsLbRoundRobin *lb)
+srs_error_t SrsEdgeFlvUpstream::connect(ISrsRequest *r, ISrsLbRoundRobin *lb)
 {
     // Because we might modify the r, which cause retry fail, so we must copy it.
     ISrsRequest *cp = r->copy();
@@ -185,7 +185,7 @@ srs_error_t SrsEdgeFlvUpstream::connect(ISrsRequest *r, SrsLbRoundRobin *lb)
     return do_connect(cp, lb, 0);
 }
 
-srs_error_t SrsEdgeFlvUpstream::do_connect(ISrsRequest *r, SrsLbRoundRobin *lb, int redirect_depth)
+srs_error_t SrsEdgeFlvUpstream::do_connect(ISrsRequest *r, ISrsLbRoundRobin *lb, int redirect_depth)
 {
     srs_error_t err = srs_success;
 
@@ -458,11 +458,6 @@ void SrsEdgeIngester::stop()
     }
 }
 
-string SrsEdgeIngester::get_curr_origin()
-{
-    return lb->selected();
-}
-
 #ifdef SRS_APM
 ISrsApmSpan *SrsEdgeIngester::span()
 {
@@ -999,11 +994,6 @@ void SrsPlayEdge::on_all_client_stop()
     }
 }
 
-string SrsPlayEdge::get_curr_origin()
-{
-    return ingester->get_curr_origin();
-}
-
 srs_error_t SrsPlayEdge::on_ingest_play()
 {
     srs_error_t err = srs_success;
diff --git a/trunk/src/app/srs_app_edge.hpp b/trunk/src/app/srs_app_edge.hpp
@@ -25,7 +25,7 @@ class SrsRtmpCommonMessage;
 class SrsMessageQueue;
 class ISrsProtocolReadWriter;
 class SrsKbps;
-class SrsLbRoundRobin;
+class ISrsLbRoundRobin;
 class SrsTcpClient;
 class SrsSimpleRtmpClient;
 class SrsRtmpCommand;
@@ -64,7 +64,7 @@ class SrsEdgeUpstream
     virtual ~SrsEdgeUpstream();
 
 public:
-    virtual srs_error_t connect(ISrsRequest *r, SrsLbRoundRobin *lb) = 0;
+    virtual srs_error_t connect(ISrsRequest *r, ISrsLbRoundRobin *lb) = 0;
     virtual srs_error_t recv_message(SrsRtmpCommonMessage **pmsg) = 0;
     virtual srs_error_t decode_message(SrsRtmpCommonMessage *msg, SrsRtmpCommand **ppacket) = 0;
     virtual void close() = 0;
@@ -94,7 +94,7 @@ class SrsEdgeRtmpUpstream : public SrsEdgeUpstream
     virtual ~SrsEdgeRtmpUpstream();
 
 public:
-    virtual srs_error_t connect(ISrsRequest *r, SrsLbRoundRobin *lb);
+    virtual srs_error_t connect(ISrsRequest *r, ISrsLbRoundRobin *lb);
     virtual srs_error_t recv_message(SrsRtmpCommonMessage **pmsg);
     virtual srs_error_t decode_message(SrsRtmpCommonMessage *msg, SrsRtmpCommand **ppacket);
     virtual void close();
@@ -128,10 +128,10 @@ class SrsEdgeFlvUpstream : public SrsEdgeUpstream
     virtual ~SrsEdgeFlvUpstream();
 
 public:
-    virtual srs_error_t connect(ISrsRequest *r, SrsLbRoundRobin *lb);
+    virtual srs_error_t connect(ISrsRequest *r, ISrsLbRoundRobin *lb);
 
 private:
-    virtual srs_error_t do_connect(ISrsRequest *r, SrsLbRoundRobin *lb, int redirect_depth);
+    virtual srs_error_t do_connect(ISrsRequest *r, ISrsLbRoundRobin *lb, int redirect_depth);
 
 public:
     virtual srs_error_t recv_message(SrsRtmpCommonMessage **pmsg);
@@ -155,7 +155,7 @@ class SrsEdgeIngester : public ISrsCoroutineHandler
     SrsPlayEdge *edge;
     ISrsRequest *req;
     SrsCoroutine *trd;
-    SrsLbRoundRobin *lb;
+    ISrsLbRoundRobin *lb;
     SrsEdgeUpstream *upstream;
 
 public:
@@ -166,7 +166,6 @@ class SrsEdgeIngester : public ISrsCoroutineHandler
     virtual srs_error_t initialize(SrsSharedPtr<SrsLiveSource> s, SrsPlayEdge *e, ISrsRequest *r);
     virtual srs_error_t start();
     virtual void stop();
-    virtual std::string get_curr_origin();
 
     // Interface ISrsReusableThread2Handler
 public:
@@ -192,7 +191,7 @@ class SrsEdgeForwarder : public ISrsCoroutineHandler
     ISrsRequest *req;
     SrsCoroutine *trd;
     SrsSimpleRtmpClient *sdk;
-    SrsLbRoundRobin *lb;
+    ISrsLbRoundRobin *lb;
     // we must ensure one thread one fd principle,
     // that is, a fd must be write/read by the one thread.
     // The publish service thread will proxy(msg), and the edge forward thread
@@ -243,7 +242,6 @@ class SrsPlayEdge
     virtual srs_error_t on_client_play();
     // When all client stopped play, disconnect to origin.
     virtual void on_all_client_stop();
-    virtual std::string get_curr_origin();
 
 public:
     // When ingester start to play stream.
diff --git a/trunk/src/app/srs_app_source.cpp b/trunk/src/app/srs_app_source.cpp
@@ -2521,8 +2521,3 @@ void SrsLiveSource::on_edge_proxy_unpublish()
 {
     publish_edge->on_proxy_unpublish();
 }
-
-string SrsLiveSource::get_curr_origin()
-{
-    return play_edge->get_curr_origin();
-}
diff --git a/trunk/src/app/srs_app_source.hpp b/trunk/src/app/srs_app_source.hpp
@@ -638,9 +638,6 @@ class SrsLiveSource : public ISrsReloadHandler
     virtual srs_error_t on_edge_proxy_publish(SrsRtmpCommonMessage *msg);
     // For edge, proxy stop publish
     virtual void on_edge_proxy_unpublish();
-
-public:
-    virtual std::string get_curr_origin();
 };
 
 #endif
diff --git a/trunk/src/core/srs_core_version7.hpp b/trunk/src/core/srs_core_version7.hpp
@@ -9,6 +9,6 @@
 
 #define VERSION_MAJOR 7
 #define VERSION_MINOR 0
-#define VERSION_REVISION 80
+#define VERSION_REVISION 81
 
 #endif
diff --git a/trunk/src/kernel/srs_kernel_balance.cpp b/trunk/src/kernel/srs_kernel_balance.cpp
@@ -10,6 +10,14 @@
 
 using namespace std;
 
+ISrsLbRoundRobin::ISrsLbRoundRobin()
+{
+}
+
+ISrsLbRoundRobin::~ISrsLbRoundRobin()
+{
+}
+
 SrsLbRoundRobin::SrsLbRoundRobin()
 {
     index = -1;
diff --git a/trunk/src/kernel/srs_kernel_balance.hpp b/trunk/src/kernel/srs_kernel_balance.hpp
@@ -12,27 +12,59 @@
 #include <string>
 #include <vector>
 
-/**
- * the round-robin load balance algorithm,
- * used for edge pull and other multiple server feature.
- */
-class SrsLbRoundRobin
+// Interface for round-robin load balance algorithm.
+//
+// This interface defines the contract for load balancing algorithms that distribute
+// requests across multiple servers in a round-robin fashion. It's primarily used
+// for edge pull scenarios and other features that require distributing load across
+// multiple backend servers.
+//
+// The round-robin algorithm ensures fair distribution by cycling through available
+// servers in sequence, giving each server an equal opportunity to handle requests.
+//
+class ISrsLbRoundRobin
+{
+public:
+    ISrsLbRoundRobin();
+    virtual ~ISrsLbRoundRobin();
+
+public:
+    // Select one server from the provided list of servers using the load balancing algorithm.
+    //
+    // @param servers A vector of server addresses/URLs to choose from. Must not be empty.
+    // @return The selected server address/URL as a string.
+    //
+    // @remark The implementation should handle the load balancing logic and maintain
+    //         any necessary state to ensure proper distribution across servers.
+    // @remark Callers must ensure the servers vector is not empty before calling this method.
+    //
+    virtual std::string select(const std::vector<std::string> &servers) = 0;
+};
+
+// Implementation of round-robin load balance algorithm.
+//
+// This class provides a concrete implementation of the ISrsLbRoundRobin interface
+// that distributes requests across multiple servers using a simple round-robin
+// algorithm. It maintains internal state to track the current position in the
+// server list and ensures fair distribution by cycling through servers sequentially.
+//
+class SrsLbRoundRobin : public ISrsLbRoundRobin
 {
 private:
-    // current selected index.
     int index;
-    // total scheduled count.
     uint32_t count;
-    // current selected server.
     std::string elem;
 
 public:
     SrsLbRoundRobin();
     virtual ~SrsLbRoundRobin();
 
 public:
+    // Get the current server index.
     virtual uint32_t current();
+    // Get the currently selected server.
     virtual std::string selected();
+    // Select the next server using round-robin algorithm.
     virtual std::string select(const std::vector<std::string> &servers);
 };
 
diff --git a/trunk/src/kernel/srs_kernel_buffer.cpp b/trunk/src/kernel/srs_kernel_buffer.cpp
@@ -20,6 +20,14 @@ ISrsEncoder::~ISrsEncoder()
 {
 }
 
+ISrsDecoder::ISrsDecoder()
+{
+}
+
+ISrsDecoder::~ISrsDecoder()
+{
+}
+
 ISrsCodec::ISrsCodec()
 {
 }
@@ -468,14 +476,23 @@ srs_error_t SrsBitBuffer::read_bits_ue(uint32_t &v)
         return srs_error_new(ERROR_HEVC_NALU_UEV, "empty stream");
     }
 
+    // Unsigned Exp-Golomb decoding algorithm from ITU-T H.265 specification
     // ue(v) in 9.2 Parsing process for Exp-Golomb codes
     // ITU-T-H.265-2021.pdf, page 221.
-    // Syntax elements coded as ue(v), me(v), or se(v) are Exp-Golomb-coded.
-    //      leadingZeroBits = -1;
-    //      for( b = 0; !b; leadingZeroBits++ )
-    //          b = read_bits( 1 )
-    // The variable codeNum is then assigned as follows:
-    //      codeNum = (2<<leadingZeroBits) - 1 + read_bits( leadingZeroBits )
+    //
+    // Algorithm:
+    // 1. Count leading zero bits until first '1' bit
+    // 2. Read the '1' bit (prefix)
+    // 3. Read leadingZeroBits more bits (suffix)
+    // 4. Calculate: codeNum = (2^leadingZeroBits) - 1 + suffix_value
+    //
+    // Examples:
+    //   "1"       -> leadingZeroBits=0, suffix=none  -> value=0
+    //   "010"     -> leadingZeroBits=1, suffix=0     -> value=1
+    //   "011"     -> leadingZeroBits=1, suffix=1     -> value=2
+    //   "00100"   -> leadingZeroBits=2, suffix=00    -> value=3
+
+    // Step 1: Count leading zero bits
     int leadingZeroBits = -1;
     for (int8_t b = 0; !b && !empty(); leadingZeroBits++) {
         b = read_bit();
@@ -485,7 +502,10 @@ srs_error_t SrsBitBuffer::read_bits_ue(uint32_t &v)
         return srs_error_new(ERROR_HEVC_NALU_UEV, "%dbits overflow 31bits", leadingZeroBits);
     }
 
+    // Step 2: Calculate base value: (2^leadingZeroBits) - 1
     v = (1 << leadingZeroBits) - 1;
+
+    // Step 3: Read suffix bits and add to base value
     for (int i = 0; i < (int)leadingZeroBits; i++) {
         if (empty()) {
             return srs_error_new(ERROR_HEVC_NALU_UEV, "no bytes for leadingZeroBits=%d", leadingZeroBits);
@@ -506,15 +526,30 @@ srs_error_t SrsBitBuffer::read_bits_se(int32_t &v)
         return srs_error_new(ERROR_HEVC_NALU_SEV, "empty stream");
     }
 
-    // ue(v) in 9.2.1 General Parsing process for Exp-Golomb codes
-    // ITU-T-H.265-2021.pdf, page 221.
+    // Signed Exp-Golomb decoding algorithm from ITU-T H.265 specification
+    // se(v) in 9.2.2 Mapping process for signed Exp-Golomb codes
+    // ITU-T-H.265-2021.pdf, page 222.
+    //
+    // Algorithm:
+    // 1. First decode as unsigned Exp-Golomb to get codeNum
+    // 2. Map to signed value using alternating positive/negative pattern:
+    //    - If codeNum is odd:  se_value = (codeNum + 1) / 2
+    //    - If codeNum is even: se_value = -(codeNum / 2)
+    //
+    // Mapping table:
+    //   codeNum: 0  1  2  3  4  5  6  7  8  ...
+    //   se(v):   0  1 -1  2 -2  3 -3  4 -4  ...
+    //
+    // This encoding efficiently represents signed integers with smaller
+    // absolute values using fewer bits.
+
+    // Step 1: Decode unsigned Exp-Golomb value
     uint32_t val = 0;
     if ((err = read_bits_ue(val)) != srs_success) {
         return srs_error_wrap(err, "read uev");
     }
 
-    // se(v) in 9.2.2 Mapping process for signed Exp-Golomb codes
-    // ITU-T-H.265-2021.pdf, page 222.
+    // Step 2: Map unsigned code to signed value
     if (val & 0x01) {
         v = (val + 1) / 2;
     } else {
diff --git a/trunk/src/kernel/srs_kernel_buffer.hpp b/trunk/src/kernel/srs_kernel_buffer.hpp
diff --git a/trunk/src/utest/srs_utest_core.cpp b/trunk/src/utest/srs_utest_core.cpp
diff --git a/trunk/src/utest/srs_utest_kernel.cpp b/trunk/src/utest/srs_utest_kernel.cpp
diff --git a/trunk/src/utest/srs_utest_kernel2.cpp b/trunk/src/utest/srs_utest_kernel2.cpp

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ SrsEdgeRtmpUpstream::~SrsEdgeRtmpUpstream()`
`62`	`62`	`close();`
`63`	`63`	`}`
`64`	`64`
`65`		`-srs_error_t SrsEdgeRtmpUpstream::connect(ISrsRequest r, SrsLbRoundRobin lb)`
	`65`	`+srs_error_t SrsEdgeRtmpUpstream::connect(ISrsRequest r, ISrsLbRoundRobin lb)`
`66`	`66`	`{`
`67`	`67`	`srs_error_t err = srs_success;`
`68`	`68`
`@@ -173,7 +173,7 @@ SrsEdgeFlvUpstream::~SrsEdgeFlvUpstream()`
`173`	`173`	`close();`
`174`	`174`	`}`
`175`	`175`
`176`		`-srs_error_t SrsEdgeFlvUpstream::connect(ISrsRequest r, SrsLbRoundRobin lb)`
	`176`	`+srs_error_t SrsEdgeFlvUpstream::connect(ISrsRequest r, ISrsLbRoundRobin lb)`
`177`	`177`	`{`
`178`	`178`	`// Because we might modify the r, which cause retry fail, so we must copy it.`
`179`	`179`	`ISrsRequest *cp = r->copy();`
`@@ -185,7 +185,7 @@ srs_error_t SrsEdgeFlvUpstream::connect(ISrsRequest r, SrsLbRoundRobin lb)`
`185`	`185`	`return do_connect(cp, lb, 0);`
`186`	`186`	`}`
`187`	`187`
`188`		`-srs_error_t SrsEdgeFlvUpstream::do_connect(ISrsRequest r, SrsLbRoundRobin lb, int redirect_depth)`
	`188`	`+srs_error_t SrsEdgeFlvUpstream::do_connect(ISrsRequest r, ISrsLbRoundRobin lb, int redirect_depth)`
`189`	`189`	`{`
`190`	`190`	`srs_error_t err = srs_success;`
`191`	`191`
`@@ -458,11 +458,6 @@ void SrsEdgeIngester::stop()`
`458`	`458`	`}`
`459`	`459`	`}`
`460`	`460`
`461`		`-string SrsEdgeIngester::get_curr_origin()`
`462`		`-{`
`463`		`- return lb->selected();`
`464`		`-}`
`465`		`-`
`466`	`461`	`#ifdef SRS_APM`
`467`	`462`	`ISrsApmSpan *SrsEdgeIngester::span()`
`468`	`463`	`{`
`@@ -999,11 +994,6 @@ void SrsPlayEdge::on_all_client_stop()`
`999`	`994`	`}`
`1000`	`995`	`}`
`1001`	`996`
`1002`		`-string SrsPlayEdge::get_curr_origin()`
`1003`		`-{`
`1004`		`- return ingester->get_curr_origin();`
`1005`		`-}`
`1006`		`-`
`1007`	`997`	`srs_error_t SrsPlayEdge::on_ingest_play()`
`1008`	`998`	`{`
`1009`	`999`	`srs_error_t err = srs_success;`
Original file line number	Diff line number	Diff line change
`@@ -2521,8 +2521,3 @@ void SrsLiveSource::on_edge_proxy_unpublish()`
`2521`	`2521`	`{`
`2522`	`2522`	`publish_edge->on_proxy_unpublish();`
`2523`	`2523`	`}`
`2524`		`-`
`2525`		`-string SrsLiveSource::get_curr_origin()`
`2526`		`-{`
`2527`		`- return play_edge->get_curr_origin();`
`2528`		`-}`