@amazon/vinyl-util 1.0.0

package/dist/types/current/network/createRequester.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { networkLoggingHandler } from './logging/networkLoggingHandler';
+import { networkMetricsController } from './metrics/networkMetricsGlobal';
+import { nativeFetchRef, RequesterImpl } from './RequesterImpl';
+import { merge } from '../util/object/merge';
+/**
+ * Creates a default Requester implementation with optional configuration or dependency overrides.
+ * The new Requester is watched for global logging and network metrics.
+ *
+ * @param options
+ * @param deps
+ */
+export function createRequester(options, deps) {
+    const defaultDeps = {
+        networkMetricsController: networkMetricsController.value,
+        fetch: nativeFetchRef.value,
+    };
+    const finalDeps = merge(defaultDeps, deps);
+    const requester = new RequesterImpl(finalDeps);
+    if (options)
+        requester.configure(options);
+    // The logging handler does not need to be disposed, when the requester is disposed
+    // the handlers will no longer be referenced.
+    networkLoggingHandler(requester);
+    return requester;
+}

package/dist/types/current/network/logging/networkLoggingHandler.d.ts

@@ -0,0 +1,14 @@
+import type { Disposable } from '../../core/disposable';
+import type { ReadonlyEventHost } from '../../event/EventHost';
+import type { RequesterImplEventMap } from '../../network/RequesterImplEventMap';
+import { type LogTarget } from '../../logging/LogTarget';
+/**
+ * Logs all network events.
+ *
+ * @param requester The event host with request events to observe.
+ * @return Returns a disposable handle to remove all added handlers.
+ */
+export declare function networkLoggingHandler(requester: ReadonlyEventHost<RequesterImplEventMap>): Disposable & {
+    readonly target: LogTarget;
+};
+//# sourceMappingURL=networkLoggingHandler.d.ts.map

package/dist/types/current/network/logging/networkLoggingHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"networkLoggingHandler.d.ts","sourceRoot":"","sources":["../../../../../src/network/logging/networkLoggingHandler.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE1D,OAAO,KAAK,EAGR,qBAAqB,EACxB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAQrE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,GACpD,UAAU,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAgE7C"}

package/dist/types/current/network/logging/networkLoggingHandler.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createDisposer } from '../../core/disposable';
+import { logDebug } from '../../logging/Logger';
+import { truncate } from '../../util/string/string';
+import { createLogPrefix } from '../../logging/LogTarget';
+/**
+ * The max length to truncate the logged service id.
+ * @private
+ */
+const SERVICE_ID_TRUNC = 20;
+/**
+ * Logs all network events.
+ *
+ * @param requester The event host with request events to observe.
+ * @return Returns a disposable handle to remove all added handlers.
+ */
+export function networkLoggingHandler(requester) {
+    const { dispose, add } = createDisposer();
+    const target = {
+        logPrefix: createLogPrefix('Network'),
+    };
+    add(requester.on('requestAttemptStart', (event) => {
+        const url = getInputUrl(event.requestInfo.input);
+        logDebug(target, 'requestAttemptStart', truncate(event.requestInfo.requestOptions.serviceId, SERVICE_ID_TRUNC), {
+            requestInfo: {
+                url,
+                requestId: event.requestInfo.requestId,
+                maxRetries: event.requestInfo.maxRetries,
+                requestOptions: event.requestInfo.requestOptions,
+                timestamp: event.requestInfo.timestamp,
+            },
+            attemptInfo: event.attemptInfo,
+        });
+    }));
+    add(requester.on('requestAttemptComplete', (event) => {
+        const url = getInputUrl(event.requestInfo.input);
+        logDebug(target, 'requestAttemptComplete', truncate(event.requestInfo.requestOptions.serviceId, SERVICE_ID_TRUNC), {
+            ok: event.ok,
+            timestamp: event.timestamp,
+            durationMs: event.timestamp - event.requestInfo.timestamp,
+            requestInfo: {
+                url,
+                requestId: event.requestInfo.requestId,
+                maxRetries: event.requestInfo.maxRetries,
+                requestOptions: event.requestInfo.requestOptions,
+                timestamp: event.requestInfo.timestamp,
+            },
+        });
+    }));
+    return {
+        target,
+        dispose,
+    };
+}
+/**
+ * Returns the URL string of the request.
+ * @param input
+ */
+function getInputUrl(input) {
+    let url;
+    if (input instanceof URL) {
+        url = input.toString();
+    }
+    else if (typeof input === 'string') {
+        url = input;
+    }
+    else {
+        url = input.url;
+    }
+    return url;
+}

