Skip to content
This repository was archived by the owner on Jan 17, 2025. It is now read-only.

Commit 838a30f

Browse files
tardieutardieu
authored
Add instructions, examples, and resources to README (#40)
* Add resources to README * Add install and example sections to README.md
1 parent 516164d commit 838a30f

File tree

4 files changed

+222
-40
lines changed

4 files changed

+222
-40
lines changed

‎README.md

Lines changed: 131 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,142 @@
1+
# @ibm-functions/composer
2+
13
[![Travis](https://travis-ci.org/ibm-functions/composer.svg?branch=master)](https://travis-ci.org/ibm-functions/composer)
24
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
3-
[![Join Slack](https://img.shields.io/badge/join-slack-9B69A0.svg)](http://slack.openwhisk.org/)
5+
[![Join
6+
Slack](https://img.shields.io/badge/join-slack-9B69A0.svg)](http://slack.openwhisk.org/)
47

58
Composer is a new programming model from [IBM
6-
Research](https://ibm.biz/serverless-research) for composing [IBM
7-
Cloud Functions](https://ibm.biz/openwhisk), built on [Apache
8-
OpenWhisk](https://github.com/apache/incubator-openwhisk).
9-
With composer, developers can build even more serverless applications including using it for IoT, with workflow
10-
orchestration, conversation services, and devops automation, to name a
11-
few examples.
9+
Research](https://ibm.biz/serverless-research) for composing [IBM Cloud
10+
Functions](https://ibm.biz/openwhisk), built on [Apache
11+
OpenWhisk](https://github.com/apache/incubator-openwhisk). With Composer,
12+
developers can build even more serverless applications including using it for
13+
IoT, with workflow orchestration, conversation services, and devops automation,
14+
to name a few examples.
15+
16+
Programming compositions for IBM Cloud Functions is supported by a new developer
17+
tool called [IBM Cloud Shell](https://github.com/ibm-functions/shell), or just
18+
_Shell_. Shell offers a CLI and graphical interface for fast, incremental,
19+
iterative, and local development of serverless applications. While we recommend
20+
using Shell, Shell is not required to work with compositions. Compositions may
21+
be managed using a combination of the Composer [compose](bin/compose) shell
22+
script (for deployment) and the [OpenWhisk
23+
CLI](https://console.bluemix.net/openwhisk/learn/cli) (for configuration,
24+
invocation, and life-cycle management).
1225

13-
Programming compositions for IBM Cloud Functions is done via a new developer tool called [IBM Cloud Shell](https://github.com/ibm-functions/shell), or just _Shell_. Shell offers a CLI and graphical interface for fast, incremental, iterative, and local development of serverless apps. Composer and shell are currently available as IBM Research previews. We are excited about both and are looking forward to the compositions you build and run using [IBM CloudFunctions](https://ibm.biz/openwhisk) or directly on [Apache
14-
OpenWhisk](https://github.com/apache/incubator-openwhisk).
26+
**In contrast to earlier releases of Composer, a REDIS server is not required to
27+
run compositions**. Composer now synthesizes OpenWhisk [conductor
28+
actions](https://github.com/apache/incubator-openwhisk/blob/master/docs/conductors.md)
29+
to implement compositions. Compositions have all the attributes and capabilities
30+
of an action (e.g., default parameters, limits, blocking invocation, web
31+
export).
1532

1633
This repository includes:
17-
* a [composer](composer.js) node.js module to author compositions using JavaScript
18-
* a [compose](bin/compose) shell script for deploying compositions,
19-
* a [tutorial](docs/README.md) for getting started,
20-
* a [reference manual](docs/COMPOSER.md),
21-
* example compositions in the [samples](samples) folder,
22-
* tests in the [test](test) folder.
34+
* the [composer](composer.js) Node.js module for authoring compositions using
35+
JavaScript,
36+
* the [compose](bin/compose) shell script for deploying compositions,
37+
* [documentation](docs), [examples](samples), and [tests](test).
38+
39+
Composer and Shell are currently available as _IBM Research previews_. As
40+
Composer and Shell continue to evolve, it may be necessary to redeploy existing
41+
compositions to take advantage of new capabilities. However existing
42+
compositions should continue to run fine without redeployment.
43+
44+
## Installation
45+
46+
To install the `composer` module use the Node Package Manager:
47+
```
48+
npm -g install @ibm-functions/composer
49+
```
50+
We recommend to install the module globally (with `-g` option) so the `compose`
51+
command is added to the path. Otherwise, it can be found in the `bin` folder of
52+
the module installation.
53+
54+
## Example
55+
56+
A composition is typically defined by means of a Javascript file as illustrated
57+
in [samples/demo.js](samples/demo.js):
58+
```javascript
59+
composer.if(
60+
composer.action('authenticate', { action: function main({ password }) { return { value: password === 'abc123' } } }),
61+
composer.action('success', { action: funcßtion main() { return { message: 'success' } } }),
62+
composer.action('failure', { action: function main() { return { message: 'failure' } } }))
63+
```
64+
Composer offers traditional control-flow concepts as methods. These methods
65+
are called _combinators_. This example composition composes three actions named
66+
`authenticate`, `success`, and `failure` using the `composer.if` combinator,
67+
which implements the usual conditional construct. It take three actions (or
68+
compositions) as parameters. It invokes the first one and, depending on the
69+
result of this invocation, invokes either the second or third action.
70+
71+
This composition includes the definitions of the three composed actions. If the
72+
actions are defined and deployed elsewhere, the composition code can be shorten
73+
to:
74+
```javascript
75+
composer.if('authenticate', 'success', 'failure')
76+
```
77+
78+
To deploy this composition use the `compose` command:
79+
```
80+
compose demo.js --deploy demo
81+
```
82+
The `compose` command synthesizes and deploy an action named `demo` that
83+
implements the composition. It also deploys the composed actions if definitions
84+
are provided for them.
85+
86+
The `demo` composition may be invoked like any action, for instance using the
87+
OpenWhisk CLI:
88+
```
89+
wsk action invoke demo -r -p password passw0rd
90+
```
91+
```
92+
{
93+
message: "failure"
94+
}
95+
```
2396

2497
## Getting started
25-
* [Introduction to Serverless Composition](docs/README.md): Setting up your programming environment and getting started with Shell and Composer
26-
* [Building a Serverless Translate Bot with Composition](docs/tutorials/translateBot/README.md): A more advanced tutorial that describes using Composition to build a serverless Slack chatbot that does language translation.
27-
* [Learning more about Composer](docs/COMPOSER.md), a Node.js module to author compositions using JavaScript
98+
* [Introduction to Serverless Composition](docs/README.md): Setting up your
99+
programming environment and getting started with Shell and Composer.
100+
* [Building a Translation Slack Bot with Serverless
101+
Composition](docs/tutorials/translateBot/README.md): A more advanced tutorial
102+
using Composition to build a serverless Slack chatbot that does language
103+
translation.
104+
* [Composer Reference](docs/COMPOSER.md): A comprehensive reference manual for
105+
the Node.js programmer.
28106

29107
## Videos
30-
* [IBM Cloud Shell YouTube channel](https://www.youtube.com/channel/UCcu16nIMNclSujJWDOgUI_g): The channel hosts demo videos of IBM Cloud Shell, including editing a composition [using a built-in editor](https://youtu.be/1wmkSYl7EDM) or [an external editor](https://youtu.be/psqoysnVgE4), and [visualizing a composition's execution](https://youtu.be/jTaHgDQDZnQ).
31-
* Watch [our presentation at Serverlessconf'17](https://acloud.guru/series/serverlessconf/view/ibm-cloud-functions) about Composition and Shell
32-
33-
## Example applications
34-
* A _Serverless Superman_ [Twitter Bot](https://www.raymondcamden.com/2017/10/20/upgrading-serverless-superman-to-ibm-composer/)
35-
* An app that [relays SMS to email](https://medium.com/openwhisk/a-composition-story-using-ibm-cloud-functions-to-relay-sms-to-email-d67fc65d29c)
36-
37-
## Feedback
38-
We welcome your feedback and criticism. Find bugs and we will squash
39-
them. And will be grateful for your help. As an early adopter, you
40-
will also be among the first to experience even more features planned
41-
for the weeks ahead. We look forward to your feedback and encourage
42-
you to [join us on slack](http://ibm.biz/composer-users).
108+
* The [IBM Cloud Shell YouTube
109+
channel](https://www.youtube.com/channel/UCcu16nIMNclSujJWDOgUI_g) hosts demo
110+
videos of IBM Cloud Shell, including editing a composition [using a built-in
111+
editor](https://youtu.be/1wmkSYl7EDM) or [an external
112+
editor](https://youtu.be/psqoysnVgE4), and [visualizing a composition's
113+
execution](https://youtu.be/jTaHgDQDZnQ).
114+
* Watch [our presentation at
115+
Serverlessconf'17](https://acloud.guru/series/serverlessconf/view/ibm-cloud-functions)
116+
about Composer and Shell.
117+
* [Conductor Actions and Composer
118+
v2](https://urldefense.proofpoint.com/v2/url?u=https-3A__youtu.be_qkqenC5b1kE&d=DwIGaQ&c=jf_iaSHvJObTbx-siA1ZOg&r=C3zA0dhyHjF4WaOy8EW8kQHtYUl9-dKPdS8OrjFeQmE&m=vCx7thSf3YtT7x3Pe2DaLYw-dcjU1hNIfDkTM_21ObA&s=MGh9y3vSvssj1xTzwEurJ6TewdE7Dr2Ycs10Tix8sNg&e=)
119+
(29:30 minutes into the video): A discussion of the composition runtime.
120+
121+
## Blog posts
122+
* [Serverless Composition with IBM Cloud
123+
Functions](https://www.raymondcamden.com/2017/10/09/serverless-composition-with-ibm-cloud-functions/)
124+
* [Building Your First Serverless Composition with IBM Cloud
125+
Functions](https://www.raymondcamden.com/2017/10/18/building-your-first-serverless-composition-with-ibm-cloud-functions/)
126+
* [Upgrading Serverless Superman to IBM
127+
Composer](https://www.raymondcamden.com/2017/10/20/upgrading-serverless-superman-to-ibm-composer/)
128+
* [Calling Multiple Serverless Actions and Retaining Values with IBM
129+
Composer](https://www.raymondcamden.com/2017/10/25/calling-multiple-serverless-actions-and-retaining-values-with-ibm-composer/)
130+
* [Serverless Try/Catch/Finally with IBM
131+
Composer](https://www.raymondcamden.com/2017/11/22/serverless-trycatchfinally-with-ibm-composer/)
132+
* [Composing functions into
133+
applications](https://medium.com/openwhisk/composing-functions-into-applications-70d3200d0fac)
134+
* [A composition story: using IBM Cloud Functions to relay SMS to
135+
email](https://medium.com/openwhisk/a-composition-story-using-ibm-cloud-functions-to-relay-sms-to-email-d67fc65d29c)
136+
137+
## Contributions
138+
We are looking forward your feedback and criticism. We encourage you to [join us
139+
on slack](http://ibm.biz/composer-users). File bugs and we will squash them.
140+
141+
We welcome contributions to Composer and Shell. See
142+
[CONTRIBUTING.md](CONTRIBUTING.md).

‎docs/COMPOSER.md

Lines changed: 58 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Composer
1+
# Composer Reference
22

33
The [`composer`](../composer.js) Node.js module makes it possible define action [compositions](#compositions) using [combinators](#combinators).
44

@@ -8,29 +8,50 @@ To install the `composer` module use the Node Package Manager:
88
```
99
npm -g install @ibm-functions/composer
1010
```
11-
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.
11+
We recommend to install the module globally (with `-g` option) so the `compose`
12+
command is added to the path. Otherwise, it can be found in the `bin` folder of
13+
the module installation.
1214

1315
## Example
1416

15-
A composition is typically defined by means of a Javascript file as illustrated in [samples/demo.js](../samples/demo.js):
17+
A composition is typically defined by means of a Javascript file as illustrated
18+
in [samples/demo.js](samples/demo.js):
1619
```javascript
17-
composer.if('authenticate', /* then */ 'success', /* else */ 'failure')
20+
composer.if(
21+
composer.action('authenticate', { action: function main({ password }) { return { value: password === 'abc123' } } }),
22+
composer.action('success', { action: funcßtion main() { return { message: 'success' } } }),
23+
composer.action('failure', { action: function main() { return { message: 'failure' } } }))
24+
```
25+
Composer offers traditional control-flow concepts as methods. These methods
26+
are called _combinators_. This example composition composes three actions named
27+
`authenticate`, `success`, and `failure` using the `composer.if` combinator,
28+
which implements the usual conditional construct. It take three actions (or
29+
compositions) as parameters. It invokes the first one and, depending on the
30+
result of this invocation, invokes either the second or third action.
31+
32+
This composition includes the definitions of the three composed actions. If the
33+
actions are defined and deployed elsewhere, the composition code can be shorten
34+
to:
35+
```javascript
36+
composer.if('authenticate', 'success', 'failure')
1837
```
19-
This example composition composes three actions named `authenticate`, `success`, and `failure` using the `composer.if` combinator.
2038

2139
To deploy this composition use the `compose` command:
2240
```
2341
compose demo.js --deploy demo
2442
```
25-
This command creates an action named `demo` that implements the composition.
43+
The `compose` command synthesizes and deploy an action named `demo` that
44+
implements the composition. It also deploys the composed actions if definitions
45+
are provided for them.
2646

27-
Assuming the composed actions are already deployed, this composition may be invoked like any action, for instance using the OpenWhisk CLI:
47+
The `demo` composition may be invoked like any action, for instance using the
48+
OpenWhisk CLI:
2849
```
2950
wsk action invoke demo -r -p password passw0rd
3051
```
3152
```
3253
{
33-
message: "Failure"
54+
message: "failure"
3455
}
3556
```
3657
An invocation of a composition creates a series of activation records:
@@ -64,6 +85,35 @@ compose demo.js
6485
```
6586
```
6687
{
88+
"actions": [
89+
{
90+
"name": "/_/authenticate",
91+
"action": {
92+
"exec": {
93+
"kind": "nodejs:default",
94+
"code": "function main({ password }) { return { value: password === 'abc123' } }"
95+
}
96+
}
97+
},
98+
{
99+
"name": "/_/success",
100+
"action": {
101+
"exec": {
102+
"kind": "nodejs:default",
103+
"code": "function main() { return { message: 'success' } }"
104+
}
105+
}
106+
},
107+
{
108+
"name": "/_/failure",
109+
"action": {
110+
"exec": {
111+
"kind": "nodejs:default",
112+
"code": "function main() { return { message: 'failure' } }"
113+
}
114+
}
115+
}
116+
],
67117
"composition": [
68118
{
69119
"type": "if",

‎samples/demo.js

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,7 @@
1414
* limitations under the License.
1515
*/
1616

17-
composer.if('authenticate', /* then */ 'success', /* else */ 'failure')
17+
composer.if(
18+
composer.action('authenticate', { action: function main({ password }) { return { value: password === 'abc123' } } }),
19+
composer.action('success', { action: function main() { return { message: 'success' } } }),
20+
composer.action('failure', { action: function main() { return { message: 'failure' } } }))

‎samples/demo.json

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,33 @@
11
{
2+
"actions": [
3+
{
4+
"name": "/_/authenticate",
5+
"action": {
6+
"exec": {
7+
"kind": "nodejs:default",
8+
"code": "function main({ password }) { return { value: password === 'abc123' } }"
9+
}
10+
}
11+
},
12+
{
13+
"name": "/_/success",
14+
"action": {
15+
"exec": {
16+
"kind": "nodejs:default",
17+
"code": "function main() { return { message: 'success' } }"
18+
}
19+
}
20+
},
21+
{
22+
"name": "/_/failure",
23+
"action": {
24+
"exec": {
25+
"kind": "nodejs:default",
26+
"code": "function main() { return { message: 'failure' } }"
27+
}
28+
}
29+
}
30+
],
231
"composition": [
332
{
433
"type": "if",

0 commit comments

Comments
 (0)