0. summary

This package aim to add a feature of communication between BrowseWindow and Webview for batch job.

You can inject the script into the web, with less risk of XXS attack (Of course, don't exposed the object to global window, that would cause XXS).

1. notice

not support site for SCP that not allow eval, Function, setTimeout, ... which would cause Exception of unsafe-eval (for example: github)

2. usage example

this package contain & , Webview side is recognize as client, and BrowseWindow side is server.

Webview side

just add this to your preload script

import 'electron-webview-rpc-framework/client'

or just use that script to be a preload script

BrowseWindow side

import the framework

import {remote} from 'electron';
import {Manager} from 'electron-webview-rpc-framework';
let options = {
    devTools: true,
    useragent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.190 Safari/537.36',
    preload: 'file://' + remote.app.getAppPath() + '/client.js',
};
let manager = new Manager(options);

after that, you can define your object

let remoteObjCreateScript=`
(function(){
  let obj={};
  obj.remoteDetect=function(text){
    console.log(text);
    obj.call("onDetect",window.location.href);//call the host object function
    //a better way to use call method is use obj['call'] when you want to pack with tools
  }
  obj.syncDetect=function(){ //define a sync function, must return Promise
    console.log(text);
    return obj.request('ping') //request to get result on the host side sync
      .then(res=>console.log(res))
      .then(_=> window.location.href)
    },3000);
  }
  return obj;
})();
`;
let hostObject={};
hostObject.onDetect=function(text) {
    console.log(text)
};
let promise1 = manager.register(
    hostObject,//object to bind
    tagName,//to identify the webview environment
    src,//the init the webview environment
    remoteObjCreateScript,//script of remote obj
);
hostObject.detect=function(text) {
    manager.ensure(hostObject)//same as promise1
    .then(id => {
        console.log(id, 'detect', text);
        manager.call(id, 'remoteDetect', text);//call the remote object function
    })
};
hostObject.detect("try");
hostObject.ping = function () { //define a sync function to wait remote object to call
    return Promise.resolve('pong')
};
hostObject.tryOnSyncWay=function() {
    manager.ensure(hostObject).then(id => {
        console.log(id, 'tryOnSyncWay');
        manager.request(id, 'syncDetect')//sync call the remote object function
                .then(res => console.log(res))
                .catch(e => console.log(e))
    })
};
hostObject.tryOnSyncWay();

3. conception

• [host object] BrowseWindow side object, it contains a [remote object]
• [remote object] Webview side object, it contains a [host object]
• [webview pool] a pool storage a batch of webview to limit usage of memory.
• [virtual webview] there would be many [host object] wants a webview to call its [remote object] , but webview is so rare. they need to share the same environment as if they has its own webview, and a [tagName] to specify the [real webview]
• [virtual host] you can exec remote function without create host object
• [watcher] to auto manage the register state and unregister state

4. apis

4.1. Manager

4.1.1. constructor

Manager constructor(options);

options = {
    /**
     * <backgroundMode> will generate invisible webview limit by <webviewPoolMaxLength>,
     * and will release webview after not <client object> host in.
     * Other wise you need manual register webview by yourself,
     * and will reject to generate <client object> if not src in webview pools.
     */
    backgroundMode: true,
    /**
     * auto open devTools, if you want to debug, set this true
     */
    devTools: false,
    /**
     * no use if not in backgroundMode, define the pool size of webviews
     */
    webviewPoolMaxLength: 5,
    /**
     * <preload> is the path use to <generate webview>.
     */
    preload: '',
    /**
     * <useragent> is the useragent of <generate webview>.
     */
    useragent: '',
    /**
     * set this params > 0 to enable to throw timeout error
     */
    syncTimeout: 0,
};

4.1.2. register

Promise register(object object, string tagName, string src, string script);

will auto unregister object before register

4.1.3. unregister

void register(int tagName);

4.1.3. ensure

Promise ensure(object object);

to let the code write easier

4.1.5. registerWebview

boolean registerWebview(Electron.WebviewTag webview, string tagName);

4.1.6. call

boolean call(int id, string method, ...args);

4.1.7. request

Promise request(int id, string method, ...args);

5. todo

find a way to write remote object easier