@ibm-functions/composer
v1.0.0
Published
Composer is a new programming model for composing cloud functions built on Apache OpenWhisk.
Downloads
5
Readme
@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 traces
This invocation creates a trace, i.e., a series of activation records:
ibmcloud fn activation list
The entry with the earliest start time (09ca3c7f8b68489c8a3c7f8b68b89cdc
)
summarizes the invocation of the composition while other entries record later
activations caused by the composition invocation. There is one entry for each
invocation of a composed action (5dceeccbdc7a4caf8eeccbdc7a9caf18
and
7efb6b7354c3472cbb6b7354c3272c98
). The remaining entries record the beginning
and end of the composition as well as the transitions between the composed
actions.
Compositions are implemented by means of OpenWhisk conductor actions. The documentation of conductor actions explains execution traces in greater details.
While composer does not limit in principle the length of a composition, OpenWhisk deployments typically enforce a limit on the number of action invocations in a composition as well as an upper bound on the rate of invocation. These limits may result in compositions failing to execute to completion.
Parallel compositions with Redis
Composer offers parallel combinators that make it possible to run actions or compositions in parallel, for example:
composer.parallel('checkInventory', 'detectFraud')
The width of parallel compositions is not in principle limited by composer, but issuing many concurrent invocations may hit OpenWhisk limits leading to failures: failure to execute a branch of a parallel composition or failure to complete the parallel composition.
These combinators require access to a Redis instance to hold intermediate
results of parallel compositions. The Redis credentials may be specified at
invocation time or earlier by means of default parameters or package bindings.
The required parameter is named $composer
. It is a dictionary with a redis
field of type dictionary. The redis
dictionary specifies the uri
for the
Redis instance and optionally a certificate as a base64-encoded string to enable
TLS connections. Hence, the input parameter object for our order-processing
example should be:
{
"$composer": {
"redis": {
"uri": "redis://...",
"ca": "optional base64 encoded tls certificate"
}
},
"order": { ... }
}
The intent is to store intermediate results in Redis as the parallel composition is progressing. Redis entries are deleted after completion and, as an added safety, expire after twenty-four hours.
OpenWhisk SSL configuration
Additional configuration is required when using an OpenWhisk instance with
self-signed certificates to disable SSL certificate validation. The input
parameter object must contain a parameter of type dictionary named $composer
.
This dictionary must contain a dictionary named openwhisk
. The openwhisk
dictionary must contain a field named ignore_certs
with value true
:
{
"$composer": {
"openwhisk": {
"ignore_certs": true
}
},
...
}
This explicit SSL configuration is currently only necessary when using parallel
combinators or the async
combinator.
Installation from Source
To install composer from a source release, download the composer source code
from our GitHub repo,
rename the release tarball to composer.tgz
and install it with command:
npm install -g composer.tgz