docs: correct data channel buffered amount semantics

docs/guide/data/data-channels.md

@@ -80,10 +80,10 @@ import dev.onvoid.webrtc.RTCDataChannelState;
 
 dataChannel.registerObserver(new RTCDataChannelObserver() {
     @Override
-    public void onBufferedAmountChange(long previousAmount) {
-        // Called when the buffered amount changes
+    public void onBufferedAmountChange(long sentDataSize) {
+        // The callback reports a decrease, not the previous queue size.
         long currentAmount = dataChannel.getBufferedAmount();
-        System.out.println("Buffered amount changed from " + previousAmount + 
+        System.out.println("Buffered amount decreased by " + sentDataSize +
                            " to " + currentAmount + " bytes");
     }
 
@@ -301,4 +301,4 @@ Data channels complement WebRTC's audio and video capabilities, making it possib
 
 For optimal performance, remember to follow the best practices outlined in this guide, particularly regarding buffer management and proper cleanup of resources.
 
-For more information on other WebRTC features, refer to the additional guides in the documentation.
+For more information on other WebRTC features, refer to the additional guides in the documentation.

webrtc/src/main/java/dev/onvoid/webrtc/RTCDataChannelObserver.java

@@ -24,11 +24,13 @@
 public interface RTCDataChannelObserver {
 
 	/**
-	 * The RTCDataChannel's buffered amount has changed.
+	 * The RTCDataChannel's buffered amount has decreased. Notifications may
+	 * combine multiple changes. The reported value is a decrease in queued
+	 * bytes, not an absolute buffer size or an acknowledgment from the peer.
 	 *
-	 * @param previousAmount The previous buffer amount.
+	 * @param sentDataSize The number of bytes removed from the buffered amount.
 	 */
-	void onBufferedAmountChange(long previousAmount);
+	void onBufferedAmountChange(long sentDataSize);
 
 	/**
 	 * The RTCDataChannel's state has changed.

webrtc/src/test/java/dev/onvoid/webrtc/RTCDataChannelTests.java

@@ -26,6 +26,8 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
 
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
@@ -46,35 +48,45 @@ void bufferedAmountChangeCallback() throws Exception {
 		caller.waitUntilConnected();
 		callee.waitUntilConnected();
 
-		// Prepare a latch-based observer to detect buffered amount change.
+		byte[] big = new byte[64 * 1024];
+		AtomicLong drainedBytes = new AtomicLong();
 		CountDownLatch latch = new CountDownLatch(1);
+		CountDownLatch open = new CountDownLatch(1);
 
 		caller.getLocalDataChannel().registerObserver(new RTCDataChannelObserver() {
 			@Override
-			public void onBufferedAmountChange(long previousAmount) {
-				latch.countDown();
+			public void onBufferedAmountChange(long sentDataSize) {
+				if (drainedBytes.addAndGet(sentDataSize) >= big.length) {
+					latch.countDown();
+				}
 			}
 
 			@Override
-			public void onStateChange() { }
+			public void onStateChange() {
+				if (caller.getLocalDataChannel().getState() == RTCDataChannelState.OPEN) {
+					open.countDown();
+				}
+			}
 
 			@Override
 			public void onMessage(RTCDataChannelBuffer buffer) { }
 		});
 
-		// Send a large enough message to cause buffering (increase from 0).
-		byte[] big = new byte[64 * 1024]; // 64 KB
-		ByteBuffer data = ByteBuffer.wrap(big);
-		RTCDataChannelBuffer buffer = new RTCDataChannelBuffer(data, true);
-		caller.getLocalDataChannel().send(buffer);
-
-		// Wait for the callback to fire to avoid flakiness.
-		boolean signaled = latch.await(5, java.util.concurrent.TimeUnit.SECONDS);
-
-		assertTrue(signaled, "onBufferedAmountChange should be called when sending data");
+		try {
+			if (caller.getLocalDataChannel().getState() == RTCDataChannelState.OPEN) {
+				open.countDown();
+			}
+			assertTrue(open.await(5, TimeUnit.SECONDS), "Data channel did not open");
+			caller.getLocalDataChannel().send(new RTCDataChannelBuffer(ByteBuffer.wrap(big), true));
 
-		caller.close();
-		callee.close();
+			assertTrue(latch.await(5, TimeUnit.SECONDS), "Buffered amount did not drain");
+			assertEquals(big.length, drainedBytes.get());
+			assertEquals(0, caller.getLocalDataChannel().getBufferedAmount());
+		}
+		finally {
+			caller.close();
+			callee.close();
+		}
 	}
 
 	@Test
@@ -128,7 +140,7 @@ public void onDataChannel(RTCDataChannel dataChannel) {
 			remoteDataChannel.registerObserver(new RTCDataChannelObserver() {
 
 				@Override
-				public void onBufferedAmountChange(long previousAmount) { }
+				public void onBufferedAmountChange(long sentDataSize) { }
 
 				@Override
 				public void onStateChange() { }