From 0b5e4f2dd7956946c98f4b5d8c3874d70f444e13 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 30 Nov 2018 23:01:09 +0000 Subject: [PATCH] Documentation updates for node-red and runtime modules --- Gruntfile.js | 9 +- .../@node-red/editor-api/lib/index.js | 5 +- .../@node-red/registry/lib/loader.js | 6 +- .../@node-red/runtime/lib/api/comms.js | 11 +- .../@node-red/runtime/lib/api/context.js | 6 +- .../@node-red/runtime/lib/api/flows.js | 16 +-- .../@node-red/runtime/lib/api/index.js | 29 +---- .../@node-red/runtime/lib/api/library.js | 8 +- .../@node-red/runtime/lib/api/nodes.js | 28 ++--- .../@node-red/runtime/lib/api/projects.js | 62 +++++------ .../@node-red/runtime/lib/api/settings.js | 16 +-- .../@node-red/runtime/lib/index.js | 105 +++++++++++++++--- .../localfilesystem/projects/Project.js | 7 +- .../projects/defaultFileSet.js | 8 +- .../localfilesystem/projects/git/index.js | 5 +- .../storage/localfilesystem/projects/index.js | 7 +- .../localfilesystem/projects/ssh/index.js | 7 +- .../localfilesystem/projects/ssh/keygen.js | 9 +- packages/node_modules/node-red/lib/red.js | 102 ++++++++++------- 19 files changed, 256 insertions(+), 190 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index 317cb7eba..ee49ae9eb 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -430,7 +430,11 @@ module.exports = function(grunt) { }, jsdoc : { runtimeAPI: { - src: 'packages/node_modules/@node-red/runtime/lib/api/*.js', + src: [ + 'packages/node_modules/node-red/lib/red.js', + 'packages/node_modules/@node-red/runtime/lib/index.js', + 'packages/node_modules/@node-red/runtime/lib/api/*.js', + ], options: { destination: 'docs', configure: './jsdoc.json' @@ -449,7 +453,8 @@ module.exports = function(grunt) { options: { separators: true }, - src: 'packages/node_modules/@node-red/runtime/lib/api/*.js', + src: ['packages/node_modules/@node-red/runtime/lib/index.js', + 'packages/node_modules/@node-red/runtime/lib/api/*.js'], dest: 'packages/node_modules/@node-red/runtime/docs/api.md' }, nodeREDUtil: { diff --git a/packages/node_modules/@node-red/editor-api/lib/index.js b/packages/node_modules/@node-red/editor-api/lib/index.js index 51fd1079c..3450eaafb 100644 --- a/packages/node_modules/@node-red/editor-api/lib/index.js +++ b/packages/node_modules/@node-red/editor-api/lib/index.js @@ -28,7 +28,7 @@ var adminApp; var server; var editor; -function init(_server,settings,storage,runtimeAPI) { +function init(settings,_server,storage,runtimeAPI) { server = _server; if (settings.httpAdminRoot !== false) { adminApp = express(); @@ -100,6 +100,5 @@ module.exports = { auth: { needsPermission: auth.needsPermission }, - get adminApp() { return adminApp; }, - get server() { return server; } + get adminApp() { return adminApp; } }; diff --git a/packages/node_modules/@node-red/registry/lib/loader.js b/packages/node_modules/@node-red/registry/lib/loader.js index 7f737e3d5..901a7fba5 100644 --- a/packages/node_modules/@node-red/registry/lib/loader.js +++ b/packages/node_modules/@node-red/registry/lib/loader.js @@ -98,7 +98,9 @@ function createNodeApi(node) { register: function(type) { return runtime.library.register(node.id,type); } - } + }, + httpNode: runtime.nodeApp, + server: runtime.server } copyObjectProperties(runtime.nodes,red.nodes,["createNode","getNode","eachNode","addCredentials","getCredentials","deleteCredentials" ]); red.nodes.registerType = function(type,constructor,opts) { @@ -109,8 +111,6 @@ function createNodeApi(node) { if (runtime.adminApi) { red.auth = runtime.adminApi.auth; red.httpAdmin = runtime.adminApi.adminApp; - red.httpNode = runtime.nodeApp; - red.server = runtime.server; } else { //TODO: runtime.adminApi is always stubbed if not enabled, so this block // is unused - but may be needed for the unit tests diff --git a/packages/node_modules/@node-red/runtime/lib/api/comms.js b/packages/node_modules/@node-red/runtime/lib/api/comms.js index 7713fd3dc..079f75c14 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/comms.js +++ b/packages/node_modules/@node-red/runtime/lib/api/comms.js @@ -15,7 +15,8 @@ **/ /** - * @namespace RED.comms + * This is the comms subsystem of the runtime. + * @mixin @node-red/runtime_comms */ /** @@ -89,7 +90,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {CommsConnection} opts.client - the client connection * @return {Promise} - resolves when complete - * @memberof RED.comms + * @memberof @node-red/runtime_comms */ addConnection: function(opts) { connections.push(opts.client); @@ -102,7 +103,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {CommsConnection} opts.client - the client connection * @return {Promise} - resolves when complete - * @memberof RED.comms + * @memberof @node-red/runtime_comms */ removeConnection: function(opts) { for (var i=0;i} - resolves when complete - * @memberof RED.comms + * @memberof @node-red/runtime_comms */ subscribe: function(opts) { var re = new RegExp("^"+opts.topic.replace(/([\[\]\?\(\)\\\\$\^\*\.|])/g,"\\$1").replace(/\+/g,"[^/]+").replace(/\/#$/,"(\/.*)?")+"$"); @@ -142,7 +143,7 @@ var api = module.exports = { * @param {CommsConnection} opts.client - the client connection * @param {String} opts.topic - the topic to unsubscribe from * @return {Promise} - resolves when complete - * @memberof RED.comms + * @memberof @node-red/runtime_comms */ unsubscribe: function(opts) {} }; diff --git a/packages/node_modules/@node-red/runtime/lib/api/context.js b/packages/node_modules/@node-red/runtime/lib/api/context.js index cbe665e53..0b2fefcc9 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/context.js +++ b/packages/node_modules/@node-red/runtime/lib/api/context.js @@ -15,7 +15,7 @@ **/ /** - * @namespace RED.context + * @mixin @node-red/runtime_context */ var runtime; @@ -69,7 +69,7 @@ var api = module.exports = { * @param {String} opts.key - the context key * @return {Promise} - the node information - * @memberof RED.context + * @memberof @node-red/runtime_context */ getValue: function(opts) { return new Promise(function(resolve,reject) { @@ -163,7 +163,7 @@ var api = module.exports = { * @param {String} opts.key - the context key * @return {Promise} - the node information - * @memberof RED.context + * @memberof @node-red/runtime_context */ delete: function(opts) { return new Promise(function(resolve,reject) { diff --git a/packages/node_modules/@node-red/runtime/lib/api/flows.js b/packages/node_modules/@node-red/runtime/lib/api/flows.js index a96fdd9a3..735e295fc 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/flows.js +++ b/packages/node_modules/@node-red/runtime/lib/api/flows.js @@ -15,7 +15,7 @@ **/ /** - * @namespace RED.flows + * @mixin @node-red/runtime_flows */ /** @@ -44,7 +44,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the active flow configuration - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ getFlows: function(opts) { return new Promise(function(resolve,reject) { @@ -57,7 +57,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the active flow configuration - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ setFlows: function(opts) { return new Promise(function(resolve,reject) { @@ -99,7 +99,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {Object} opts.flow - the flow to add * @return {Promise} - the id of the added flow - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ addFlow: function(opts) { return new Promise(function(resolve,reject) { @@ -123,7 +123,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {Object} opts.id - the id of the flow to retrieve * @return {Promise} - the active flow configuration - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ getFlow: function(opts) { return new Promise(function (resolve,reject) { @@ -148,7 +148,7 @@ var api = module.exports = { * @param {Object} opts.id - the id of the flow to update * @param {Object} opts.flow - the flow configuration * @return {Promise} - the id of the updated flow - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ updateFlow: function(opts) { return new Promise(function (resolve,reject) { @@ -185,7 +185,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {Object} opts.id - the id of the flow to delete * @return {Promise} - resolves if successful - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ deleteFlow: function(opts) { return new Promise(function (resolve,reject) { @@ -222,7 +222,7 @@ var api = module.exports = { * @param {String} opts.type - the node type to return the credential information for * @param {String} opts.id - the node id * @return {Promise} - the safe credentials - * @memberof RED.flows + * @memberof @node-red/runtime_flows */ getNodeCredentials: function(opts) { return new Promise(function(resolve,reject) { diff --git a/packages/node_modules/@node-red/runtime/lib/api/index.js b/packages/node_modules/@node-red/runtime/lib/api/index.js index 2b315c0dc..8856ac3c2 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/index.js +++ b/packages/node_modules/@node-red/runtime/lib/api/index.js @@ -17,13 +17,7 @@ var runtime; -/** - * This module provides the core runtime component of Node-RED. - * It does *not* include the Node-RED editor. All interaction with - * this module is done using the api provided. - * - * @namespace RED - */ + var api = module.exports = { init: function(_runtime) { runtime = _runtime; @@ -44,31 +38,10 @@ var api = module.exports = { projects: require("./projects"), context: require("./context"), - /** - * Returns whether the runtime is started - * @param {Object} opts - * @param {User} opts.user - the user calling the api - * @return {Promise} - whether the runtime is started - * @memberof RED - */ isStarted: function(opts) { return Promise.resolve(runtime.isStarted()); }, - - /** - * Returns version number of the runtime - * @param {Object} opts - * @param {User} opts.user - the user calling the api - * @return {Promise} - the runtime version number - * @memberof RED - */ version: function(opts) { return Promise.resolve(runtime.version()); } } - -/** - * A user accessing the API - * @typedef User - * @type {object} - */ diff --git a/packages/node_modules/@node-red/runtime/lib/api/library.js b/packages/node_modules/@node-red/runtime/lib/api/library.js index f6d521b10..6f6571463 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/library.js +++ b/packages/node_modules/@node-red/runtime/lib/api/library.js @@ -15,7 +15,7 @@ **/ /** - * @namespace RED.library + * @mixin @node-red/runtime_library */ var runtime; @@ -32,7 +32,7 @@ var api = module.exports = { * @param {String} opts.type - the type of entry * @param {String} opts.path - the path of the entry * @return {Promise} - resolves when complete - * @memberof RED.library + * @memberof @node-red/runtime_library */ getEntry: function(opts) { return new Promise(function(resolve,reject) { @@ -71,7 +71,7 @@ var api = module.exports = { * @param {Object} opts.meta - any meta data associated with the entry * @param {String} opts.body - the body of the entry * @return {Promise} - resolves when complete - * @memberof RED.library + * @memberof @node-red/runtime_library */ saveEntry: function(opts) { return new Promise(function(resolve,reject) { @@ -98,7 +98,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.type - the type of entry * @return {Promise} - the entry listing - * @memberof RED.library + * @memberof @node-red/runtime_library */ getEntries: function(opts) { return new Promise(function(resolve,reject) { diff --git a/packages/node_modules/@node-red/runtime/lib/api/nodes.js b/packages/node_modules/@node-red/runtime/lib/api/nodes.js index bc7b2c36b..ca67acc17 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/nodes.js +++ b/packages/node_modules/@node-red/runtime/lib/api/nodes.js @@ -15,7 +15,7 @@ **/ /** - * @namespace RED.nodes + * @mixin @node-red/runtime_nodes */ var fs = require("fs"); @@ -49,7 +49,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the node set to return * @return {Promise} - the node information - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getNodeInfo: function(opts) { return new Promise(function(resolve,reject) { @@ -74,7 +74,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the list of node modules - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getNodeList: function(opts) { return new Promise(function(resolve,reject) { @@ -90,7 +90,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the node set to return * @param {String} opts.lang - the locale language to return * @return {Promise} - the node html content - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getNodeConfig: function(opts) { return new Promise(function(resolve,reject) { @@ -115,7 +115,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.lang - the locale language to return * @return {Promise} - the node html content - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getNodeConfigs: function(opts) { return new Promise(function(resolve,reject) { @@ -130,7 +130,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.module - the id of the module to return * @return {Promise} - the node module info - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getModuleInfo: function(opts) { return new Promise(function(resolve,reject) { @@ -155,7 +155,7 @@ var api = module.exports = { * @param {String} opts.module - the id of the module to install * @param {String} opts.version - (optional) the version of the module to install * @return {Promise} - the node module info - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ addModule: function(opts) { return new Promise(function(resolve,reject) { @@ -210,7 +210,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.module - the id of the module to remove * @return {Promise} - resolves when complete - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ removeModule: function(opts) { return new Promise(function(resolve,reject) { @@ -253,7 +253,7 @@ var api = module.exports = { * @param {String} opts.module - the id of the module to enable or disable * @param {String} opts.enabled - whether the module should be enabled or disabled * @return {Promise} - the module info object - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ setModuleState: function(opts) { var mod = opts.module; @@ -301,7 +301,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the node-set to enable or disable * @param {String} opts.enabled - whether the module should be enabled or disabled * @return {Promise} - the module info object - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ setNodeSetState: function(opts) { return new Promise(function(resolve,reject) { @@ -348,7 +348,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {User} opts.lang - the i18n language to return. If not set, uses runtime default (en-US) * @return {Promise} - the message catalogs - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getModuleCatalogs: function(opts) { return new Promise(function(resolve,reject) { @@ -377,7 +377,7 @@ var api = module.exports = { * @param {User} opts.module - the module * @param {User} opts.lang - the i18n language to return. If not set, uses runtime default (en-US) * @return {Promise} - the message catalog - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getModuleCatalog: function(opts) { return new Promise(function(resolve,reject) { @@ -398,7 +398,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the list of all icons - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getIconList: function(opts) { return new Promise(function(resolve,reject) { @@ -414,7 +414,7 @@ var api = module.exports = { * @param {String} opts.module - the id of the module requesting the icon * @param {String} opts.icon - the name of the icon * @return {Promise} - the icon file as a Buffer or null if no icon available - * @memberof RED.nodes + * @memberof @node-red/runtime_nodes */ getIcon: function(opts) { return new Promise(function(resolve,reject) { diff --git a/packages/node_modules/@node-red/runtime/lib/api/projects.js b/packages/node_modules/@node-red/runtime/lib/api/projects.js index 79b447d52..27aef8c7b 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/projects.js +++ b/packages/node_modules/@node-red/runtime/lib/api/projects.js @@ -15,7 +15,7 @@ **/ /** - * @namespace RED.projects + * @mixin @node-red/runtime_projects */ var runtime; @@ -33,7 +33,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ listProjects: function(opts) { return runtime.storage.projects.listProjects(opts.user).then(function(list) { @@ -57,7 +57,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {Object} opts.project - the project information * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ createProject: function(opts) { return runtime.storage.projects.createProject(opts.user, opts.project) @@ -70,7 +70,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project to initialise * @param {Object} opts.project - the project information * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ initialiseProject: function(opts) { // Initialised set when creating default files for an empty repo @@ -82,7 +82,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the active project - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getActiveProject: function(opts) { return Promise.resolve(runtime.storage.projects.getActiveProject(opts.user)); @@ -94,7 +94,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the project to activate * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ setActiveProject: function(opts) { var currentProject = runtime.storage.projects.getActiveProject(opts.user); @@ -111,7 +111,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the project to get * @return {Promise} - the project metadata - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getProject: function(opts) { return runtime.storage.projects.getProject(opts.user, opts.id) @@ -124,7 +124,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project to update * @param {Object} opts.project - the project information * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ updateProject: function(opts) { return runtime.storage.projects.updateProject(opts.user, opts.id, opts.project); @@ -136,7 +136,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the project to update * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ deleteProject: function(opts) { return runtime.storage.projects.deleteProject(opts.user, opts.id); @@ -149,7 +149,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {Boolean} opts.remote - whether to include status of remote repos * @return {Promise} - the project status - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getStatus: function(opts) { return runtime.storage.projects.getStatus(opts.user, opts.id, opts.remote) @@ -162,7 +162,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {Boolean} opts.remote - whether to return remote branches (true) or local (false) * @return {Promise} - a list of the local branches - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getBranches: function(opts) { return runtime.storage.projects.getBranches(opts.user, opts.id, opts.remote); @@ -175,7 +175,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String} opts.branch - the name of the branch * @return {Promise} - the status of the branch - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getBranchStatus: function(opts) { return runtime.storage.projects.getBranchStatus(opts.user, opts.id, opts.branch); @@ -189,7 +189,7 @@ var api = module.exports = { * @param {String} opts.branch - the name of the branch * @param {Boolean} opts.create - whether to create the branch if it doesn't exist * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ setBranch: function(opts) { return runtime.storage.projects.setBranch(opts.user, opts.id, opts.branch, opts.create) @@ -203,7 +203,7 @@ var api = module.exports = { * @param {String} opts.branch - the name of the branch * @param {Boolean} opts.force - whether to force delete * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ deleteBranch: function(opts) { return runtime.storage.projects.deleteBranch(opts.user, opts.id, opts.branch, false, opts.force); @@ -216,7 +216,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String} opts.message - the message to associate with the commit * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ commit: function(opts) { return runtime.storage.projects.commit(opts.user, opts.id,{message: opts.message}); @@ -229,7 +229,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String} opts.sha - the sha of the commit to return * @return {Promise} - the commit details - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getCommit: function(opts) { return runtime.storage.projects.getCommit(opts.user, opts.id, opts.sha); @@ -243,7 +243,7 @@ var api = module.exports = { * @param {String} opts.limit - limit how many to return * @param {String} opts.before - id of the commit to work back from * @return {Promise} - an array of commits - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getCommits: function(opts) { return runtime.storage.projects.getCommits(opts.user, opts.id, { @@ -258,7 +258,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the project * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ abortMerge: function(opts) { return runtime.storage.projects.abortMerge(opts.user, opts.id); @@ -272,7 +272,7 @@ var api = module.exports = { * @param {String} opts.path - the path of the file being merged * @param {String} opts.resolutions - how to resolve the merge conflict * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ resolveMerge: function(opts) { return runtime.storage.projects.resolveMerge(opts.user, opts.id, opts.path, opts.resolution); @@ -284,7 +284,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the project * @return {Promise} - the file listing - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getFiles: function(opts) { return runtime.storage.projects.getFiles(opts.user, opts.id); @@ -298,7 +298,7 @@ var api = module.exports = { * @param {String} opts.path - the path of the file * @param {String} opts.tree - the version control tree to use * @return {Promise} - the content of the file - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getFile: function(opts) { return runtime.storage.projects.getFile(opts.user, opts.id,opts.path,opts.tree); @@ -311,7 +311,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String|Array} opts.path - the path of the file, or an array of paths * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ stageFile: function(opts) { return runtime.storage.projects.stageFile(opts.user, opts.id, opts.path); @@ -324,7 +324,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String} opts.path - the path of the file. If not set, all staged files are unstaged * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ unstageFile: function(opts) { return runtime.storage.projects.unstageFile(opts.user, opts.id, opts.path); @@ -337,7 +337,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String} opts.path - the path of the file * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ revertFile: function(opts) { return runtime.storage.projects.revertFile(opts.user, opts.id,opts.path) @@ -351,7 +351,7 @@ var api = module.exports = { * @param {String} opts.path - the path of the file * @param {String} opts.type - the type of diff * @return {Promise} - the requested diff - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getFileDiff: function(opts) { return runtime.storage.projects.getFileDiff(opts.user, opts.id, opts.path, opts.type); @@ -363,7 +363,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {String} opts.id - the id of the project * @return {Promise} - a list of project remotes - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ getRemotes: function(opts) { return runtime.storage.projects.getRemotes(opts.user, opts.id); @@ -379,7 +379,7 @@ var api = module.exports = { * @param {String} opts.remote.name - the name of the remote * @param {String} opts.remote.url - the url of the remote * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ addRemote: function(opts) { return runtime.storage.projects.addRemote(opts.user, opts.id, opts.remote) @@ -392,7 +392,7 @@ var api = module.exports = { * @param {String} opts.id - the id of the project * @param {String} opts.remote - the name of the remote * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ removeRemote: function(opts) { return runtime.storage.projects.removeRemote(opts.user, opts.id, opts.remote); @@ -406,7 +406,7 @@ var api = module.exports = { * @param {Object} opts.remote - the remote metadata * @param {String} opts.remote.name - the name of the remote * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ updateRemote: function(opts) { return runtime.storage.projects.updateRemote(opts.user, opts.id, opts.remote.name, opts.remote) @@ -417,7 +417,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ pull: function(opts) { return runtime.storage.projects.pull(opts.user, opts.id, opts.remote, opts.track, opts.allowUnrelatedHistories); @@ -431,7 +431,7 @@ var api = module.exports = { * @param {String} opts.remote - the name of the remote * @param {String} opts.track - whether to set the remote as the upstream * @return {Promise} - resolves when complete - * @memberof RED.projects + * @memberof @node-red/runtime_projects */ push: function(opts) { return runtime.storage.projects.push(opts.user, opts.id, opts.remote, opts.track); diff --git a/packages/node_modules/@node-red/runtime/lib/api/settings.js b/packages/node_modules/@node-red/runtime/lib/api/settings.js index 9afbff827..3ae83d0cf 100644 --- a/packages/node_modules/@node-red/runtime/lib/api/settings.js +++ b/packages/node_modules/@node-red/runtime/lib/api/settings.js @@ -15,7 +15,7 @@ **/ /** - * @namespace RED.settings + * @mixin @node-red/runtime_settings */ var util = require("util"); @@ -61,7 +61,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the runtime settings - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ getRuntimeSettings: function(opts) { return new Promise(function(resolve,reject) { @@ -126,7 +126,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the user settings - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ getUserSettings: function(opts) { var username; @@ -144,7 +144,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {Object} opts.settings - the updates to the user settings * @return {Promise} - the user settings - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ updateUserSettings: function(opts) { var username; @@ -179,7 +179,7 @@ var api = module.exports = { * @param {Object} opts * @param {User} opts.user - the user calling the api * @return {Promise} - the user's ssh keys - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ getUserKeys: function(opts) { return new Promise(function(resolve,reject) { @@ -199,7 +199,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {User} opts.id - the id of the key to return * @return {Promise} - the user's ssh public key - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ getUserKey: function(opts) { return new Promise(function(resolve,reject) { @@ -230,7 +230,7 @@ var api = module.exports = { * @param {User} opts.comment - (option) a comment to associate with the key pair * @param {User} opts.size - (optional) the size of the key. Default: 2048 * @return {Promise} - the id of the generated key - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ generateUserKey: function(opts) { return new Promise(function(resolve,reject) { @@ -250,7 +250,7 @@ var api = module.exports = { * @param {User} opts.user - the user calling the api * @param {User} opts.id - the id of the key to delete * @return {Promise} - resolves when deleted - * @memberof RED.settings + * @memberof @node-red/runtime_settings */ removeUserKey: function(opts) { return new Promise(function(resolve,reject) { diff --git a/packages/node_modules/@node-red/runtime/lib/index.js b/packages/node_modules/@node-red/runtime/lib/index.js index 2ca92a4f0..4cd257f0f 100644 --- a/packages/node_modules/@node-red/runtime/lib/index.js +++ b/packages/node_modules/@node-red/runtime/lib/index.js @@ -1,4 +1,4 @@ -/** +/*! * Copyright JS Foundation and other contributors, http://js.foundation * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -31,8 +31,8 @@ var fs = require("fs"); var os = require("os"); var redUtil = require("@node-red/util"); -var log; -var i18n; +var log = redUtil.log; +var i18n = redUtil.i18n; var runtimeMetricInterval = null; @@ -48,18 +48,24 @@ var adminApi = { auth: { needsPermission: function() {} }, - comms: { - publish: function() {} - }, adminApp: stubbedExpressApp, server: {} } var nodeApp; +var server; -function init(userSettings,_adminApi) { - log = redUtil.log; - i18n = redUtil.i18n; + +/** + * Initialise the runtime module. + * @param {Object} settings - the runtime settings object + * @param {HTTPServer} server - the http server instance for the server to use + * @param {AdminAPI} adminApi - an instance of @node-red/editor-api. TODO: This needs to be + * better abstracted. + * @memberof @node-red/runtime + */ +function init(userSettings,httpServer,_adminApi) { + server = httpServer; userSettings.version = getVersion(); settings.init(userSettings); @@ -90,6 +96,12 @@ function getVersion() { return version; } +/** + * Start the runtime. + * @return {Promise} - resolves when the runtime is started. This does not mean the + * flows will be running as they are started asynchronously. + * @memberof @node-red/runtime + */ function start() { return i18n.registerMessageCatalog("runtime",path.resolve(path.join(__dirname,"..","locales")),"runtime.json") @@ -225,6 +237,11 @@ function reportMetrics() { }); } +/** + * Stops the runtime. + * @return {Promise} - resolves when the runtime is stopped. + * @memberof @node-red/runtime + */ function stop() { if (runtimeMetricInterval) { clearInterval(runtimeMetricInterval); @@ -253,27 +270,89 @@ var runtime = { util: require("@node-red/util").util, get adminApi() { return adminApi }, get nodeApp() { return nodeApp }, + get server() { return server }, isStarted: function() { return started; } }; - +/** + * This module provides the core runtime component of Node-RED. + * It does *not* include the Node-RED editor. All interaction with + * this module is done using the api provided. + * + * @namespace @node-red/runtime + */ module.exports = { init: init, start: start, stop: stop, - "_": runtime, - + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_comms + */ comms: externalAPI.comms, + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_flows + */ flows: externalAPI.flows, + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_library + */ library: externalAPI.library, + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_nodes + */ nodes: externalAPI.nodes, + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_settings + */ settings: externalAPI.settings, + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_projects + */ projects: externalAPI.projects, + /** + * @memberof @node-red/runtime + * @mixes @node-red/runtime_context + */ context: externalAPI.context, + /** + * Returns whether the runtime is started + * @param {Object} opts + * @param {User} opts.user - the user calling the api + * @return {Promise} - whether the runtime is started + * @function + * @memberof @node-red/runtime + */ isStarted: externalAPI.isStarted, - version: externalAPI.version + + /** + * Returns version number of the runtime + * @param {Object} opts + * @param {User} opts.user - the user calling the api + * @return {Promise} - the runtime version number + * @function + * @memberof @node-red/runtime + */ + version: externalAPI.version, + + storage: storage, + events: events, + get httpNode() { return nodeApp }, + get server() { return server } } + + +/** + * A user accessing the API + * @typedef User + * @type {object} + */ diff --git a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/Project.js b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/Project.js index f580c178e..d07a544c8 100644 --- a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/Project.js +++ b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/Project.js @@ -26,7 +26,7 @@ var defaultFileSet = require("./defaultFileSet"); var sshKeys = require("./ssh"); var settings; var runtime; -var log; +var log = require("@node-red/util").log; var projectsDir; @@ -162,7 +162,7 @@ Project.prototype.initialise = function(user,data) { if (defaultFileSet.hasOwnProperty(file)) { var path = fspath.join(project.path,file); if (!fs.existsSync(path)) { - promises.push(util.writeFile(path,defaultFileSet[file](project, runtime))); + promises.push(util.writeFile(path,defaultFileSet[file](project))); } } @@ -858,7 +858,7 @@ function createDefaultProject(user, project) { } for (var file in defaultFileSet) { if (defaultFileSet.hasOwnProperty(file)) { - promises.push(util.writeFile(fspath.join(projectPath,file),defaultFileSet[file](project, runtime))); + promises.push(util.writeFile(fspath.join(projectPath,file),defaultFileSet[file](project))); } } @@ -992,7 +992,6 @@ function loadProject(projectPath) { function init(_settings, _runtime) { settings = _settings; runtime = _runtime; - log = runtime.log; projectsDir = fspath.join(settings.userDir,"projects"); authCache.init(); } diff --git a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/defaultFileSet.js b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/defaultFileSet.js index a7e825207..04b95e3e0 100644 --- a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/defaultFileSet.js +++ b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/defaultFileSet.js @@ -14,9 +14,10 @@ * limitations under the License. **/ +var i18n = require("@node-red/util").i18n; + module.exports = { - "package.json": function(project, runtime) { - var i18n = runtime.i18n; + "package.json": function(project) { var package = { "name": project.name, "description": project.summary||i18n._("storage.localfilesystem.projects.summary"), @@ -35,8 +36,7 @@ module.exports = { } return JSON.stringify(package,"",4); }, - "README.md": function(project, runtime) { - var i18n = runtime.i18n; + "README.md": function(project) { var content = project.name+"\n"+("=".repeat(project.name.length))+"\n\n"; if (project.summary) { content += project.summary+"\n\n"; diff --git a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/git/index.js b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/git/index.js index d5c23ccb6..214a9e615 100644 --- a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/git/index.js +++ b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/git/index.js @@ -25,7 +25,7 @@ var path = require("path"); var gitCommand = "git"; var gitVersion; -var log; +var log = require("@node-red/util").log; function runGitCommand(args,cwd,env,emit) { log.trace(gitCommand + JSON.stringify(args)); @@ -382,8 +382,7 @@ function removeRemote(cwd,name) { } module.exports = { - init: function(_settings,_runtime) { - log = _runtime.log + init: function(_settings) { return new Promise(function(resolve,reject) { Promise.all([ runGitCommand(["--version"]), diff --git a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/index.js b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/index.js index d11c2b06d..4fee06a45 100644 --- a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/index.js +++ b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/index.js @@ -29,7 +29,7 @@ var Projects = require("./Project"); var settings; var runtime; -var log; +var log = require("@node-red/util").log; var projectsEnabled = false; var projectLogMessages = []; @@ -42,7 +42,6 @@ var globalGitUser = false; function init(_settings, _runtime) { settings = _settings; runtime = _runtime; - log = runtime.log; try { if (settings.editorTheme.projects.enabled === true) { @@ -90,7 +89,7 @@ function init(_settings, _runtime) { if (projectsEnabled) { return sshTools.init(settings,runtime).then(function() { - gitTools.init(_settings, _runtime).then(function(gitConfig) { + gitTools.init(_settings).then(function(gitConfig) { if (!gitConfig || /^1\./.test(gitConfig.version)) { if (!gitConfig) { projectLogMessages.push(log._("storage.localfilesystem.projects.git-not-found")) @@ -109,7 +108,7 @@ function init(_settings, _runtime) { } else { globalGitUser = gitConfig.user; Projects.init(settings,runtime); - sshTools.init(settings,runtime); + sshTools.init(settings); projectsDir = fspath.join(settings.userDir,"projects"); if (!settings.readOnly) { return fs.ensureDir(projectsDir) diff --git a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/index.js b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/index.js index cc9bd8754..25dacd3b1 100644 --- a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/index.js +++ b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/index.js @@ -20,15 +20,12 @@ var fspath = require("path"); var keygen = require("./keygen"); var settings; -var runtime; -var log; +var log = require("@node-red/util").log; var sshkeyDir; var userSSHKeyDir; -function init(_settings, _runtime) { +function init(_settings) { settings = _settings; - runtime = _runtime; - log = runtime.log; sshkeyDir = fspath.resolve(fspath.join(settings.userDir, "projects", ".sshkeys")); userSSHKeyDir = fspath.join(process.env.HOME || process.env.USERPROFILE || process.env.HOMEPATH, ".ssh"); // console.log('sshkeys.init()'); diff --git a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/keygen.js b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/keygen.js index d7081c154..218144c12 100644 --- a/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/keygen.js +++ b/packages/node_modules/@node-red/runtime/lib/storage/localfilesystem/projects/ssh/keygen.js @@ -18,7 +18,7 @@ var child_process = require('child_process'); var sshkeygenCommand = "ssh-keygen"; -var log; +var log = require("@node-red/util").log; function runSshKeygenCommand(args,cwd,env) { return new Promise(function(resolve, reject) { @@ -54,10 +54,6 @@ function runSshKeygenCommand(args,cwd,env) { }); } -function init(_settings, _runtime) { - log = _runtime.log; -} - function generateKey(options) { var args = ['-q', '-t', 'rsa']; var err; @@ -90,6 +86,5 @@ function generateKey(options) { } module.exports = { - init: init, - generateKey: generateKey, + generateKey: generateKey }; diff --git a/packages/node_modules/node-red/lib/red.js b/packages/node_modules/node-red/lib/red.js index 128869c43..2dcc1ae53 100644 --- a/packages/node_modules/node-red/lib/red.js +++ b/packages/node_modules/node-red/lib/red.js @@ -1,4 +1,4 @@ -/** +/*! * Copyright JS Foundation and other contributors, http://js.foundation * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -22,8 +22,6 @@ var redUtil = require("@node-red/util"); var api = require("@node-red/editor-api"); -var nodeApp = null; -var adminApp = null; var server = null; var apiEnabled = false; @@ -37,9 +35,20 @@ function checkVersion(userSettings) { userSettings.UNSUPPORTED_VERSION = process.version; } } - +/** + * This module provides the full Node-RED application, with both the runtime + * and editor components built in. + * + * @namespace node-red + */ module.exports = { - init: function(httpServer,userSettings) { + /** + * Initialise the Node-RED application. + * @param {server} httpServer - the HTTP server object to use + * @param {Object} userSettings - an object containing the runtime settings + * @memberof node-red + */ + init: function(httpServer, userSettings) { if (!userSettings) { userSettings = httpServer; httpServer = null; @@ -54,27 +63,26 @@ module.exports = { } redUtil.init(userSettings); if (userSettings.httpAdminRoot !== false) { - runtime.init(userSettings,api); - api.init(httpServer,userSettings,runtime._.storage,runtime); - + runtime.init(userSettings,httpServer,api); + api.init(userSettings,httpServer,runtime.storage,runtime); apiEnabled = true; - server = runtime._.adminApi.server; - runtime._.server = runtime._.adminApi.server; + server = httpServer; } else { runtime.init(userSettings); apiEnabled = false; - if (httpServer){ + if (httpServer) { server = httpServer; - runtime._.server = httpServer; } else { - server = runtime._.adminApi.server; - runtime._.server = runtime._.adminApi.server; // useless at this point, but at least harmless. + server = null; } } - adminApp = runtime._.adminApi.adminApp; - nodeApp = runtime._.nodeApp; return; }, + /** + * Start the Node-RED application. + * @return {Promise} - resolves when complete + * @memberof node-red + */ start: function() { return runtime.start().then(function() { if (apiEnabled) { @@ -82,6 +90,11 @@ module.exports = { } }); }, + /** + * Stop the Node-RED application. + * @return {Promise} - resolves when complete + * @memberof node-red + */ stop: function() { return runtime.stop().then(function() { if (apiEnabled) { @@ -89,30 +102,37 @@ module.exports = { } }) }, - nodes: runtime._.nodes, - log: redUtil.log, - settings:runtime._.settings, - util: runtime._.util, - version: runtime._.version, - events: runtime._.events, - comms: { - publish: function(topic,data,retain) { - runtime._.events.emit("comms",{ - topic: topic, - data: data, - retain: retain - }) - } - }, - library: { - register: function(type) { - return runtime._.library.register(null,type); - } - }, - auth: api.auth, - get app() { console.log("Deprecated use of RED.app - use RED.httpAdmin instead"); return runtime._.app }, - get httpAdmin() { return adminApp }, - get httpNode() { return nodeApp }, - get server() { return server } + log: redUtil.log, + util: redUtil.util, + + get nodes() { console.log("Deprecated use of RED.nodes - refer to API documentation on RED.runtime.nodes"); return runtime._.nodes }, + get settings() { console.log("Deprecated use of RED.settings - refer to API documentation on RED.runtime.settings"); return runtime._.settings }, + get version() { console.log("Deprecated use of RED.version - refer to API documentation on RED.runtime.version"); return runtime._.version }, + get events() { console.log("Deprecated use of RED.events - refer to API documentation on RED.runtime.events"); return runtime.events }, + + /** + * The express application for the Editor Admin API + * @memberof node-red + */ + get httpAdmin() { return api.adminApp }, + + /** + * The express application for HTTP Nodes + * @memberof node-red + */ + get httpNode() { return runtime.httpNode }, + + /** + * The HTTP Server used by the runtime + * @memberof node-red + */ + get server() { return server }, + + /** + * The runtime api + * @see @node-red/runtime + * @memberof node-red + */ + runtime: runtime };