package/dist/types/current/network/metrics/NetworkMetricsController.d.ts

@@ -0,0 +1,41 @@
+import type { ReadonlyEventHost } from '../../event/EventHost';
+import type { AnyRecord, Maybe } from '../../util/type';
+import type { NetworkMetrics, NetworkMetricsEntry, NetworkTransferEntry, ServiceMetrics } from './networkMetricsModel';
+export interface NetworkMetricsEventMap {
+    /**
+     * The network metrics state has changed.
+     */
+    readonly metricsChange: AnyRecord;
+}
+export interface ReadonlyNetworkMetricsController extends ReadonlyEventHost<NetworkMetricsEventMap> {
+    /**
+     * The current metrics state.
+     * The returned object is static at the time of request.
+     */
+    readonly metrics: NetworkMetrics;
+    /**
+     * Returns metrics for the given service id.
+     * If the service id is nullish, or there is no history for the given service, empty service
+     * metrics will be returned.
+     *
+     * The returned object is static at the time of request.
+     *
+     * @param serviceId
+     */
+    getServiceMetrics(serviceId: Maybe<string>): ServiceMetrics;
+}
+export interface NetworkMetricsController extends ReadonlyNetworkMetricsController {
+    /**
+     * Adds information about a completed settled request.
+     * Note: This does not update estimated bandwidth.
+     * @param entry
+     */
+    addMetricsEntry(entry: NetworkMetricsEntry): void;
+    /**
+     * Adds information about a completed downlink content transfer.
+     *
+     * @param entry
+     */
+    addDownlinkTransferEntry(entry: NetworkTransferEntry): void;
+}
+//# sourceMappingURL=NetworkMetricsController.d.ts.map

package/dist/types/current/network/metrics/NetworkMetricsController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkMetricsController.d.ts","sourceRoot":"","sources":["../../../../../src/network/metrics/NetworkMetricsController.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EACR,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACjB,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAA;CACpC;AAED,MAAM,WAAW,gCAAiC,SAAQ,iBAAiB,CAAC,sBAAsB,CAAC;IAC/F;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAEhC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,cAAc,CAAA;CAC9D;AAED,MAAM,WAAW,wBAAyB,SAAQ,gCAAgC;IAC9E;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAEjD;;;;OAIG;IACH,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAAA;CAC9D"}

package/dist/types/current/network/metrics/NetworkMetricsController.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/network/metrics/NetworkMetricsControllerImpl.d.ts

