@ibm-functions/composer

@ibm-functions/composer

Composer is a new programming model from IBM Research for composing IBM Cloud Functions, built on Apache OpenWhisk. With Composer, developers can build even more serverless applications including using it for IoT, with workflow orchestration, conversation services, and devops automation, to name a few examples.

Programming compositions for IBM Cloud Functions is supported by a new developer tool called IBM Cloud Shell, or just Shell. Shell offers a CLI and graphical interface for fast, incremental, iterative, and local development of serverless applications. While we recommend using Shell, Shell is not required to work with compositions. Compositions may be managed using a combination of the Composer compose shell script (for deployment) and the OpenWhisk CLI (for configuration, invocation, and life-cycle management).

In contrast to earlier releases of Composer, a REDIS server is not required to run compositions. Composer now synthesizes OpenWhisk conductor actions to implement compositions. Compositions have all the attributes and capabilities of an action (e.g., default parameters, limits, blocking invocation, web export).

This repository includes:

• the composer Node.js module for authoring compositions using JavaScript,
• the compose shell script for deploying compositions,
• documentation, examples, and tests.

Composer and Shell are currently available as IBM Research previews. As Composer and Shell continue to evolve, it may be necessary to redeploy existing compositions to take advantage of new capabilities. However existing compositions should continue to run fine without redeployment.

Installation

To install the composer module use the Node Package Manager:

npm -g install @ibm-functions/composer

We recommend to install the module globally (with -g option) so the compose command is added to the path. Otherwise, it can be found in the bin folder of the module installation.

Example

A composition is typically defined by means of a Javascript file as illustrated in samples/demo.js:

composer.if(
    composer.action('authenticate', { action: function main({ password }) { return { value: password === 'abc123' } } }),
    composer.action('success', { action: function main() { return { message: 'success' } } }),
    composer.action('failure', { action: function main() { return { message: 'failure' } } }))

Composer offers traditional control-flow concepts as methods. These methods are called combinators. This example composition composes three actions named authenticate, success, and failure using the composer.if combinator, which implements the usual conditional construct. It take three actions (or compositions) as parameters. It invokes the first one and, depending on the result of this invocation, invokes either the second or third action.

This composition includes the definitions of the three composed actions. If the actions are defined and deployed elsewhere, the composition code can be shorten to:

composer.if('authenticate', 'success', 'failure')

To deploy this composition use the compose command:

compose demo.js --deploy demo

The compose command synthesizes and deploy an action named demo that implements the composition. It also deploys the composed actions if definitions are provided for them.

The demo composition may be invoked like any action, for instance using the OpenWhisk CLI:

wsk action invoke demo -r -p password passw0rd

{
    "message": "failure"
}

Getting started

• Introduction to Serverless Composition: Setting up your programming environment and getting started with Shell and Composer.
• Building a Translation Slack Bot with Serverless Composition: A more advanced tutorial using Composition to build a serverless Slack chatbot that does language translation.
• Composer Reference: A comprehensive reference manual for the Node.js programmer.

Videos

• The IBM Cloud Shell YouTube channel hosts demo videos of IBM Cloud Shell, including editing a composition using a built-in editor or an external editor, and visualizing a composition's execution.
• Watch our presentation at Serverlessconf'17 about Composer and Shell.
• Conductor Actions and Composer v2 (29:30 minutes into the video): A discussion of the composition runtime.

Blog posts

• Serverless Composition with IBM Cloud Functions
• Building Your First Serverless Composition with IBM Cloud Functions
• Upgrading Serverless Superman to IBM Composer
• Calling Multiple Serverless Actions and Retaining Values with IBM Composer
• Serverless Try/Catch/Finally with IBM Composer
• Composing functions into applications
• A composition story: using IBM Cloud Functions to relay SMS to email

Contributions

We are looking forward to your feedback and criticism. We encourage you to join us on slack. File bugs and we will squash them.

We welcome contributions to Composer and Shell. See CONTRIBUTING.md.