feat(plugins/scripts-runner): introduce exec command to run scripts

This commit introduces a new feature that enables users to run (migration) scripts. Similar to deployment hooks, scripts are functions that may perform operations on newly deployed Smart Contracts. Therefore a script needs to export a function that has access to some dependencies: ``` // scripts/001-some-script.js module.exports = async ({contracts, web3, logger}) => { ... }; ``` Where `contracts` is a map of newly deployed Smart Contract instances, `web3` a blockchain connector instance and `logger` Embark's logger instance. Script functions can but don't have to be `async`. To execute such a script users use the newly introduced `exec` command: ``` $ embark exec development scripts/001-some-script.js ``` In the example above, `development` defines the environment in which Smart Contracts are being deployed to as well as where tracking data is stored. Alternativey, users can also provide a directory in which case Embark will try to execute every script living inside of it: ``` $ embark exec development scripts ``` Scripts can fail and therefore emit an error accordingly. When this happens, Embark will abort the script execution (in case multiple are scheduled to run) and informs the user about the original error: ``` .. 001_foo.js running.... Script '001_foo.js' failed to execute. Original error: Error: Some error ``` It's recommended for scripts to emit proper instances of `Error`. (Migration) scripts can be tracked as well but there are a couple of rules to be aware of: - Generally, tracking all scripts that have been executed by default is not a good thing because some scripts might be one-off operations. - OTOH, there might be scripts that should always be tracked by default - Therefore, we introduce a dedicated `migrations` directory in which scripts live that should be tracked by default - Any other scripts that does not live in the specified `migrations` directory will not be tracked **unless** - The new `--track` option was provided For more information see: https://notes.status.im/h8XwB7xkR7GKnfNh6OnPMQ
embarklabs · Feb 12, 2020 · 40c3d98 · 40c3d98
1 parent 0f59e0c
commit 40c3d98
Show file tree

Hide file tree

Showing 22 changed files with 927 additions and 32 deletions.
diff --git a/packages/core/core/constants.json b/packages/core/core/constants.json
@@ -108,5 +108,6 @@
   },
   "environments": {
     "development": "development"
-  }
-}
+  },
+  "defaultMigrationsDir": "migrations"
+}
diff --git a/packages/core/core/src/config.ts b/packages/core/core/src/config.ts
@@ -27,7 +27,7 @@ import { readJsonSync } from 'fs-extra';
 const cloneDeep = require('lodash.clonedeep');
 const { replaceZeroAddressShorthand } = AddressUtils;
 
-import { getBlockchainDefaults, getContractDefaults } from './configDefaults';
+import { getBlockchainDefaults, getContractDefaults, embarkConfigDefaults } from './configDefaults';
 
 const constants = readJsonSync(path.join(__dirname, '../constants.json'));
 
