https://github.com/stencila/executa
⚡ Execution engine for executable documents
https://github.com/stencila/executa
Last synced: 10 months ago
JSON representation
⚡ Execution engine for executable documents
- Host: GitHub
- URL: https://github.com/stencila/executa
- Owner: stencila
- Created: 2019-09-30T03:11:15.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-16T11:01:50.000Z (about 1 year ago)
- Last Synced: 2025-04-16T14:43:30.674Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 3.15 MB
- Stars: 7
- Watchers: 3
- Forks: 0
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# ⚡ Executa
#### Execution engine for executable documents
[](https://dev.azure.com/stencila/stencila/_build/latest?definitionId=4&branchName=master)
[](https://codecov.io/gh/stencila/executa)
[](https://www.npmjs.com/package/@stencila/executa)
## Install
```bash
npm install --global @stencila/executa
```
## Use
All configuration options can be set, in descending order of priority, by:
- a command line argument e.g. `-- `
- an environment variable prefixed with `EXECUTA_` e.g. `EXECUTA_=`
- 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.
```bash
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):
```bash
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 `` 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.
```bash
npm run cli:debug -- serve --http
```
> The `:debug` suffix to `cli` enables the Node [debug inspector](https://nodejs.org/en/docs/guides/debugging-getting-started/) 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.