From 09c818d82ab26bd1edcbb8e27bab0026e13e27cd Mon Sep 17 00:00:00 2001 From: Noah Gregory Date: Thu, 9 Apr 2026 11:17:20 -0400 Subject: [PATCH 1/2] rfc: protocol handling enhancement --- text/0027-protocol-handling-enhancement.md | 53 ++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 text/0027-protocol-handling-enhancement.md diff --git a/text/0027-protocol-handling-enhancement.md b/text/0027-protocol-handling-enhancement.md new file mode 100644 index 0000000..adbe1ea --- /dev/null +++ b/text/0027-protocol-handling-enhancement.md @@ -0,0 +1,53 @@ +# Protocol Handling Enhancement + +- Start Date: 2026-04-09 +- RFC PR: [electron/rfcs#29](https://github.com/electron/rfcs/pull/29) +- Electron Issues: [electron/electron#15434](https://github.com/electron/electron/issues/15434), [electron/electron#49358](https://github.com/electron/electron/issues/49358), [electron/electron#39709](https://github.com/electron/electron/issues/39709), [electron/electron#39525](https://github.com/electron/electron/issues/39525) +- Reference Implementation: [electron/electron#49671](https://github.com/electron/electron/pull/49671) +- Status: **Proposed** + +## Summary + +This RFC outlines the need for a better approach to request interception / introspection / modification API's. + +## Motivation + +Right now, the ability to intercept, introspect, and/or modify HTTP requests is split across the `protocol.handle` API and the `webRequest` handlers. This has lead to some users attempting to use `protocol.handle` as a sort of middleware, using `bypassCustomProtocolHandlers` to forward the intercepted request to the built-in handler. This is the way that option is currently documented. However, it is documented it with the use of `net.fetch`, which can have different semantics than the Chromium browser (especially around redirects). A more aligned "fallback to Chromium" path should be added. + +The simplfied `Request`->`Response` flow has also lead to some users attempting to set cookies merely by returning a `Response` with their desired `Set-Cookie` header. Things like this may, currently, be better handled with `webRequest` handlers. However, that splits up behavior when a user may want to be able to do all of these things in a single API. + +## Guide-level explanation + +The future API design for depends on answers to the unresolved questions below. + +## Reference-level explanation + +The future API design for depends on answers to the unresolved questions below. + +## Drawbacks + +The work required to balance all the nuances here is likely non-trivial. + +## Rationale and alternatives + +N/A + +## Prior art + +To be filled out as alignment happens on a more clear API design. + +## Unresolved questions + +- Is `protocol.handle` meant, by us, to be an middleware-like interception API or a provider API for the `https` scheme? +- Should `protocol.handle` be split into two different API's (e.g. `protocol.handle` and `protocol.intercept`)? +- In the case that a more middleware-like interception API is desired: + - Should we allow for the intercepted request to be modified before a potential fallback? + - Should we allow for the returned response to be modified before passing it along? + - Should the "fallback to Chromium" option use the in-flight request or dispatch a new one? + - Should setting the `Set-Cookie` header in a returned response set the cookies? + - Should layered handlers (middleware-like) be supported? +- What should happen to the `webRequest` handlers API? + +## Future possibilities + +N/A \ No newline at end of file From a6abf234949de62048ab8ed190db89c2be1c8fae Mon Sep 17 00:00:00 2001 From: Noah Gregory Date: Thu, 9 Apr 2026 11:24:45 -0400 Subject: [PATCH 2/2] fix: minor wording change --- text/0027-protocol-handling-enhancement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0027-protocol-handling-enhancement.md b/text/0027-protocol-handling-enhancement.md index adbe1ea..8ee71c6 100644 --- a/text/0027-protocol-handling-enhancement.md +++ b/text/0027-protocol-handling-enhancement.md @@ -12,7 +12,7 @@ This RFC outlines the need for a better approach to request interception / intro ## Motivation -Right now, the ability to intercept, introspect, and/or modify HTTP requests is split across the `protocol.handle` API and the `webRequest` handlers. This has lead to some users attempting to use `protocol.handle` as a sort of middleware, using `bypassCustomProtocolHandlers` to forward the intercepted request to the built-in handler. This is the way that option is currently documented. However, it is documented it with the use of `net.fetch`, which can have different semantics than the Chromium browser (especially around redirects). A more aligned "fallback to Chromium" path should be added. +Right now, the ability to intercept, introspect, and/or modify HTTP requests is split across the `protocol.handle` API and the `webRequest` handlers. This has lead to some users attempting to use `protocol.handle` as a sort of middleware, using `bypassCustomProtocolHandlers` to forward the intercepted request to the built-in handler. This is the way that option is currently documented. However, it is documented it with the use of `net.fetch`, which can have different semantics than the Chromium browser (especially around redirects). A more-aligned "fallback to Chromium" path should be added. The simplfied `Request`->`Response` flow has also lead to some users attempting to set cookies merely by returning a `Response` with their desired `Set-Cookie` header. Things like this may, currently, be better handled with `webRequest` handlers. However, that splits up behavior when a user may want to be able to do all of these things in a single API.