feat: report server-accepted upload bytes in results

src/Results/MeasurementCalculations.ts

@@ -82,14 +82,23 @@ class MeasurementCalculations {
     Object.entries(bandwidthResults)
       .map(([bytes, { timings }]) =>
         timings.map(
-          ({ bps, duration, ping, measTime, serverTime, transferSize }) => ({
+          ({
+            bps,
+            duration,
+            ping,
+            measTime,
+            serverTime,
+            transferSize,
+            uploadBytes
+          }) => ({
             bytes: +bytes,
             bps,
             duration,
             ping,
             measTime,
             serverTime,
-            transferSize
+            transferSize,
+            uploadBytes
           })
         )
       )

src/engines/BandwidthEngine/BandwidthEngine.ts

@@ -84,6 +84,8 @@ export interface BandwidthMeasurementTiming {
   ping: number;
   duration: number;
   bps: number | undefined;
+  /** Server-accepted upload size (bytes) from `cf-meta-upload-bytes`, uploads only. */
+  uploadBytes?: number;
 }
 
 export interface BandwidthTimingResult extends BandwidthMeasurementTiming {

src/engines/BandwidthEngine/LoggingBandwidthEngine.ts

@@ -7,6 +7,25 @@ import type {
 } from './BandwidthEngine';
 import type { ParallelLatencyOptions } from './ParallelLatency';
 
+export const parseUploadBytesHeader = (
+  headers: Headers
+): number | undefined => {
+  const value = headers.get('cf-meta-upload-bytes');
+  if (!value || !/^\d+$/.test(value)) return undefined;
+
+  const bytes = Number(value);
+  return Number.isSafeInteger(bytes) ? bytes : undefined;
+};
+
+/** Upload logs use server-accepted bytes when the server reports a cap. */
+export const getLoggedBytes = (
+  measData: Pick<BandwidthTimingResult, 'type' | 'bytes'>,
+  uploadBytes: number | undefined
+): number =>
+  measData.type === 'up' && uploadBytes !== undefined
+    ? uploadBytes
+    : measData.bytes;
+
 export interface LoggingBandwidthEngineOptions extends ParallelLatencyOptions {
   measurementId?: string;
   logApiUrl?: string;
@@ -38,8 +57,10 @@ class LoggingBandwidthEngine extends BandwidthEngine {
     super.qsParams = logApiUrl ? { measId: this.#measurementId! } : {};
     super.responseHook = (r: ResponseHookPayload) =>
       this.#loggingResponseHook(r);
-    super.onMeasurementResult = (meas: BandwidthTimingResult) =>
+    super.onMeasurementResult = (meas: BandwidthTimingResult) => {
+      this.#applyUploadBytes(meas);
       this.#logMeasurement(meas);
+    };
   }
 
   // Overridden attributes
@@ -66,6 +87,7 @@ class LoggingBandwidthEngine extends BandwidthEngine {
       meas: BandwidthTimingResult,
       ...restArgs: [BandwidthEngineResults]
     ) => {
+      this.#applyUploadBytes(meas);
       onMeasurementResult(meas, ...restArgs);
       this.#logMeasurement(meas);
     };
@@ -75,11 +97,27 @@ class LoggingBandwidthEngine extends BandwidthEngine {
   #measurementId: string | undefined;
   #token: string | null | undefined;
   #requestTime: number | null | undefined;
+  #uploadBytes: number | undefined;
   #logApiUrl: string | undefined;
   #sessionId: string | undefined;
 
   // Internal methods
+
+  /**
+   * Records server-accepted upload bytes on the measurement result so the
+   * final results payload can report the actual uploaded size (uploads only).
+   */
+  #applyUploadBytes(measData: BandwidthTimingResult): void {
+    if (measData.type === 'up' && this.#uploadBytes !== undefined) {
+      measData.uploadBytes = this.#uploadBytes;
+    }
+  }
+
   #loggingResponseHook(r: ResponseHookPayload): void {
+    // Capture server-accepted upload bytes regardless of per-measurement
+    // logging, so the final results payload can report actual uploaded sizes.
+    this.#uploadBytes = parseUploadBytesHeader(r.headers);
+
     if (!this.#logApiUrl) return;
 
     // get request time
@@ -94,7 +132,7 @@ class LoggingBandwidthEngine extends BandwidthEngine {
 
     const logData = {
       type: measData.type,
-      bytes: measData.bytes,
+      bytes: getLoggedBytes(measData, this.#uploadBytes),
       ping: Math.round(measData.ping), // round to ms
       ttfb: Math.round(measData.ttfb), // round to ms
       payloadDownloadTime: Math.round(measData.payloadDownloadTime),
@@ -109,6 +147,7 @@ class LoggingBandwidthEngine extends BandwidthEngine {
 
     this.#token = null;
     this.#requestTime = null;
+    this.#uploadBytes = undefined;
 
     fetch(this.#logApiUrl, {
       method: 'POST',

src/logging/logFinalResults.ts

@@ -50,10 +50,14 @@ const round = (
 const latencyPointsParser: ParserFn = durations =>
   (durations as number[]).map(d => round(d, 2));
 
-/** Extracts bytes and rounded bps from each bandwidth data point. */
+/**
+ * Extracts bytes and rounded bps from each bandwidth data point. For uploads,
+ * `bytes` is the server-accepted size (`cf-meta-upload-bytes`) when reported,
+ * falling back to the requested size; downloads always use the requested size.
+ */
 const bpsPointsParser: ParserFn = pnts =>
   (pnts as BandwidthPoint[]).map(d => ({
-    bytes: +d.bytes,
+    bytes: d.uploadBytes ?? +d.bytes,
     bps: round(d.bps)
   }));
 

src/types.ts

@@ -37,6 +37,13 @@ export interface BandwidthTiming {
 
   /** Actual number of bytes transferred (from `PerformanceResourceTiming`). */
   transferSize: number;
+
+  /**
+   * Server-accepted upload size (bytes), from the `cf-meta-upload-bytes`
+   * response header. Present only for upload requests where the server
+   * reported how much of the body it accepted (e.g. when it caps the upload).
+   */
+  uploadBytes?: number;
 }
 
 /**
@@ -87,6 +94,13 @@ export interface BandwidthPoint {
 
   /** From `PerformanceResourceTiming`. */
   transferSize: number;
+
+  /**
+   * Server-accepted upload size (bytes), from the `cf-meta-upload-bytes`
+   * response header. Present only for upload points where the server reported
+   * how much of the body it accepted.
+   */
+  uploadBytes?: number;
 }
 
 /** Results from a packet-loss measurement via WebRTC TURN relay. */

tests/unit/Results/MeasurementCalculations.test.ts

@@ -119,6 +119,27 @@ describe('MeasurementCalculations', () => {
       expect(result[0].bytes).toBe(100000);
       expect(result[1].bytes).toBe(1000000);
     });
+
+    it('surfaces server-accepted upload bytes when present', () => {
+      const calc = createCalc();
+      const result = calc.getBandwidthPoints({
+        5000000000: {
+          timings: [
+            {
+              bps: 10e6,
+              duration: 100,
+              ping: 12,
+              measTime: new Date(200),
+              serverTime: 8,
+              transferSize: 4000000000,
+              uploadBytes: 4000000000
+            }
+          ]
+        }
+      });
+      expect(result[0].bytes).toBe(5000000000);
+      expect(result[0].uploadBytes).toBe(4000000000);
+    });
   });
 
   describe('getBandwidth', () => {

tests/unit/engines/loggingBandwidthEngine.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  getLoggedBytes,
+  parseUploadBytesHeader
+} from '../../../src/engines/BandwidthEngine/LoggingBandwidthEngine.ts';
+
+describe('LoggingBandwidthEngine', () => {
+  describe('parseUploadBytesHeader', () => {
+    it('reads a valid cf-meta-upload-bytes header', () => {
+      const headers = new Headers({ 'cf-meta-upload-bytes': '4000000000' });
+
+      expect(parseUploadBytesHeader(headers)).toBe(4000000000);
+    });
+
+    it('ignores missing or invalid cf-meta-upload-bytes headers', () => {
+      expect(parseUploadBytesHeader(new Headers())).toBeUndefined();
+      expect(
+        parseUploadBytesHeader(new Headers({ 'cf-meta-upload-bytes': '1e3' }))
+      ).toBeUndefined();
+      expect(
+        parseUploadBytesHeader(new Headers({ 'cf-meta-upload-bytes': '-1' }))
+      ).toBeUndefined();
+    });
+  });
+
+  describe('getLoggedBytes', () => {
+    it('uses server-reported upload bytes for upload measurements', () => {
+      expect(
+        getLoggedBytes({ type: 'up', bytes: 5000000000 }, 4000000000)
+      ).toBe(4000000000);
+    });
+
+    it('falls back to measured bytes when the header is absent', () => {
+      expect(getLoggedBytes({ type: 'up', bytes: 5000000000 }, undefined)).toBe(
+        5000000000
+      );
+    });
+
+    it('does not override download measurements', () => {
+      expect(
+        getLoggedBytes({ type: 'down', bytes: 5000000000 }, 4000000000)
+      ).toBe(5000000000);
+    });
+  });
+});