Forge bundler
The bundler package is responsible for compiling the user code, including
dependencies (NPM packages), into files that get uploaded to AWS Lambda.
This is required for two reasons:
- Forge only runs JavaScript functions (on either sandbox or Node runtime),
so TypeScript has to be compiled to JavaScript.
- All files that the user code imports need to be available when the Forge
function runs.
The bundler is used:
- When deploying a Forge app (
forge deploy
) - When running an app locally (
forge tunnel
)
Implementation
Bundler uses webpack to compile user code.
Every entry point from the manifest (referenced in modules.function.handler
)
and resource for Native UI is compiled into a single JavaScript file
containing all of its dependencies.
Sandbox runtime
Some built-in Node modules and globals are not exposed in the
sandbox JavaScript environment.
Accessing those at runtime would throw an error.
Where possible, the unavailable modules and globals are replaced with
compatible implementations using
ProvidePlugin and
alias
. If
there is no point in providing an implementation altogether (e.g. dns
module), it is replaced with a stub showing an "unsupported" message.
Some NPM modules provide different implementations for "browser" and "node"
environments, based on
package-browser-field-spec.
Even though Forge functions run in Node.js, our environment is more compatible
with "browser" implementations. The sandbox Webpack configuration sets the
resolve
options to prefer those.
Node runtime
The interface for the Forge functions is different from the XIS interface, see
Node runtime: Technical Details.
Therefore, a layer of wrapper code is required to convert the calls and
responses.
To maintain the correspondence between AWS Lambda handler and the handler in
the Forge manifest, the bundled user code is put into a new location, with the
wrapper code left in the original place. For example, if the manifest
specifies index.run
as the handler, AWS Lambda function will have:
index.js
- wrapper codebundled/index.js
- bundled user code from src/index.js
The wrapper code, when invoked:
- Parses the invocation request from XIS
- Sets up the environment (e.g. user variables) for the Forge function run
- Loads the user code
- Invokes the user code
- Converts the result or error to the XIS response format and returns it
The wrapper cannot load the user code before the environment is set up, as any
actions that the user code does upon initialization might fail (e.g. because
the proxy token is not yet set up).
However, wrapper needs to know which exports to make available. This
information is passed to the bundler from the manifest: if it contains
index.run
and index.another
as handlers, then the wrapper for index.js
will need to export run
and another
. Bundler uses
BannerPlugin to add this as a
constant to each wrapper.
To redirect console calls from the user code to Xen Logs Ingestor that backs
forge logs
and the Forge Developer console, occurrences console
are
replaced with a custom implementation via
ProvidePlugin.
Native UI
TODO: Not documented