@voiceflow/general-runtime

[!WARNING] Update April 24, 2024: the open-source general-runtime deployment will no longer be actively supported. A longer term sunset plan will be provided. It is not recommended to create dependencies or references to this respository.

---

general-runtime

general-runtime is an http webhook service that handles voiceflow prototype requests and generates a response. It manages the state of the user based on the programs (flows) made on the Voiceflow Creator tool. This can be hosted independently from Voiceflow.

This is the same service that powers the Voiceflow test tool and Voiceflow DM API. This includes supporting production apps and handling millions of requests.

Documentation

For a high level understanding of what the service is doing, reference "What is the Voiceflow API and how do you use it?".

To interact with your general-runtime server, reference the Voiceflow DM API. Instead of the default https://general-runtime.voiceflow.com, use your own local or remote endpoint.

Setup (Local)

run yarn in command line to install all dependencies.

For the isolated-vm dependency, there are additional steps to install here

Add the following file to the local repository:

.env.local

PORT=4000
LOG_LEVEL="info"
MIDDLEWARE_VERBOSITY="none"

SESSIONS_SOURCE='local'
GENERAL_SERVICE_ENDPOINT='https://general-service.voiceflow.com'

# use local vfr file under /projects
PROJECT_SOURCE='[VFFILE.vfr]'

For more info on Environment Variables

Use yarn start:local to run the development version.

For the production version, run yarn build followed by yarn start (this checks against .env.production instead of .env.local)

Docker

[!WARNING]
There are private npm dependencies required to build this image that the general public does not have access to

[!IMPORTANT] We rely on BuildKit features such as COPY --link and therefore require Docker version >= 24

There is a provided script for building the Docker image locally at ./local-build.sh. It will read from the following environment variables:

EnvVar Name	Default	Required	Description
NPM_TOKEN		x	Required for private voiceflow package dependencies
TARGET	prod		Stage to target in the Dockerfile
IMAGE_TAG	TARGET		Resulting image tag (general-runtime:<IMAGE_TAG>)
PLATFORMS	linux/amd64		buildx build flag
DOCKERFILE	Dockerfile		Location of the Dockerfile
BUILDER	buildy		Name of docker-container builder to use
NO_CACHE_FILTER			Ignore build cache for specific stages

Notable Code Locations

Context Handlers (documentation)- handlers for processing request
lib/services/runtime/handlers - handlers for all the various nodes and defining their behavior
runtime/lib/Runtime/cycleStack - iterator and execution of flows
runtime/lib/Runtime/cycleHandler - iterator and execution of individual nodes

API Documentation (Open API)

Documentation for all API Endpoints on this service. It is critical to make sure all OpenAPI docs are up to date:

https://github.com/voiceflow/general-runtime/tree/master/src/legacy/backend/docs/openapi.yaml

Whenever any of the paths change, or new ones get added, or if any of the behaviors documented change, be sure to update the Open API doc. Recommend to use an editor like Swagger Editor or Stoplight to help construct the YAML file, and then fine tune things on local.

Local Setup

Run npm i -g redoc-cli to install as command.

While on the root of this repository, run

redoc-cli serve src/legacy/backend/docs/openapi.yaml --ssr --watch

to see it locally - note: this will not load the local CSS file.

If your browser autoresolves http://localhost to https://localhost, you might want to open the local link in incognito or a different browser.

Integration tests

link to integration tests