@ibm-functions/composer

Composer is a new programming model for composing 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.

Composer 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 and deploy commands for compiling and deploying compositions,
• documentation, examples, and tests.

Installation

Composer is distributed as Node.js package. To install this package, use the Node Package Manager:

npm install -g @ibm-functions/composer

We recommend installing the package globally (with -g option) if you intend to use the compose and deploy commands to compile and deploy compositions.

Defining a composition

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

const composer = require('@ibm-functions/composer')

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

Compositions compose actions using combinator methods. These methods implement the typical control-flow constructs of an imperative programming language. This example composition composes three actions named authenticate, success, and failure using the composer.if combinator, which implements the usual conditional construct. It takes 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 shortened to:

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

Deploying a composition

One way to deploy a composition is to use the compose and deploy commands:

compose demo.js > demo.json
deploy demo demo.json -w

ok: created /_/authenticate,/_/success,/_/failure,/_/demo

The compose command compiles the composition code to a portable JSON format. The deploy command deploys the JSON-encoded composition creating an action with the given name. It also deploys the composed actions if definitions are provided for them. The -w option authorizes the deploy command to overwrite existing definitions.

Running a composition

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

ibmcloud fn action invoke demo -p password passw0rd

ok: invoked /_/demo with id 09ca3c7f8b68489c8a3c7f8b68b89cdc

The result of this invocation is the result of the last action in the composition, in this case the failure action since the password in incorrect:

ibmcloud fn activation result 09ca3c7f8b68489c8a3c7f8b68b89cdc

{
    "message": "failure"
}

Execution tr