Allow Aerie actions to access & run functions from sequencing adaptation

[dandelany]

Summary

Allow aerie-actions to retrieve the workspace's JS sequence adaptation (from the Parcel) and call exported functions from it at runtime.

Background

Users would like to be able to edit sequences in the editor using their authoring language (aka inputFormat), and then invoke Actions which require the sequence in its output language(s). For example, FRESH (a static checking service) operates on seq-json and we'd like to invoke it from an action called on a SeqN file. Aerie no longer maintains copies of both formats like it used to, so we need a new way to support this use case.

Each sequencing workspace has a Parcel associated with it, which contains dictionaries + the Sequence Adaptation. The adaptation contains (among other things) JS functions for translating between formats. If actions were able to use these functions, users could invoke the action with the inputFormat sequence, and the action could translate it to outputFormat before sending it to eg. FRESH.

However, the aerie-actions API currently gives access to the dictionaries in the parcel (eg. readCommandDictionary()), but not the adaptation. Users could import & bundle their adaptations into the action, but this risks getting out-of-sync: the adaptation may change over time, and they would have to re-build a new version of the action with the new adaptation every time.

Therefore, we propose updating the Actions API to support calling JS functions from the adaptation within the context of the action.

Requirements

• The readParcel() function in aerie-actions will need to be updated to return the adaptation ID (sequence_adaptation_id)
• A new function should be added to the aerie-actions API which retrieves the adaptation from the database and loads/evaluates it.
  • async function readAdaptation(number adaptationId) { ... }
  • The return type of this should match the sequence adaptation type used by aerie-ui - we can discuss with @cartermak whether it makes sense to import this from the aerie-sequence-languages library or copy it.
  • The adaptation result should be validated and then evaled or similar (as safely as possible) so that users may call functions on it eg. adaptation.outputs[0].toOutputFormat(...)

API example

This is roughly how we imagine actions using this API (inside an action's main function):

// get the sequence file and parcel (this part already exists)
const sequencePath = parameters.sequence;
const sequenceContents = await actionsAPI.readFile(sequencePath);
const parcel = await actionsAPI.readParcel();
// new field on parcel
const adaptationId = parcel.sequence_adaptation_id;
// new: retrieve adaptation from ID
const adaptation = await actionsAPI.readAdaptation(parcel.adaptationId);
// users will likely also need to retrieve one or more dictionaries from the parcel
// since translation functions often require them to be passed in as context
const commandDictionary = await actionsAPI.readCommandDictionary(parcel.command_dictionary_id);
const phoenixContext = {commandDictionary, ...}
// new: can call functions on the adaptation
const translatedSequence = adaptation.outputs[0].toOutputFormat(sequenceContents, phoenixContext, sequencePath);
// now we have the translated contents of the sequence and can pass it along to other services
await fetch(settings.fresh_service_url, ....);

Security Concerns

Usually, evaluating code from userspace is considered unsafe/bad practice, so it's worth a few notes on why it makes sense in this case:

• We are generally operating with a trusted user security model, assuming a limited & closed Aerie deployment not open to the Internet.
• Both adaptations (parcels) and actions, which are the two things which contain user-defined JS, may only be created by users with aerie-admin role
• These are the only two types of user JS we allow. Aerie core code will never eg. evaluate JS from a user-provided URL, we are only loading & evaluating these two
• We are already executing user adaptation code on the frontend. Providing code for Aerie to run is the central value proposition of Adaptations.