feat: Add support to callback in protocol interceptor handler without argument to perform as if no interceptors.

[mrchaofan]

Description of Change

To SAVE your life while doing protocol intercept.
These changes were made to allow you writting code blow.

protocol.interceptProtocol('https', (req, callback) => {
    // map request to file.
    if (shouldMapToLocal(req)) {
        callback({
            path: getLocalFilePathOf(req)
        })
        return
    }
    // Trigger the default behavior of loading https request
    // You never need to care about the net.fetch and handle the redirect may happen in net.fetch.
    // Just call callback();
    // NOTE that only protocol.intercept(Any)Protocol is allowed to call callback without argument.
    // if you are doing a protocol register you have to give the response data in callback too.
    callback();
})

Just DO NOT use the documented way.

protocol.handle('app', (req) => {
  if (shouldResponseByOthers(req) {
    return giveReponseByOthers(req)
  }
  // To work as you don't intercept it.
  return net.fetch(req)
})

The document's code is perfect but in real it has tons of bug.

problems

1. losing blob data of req. If you post a file created by a input tag. you'll lose the most important part of the request🐶.(fixed in fix: properly stream uploadData in protocol.handle() #41052)
   
2. exception caused by web stream contains undefined data.
3. You cannot perceive redirection in net.fetch API. If you're loading a page you can't response the data of yyyy.html while rendering xxxx.html. You need to perceive the navigation and response with a object created by Response.redirect("yyyy.html").

cc: @codebytere @nornagon

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

notes: Add support to callback in protocol interceptor handler without argument to perform as if no interceptors.

[welcome]

💖 Thanks for opening this pull request! 💖

We use semantic commit messages to streamline the release process. Before your pull request can be merged, you should update your pull request title to start with a semantic prefix.

Examples of commit messages with semantic prefixes:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

Things that will help get your PR across the finish line:

• Follow the JavaScript, C++, and Python coding style.
• Run npm run lint locally to catch formatting errors earlier.
• Document any user-facing changes you've made following the documentation styleguide.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can.

[codebytere]

As this is an user-facing API change, we'll need to update API documentation as well as add tests to ensure coverage for this change.

[mrchaofan]

As this is a user-facing API change, we'll need to update API documentation as well as add tests to ensure coverage for this change.

Okay. I'll write some tests for it.

[mrchaofan]

@codebytere @nornagon I've add some test for protocol.interceptProtocol api. But It is a private api so I don't know how to write document for it. But It is ok to work with calling protocol.interceptHttpProtocol api.

protocol.interceptHttpProtocol('https', (req, callback) => {
    // a Electron.ProtocolResponse or undefined or null or {};
    const maybeSpecialRes = getSpecialRes(req); // null or {url, uploadData}
    // If maybeSpecialRes is not a Electron.ProtocolResponse then the behavior should perform like no interceptor.
    callback(maybeSpecialRes);
})

But the interceptHttpProtocol api forces you to send only http.But protocol.interceptProtocol has more exciting features.

protocol.interceptProtocol('https', (req, callback) => {
    if (/^https:\/\/docs\.qq\.com\/desktop($|\?|\/)/.test(req.url)) {
        // Map request to local file.
        callback({
            path: path.join(__dirname, 'index.html')
        })
        return
    }
    // Perform default http request behavior.
    callback();
});

[mrchaofan]

ElectronURLLoaderFactory can be used for protocol intercept and protocol register. There are much differences. If start loading was called by intercept, the receiver is ProxyingURLLoaderFactory, so you can call remote to trigger it. But if it was called by protocol register, you can't call remote to attempt to take the benefit of the default behavior, the receiver is its self, that will lead to death loop. We should treat intercept and register differently.
I'm totally wrong. 😂 The issue dialog made me feel socially dead.

[mrchaofan]

@codebytere @nornagon If you have time, please could you review my code?
I've done my changes. I think I'm back on the right way to support that you can call callback() to call the Remote created in the ElectronBrowserClient::WillCreateURLLoaderFactory only if you are intercepting a protocol. If the new protocol you registered you can't, you have to call callback function with argument.

I changed the ProxingURLLoaderFactory to treat intercept differently from register a new protocol and updated test files.

And I see a test of webview-spec.ts failed. I think it's irrelevant.

[Imperat]

Hi @mrchaofan
Thanks for this change 🙏

@codebytere @nornagon I've add some test for protocol.interceptProtocol api. But It is a private api so I don't know how to write document for it. But It is ok to work with calling protocol.interceptHttpProtocol api.

Please just made relevant changes inside https://github.com/electron/electron/tree/main/docs/api 👍

[mrchaofan]

@Imperat I've just updated the document and It seems electron.d.ts was automatically updated too.
@codebytere I think it is reasonable to do nothing in the protocol interception handler and just perform as if it hasn't been intercepted. But just for the interception. So I changes some codes to treat registration and interception differently.