Network Efficiency Guardrails -- Inefficient network usage Document Policy

[lflores-ms]

Introduction

Network Efficiency Guardrails allows documents to opt into User Agent monitoring of network resource usage to identify resource loading patterns that are known to have disproportionate performance impact, using Document Policy as the configuration mechanism. When enabled, the User Agent classifies specific resource loading patterns as policy violations (for example, serving large or uncompressed assets), and surfaces them via the Reporting API, optionally enforcing them by blocking the resource.

Motivation

While existing performance APIs expose detailed request‑level metrics, they require developers to derive their own heuristics to identify inefficient network behavior. In practice, this makes it difficult to attribute real‑world performance regressions. The goal of this API is to make inefficient network resource usage observable through a policy-level signal.

Read the complete Explainer.

Feedback

I welcome feedback in this thread, but encourage you to file bugs against the Explainer.

[lflores-ms]

We've added an "Open questions" section to the explainer, based on recent feedback. This section includes:

• Compression eligibility for additional resource types (e.g. WASM)
• Handling of very small resources where compression overhead may exceed benefit

Feedback on any of these points would be very welcome.

[ricea]

I think total request count may also be worth considering. 1000 200-byte images is the same amount of data as 1 200,000 byte image, but the former will have a much large impact on the user experience.

[lflores-ms]

That's a good point. We had considered aggregate limits but prioritized what we considered "outrageous" behaviors in the first cut of the policy, especially per-resource transfer size as a proxy for network time. Aggregate behavior was intended to be introduced under a separate policy.

For many small requests, is the concern mainly the per-request overhead (metrics, IPC, preflights, memory, etc.) compounding over time? That's worth considering but likely requires something like a rate-based metric, which is closer to aggregate behavior than the current per-resource criteria. Curious if you have a specific formulation in mind that you think would work well here.

[ricea]

Yes, per-request overhead is a problem.

In Chrome, the first problem you hit is queuing. Requests take a very long time to hit the network, and so responsiveness suffers.

In limited-memory environments, the memory used by all those queued requests also piles up, leading to things getting even slower.

There's a hard limit somewhere of (I think) 4,000 concurrent requests, after which further requests fail, although usually by that time the first two problems have destroyed the user experience already.

A rate limit is certainly the best solution, but also the hardest to specify and implement.

It would be interesting to know how often this is a problem in practice. Unfortunately, I don't know how to get that information without implementing it.

[mmocny]

This might be beyond your scope, but to add to @ricea:

Requesting 1000 distinct resources begins to add non trivial renderer main thread processing time-- to the extent that Interaction responsiveness is visibly affected for users.

Here is a simple test page. It might not be a perfect test page but its the one I have :D

On an unthrottled MacBook it is not so bad, on a more typical mobile device, requesting 1000 resources in a single animation frame would on its own be enough to tank INP thresholds.

---

Context: this occasionally comes up in tracing real websites. Site authors optimize for JS rendering but request a large grid of components to re-render, each with too many resources...

(This part of the problem may be better served through integrating signals into the Long Animation Frame Timing API, I'm just adding food for thought)

[lflores-ms]

Thanks for adding some context. This makes sense, and I agree it's plausibly an issue. At the moment it feels exploratory: understanding prevalence seems like it would require some implementation-level instrumentation, rather than something we can confidently specify up front.

For the network-level aspect (bytes and transfer, which can certainly add up with a large number of resources), I've captured this as an open question in the explainer, but I don't think it's well-formed enough yet to shape the proposal.

It also seems useful to distinguish between layers here. The later comment appears to be more about renderer main-thread congestion and animation frame overruns affecting INP. That's valuable context, but I agree it's likely more closely aligned with LoAF and out of scope for Network Efficiency Guardrails.

[lflores-ms]

@Bas-moz Some of the discussion in Web Perf WG around the earlier proposal (link) raised questions about how enforcement and opt-in would work. I have since posted this re-scoped explainer to focus on a single policy. I welcome any thoughts on whether this framing makes those questions easier to discuss in context.

[lflores-ms]

@yoavweiss, @cwilso, @liminzhu Given the comments above, I think there's enough shared interest in the problem space to migrate the repo to WICG for further discussion. WDYT?

[ricea]

I think further discussion is warranted, yes.

My main concerns are:

1. Are the extra information disclosures really harmless?
   • Can an attacker force a cross-origin subresource to be above/below 200KB depending on whether the user is logged in?
   • Can the compressed/not compressed signal be used to distinguish between a successful response and an error response?
2. Is the feature sufficiently useful without visibility into cross-origin iframes? My impression is that third-parties use iframes extensively.

[lflores-ms]

I think these are valid concerns. Here are my current thoughts:

1. cross-origin response info
The generic version of this seems to be something like "can the hosting document infer cross-origin state based on any of the response-shape signals exposed through reporting?", which could be further broken down into:

• Can the resource shape change based on target origin state? I think the answer is yes even without exact size information. A quick example: a cross-origin request returns a small 50kB image when not logged in, and a large 500kB image when logged in.

  As far as I know, there's nothing fundamentally stopping the target origin from providing a different response based on client state, if that state is sent with the request. While increasingly harder for things like cookies, it's still possible the state would be sent in subresource embedding cases (for example, browsers with default SameSite=None).

• Does the proposed mechanism enable clear distinction of this state? I think this falls to programmatic access to cross-origin response information. In Document Policy, violations trigger Reporting API reports, which do get exposed in javascript. So, using the same example above, if the hosting document knows the response behaves differently when logged in and triggers the resource load, then it would simply need to register an observer to infer login state (assuming client state is in fact included in the request).

A few potential mitigations I think are worth exploring for these cross-origin cases:

• Introduce an opt-in header. Similar Resource Timing's Timing-Allow-Origin (mdn).

• Only trigger reports for CORS requests.

• Restrict individual reports (for example, don't trigger the javascript event, only the browser-to-endpoint report).

• Require Cross-Origin Isolation to enable the feature. Seems like an overkill and hard barrier to adoption.

• Redacted reports. Even with the details hidden, the hosting document could be crafted to infer the resource.

• Fuzzy budgets. Only applicable to sizes, and heavily dependent on fuzzy range and response diffs. If the range is 100kB but responses are 50kB vs 500kB, it still won't help.

2. cross-origin iframes

For cross-origin iframes, I think it's a matter of mechanism. The way it's set up right now, that scenario would be enabled through Document Policy's required policy (explainer), which provides enforcement. The caveat is that violation visibility cross-origin would require an extension like the one proposed in the cross-document reporting section. But I think that's something that belongs in Document Policy itself.

For same-document cases, visibility would depend on the discussion in (1). The thinking so far has been that even if cross-document reporting takes longer, the policy would still provide some value as same-document RUM signal.

[yoavweiss]

Apologies for the delay. It does seem like there's enough interest in moving this to WICG.

Do you want me to create a new repo in the WICG org for this? It seems like the explainer doesn't currently have its own repo, so transfer may not work

[lflores-ms]

No worries, thanks for having a look! Yes, we can create a repo and I'll move the "current version" to the new repo. network-efficiency-guardrails is the name I've been using.