Feature Request — Runtime APIs: API for Early Hints

[marcusdarmstrong]

Background:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103
https://blog.cloudflare.com/early-hints/

For my application (and presumably others with this as a design goal), we can trivially determine (some of) the asset URLs we're going to need on the document load, far ahead of knowing what the status code will be. Currently, Workerd lacks an explicit facility for declaring early hints from the application, with Cloudflare's public offering requiring that the eventual response header be committed to extract them.

My potentially naive proposal here would be to accept generators as fetch handlers, allowing yields of Response objects with a 103 status, but a context object based API would seem to be viable too. Pursuing use of the Response object in either API would technically require either spec divergence or upstream agreement, as Response is spec'd to throw a RangeError for status codes < 200.

While I have very limited experience in the C++ world, it's very important to some of my employer's architectural goals/possibly a blocker to our ability to use workerd, so I'd be happy to try to work towards contributing this if we can establish agreement on desirability and API.

[kentonv]

Hi Marcus,

Thanks for the suggestion. We prefer our issue tracker to track immediately-actionable issues (e.g. bugs) rather than long-term feature requests and ideas, so I will convert this to a discussion.

[marcusdarmstrong]

Circling back, is there any read on your end about desirability here?

[kentonv]

Hi Marcus,

This seems like a reasonable feature request, but I'm not sure when we'd be able to work on it -- we have a lot on our plates. While I appreciate the offer to help, unfortunately our experience is that guiding someone outside the team to implement a new feature usually ends up taking more of the team's time overall than having someone on the team do the work directly.

cc @irvinebroque (product manager) to think about where this might fit into our long term roadmap.

[jasnell]

As a fan of the early hints work I would absolutely love to see this happen. One key challenge here is that there really isn't a standard way of expressing these just yet. Yielding a non-final Response object would likely work but just feels.... hacky? Especially given that at most what we need here is setting a Headers object. e.g. something like...

export default {
  async fetch(req, env, ctx) {
    // send hints...
    ctx.sendEarlyHints(new Headers('...'));
    // do something
    return new Response(...);
  }
};

For me, this feels a bit more natural.

Unfortunately it is not as simple as just adding this API. Internally, we make use of kj's HTTP implementation and have that woven throughout a number of places internally. The first step here, I believe, would be in teaching kj how to handle early hints, which I imagine is a non-trivial exercise. Once that is done, we could look at how to support this elsewhere. We would also have to make sure that other parts of our infrastructure can support us sending these, which is something that can be explored, but as Kenton points out, we've got a lot on the plate already and it is not clear that this is something that could be prioritized quickly. That said, if it is something that you're interested in exploring, with the warning that it may take some time and a lot of back and forth, I would encourage you to start digging into the details of kj to see how it could be done. I caution, however, it's likely to be a very complex change, and in the spirit of Zork, "It is pitch black. You are likely to be eaten by a grue."

[marcusdarmstrong]

Yeah, my thought with the Response suggestion was mostly that this seems possible to be something the service worker spec itself might want to take up in the future, but getting all the relevant ducks in a row to get actual spec-level alignment on that sounds like making a slow process even slower. I certainly have no objection to specific context-driven API, however, particularly given that there isn't an in-progress standard here—I'm just sympathetic to the stated workerd philosophy of "web standard apis" as the starting point.

My hope would be that the existing codepaths for HTTP 101/Upgrade responses might make some of that wiring internally more viable, but I'll take a look and see what might be missing.

[jasnell]

There is a conversation starting within WinterCG to eventually try to standardize a lot of the server-side serverless/edge function APIs and behaviors but that is a long road and won't happen anytime soon. We'll need implementation experience first and a cloudflare/workerd-specific API would be the best approach forward on that front.