@@ -45,6 +45,7 @@ export interface EmbarkConfig {
   generationDir?: string;
   plugins?: any;
   buildDir?: string;
+  migrations: string;
 }
 
 export class Config {
@@ -83,7 +84,7 @@ export class Config {
 
   events: Events;
 
-  embarkConfig: any = {};
+  embarkConfig: EmbarkConfig = embarkConfigDefaults;
 
   context: any;
 
@@ -629,17 +630,7 @@ export class Config {
   }
 
   loadEmbarkConfigFile() {
-    const configObject = {
-      options: {
-        solc: {
-          "optimize": true,
-          "optimize-runs": 200
-        }
-      },
-      generationDir: "embarkArtifacts"
-    };
-
-    this.embarkConfig = recursiveMerge(configObject, this.embarkConfig);
+    this.embarkConfig = recursiveMerge(embarkConfigDefaults, this.embarkConfig);
 
     const contracts = this.embarkConfig.contracts;
     // determine contract 'root' directories

diff --git a/packages/core/core/src/configDefaults.ts b/packages/core/core/src/configDefaults.ts
@@ -4,6 +4,22 @@ import { join } from "path";
 
 const constants = readJsonSync(join(__dirname, '../constants.json'));
 
+export const embarkConfigDefaults = {
+  contracts: [],
+  config: '',
+  migrations: 'migrations',
+  versions: {
+    solc: "0.6.1"
+  },
+  options: {
+    solc: {
+      "optimize": true,
+      "optimize-runs": 200
+    }
+  },
+  generationDir: "embarkArtifacts"
+};
+
 export function getBlockchainDefaults(env) {
   const defaults = {
     clientConfig: {

diff --git a/packages/core/core/src/index.ts b/packages/core/core/src/index.ts
@@ -91,6 +91,9 @@ export interface Configuration {
       cert: string;
     };
   };
+  contractsConfig: {
+    tracking?: boolean | string;
+  };
   plugins: EmbarkPlugins;
   reloadConfig(): void;
 }

diff --git a/packages/embark/src/cmd/cmd.js b/packages/embark/src/cmd/cmd.js
@@ -15,6 +15,7 @@ class Cmd {
     this.demo();
     this.build();
     this.run();
+    this.exec();
     this.console();
     this.blockchain();
     this.simulator();
@@ -174,6 +175,30 @@ class Cmd {
       });
   }
 
+  exec() {
+    program
+      .command('exec [environment] [script|directory]')
+      .option('-t, --track', __('Force tracking of migration script', false))
+      .description(__("Executes specified scripts or all scripts in 'directory'"))
+      .action((env, target, options) => {
+        embark.exec({
+          env,
+          target,
+          forceTracking: options.track
+        }, (err) => {
+          if (err) {
+            console.error(err.message ? err.message : err);
+            process.exit(1);
+          }
+          console.log('Done.');
+          // TODO(pascal): Ideally this shouldn't be needed.
+          // Seems like there's a pending child process at this point that needs
+          // to be stopped.
+          process.exit(0);
+        });
+      });
+  }
+
   console() {
     program
       .command('console [environment]')

diff --git a/packages/embark/src/cmd/cmd_controller.js b/packages/embark/src/cmd/cmd_controller.js
@@ -352,6 +352,44 @@ class EmbarkController {
     });
   }
 
+  exec(options, callback) {
+
+    const engine = new Engine({
+      env: options.env,
+      embarkConfig: options.embarkConfig || 'embark.json'
+    });
+
+    engine.init({}, () => {
+      engine.registerModuleGroup("coreComponents", {
+        disableServiceMonitor: true
+      });
+      engine.registerModuleGroup("stackComponents");
+      engine.registerModuleGroup("blockchain");
+      engine.registerModuleGroup("compiler");
+      engine.registerModuleGroup("contracts");
+      engine.registerModulePackage('embark-deploy-tracker', {
+        plugins: engine.plugins
+      });
+      engine.registerModulePackage('embark-scripts-runner');
+
+      engine.startEngine(async (err) => {
+        if (err) {
+          return callback(err);
+        }
+        try {
+          await engine.events.request2("blockchain:node:start", engine.config.blockchainConfig);
+          const [contractsList, contractDependencies] = await compileSmartContracts(engine);
+          await engine.events.request2("deployment:contracts:deploy", contractsList, contractDependencies);
+          await engine.events.request2('scripts-runner:initialize');
+          await engine.events.request2('scripts-runner:execute', options.target, options.forceTracking);
+        } catch (err) {
+          return callback(err);
+        }
+        callback();
+      });
+    });
+  }
+
   console(options) {
     this.context = options.context || [constants.contexts.run, constants.contexts.console];
     const REPL = require('./dashboard/repl.js');

diff --git a/packages/plugins/scripts-runner/README.md b/packages/plugins/scripts-runner/README.md
@@ -0,0 +1,10 @@
+embark-scripts-runner
+==========================
+
+> Embark Scripts Runner
+
+Plugin to run migration scripts for Smart Contract Deployment
+
+Visit [embark.status.im](https://embark.status.im/) to get started with
+[Embark](https://github.com/embarklabs/embark).
+
diff --git a/packages/plugins/scripts-runner/package.json b/packages/plugins/scripts-runner/package.json
@@ -0,0 +1,78 @@
+{
+  "name": "embark-scripts-runner",
+  "version": "5.1.0",
+  "description": "Embark Scripts Runner",
+  "repository": {
+    "directory": "packages/plugins/scripts-runner",
+    "type": "git",
+    "url": "https://github.com/embarklabs/embark/"
+  },
+  "author": "Iuri Matias <iuri.matias@gmail.com>",
+  "license": "MIT",
+  "bugs": "https://github.com/embarklabs/embark/issues",
+  "keywords": [],
+  "files": [
+    "dist/"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "embark-collective": {
+    "build:node": true,
+    "typecheck": true
+  },
+  "scripts": {
+    "_build": "npm run solo -- build",
+    "_typecheck": "npm run solo -- typecheck",
+    "ci": "npm run qa",
+    "clean": "npm run reset",
+    "lint": "npm-run-all lint:*",
+    "lint:ts": "tslint -c tslint.json \"src/**/*.ts\"",
+    "qa": "npm-run-all lint _typecheck _build test",
+    "reset": "npx rimraf dist embark-*.tgz package",
+    "solo": "embark-solo",
+    "test": "jest"
+  },
+  "dependencies": {
+    "async": "2.6.1",
+    "@babel/runtime-corejs3": "7.7.4",
+    "core-js-pure": "3.6.4",
+    "embark-core": "^5.2.0-nightly.1",
+    "embark-i18n": "^5.1.1",
+    "embark-logger": "^5.1.2-nightly.0",
+    "embark-utils": "^5.2.0-nightly.1",
+    "fs-extra": "8.1.0",
+    "web3": "1.2.4"
+  },
+  "devDependencies": {
+    "@babel/core": "7.7.4",
+    "@types/node": "^10.5.3",
+    "babel-jest": "24.9.0",
+    "embark-solo": "^5.1.1-nightly.2",
+    "embark-testing": "^5.1.0",
+    "jest": "24.9.0",
+    "npm-run-all": "4.1.5",
+    "rimraf": "3.0.0",
+    "tmp-promise": "1.1.0"
+  },
+  "engines": {
+    "node": ">=10.17.0",
+    "npm": ">=6.11.3",
+    "yarn": ">=1.19.1"
+  },
+  "jest": {
+    "collectCoverage": true,
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/test/**/*.js"
+    ],
+    "transform": {
+      "\\.(js|ts)$": [
+        "babel-jest",
+        {
+          "rootMode": "upward"
+        }
+      ]
+    }
+  }
+}
+
diff --git a/packages/plugins/scripts-runner/src/error.ts b/packages/plugins/scripts-runner/src/error.ts
@@ -0,0 +1,60 @@
+import path from 'path';
+import { Stats } from 'fs';
+
+enum FileType {
+  SymbolicLink = 'symbolic link',
+  Socket = 'socket',
+  Unknown = 'unknown'
+}
+
+export class InitializationError extends Error {
+
+  name = 'InitalizationError';
+
+  constructor(public innerError: Error) {
+    super();
+    this.message = `Failed to initalize tracking file: Orignal Error: ${innerError}`;
+  }
+}
+
+export class UnsupportedTargetError extends Error {
+
+  name = 'UnsupportedTargetError';
+
+  constructor(public stats: Stats) {
+    super();
+    // We can't access `this` before `super()` is called so we have to
+    // set `this.message` after that to get a dedicated error message.
+    this.setMessage();
+  }
+
+  private setMessage() {
+    let ftype = FileType.Unknown;
+    if (this.stats.isSymbolicLink()) {
+      ftype = FileType.SymbolicLink;
+    } else if (this.stats.isSocket()) {
+      ftype = FileType.Socket;
+    }
+    this.message = `Script execution target not supported. Expected file path or directory, got ${ftype} type.`;
+  }
+}
+
+export class ScriptExecutionError extends Error {
+
+  name = 'ScriptExecutionError';
+
+  constructor(public target: string, public innerError: Error) {
+    super();
+    this.message = `Script '${path.basename(target)}' failed to execute. Original error: ${innerError.stack}`;
+  }
+}
+
+export class ScriptTrackingError extends Error {
+
+  name = 'ScriptTrackingError';
+
+  constructor(public innerError: Error) {
+    super();
+    this.message = `Couldn't track script due execption. Original error: ${innerError.stack}`;
+  }
+}