@@ -0,0 +1,119 @@
+import { EventHostImpl } from '../../event/EventHost';
+import type { NetworkInformation } from '../../network/browser/NetworkInformation';
+import type { NetworkMetricsController, NetworkMetricsEventMap } from './NetworkMetricsController';
+import type { NetworkMetrics, NetworkMetricsEntry, NetworkTransferEntry, ServiceMetrics } from './networkMetricsModel';
+import type { ReadonlyDeep } from '../../util/object/readonlyType';
+import type { Maybe } from '../../util/type';
+import type { Timestamp } from '../../util/date/date';
+export interface NetworkMetricsControllerImplOptions {
+    /**
+     * The smoothing factor for EWMA (Exponential Moving Weighted Average), used in
+     * bandwidth and response time moving averages.
+     *
+     * The purpose is to give more weight to recent events than old events, while keeping
+     * calculations simple and avoiding the need to keep histories as a rolling average would.
+     *
+     * This value should be between 0 and 1.
+     * The closer to 1 this value is, the more weight new values have.
+     * A value of 0.2 for example would mean that after 10 updates, the current average after
+     * ten new data points would influence the new average by (1-0.2)^10 ≈ 10% and the latest
+     * update would influence the average by 20%.
+     */
+    readonly ewmaSmoothing: number;
+    /**
+     * For biased values such as ewmaHigh/ewmaLow, when the value is in the direction of the
+     * bias, this smoothing will be used.
+     * This should be a value between 0 and 1 and be more than bias negative smoothing.
+     */
+    readonly ewmaBiasPositiveSmoothing: number;
+    /**
+     * For biased values such as ewmaHigh/ewmaLow, when the value is not in the direction of the
+     * bias, this smoothing will be used.
+     * This should be a value between 0 and 1 and be less than bias positive smoothing.
+     */
+    readonly ewmaBiasNegativeSmoothing: number;
+    /**
+     * When the user's bandwidth cannot be determined due to lack of NetworkInformation support
+     * and no reported downlink history, then this value will be used.
+     * This should be in bits per second.
+     */
+    readonly unknownDownlinkBandwidthEstimate: number;
+    /**
+     * Maximum bandwidth in bps we will attribute to any single measurement.
+     * Transfers measured above this are clamped; zero-duration transfers are
+     * treated as this speed rather than discarded.
+     * Default: 30_000_000
+     */
+    readonly maxMeasuredBandwidthBps: number;
+    /**
+     * Time window (in seconds) for amortizing network transfer entries in bandwidth estimation.
+     *
+     * This window enables accurate bandwidth calculation across multiple concurrent streams
+     * (audio, video, etc.) by aggregating transfer data over time.
+     *
+     * - Too low: Streams won't be properly combined, leading to inaccurate estimates
+     * - Too high: Bandwidth estimation becomes slow to adapt to network changes
+     *
+     * @default 4
+     */
+    readonly bandwidthEstimationWindow: number;
+}
+/**
+ * Default configuration for NetworkMetricsControllerImpl
+ */
+export declare const defaultNetworkMetricsControllerImplOptions: {
+    readonly ewmaSmoothing: 0.2;
+    readonly ewmaBiasNegativeSmoothing: 0.1;
+    readonly ewmaBiasPositiveSmoothing: 0.5;
+    readonly unknownDownlinkBandwidthEstimate: 2200000;
+    readonly maxMeasuredBandwidthBps: 30000000;
+    readonly bandwidthEstimationWindow: 4;
+};
+export interface NetworkMetricsControllerImplDependencies {
+    readonly networkInformation?: Maybe<NetworkInformation>;
+}
+export declare class NetworkMetricsControllerImpl extends EventHostImpl<NetworkMetricsEventMap> implements NetworkMetricsController {
+    private readonly deps;
+    private _metrics;
+    /**
+     * A clone of _metrics, copied on read after a change.
+     * @private
+     */
+    private _metricsSnapshot;
+    private hasChanged;
+    private readonly options;
+    private readonly transferEntries;
+    private readonly refreshEstimatedBandwidthThrottled;
+    private readonly disposer;
+    constructor(deps: NetworkMetricsControllerImplDependencies, options?: Partial<NetworkMetricsControllerImplOptions>);
+    get [Symbol.toStringTag](): string;
+    get metrics(): NetworkMetrics;
+    getServiceMetrics(serviceId: Maybe<string>): ReadonlyDeep<ServiceMetrics>;
+    addMetricsEntry(entry: NetworkMetricsEntry): void;
+    private readonly refreshEstimatedBandwidth;
+    addDownlinkTransferEntry(entry: NetworkTransferEntry): void;
+    private onDownloadSpeedChange;
+    private notifyMetricsChange;
+    dispose(): void;
+}
+/**
+ * Estimates the timestamp when the first response byte was received for a network transfer.
+ *
+ * When the browser's Resource Timing API provides `responseStart`, that value is used directly.
+ * Otherwise, a logistic model estimates the latency fraction (the proportion of total
+ * request time spent waiting for the first byte) from the transfer size and total duration.
+ *
+ * The model uses a sigmoid function parameterized on a feature combining `log(bytes)` and
+ * `log(totalTime)`. Larger transfers relative to their duration are assumed to have a smaller
+ * latency fraction (most time is spent downloading), while small or slow transfers are assumed
+ * to be latency-dominated.
+ *
+ * `responseEnd` represents when the fetch promise settled (approximately when HTTP headers
+ * arrived). This provides an upper bound on when the first byte was received — the actual
+ * responseStart is at or before this point.
+ *
+ * @param entry - A completed network transfer entry with timing information.
+ * @returns The estimated timestamp (ms since epoch) when the first response byte arrived.
+ */
+export declare function estimateResponseStart(entry: NetworkTransferEntry): Timestamp;
+//# sourceMappingURL=NetworkMetricsControllerImpl.d.ts.map

package/dist/types/current/network/metrics/NetworkMetricsControllerImpl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkMetricsControllerImpl.d.ts","sourceRoot":"","sources":["../../../../../src/network/metrics/NetworkMetricsControllerImpl.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAA;AAC9E,OAAO,KAAK,EACR,wBAAwB,EACxB,sBAAsB,EACzB,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EACR,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EAEjB,MAAM,uBAAuB,CAAA;AAO9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAG9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAkBjD,MAAM,WAAW,mCAAmC;IAChD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,gCAAgC,EAAE,MAAM,CAAA;IAEjD;;;;;OAKG;IACH,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAA;IAExC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAA;CAC7C;AAED;;GAEG;AACH,eAAO,MAAM,0CAA0C;;;;;;;CAWC,CAAA;AAExD,MAAM,WAAW,wCAAwC;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAA;CAC1D;AAED,qBAAa,4BACT,SAAQ,aAAa,CAAC,sBAAsB,CAC5C,YAAW,wBAAwB;IAkB/B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAhBzB,OAAO,CAAC,QAAQ,CAA4D;IAE5E;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAwB;IAChD,OAAO,CAAC,UAAU,CAAQ;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,kCAAkC,CAAmB;IAEtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAGvB,IAAI,EAAE,wCAAwC,EAC/D,OAAO,CAAC,EAAE,OAAO,CAAC,mCAAmC,CAAC;IAgC1D,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;IAED,IAAI,OAAO,IAAI,cAAc,CAM5B;IAED,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,cAAc,CAAC;IAKzE,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAejD,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAgCzC;IAED,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI;IAM3D,OAAO,CAAC,qBAAqB,CAW5B;IAED,OAAO,CAAC,mBAAmB;IAK3B,OAAO;CAIV;AAwED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAe5E"}

package/dist/types/current/network/metrics/NetworkMetricsControllerImpl.js

