{"name":"@openwhisk/wskdebug","version":"1.3.0","description":"Debugging and live development tool for Apache OpenWhisk","license":"Apache-2.0","author":{"name":"Apache Software Foundation"},"repository":{"type":"git","url":"git+https://github.com/apache/openwhisk-wskdebug.git"},"homepage":"https://github.com/apache/openwhisk-wskdebug#readme","bugs":{"url":"https://github.com/apache/openwhisk-wskdebug/issues"},"keywords":["openwhisk","debug","debugger","serverless","apache"],"main":"index.js","bin":{"wskdebug":"wskdebug.js"},"scripts":{"pretest":"npm install --no-save ngrok","test":"WSKDEBUG_QUIET=1 nyc mocha test/**/*.test.js && test/install/test-npm-install.sh","posttest":"eslint .","report-coverage":"nyc report --reporter=json && codecov -f coverage/coverage-final.json"},"nyc":{"all":true,"es-modules":false,"reporter":"text","include":["[^.]*.js","src/**/*.js","agent/**/*.js"]},"mocha":{"reporter":"mocha-multi-reporters","reporterOptions":{"configFile":"test/multireporterconfig.json"},"file":"test/logfile.setup.js"},"dependencies":{"chalk":"^4.0.0","clone":"^2.1.2","debug":"^4.1.1","dockerode":"^3.2.0","dotenv":"^8.2.0","fetch-retry":"^3.1.0","fs-extra":"^8.1.0","get-port":"^5.1.1","is-port-reachable":"^3.0.0","isomorphic-fetch":"^2.2.1","livereload":"^0.9.1","manakin":"^0.5.2","openwhisk":"^3.21.2","ora":"^4.0.3","pretty-bytes":"^5.3.0","pretty-ms":"^6.0.1","yargs":"^15.3.1"},"peerDependencies":{"ngrok":"^3.2.7"},"devDependencies":{"chmodr":"^1.2.0","codecov":"^3.6.5","eslint":"^6.8.0","eslint-config-problems":"^4.0.0","eslint-plugin-mocha":"^6.3.0","mocha":"^7.1.0","mocha-multi-reporters":"^1.1.7","mock-fs":"^4.12.0","mock-require":"^3.0.3","nock":"^12.0.2","nyc":"^15.0.0","strip-ansi":"^6.0.0","tmp":"^0.1.0"},"publishConfig":{"access":"public"},"engines":{"node":">=10.0.0"},"gitHead":"c90b665c1b45cde0526d176af5db9204fcd904ff","_id":"@openwhisk/wskdebug@1.3.0","_nodeVersion":"14.1.0","_npmVersion":"6.14.4","dist":{"integrity":"sha512-XUynPhwnvBCK3jDtiTOJCxr5Ecb7lCV99R4xMci7rOmW1D/XgDHwV1nSRuYnqn5o2w49Anq4g0+i9/VslPc+fA==","shasum":"7ec127d0b7c658f660ccb59c2a69160aa7fab465","tarball":"https://registry.npmmirror.com/@openwhisk/wskdebug/-/wskdebug-1.3.0.tgz","fileCount":23,"unpackedSize":168716,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfKxVbCRA9TVsSAnZWagAAlbwP/i878EIxbsmu40Y9oIKj\naZNz4Ra5RSyDKj1JCVczM8SmNgy4KIAVny/4SM/X2uUY506Nyyw4ZrzH8jw/\nnMbDO+f39nyvdXxq5dEVT8OYmls0U7w7JPmiuyKtML4HieZIo4ypxS9o/EH5\nf8qIzYS2aKPujYsmjQgBlfcWP9um4QFL5yQ7VWgY0uxOlQfSpFAVOoUGAOlO\nNWQWPOlHdydEPQUm20QhrMM8pER68DCvr5yH+Rg6A6dEJn0GaXHe8VSFDpo3\nDCmLfzjOEEkLyR0NWaVr64g2V/BSMV7/6va7jF4D8COVI/zw4SDT1jprt8Za\ng39NzSvrRuggZgsxAToDrpT7nz+YTpFyhX36i/nS0tv5Z5iO37a0SE/2pfnG\nmVlNjgfdhhTUvlIxRjLmo3XxrukCKTAcNBtFkqDdnxs9C7HU9sr/Qr9vyrl9\ns/tkdVvC87hMScQNpbxbJ6tV2vOyTG1qVXDvEm+wK7RC0UjzcyTKVPwq627Q\ng+yLu1feQ0rqh4TIGblOCRXuY9J2Kzs6SqBg8PZD1u2SnKt3vOzbjAIdZcxk\nCJHOUqQiIAahZoWk915tnvTAlCEJRNiH+VuoUMqVghFl+HXMAJgQMyn/pRfC\nNgjtBTfgssoA7rqcB4807FiVkiVvggXJsfyJ1+NPWWaMqwBjZ1ROlDGB/49j\nlRpC\r\n=90DK\r\n-----END PGP SIGNATURE-----\r\n","size":43450},"maintainers":[{"name":"csantanapr","email":"csantana23@gmail.com"},{"name":"jthomas","email":"james@jamesthom.as"},{"name":"openwhisk-bot","email":"apacheopenwhisk@gmail.com"},{"name":"rabbah","email":"rodric@gmail.com"}],"_npmUser":{"name":"openwhisk-bot","email":"apacheopenwhisk@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/wskdebug_1.3.0_1596659035311_0.25688049980168404"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2021-12-25T14:34:06.496Z","readme":"\n\n\n[![npm version](https://img.shields.io/npm/v/@openwhisk/wskdebug)](https://www.npmjs.com/package/@openwhisk/wskdebug)\n![](https://img.shields.io/badge/cli-wskdebug-brightgreen)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n[![Travis](https://travis-ci.com/apache/openwhisk-wskdebug.svg?branch=master)](https://travis-ci.com/apache/openwhisk-wskdebug)\n\n\nwskdebug\n========\n\nDebugging and live development for [Apache OpenWhisk](https://openwhisk.apache.org). CLI tool written in [Node.js](https://nodejs.org) and depending on a [local Docker](https://www.docker.com/products/docker-desktop). Integrates easily into IDEs such as [Visual Studio Code](https://code.visualstudio.com).\n\n---\n\nLive development of a web action using `wskdebug`:\n\n![screen cast showing debugging of a web action using wskdebug](resources/wskdebug-demo.gif)\n\n_On the left [Visual Studio Code](https://code.visualstudio.com) in debug mode. On the right, a browser with the page rendered by the web action. The developer notices the feature of handling the `name` is not implemented yet. A breakpoint shows them that `name` is set, but it's not used. They add the code to respond and greet with `name`. Simply by saving the code, the browser auto reloads the page and the breakpoint is hit again. They step through to see that the new code is working fine, and get the expected result in the browser: \"Hello, Alex!\"._\n\n---\n\n[Youtube video of wskdebug being demoed to the OpenWhisk community](https://youtu.be/Qtsi8VFm0uY?t=727):\n\n[![youtube video demoing wskdebug to the openwhisk community](resources/wskdebug-ow-meeting-screenshot.png)](https://youtu.be/Qtsi8VFm0uY?t=727)\n\n---\n\n### Contents\n\n * [Installation](#installation)\n * [About](#about)\n * [Usage](#usage)\n * [Troubleshooting](#troubleshooting)\n * [How it works](#how-it-works)\n * [Development](#development)\n * [Contributing](#contributing)\n * [Releasing](#releasing)\n * [Licensing](#licensing)\n\n\n## Installation\n\n`wskdebug` requires [Node.js](https://nodejs.org) (version 10+), `npm` and a local [Docker](https://www.docker.com/products/docker-desktop) environment.\n\nTo install or update run:\n\n```\nnpm install -g @openwhisk/wskdebug\n```\n\n\n### Uninstall\n\n```\nnpm uninstall -g @openwhisk/wskdebug\n```\n\n\n## About\n\n_wskdebug_ is a command line tool to **develop and debug** [OpenWhisk actions](https://openwhisk.apache.org/documentation.html#programming-model-actions) in your favorite IDE or debugger with a **fast feedback loop**. It features:\n\n* full debugging of actions of the respective language runtime\n* automatic code reloading\n* LiveReload for web actions\n* auto-invoking of actions on code changes\n* or running any shell command such as a curl request on code changes\n\nCurrently, [Node.js actions](https://openwhisk.apache.org/documentation.html#nodejs) are supported out of the box. For others, basic debugging can be [configured on the command line](#unsupported-action-kinds), while automatic code reloading needs an [extension in `wskdebug`](#extending-wskdebug-for-other-kinds).\n\n### Note on timeouts\n\nWeb actions or other blocking invocations time out after **1 minute in OpenWhisk**. This limit cannot be configured. This means that if the debugging session (stepping through code) takes longer than 1 minute, any web action will return an error and any blocking invocations will just get the activation id, which most callers of a blocking invocation do not expect.\n\nHowever, there is no time limit on stepping through the code itself if you do not care about the result of the action being handled synchronously.\n\n\n## Usage\n\nThe action to debug (e.g. `myaction`) must already be deployed.\n\n+ [Node.js: Visual Studio Code](#nodejs-visual-studio-code)\n+ [Node.js: Multiple actions](#nodejs-multiple-actions)\n+ [Node.js: Plain usage](#nodejs-plain-usage)\n+ [Node.js: Chrome DevTools](#nodejs-chrome-devtools)\n+ [Node.js: node-inspect command line](#nodejs-node-inspect-command-line)\n+ [Enable debug logging](#enable-debug-logging)\n+ [Unsupported action kinds](#unsupported-action-kinds)\n+ [Source mounting](#source-mounting)\n+ [Live reloading](#live-reloading)\n+ [Hit condition](#hit-condition)\n+ [Custom build step](#custom-build-step)\n+ [Help output](#help-output)\n\n\n### Node.js: Visual Studio Code\n\n> ⚠️ **VS Code June 2020 release (version 1.47) breaks wskdebug**\n>\n> Breakpoints will not hit because it debugs the wskdebug process instead of the action.\n>\n> Workaround: set `\"debug.javascript.usePreview\": false` in your VS Code `settings.json`.\n>\n> A better solution will come with a new VS Code update and wskdebug 1.3.0.\n>\n> More details in [issue #74](https://github.com/apache/openwhisk-wskdebug/issues/74).\n\nAdd the configuration below to your [launch.json](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations). Replace `MYACTION` with the name of your action and `ACTION.js` with the source file containing the action. When you run this, it will start wskdebug and should automatically connect the debugger.\n\n```json\n \"configurations\": [\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"wskdebug MYACTION\",\n \"runtimeExecutable\": \"wskdebug\",\n \"args\": [ \"MYACTION\", \"ACTION.js\", \"-l\" ],\n \"localRoot\": \"${workspaceFolder}\",\n \"remoteRoot\": \"/code\",\n \"outputCapture\": \"std\"\n }\n ]\n```\n\nStop the debugger in VS Code to end the debugging session and `wskdebug`.\n\nThis snippets enables browser LiveReloading using `-l`. For other reloading options, see [live reloading](#live-reloading).\n\nFor troubleshooting, you can run the debugger in verbose mode by adding `\"-v\"` to the `args` array.\n\n#### Control wskprops credentials\n\nTo use custom credentials from a custom `.wskprops` and/or use a developer-specific openwhisk package name, but avoid committing that into your source control system, you can use an `.env` file.\n\n1. Put this `.env` file in your VS Code project root:\n\n ```\n WSK_CONFIG_FILE=/Users/user/.wskprops-custom\n WSK_PACKAGE=my-package\n ```\n\n Set either of the variables as needed.\n\n2. Make sure to not commit this file into source control, by e.g. adding `.env` to a `.gitignore` file.\n\n3. Add an `envFile` setting to the `.vscode/launch.json`, which you can share with co-workers and commit to source control:\n\n ```json\n \"configurations\": [\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"wskdebug\",\n \"runtimeExecutable\": \"wskdebug\",\n \"args\": [ \"MYACTION\", \"ACTION.js\", \"-l\" ],\n \"localRoot\": \"${workspaceFolder}\",\n \"remoteRoot\": \"/code\",\n \"outputCapture\": \"std\",\n \"envFile\": \"${workspaceFolder}/.env\"\n }\n ]\n ```\n\n\n### Node.js: Multiple actions\n\nEach `wskdebug` process can debug and live reload exactly a single action. To debug multiple actions, run `wskdebug` for each. If all of them are using the same kind/language, where the default debug port is the same, different ports need to be used.\n\nIn VS code you can start multiple debuggers from the same window thanks to compounds. Compounds provide a way to aggregate VS code configurations to run them together.\nHere is a `.vscode/launch.json` example that uses compounds to expose a config starting 2 wskdebug instances:\n\n```json\n{\n \"configurations\": [\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"mypackage/action1\",\n \"runtimeExecutable\": \"wskdebug\",\n \"args\": [\n \"mypackage/action1\",\n \"action1.js\"\n ],\n \"localRoot\": \"${workspaceFolder}\",\n \"remoteRoot\": \"/code\",\n \"outputCapture\": \"std\"\n },\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"mypackage/action2\",\n \"runtimeExecutable\": \"wskdebug\",\n \"args\": [\n \"mypackage/action2\",\n \"action2.js\"\n ],\n \"localRoot\": \"${workspaceFolder}\",\n \"remoteRoot\": \"/code\",\n \"outputCapture\": \"std\"\n }\n ],\n \"compounds\": [\n {\n \"name\": \"All actions\",\n \"configurations\": [\n \"mypackage/action1\",\n \"mypackage/action2\"\n ]\n }\n ]\n}\n```\n\nAlternatively, if you don't want to use compounds, you can have a separate VS code window for each action with separate VS code `launch` configurations.\n\nWith `launch`, VS Code will automatically pick an unused debug port and pass it as `--inspect=port` param to `wskdebug` as if it were `node`, and `wskdebug` understands this as alias for its `--port` argument.\n\nOtherwise you have to make sure to pass a different `--port` to each `wskdebug`. Similarly, if you use browser live reloading for multiple actions, you must specify different ports for that uing `--lr-port` on each instance.\n\n\n### Node.js: Plain usage\n\nRun `wskdebug` and specify the action\n\n```\nwskdebug myaction\n```\n\nThis will output (in case of a nodejs action):\n\n```\nDebug type: nodejs\nDebug port: localhost:9229\nReady, waiting for activations of myaction\nUse CTRL+C to exit\n```\n\nYou can then use a debugger to connect to the debug port, in this case `localhost:9229`. See below.\n\nWhen done, terminate `wskdebug` (not kill!) using CTRL+C. It will cleanup and remove the forwarding agent and restore the original action.\n\n\n### Node.js: Chrome DevTools\n\nRun [Node.js: Plain usage](#nodejs-plain-usage) and then:\n\n1. Open Chrome\n2. Enter `about:inspect`\n3. You should see a remote target `app.js`\n4. Click on \"Open dedicated DevTools for Node\" (but not on \"inspect\" under Target)\n5. This should open a new window\n6. Go to Sources > Node\n7. Find the `runner.js`\n8. Set a breakpoint on the line `thisRunner.userScriptMain(args)` inside `this.run()` (around line 97)\n9. Invoke the action\n10. Debugger should hit the breakpoint\n11. Then step into the function, it should now show the action sources in a tab named like `VM201` (the openwhisk nodejs runtime evals() the script, hence it's not directly listed as source file)\n\nSee also this [article](https://medium.com/@paul_irish/debugging-node-js-nightlies-with-chrome-devtools-7c4a1b95ae27).\n\n\n### Node.js: node-inspect command line\n\nRun [Node.js: Plain usage](#nodejs-plain-usage) and then:\n\nUse the command line Node debugger [node-inspect](https://github.com/nodejs/node-inspect):\n\n```\nnode-inspect 127.0.0.1:9229\n```\n\n\n### Enable debug logging\n\nTo enable debug logs in your action, you can set environment variables:\n\n1. (nodejs) `DEBUG` environment variable from the popular [debug](https://www.npmjs.com/package/debug) library is passed through to the action. Options:\n - Run wskdebug using\n\n ```\n DEBUG=xyz wskdebug myaction\n ```\n - Alternatively put it in the `.env` file (see [above](#nodejs-visual-studio-code))\n\n ```\n DEBUG=xyz\n ```\n2. (nodejs) To control the`NODE_DEBUG` [used](https://nodejs.org/api/util.html#util_util_debuglog_section) by built-in node modules, just set the `WSK_NODE_DEBUG` variable. (It is a separate one in order to not affect `wskdebug` itself which is written in nodejs.) Options:\n - Run wskdebug using\n\n ```\n WSK_NODE_DEBUG=NET wskdebug myaction\n ```\n - Alternatively put it in the `.env` file (see above)\n\n ```\n WSK_NODE_DEBUG=NET\n ```\n3. Any other custom environment variables that enable debugging or logging features in your action can be set by controlling the docker run arguments using `--docker-args` (note the leading space before `-e`, which is required):\n\n ```\n wskdebug --docker-args \" -e DEBUG_VAR=something\" myaction\n ```\n\n\n\n### Unsupported action kinds\n\nTo enable debugging for kinds/languages not supported out of the box, you can specify these cli arguments manually:\n\n* `--internal-port` the actual language debug port inside the container\n* `--command` override the docker run command for the image to e.g. pass a debug flag to the language enviroment\n* `--port` (optional) the port as it will be exposed from the container to the host, i.e. to what clients will connect to. defaults to `--internal-port` if set\n* `--image` (optional) control the docker image used as runtime for the action\n\nOnce you found a working configuration, feel encouraged to open a pull request to [add support for this out of the box](#default-debug-ports-and-commands)!\n\nFor automatic code reloading for other languages, `wskdebug` needs to be [extended](#extending-wskdebug-for-other-kinds).\n\n\n### Source mounting\n\nWhen a `` is provided, `wskdebug` will load the local sources and run them as action (for supported languages/kinds). This enables the hot code reloading feature.\n\nFor this to work, you must run `wskdebug` in the root folder of your project, _below_ which all the sources are (e.g. in nodejs anything that is loaded through `require()` statements), and then provide a relative path to the main js file (the one that contains the action `main` function) as `` . If you have sources outside the current working directory `wskdebug` is executed in, they would not be visible to the action that `wskdebug` runs.\n\nFor example, say you have a folder structure like this:\n\n```\nlib/\n action/\n action.js\n util.js\n other.js\n```\n\nThen you want to run it in the root like this:\n\n```\nwskdebug myaction lib/action/action.js\n```\n\nUnder the hood, `wskdebug` will mount the working directory it is executed in into the local action container (under `/code` inside the container), and then tell it to load the `lib/action/action.js` file as action entry point.\n\nIf `--on-build` and `--build-path` are specified, then `--build-path` is used instead of the `` for running the action inside the container. It still mounts the current working directory. But `` is still relevant for detecting local modifications for [live reloading](#live-reloading).\n\n\n### Live reloading\n\nThere are 3 different live reload mechanism possible that will trigger something when sources are modified. Any of them enables the hot reloading of code on any new activation.\n\n* Browser `LiveReload` using `-l`: works with [LiveReload](http://livereload.com) browser extensions (though we noticed only Chrome worked reliably) that will automatically reload the web page. Great for web actions that render HTML to browsers.\n* Action invocation using `-P` and `-a`: specify `-P` pointing to a json file with the invocation parameters and the debugged action will be automatically invoked with these parameters. This will also automatically invoke if that json file is modified. If you need to trigger a different action (because there is chain of actions before the one you are debugging), define it using `-a`.\n* Arbitrary shell command using `-r`: this can be used to invoke web APIs implemented by web actions using `curl`, or any scenario where something needs to be triggered so that the debugged action gets activated downstream.\n\nBy default it watches for changes underneath the current working directory for these file extensions (reflecting common OpenWhisk kinds and json for `-P params.json` auto-execution):\n\n```\njson, js, ts, coffee, py, rb, erb, go, java, scala, php, swift, rs, cs, bal, php, php5\n```\n\nThe directory or directories to watch can be changed using the `--watch` argument, which can be a directory path glob. You can also specify multiple via `--watch one --watch two` or `--watch one two`.\n\nThe extensions to watch can be changed through the `--watch-exts` argument, e.g. `--watch-exts js ts`.\n\n\n### Hit condition\n\nIf an action is invoked frequently but you only want to catch certain invocations, such as ones you control, you can set a condition to limit when the debugger should be invoked using `-c` or `--condition`. This must be a javascript expression which will be evaluated agains the input parameters.\n\nFor example, with a condition like this:\n\n```\n-c \"debug === 'true'\"\n```\n\nan invocation with these parameters would trigger the debugger:\n\n```\n{\n \"debug\": \"true\",\n \"some\": \"value\"\n}\n```\n\nIn another example for a web action, let's assume we want to catch all requests from Chrome. We would check for the header:\n\n```\n-c \"__ow_headers['user-agent'].includes('Chrome')\"\n```\n\nIf the hit condition is true, the action will be forwarded to the local debug container. If not, the original action (copy) in the OpenWhisk system will be invoked.\n\nPlease note that if source mounting is enabled, this will not have an effect on the original action copy that is invoked if the hit condition is not met. This means if condition is met, the latest local code changes will have an effect, but if not, the version of the action before wskdebug was started will be executed.\n\n\n### Custom build step\n\nFor some projects, the raw source code that developers edit in the IDE goes through a build process before being deployed as OpenWhisk action. To support this, `wskdebug` has these arguments:\n\n* `--on-build`: Shell command for custom action build step\n* `--build-path`: Path to built action, result of --on-build command\n\nAs a simple example, imagine the build process for an action with source file `action.js` deployed as `myaction` is simply renaming the file and placing it as `index.js` in a `build/` directory:\n\n```\nmkdir build/\ncp action.js build/index.js\n```\n\nReplace the copy/rename here with whatever build step is happening. Make sure source maps are enabled.\n\nThen you would invoke `wskdebug` like this:\n\n```\nwskdebug myaction action.js \\\n --on-build \"mkdir build/; cp action.js build/index.js\" \\\n --build-path build/index.js\n```\n\n**Note**: When using `--on-build`, you might have to set `--watch` to the directory that holds the source files and which is not the build directory. Otherwise you could get an endless loop as writing the build files will trigger `--on-build` again. The `--build-path` file will be explicitly excluded from watching, but other files next to it that might be generated as part of the build are not. For example, if there is a `src/` and `build/` directory and multiple files would be generated under `build/`, add `--watch src`:\n\n```\nwskdebug myaction src/action.js \\\n --on-build \"mkdir build/; cp action.js build/index.js; cp util.js build/util.js\" \\\n --build-path build/index.js \\\n --watch src\n```\n\n\n### Help output\n\n```\nwskdebug [source-path]\n\n. ____ ___ _ _ _ _ _\n. /\\ \\ / _ \\ _ __ ___ _ __ | | | | |__ (_)___| | __\n. /\\ /__\\ \\ | | | | '_ \\ / _ \\ '_ \\| | | | '_ \\| / __| |/ /\n. / \\____ \\ / | |_| | |_) | __/ | | | |/\\| | | | | \\__ \\ <\n. \\ \\ / \\/ \\___/| .__/ \\___|_| |_|__/\\__|_| |_|_|___/_|\\_\\\n. \\___\\/ tm |_|\n\n. W S K D E B U G\n\nDebug an Apache OpenWhisk by forwarding its activations to a local docker\ncontainer that has debugging enabled and its debug port exposed to the host.\n\nIf only is specified, the deployed action code is debugged.\n\nIf [source-path] is set, it must point to the local action sources which will be mounted\ninto the debug container. Sources will be automatically reloaded on each new activation.\nThis feature depends on the kind.\n\nSupported kinds:\n- nodejs: Node.js V8 inspect debugger on port 9229. Supports source mount\n\n\nArguments:\n action Name of action to debug [string]\n source-path Path to local action sources, file or folder (optional) [string]\n\nAction options:\n -m, --main Name of action entry point [string]\n -k, --kind Action kind override, needed for blackbox images [string]\n -i, --image Docker image to use as action container [string]\n --on-build Shell command for custom action build step [string]\n --build-path Path to built action, result of --on-build command [string]\n\nLiveReload options:\n -l Enable browser LiveReload on [source-path] [boolean]\n --lr-port Port for browser LiveReload (defaults to 35729) [number]\n -P Invoke action with these parameters on changes to [source-path].\n Argument can be json string or name of json file. [string]\n -a Name of custom action to invoke upon changes to [source-path].\n Defaults to if -P is set. [string]\n -r Shell command to run upon changes to [source-path] [string]\n --watch Glob pattern(s) to watch for source modifications [array]\n --watch-exts File extensions to watch for modifications [array]\n\nDebugger options:\n -p, --port Debug port exposed from container that debugging clients connect to.\n Defaults to --internal-port if set or standard debug port of the kind.\n Node.js arguments --inspect and co. can be used too. [number]\n --internal-port Actual debug port inside the container. Must match port opened by\n --command. Defaults to standard debug port of kind. [number]\n --command Custom container command that enables debugging [string]\n --docker-args Additional docker run arguments for container. Must be quoted and start\n with space: 'wskdebug --docker-args \" -e key=var\" myaction' [string]\n --on-start Shell command to run when debugger is up [string]\n\nAgent options:\n -c, --condition Hit condition to trigger debugger. Javascript expression evaluated\n against input parameters. Example: 'debug == 'true' [string]\n --agent-timeout Debugging agent timeout (seconds). Default: 5 min [number]\n --ngrok Use 3rd party service ngrok.com for agent forwarding. [boolean]\n --ngrok-region Ngrok region to use. Defaults to 'us'. [string]\n --cleanup Remove backup and any helper actions on exit. Makes shutdown slower.\n [boolean]\n --ignore-certs Bypass TLS certificate checking for openwhisk requests. [boolean]\n\nOptions:\n -v, --verbose Verbose output. Logs activation parameters and result [boolean]\n -q, --quiet Quiet mode. Only output logs from action container. [boolean]\n --version Show version number [boolean]\n -h, --help Show help [boolean]\n```\n\n\n## Troubleshooting\n\n### Debugger in VS Code does not hit breakpoints\n\nIf you use VS Code June 2020 release (version 1.47) it breaks wskdebug due to the new Javascript debugger implementation it includes. Breakpoints will not hit because it debugs the wskdebug process instead of the action.\n\n#### Workaround\n\nTell VS Code to use the old debugger. In your VS Code `settings.json` set:\n\n```\n\"debug.javascript.usePreview\": false\n```\n\nA better solution will come with a new VS Code update and wskdebug 1.3.0.\n\nMore details in [issue #74](https://github.com/apache/openwhisk-wskdebug/issues/74).\n\n### Cannot install - EACCES: permission denied, access '/usr/local/lib/node_modules\n\nIf you get an error during `npm install -g @openwhisk/wskdebug` like this:\n\n```\nnpm ERR! code EACCES\nnpm ERR! syscall access\nnpm ERR! path /usr/local/lib/node_modules\nnpm ERR! errno -13\nnpm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'\nnpm ERR! [Error: EACCES: permission denied, access '/usr/local/lib/node_modules'] {\nnpm ERR! stack: \"Error: EACCES: permission denied, access '/usr/local/lib/node_modules'\",\nnpm ERR! errno: -13,\nnpm ERR! code: 'EACCES',\nnpm ERR! syscall: 'access',\nnpm ERR! path: '/usr/local/lib/node_modules'\nnpm ERR! }\nnpm ERR!\nnpm ERR! The operation was rejected by your operating system.\nnpm ERR! It is likely you do not have the permissions to access this file as the current user\nnpm ERR!\nnpm ERR! If you believe this might be a permissions issue, please double-check the\nnpm ERR! permissions of the file and its containing directories, or try running\nnpm ERR! the command again as root/Administrator.\n```\n\nThis is a common npm situation, please see npm documentation for different solutions: [Resolving EACCES permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).\n\n### Cannot install ngrok dependency\n\nIf you get an error during `npm install -g @openwhisk/wskdebug` like this:\n\n```\nngrok - downloading binary https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-darwin-amd64.zip\nngrok - error storing binary to local file [Error: EACCES: permission denied, open '/usr/local/lib/node_modules/wskdebug/node_modules/ngrok/bin/aHR0cHM6Ly9iaW4uZXF1aW5veC5pby9jLzRWbUR6QTdpYUhiL25ncm9rLXN0YWJsZS1kYXJ3aW4tYW1kNjQuemlw.zip'] {\n errno: -13,\n code: 'EACCES',\n syscall: 'open',\n path: '/usr/local/lib/node_modules/wskdebug/node_modules/ngrok/bin/aHR0cHM6Ly9iaW4uZXF1aW5veC5pby9jLzRWbUR6QTdpYUhiL25ncm9rLXN0YWJsZS1kYXJ3aW4tYW1kNjQuemlw.zip'\n}\n```\n\nrun this instead:\n\n```\nsudo npm install -g @openwhisk/wskdebug --unsafe-perm=true --allow-root\n```\n\nThe dependency `ngrok` requires full write permission in `/usr/local/lib/node_modules` during its custom install phase. This is a [known ngrok issue](https://github.com/bubenshchykov/ngrok/issues/87).\n\nNote that since `wskdebug 1.2` the install command `npm install -g @openwhisk/wskdebug --unsafe-perm=true` should work, and since `wskdebug 1.3` ngrok is an optional dependency that is not installed by default, and a plain `npm install -g @openwhisk/wskdebug` should be enough.\n\n\n### Does not work, namespace shows as undefined\n\nOlder versions of `wskdebug` before `1.1.2` required the `NAMESPACE` to be set in the `~/.wskprops`. See [issue #3](https://github.com/adobe/wskdebug/issues/3).\n\n### No invocations visible in wskdebug\n\n* Is `wskdebug` working against the correct namespace? You can see that in the \"Starting debugger for ...\" output at the very start. If you tend to use `WSK_CONFIG_FILE` in your shell, please be aware that IDEs starting `wskdebug` will use `~/.wskprops` unless you set the environment variable for the `wskdebug` invocation in the IDE.\n* Wait a bit and try again. Restart (CTRL+C, then start `wskdebug` again), wait a bit and try again. Catching the invocations is not 100% perfect, as OpenWhisk could sometimes start multiple containers for the action and that might break the agents used by wskdebug to forward the invocations locally. A restart overwrites the action and will reset those containers.\n\n### Port is already allocated\n\nYou can only run one `wskdebug` aka one action for the same runtime (debug port) at a time.\n\nIf you get an error like this:\n\n```\ndocker: Error response from daemon: driver failed programming external connectivity on endpoint wskdebug-webaction-1559204115390 (3919892fab2981bf9feab0b6ba3fc256676de59d1a6ab67519295757313e8ac3): Bind for 0.0.0.0:9229 failed: port is already allocated.\n```\n\nit means that there is another `wskdebug` already running or that its container was left over, blocking the debug port.\n\nEither quit the other `wskdebug` or if its an unexpected left over, terminate the docker container using:\n\n```\ndocker rm -f wskdebug-webaction-1559204115390\n```\n\nThe containers are named `wskdebug-ACTION-TIMESTAMP`.\n\n### Restore action\n\nIf `wskdebug` fails unexpectedly or gets killed, it might leave the forwarding agent behind in place of the action. You should be able to restore the original action using the copied action named `*_wskdebug_original`.\n\n```\nwsk action delete myaction\nwsk action create --copy myaction myaction_wskdebug_original\nwsk action delete myaction_wskdebug_original\n```\n\nAlternatively you could also redeploy your action and then delete the backup:\n\n```\n# deploy command might vary\nwsk action update myaction myaction.js\n\nwsk action delete myaction_wskdebug_original\n```\n\n\n## How it works\n\n`wskdebug` supports debugging of an action by **forwarding** it from the OpenWhisk system to a **local container on your desktop** and executing it there. By overriding the command to run in the container and other `docker run` configurations, the local container respectively the language runtime inside the container is run in debug mode and the respective debug port is opened and exposed to the local desktop.\n\nFurthermore, the local container can **mount the local source files** and automatically reload them on every invocation. `wskdebug` can also listen for changes to the source files and trigger an automatic reload of a web action or direct invocation of the action or just any shell command, e.g. if you need to make more nuanced curl requests to trigger your API.\n\nThe forwarding works by **replacing the original action with a special agent**. There are different [agent variations](agent/), which all achieve the same: catch activations of the action on the OpenWhisk side, pass them on to the local container and finally return the local result back to the original activation.\n\nThe fastest option (concurrency) leverages the NodeJS concurrency feature available in some OpenWhisk installations where a single container instance will receive all activations. It uses queues implemented as global variables of the action so that multiple invocations of this action (agent) can see and wait for each other.\n\nThe second fastest option - and fastest in case of an OpenWhisk that does not support concurrency - is using the free 3rd party service [ngrok](https://ngrok.com), which supports internet-to-localhost port forwarding. ngrok must be separately installed using `npm install -g ngrok --unsafe-perm=true` and manually selected using `--ngrok` on the command line. This works even without an account on [ngrok.com](https://ngrok.com). _Please note that ngrok.com is not affiliated with Apache OpenWhisk and use is completely optional and up to the user._\n\nLastly, there is the \"activation DB\" agent which simply stores the activation input and result as separate activations (using helper actions named `*_wskdebug_invoked` and `*_wskdebug_completed`) and polls them via `wsk activation list`, both from wskdebug (for new activations) and in the agent itself (waiting for results).\n\nInside the agents waiting for the result is where the limits have an effect: if the invocation is synchronous (blocking=true) or a web action, OpenWhisk will not wait for more than 1 minute. For asynchronous invocations, it depends on the timeout setting of the action. `wskdebug` sets it to 5 minute by default but it can be controlled via `--agent-timeout` to set it to a feasible maximum.\n\nThe debugger works with all normal actions, including web actions. Sequences are not directly supported but can be debugged by starting a debugger for each action in the sequence see [Nodejs Multiple actions](#nodejs-multiple-actions). Compositions itself (not the component actions) are not supported. The solution is only based on custom actions and works with any OpenWhisk system. `wskdebug` was inspired by the now defunct [wskdb](https://github.com/apache/incubator-openwhisk-debugger).\n\n![diagram showing wskdebug](resources/wskdebug-architecture.png)\n\n_This diagram shows how `wskdebug` works including debugging, source mounting and browser LiveReload. The wskdebug components are marked blue. Follow the steps from (1) to (10) to see what happens when the user edits and saves a source file._\n\n\n## Development\n\n\n### Extending wskdebug for other kinds\n\nFor automatic code reloading for other languages, `wskdebug` needs to be extended to support these kinds. This happens inside [src/kinds](src/kinds).\n\n- [Mapping of kinds to docker images](#mapping-of-kinds-to-docker-images)\n- [Custom debug kind](#custom-debug-kind)\n- [Default debug ports and commands](#default-debug-ports-and-commands)\n- [Support code reloading](#support-code-reloading)\n- [Available variables](#available-variables)\n\n\n\n#### Mapping of kinds to docker images\n\nTo change the mapping of kinds to docker images (based on [runtimes.json](https://github.com/apache/incubator-openwhisk/blob/master/ansible/files/runtimes.json) from OpenWhisk), change [src/kinds/kinds.js](src/kinds/kinds.js).\n\n\n#### Custom debug kind\n\nFor default debug instructions and live code reloading, a custom \"debug kind js\" needs to be provided at `src/kinds//.js`.\n\n`` must be without the version, i.e. the part before the `:` in a kind. For example for `nodejs:8` it will be `nodejs`, for `nodejs:default` it will be `nodejs` as well. This is because normally the debug mechanism is the same across language versions. To define a different debug kind, add a `debug` field in [src/kinds/kinds.js](src/kinds/kinds.js) for the particular kind, e.g. for `nodejs:6`set `debug: \"nodejsLegacy\"` and then it must be under `src/kinds/nodejsLegacy/nodejsLegacy.js`.\n\nThis js module needs to export an object with different fields. These can be either a literal value (for simple fixed things such as a port) or a function (allowing for dynamic logic based on cli arguments etc.). These functions get the `invoker` passed as argument, which provides [certain variables](#available-variables) such as cli arguments.\n\nA complete example is the [src/kinds/nodejs/nodejs.js](src/kinds/nodejs/nodejs.js).\n\nSee below for the different items to do.\n\n\n#### Default debug ports and commands\n\nTo just add default debug ports and docker command for a kind, add a custom debug kind and export an object with `description`, `port` and `command` fields. Optionally implement `updateContainerConfig()` for extra container settings (such as passing in environment variables using `-e` or mounting volumes).\n\n\n#### Support code reloading\n\nTo support live code reloading/mounting, add a custom debug kind and export an object with a `mountAction` function. This has to return an action that dynamically loads the code at the start of each activation. A typical approach is to mount the `` (folder) passed on the cli as `/code` inside the docker container, from where the mount action can reload it. The exact mechanism will depend on the language - in node.js for example, `eval()` is [used for plain actions](src/kinds/nodejs/mount-plain.js#L30). The docker mounting can be specified in `updateContainerConfig()`.\n\nThe `mountAction(invoker)` must return an object that is an openwhisk action `/init` definition, which consists of:\n\n* `binary`: true if zip or binary distribution (depends on kind), false if plain code (for scripting languages)\n* `main`: name of the entry function\n* `code`: string with source code or base64 encoded if binary for the live mount\n\nExample mounting actions from nodejs are [mount-plain.js](src/kinds/nodejs/mount-plain.js) (for plain node.js actions) and [mount-require.js](src/kinds/nodejs/mount-require.js) (for action zips expecting node modules using `require()`).\n\n\n#### Available variables\n\nSee also [invoker.js](src/invoker.js). Note that some of these might not be set yet, for example `invoker.debug.port` is not yet available when `port()` is invoked. The raw cli args are usually available as `invoker.`.\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `invoker.main` | `string` | name of the `main` entry point (from cli args) |\n| `invoker.sourcePath` | `string` | path to the source file either `` or the `--build-path` |\n| `invoker.sourceDir` | `string` | absolute path to root directory to mount in the container |\n| `invoker.sourceFile` | `string` | relative path from `sourceDir` to `sourcePath` |\n| `invoker.action` | `object` | the object representing the debugged action, as specified as `Action` model in the [openwhisk REST API spec](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/openwhisk/openwhisk/master/core/controller/src/main/resources/apiv1swagger.json) |\n| `invoker.debug.port` | `number` | `--port` from cli args or `--internal-port` or the `port` from the debug kind js (in that preference) |\n| `invoker.debug.internalPort` | `number` | `--internal-port` from cli args or if not specified, the `port` from the debug kind js |\n| `invoker.debug.command` | `string` | `--command` from cli args or the `command` from the debug kind js (in that preference) |\n\n\n## Contributing\n\nContributions are welcomed! Read the [Contributing Guide](.github/CONTRIBUTING.md) for more information.\n\n\n## Releasing\n\nReleases are done using the [Apache OpenWhisk Release Process](https://github.com/apache/openwhisk-release/blob/master/docs/release_instructions.md).\n\n`wskdebug` releases are made available:\n- on the [Apache OpenWhisk download page](https://openwhisk.apache.org/downloads), stored on Apache mirrors (canonical signed releases)\n- on NPM as [@openwhisk/wskdebug](https://www.npmjs.com/package/@openwhisk/wskdebug) (for convenience, not signed)\n- as [Github Releases](https://github.com/apache/openwhisk-wskdebug/releases) (for tracking release history, linked to source history, not signed)\n\n\n## Licensing\n\nThis project is licensed under the Apache V2 License. See [LICENSE](LICENSE) for more information.\n"}