Commit 55d6a16f authored by Amaury Martiny's avatar Amaury Martiny
Browse files

Add readme for parity-electron

parent c1d2e5ae
Pipeline #44251 canceled with stages
......@@ -37,18 +37,19 @@ function createWindow () {
// Set options for @parity/electron
parityElectron({
cli,
logger: namespace => log => Pino({ name: namespace }).info(log),
parityChannel: parity.channel
logger: namespace => log => Pino({ name: namespace }).info(log)
});
// Look if Parity is installed
getParityPath()
.catch(() =>
// Install parity if not present
fetchParity(mainWindow, progress =>
// Notify the renderers on download progress
mainWindow.webContents.send('parity-download-progress', progress)
)
fetchParity(mainWindow, {
onProgress: progress =>
// Notify the renderers on download progress
mainWindow.webContents.send('parity-download-progress', progress),
parityChannel: parity.channel
})
)
.then(() =>
// Run parity when installed
......
# @parity/electron
Control the Parity client from electron.
## Getting Started
```bash
yarn add @parity/electron
```
## Usage
```javascript
import parityElectron, { isParityRunning } from '@parity/electron';
// Optional: override default options
parityElectron({
cli: myOwnCliObject,
logger: myCustomLoggerFunction,
parityChannel: 'nightly'
})
isParityRunning()
.then(() => ...);
```
## API
#### `parityElectron(options: Object)`
If you don't want to override the default options, there's no need to call this function. Here `options` can have the following fields:
| Option | Default Value | Description |
| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options.cli` | `{}` | An object where key/values are --flags passed to the binary. The `cli` object returned by `yargs` or [`commander.js`](https://github.com/tj/commander.js/) would fit here. |
| `options.logger` | `require('debug')` | A function with the same signature as [`debug`](https://github.com/visionmedia/debug). All logs inside `@parity/electron` will then be logged by this function. |
#### `fetchParity(mainWindow: BrowserWindow, options: Object): Promise<String>`
Downloads Parity, saves it to Electron's `userData` folder, and returns the path to the downloaded binary once finished.
| Option | Type | Description |
| ----------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `mainWindow` | [BrowserWindow](https://github.com/electron/electron/blob/master/docs/api/browser-window.md) | The Electron BrowserWindow in which to download the binary. |
| `options.onProgress` | `Function` | Optional callback that receives a number between 0 and 1 representing the progress of the current download. |
| `options.parityChannel` | `String` | Can be `stable`, `beta` or `nightly`. If downloading Parity is needed, determines which version of Parity to download. Defaults to `beta`. |
#### `getParityPath(): Promise<String>`
Returns the path to Parity. It checks (in this order) if Parity is in `$PATH`, in a standard OS location or in Electron's `userData` folder, and returns the first instance of Parity found. The Promise rejects if no Parity instance is found.
#### `defaultParityPath(): Promise<String>`
Returns the path to the Parity path inside Electron's `userData` folder, even if that binary doesn't exist. It's the default download location for [`fetchParity`](#fetchParitymainWindow-BrowserWindow-options-Object-PromiseltStringgt0).
#### `isParityRunning(): Promise<Boolean>`
Resolves to `true` if Parity is currently running, or to `false` if not.
#### `runParity(onParityError: Function): Promise<Null>`
Spawns a child process to run Parity. If some `cli` flags are passed into the options in `parityElectron`, then those flags will be passed down to Parity itself.
| Option | Type | Description |
| --------------- | ---------- | ------------------------------------------------------------------ |
| `onParityError` | `Function` | Callback with `error` as argument when Parity encounters an error. |
#### `killParity(): Promise<Null>`
If a Parity process has been spawned with [`runParity`](#runParityonParityError-Function-PromiseltNullgt), then it kills this process. The Promise resolves instantly, there's no guarantee that Parity has been cleanly killed.
#### `deleteParity(): Promise<Null>`
If Parity has been downloaded to Electron's `userData` folder, then it deletes the Parity binary file from that folder.
#### `signerNewToken(): Promise<String>`
Runs `parity signer new-token` and resolves with a new secure token to be used in a dapp. Rejects if no token could be extracted.
......@@ -13,7 +13,6 @@ import retry from 'async-retry';
import { defaultParityPath, getParityPath } from './getParityPath';
import logger from './utils/logger';
import parityChannel from './utils/parityChannel';
const checksum = promisify(cs.file);
const fsChmod = promisify(fs.chmod);
......@@ -65,7 +64,12 @@ export const deleteParity = async () => {
};
// Fetch parity from https://vanity-service.parity.io/parity-binaries
export const fetchParity = (mainWindow, onProgress) => {
export const fetchParity = (
mainWindow,
{ onProgress, parityChannel } = {
parityChannel: 'beta'
}
) => {
try {
return retry(
async (_, attempt) => {
......@@ -77,7 +81,7 @@ export const fetchParity = (mainWindow, onProgress) => {
await deleteParity();
// Fetch the metadata of the correct version of parity
const metadataUrl = `${VANITY_URL}?version=${parityChannel()}&os=${getOs()}&architecture=${getArch()}`;
const metadataUrl = `${VANITY_URL}?version=${parityChannel}&os=${getOs()}&architecture=${getArch()}`;
logger()('@parity/electron:main')(`Downloading from ${metadataUrl}.`);
const { data } = await axios.get(metadataUrl);
......
......@@ -5,7 +5,6 @@
import { setCli } from './utils/cli';
import { setLogger } from './utils/logger';
import { setParityChannel } from './utils/parityChannel';
export * from './getParityPath';
export * from './fetchParity';
......@@ -22,8 +21,4 @@ export default opts => {
if (opts.logger) {
setLogger(opts.logger);
}
if (opts.parityChannel) {
setParityChannel(opts.parityChannel);
}
};
// Copyright 2015-2018 Parity Technologies (UK) Ltd.
// This file is part of Parity.
//
// SPDX-License-Identifier: BSD-3-Clause
let parityChannel = 'beta'; // Fetch beta by default
/**
* Set custom parity channel.
*
* @param {*} channel
*/
export const setParityChannel = channel => {
parityChannel = channel;
};
export default () => parityChannel;
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment