Repository files navigation

Composer is a new programming model for composing cloud functions built onApache OpenWhisk. WithComposer, developers can build even more serverless applications including usingit for IoT, with workflow orchestration, conversation services, and devopsautomation, to name a few examples.

Composer synthesizes OpenWhiskconductoractionsto implement compositions. Compositions have all the attributes and capabilitiesof an action, e.g., default parameters, limits, blocking invocation, web export.

This repository includes:

• thecomposer Node.js module for authoring compositions usingJavaScript,
• thecompose anddeploycommands for compiling and deploying compositions,
• documentation,examples, andtests.

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

npm install -g @ibm-functions/composer

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

A composition is typically defined by means of a JavaScript expression asillustrated insamples/demo.js:

constcomposer=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 usingcombinator methods.These methods implement the typical control-flow constructs of an imperativeprogramming language. This example composition composes three actions namedauthenticate,success, andfailure using thecomposer.if combinator,which implements the usual conditional construct. It takes three actions (orcompositions) as parameters. It invokes the first one and, depending on theresult of this invocation, invokes either the second or third action.

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

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

One way to deploy a composition is to use thecompose anddeploy commands:

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

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

Thecompose command compiles the composition code to a portable JSON format.Thedeploy command deploys the JSON-encoded composition creating an actionwith the given name. It also deploys the composed actions if definitions areprovided for them. The-w option authorizes thedeploy command to overwriteexisting definitions.

Thedemo composition may be invoked like any action, for instance using theIBM 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 thecomposition, in this case thefailure action since the password in incorrect:

ibmcloud fn activation result 09ca3c7f8b68489c8a3c7f8b68b89cdc

{"message":"failure"}

This invocation creates a trace, i.e., a series of activation records:

ibmcloud fn activation list

Datetime            Activation ID                    Kind     Start Duration   Status  Entity2019-03-15 16:43:22 e6bea73bf75f4eb7bea73bf75fdeb703 nodejs:10 warm  1ms        success guest/demo:0.0.12019-03-15 16:43:21 7efb6b7354c3472cbb6b7354c3272c98 nodejs:10 cold  31ms       success guest/failure:0.0.12019-03-15 16:43:21 377cd080f0674e9cbcd080f0679e9c1d nodejs:10 warm  2ms        success guest/demo:0.0.12019-03-15 16:43:20 5dceeccbdc7a4caf8eeccbdc7a9caf18 nodejs:10 cold  29ms       success guest/authenticate:0.0.12019-03-15 16:43:19 66355a1f012d4ea2b55a1f012dcea264 nodejs:10 cold  104ms      success guest/demo:0.0.12019-03-15 16:43:19 09ca3c7f8b68489c8a3c7f8b68b89cdc sequence warm  3.144s     success guest/demo:0.0.1

The entry with the earliest start time (09ca3c7f8b68489c8a3c7f8b68b89cdc)summarizes the invocation of the composition while other entries record lateractivations caused by the composition invocation. There is one entry for eachinvocation of a composed action (5dceeccbdc7a4caf8eeccbdc7a9caf18 and7efb6b7354c3472cbb6b7354c3272c98). The remaining entries record the beginningand end of the composition as well as the transitions between the composedactions.

Compositions are implemented by means of OpenWhisk conductor actions. Thedocumentation of conductoractionsexplains 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 actioninvocations in a composition as well as an upper bound on the rate ofinvocation. These limits may result in compositions failing to execute tocompletion.

Composer offers parallel combinators that make it possible to run actions orcompositions in parallel, for example:

composer.parallel('checkInventory','detectFraud')

The width of parallel compositions is not in principle limited by composer, butissuing many concurrent invocations may hit OpenWhisk limits leading tofailures: failure to execute a branch of a parallel composition or failure tocomplete the parallel composition.

These combinators require access to a Redis instance to hold intermediateresults of parallel compositions. The Redis credentials may be specified atinvocation time or earlier by means of default parameters or package bindings.The required parameter is named$composer. It is a dictionary with aredisfield of type dictionary. Theredis dictionary specifies theuri for theRedis instance and optionally a certificate as a base64-encoded string to enableTLS connections. Hence, the input parameter object for our order-processingexample 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 compositionis progressing. Redis entries are deleted after completion and, as an addedsafety, expire after twenty-four hours.

Additional configuration is required when using an OpenWhisk instance withself-signed certificates to disable SSL certificate validation. The inputparameter object must contain a parameter of type dictionary named$composer.This dictionary must contain a dictionary namedopenwhisk. Theopenwhiskdictionary must contain a field namedignore_certs with valuetrue:

{"$composer": {"openwhisk": {"ignore_certs":true        }    },...}

This explicit SSL configuration is currently only necessary when using parallelcombinators or theasync combinator.

To install composer from a source release, download the composer source codefromour GitHub repo,rename the release tarball tocomposer.tgz and install it with command:

npm install -g composer.tgz