Skip to content

rfc: protocol handling enhancement #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nmggithub wants to merge 2 commits into
base: main
Choose a base branch
from
+53 −0
Open

rfc: protocol handling enhancement #29

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09c818d
rfc: protocol handling enhancement
nmggithub Apr 9, 2026
a6abf23
fix: minor wording change
nmggithub Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions text/0027-protocol-handling-enhancement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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