⚡ Executa

Execution engine for executable documents

Install

npm install --global @stencila/executa

Use

All configuration options can be set, in descending order of priority, by:

• a command line argument e.g. --<value> <value>
• an environment variable prefixed with EXECUTA_ e.g. EXECUTA_<option>=<value>
• a .json or .ini configuration file, set using the --config option, or .executarc by default

| Name | Description | Type | Validators | Default | | ------------- | ------------------------------------------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------- | --------------- | | debug | Display debug log data? | boolean | | false | | stdio | Start a stdio server. | boolean | | false | | vsock | Start a vsock server.1 | boolean | number | | false | | tcp | Start a TCP server.2 | boolean | string | pattern: /^((tcp?://)?([^:/]+)(:(d+))?(/(.+))?)|(d+)$/ | false | | http | Start a HTTP server.3 | boolean | string | pattern: /^((https?://)?([^:/]+)(:(d+))?(/(.+))?)|(d+)$/ | false | | ws | Start a WebSocket server.4 | boolean | string | pattern: /^((wss?://)?([^:/]+)(:(d+))?(/(.+))?)|(d+)$/ | false | | timeout | Duration of inactivity after which the process should stop.5 | number | | 0 | | timelimit | Maximum duration for the process.6 | number | | 0 | | peers | List of peer addresses.7 | string[] | | ["stdio://*"] | | queueLength | Maximum length of the request queue.8 | number | minimum: 0 | 1000 | | queueInterval | Interval between attempts to reduce request queue.9 | number | exclusiveMinimum: 0 | 1 | | queueStale | Duration after which a request is removed from queue.10 | number | exclusiveMinimum: 0 | 3600 |

1. If a number, it will be used as the port number. If true, the default Vsock port 6000 will be used.
2. If a string, it will be parsed and used as the address of the TCP server. If true, the default TCP address tcp://127.0.0.1:7000 will be used.
3. If a string, it will be parsed and used as the address of the HTTP server. If true, the default HTTP address http://127.0.0.1:8000 will be used.
4. If a string, it will be parsed and used as the address of the WebSocket server. If true, the default WebSocket address ws://127.0.0.1:9000 will be used.
5. Seconds. Zero means no timeout.
6. Seconds. Zero means no time limit.
7. Each string in this list is parsed as an address to a peer executor. e.g. https://123.45.67.89/, docker://image
8. When queue reaches this length, subsequent requests will fail with an error response to client.
9. Seconds.
10. Seconds. Client will be notified when a request is removed.

Develop

Testing with the REPL

There is an interactive REPL that can be used with the both query and execute CLI commands e.g.

npm run cli -- execute --repl --debug

Testing in the browser

1. Serve Executa over HTTP (to provide static HTML) and WebSocket (to provide JSON RPC):

   npm run cli:dev -- serve --http --ws

The :dev suffix to cli uses ts-node-dev which will restart the process when any source files change.

2. Visit http://localhost:8000 in your browser and play around with the <stencila-code-chunk> WebComponent that is connected to the Executa WebSocket that you just started.

Debug inspecting

There is a NPM script, cli:debug, that can be useful for debugging the CLI, for example, from within VSCode (which will auto attach to the Node process), e.g.

npm run cli:debug -- serve --http

The :debug suffix to cli enables the Node debug inspector so you can use your favorite IDE to attach to the CLI and step through the code.

FAQ

Why is @types/ws a production dependency?

This package has several dependents e.g @stencila/basha. If @types/ws is not installed as a production dependency, when you try to build dependent packages, you get the error "Cannot find type definition file for 'ws'.". By having it as a production dependency here, each dependent package does not have to install it as a development dependency.