@@ -0,0 +1,210 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { EventHostImpl } from '../../event/EventHost';
+import { EMPTY_NETWORK_METRICS, EMPTY_SERVICE_METRICS, } from './networkMetricsModel';
+import { lerp } from '../../util/math/math';
+import { clone } from '../../util/object/clone';
+import { getOrSetProp } from '../../util/object/object';
+import { logVerbose } from '../../logging/Logger';
+import { throttle } from '../../util/fun/throttle';
+import { createDisposer } from '../../core/disposable';
+import { UnionRanges } from '../../util/range/UnionRanges';
+import { rangesOf } from '../../util/range/Ranges';
+/**
+ * Default configuration for NetworkMetricsControllerImpl
+ */
+export const defaultNetworkMetricsControllerImplOptions = {
+    ewmaSmoothing: 0.2,
+    ewmaBiasNegativeSmoothing: 0.1,
+    ewmaBiasPositiveSmoothing: 0.5,
+    // Using the p10 value for customer bandwidth worldwide, which should be enough bandwidth for
+    // 90% of customers. This is high enough for HD content, but not UHD.
+    unknownDownlinkBandwidthEstimate: 2_200_000,
+    maxMeasuredBandwidthBps: 30_000_000,
+    bandwidthEstimationWindow: 4,
+};
+export class NetworkMetricsControllerImpl extends EventHostImpl {
+    deps;
+    _metrics = clone(EMPTY_NETWORK_METRICS);
+    /**
+     * A clone of _metrics, copied on read after a change.
+     * @private
+     */
+    _metricsSnapshot = EMPTY_NETWORK_METRICS;
+    hasChanged = false;
+    options;
+    transferEntries = [];
+    refreshEstimatedBandwidthThrottled;
+    disposer = createDisposer();
+    constructor(deps, options) {
+        super();
+        this.deps = deps;
+        const { add } = this.disposer;
+        this.options = {
+            ...defaultNetworkMetricsControllerImplOptions,
+            ...options,
+        };
+        this.onDownloadSpeedChange();
+        this.deps.networkInformation?.addEventListener('change', this.onDownloadSpeedChange);
+        add(() => {
+            this.deps.networkInformation?.removeEventListener('change', this.onDownloadSpeedChange);
+        });
+        this.refreshEstimatedBandwidthThrottled = add(throttle(this.refreshEstimatedBandwidth, this.options.bandwidthEstimationWindow, {
+            leading: false,
+            trailing: true,
+        }));
+    }
+    get [Symbol.toStringTag]() {
+        return 'NetworkMetricsControllerImpl';
+    }
+    get metrics() {
+        if (this.hasChanged) {
+            this.hasChanged = false;
+            this._metricsSnapshot = clone(this._metrics);
+        }
+        return this._metricsSnapshot;
+    }
+    getServiceMetrics(serviceId) {
+        if (serviceId == null)
+            return EMPTY_SERVICE_METRICS;
+        return this.metrics.serviceMetrics[serviceId] ?? EMPTY_SERVICE_METRICS;
+    }
+    addMetricsEntry(entry) {
+        const metrics = this._metrics;
+        if (entry.serviceId) {
+            const serviceMetrics = getOrSetProp(metrics.serviceMetrics, entry.serviceId, () => clone(EMPTY_SERVICE_METRICS));
+            updateServiceMetrics(serviceMetrics, entry, this.options);
+        }
+        updateServiceMetrics(metrics.totals, entry, this.options);
+        this.notifyMetricsChange();
+    }
+    refreshEstimatedBandwidth = () => {
+        const ranges = [];
+        let bytes = 0;
+        for (const entry of this.transferEntries) {
+            const start = estimateResponseStart(entry);
+            const end = entry.contentEnd;
+            ranges.push([start, end]);
+            bytes += entry.bytes;
+        }
+        this.transferEntries.length = 0;
+        const union = new UnionRanges([rangesOf(ranges)]);
+        let time = Number.MIN_VALUE;
+        for (const [start, end] of union) {
+            time += (end - start) / 1000;
+        }
+        const bps = Math.min((bytes * 8) / time, this.options.maxMeasuredBandwidthBps);
+        updateStatMetrics(this._metrics.estimatedDownlinkBandwidth, bps, this.options);
+        logVerbose(this, 'addDownlinkTransferEntry', this._metrics.estimatedDownlinkBandwidth);
+        this.notifyMetricsChange();
+    };
+    addDownlinkTransferEntry(entry) {
+        if (entry.bytes <= 0)
+            return;
+        this.transferEntries.push(entry);
+        this.refreshEstimatedBandwidthThrottled();
+    }
+    onDownloadSpeedChange = () => {
+        const downlink = this.deps.networkInformation?.downlink; // mbps
+        const estimatedSpeed = downlink
+            ? downlink * 1024 * 1024 // bps
+            : this.options.unknownDownlinkBandwidthEstimate;
+        updateStatMetrics(this._metrics.estimatedDownlinkBandwidth, estimatedSpeed, this.options);
+        this.notifyMetricsChange();
+    };
+    notifyMetricsChange() {
+        this.hasChanged = true;
+        this.dispatch('metricsChange', {});
+    }
+    dispose() {
+        super.dispose();
+        this.disposer.dispose();
+    }
+}
+/**
+ * Updates totals and consecutive counts for the service metrics.
+ */
+function updateServiceMetrics(serviceMetrics, entry, options) {
+    const totals = entry.ok
+        ? serviceMetrics.successTotals
+        : serviceMetrics.failureTotals;
+    totals.totalCount++;
+    totals.consecutiveCount++;
+    if (entry.responseTime) {
+        updateStatMetrics(serviceMetrics.responseTime, entry.responseTime, options);
+    }
+    if (entry.ok)
+        serviceMetrics.failureTotals.consecutiveCount = 0;
+    else
+        serviceMetrics.successTotals.consecutiveCount = 0;
+    if (entry.retryAfter)
+        serviceMetrics.retryAfter = Math.max(serviceMetrics.retryAfter ?? 0, entry.retryAfter);
+}
+function updateStatMetrics(statMetrics, newValue, options) {
+    if (!statMetrics.dataPoints) {
+        statMetrics.min = newValue;
+        statMetrics.max = newValue;
+        statMetrics.average = newValue;
+        statMetrics.latest = newValue;
+        statMetrics.ewma = newValue;
+        statMetrics.ewmaHigh = newValue;
+        statMetrics.ewmaLow = newValue;
+        statMetrics.dataPoints = 1;
+        return;
+    }
+    statMetrics.dataPoints++;
+    statMetrics.min = Math.min(statMetrics.min, newValue);
+    statMetrics.max = Math.max(statMetrics.max, newValue);
+    statMetrics.average = lerp(statMetrics.average, newValue, 1 / statMetrics.dataPoints);
+    statMetrics.latest = newValue;
+    // Weighted averages
+    statMetrics.ewma = lerp(statMetrics.ewma, newValue, options.ewmaSmoothing);
+    const highAlpha = newValue > statMetrics.ewmaHigh
+        ? options.ewmaBiasPositiveSmoothing
+        : options.ewmaBiasNegativeSmoothing;
+    statMetrics.ewmaHigh = lerp(statMetrics.ewmaHigh, newValue, highAlpha);
+    const lowAlpha = newValue < statMetrics.ewmaLow
+        ? options.ewmaBiasPositiveSmoothing
+        : options.ewmaBiasNegativeSmoothing;
+    statMetrics.ewmaLow = lerp(statMetrics.ewmaLow, newValue, lowAlpha);
+}
+/**
+ * Estimates the timestamp when the first response byte was received for a network transfer.
+ *
+ * When the browser's Resource Timing API provides `responseStart`, that value is used directly.
+ * Otherwise, a logistic model estimates the latency fraction (the proportion of total
+ * request time spent waiting for the first byte) from the transfer size and total duration.
+ *
+ * The model uses a sigmoid function parameterized on a feature combining `log(bytes)` and
+ * `log(totalTime)`. Larger transfers relative to their duration are assumed to have a smaller
+ * latency fraction (most time is spent downloading), while small or slow transfers are assumed
+ * to be latency-dominated.
+ *
+ * `responseEnd` represents when the fetch promise settled (approximately when HTTP headers
+ * arrived). This provides an upper bound on when the first byte was received — the actual
+ * responseStart is at or before this point.
+ *
+ * @param entry - A completed network transfer entry with timing information.
+ * @returns The estimated timestamp (ms since epoch) when the first response byte arrived.
+ */
+export function estimateResponseStart(entry) {
+    if (entry.responseStart)
+        return entry.responseStart;
+    // responseEnd is when the fetch settled (headers received), which is an upper bound on
+    // when the first byte arrived. Use it as the estimate — the actual first byte is at or
+    // slightly before this point, but never after it.
+    if (entry.responseEnd <= entry.requestStart)
+        return entry.requestStart;
+    const totalTime = entry.contentEnd - entry.requestStart;
+    if (totalTime === 0)
+        return entry.requestStart;
+    // The sigmoid estimates what fraction of the total request-to-content time was spent
+    // waiting (DNS, TCP, TLS, server processing) vs. receiving bytes.
+    const feature = 0.2 * Math.log(entry.bytes) - Math.log(totalTime);
+    const latencyFraction = 0.87 / (1 + Math.exp(-(feature + 3.8) / 0.3));
+    // Clamp the estimate to not exceed responseEnd (when headers arrived).
+    const estimated = entry.requestStart + latencyFraction * totalTime;
+    return Math.min(estimated, entry.responseEnd);
+}

