@kabacorp/kaba-electron-rpc 7.0.1

package/README.md

@@ -0,0 +1,138 @@
+# kaba-electron-rpc
+
+Features:
+
+ - Supports RPC calls to/from the renderer or webview or a node child-process to the background process
+ - Supports methods which return:
+   - Sync values
+   - Async CBs
+   - Promises
+   - Readable streams
+   - Writable streams
+   - Duplex streams
+ - Permissions by examining the sender of the call
+ - Monitors renderer/webview lifetime to automatically release streams
+ - Optional timeout for async methods
+
+## Example usage
+
+In a shared `example-api-manifest.js`:
+
+```js
+module.exports = {
+  // simple method-types
+  readFile: 'async',
+  readFileSync: 'sync',
+  sayHello: 'promise',
+  createReadStream: 'readable',
+  createWriteStream: 'writable',
+  createDuplexStream: 'duplex'
+}
+```
+
+In the main electron process:
+
+```js
+var rpc = require('kaba-electron-rpc')
+var manifest = require('./example-api-manifest')
+var fs = require('fs')
+
+// export over the 'example-api' channel
+var api = rpc.exportAPI('example-api', manifest, {
+  // the exported API behaves like normal calls:
+  readFile: fs.readFile,
+  readFileSync: fs.readFileSync,
+  sayHello: () => return Promise.resolve('hello!'),
+  createReadStream: fs.createReadStream,
+  createWriteStream: /* ... */,
+  createDuplexStream: /* ... */
+})
+
+// log any errors
+api.on('error', console.log)
+```
+
+In the renderer or webview process:
+
+```js
+var rpc = require('kaba-electron-rpc')
+var manifest = require('./example-api-manifest')
+
+// import over the 'example-api' channel
+var api = rpc.importAPI('example-api', manifest, { timeout: 30e3 })
+
+// now use, as usual:
+api.readFileSync('/etc/hosts') // => '...'
+```
+
+## API
+
+### rpc.exportAPI(channelName, manifest, methods, [globalPermissionCheck])
+
+Methods will be called with a `this` set to the `event` object from [electron ipc](http://electron.atom.io/docs/api/ipc-main/#event-object).
+Don't touch `returnValue`.
+
+You can optionally specify a method for `globalPermissionCheck` with the following signature:
+
+```js
+function globalPermissionCheck (event, methodName, args) {
+  if (event.sender.getURL() != 'url-I-trust') return false
+  return true
+}
+```
+
+If `globalPermissionCheck` is specified, and does not return true, the method call will respond with a 'Denied' error.
+
+### rpc.importAPI(channelName, manifest [,options])
+
+ - `options.timeout` Number. Specify how long in ms that async methods wait before erroring. Set to `false` to disable timeout.
+ - `options.errors` Object. Provides custom error constructors.
+ - `options.wc` WebContents. The web-contents that is exporting the API. Use this when importing an API from a webContents into the main thread.
+ - `options.proc` ChildProcess. The child-process that is exporting the API. Use this when importing an API from a node child process into the main thread.
+
+## Readable Streams
+
+Readable streams in the clientside are given a `.close()` method.
+All serverside streams MUST implement `.close()` or `.destroy()`, either of which will be called.
+
+Stream methods can return a promise that resolves to a stream.
+
+## Buffers and ArrayBuffers
+
+Arguments and return values are massaged so that they are Buffers on the exporter's side, and ArrayBuffers on the importer side.
+
+## Custom Errors
+
+```js
+// shared code
+// =
+
+var manifest = {
+  testThrow: 'promise'
+}
+
+class MyCustomError extends Error {
+  constructor() {
+    super()
+    this.name = 'MyCustomError'
+    this.message = 'Custom error!'
+  }
+}
+
+// server
+// =
+
+rpc.exportAPI('error-api', manifest, {
+  testThrow() {
+    return Promise.reject(new MyCustomError())
+  }
+})
+
+// client
+// =
+
+var rpcClient = rpc.importAPI('error-api', manifest, {
+  errors: {MyCustomError} // pass in custom error constructors
+})
+rpcClient.testThrow().catch(console.log) // => MyCustomError
+```

package/index.js

@@ -0,0 +1,2 @@
+module.exports.exportAPI = require('./lib/export-api')
+module.exports.importAPI = require('./lib/import-api')

package/lib/export-api.js

@@ -0,0 +1,351 @@
+const EventEmitter = require("events");
+const {
+  IPCValueToValue,
+  valueToIPCValue,
+  isNodeProcess,
+  isRenderer,
+} = require("./util");
+
+const _ = require("lodash");
+
+module.exports = function (
+  channelName,
+  manifest,
+  methods,
+  globalPermissionCheck
+) {
+  var api = new EventEmitter();
+  var webcontentsStreams = {};
+
+  var channel;
+  if (isNodeProcess()) {
+    var mockedSender = new EventEmitter();
+    mockedSender.id = "main-process";
+    mockedSender.send = (channelName, msgType, requestId, ...args) => {
+      // console.log('export-api#send', {channelName, msgType, requestId, args})
+      process.send({ channelName, msgType, requestId, args });
+    };
+    channel = {
+      onMessage(cb) {
+        process.on("message", (msg) => {
+          if (msg.channelName !== channelName) return;
+          let mockedEvent = { sender: mockedSender };
+          // console.log('export-api#onMessage', msg)
+          cb(mockedEvent, msg.methodName, msg.requestId, ...msg.args);
+        });
+      },
+    };
+  } else if (isRenderer()) {
+    var { ipcRenderer } = require("electron");
+    channel = {
+      onMessage(cb) {
+        ipcRenderer.on(channelName, cb);
+      },
+    };
+  } else {
+    var { ipcMain } = require("electron");
+    channel = {
+      onMessage(cb) {
+        ipcMain.on(channelName, cb);
+      },
+    };
+  }
+
+  // wire up handler
+  channel.onMessage(async function (event, methodName, requestId, ...args) {
+    // console.log('received', channelName, methodName, requestId, ...args)
+    args = args.map(IPCValueToValue);
+
+    // watch for a navigation event
+    var hasNavigated = false;
+    function onDidNavigate() {
+      hasNavigated = true;
+    }
+    event.sender.on("did-navigate", onDidNavigate);
+
+    // helper to send
+    const send = function (
+      msgType,
+      err,
+      value,
+      keepListeningForDidNavigate = false
+    ) {
+      if (event.sender.isDestroyed && event.sender.isDestroyed()) return; // dont send response if destroyed
+      if (!keepListeningForDidNavigate)
+        event.sender.removeListener("did-navigate", onDidNavigate);
+      if (hasNavigated) return; // dont send response if the page changed
+
+      console.log("sending", channelName, msgType, requestId, err, value);
+      //
+      if (event.reply) {
+        var v = _.cloneDeep(value);
+        event.sender.send(channelName, msgType, requestId, err, v);
+        // event.reply(channelName, msgType, requestId, err, value);
+      } else if (event.sender && event.sender.send) {
+        var v = _.cloneDeep(value);
+        event.sender.send(channelName, msgType, requestId, err, v);
+        // event.sender.send(channelName, msgType, requestId, err, value);
+      }
+    };
+
+    // handle special methods
+    if (methodName == "stream-request-write") {
+      event.returnValue = true;
+      return streamRequestWrite(event.sender.id, requestId, args);
+    }
+    if (methodName == "stream-request-end") {
+      event.returnValue = true;
+      return streamRequestEnd(event.sender.id, requestId, args);
+    }
+    if (methodName == "stream-request-close") {
+      event.returnValue = true;
+      return streamRequestClose(event.sender.id, requestId, args);
+    }
+
+    // look up the method called
+    var type = manifest[methodName];
+    var method = methods[methodName];
+    if (!type || !method) {
+      api.emit(
+        "error",
+        new Error(`Method not found: "${methodName}"`),
+        arguments
+      );
+      return;
+    }
+
+    // global permission check
+    if (
+      globalPermissionCheck &&
+      !globalPermissionCheck(event, methodName, args)
+    ) {
+      // repond according to method type
+      if (type == "async" || type == "promise") {
+        send("async-reply", "Method Access Denied");
+      } else {
+        event.returnValue = { error: "Method Access Denied" };
+      }
+      return;
+    }
+
+    // run method by type
+    if (type == "sync") {
+      // call sync
+      try {
+        event.returnValue = {
+          success: valueToIPCValue(method.apply(event, args)),
+        };
+      } catch (e) {
+        event.returnValue = { error: e.message };
+      }
+      return;
+    }
+    if (type == "async") {
+      // create a reply cb
+      const replyCb = (err, value) => {
+        if (err) err = errorObject(err);
+        send("async-reply", err, valueToIPCValue(value));
+      };
+      args.push(replyCb);
+
+      // call async
+      method.apply(event, args);
+      return;
+    }
+    if (type == "promise") {
+      // call promise
+      let p;
+      try {
+        p = method.apply(event, args);
+        if (typeof p === "undefined") p = Promise.resolve();
+        if (typeof p.then === "undefined") p = Promise.resolve(p);
+      } catch (e) {
+        p = Promise.reject(errorObject(e));
+      }
+
+      // handle response
+      p.then(
+        (value) => send("async-reply", null, valueToIPCValue(value)),
+        (error) => send("async-reply", errorObject(error))
+      );
+      return;
+    }
+
+    var streamTypes = {
+      readable: createReadableEvents,
+      writable: createWritableEvents,
+      duplex: createDuplexEvents,
+    };
+
+    if (streamTypes[type]) {
+      return await handleStream(
+        event,
+        method,
+        requestId,
+        args,
+        streamTypes[type],
+        send
+      );
+    }
+
+    api.emit(
+      "error",
+      new Error(`Invalid method type "${type}" for "${methodName}"`),
+      arguments
+    );
+  });
+
+  async function handleStream(
+    event,
+    method,
+    requestId,
+    args,
+    createStreamEvents,
+    send
+  ) {
+    // call duplex
+    let stream;
+    let error;
+    try {
+      stream = method.apply(event, args);
+      if (!stream) {
+        send("stream-error", "Empty stream response");
+        return;
+      }
+    } catch (e) {
+      send("stream-error", "" + e);
+      return;
+    }
+
+    // handle promises
+    if (stream.then) {
+      try {
+        stream = await stream; // wait for it
+      } catch (e) {
+        send("stream-error", "" + e);
+        return;
+      }
+    }
+
+    trackWebcontentsStreams(event.sender, requestId, stream);
+    var events = createStreamEvents(event, stream, requestId, send);
+    hookUpEventsAndUnregister(stream, events);
+
+    // done
+    event.returnValue = { success: true };
+    return;
+  }
+
+  function hookUpEventsAndUnregister(stream, events) {
+    Object.keys(events).forEach((key) => stream.on(key, events[key]));
+    stream.unregisterEvents = () => {
+      Object.keys(events).forEach((key) =>
+        stream.removeListener(key, events[key])
+      );
+    };
+  }
+
+  function createReadableEvents(event, stream, requestId, send) {
+    return {
+      data: (chunk) =>
+        send("stream-data", valueToIPCValue(chunk), undefined, true),
+      close: () => send("stream-close"),
+      error: (err) => {
+        stream.unregisterEvents();
+        send("stream-error", err ? err.message : "");
+      },
+      end: () => {
+        stream.unregisterEvents(); // TODO does calling this in 'end' mean that 'close' will never be sent?
+        send("stream-end");
+        webcontentsStreams[event.sender.id][requestId] = null;
+      },
+    };
+  }
+
+  function createWritableEvents(event, stream, requestId, send) {
+    return {
+      drain: () => send("stream-drain", undefined, undefined, true),
+      close: () => send("stream-close"),
+      error: (err) => {
+        stream.unregisterEvents();
+        send("stream-error", err ? err.message : "");
+      },
+      finish: () => {
+        stream.unregisterEvents();
+        send("stream-finish");
+        webcontentsStreams[event.sender.id][requestId] = null;
+      },
+    };
+  }
+
+  function createDuplexEvents(event, stream, requestId, send) {
+    return Object.assign(
+      createWritableEvents(event, stream, requestId, send),
+      createReadableEvents(event, stream, requestId, send)
+    );
+  }
+
+  // special methods
+  function trackWebcontentsStreams(webcontents, requestId, stream) {
+    // track vs. sender's lifecycle
+    if (!webcontentsStreams[webcontents.id]) {
+      webcontentsStreams[webcontents.id] = {};
+      // listen for webcontent close event
+      webcontents.once(
+        "did-navigate",
+        closeAllWebcontentsStreams(webcontents.id)
+      );
+      webcontents.once("destroyed", closeAllWebcontentsStreams(webcontents.id));
+    }
+    webcontentsStreams[webcontents.id][requestId] = stream;
+  }
+
+  function streamRequestWrite(webcontentsId, requestId, args) {
+    var stream = webcontentsStreams[webcontentsId][requestId];
+
+    if (stream && typeof stream.write == "function") {
+      stream.write(...args);
+    }
+  }
+  function streamRequestEnd(webcontentsId, requestId, args) {
+    var stream = webcontentsStreams[webcontentsId][requestId];
+    if (stream && typeof stream.end == "function") stream.end(...args);
+  }
+  function streamRequestClose(webcontentsId, requestId, args) {
+    var stream = webcontentsStreams[webcontentsId][requestId];
+    if (!stream) return;
+    // try .close
+    if (typeof stream.close == "function") stream.close(...args);
+    // hmm, try .destroy
+    else if (typeof stream.destroy == "function") stream.destroy(...args);
+    // oye, last shot: end()
+    else if (typeof stream.end == "function") stream.end(...args);
+  }
+
+  // helpers
+  function closeAllWebcontentsStreams(webcontentsId) {
+    return (e) => {
+      if (!webcontentsStreams[webcontentsId]) return;
+
+      // close all of the open streams
+      for (var requestId in webcontentsStreams[webcontentsId]) {
+        if (webcontentsStreams[webcontentsId][requestId]) {
+          webcontentsStreams[webcontentsId][requestId].unregisterEvents();
+          streamRequestClose(webcontentsId, requestId, []);
+        }
+      }
+
+      // stop tracking
+      delete webcontentsStreams[webcontentsId];
+    };
+  }
+
+  return api;
+};
+
+function errorObject(error) {
+  var copy = Object.assign({}, error);
+  copy.message = error.message || error.toString();
+  if (error.name) copy.name = error.name;
+  return copy;
+}