Runtime

ScriptRunner Connect runtime is a custom JavaScript runtime based on Google's V8 engine, which offers strong security guarantees for isolating script executions. Because we have our own runtime, it's incompatible with other runtimes, such as Node or Deno. However, we are embracing implementing standardized APIs whenever possible and generally aim to be compatible with other runtimes of a similar nature. We welcome and aim to be compatible with the WinterCG initiative.

How does that affect you?

When you want to include an NPM package in your workspace, it may not be (fully) compatible with our runtime if it's built exclusively for Node or uses browser-based APIs which we don't support. This does not mean that you can't use any NPM package. There are many packages out there that solve the same problem; you just have to try a different one that may be written to utilize (more modern) standardized APIs. For example, an NPM package that uses Node's crypto module under the hood wouldn't work because we don't support that API. However, if you find a different package that does the same job and uses Web Crypto API, which is standardized, it's more than likely to work (although our Web Crypto support is currently partial).

We'll be curating a list of verified (to work in our runtime) third-party NPM packages, which you can easily pick from, but you can try out any NPM package you desire. 

Enhanced isolation mode

Although V8 is very robust in ensuring isolation, no software is immune to bugs and zero-day vulnerabilities. By default, a new V8 isolate is created and destroyed per request and is executed in a shared pool of AWS Lambdas. However, a theoretical vulnerability still exists where a sandbox escape is possible from the V8 isolate, which could lead to an AWS Lambda runtime instance being unintentionally altered. As an extra layer of security, you can enable enhanced isolation mode at the workspace level (go to edit workspace to enable it) that will cause scripts from enabled workspaces to run in a tenant isolation mode in Lambda, which means that the code running in enhanced isolation mode runs in a pool of Lambdas that are only allocated for a given team. Should a sandbox escape event occur, the malicious actor won't be able to reach other AWS Lambda instances running in tenant isolation mode.

Caveat

AWS Lambda functions experience a phenomenon known as cold starts. This means that whenever a new Lambda instance needs to be created to process a new request, it must go through the initialisation phase, which incurs additional latency. In the ScriptRunner Connect runtime, this latency is typically 2-3 seconds. By default, this is almost unnoticeable because we collectively process a large volume of scripts, and the likelihood of consistently hitting a cold Lambda is quite low. However, when you enable enhanced isolation mode, you'll start running your scripts in an isolated pool of Lambda instances dedicated to your team, which most likely will lead to an increased occurrence of cold-starts, unless your scripts are being processed in a very uniform manner (constant and frequent load with very few spikes). For most workloads, the extra 1-2 seconds of delay should not be a concern. Still, in a few cases, such as processing Sync HTTP event listeners, where response times are time-critical, you may want to trade off extra security for performance by turning off enhanced isolation mode (which is less likely to cause cold starts).

Supported APIs

By default, V8 has a core standard library for JavaScript (ECMAScript 2020).

On top of the core standard library, we have added support for the following APIs:

• console

  • log

  • trace

  • debug

  • info

  • warn

  • error

  • assert

  • count

  • countReset

  • time

  • timeLog

  • timeEnd

  • group

  • groupCollapsed

  • groupEnd

• performance

  • now

• crypto (can also be accessed as window.crypto)

  • gerRandomValues

• crypto.subtle (can also be accessed as window.crypto.subtle)

  • generateKey

  • exportKey

  • importKey

  • sign

  • verify

• fetch (partial implementation, but all the essentials are implemented)

• btoa

• atob

• setTimeout

• clearTimeout

• Headers

• Blob

• FormData

• URL

• URLSearchParams

• TextEncoder

• TextDecoder

If you're interested in TS types for our runtime, you can find them here.

Known limitations

Unhandled promise rejections are not captured and logged for floating promises. We recommend taking caution not to fire off a promise without awaiting completion, or adding a catch method to capture any possible errors.

Versions

Runtime version allows you to control which version of the runtime your scripts are running on the workspace level. You can change the version by navigating to the Workspace Edit setting and selecting the Runtime version. Currently, the default version for all existing workspaces is V1, while new workspaces will be configured to use V2. 

Runtime version selection is only available during the transitional periods when the ScriptRunner Connect team is releasing a new runtime version. Historically, we have performed runtime upgrades in the background, but since upgrading the underlying Node and V8, versions can introduce changes in how memory is used, so we have now opted to use staged releases. For a short period, both versions will remain available, allowing you to switch to the new version while the old version remains as a rollback option. 

Changelog

V2

• Internal implementations of TextEncoder and TextDecoder APIs are upgraded. These APIs are used internally by Managed API's HTTP response text and JSON methods, thereby affecting many scripts. The new implementation should use significantly less memory, allowing it to decode larger HTTP responses without running out of memory as quickly.
• Introducing the fastTransfer option for some APIs that work with ArrayBuffers. By default, when you pass an ArrayBuffer as a parameter to an API, the contents of the ArrayBuffer will be copied. When you're performing a lot of these operations, and ArrayBuffers tend to be larger in size, you're spending CPU time just on copying the content over. To speed up such operations, you can now optionally enable fastTransfer mode, which, instead of copying the content, will pass along the reference of the ArrayBuffer instead, which is a constant-time operation. As a consequence of passing the reference, the ArrayBuffer reference in your script becomes invalidated (de-referenced), meaning that you no longer can access the content or edit your ArrayBuffer, henceforward, which in most cases you wouldn't need anyway. Trying to read from an invalidated ArrayBuffer or edit it will either return an empty byte array or throw an error. If you need to continue reading or editing the contents of the ArrayBuffer after you have passed its reference into an API, simply do not enable this mode. The following APIs have this option available:
  • TextDecoder's decode method accepts the fastTransfer option
    
  • @sr-connect/convert's convertBufferToText and convertBufferToBase64 functions accept fastTransfer option.