package/dist/types/current/network/metrics/networkMetricsGlobal.d.ts

@@ -0,0 +1,11 @@
+import type { NetworkMetricsController } from './NetworkMetricsController';
+import type { NetworkMetrics } from './networkMetricsModel';
+/**
+ * A global reference to the network metrics controller.
+ */
+export declare const networkMetricsController: import("../../global/globalRegistry").GlobalRef<NetworkMetricsController>;
+/**
+ * Returns the global network metrics.
+ */
+export declare function getNetworkMetrics(): NetworkMetrics;
+//# sourceMappingURL=networkMetricsGlobal.d.ts.map

package/dist/types/current/network/metrics/networkMetricsGlobal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"networkMetricsGlobal.d.ts","sourceRoot":"","sources":["../../../../../src/network/metrics/networkMetricsGlobal.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAE3D;;GAEG;AACH,eAAO,MAAM,wBAAwB,uEAKpC,CAAA;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}

package/dist/types/current/network/metrics/networkMetricsGlobal.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { globalRef } from '../../global/globalRegistry';
+import { getNetworkInformation } from '../../network/browser/NetworkInformation';
+import { NetworkMetricsControllerImpl } from './NetworkMetricsControllerImpl';
+/**
+ * A global reference to the network metrics controller.
+ */
+export const networkMetricsController = globalRef(() => new NetworkMetricsControllerImpl({
+    networkInformation: getNetworkInformation(),
+}));
+/**
+ * Returns the global network metrics.
+ */
+export function getNetworkMetrics() {
+    return networkMetricsController.value.metrics;
+}