Functions and Events

Computation in a Serverless environment is generally split in functions. A function is typically a piece of code that will receive input and will provide an output in response. It is important to note that a function is expected to be stateless.

Frequently web applications are stateful. Just think of a shopping cart application for an e-commerce: while you navigate the website, you add your items to the basket, to buy them at the end. You keep a state, the cart.

Being stateful however is an expensive property that limits scalability: you need to provide something to store data. Most importantly, you will need something to synchronize the state between invocations. When your load increase, this “state keeping” infrastructure will limit your ability to grow. If you are stateless, you can usually add more servers.

The OpenWhisk solution, and more widely the solution adopted by Serverless environments is the requirement functions must be stateless. You can keep state, but you will use separate storage designed to scale.

To run functions to perform our computations, the environment will manage the infrastructure and invoke the actions when there is something to do.

In short, “having something to do” is what is called an event. So the developer must code thinking what to do when something happens (a request from the user, a new data is available), and process it quickly. The rest belongs to the cloud environment.

In conclusion, Serverless environments allow you to build your application out of simple stateless functions, or actions as they are called in the context of OpenWhisk, triggered by events. We will see later in this chapter which other constraints those actions must satisfy.

Architecture Overview

We just saw OpenWhisk from the outside, and now we have an idea of what it does. Now it is time to investigate its architecture, to understand better how it works under the hood.

Figure 1-2. OpenWhisk High Level Archiecture - Actions

We will refer to the Figure Figure 1-2, with some numbered markers. In the Figure, the big container (see 1) at the center, is OpenWhisk itself. It acts as a container of actions. We will see later what an action and what the container is.

For the architect, you can consider it as an opaque system that executes those actions in response to events.

Programming Languages for OpenWhisk

You can write actions in many programming languages. Probably the more natural to use are interpreted programming languages: like JavaScript (see 2) (actually, Node.js) or Python (see 3). Those programming languages are interpreted and give an immediate feedback since you can execute them without compilation. They are also generally of higher level, hence more comfortable to use (while the drawback is usually they are slower than compiled languages). Since OpenWhisk is a highly responsive system, where you can immediately run your code in the cloud, probably the majority of the developers prefer to use those “interactive” programming languages.

In addition to purely interpreted (or compiled-on-the-fly languages, as it is correct to say), you can use also pre-compiled interpreted languages, like the languages of the Java family. Java, Scala and Kotlin (see 4) are the more common programming languages of this family. They run on the Java Virtual Machine, and they are distributed not in source form but an intermediate form. The developer must create a “jar” file to run the action. This jar includes the so-called “bytecode” that OpenWhisk will execute when it will be deployed . A Java Virtual Machine is the actual executor of the action.

Finally, in OpenWhisk you can use compiled languages, producing a binary executable that runs on “bare metal” without interpreters or virtual machines. Examples of those binary languages are Swift, Go or the classical C/C++, see (see 5).

OpenWhisk supports out-of-the-box Go and Swift. You need to send the code of an action compiled in Linux elf format for the amd64 processor architecture, so a compilation infrastructure is needed. However today, with the help of Docker, is not complicated to install on any system the necessary toolchain for the compilation.

Finally, you can use in OpenWhisk any arbitrary language or system that can you can package like a Docker image (see 6) and that you can publish on Docker Hub: OpenWhisk allows to retrieve such an image and run it, as long as you follow its conventions. We will discuss this in the chapter devoted to native actions.

Actions and Action Composition

OpenWhisk applications are a collection of actions. We already saw the available type of actions. Now let’s see in Figure Figure 1-3 how they are assembled to build applications.

Figure 1-3. Open Whisk High Level Architecture - Components

An action is a piece of code, written in one of the supported programming languages, that you can invoke. On invocation, the action will receive some information as input (see 1).

To standardize parameter passing among multiple programming languages, OpenWhisk uses the widely supported JSON format, since it is pretty simple, and there are libraries to encode and decode this format available basically for every programming language.

The parameters are passed to actions as a JSON string, that the action receives when it starts, and it is expected to process. At the end of the processing, each action must produce its result that is then returned also as a JSON string (see 2).

You can group actions in packages (see 3). A package acts as a unit of distribution. You can share a package with others using bindings. You can also customize a package providing parameters that are different for each binding.

Actions can be combined in many ways. The simplest form of combination is chaining them in sequences (see 4)

Chained actions will use as input the output of the preceding actions. Of course, the first action of a sequence will receive the parameters (in JSON format), and the last action of the sequence will produce the final result, as a JSON string.

However, since not all the flows can be implemented as a linear pipeline of input and output, there is also a way to split the flow of an action in multiple directions. 

This feature is implemented using triggers and rules (see 5).

A trigger is merely a named invocation. You can create a trigger, but by itself a trigger does nothing. However, you can then associate the trigger with multiple actions using Rules.

Once you have created the trigger and associated some action with it, you can fire the trigger providing parameters.

The connection between actions and triggers is called a feed (see 6). A feed is an ordinary action that must follow an implementation pattern. We will see in the chapter devoted to the design pattern. Essentially it must implement an observer pattern, and be able to activate a trigger when an event happens.

When you create an action that follows the feed pattern (and that can be implemented in many different ways), that action can be marked as a feed in a package. In this case, you can combine a trigger and feed when you deploy the application, to use a feed as a source of events for a trigger (and in turn activate other actions).

Nginx

Everything starts when an action is invoked. There are different ways to invoke an action:

• from the Web, when the action is exposed as Web Action

• when another action invokes it through the API

• when a trigger is activated and there is a rule to invoke the action

• from the Command Line Interface

Let’s call the client the subject who invokes the action. OpenWhisk is a RESTful system, so every invocation is translated in an https call and hits the so-called “edge” node.

The edge is actually the web server and reverse proxy Nginx. The primary purpose of Nginx is implementing support for the “https” secure web protocol. So it deploys all the certificates required for secure processing. Nginx then forwards the requests to the actual internal service component, the Controller.

Controller

The Controller, that is implemented in Scala, before effectively executing the action, performs pretty complicated processing.

1. It needs to be sure it can execute the action. Hence the need to authenticate the requests, verifying if the source of the request is a legitimate subject.

2. Once the origin of the request has been identified, it needs to be authorized, verifying that the subject has the appropriate permissions.

3. The request must be enriched with all the default parameters that have been configured. Those parameters, as we will see, are part of the action configuration.

To perform all those steps the Controller consults the database, that in OpenWhisk is CouchDB.

Once validated and enriched, the action is now is ready to be executed, so it is sent to the next component of the processing, the Load Balancer.

Load Balancer

Load Balancer job, as its name states, is to balance the load among the various executors in the system, which are called in OpenWhisk Invokers.

We already saw that OpenWhisk executes actions in runtimes, and there are runtimes available for many programming languages. The Load Balancer keeps an eye on all the available instances of the runtime, checks its status and decide which one should be used to serve the new action requested, or if it must create a new instance.

We got to the point where the system is ready to invoke the action. However, you can not just send your action to an Invoker, because it can be busy serving another action. There is also the possibility that an invoker crashed, or even the whole system may have crashed and is restarting.

So, because we are working in a massively parallel environment that is expected to scale, we have to consider the eventuality we do not have the resources available to execute the action immediately. Hence we have to buffer invocations.

The solution for this purpose is using Kafka. Kafka is a high performing “publish and subscribe” messaging system, able to store your requests, keep them waiting until they are ready to be executed. The request is turned in a message, addressed to the invoker the Load Balancer chose for the execution.

Each message sent to an Invoker has an identifier, the ActivationId. Once the message has been queued in Kafka, the ActivationId is sent back as the final answer of the request to the client, and the request completes.

Because as we said the processing is asynchronous, the Client is expected to come back later to check the result of the invocation.

Invoker

The Invoker is the critical component of OpenWhisk and it is in charge of executing the Actions. Actions are actually executed by the Invoker creating an isolated environment provided by Docker.

Docker can create execution environments (called “Containers”) that resemble an entire operating system, providing everything code written in any programming language needs to run.

In a sense, an environment provided by Docker looks like, as seen by action, to an entire computer for it (just like a Virtual Machine). However, execution within containers is much more efficient than VMs, so they are used in preference to actual emulated environments.

Docker actually uses Images as the starting point for creating containers where it executes actions. A runtime is really a Docker image. The Invoker launches a new Image for the chosen runtime then initialize it with the code of the action.

OpenWhisk provides a set of Docker Images including support for the various languages, and the execution logic to accept the initialization: JavaScript, Python, Java, Go, etc.

Once the runtime is up and running, the invoker passes the whole action requests that have been constructed in the processing so far. Also, Invokers will take care of managing and storing logs to facilitate debugging.

Once OpenWhisk completes the processing, it must store the result somewhere. This place is again CouchDB (where also configuration data are stored). Each result of the execution of an action is then associated with the ActivationId, the one that was sent back to the client. Thus the client will be able to retrieve the result of its request querying the database with the id.

Aysnchronous Client

As we already said, the processing described so far is asynchronous. This fact means the client will start a request and forget. Well, it will not leave it behind entirely, because it returns an activation id as a result of an invocation. As we have seen so far, the activation id is used to associate the result in the database after the processing.

So, to retrieve the final result, the client will have to perform a request again later, passing the activation id as a parameter. Once the action completes, the result, the logs, and other information are available in the database and can be retrieved.

Synchronous processing is available in addition to the asynchronous one. It primarily works in the same way as the asynchronous, except the client will block waiting for the action to complete and retrieve the result immediately.

Action Execution Constraints

In Figure Figure 1-5 are depicted the significant constraints an action is subject.

All the constraints have some value in term of time or space, either timeout, frequency, memory, size of disk space. Some are configurable; others are hardcoded. The standard values (that can be different according to the particular cloud or installation you are using) are:

• execution time: max 1 minute per action (configurable)

• memory used: max 256MB per action (configurable)

• log size: max 10MB per action (configurable)

• code size: max 48MB per action (fixed)

• parameters: max 1MB per action (fixed)

• result: max 1MB per action (fixed)

Furthermore, there are global constraints:

• concurrency: max 100 concurrent activations can be queued at the same time (configurable)

• frequency: max 120 activations per minute can be requested (configurable)

Let’s discuss more in detail those constraints.

Actions are Functional

As already mentioned, each action must be a function, invoked with a single input and must produce a single output.

The input is a string in JSON format. The action usually deserializes the string in a data structure, specific to the programming language used for the implementation.

The runtime generally performs the deserialization, so the developer will receive an already parsed data structure.

If you use dynamic languages like Javascript or Python, usually you receive something like a Javascript object or a Python dictionary, that can be efficiently processed using the feature of the programming language.

If you use a more statically typed language like Java or Go, you may need to put more effort in decoding the input. Libraries for performing the decoding task are generally readily available. However, some decoding work may be necessary to map the generally untyped arguments to the typed data structure of the language.

The same holds true for returning the output. It must be a single data structure, the programming language you are using can create, but it must be serialized back in JSON format before being returned. Runtimes also usually take care of serializing data structures back in a string.

Actions are Event Driven

Everything in the Serverless environment is activated by events. You cannot have any long running process. It is the system that will invoke actions, only when they are needed.

For example, an event is a user that when is browsing the web opens the URL of a serverless application. In such a case, the action is triggered to serve it.

However, this is only one possible event. Other events include for example a request, maybe originated by another action, that arrives on a message queue.

Also, database management is event-driven. You can perform a query on a database, then wait until an event is triggered when the data arrives.

Other websites can also originate events. For example, you may receive an event:

• when someone pushes a commit on GitHub

• when a user interacts with Slack and sends a message

• when a scheduled alarm is triggered

• when an action update a database

etc.

Actions do not have Local State

Actions are executed in Docker containers. As a consequence (by Docker design) file system is ephemeral. Once a container terminates, all the data stored on the file system will be removed too.

However, this does not mean you cannot store anything on files when using a function. You can use files for temporary data while executing an application.

Indeed a container can be used multiple times, so for example, if your application needs some data downloaded from the web, an action can download some stuff it makes available to other actions executed in the same container.

What you cannot assume is that the data will stay there forever. At some point in time, either the container will be destroyed or another container will be created to execute the action. In a new container, the data you downloaded in a precedent execution of the action will be no more available.

In short, you can use local storage only as a cache for speed up further actions, but you cannot rely on the fact data you store in a file will persist forever. For long-term persistence, you need to use other means. Typically a database or another form of cloud storage.

Actions are Time Bounded

It is essential to understand that action must execute in the shortest time possible. As we already mentioned, the execution environment imposes time limits on the execution time of an action. If the action does not terminate within the timeout, it will be aborted. This fact is also true for background actions or threads you may have started.

So you need to be well aware of this behavior and ensure your code will not keep going for an unlimited amount of time, for example when it gets larger input. Instead, you may sometimes need to split the processing into smaller chunks and ensure the execution time of your action will stay within limits.

Also usually the billing charge is time-dependent. If you run your application in a cloud provider supporting OpenWhisk, you are charged for the time your action takes. So faster actions will result in lower cost. When you have millions of actions executed, a few milliseconds speedier action can sum up in significant savings.

Actions are Not Ordered

Note also that actions are not ordered. You cannot rely on the fact action is invoked before another. If you have action A at time X and action B at time Y, with X < Y, action B can be executed before A.

As a consequence, if the action has a side effect, for example writing in the database, the side effect of action A may be applied later than the action B. Furthermore, there is not even any guarantee that an action will be executed entirely before or after another action. They may overlap in time.

So for example when you write in a database you must be aware that while you are writing in it, and before you have finished, another action may start writing in it too. So you have to provide your transaction support.

Classical JavaEE Architecture

The core idea behind JavaEE was allowing the development of large application out of small, manageable parts. It was a technology designed to help application development for large organizations, using the Java programming language. Hence the name of Java Enterprise Edition.

To facilitate the development of that vast and complex application, JavaEE provided a productive (and complicated) infrastructure of services.

To use them, JavaEE offered many different types of components, each one deployable separately, and many ways to let the various part to communicate with each other.

Those services were put together and made available through the use of Application Server. JavaEE itself was a specification.

The actual implementation was a set of competing products. The most prominent names in the world of application servers that are still in broad use today are Oracle Weblogic and IBM WebSphere.

Figure 1-6. JavaEE Architecture

If we look at the classical JavaEE architecture we can quickly identify the following tiers:

• The client (front end) tier

• The web (back-end) tier

• The EJB (business) tier

• The EIS (integration) tier

The following ideas characterize it:

• Application is split into discrete components, informally called beans.

• Components are executed in (Java-based) containers.

• Interface to the external world is provided by connectors.

In JavaEE, we have different types of components.

The client tier is expected to implement the application logic at the client level. Historically Java was used to implement applet, small java components that can be downloaded and run in the browser. Javascript, CSS, and HTML nowadays entirely replace those web components

In the web tier, the most crucial kind of components are the servlets. They are further specialized in JSP, tag libraries, etc. Those components define the web user interface at the server level.

The so-called business logic, managing data and connection to other “enterprise systems” is expected to be implemented in the Business Tier using the so-called EJB (Enterprise Java Beans). There were many flavors of EJB, like Entity Beans, Session Beans, Message Beans, etc.

Each component in JavaEE is a set of Java classes that must implement an API. The developer writes those classes and then deliver them to the Application Server, that loads the components and run them in their containers.

Furthermore, application servers also provide a set of connectors to interface the application with the external world, the EIS tier. There were connectors, written for Java, allowing to interface to virtually any resource of interest,

The more common in JavaEE are connectors to:

• databases

• message queues

• email and other communication systems

In the JavaEE world, Application Servers provided the implementation of all the JavaEE specification, and included APIs and connectors, to be a one-stop solution for all the development needs of enterprises.

Serveless equivalent of JavaEE

For many reasons, the architecture of Serverless application and OpenWhisk can be seen as an evolution of JavaEE. Everything starts from the same basic idea: split your application into many small, manageable parts, and provide a system to quickly put together all those pieces.

However, the technological landscape driving the development of Serverless environment is different than the one driving JavaEE development. In our brave new world, we have:

• applications are spread among multiple servers in the cloud, requiring virtually infinite scalability

• numerous programming languages, including scripting languages, are in extensive use and must be usable

• virtual machine and container technologies are available to wrap and control the execution of programs

• HTTP can be considered a standard transport protocol

• JSON is simple and widely used to be usable as a universal exchange format

Now, let’s compare JavaEE with the OpenWhisk architecture in Figure Figure 1-7. The Figure is intentionally similar to the Figure Figure 1-6, to highlight similarities and differences.

Figure 1-7. Serverless Architecture

Tiers

As you can see in the Figure, we can recognize web tier and a business tier also in OpenWhisk, in addition to a client and an integration tier.

While there is not a formal difference between the two tiers, in practice we have actions directly exposed to the web (web actions) and actions that are not.

Web Actions can be considered to be the web tier. Those actions which are meant to serve events, either coming from web actions or triggered by other services in the infrastructure, can be considered “Business Actions,” defining a “Business Tier.”

Components

In JavaEE, everything runs in the Java Virtual Machine, and everything must be coded in Java (or any language that can generate JVM-compatible byte-code).

In OpenWhisk, you can code applications in multiple programming languages. We use their runtimes as equivalents of the Java Virtual Machine. Furthermore, those runtimes are wrapped in Docker containers to provide isolation and control over resource usage.

Hence you can write your components in any (supported) language you like. You are no more confined to write your application solely for the JVM. However, a JVM runtime is available, so you can still use Java and its family of languages if you like.

You can now write your code for the JavaScript Virtual Machine, more commonly referred to as NodeJs .

If you choose to use the Python programming languages, you are also using its interpreter. Python has many available interpreters, one being the move widely used CPython, but there is also other available, like Pypy. The JVM can even execute Python.

Furthermore, you may choose not to use a virtual machine at all, but write your application in a language producing native executables like Swift or Go. In the Serverless world, it is becoming to become a popular choice. As long as you compile your application for Linux and AMD64, you can use it for OpenWhisk.

APIs

In JavaEE, you have APIs available to interact with the rest of the world, written in Java itself. Basically, the JavaEE model is , and every interesting resource for writing applications has been adapted to be used by Java.

In OpenWhisk, you have first and before all only one API, available for all the supported programming languages. This API is the OpenWhisk API itself, and it is a RESTful API. You can invoke it over HTTP using JSON as an interchange format.

This API can even be invoked directly just using an HTTP library, reading and writing JSON strings. However, are available wrappers for all the supported programming languages to use it efficiently. This API acts as glue for the various components in OpenWhisk.

All the communication between the different parts in OpenWhisk are performed in JSON over HTTP.

Connectors

In JavaEE, you have connectors for each external system you want to communicate with, primarily drivers. For example, if you’re going to interact with an Oracle database you need an Oracle JDBC driver, to communicate with IBM DB2 you need a specify DB2 JDBC driver, etc. The same holds true for messaging queues, email, etc.

In OpenWhisk, interaction with other systems is wrapped in packages, that are a collection of actions explicitly written to interact with a particular system. You can use any programming language and available APIs and drivers to communicate with it. So if you have for example a Java driver for a database, you can write a package to interact with it. Those packages act as Connectors.

In the IBM Cloud, there are packages available to communicate with essential services in the cloud. Most notably, we have

• the cloud database Cloudant

• the Kafka messaging system,

• the enterprise chat Slack

• many others, some specific to IBM services

You use the Feed mechanism provided by OpenWhisk to hook in those systems.

Application Server

Finally, in JavaEE, everything is managed by Application Servers. They are “the place” where Enterprise Applications are meant to be deployed.

In a sense, OpenWhisk itself replaces the Application Server concept, providing a cloud-based, multi-node, language agnostic execution service.

Using a serverless engine like OpenWhisk, the cloud becomes a transparent entity where you deploy your code. The environment manages the distribution of application in the Cloud.

For now, we have to say that OpenWhisk by itself runs in Docker containers. However, scaling Docker in a Cloud requires you to manage those Docker containers under some supervisor system called Orchestrators.

There are many Orchestrator available. At this stage, OpenWhisk supports:

• Kubernetes, a widely used orchestration system, initially developed by Google

• DC/OS, a “cloud” operating system, supporting the management of distributed application and Docker.

The Bash command line is a prerequisite for development

Serverless development is primarily performed at the terminal, using a command line interface (CLI). We are going to use mostly the Unix based CLI and the command line interpreter Bash. In a sense, this is a Unix-centered book. Bash is available out-of-the-box in any Linux based environment and on OSX. It can also be installed on Windows.

In the following examples, we are also going to use Bash widely for (numerous) command line examples. So you need to familiar working with Bash and the command line.

$ pwd                      
/Users/msciab
$ ls \                     
-l
# total 16                 
-rw-r--r--@ 1 msciab  staff  1079 24 Feb 09:53 form.js
-rw-r--r--@ 1 msciab  staff    71 23 Feb 17:18 submit.js

you should type now pwd at the command line

you should type at the terminal both the two lines

this is an example of the output you should expect

Address Validation

First, let’s check only if the name is provided.

// validate the name
if(args.name) {
 message.push("name: "+args.name)
} else {
 errors.push("No name provided")
}

Second, let’s validate the email address, checking if it “looks like” an email. We use here a regular expression:

// validate email
var re = /\S+@\S+\.\S+/;
if(args.email && re.test(args.email)) {
   message.push("email: "+args.email)
} else {
  errors.push("Email missing or incorrect.")
}

Third, let’s validate the phone number, checking it has “enough” digits (at least 10):

/// validate the phone
if(args.phone && args.phone.match(/\d/g).length >= 10) {
  message.push("phone: "+args.phone)
} else {
  errors.push("Phone number missing or incorrect.")
}

Finally, let’s add the message text if any:

/// add the message text, optional
if(args.message) {
  message.push("message:
"+args.message)
}

Returning the result

Once we have all the fields validated, we can return the result. There is now a bit of logic: we choose if returning an error message or an acceptance message.

// complete the processing
var data = "<pre>"+message.join("\n")+"</pre>"
var errs = "<ul><li>"+errors.join("</li><li>")+"</li></ul>"
if(errors.length) {
  return {
    body: "<h1>Errors!</h1>"+
      data + errs +
      '<br><a href="javascript:window.history.back()">Back</a>'
   }
} else {
   // storing in the database
   // TODO: <Store the message in the database> 
   return {
     body: "<h1>Thank you!</h1>"+ data
   }
}

Placeholder to insert code to save data in the database

The action is not complete (we have still to see how to store the data) but we can test this partial code with this command:

$ wsk action create contact/submit submit.js --web true
ok: created action contact/submit

If you now submit the form empty, you will see the message in Figure Figure 2-4 under “Form Rejected”. If we instead provide all the parameters correctly, we will be gratified with the acknowledgment under “Form Accepted”.

Figure 2-4. What the form submit displays

Invoking actions

So far we have seen how we can create actions and how to invoke them. Actually, in the first two examples, we have seen one specific kind of actions: web action (you may have noted the --web true flag in the commands). Those are the actions which can be invoked directly, navigating to web URLs or submitting web forms.

However, not all the actions are there to be invoked straight from the web. Many of them execute internal processing and are activated only through some specific APIs.

The actions letting to read and write in the database, those who we just exported from the Cloudant package, are not web actions. They can be invoked however using the command line interface.

In particular, we have to use the wsk action invoke command, passing parameters with the --param options and data in JSON format as a command line argument.

Let verify how it works, writing in the database, by invoking the action directly write, as follows.

$ wsk action invoke contactdb/write \
  --blocking --result --param dbname contactdb \
  --param doc '{"name":"Michele Sciabarra", "email": "michele@sciabarra.com"}'
{
    "id": "fad432c6ea1145e71e99053c0d811475",
    "ok": true,
    "rev": "1-d14ba6a37cfdf34a8b3bb49dd3c0e22a"
}

The database replied with a confirmation and some extra information. Most notably, the result includes the id of a new record, that we can use later for retrieving the value.

We can now check the database user interface to see the data we just stored in it. You can select the database, then the id and you can see the data we just inserted in the database in JSON format.

As you can see, to write data in the database you need just a JSON object. So far we wrote data using the command line. Let’s look at how we can do it in code.

Figure 2-7. How to retrieve data from cloudant

Storing in the database

OpenWhisk includes an API to interact with the rest of the system. Among the possibilities, there is the ability to invoke actions.

We provisioned the database as a package binding. Thus we have now an action available to write in the database. To use it we need to invoke the action from another action. Let see how.

First and before all, we need a:

var openwhisk = require('openwhisk')

to access to the openwhisk API. This code is the entry point to interact with OpenWhisk from within an action.

Now, we can define the function save using the OpenWhisk API to invoke the action to write in the database. The following code should be placed at the beginning of the submit.js:

var openwhisk = require('openwhisk')

function save(doc)  {
  var ow = openwhisk()
  return ow.actions.invoke({
    "name": "/_/contactdb/write",
    "params": {
       "dbname": "contactdb",
       "doc": doc
    }
  })
}

Once the save function is available, you can use it to save data just by creating an appropriate JSON object and pass it as a parameter. Place the following code after <Store the message in the database>:

save({
 "name": args.name,
  "email": args.email,
  "phone": args.phone,
  "message": args.message
})

The code is now complete. We can deploy it, as a web action too, to be executed when the user posts the form:

$ wsk action update contact/submit submit.js --web true
ok: updated action contact/submit

We can now manually test the action from the command line, to check if it writes in the database:

$ wsk action invoke contact/submit -p name Michele -p email \
    michele@sciabarra.com -p phone 1234567890 -r
{
    "body": "<h1>Thank you!</h1><pre>name: Michele
email: michele@sciabarra.com
phone: 1234567890</pre>"
}

Now we can go on and try our form, verifying data are written in the database, as in figure Figure 2-8.

Figure 2-8. Submitting the form and storing the data

Configuring Mailgun

To use Mailgun you need to go to the website www.mailgun.com and register for a free account. Once you have set up an account you will get a “sandboxed” account (note the site will ask for a phone number for verification purposes).

Once registered, to retrieve credentials for sending an email (Figure Figure 2-9) you need to:

1. Login in Mailgun

2. Scroll down until you find the Sandbox Domain

3. Click on “Authorized Recipient”

4. Invite the recipient

5. Click on the link in the email received

Once done, you need the following information, as shown in the figure, for writing your script:

• the sandboxed domain

• the private API key

• the authorized recipient address

Figure 2-9. How to register in Mailgun

Writing an action for sending email

Now, we can build an action for sending an email. Actually, the purpose of this example is to show how you can create more complex action involving third-party services and libraries.

Hence now preparing this action is a bit more complicated than the actions we have seen before, because we need to use and install an external library then and deploy it together with the action code.

Let start by creating a folder and importing the library mailgun-js with the npm tool. We assume you have installed it, refer to Appendix II for details about the purpose and usage of this tool.

$ mkdir sendmail
$ cd sendmail
$ npm init -y
$ npm install --save mailgun-js

Now we can write a simple action that can send an email and place it in sendmail/index.js. Check the listing with the notes about the information you have to replace with those who collected before when registering to Mailgun.

var mailgun = require("mailgun.js")
var mg = mailgun.client({username: 'api',
        key: 'key-<YOUR-PRIVATE-API-KEY>'})      
function main(args) {
  return mg.messages.create(
          '<YOUR-SANDBOX-DOMAIN>.mailgun.org', { 
    from: "<YOUR-RECIPIENT-EMAIL>", 
    to: ["<YOUR-RECIPIENT-EMAIL>"], 
    subject: "[Contact Form]",
    html: args.body
  }).then(function(msg) {
     console.log(msg);
     return args;
  }).catch(function(err) {
     console.log(err);
     return args;
  })
}

replace key-<YOUR-PRIVATE-API-KEY> with the Private API Key

replace <YOUR-SANDBOX-DOMAIN>.mailgun.org with the Sandbox Domain

replace <YOUR-RECIPIENT-EMAIL> with the one that is used both as the sender and the recipient

same as 3

We can deploy now the action. Since this time the action is not a single file, but it includes libraries, we have to package everything in a zip file, to deploy them too.

$ zip ../sendmail.zip -r *
$ wsk action update contact/sendmail ../mailgun.zip --kind nodejs:6
ok: updated action contact/sendmail

We can now test the action invoking it directly:

$ wsk action invoke contact/sendmail -p body "<h1>Hello</h1>" -r
{
    "body": "<h1>Hello</h1>"
}

The action acts as a filter, accepting the input and copying it in the output. We will leverage this behavior to chain the action to the submit.

When invoked, it will return an output, but also it will send an email as a side effect.

Figure 2-10. The email send by your action in your Inbox

Creating an action sequence

So far we have developed an action that can send an email as a stand-alone action.

However, we designed the action in such a way that it can take the output of the submit action and return it as is. So we can create a pipeline of actions, similar to the Unix shell processing, where the output of a command is used as an input for another command.

We are going to take the output of the sendmail action, use it as the input for the submit action and then return it as the final result of the email submission.

Please note as a side effect; it will send emails for every submission, also for incorrect inputs, so we can know someone is trying to use the form without providing full information.

However, we will store in the database only the fully validated data. Let’s create such a pipeline that is called sequence in OpenWhisk, and then test it.

$ wsk action create contact/submit-sendmail \
  --sequence contact/submit,contact/sendmail \
  --web true
ok: updated action contact/submit-sendmail

$ wsk action invoke contact/submit-sendmail -p name Michele -r
{
    "body": "<h1>Errors!</h1><pre>name: Michele</pre><ul><li>Email missing or incorrect.</li><li>Phone number missing or incorrect.</li></ul><br><a href=\"javascript:window.history.back()\">Back</a>"
}

As a result, we should be receiving an email for each attempt of submitting a form, including partial data from the contact form.

Now we are ready. We can use the complete form including storing in the database and sending the email. But now the form should activate our sequence, not just the submission action. The simplest way is to edit the form.js, replacing the action we are invoking in the form. We should do the following change in form.js:

-<form method="POST" action="submit">
+<form method="POST" action="submit-sendmail">

If we now update the action and try it, we will receive an email for each form submission, but the form will be stored in the database only when the data is complete.

Configure the wsk command

The wsk command has many “properties” you can configure to access to an OpenWhisk environment. When you use the IBM Cloud, those properties are actually set for you by the ibmcloud main command. If you have a different OpenWhisk deployment, you may need to change the properties manually to access it.

You can see the currently configured properties with:

$ wsk property get
Client key
whisk auth            xxxxx:YYYYY                  
whisk API host        openwhisk.eu-gb.bluemix.net  
whisk API version    v1
whisk namespace        _                            
whisk CLI version    2017-11-15T19:55:32+00:00
whisk API build        2018-02-28T23:44:25Z
whisk API build number    whisk-build-7922

the API authentication key (replaced in the example with xxxxx:YYYYY) - your own will be different

the OpenWhisk host you connect to control OpenWhisk with the CLI - depends on your location

your current namespace (the value _ is a shorthand for you default namespace)

If you install a local OpenWhisk environment, you need to set those properties using wsk property set manually. In particular, you need to set the whisk auth and the whisk host properties with values provided by your local installation.

OpenWhisk Entity Names

Let’s see how we name things. As you may already know, in OpenWhisk we have the following entities with a name:

• packages

• actions

• sequences

• triggers

• rules

• feeds

There are precise naming conventions for them. Furthermore, those conventions are reflected in the structure of the URL used to invoke the various elements of OpenWhisk.

First and before all, each user is placed in a namespace, and everything a user creates, belong to it. It acts as a workspace and also provides a base URL for what a user creates. Credentials for a user allows access to all the resources in its namespace.

For example, when I registered in the IBM Cloud, my namespace was /openwhisk@sciabarra.com_dev/. It is my username followed by _dev (for development).

You can create a namespace in an OpenWhisk installation if you are authorized, otherwise, a namespace is created for you by the system administrator.

Under a namespace you can create triggers, rules, actions and packages, so they will have names like:

• /openwhisk@sciabarra.com_dev/a-triggger

• /openwhisk@sciabarra.com_dev/a-rule

• /openwhisk@sciabarra.com_dev/a-package

• /openwhisk@sciabarra.com_dev/an-action

When you create a package, you can put in its actions and feeds. So for example below the package a-package you can have:

• /openwhisk@sciabarra.com_dev/a-package/another-action

• /openwhisk@sciabarra.com_dev/a-package/a-feed

To recap:

• The general format for entities is: /namespace/package/entity, but it can be reduced to /namespacke/entity

• Under a namespace you can create triggers, rules, package, and actions but not feeds.

• Under a package you can create actions and feeds, but not triggers, rules, and other packages.

Chain Sequences of Actions

An essential feature of OpenWhisk is the ability to chain action in sequences, creating actions that use, as an input, the output of another action, as shown in Figure Figure 3-1.

Figure 3-1. Actions chained in a sequence

Let’s do a practical example of a similar action sequence. We implement a word count application, separating it in two actions, put in a sequence. The first action splits the input, that is supposed to be a text file, in “words”, while the second retrieves the words and produce a map as a result. In the map, each word is then shown with its frequency.

Let’s start with the first action, split.js, as follows:

function main(args) {
    let words = args.text.split(' ')
    return {
        "words": words
    }
}

You can deploy and test it, feeding a simple string:

$ wsk action update basics/split basics/split.js
ok: updated action basics/split
$ wsk action invoke basics/split \
  -p text "the pen is on the table" -r \
  | tee save.json 
{
    "words": [
        "the",
        "pen",
        "is",
        "on",
        "the",
        "table"
    ]
}

note here we are saving the output in a file save.json

Now it is time to do the second step, with this count.js actions:

function main(args) {
    let words = args.words
    let map = {}
    let n = 0
    for(word of words) {
       n = map[word]
       map[word] = n ? n+1 : 1
    }
    return map
}

We can now deploy it and check the result, feeding the output of the first action as input:

$ wsk action update basics/count count.js
ok: updated action basics/count
$ wsk action invoke basics/count -P save.json -r
{
    "is": 1,
    "on": 1,
    "pen": 1,
    "table": 1,
    "the": 2
}

Now we have two actions, the second able to take the output of the first as input, we can create a sequence:

wsk action update basics/wordcount \
  --sequence basics/split,basics/count 

note here we are specifying a comma-separated list of existing action names

The sequence can be now invoked as a single action, so we can feed the text input and see the result:

$ wsk action invoke basics/wordcount -r -p text  \
"can you can a can as a canner can can a can"
{
    "a": 3,
    "as": 1,
    "can": 6,
    "canner": 1,
    "you": 1
}

Actions including Libraries

In the simplest case, your action is just a single javascript file. However, as we are going to see, very often commonly you have some code you want to share and reuse between actions.

The best way to handle this situation is to have a library of code that you can include for every action and that you deploy with your actions.

Let’s consider this example: a couple of utility functions that format a date in a standard format “YYYY/MM/DD” and time in the standard format “HH:MM:SS”.

function fmtDate(d) {
    let month = '' + (d.getMonth() + 1),
        day = '' + d.getDate(),
        year = d.getFullYear();
    if (month.length < 2) month = '0' + month;
    if (day.length < 2) day = '0' + day;
    return year + "/" + month + "/" + day
}

function fmtTime(d) {
    let hour =  ''+ d.getHours(),
        minute = '' + d.getMinutes()
        second = '' + d.getSeconds()

    if(hour.length < 2) hour = "0"+hour
    if(minute.length < 2) minute = "0"+minute
    if(second.length <2 ) second = "0"+second

    return hour + ":" + minute + ":" + second
}

You may, of course, copy this code in each action file, although it is pretty awkward to maintain. Just consider that when you change the function, you have to change it in all the copies of the functions across multiple files. Of course, there is a better way.

Since actions are executed using NodeJs, you have the standard export/require mechanism available for writing your actions.

As a convention, we are going to place our shared code in a subdirectory named lib, and we treat them as modules.

So you should place the format date-time listing above in a file lib/datetime.js and add at the end the following code:

module.exports = {
    fmtTime: fmtTime,
    fmtDate: fmtDate
}

Now you can use the two functions in one action. For example let consider an action named clock that returns the date if invoked with date=true, the time if invoked with time=true, or both if the date and time parameters are specified.

Our action will starts requiring the library with:

var dt = require("./lib/datetime.js")

This way you can access the two functions as dt.fmtDate and dt.fmtTime. Using those functions, we can easily write the main body, called clock.js:

function main(args) {
  let now = args.millis ? new Date(args.millis) : new Date()
  let res = " "
  if(args.date)
    res = dt.fmtDate(now) + res
  if(args.time)
    res = res + dt.fmtTime(now)
  return {
    body: res
  }
}
exports.main = main

Now, we have to deploy the action, but we also need to include the library. How can we do this in OpenWhisk?

The solution is to deploy not a single file but a zip file that includes all the files we want to run as a single action.

When deploying multiple files, you need either to put your code in a file index.js or to provide a package.json saying which one is the main file.

Let’s perform this procedure with the following commands:

$ cd basics
$ echo '{"main":"clock.js"}' >package.json
$ zip -r clock.zip clock.js package.json lib    
  adding: clock.js (deflated 40%)
  adding: package.json (stored 0%)
  adding: lib/ (stored 0%)
  adding: lib/datetime.js (deflated 57%)
$ wsk action update basics/clock clock.zip \
  --kind nodejs:6                               
ok: updated action basics/clock

creating a zip file with subdirectories, so the -r switch is required

specifying the runtime we want to use is nodejs:6

Let’s test it:

$ wsk action invoke basics/clock -p date true -r
{
    "body": "2018/03/18 "
}
$ wsk action invoke basics/clock -p time true -r
{
    "body": " 15:40:42"
}

Associate Triggers to Actions with Rules

Once we have a trigger and some actions we can create rules for the trigger. A rule connects the trigger with an action, so if you fire the trigger, it will invoke the action. Let’s see in practice in the next listing.

$ wsk rule create basics-alert-alpha \
       basics-alert basics/log-alpha                      
ok: created rule basics-alert-alpha
$ wsk trigger fire basics-alert                           
ok: triggered /_/alert with id 86b8d33f64b845f8b8d33f64b8f5f887
$ wsk activation logs 86b8d33f64b845f8b8d33f64b8f5f887 \  
   | jq                                                   
{
  "statusCode": 0,
  "success": true,
  "activationId": "b57a1f1dc3414b06ba1f1dc341ab0626",     
  "rule": "openwhisk@sciabarra.com_dev/alert-alpha",
  "action": "openwhisk@sciabarra.com_dev/basics/alpha"
}

$ wsk activation logs b57a1f1dc3414b06ba1f1dc341ab0626    
2018-03-17T18:10:48.471777977Z stdout: alpha

creating a rule to activate the action alpha

we can now fire the rule, it returns an activation id

let’s inspect the activation id

we piped the output in the jq utility to make the output more readable

in turn the rule enabled an action with this activation id

let’s see what the rule did

A trigger can enable multiple rules, so firing one trigger actually activates multiple actions.

Let’s try this feature in the next listing. However, before starting, let’s open another terminal window and enable polling (with the command wsk activation poll) to see what happens.

$ wsk rule create basics-alert-beta basics-alert basics/log-beta
ok: created rule basics-alert-beta
$ wsk trigger fire basics-alert
ok: triggered /_/basics-alert with id a731a03603bb4183b1a03603bb8183ce

If we check the logs we should see something like this:

$ wsk activation poll
Enter Ctrl-c to exit.
Polling for activation logs

Activation: 'alert' (a731a03603bb4183b1a03603bb8183ce)    
[
    "{\"statusCode\":0,\"success\":true,\"activationId\":\"3024596c57ac4c10a4596c57ac7c1042\",\"rule\":\"openwhisk@sciabarra.com_dev/basics-alert-alpha\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-alpha\"}",
    "{\"statusCode\":0,\"success\":true,\"activationId\":\"6d88836c860d405f88836c860d305f83\",\"rule\":\"openwhisk@sciabarra.com_dev/basics-alert-beta\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-beta\"}"
]

Activation: 'log-alpha' (3024596c57ac4c10a4596c57ac7c1042) 
[
    "2018-03-17T18:34:58.633797676Z stdout: alpha"
]

Activation: 'log-beta' (6d88836c860d405f88836c860d305f83)  
[
    "2018-03-17T18:34:58.629413468Z stdout: beta"
]

The trigger activation invoked 2 actions

This is the log of the first action

This is the log of the second action

Rules can also be enabled and disabled without removing them. As the last example, we try to disable the first rule and fire the trigger again to see what happens. As before, first, we start the log polling to see what happened.

$ wsk rule disable basics-alert-alpha     
ok: disabled rule basics-alert-alpha
$ wsk rule enable basics-alert-beta       
ok: enabled rule basics-alert-beta
$ wsk rule list                           
rules
/openwhisk@sciabarra.com_dev/basics-alert-beta                                private              active
/openwhisk@sciabarra.com_dev/basics-alert-alpha                               private              inactive
$ wsk trigger fire basics-alert           
ok: triggered /_/basics-alert with id 0f4fa69d910f4c738fa69d910f9c73af

disabling rule alert-alpha

enabling rule alert-beta (just to be sure)

a quick listing confirms only one active rule

firing the trigger again

Moreover, if we go and check the result, we see this time only the action log-beta was invoked.

$ wsk activation poll
Enter Ctrl-c to exit.
Polling for activation logs

Activation: 'basics-alert' (0f4fa69d910f4c738fa69d910f9c73af)
[
    "{\"statusCode\":0,\"success\":true,\"activationId\":\"a8221c7d7fe94e22a21c7d7fe9ce223c\",\"rule\":\"openwhisk@sciabarra.com_dev/alert-beta\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-beta\"}",
    "{\"statusCode\":1,\"success\":false,\"rule\":\"openwhisk@sciabarra.com_dev/basics-alert-alpha\",\"error\":\"Rule 'openwhisk@sciabarra.com_dev/basics-alert-alpha' is inactive, action 'openwhisk@sciabarra.com_dev/basics/log-alpha' was not activated.\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-alpha\"}"
]

Activation: 'log-beta' (a8221c7d7fe94e22a21c7d7fe9ce223c)
[
    "2018-03-18T07:27:14.01530577Z  stdout: beta"
]

Asynchronous invocation

A promise is a way to wrap an asynchronous computation in an object that can be returned as a result for a function invocation.

To understand why we need to do that, let’s consider as an example a simple script that generates a new UUID using the website httpbin.org. We are using here the https NodeJS standard API.

The following code opens a connection to the website, and then define a couple of callbacks to handle the data and error events. In Javascript, providing callbacks is the standard way of handling events that do not happen immediately, but later in the future, the so-called “asynchronous” computations.

var http = require("https")

function uuid(callback) {
   http.get("https://httpbin.org/uuid",
   function(res) {
     res.on('data', (data) =>
        callback(undefined, JSON.parse(data).uuid))
   }).on("error", function(err) {
     callback(err)
   })
}

You can note that this function does not return anything. The user of the function, to retrieve the result and do something with it (for example, print it on the console) have to pass a function, like this:

uuid(function(err, data) {
   if(err) console.log("ERROR:" +err)
   else console.log(data)
})

We can use this code locally with NodeJS, but we cannot deploy it as an action, for the simple reason it does not return anything, while the main action must always expect you return “something”.

In OpenWhisk, the “something” expected for asynchronous computation is a “Promise” object. However, what is a Promise? How you build it? Let’s see the details in the next paragraph.

Introducing Promises

We have just seen an example of an asynchronous computation. This code in the latest listing does not return anything, because the computation is asynchronous. Instead of waiting for the result, we provide a function as a parameter. It will perform our work later, only when the computation finally completes.

In OpenWhisk instead, we cannot do this. We need a way to return the asynchronous computation as a result. So the computation must be wrapped in some object we can return as an answer to the action. The solution for this requirement is called Promise, and the OpenWhisk API is heavily based on it.

A Promise is an object that is returned by a function requiring asynchronous computations. It provides the methods to retrieve the result of this computation when it completes.

Using promises (we are going to see how to create one in the next paragraph) we can keep the advantage of being asynchronous while encapsulating this fact in an object that can be passed around and returned as the result of a function invocation.

It is essential to understand that even with a Promise, the computation is still asynchronous, so the result can be retrieved only when ready because we do not know in advance when the result is going to be available. Furthermore, an asynchronous computation can also fail with an error.

Promises combine a nice way to retrieve result and error management. With the promise-based genuuid that we will see next, extracting the value and managing the erros will be peformed with the following code:

var p = uuid()
p.then(data => console.log(data))
 .catch(err => console.log("ERROR:"+err))

Creating a Promise

Let’s translate the genuuid example to make it Promise based.

Instead of requiring a callback we wrap out asynchronous code in a function block like this:

return new Promise(function(resolve, reject) { 
    // ok
    resolve(success)                           
    // K.O.
    reject(error)                              
})

wrapper function to create an isolated environment

what to do when you got the result successfully

what to do when you catch an error

It can look a bit twisted, but it makes sense. A function wraps asynchronous code for 3 reasons:

• create an isolated scope

• be invoked only when the Promise resolution is required

• use the arguments to pass to the code block two functions for returning the result and catching errors

So the real work of wrapping the asynchronous behavior is performed by the function. We could at this point return the function, but we still need some work:

• starting the invocation when needed (then)

• catching errors (catch)

• provide our implementation of the resolve

• provide our implementation of the reject.

Hence, we further wrap the function in a Promise object and return it as a result. Finally, we have created the standard Promise we described before.

Using a Promise we can now implement our genuuid function. Translating the callback is straightforward:

var http = require("https")

function uuid() {
  return new Promise(function(resolve, reject){ 
    http.get("https://httpbin.org/uuid",
     function(res) {
      res.on('data', (data) =>
         resolve(JSON.parse(data).uuid))        
     }).on("error", function(err) {
         reject(err)                            
    })
  })
}

wrap the asynchronous code in a Promise

success, we can return the result with resolve

failure, returning the error with reject

As you can see the code is similar to the standard way using a callback, except we wrap everything in a function that provides the resolve and reject actions. The function is then used to build a Promise. Most of the implementation of the Promise is standard; only the function must be defined to implement the specific behavior.

Now, using the Promise, we are now able to create an action for OpenWhisk, providing the following main:

function main() {
    return uuid()
      .then( data =>  ({"uuid": data}))
      .catch(err =>   ({"error": err}))
}

Let’s try the code:

$ wsk action update apidemo/promise-genuuid \
      apidemo/promise-genuuid.js
ok: updated action apidemo/promise-genuuid
$ wsk action invoke apidemo/promise-genuuid -r
{
    "uuid": "52a188a9-ff9b-4f3a-b72d-301c26aac2cf"
}

Overview of the API

The OpenWhisk API provides the same functions available on the command line interface.

Some features are more useful than others for actually writing action code. The most important is, of course:

• ow.actions

• ow.triggers

• ow.activations

We are going to cover those API in details.

There are available many other features that are useful for deploying code. We will not discuss those features here since are needed when you develop your deployment tools. Those other available features are:

• ow.rules

• ow.packages

• ow.feeds

Invoking multiple promises

We learned how to create Promises, and we have seen how to use them for chaining asynchronous operations.

Another important use case to consider, however, is when you have multiple promises. In such a case you may want to wait for all of them to complete.

We could wait for multiple actions with some complex code involving then. Since this use case is frequent enough, it is worth the availability of a standard method: Promise.all(promises).

Within this method call, the promises are an array of Promises (actually, anything satisfying the “iterable” Javascript protocol). As a result, it returns a Promise that completes when all the other promises complete.

You can then retrieve the combined result of all the Promises with a then function, receiving, as a result, an array of the results of the many Promises.

We can now construct an example to demonstrate this feature. We are going to create a Web action consisting in multiple promises (actually multiple invocations). Then we wait for all of them to complete, and finally, we construct a web page concatenating the results. You may notice in the example the use of map, that is probably idiomatic in those cases.

var openwhisk = require("openwhisk")

function main(args) {
    let ow = openwhisk()
    let count = args.n ? args.n : 3;                       
    let inv = { name: "apidemo/promise-genuuid",
                blocking: true,
                result: true
    }
    let promises = []
    for(let i=0; i< count; i++)                            
        promises.push(ow.actions.invoke(inv));
    return Promise.all(promises)                           
      .then(res => ({
            body: "<h1>UUIDs</h1><ul><li>"+
                   res.map(x=>x.uuid).join("</li><li>")+   
                   "</li></ul>"
        }))
}

we are reading a parameter from the URL, if not specified it defaults to 3

we are looping, constructing an array of invocations, each one asking for a different uuid

this is the key call: we are waiting for all the promises to complete

the final result is built here, in the form of an array of results, each one being a different UUID. We join them to create a dotted list in HTML.

Now, we can test the invocation and check the results.

$ wsk action update apidemo/invoke-genuuid-list \        
  apidemo/invoke/invoke-genuuid-list.js  --web true
ok: updated action apidemo/invoke-genuuid-list
$ curl $(wsk action get apidemo/invoke-genuuid-list  \   
         --url | tail -1)
<h1>UUIDs</h1>                                           
<ul>
  <li>3b72aec9-eb1d-45e9-9c98-d689a6bddf2b</li>
  <li>3189605c-d003-469b-afcc-202ef690a544</li>
  <li>3e78ee6d-f141-483b-8d1a-7e8aaaae309d</li>
</ul>

Deployment of the action wrapping multiple promises as a web action

Invocation of the new action using curl and extracting the url

The result is now the combination of multiple invocation of the promise-genuuid action

Using Jest

As we already pointed out, there are a lot of test tools available for Javascript and NodeJS. So many that is difficult to make a choice. But since we need to pick one to write our tests, we selected one that we believe it is a right balance between ease of use and completeness.

We ultimately picked Jest, the test tool developed by Facebook as a complement to testing React applications. We are not going to use React in this book, but Jest is independent of React, and it is a good fit for our purposes.

Some Jest features I cannot live without are:

• it is straightforward to install

• it is pretty fast

• it supports snapshot testing

• it provides extensive support for “mocking.”

Of course, this does not mean other tools does not have similar features. But we have to settle on someone.

So, assuming you agree with this choice, let’s start installing it. It is not difficult:

$ npm install -g jest                  
+ jest@22.4.3
updated 1 package in 13.631s
$ jest --version                       
v22.4.3

install Jest as a global command

check if jest is now available as a command

Since now we have Jest, we can write a test. Our first test will check a modified version of the word count action (count.js) we used in chapter 2.

The action we are going to test receives its input as a property text of an object args, split the text in words by itself, then it counts words, returning a table with all the words and a count of the occurrences.

Here is the updated version wordcount.js:

function main(args) {
    let words = args.text.split(" ")
    let map = {}
    let n = 0
    for(word of words) {
       n = map[word]
       map[word] = n ? n+1 : 1
    }
    return map
}
module.exports.main = main             

add an export of the function

In OpenWhisk, you can deploy a simple function. It works as long as it as a main function. When you want to use it locally in a test, however, it must be a proper module so a test can import it. So here is an important suggestion:

We can now write a test for wordcount that we can run with Jest. A test is composed of 3 important parts:

• import of the module we want to test with require

• declare a test with the function test(<description>, <test-body>) where <description> is a string and <test-body> is a function performing the test

• in the body of the test you perform some assertions in the form expect(<expression>).toBe(<value>) or similar (there are many different toXXX methods; we will see next)

We have to write now a wordcount.test.js with the following code:

const wordcount =
      require("./wordcount").main                
test('wordcount simple', () => {                 
    res = wordcount({text: "a b a"})             
    expect(res["a"]).toBe(2)                     
    expect(res["b"]).toBe(1)                     
})

import the module wordcount.js under test

declare a test

invoke the function

ensure it found two ``a``s

ensure it found one ``b``s

We are ready to run the tests, but before we go on, we need to create a file package.json, as simple as this:

{ "name": "jest-samples" }

Now you can run the test. You can do it directly using the jest command line from the directory containing all our files:

$ ls
package.json
wordcount.js
wordcount.test.js
$ jest
 PASS  ./wordcount.test.js
  ✓ wordcount simple (3ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.341s
Ran all test suites matching /wordcount/i.

Jest started to search for tests, found our wordcount.test.js, loaded it and executed all the test in it, then showed the results.

{
  "name": "jest-samples",
  "scripts": {
    "test": "jest"
  }
}

Configuring an Environment to Locally run OpenWhisk actions

So far we have seen how to run tests in general. Now we focus on actually being able to execute tests locally to unit test them.

In general, actions in OpenWhisk runs under NodeJS, so the same code you can execute in your computer with NodeJS should also work in OpenWhisk, as long as the environment is the same.

You need however to match the environment, so you may need to install locally the same libraries and the same version of NodeJS in use in OpenWhisk.

To match the environment, when you run your tests you need to: * run your tests with the same version of Node * have the same Node Packages installed locally * load code in the same way as OpenWhisk load it * provide the same environment variables that are available in OpenWhisk

Let’s discuss those needs in order.

$ nvm install v6.14.1                            
Downloading https://nodejs.org/dist/\
  v6.14.1/node-v6.14.1-darwin-x64.tar.xz...
######### 100,0%
Now using node v6.14.1 (npm v3.10.10)
$ node -v
v6.14.1
$ npm init --yes                                 
Wrote to  chapter4/package.json
$ npm install --save cheerio@0.22.0              
chapter4@1.0.0 chapter4
└─┬ cheerio@0.22.0

const Validator = require("./lib/validator.js")
function checkEmail(input) {                           
  var re = /\S+@\S+\.\S+/;
  return re.test(input)
}
var errmsg = " does not look like an email"
class EmailValidator extends Validator {
    validator(value) {
        let error = super.validator(value);
        if (error) return error;
        if(checkEmail(value))                          
            return "";
        return value+errmsg
    }
}
function main(args) {
    if(args.errmsg) {                                  
        errmsg = args.errmsg
        delete args.errmsg
    }
    return new EmailValidator("email").validate(args)
}
module.exports = {
  main: main,                                          
  checkEmail: checkEmail                               
}

const main = require("./email").main
const checkEmail = require("./email").checkEmail

test("checkEmail", () => {
 expect(
  checkEmail("michele@sciabara.com"))
    .toBe(true)
 expect(
  checkEmail("http://michele.sciabarra.com"))
    .toBe(false)
})

test("validate email", () => {
 expect(main({email: "michele@sciabarra.com"})
   .message[0])
   .toBe('email: michele@sciabarra.com')
 expect(main({email:"michele.sciabarra.com"})
   .errors[0])
   .toBe('michele.sciabarra.com does not look like an email')
})

Setting OpenWhisk Enviroment Variables

In OpenWhisk you use the OpenWhisk API to interact with other actions. We already discussed in Chapter 3 how you invoke actions, fire triggers, read activations and so on.

When you want to invoke other actions running in the same namespace as the main action, you need to use require("openwhisk") and then you can access the API. At least, this is what happens your application is running inside OpenWhisk.

When your code is running outside OpenWhisk, as it happens when you are running unit tests it, the OpenWhisk API cannot talk with other actions because every request needs authentication. Hence, if you try to run your code outside of OpenWhisk, you will get an error.

We can demonstrate this fact considering a simple action dbread.js, able to read a single record we put in the database with the Contact Form:

const openwhisk = require("openwhisk")
function main(args) {
  let ow = openwhisk()
  return ow.actions.invoke({
    name: "patterndb/read",
    result: true,
    blocking: true,
    params: {
      docid: "michele@sciabarra.com"
    }
  })
}
module.exports.main = main

If we deploy and run the action in OpenWhisk there are no problems:

$ wsk action update dbread dbread.js
ok: updated action dbread
$ wsk action invoke dbread -r
{
    "_id": "michele@sciabarra.com",
    "_rev": "5-011e075095301fcfc350cac66fd17c7e",
    "type": "contact",
    "value": {
        "name": "Michele",
        "phone": "1234567890"
    }
}

However, let’s try to write and run a test dbread.test.js for this simple action:

const main = require("./dbread").main
test("read record", () => {
   main().then(r => expect(r.value.name).toBe("Michele"))
})

If we run the test, the story is a bit different:

$ jest dbread
 FAIL  ./dbread.test.js
  ✕ read record (8ms)

  ● read record

    Invalid constructor options. Missing api_key parameter.

      1 | const openwhisk = require("openwhisk")
      2 | function main(args) {
    > 3 |   let ow = openwhisk()
      4 |   return ow.actions.invoke({
      5 |     name: "patterndb/read",
      6 |     result: true,

      at Client.parse_options (node_modules/openwhisk/lib/client.js:80:13)
      at new Client (node_modules/openwhisk/lib/client.js:60:25)
      at OpenWhisk (node_modules/openwhisk/lib/main.js:15:18)
      at main (dbread.js:3:12)
      at Object.<anonymous>.test (dbread.test.js:5:4)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        1.021s
Ran all test suites matching /dbread/i.

As we discussed in Chapter 3 when we introduced the API, the OpenWhisk library needs to know the host to contact to perform requests (the API host) and must provide an authentication key to be able to interact with it.

When your application is running in the cloud in OpenWhisk, those keys are available through two environment variables \\__OW_API_HOST and \\__OW_API_KEY. It is the OpenWhisk environment that sets them before executing the code.

When your code is running locally, those variables are not available, unless your test code takes care of setting them. Luckily, it is it pretty easy to provide them locally. Indeed, if you are using the tool wsk and you have configured properly, it stores credentials in a file named .wskprops in the home directory.

Because the format of this is compatible with the syntax of the shell, if you are using bash (as we always assumed you are doing in this book) you can load those environment variables with the following commands:

$ source ~/.wskprops
$ export __OW_API_HOST=$APIHOST
$ export __OW_API_KEY=$APIKEY

Now, with those environment variables set, you can try again to run the test, and this time you will be successful:

$ jest dbread
 PASS  ./dbread.test.js
  ✓ read record (22ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.951s, estimated 1s
Ran all test suites matching /dbread/i.

Your local code is using credentials and can contact and interact with the real server to run the test.

 "scripts": {
    "test": "source $HOME/.wskprops;               
 __OW_API_HOST=$APIHOST
 __OW_API_KEY=$AUTH jest"
  },

this is actually one long line split in three lines for typesetting purposes

Snapshot Testing

A common problem, in the test phase, is the burden of having to check results. You may end up to writing a lot of code that the result against the expected values. Luckily, there are techniques (that we are going to see) to reduce the amount of repetitive and pointless code you have to write.

When you test, you decide on a set of data corresponding to the various scenarios you want to verify. Then you write your test, invoking your code against the test data, and check the results. While defining the test data is generally an exciting experience, because you have to think about your code and what it does, verifying that the results are the expected one is typically not an exciting activity.

Jest provides a large number of “matchers” to make easy result verification. Matchers work well when results are small. But sometimes test results are pretty large; hence the code to check the result can be not only dull but also substantial.

There is an alternative to automate this activity, to focus more on checking the results and less on writing repetitive and naive code: snapshot testing.

The idea of snapshot testings is pretty simple: when you run a test the first time, you save the test results in a file. This file is called a “snapshot.” You can then check the result is correct. You do not have to write code, only verify the expected result checking the snapshot.

If the result is correct, you can commit the snapshot into the version control system. When you rerun a test, if there is already a snapshot in place, the test tool will automatically compare the new result of the test with the snapshot. If it is the same, the test passes, otherwise, it fails.

Let’s see snapshot testing in Jest with an example. You implement snapshot testing using the simple matcher called toMatchSnapshot().

We now modify the two tests in the preceding paragraph to use snapshot testing. While the test for checkEmail simply checks if the result is true or false (so there is not any significant advantage in using snapshot testing), the test for validateEmail is a bit more complicated.

Indeed, we wrote a test expressions like this:

expect(main({email: "michele@sciabarra.com"})
   .message[0])
   .toBe('email: michele@sciabarra.com')
expect(main({email: "michele.sciabarra.com"})
   .errors[0])
   .toBe('michele.sciabarra.com does not look like an email')

Here we are taking the test output, extracting some pieces (.message[0] or .errors[0]) to verify only a part of the result.

We could save yourself from the burden of thinking which parts to inspect just writing:

test("validate email with snapshot", () => {
  expect(main({email: "michele@sciabarra.com"})
   .toMatchSnapshot()
  expect(main({email: "michele.sciabarra.com"})
   .toMatchSnapshot()
})

Now, if you run the test, Jest will save the results of the tests. Of course, we should always check that the snapshot is correct. Here is the first execution of the tests, when you create the snapshots:

$ jest email-snap
 PASS  ./email-snap.test.js
  ✓ validate email with snapshot (7ms)

 › 2 snapshots written.                         
Snapshot Summary
 › 2 snapshots written in 1 test suite.

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   2 added, 2 total                   
Time:        0.899s, estimated 1s

running the test creates two snapshots

summary of the snapshots in the test

Jest creates a folder named __snapshots__ to store snapshots; then, for each test, it writes a file named after the filename containing the snapshots:

__snapshots__/email-snap.test.js.snap

This file is human readable, and it was designed e expecting that a human can reads it to be sure the result of the snapshot are as expected.

For example, this is the content of the snapshot file just created:

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`validate email with snapshot 1`] = `  
Object {
  "email": "michele@sciabarra.com",
  "errors": Array [],
  "message": Array [                           
    "email: michele@sciabarra.com",
  ],
}
`;

exports[`validate email with snapshot 2`] = `  
Object {
  "email": "michele.sciabarra.com",
  "errors": Array [                            
    "michele.sciabarra.com does not look like an email",
  ],
  "message": Array [],
}
`;

result of the first test, with a correct email

we produce an array of messages

result of the second test, with a wrong email

we produce an array of errors

Now, once we have verified the snapshot to be correct, all we have to do is to keep it, saving in the version control system. If the snapshot is already present, running again the tests will compare the test execution against the snapshot, as follows:

$ jest email-snap.test.js
 PASS  ./email-snap.test.js
  ✓ validate email with snapshot (7ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   2 passed, 2 total
Time:        0.876s, estimated 1s

Updating a Snapshot when something change

Once a snapshot is in place, Jest will verify the tests always returns the same result. But of course, snapshots cannot be set on stone. It may happen that something change and we will have to update the snapshot. So let’s make now an example of a failed test verified comparing a snapshot, then update that snapshot.

For example, assume we decide that from now we want to consider acceptable only emails having a dot in the username. This example is, of course, non-realistic, made only to add another constraints to fail on purpose some snapshot tests and act as a consequence.

So, we change the regular epression to validate the emails:

before: var re = /\S+@\S+\.\S+/;
after : var re = /\S+\.\S+@\S+\.\S+/;

If we now run the tests, we see they are now failing:

FAIL ./email-snap.test.js
  ✕ validate email with snapshot (17ms)

  ● validate email with snapshot

    expect(value).toMatchSnapshot()

    Received value does not match stored snapshot 1.

    - Snapshot
    + Received

      Object {
        "email": "michele@sciabarra.com",
    -   "errors": Array [],
    -   "message": Array [
    -     "email: michele@sciabarra.com",
    +   "errors": Array [
    +     "michele@sciabarra.com does not look like an email",
        ],
    +   "message": Array [],
      }

      2 |
      3 | test("validate email with snapshot", () => {
    > 4 |     expect(main({email: "michele@sciabarra.com"})).toMatchSnapshot()
      5 |     expect(main({email: "michele.sciabarra.com"})).toMatchSnapshot()
      6 | })
      7 |

      at Object.<anonymous>.test (testing/strategy/email-snap.test.js:4:52)

 › 1 snapshot test failed.
Snapshot Summary
 › 1 snapshot test failed in 1 test suite. Inspect your code changes or re-run \
      jest with `-u` to update them.

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   1 failed, 1 passed, 2 total
Time:        0.967s, estimated 1s
Ran all test suites matching /email-snap.test.js/i.

We can fix the test replacing the first email:

expect(main({email: "michele.sciabarra@gmail.com"}))
.toMatchSnapshot()

However, if we run the test again, it will still be failing because the snapshot expects a michele@sciabarra.com somewhere.

We need to update the tests using jest -u. The flag -u tells to Jest to discard the current content of the snapshot cache and recreate them.

After updating tests of course, you should check that the new snapshot is correct. Indeed we have now:

 "message": Array [
    "email: michele.sciabarra@gmail.com",
  ],

and the new snapshot is ready to be used for further tests.

Mocking an https request

The concept behind mocking is pretty simple: you run your code replacing a system you interface with, using a simulation that you can execute locally. The simulation generally runs without connecting to any real system and providing dummy data.

To better understand how it works, and which problem mocking solves, let’s consider a common problem: testing code that executes a remote HTTP call. We are going for this purpose to write a simple action httptime.js, that just return the current time.

However, to make it a case of an action “hard” to test it, the implementation is going to use another action, invoked via http, that will return the date and time in full format, from where our action will extract the time.

We will have to use the NodeJS https module, that is a bit low level; also we need to wrap the call in a Promise, to conform to OpenWhisk requirements. For those reasons the code is a bit more convoluted than we would like it to be. However, since mocking https call is a frequent and important case, it is worth to follow this example in full.

The action to be tested by Mocking

The code in the following listing, implementing an action that returns current time via another action providing date and time, works this way:

• wraps everything in a promise, providing a resolve function

• opens an http request to an url, provide as a parameter

• define event handlers for two events: data and end

• collect data as they are received

• at the end extract the time with a regular expression

const https = require("https")

function main(args) {
  return new Promise(resolve => {                    
    let time = ""                                    
    https.get(args.url, (resp) => {                  
      resp.on('data', (data) => {                    
        time += data                                 
      })
      resp.on('end', () => {                         
        var a = /(\d\d:\d\d:\d\d)/.exec(time)        
        resolve({body:a[0]})                         
      })
     })
   })
}

wrap everything in a promise

this variable collects the input

use the https module

handle the data event, new data received

collect the data

handle the end event, all data received

this regexp extract the time from the date

return the value extracted

For convenience, let’s test first the real thing, deploying it in OpenWhisk. We need to create also the action service that returns the current time and date.

Note the following commands, that create on the fly an action on the command line and pass its url to our action:

$ CODE="function main() {\                           
>  return { body: new Date() } }"
$ wsk action update testing/now <(echo $CODE) \      
   --kind nodejs:6 --web true
$ URL=$(wsk action get testing/now --url | tail -1)  
$ curl $URL                                          
2018-05-02T19:42:34.289Z

store some code in a variable

use a bash feature to create a temporary file

get the url of the newly created action

invoke the action in http

We can now deploy and invoke the action to see if it works:

$ wsk action update testing/httptime httptime.js \
  -p url "$URL" --web true
$ TIMEURL=$(wsk action get testing/httptime --url | tail -1)
$ curl $TIMEURL
20:06:55

Mocking the https module

The example action we just wrote is a typical example of an action difficult to unit test, for many common reasons:

• it invokes a remote service, so to run tests you need to be connected to the internet

• you also need to be sure the invoked service is readily available

• data returned changes every time, so you cannot compare results with fixed values

Hence we have a is a perfect candidate for testing by mocking the remote service. We need to replace the https call with a mock that will not perform any remote call. Let see how to do it with Jest.

To replace the https module with a mock the following steps are required:

• put code that replaces the https modules with your code in a directory called __mocks__

• use jest.mock('https') in your test code before importing the module to test

• write your test code as if you were using the real service

When you perform a require in a jest test, it will load your mocking code instead of the regular code. Since we want to replace the https module, we need to write a __mocks__\https.js mock code.

Now it is time to write the mock code that should replace the https call.

To better understand it, let’s split the description into two steps. At the top level, it works mostly in this way:

https.get(URL, (resp) =>
   resp.on('data', (data) => {

     // COLLECT_DATA

   }

   resp.on('end', () => {

      // COMPLETE_REQUEST

   }

}

The “real” https module receives an object (resp) as a gatherer of event handling functions, that mimic how https works. The protocol https, when performing a request, opens a connection to an URL, then read and return results in multiple chunks. For this reason, you can have multiple calls to the data event executing the code marked as COLLECT_DATA. Hence you need to collect data before analyzing them. When all the data are collected, you get one (and only one) invocation to execute the code marked as COMPLETE_REQUEST.

If we want to emulate this code with a mock, we need to do the following steps:

1. first create an object that store the event handler

2. invoke once (or more) the data event handler

3. invoke once the end event handler

So, the code to gather the events is:

var observer = {               
   on(event, fun) {            
       observer[event] = fun   
    }
}

create an object

define an on function

assign to a field named as the event a function

This code is simple, but is it not so obvious. It defines an object that can register event handlers, and then can invoke them by name, as follows:

observer.on('something', doSomething)

observer.something(1)

So if you pass the observer to the https.get function, you will get being able to invoke the two handlers registered. Code will register resp.on('data', dataFunc) and resp.on('end', endFunc). Afterwards you will invoke just resp.data("some data") and resp.end().

Now that we have our observer, the full mock is much simpler to write.

// observer here, omitted for brevity

function get(url, handler) {       

    handler(observer)              

    observer.data(url)             

    observer.end()                 

}

module.exports.get = get

it will be invoked as https.get(url, handler)

to fully understand this, review the first listing in this section

important: we are using the URL itself as the value returned by the mocked https call

invoke the end handler

Now, we can use the our __mock__/https.js to write a test https.test.js:

jest.mock('https')                        
const main = require('./httptime').main   
test('https', () => {                     
  main({
    url: '2000-01-01T00:00:00.000Z'       
  }).then(res => {                        
    expect(res.body).toBe('00:00:00')     
  })
})

enable the mock

import the action locally for test

declare a test

invoke the main, remember we use the URL as the data!

the action returns a promise, so we have to handle it

check the handler extracts the time from the date

To be sure, we try to rerun the test with different data:

test('https2', () => {
  main({ url: '2018-05-02T19:42:34.289Z' })
  .then(res => {
    expect(res.body).toBe('19:42:34')
  })
})

The final result:

$ jest httptime
 PASS  ./httptime.test.js
  ✓ https (5ms)
  ✓ https2 (1ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.222s
Ran all test suites matching /httptime/i.

Using the mocking library to invoke an action

To use our library, we have to follow some conventions in the layout of our code.

When your application runs in OpenWhisk, you do not have the problem of locating the code when invoking an action. You deploy them with the name you choose, then use this name in the action invocation. It is the OpenWhisk runtime that resolves the names.

When you test your code locally and simulate invocations by mocking, you do not deploy your action code, but you still invoke it by name. So our mocking library must be to locate the actual code locally. It does following some conventions.

To illustrate the conventions it follows, let’s see an example. We write a test that will invoke an action using the OpenWhisk API.

const ow = require('openwhisk')             
test("invoke email validation", () => {
    ow()                                    
      .actions.invoke({                     
        name: "testing/strategy-email",     
        params: {
          email: "michele.sciabarra.com"    
        }
      }).then(res =>
        expect(res).toMatchSnapshot())
})

initialization of the OpenWhisk library

create the actual invocation instance

perform the invocation

action name

parameters

You must translate the testing/strategy-email name in a file name located in the local filesystem. We use, as the base in the filesystem, the folder with our package.json and node_modules, that is the project root.

By convention, we name our actions according to this structure:

<package>/<prefix>-<action>

Then we expect actions code to be placed in a file named:

<package>/<prefix>/<file>.js

So, when you test locally code invoking the testing/strategy-email action, the mocking library works in this way:

• the require("openwhisk") will actually load the __mocks__/openwhisk.js library

• the mocking library can locate its position from the __dirname variable, hence find the project root (that is, the parent directory)

• using the name of the action, it can now locate the code of the action to invoke: in our case <project-root>/testing/strategy/email.js

Mocking action parameters

There is another essential feature required to complete our simulation for testing.

In OpenWhisk, actions can have additional parameters. Those parameters can be specified when you deploy the action or can be inherited from the package to which the action belongs. When we use our library mocking library, we can simulate those parameters by adding a file with the same name as the action and extension .json.

For example, in our case we have the file testing/strategy/email.json, in the same folder as the email.js with the content:

{
    "errmsg": " is not an email address"
}

The mocking library uses this file, preloading the parameters and passing them as args. Indeed we can check the test has used the parameter errmsg. We need to check the snapshot to see:

$ cat __snapshots__/invoke.test.js.snap                    
// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`invoke email validation 1`] = `
Object {
  "email": "michele.sciabarra.com",
  "errors": Array [
    "michele.sciabarra.com is not an email address",      
  ],
  "message": Array [],
}
`;

dump on the terminal the snapshot file

the error message produced is the one specified in the email.json file

Mocking a sequence

We can now complete our analysis of the mocking library by describing how to mock a sequence.

In Chapter 5 we saw the pattern “Chain of Responsibility” implemented as a sequence.

A sequence does not have a corresponding action, but it does exist as a deployment declaration only. We can simulate an action sequence with a particular value in the JSON file we use to pass parameters.

For example, let consider a test to a sequence:

test('validate4', () =>
 ow().actions.invoke({
   name: 'testing/chainresp-validate',
   params: {
     name: 'Michele',
     email: 'michele.sciabarra.com',
     phone: '1234567890'
   }
}).then(res => expect(res).toMatchSnapshot()))

There is not a testing/chainresp/validate.js file, but there is a testing/chainresp/validate.json with this content:

{
  "__sequence__": [
    "testing/strategy-name",
    "testing/strategy-email",
    "testing/strategy-phone"
  ]
}

You can now write a test for example as follows:

const ow = require('openwhisk')
test('validate', () =>
  ow().actions
    .invoke({
      name: 'testing/chainresp-validate',
      params: {
        name: 'Michele',
        email: 'michele.sciabarra.com',
        phone: '1234567890'
      }
    })
    .then(res => expect(res).toMatchSnapshot()))

The mocking library then read the __sequence__ property from the validate.json and translate in a sequence of invocations (as it would happen in the real OpenWhisk) allowing to test the result of a chained invocation locally.

We can see that the mocking of the sequence works inspecting the snapshot.

// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`validate 1`] = `
Object {
  "email": "michele.sciabarra.com",
  "errors": Array [
    "michele.sciabarra.com is not an email address",  
  ],
  "message": Array [
    "name: Michele",
    "phone: 1234567890",
  ],
  "name": "Michele",
  "phone": "1234567890",
}
`;

error message defined as a parameter

Functions and Events

Computation in a Serverless environment is generally split in functions. A function is typically a piece of code that will receive input and will provide an output in response. It is important to note that a function is expected to be stateless.

Frequently web applications are stateful. Just think of a shopping cart application for an e-commerce: while you navigate the website, you add your items to the basket, to buy them at the end. You keep a state, the cart.

Being stateful however is an expensive property that limits scalability: you need to provide something to store data. Most importantly, you will need something to synchronize the state between invocations. When your load increase, this “state keeping” infrastructure will limit your ability to grow. If you are stateless, you can usually add more servers.

The OpenWhisk solution, and more widely the solution adopted by Serverless environments is the requirement functions must be stateless. You can keep state, but you will use separate storage designed to scale.

To run functions to perform our computations, the environment will manage the infrastructure and invoke the actions when there is something to do.

In short, “having something to do” is what is called an event. So the developer must code thinking what to do when something happens (a request from the user, a new data is available), and process it quickly. The rest belongs to the cloud environment.

In conclusion, Serverless environments allow you to build your application out of simple stateless functions, or actions as they are called in the context of OpenWhisk, triggered by events. We will see later in this chapter which other constraints those actions must satisfy.

Architecture Overview

We just saw OpenWhisk from the outside, and now we have an idea of what it does. Now it is time to investigate its architecture, to understand better how it works under the hood.

Figure 1-2. OpenWhisk High Level Archiecture - Actions

We will refer to the Figure Figure 1-2, with some numbered markers. In the Figure, the big container (see 1) at the center, is OpenWhisk itself. It acts as a container of actions. We will see later what an action and what the container is.

For the architect, you can consider it as an opaque system that executes those actions in response to events.

Programming Languages for OpenWhisk

You can write actions in many programming languages. Probably the more natural to use are interpreted programming languages: like JavaScript (see 2) (actually, Node.js) or Python (see 3). Those programming languages are interpreted and give an immediate feedback since you can execute them without compilation. They are also generally of higher level, hence more comfortable to use (while the drawback is usually they are slower than compiled languages). Since OpenWhisk is a highly responsive system, where you can immediately run your code in the cloud, probably the majority of the developers prefer to use those “interactive” programming languages.

In addition to purely interpreted (or compiled-on-the-fly languages, as it is correct to say), you can use also pre-compiled interpreted languages, like the languages of the Java family. Java, Scala and Kotlin (see 4) are the more common programming languages of this family. They run on the Java Virtual Machine, and they are distributed not in source form but an intermediate form. The developer must create a “jar” file to run the action. This jar includes the so-called “bytecode” that OpenWhisk will execute when it will be deployed . A Java Virtual Machine is the actual executor of the action.

Finally, in OpenWhisk you can use compiled languages, producing a binary executable that runs on “bare metal” without interpreters or virtual machines. Examples of those binary languages are Swift, Go or the classical C/C++, see (see 5).

OpenWhisk supports out-of-the-box Go and Swift. You need to send the code of an action compiled in Linux elf format for the amd64 processor architecture, so a compilation infrastructure is needed. However today, with the help of Docker, is not complicated to install on any system the necessary toolchain for the compilation.

Finally, you can use in OpenWhisk any arbitrary language or system that can you can package like a Docker image (see 6) and that you can publish on Docker Hub: OpenWhisk allows to retrieve such an image and run it, as long as you follow its conventions. We will discuss this in the chapter devoted to native actions.

Actions and Action Composition

OpenWhisk applications are a collection of actions. We already saw the available type of actions. Now let’s see in Figure Figure 1-3 how they are assembled to build applications.

Figure 1-3. Open Whisk High Level Architecture - Components

An action is a piece of code, written in one of the supported programming languages, that you can invoke. On invocation, the action will receive some information as input (see 1).

To standardize parameter passing among multiple programming languages, OpenWhisk uses the widely supported JSON format, since it is pretty simple, and there are libraries to encode and decode this format available basically for every programming language.

The parameters are passed to actions as a JSON string, that the action receives when it starts, and it is expected to process. At the end of the processing, each action must produce its result that is then returned also as a JSON string (see 2).

You can group actions in packages (see 3). A package acts as a unit of distribution. You can share a package with others using bindings. You can also customize a package providing parameters that are different for each binding.

Actions can be combined in many ways. The simplest form of combination is chaining them in sequences (see 4)

Chained actions will use as input the output of the preceding actions. Of course, the first action of a sequence will receive the parameters (in JSON format), and the last action of the sequence will produce the final result, as a JSON string.

However, since not all the flows can be implemented as a linear pipeline of input and output, there is also a way to split the flow of an action in multiple directions. 

This feature is implemented using triggers and rules (see 5).

A trigger is merely a named invocation. You can create a trigger, but by itself a trigger does nothing. However, you can then associate the trigger with multiple actions using Rules.

Once you have created the trigger and associated some action with it, you can fire the trigger providing parameters.

The connection between actions and triggers is called a feed (see 6). A feed is an ordinary action that must follow an implementation pattern. We will see in the chapter devoted to the design pattern. Essentially it must implement an observer pattern, and be able to activate a trigger when an event happens.

When you create an action that follows the feed pattern (and that can be implemented in many different ways), that action can be marked as a feed in a package. In this case, you can combine a trigger and feed when you deploy the application, to use a feed as a source of events for a trigger (and in turn activate other actions).

Nginx

Everything starts when an action is invoked. There are different ways to invoke an action:

• from the Web, when the action is exposed as Web Action

• when another action invokes it through the API

• when a trigger is activated and there is a rule to invoke the action

• from the Command Line Interface

Let’s call the client the subject who invokes the action. OpenWhisk is a RESTful system, so every invocation is translated in an https call and hits the so-called “edge” node.

The edge is actually the web server and reverse proxy Nginx. The primary purpose of Nginx is implementing support for the “https” secure web protocol. So it deploys all the certificates required for secure processing. Nginx then forwards the requests to the actual internal service component, the Controller.

Controller

The Controller, that is implemented in Scala, before effectively executing the action, performs pretty complicated processing.

1. It needs to be sure it can execute the action. Hence the need to authenticate the requests, verifying if the source of the request is a legitimate subject.

2. Once the origin of the request has been identified, it needs to be authorized, verifying that the subject has the appropriate permissions.

3. The request must be enriched with all the default parameters that have been configured. Those parameters, as we will see, are part of the action configuration.

To perform all those steps the Controller consults the database, that in OpenWhisk is CouchDB.

Once validated and enriched, the action is now is ready to be executed, so it is sent to the next component of the processing, the Load Balancer.

Load Balancer

Load Balancer job, as its name states, is to balance the load among the various executors in the system, which are called in OpenWhisk Invokers.

We already saw that OpenWhisk executes actions in runtimes, and there are runtimes available for many programming languages. The Load Balancer keeps an eye on all the available instances of the runtime, checks its status and decide which one should be used to serve the new action requested, or if it must create a new instance.

We got to the point where the system is ready to invoke the action. However, you can not just send your action to an Invoker, because it can be busy serving another action. There is also the possibility that an invoker crashed, or even the whole system may have crashed and is restarting.

So, because we are working in a massively parallel environment that is expected to scale, we have to consider the eventuality we do not have the resources available to execute the action immediately. Hence we have to buffer invocations.

The solution for this purpose is using Kafka. Kafka is a high performing “publish and subscribe” messaging system, able to store your requests, keep them waiting until they are ready to be executed. The request is turned in a message, addressed to the invoker the Load Balancer chose for the execution.

Each message sent to an Invoker has an identifier, the ActivationId. Once the message has been queued in Kafka, the ActivationId is sent back as the final answer of the request to the client, and the request completes.

Because as we said the processing is asynchronous, the Client is expected to come back later to check the result of the invocation.

Invoker

The Invoker is the critical component of OpenWhisk and it is in charge of executing the Actions. Actions are actually executed by the Invoker creating an isolated environment provided by Docker.

Docker can create execution environments (called “Containers”) that resemble an entire operating system, providing everything code written in any programming language needs to run.

In a sense, an environment provided by Docker looks like, as seen by action, to an entire computer for it (just like a Virtual Machine). However, execution within containers is much more efficient than VMs, so they are used in preference to actual emulated environments.

Docker actually uses Images as the starting point for creating containers where it executes actions. A runtime is really a Docker image. The Invoker launches a new Image for the chosen runtime then initialize it with the code of the action.

OpenWhisk provides a set of Docker Images including support for the various languages, and the execution logic to accept the initialization: JavaScript, Python, Java, Go, etc.

Once the runtime is up and running, the invoker passes the whole action requests that have been constructed in the processing so far. Also, Invokers will take care of managing and storing logs to facilitate debugging.

Once OpenWhisk completes the processing, it must store the result somewhere. This place is again CouchDB (where also configuration data are stored). Each result of the execution of an action is then associated with the ActivationId, the one that was sent back to the client. Thus the client will be able to retrieve the result of its request querying the database with the id.

Aysnchronous Client

As we already said, the processing described so far is asynchronous. This fact means the client will start a request and forget. Well, it will not leave it behind entirely, because it returns an activation id as a result of an invocation. As we have seen so far, the activation id is used to associate the result in the database after the processing.

So, to retrieve the final result, the client will have to perform a request again later, passing the activation id as a parameter. Once the action completes, the result, the logs, and other information are available in the database and can be retrieved.

Synchronous processing is available in addition to the asynchronous one. It primarily works in the same way as the asynchronous, except the client will block waiting for the action to complete and retrieve the result immediately.

Action Execution Constraints

In Figure Figure 1-5 are depicted the significant constraints an action is subject.

All the constraints have some value in term of time or space, either timeout, frequency, memory, size of disk space. Some are configurable; others are hardcoded. The standard values (that can be different according to the particular cloud or installation you are using) are:

• execution time: max 1 minute per action (configurable)

• memory used: max 256MB per action (configurable)

• log size: max 10MB per action (configurable)

• code size: max 48MB per action (fixed)

• parameters: max 1MB per action (fixed)

• result: max 1MB per action (fixed)

Furthermore, there are global constraints:

• concurrency: max 100 concurrent activations can be queued at the same time (configurable)

• frequency: max 120 activations per minute can be requested (configurable)

Let’s discuss more in detail those constraints.

Actions are Functional

As already mentioned, each action must be a function, invoked with a single input and must produce a single output.

The input is a string in JSON format. The action usually deserializes the string in a data structure, specific to the programming language used for the implementation.

The runtime generally performs the deserialization, so the developer will receive an already parsed data structure.

If you use dynamic languages like Javascript or Python, usually you receive something like a Javascript object or a Python dictionary, that can be efficiently processed using the feature of the programming language.

If you use a more statically typed language like Java or Go, you may need to put more effort in decoding the input. Libraries for performing the decoding task are generally readily available. However, some decoding work may be necessary to map the generally untyped arguments to the typed data structure of the language.

The same holds true for returning the output. It must be a single data structure, the programming language you are using can create, but it must be serialized back in JSON format before being returned. Runtimes also usually take care of serializing data structures back in a string.

Actions are Event Driven

Everything in the Serverless environment is activated by events. You cannot have any long running process. It is the system that will invoke actions, only when they are needed.

For example, an event is a user that when is browsing the web opens the URL of a serverless application. In such a case, the action is triggered to serve it.

However, this is only one possible event. Other events include for example a request, maybe originated by another action, that arrives on a message queue.

Also, database management is event-driven. You can perform a query on a database, then wait until an event is triggered when the data arrives.

Other websites can also originate events. For example, you may receive an event:

• when someone pushes a commit on GitHub

• when a user interacts with Slack and sends a message

• when a scheduled alarm is triggered

• when an action update a database

etc.

Actions do not have Local State

Actions are executed in Docker containers. As a consequence (by Docker design) file system is ephemeral. Once a container terminates, all the data stored on the file system will be removed too.

However, this does not mean you cannot store anything on files when using a function. You can use files for temporary data while executing an application.

Indeed a container can be used multiple times, so for example, if your application needs some data downloaded from the web, an action can download some stuff it makes available to other actions executed in the same container.

What you cannot assume is that the data will stay there forever. At some point in time, either the container will be destroyed or another container will be created to execute the action. In a new container, the data you downloaded in a precedent execution of the action will be no more available.

In short, you can use local storage only as a cache for speed up further actions, but you cannot rely on the fact data you store in a file will persist forever. For long-term persistence, you need to use other means. Typically a database or another form of cloud storage.

Actions are Time Bounded

It is essential to understand that action must execute in the shortest time possible. As we already mentioned, the execution environment imposes time limits on the execution time of an action. If the action does not terminate within the timeout, it will be aborted. This fact is also true for background actions or threads you may have started.

So you need to be well aware of this behavior and ensure your code will not keep going for an unlimited amount of time, for example when it gets larger input. Instead, you may sometimes need to split the processing into smaller chunks and ensure the execution time of your action will stay within limits.

Also usually the billing charge is time-dependent. If you run your application in a cloud provider supporting OpenWhisk, you are charged for the time your action takes. So faster actions will result in lower cost. When you have millions of actions executed, a few milliseconds speedier action can sum up in significant savings.

Actions are Not Ordered

Note also that actions are not ordered. You cannot rely on the fact action is invoked before another. If you have action A at time X and action B at time Y, with X < Y, action B can be executed before A.

As a consequence, if the action has a side effect, for example writing in the database, the side effect of action A may be applied later than the action B. Furthermore, there is not even any guarantee that an action will be executed entirely before or after another action. They may overlap in time.

So for example when you write in a database you must be aware that while you are writing in it, and before you have finished, another action may start writing in it too. So you have to provide your transaction support.

Classical JavaEE Architecture

The core idea behind JavaEE was allowing the development of large application out of small, manageable parts. It was a technology designed to help application development for large organizations, using the Java programming language. Hence the name of Java Enterprise Edition.

To facilitate the development of that vast and complex application, JavaEE provided a productive (and complicated) infrastructure of services.

To use them, JavaEE offered many different types of components, each one deployable separately, and many ways to let the various part to communicate with each other.

Those services were put together and made available through the use of Application Server. JavaEE itself was a specification.

The actual implementation was a set of competing products. The most prominent names in the world of application servers that are still in broad use today are Oracle Weblogic and IBM WebSphere.

Figure 1-6. JavaEE Architecture

If we look at the classical JavaEE architecture we can quickly identify the following tiers:

• The client (front end) tier

• The web (back-end) tier

• The EJB (business) tier

• The EIS (integration) tier

The following ideas characterize it:

• Application is split into discrete components, informally called beans.

• Components are executed in (Java-based) containers.

• Interface to the external world is provided by connectors.

In JavaEE, we have different types of components.

The client tier is expected to implement the application logic at the client level. Historically Java was used to implement applet, small java components that can be downloaded and run in the browser. Javascript, CSS, and HTML nowadays entirely replace those web components

In the web tier, the most crucial kind of components are the servlets. They are further specialized in JSP, tag libraries, etc. Those components define the web user interface at the server level.

The so-called business logic, managing data and connection to other “enterprise systems” is expected to be implemented in the Business Tier using the so-called EJB (Enterprise Java Beans). There were many flavors of EJB, like Entity Beans, Session Beans, Message Beans, etc.

Each component in JavaEE is a set of Java classes that must implement an API. The developer writes those classes and then deliver them to the Application Server, that loads the components and run them in their containers.

Furthermore, application servers also provide a set of connectors to interface the application with the external world, the EIS tier. There were connectors, written for Java, allowing to interface to virtually any resource of interest,

The more common in JavaEE are connectors to:

• databases

• message queues

• email and other communication systems

In the JavaEE world, Application Servers provided the implementation of all the JavaEE specification, and included APIs and connectors, to be a one-stop solution for all the development needs of enterprises.

Serveless equivalent of JavaEE

For many reasons, the architecture of Serverless application and OpenWhisk can be seen as an evolution of JavaEE. Everything starts from the same basic idea: split your application into many small, manageable parts, and provide a system to quickly put together all those pieces.

However, the technological landscape driving the development of Serverless environment is different than the one driving JavaEE development. In our brave new world, we have:

• applications are spread among multiple servers in the cloud, requiring virtually infinite scalability

• numerous programming languages, including scripting languages, are in extensive use and must be usable

• virtual machine and container technologies are available to wrap and control the execution of programs

• HTTP can be considered a standard transport protocol

• JSON is simple and widely used to be usable as a universal exchange format

Now, let’s compare JavaEE with the OpenWhisk architecture in Figure Figure 1-7. The Figure is intentionally similar to the Figure Figure 1-6, to highlight similarities and differences.

Figure 1-7. Serverless Architecture

Tiers

As you can see in the Figure, we can recognize web tier and a business tier also in OpenWhisk, in addition to a client and an integration tier.

While there is not a formal difference between the two tiers, in practice we have actions directly exposed to the web (web actions) and actions that are not.

Web Actions can be considered to be the web tier. Those actions which are meant to serve events, either coming from web actions or triggered by other services in the infrastructure, can be considered “Business Actions,” defining a “Business Tier.”

Components

In JavaEE, everything runs in the Java Virtual Machine, and everything must be coded in Java (or any language that can generate JVM-compatible byte-code).

In OpenWhisk, you can code applications in multiple programming languages. We use their runtimes as equivalents of the Java Virtual Machine. Furthermore, those runtimes are wrapped in Docker containers to provide isolation and control over resource usage.

Hence you can write your components in any (supported) language you like. You are no more confined to write your application solely for the JVM. However, a JVM runtime is available, so you can still use Java and its family of languages if you like.

You can now write your code for the JavaScript Virtual Machine, more commonly referred to as NodeJs .

If you choose to use the Python programming languages, you are also using its interpreter. Python has many available interpreters, one being the move widely used CPython, but there is also other available, like Pypy. The JVM can even execute Python.

Furthermore, you may choose not to use a virtual machine at all, but write your application in a language producing native executables like Swift or Go. In the Serverless world, it is becoming to become a popular choice. As long as you compile your application for Linux and AMD64, you can use it for OpenWhisk.

APIs

In JavaEE, you have APIs available to interact with the rest of the world, written in Java itself. Basically, the JavaEE model is , and every interesting resource for writing applications has been adapted to be used by Java.

In OpenWhisk, you have first and before all only one API, available for all the supported programming languages. This API is the OpenWhisk API itself, and it is a RESTful API. You can invoke it over HTTP using JSON as an interchange format.

This API can even be invoked directly just using an HTTP library, reading and writing JSON strings. However, are available wrappers for all the supported programming languages to use it efficiently. This API acts as glue for the various components in OpenWhisk.

All the communication between the different parts in OpenWhisk are performed in JSON over HTTP.

Connectors

In JavaEE, you have connectors for each external system you want to communicate with, primarily drivers. For example, if you’re going to interact with an Oracle database you need an Oracle JDBC driver, to communicate with IBM DB2 you need a specify DB2 JDBC driver, etc. The same holds true for messaging queues, email, etc.

In OpenWhisk, interaction with other systems is wrapped in packages, that are a collection of actions explicitly written to interact with a particular system. You can use any programming language and available APIs and drivers to communicate with it. So if you have for example a Java driver for a database, you can write a package to interact with it. Those packages act as Connectors.

In the IBM Cloud, there are packages available to communicate with essential services in the cloud. Most notably, we have

• the cloud database Cloudant

• the Kafka messaging system,

• the enterprise chat Slack

• many others, some specific to IBM services

You use the Feed mechanism provided by OpenWhisk to hook in those systems.

Application Server

Finally, in JavaEE, everything is managed by Application Servers. They are “the place” where Enterprise Applications are meant to be deployed.

In a sense, OpenWhisk itself replaces the Application Server concept, providing a cloud-based, multi-node, language agnostic execution service.

Using a serverless engine like OpenWhisk, the cloud becomes a transparent entity where you deploy your code. The environment manages the distribution of application in the Cloud.

For now, we have to say that OpenWhisk by itself runs in Docker containers. However, scaling Docker in a Cloud requires you to manage those Docker containers under some supervisor system called Orchestrators.

There are many Orchestrator available. At this stage, OpenWhisk supports:

• Kubernetes, a widely used orchestration system, initially developed by Google

• DC/OS, a “cloud” operating system, supporting the management of distributed application and Docker.

The Bash command line is a prerequisite for development

Serverless development is primarily performed at the terminal, using a command line interface (CLI). We are going to use mostly the Unix based CLI and the command line interpreter Bash. In a sense, this is a Unix-centered book. Bash is available out-of-the-box in any Linux based environment and on OSX. It can also be installed on Windows.

In the following examples, we are also going to use Bash widely for (numerous) command line examples. So you need to familiar working with Bash and the command line.

$ pwd                      
/Users/msciab
$ ls \                     
-l
# total 16                 
-rw-r--r--@ 1 msciab  staff  1079 24 Feb 09:53 form.js
-rw-r--r--@ 1 msciab  staff    71 23 Feb 17:18 submit.js

you should type now pwd at the command line

you should type at the terminal both the two lines

this is an example of the output you should expect

Address Validation

First, let’s check only if the name is provided.

// validate the name
if(args.name) {
 message.push("name: "+args.name)
} else {
 errors.push("No name provided")
}

Second, let’s validate the email address, checking if it “looks like” an email. We use here a regular expression:

// validate email
var re = /\S+@\S+\.\S+/;
if(args.email && re.test(args.email)) {
   message.push("email: "+args.email)
} else {
  errors.push("Email missing or incorrect.")
}

Third, let’s validate the phone number, checking it has “enough” digits (at least 10):

/// validate the phone
if(args.phone && args.phone.match(/\d/g).length >= 10) {
  message.push("phone: "+args.phone)
} else {
  errors.push("Phone number missing or incorrect.")
}

Finally, let’s add the message text if any:

/// add the message text, optional
if(args.message) {
  message.push("message:
"+args.message)
}

Returning the result

Once we have all the fields validated, we can return the result. There is now a bit of logic: we choose if returning an error message or an acceptance message.

// complete the processing
var data = "<pre>"+message.join("\n")+"</pre>"
var errs = "<ul><li>"+errors.join("</li><li>")+"</li></ul>"
if(errors.length) {
  return {
    body: "<h1>Errors!</h1>"+
      data + errs +
      '<br><a href="javascript:window.history.back()">Back</a>'
   }
} else {
   // storing in the database
   // TODO: <Store the message in the database> 
   return {
     body: "<h1>Thank you!</h1>"+ data
   }
}

Placeholder to insert code to save data in the database

The action is not complete (we have still to see how to store the data) but we can test this partial code with this command:

$ wsk action create contact/submit submit.js --web true
ok: created action contact/submit

If you now submit the form empty, you will see the message in Figure Figure 2-4 under “Form Rejected”. If we instead provide all the parameters correctly, we will be gratified with the acknowledgment under “Form Accepted”.

Figure 2-4. What the form submit displays

Invoking actions

So far we have seen how we can create actions and how to invoke them. Actually, in the first two examples, we have seen one specific kind of actions: web action (you may have noted the --web true flag in the commands). Those are the actions which can be invoked directly, navigating to web URLs or submitting web forms.

However, not all the actions are there to be invoked straight from the web. Many of them execute internal processing and are activated only through some specific APIs.

The actions letting to read and write in the database, those who we just exported from the Cloudant package, are not web actions. They can be invoked however using the command line interface.

In particular, we have to use the wsk action invoke command, passing parameters with the --param options and data in JSON format as a command line argument.

Let verify how it works, writing in the database, by invoking the action directly write, as follows.

$ wsk action invoke contactdb/write \
  --blocking --result --param dbname contactdb \
  --param doc '{"name":"Michele Sciabarra", "email": "michele@sciabarra.com"}'
{
    "id": "fad432c6ea1145e71e99053c0d811475",
    "ok": true,
    "rev": "1-d14ba6a37cfdf34a8b3bb49dd3c0e22a"
}

The database replied with a confirmation and some extra information. Most notably, the result includes the id of a new record, that we can use later for retrieving the value.

We can now check the database user interface to see the data we just stored in it. You can select the database, then the id and you can see the data we just inserted in the database in JSON format.

As you can see, to write data in the database you need just a JSON object. So far we wrote data using the command line. Let’s look at how we can do it in code.

Figure 2-7. How to retrieve data from cloudant

Storing in the database

OpenWhisk includes an API to interact with the rest of the system. Among the possibilities, there is the ability to invoke actions.

We provisioned the database as a package binding. Thus we have now an action available to write in the database. To use it we need to invoke the action from another action. Let see how.

First and before all, we need a:

var openwhisk = require('openwhisk')

to access to the openwhisk API. This code is the entry point to interact with OpenWhisk from within an action.

Now, we can define the function save using the OpenWhisk API to invoke the action to write in the database. The following code should be placed at the beginning of the submit.js:

var openwhisk = require('openwhisk')

function save(doc)  {
  var ow = openwhisk()
  return ow.actions.invoke({
    "name": "/_/contactdb/write",
    "params": {
       "dbname": "contactdb",
       "doc": doc
    }
  })
}

Once the save function is available, you can use it to save data just by creating an appropriate JSON object and pass it as a parameter. Place the following code after <Store the message in the database>:

save({
 "name": args.name,
  "email": args.email,
  "phone": args.phone,
  "message": args.message
})

The code is now complete. We can deploy it, as a web action too, to be executed when the user posts the form:

$ wsk action update contact/submit submit.js --web true
ok: updated action contact/submit

We can now manually test the action from the command line, to check if it writes in the database:

$ wsk action invoke contact/submit -p name Michele -p email \
    michele@sciabarra.com -p phone 1234567890 -r
{
    "body": "<h1>Thank you!</h1><pre>name: Michele
email: michele@sciabarra.com
phone: 1234567890</pre>"
}

Now we can go on and try our form, verifying data are written in the database, as in figure Figure 2-8.

Figure 2-8. Submitting the form and storing the data

Configuring Mailgun

To use Mailgun you need to go to the website www.mailgun.com and register for a free account. Once you have set up an account you will get a “sandboxed” account (note the site will ask for a phone number for verification purposes).

Once registered, to retrieve credentials for sending an email (Figure Figure 2-9) you need to:

1. Login in Mailgun

2. Scroll down until you find the Sandbox Domain

3. Click on “Authorized Recipient”

4. Invite the recipient

5. Click on the link in the email received

Once done, you need the following information, as shown in the figure, for writing your script:

• the sandboxed domain

• the private API key

• the authorized recipient address

Figure 2-9. How to register in Mailgun

Writing an action for sending email

Now, we can build an action for sending an email. Actually, the purpose of this example is to show how you can create more complex action involving third-party services and libraries.

Hence now preparing this action is a bit more complicated than the actions we have seen before, because we need to use and install an external library then and deploy it together with the action code.

Let start by creating a folder and importing the library mailgun-js with the npm tool. We assume you have installed it, refer to Appendix II for details about the purpose and usage of this tool.

$ mkdir sendmail
$ cd sendmail
$ npm init -y
$ npm install --save mailgun-js

Now we can write a simple action that can send an email and place it in sendmail/index.js. Check the listing with the notes about the information you have to replace with those who collected before when registering to Mailgun.

var mailgun = require("mailgun.js")
var mg = mailgun.client({username: 'api',
        key: 'key-<YOUR-PRIVATE-API-KEY>'})      
function main(args) {
  return mg.messages.create(
          '<YOUR-SANDBOX-DOMAIN>.mailgun.org', { 
    from: "<YOUR-RECIPIENT-EMAIL>", 
    to: ["<YOUR-RECIPIENT-EMAIL>"], 
    subject: "[Contact Form]",
    html: args.body
  }).then(function(msg) {
     console.log(msg);
     return args;
  }).catch(function(err) {
     console.log(err);
     return args;
  })
}

replace key-<YOUR-PRIVATE-API-KEY> with the Private API Key

replace <YOUR-SANDBOX-DOMAIN>.mailgun.org with the Sandbox Domain

replace <YOUR-RECIPIENT-EMAIL> with the one that is used both as the sender and the recipient

same as 3

We can deploy now the action. Since this time the action is not a single file, but it includes libraries, we have to package everything in a zip file, to deploy them too.

$ zip ../sendmail.zip -r *
$ wsk action update contact/sendmail ../mailgun.zip --kind nodejs:6
ok: updated action contact/sendmail

We can now test the action invoking it directly:

$ wsk action invoke contact/sendmail -p body "<h1>Hello</h1>" -r
{
    "body": "<h1>Hello</h1>"
}

The action acts as a filter, accepting the input and copying it in the output. We will leverage this behavior to chain the action to the submit.

When invoked, it will return an output, but also it will send an email as a side effect.

Figure 2-10. The email send by your action in your Inbox

Creating an action sequence

So far we have developed an action that can send an email as a stand-alone action.

However, we designed the action in such a way that it can take the output of the submit action and return it as is. So we can create a pipeline of actions, similar to the Unix shell processing, where the output of a command is used as an input for another command.

We are going to take the output of the sendmail action, use it as the input for the submit action and then return it as the final result of the email submission.

Please note as a side effect; it will send emails for every submission, also for incorrect inputs, so we can know someone is trying to use the form without providing full information.

However, we will store in the database only the fully validated data. Let’s create such a pipeline that is called sequence in OpenWhisk, and then test it.

$ wsk action create contact/submit-sendmail \
  --sequence contact/submit,contact/sendmail \
  --web true
ok: updated action contact/submit-sendmail

$ wsk action invoke contact/submit-sendmail -p name Michele -r
{
    "body": "<h1>Errors!</h1><pre>name: Michele</pre><ul><li>Email missing or incorrect.</li><li>Phone number missing or incorrect.</li></ul><br><a href=\"javascript:window.history.back()\">Back</a>"
}

As a result, we should be receiving an email for each attempt of submitting a form, including partial data from the contact form.

Now we are ready. We can use the complete form including storing in the database and sending the email. But now the form should activate our sequence, not just the submission action. The simplest way is to edit the form.js, replacing the action we are invoking in the form. We should do the following change in form.js:

-<form method="POST" action="submit">
+<form method="POST" action="submit-sendmail">

If we now update the action and try it, we will receive an email for each form submission, but the form will be stored in the database only when the data is complete.

Configure the wsk command

The wsk command has many “properties” you can configure to access to an OpenWhisk environment. When you use the IBM Cloud, those properties are actually set for you by the ibmcloud main command. If you have a different OpenWhisk deployment, you may need to change the properties manually to access it.

You can see the currently configured properties with:

$ wsk property get
Client key
whisk auth            xxxxx:YYYYY                  
whisk API host        openwhisk.eu-gb.bluemix.net  
whisk API version    v1
whisk namespace        _                            
whisk CLI version    2017-11-15T19:55:32+00:00
whisk API build        2018-02-28T23:44:25Z
whisk API build number    whisk-build-7922

the API authentication key (replaced in the example with xxxxx:YYYYY) - your own will be different

the OpenWhisk host you connect to control OpenWhisk with the CLI - depends on your location

your current namespace (the value _ is a shorthand for you default namespace)

If you install a local OpenWhisk environment, you need to set those properties using wsk property set manually. In particular, you need to set the whisk auth and the whisk host properties with values provided by your local installation.

OpenWhisk Entity Names

Let’s see how we name things. As you may already know, in OpenWhisk we have the following entities with a name:

• packages

• actions

• sequences

• triggers

• rules

• feeds

There are precise naming conventions for them. Furthermore, those conventions are reflected in the structure of the URL used to invoke the various elements of OpenWhisk.

First and before all, each user is placed in a namespace, and everything a user creates, belong to it. It acts as a workspace and also provides a base URL for what a user creates. Credentials for a user allows access to all the resources in its namespace.

For example, when I registered in the IBM Cloud, my namespace was /openwhisk@sciabarra.com_dev/. It is my username followed by _dev (for development).

You can create a namespace in an OpenWhisk installation if you are authorized, otherwise, a namespace is created for you by the system administrator.

Under a namespace you can create triggers, rules, actions and packages, so they will have names like:

• /openwhisk@sciabarra.com_dev/a-triggger

• /openwhisk@sciabarra.com_dev/a-rule

• /openwhisk@sciabarra.com_dev/a-package

• /openwhisk@sciabarra.com_dev/an-action

When you create a package, you can put in its actions and feeds. So for example below the package a-package you can have:

• /openwhisk@sciabarra.com_dev/a-package/another-action

• /openwhisk@sciabarra.com_dev/a-package/a-feed

To recap:

• The general format for entities is: /namespace/package/entity, but it can be reduced to /namespacke/entity

• Under a namespace you can create triggers, rules, package, and actions but not feeds.

• Under a package you can create actions and feeds, but not triggers, rules, and other packages.

Chain Sequences of Actions

An essential feature of OpenWhisk is the ability to chain action in sequences, creating actions that use, as an input, the output of another action, as shown in Figure Figure 3-1.

Figure 3-1. Actions chained in a sequence

Let’s do a practical example of a similar action sequence. We implement a word count application, separating it in two actions, put in a sequence. The first action splits the input, that is supposed to be a text file, in “words”, while the second retrieves the words and produce a map as a result. In the map, each word is then shown with its frequency.

Let’s start with the first action, split.js, as follows:

function main(args) {
    let words = args.text.split(' ')
    return {
        "words": words
    }
}

You can deploy and test it, feeding a simple string:

$ wsk action update basics/split basics/split.js
ok: updated action basics/split
$ wsk action invoke basics/split \
  -p text "the pen is on the table" -r \
  | tee save.json 
{
    "words": [
        "the",
        "pen",
        "is",
        "on",
        "the",
        "table"
    ]
}

note here we are saving the output in a file save.json

Now it is time to do the second step, with this count.js actions:

function main(args) {
    let words = args.words
    let map = {}
    let n = 0
    for(word of words) {
       n = map[word]
       map[word] = n ? n+1 : 1
    }
    return map
}

We can now deploy it and check the result, feeding the output of the first action as input:

$ wsk action update basics/count count.js
ok: updated action basics/count
$ wsk action invoke basics/count -P save.json -r
{
    "is": 1,
    "on": 1,
    "pen": 1,
    "table": 1,
    "the": 2
}

Now we have two actions, the second able to take the output of the first as input, we can create a sequence:

wsk action update basics/wordcount \
  --sequence basics/split,basics/count 

note here we are specifying a comma-separated list of existing action names

The sequence can be now invoked as a single action, so we can feed the text input and see the result:

$ wsk action invoke basics/wordcount -r -p text  \
"can you can a can as a canner can can a can"
{
    "a": 3,
    "as": 1,
    "can": 6,
    "canner": 1,
    "you": 1
}

Actions including Libraries

In the simplest case, your action is just a single javascript file. However, as we are going to see, very often commonly you have some code you want to share and reuse between actions.

The best way to handle this situation is to have a library of code that you can include for every action and that you deploy with your actions.

Let’s consider this example: a couple of utility functions that format a date in a standard format “YYYY/MM/DD” and time in the standard format “HH:MM:SS”.

function fmtDate(d) {
    let month = '' + (d.getMonth() + 1),
        day = '' + d.getDate(),
        year = d.getFullYear();
    if (month.length < 2) month = '0' + month;
    if (day.length < 2) day = '0' + day;
    return year + "/" + month + "/" + day
}

function fmtTime(d) {
    let hour =  ''+ d.getHours(),
        minute = '' + d.getMinutes()
        second = '' + d.getSeconds()

    if(hour.length < 2) hour = "0"+hour
    if(minute.length < 2) minute = "0"+minute
    if(second.length <2 ) second = "0"+second

    return hour + ":" + minute + ":" + second
}

You may, of course, copy this code in each action file, although it is pretty awkward to maintain. Just consider that when you change the function, you have to change it in all the copies of the functions across multiple files. Of course, there is a better way.

Since actions are executed using NodeJs, you have the standard export/require mechanism available for writing your actions.

As a convention, we are going to place our shared code in a subdirectory named lib, and we treat them as modules.

So you should place the format date-time listing above in a file lib/datetime.js and add at the end the following code:

module.exports = {
    fmtTime: fmtTime,
    fmtDate: fmtDate
}

Now you can use the two functions in one action. For example let consider an action named clock that returns the date if invoked with date=true, the time if invoked with time=true, or both if the date and time parameters are specified.

Our action will starts requiring the library with:

var dt = require("./lib/datetime.js")

This way you can access the two functions as dt.fmtDate and dt.fmtTime. Using those functions, we can easily write the main body, called clock.js:

function main(args) {
  let now = args.millis ? new Date(args.millis) : new Date()
  let res = " "
  if(args.date)
    res = dt.fmtDate(now) + res
  if(args.time)
    res = res + dt.fmtTime(now)
  return {
    body: res
  }
}
exports.main = main

Now, we have to deploy the action, but we also need to include the library. How can we do this in OpenWhisk?

The solution is to deploy not a single file but a zip file that includes all the files we want to run as a single action.

When deploying multiple files, you need either to put your code in a file index.js or to provide a package.json saying which one is the main file.

Let’s perform this procedure with the following commands:

$ cd basics
$ echo '{"main":"clock.js"}' >package.json
$ zip -r clock.zip clock.js package.json lib    
  adding: clock.js (deflated 40%)
  adding: package.json (stored 0%)
  adding: lib/ (stored 0%)
  adding: lib/datetime.js (deflated 57%)
$ wsk action update basics/clock clock.zip \
  --kind nodejs:6                               
ok: updated action basics/clock

creating a zip file with subdirectories, so the -r switch is required

specifying the runtime we want to use is nodejs:6

Let’s test it:

$ wsk action invoke basics/clock -p date true -r
{
    "body": "2018/03/18 "
}
$ wsk action invoke basics/clock -p time true -r
{
    "body": " 15:40:42"
}

Associate Triggers to Actions with Rules

Once we have a trigger and some actions we can create rules for the trigger. A rule connects the trigger with an action, so if you fire the trigger, it will invoke the action. Let’s see in practice in the next listing.

$ wsk rule create basics-alert-alpha \
       basics-alert basics/log-alpha                      
ok: created rule basics-alert-alpha
$ wsk trigger fire basics-alert                           
ok: triggered /_/alert with id 86b8d33f64b845f8b8d33f64b8f5f887
$ wsk activation logs 86b8d33f64b845f8b8d33f64b8f5f887 \  
   | jq                                                   
{
  "statusCode": 0,
  "success": true,
  "activationId": "b57a1f1dc3414b06ba1f1dc341ab0626",     
  "rule": "openwhisk@sciabarra.com_dev/alert-alpha",
  "action": "openwhisk@sciabarra.com_dev/basics/alpha"
}

$ wsk activation logs b57a1f1dc3414b06ba1f1dc341ab0626    
2018-03-17T18:10:48.471777977Z stdout: alpha

creating a rule to activate the action alpha

we can now fire the rule, it returns an activation id

let’s inspect the activation id

we piped the output in the jq utility to make the output more readable

in turn the rule enabled an action with this activation id

let’s see what the rule did

A trigger can enable multiple rules, so firing one trigger actually activates multiple actions.

Let’s try this feature in the next listing. However, before starting, let’s open another terminal window and enable polling (with the command wsk activation poll) to see what happens.

$ wsk rule create basics-alert-beta basics-alert basics/log-beta
ok: created rule basics-alert-beta
$ wsk trigger fire basics-alert
ok: triggered /_/basics-alert with id a731a03603bb4183b1a03603bb8183ce

If we check the logs we should see something like this:

$ wsk activation poll
Enter Ctrl-c to exit.
Polling for activation logs

Activation: 'alert' (a731a03603bb4183b1a03603bb8183ce)    
[
    "{\"statusCode\":0,\"success\":true,\"activationId\":\"3024596c57ac4c10a4596c57ac7c1042\",\"rule\":\"openwhisk@sciabarra.com_dev/basics-alert-alpha\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-alpha\"}",
    "{\"statusCode\":0,\"success\":true,\"activationId\":\"6d88836c860d405f88836c860d305f83\",\"rule\":\"openwhisk@sciabarra.com_dev/basics-alert-beta\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-beta\"}"
]

Activation: 'log-alpha' (3024596c57ac4c10a4596c57ac7c1042) 
[
    "2018-03-17T18:34:58.633797676Z stdout: alpha"
]

Activation: 'log-beta' (6d88836c860d405f88836c860d305f83)  
[
    "2018-03-17T18:34:58.629413468Z stdout: beta"
]

The trigger activation invoked 2 actions

This is the log of the first action

This is the log of the second action

Rules can also be enabled and disabled without removing them. As the last example, we try to disable the first rule and fire the trigger again to see what happens. As before, first, we start the log polling to see what happened.

$ wsk rule disable basics-alert-alpha     
ok: disabled rule basics-alert-alpha
$ wsk rule enable basics-alert-beta       
ok: enabled rule basics-alert-beta
$ wsk rule list                           
rules
/openwhisk@sciabarra.com_dev/basics-alert-beta                                private              active
/openwhisk@sciabarra.com_dev/basics-alert-alpha                               private              inactive
$ wsk trigger fire basics-alert           
ok: triggered /_/basics-alert with id 0f4fa69d910f4c738fa69d910f9c73af

disabling rule alert-alpha

enabling rule alert-beta (just to be sure)

a quick listing confirms only one active rule

firing the trigger again

Moreover, if we go and check the result, we see this time only the action log-beta was invoked.

$ wsk activation poll
Enter Ctrl-c to exit.
Polling for activation logs

Activation: 'basics-alert' (0f4fa69d910f4c738fa69d910f9c73af)
[
    "{\"statusCode\":0,\"success\":true,\"activationId\":\"a8221c7d7fe94e22a21c7d7fe9ce223c\",\"rule\":\"openwhisk@sciabarra.com_dev/alert-beta\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-beta\"}",
    "{\"statusCode\":1,\"success\":false,\"rule\":\"openwhisk@sciabarra.com_dev/basics-alert-alpha\",\"error\":\"Rule 'openwhisk@sciabarra.com_dev/basics-alert-alpha' is inactive, action 'openwhisk@sciabarra.com_dev/basics/log-alpha' was not activated.\",\"action\":\"openwhisk@sciabarra.com_dev/basics/log-alpha\"}"
]

Activation: 'log-beta' (a8221c7d7fe94e22a21c7d7fe9ce223c)
[
    "2018-03-18T07:27:14.01530577Z  stdout: beta"
]

Asynchronous invocation

A promise is a way to wrap an asynchronous computation in an object that can be returned as a result for a function invocation.

To understand why we need to do that, let’s consider as an example a simple script that generates a new UUID using the website httpbin.org. We are using here the https NodeJS standard API.

The following code opens a connection to the website, and then define a couple of callbacks to handle the data and error events. In Javascript, providing callbacks is the standard way of handling events that do not happen immediately, but later in the future, the so-called “asynchronous” computations.

var http = require("https")

function uuid(callback) {
   http.get("https://httpbin.org/uuid",
   function(res) {
     res.on('data', (data) =>
        callback(undefined, JSON.parse(data).uuid))
   }).on("error", function(err) {
     callback(err)
   })
}

You can note that this function does not return anything. The user of the function, to retrieve the result and do something with it (for example, print it on the console) have to pass a function, like this:

uuid(function(err, data) {
   if(err) console.log("ERROR:" +err)
   else console.log(data)
})

We can use this code locally with NodeJS, but we cannot deploy it as an action, for the simple reason it does not return anything, while the main action must always expect you return “something”.

In OpenWhisk, the “something” expected for asynchronous computation is a “Promise” object. However, what is a Promise? How you build it? Let’s see the details in the next paragraph.

Introducing Promises

We have just seen an example of an asynchronous computation. This code in the latest listing does not return anything, because the computation is asynchronous. Instead of waiting for the result, we provide a function as a parameter. It will perform our work later, only when the computation finally completes.

In OpenWhisk instead, we cannot do this. We need a way to return the asynchronous computation as a result. So the computation must be wrapped in some object we can return as an answer to the action. The solution for this requirement is called Promise, and the OpenWhisk API is heavily based on it.

A Promise is an object that is returned by a function requiring asynchronous computations. It provides the methods to retrieve the result of this computation when it completes.

Using promises (we are going to see how to create one in the next paragraph) we can keep the advantage of being asynchronous while encapsulating this fact in an object that can be passed around and returned as the result of a function invocation.

It is essential to understand that even with a Promise, the computation is still asynchronous, so the result can be retrieved only when ready because we do not know in advance when the result is going to be available. Furthermore, an asynchronous computation can also fail with an error.

Promises combine a nice way to retrieve result and error management. With the promise-based genuuid that we will see next, extracting the value and managing the erros will be peformed with the following code:

var p = uuid()
p.then(data => console.log(data))
 .catch(err => console.log("ERROR:"+err))

Creating a Promise

Let’s translate the genuuid example to make it Promise based.

Instead of requiring a callback we wrap out asynchronous code in a function block like this:

return new Promise(function(resolve, reject) { 
    // ok
    resolve(success)                           
    // K.O.
    reject(error)                              
})

wrapper function to create an isolated environment

what to do when you got the result successfully

what to do when you catch an error

It can look a bit twisted, but it makes sense. A function wraps asynchronous code for 3 reasons:

• create an isolated scope

• be invoked only when the Promise resolution is required

• use the arguments to pass to the code block two functions for returning the result and catching errors

So the real work of wrapping the asynchronous behavior is performed by the function. We could at this point return the function, but we still need some work:

• starting the invocation when needed (then)

• catching errors (catch)

• provide our implementation of the resolve

• provide our implementation of the reject.

Hence, we further wrap the function in a Promise object and return it as a result. Finally, we have created the standard Promise we described before.

Using a Promise we can now implement our genuuid function. Translating the callback is straightforward:

var http = require("https")

function uuid() {
  return new Promise(function(resolve, reject){ 
    http.get("https://httpbin.org/uuid",
     function(res) {
      res.on('data', (data) =>
         resolve(JSON.parse(data).uuid))        
     }).on("error", function(err) {
         reject(err)                            
    })
  })
}

wrap the asynchronous code in a Promise

success, we can return the result with resolve

failure, returning the error with reject

As you can see the code is similar to the standard way using a callback, except we wrap everything in a function that provides the resolve and reject actions. The function is then used to build a Promise. Most of the implementation of the Promise is standard; only the function must be defined to implement the specific behavior.

Now, using the Promise, we are now able to create an action for OpenWhisk, providing the following main:

function main() {
    return uuid()
      .then( data =>  ({"uuid": data}))
      .catch(err =>   ({"error": err}))
}

Let’s try the code:

$ wsk action update apidemo/promise-genuuid \
      apidemo/promise-genuuid.js
ok: updated action apidemo/promise-genuuid
$ wsk action invoke apidemo/promise-genuuid -r
{
    "uuid": "52a188a9-ff9b-4f3a-b72d-301c26aac2cf"
}

Overview of the API

The OpenWhisk API provides the same functions available on the command line interface.

Some features are more useful than others for actually writing action code. The most important is, of course:

• ow.actions

• ow.triggers

• ow.activations

We are going to cover those API in details.

There are available many other features that are useful for deploying code. We will not discuss those features here since are needed when you develop your deployment tools. Those other available features are:

• ow.rules

• ow.packages

• ow.feeds

Invoking multiple promises

We learned how to create Promises, and we have seen how to use them for chaining asynchronous operations.

Another important use case to consider, however, is when you have multiple promises. In such a case you may want to wait for all of them to complete.

We could wait for multiple actions with some complex code involving then. Since this use case is frequent enough, it is worth the availability of a standard method: Promise.all(promises).

Within this method call, the promises are an array of Promises (actually, anything satisfying the “iterable” Javascript protocol). As a result, it returns a Promise that completes when all the other promises complete.

You can then retrieve the combined result of all the Promises with a then function, receiving, as a result, an array of the results of the many Promises.

We can now construct an example to demonstrate this feature. We are going to create a Web action consisting in multiple promises (actually multiple invocations). Then we wait for all of them to complete, and finally, we construct a web page concatenating the results. You may notice in the example the use of map, that is probably idiomatic in those cases.

var openwhisk = require("openwhisk")

function main(args) {
    let ow = openwhisk()
    let count = args.n ? args.n : 3;                       
    let inv = { name: "apidemo/promise-genuuid",
                blocking: true,
                result: true
    }
    let promises = []
    for(let i=0; i< count; i++)                            
        promises.push(ow.actions.invoke(inv));
    return Promise.all(promises)                           
      .then(res => ({
            body: "<h1>UUIDs</h1><ul><li>"+
                   res.map(x=>x.uuid).join("</li><li>")+   
                   "</li></ul>"
        }))
}

we are reading a parameter from the URL, if not specified it defaults to 3

we are looping, constructing an array of invocations, each one asking for a different uuid

this is the key call: we are waiting for all the promises to complete

the final result is built here, in the form of an array of results, each one being a different UUID. We join them to create a dotted list in HTML.

Now, we can test the invocation and check the results.

$ wsk action update apidemo/invoke-genuuid-list \        
  apidemo/invoke/invoke-genuuid-list.js  --web true
ok: updated action apidemo/invoke-genuuid-list
$ curl $(wsk action get apidemo/invoke-genuuid-list  \   
         --url | tail -1)
<h1>UUIDs</h1>                                           
<ul>
  <li>3b72aec9-eb1d-45e9-9c98-d689a6bddf2b</li>
  <li>3189605c-d003-469b-afcc-202ef690a544</li>
  <li>3e78ee6d-f141-483b-8d1a-7e8aaaae309d</li>
</ul>

Deployment of the action wrapping multiple promises as a web action

Invocation of the new action using curl and extracting the url

The result is now the combination of multiple invocation of the promise-genuuid action

Using Jest

As we already pointed out, there are a lot of test tools available for Javascript and NodeJS. So many that is difficult to make a choice. But since we need to pick one to write our tests, we selected one that we believe it is a right balance between ease of use and completeness.

We ultimately picked Jest, the test tool developed by Facebook as a complement to testing React applications. We are not going to use React in this book, but Jest is independent of React, and it is a good fit for our purposes.

Some Jest features I cannot live without are:

• it is straightforward to install

• it is pretty fast

• it supports snapshot testing

• it provides extensive support for “mocking.”

Of course, this does not mean other tools does not have similar features. But we have to settle on someone.

So, assuming you agree with this choice, let’s start installing it. It is not difficult:

$ npm install -g jest                  
+ jest@22.4.3
updated 1 package in 13.631s
$ jest --version                       
v22.4.3

install Jest as a global command

check if jest is now available as a command

Since now we have Jest, we can write a test. Our first test will check a modified version of the word count action (count.js) we used in chapter 2.

The action we are going to test receives its input as a property text of an object args, split the text in words by itself, then it counts words, returning a table with all the words and a count of the occurrences.

Here is the updated version wordcount.js:

function main(args) {
    let words = args.text.split(" ")
    let map = {}
    let n = 0
    for(word of words) {
       n = map[word]
       map[word] = n ? n+1 : 1
    }
    return map
}
module.exports.main = main             

add an export of the function

In OpenWhisk, you can deploy a simple function. It works as long as it as a main function. When you want to use it locally in a test, however, it must be a proper module so a test can import it. So here is an important suggestion:

We can now write a test for wordcount that we can run with Jest. A test is composed of 3 important parts:

• import of the module we want to test with require

• declare a test with the function test(<description>, <test-body>) where <description> is a string and <test-body> is a function performing the test

• in the body of the test you perform some assertions in the form expect(<expression>).toBe(<value>) or similar (there are many different toXXX methods; we will see next)

We have to write now a wordcount.test.js with the following code:

const wordcount =
      require("./wordcount").main                
test('wordcount simple', () => {                 
    res = wordcount({text: "a b a"})             
    expect(res["a"]).toBe(2)                     
    expect(res["b"]).toBe(1)                     
})

import the module wordcount.js under test

declare a test

invoke the function

ensure it found two ``a``s

ensure it found one ``b``s

We are ready to run the tests, but before we go on, we need to create a file package.json, as simple as this:

{ "name": "jest-samples" }

Now you can run the test. You can do it directly using the jest command line from the directory containing all our files:

$ ls
package.json
wordcount.js
wordcount.test.js
$ jest
 PASS  ./wordcount.test.js
  ✓ wordcount simple (3ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.341s
Ran all test suites matching /wordcount/i.

Jest started to search for tests, found our wordcount.test.js, loaded it and executed all the test in it, then showed the results.

{
  "name": "jest-samples",
  "scripts": {
    "test": "jest"
  }
}

Configuring an Environment to Locally run OpenWhisk actions

So far we have seen how to run tests in general. Now we focus on actually being able to execute tests locally to unit test them.

In general, actions in OpenWhisk runs under NodeJS, so the same code you can execute in your computer with NodeJS should also work in OpenWhisk, as long as the environment is the same.

You need however to match the environment, so you may need to install locally the same libraries and the same version of NodeJS in use in OpenWhisk.

To match the environment, when you run your tests you need to: * run your tests with the same version of Node * have the same Node Packages installed locally * load code in the same way as OpenWhisk load it * provide the same environment variables that are available in OpenWhisk

Let’s discuss those needs in order.

$ nvm install v6.14.1                            
Downloading https://nodejs.org/dist/\
  v6.14.1/node-v6.14.1-darwin-x64.tar.xz...
######### 100,0%
Now using node v6.14.1 (npm v3.10.10)
$ node -v
v6.14.1
$ npm init --yes                                 
Wrote to  chapter4/package.json
$ npm install --save cheerio@0.22.0              
chapter4@1.0.0 chapter4
└─┬ cheerio@0.22.0

const Validator = require("./lib/validator.js")
function checkEmail(input) {                           
  var re = /\S+@\S+\.\S+/;
  return re.test(input)
}
var errmsg = " does not look like an email"
class EmailValidator extends Validator {
    validator(value) {
        let error = super.validator(value);
        if (error) return error;
        if(checkEmail(value))                          
            return "";
        return value+errmsg
    }
}
function main(args) {
    if(args.errmsg) {                                  
        errmsg = args.errmsg
        delete args.errmsg
    }
    return new EmailValidator("email").validate(args)
}
module.exports = {
  main: main,                                          
  checkEmail: checkEmail                               
}

const main = require("./email").main
const checkEmail = require("./email").checkEmail

test("checkEmail", () => {
 expect(
  checkEmail("michele@sciabara.com"))
    .toBe(true)
 expect(
  checkEmail("http://michele.sciabarra.com"))
    .toBe(false)
})

test("validate email", () => {
 expect(main({email: "michele@sciabarra.com"})
   .message[0])
   .toBe('email: michele@sciabarra.com')
 expect(main({email:"michele.sciabarra.com"})
   .errors[0])
   .toBe('michele.sciabarra.com does not look like an email')
})

Setting OpenWhisk Enviroment Variables

In OpenWhisk you use the OpenWhisk API to interact with other actions. We already discussed in Chapter 3 how you invoke actions, fire triggers, read activations and so on.

When you want to invoke other actions running in the same namespace as the main action, you need to use require("openwhisk") and then you can access the API. At least, this is what happens your application is running inside OpenWhisk.

When your code is running outside OpenWhisk, as it happens when you are running unit tests it, the OpenWhisk API cannot talk with other actions because every request needs authentication. Hence, if you try to run your code outside of OpenWhisk, you will get an error.

We can demonstrate this fact considering a simple action dbread.js, able to read a single record we put in the database with the Contact Form:

const openwhisk = require("openwhisk")
function main(args) {
  let ow = openwhisk()
  return ow.actions.invoke({
    name: "patterndb/read",
    result: true,
    blocking: true,
    params: {
      docid: "michele@sciabarra.com"
    }
  })
}
module.exports.main = main

If we deploy and run the action in OpenWhisk there are no problems:

$ wsk action update dbread dbread.js
ok: updated action dbread
$ wsk action invoke dbread -r
{
    "_id": "michele@sciabarra.com",
    "_rev": "5-011e075095301fcfc350cac66fd17c7e",
    "type": "contact",
    "value": {
        "name": "Michele",
        "phone": "1234567890"
    }
}

However, let’s try to write and run a test dbread.test.js for this simple action:

const main = require("./dbread").main
test("read record", () => {
   main().then(r => expect(r.value.name).toBe("Michele"))
})

If we run the test, the story is a bit different:

$ jest dbread
 FAIL  ./dbread.test.js
  ✕ read record (8ms)

  ● read record

    Invalid constructor options. Missing api_key parameter.

      1 | const openwhisk = require("openwhisk")
      2 | function main(args) {
    > 3 |   let ow = openwhisk()
      4 |   return ow.actions.invoke({
      5 |     name: "patterndb/read",
      6 |     result: true,

      at Client.parse_options (node_modules/openwhisk/lib/client.js:80:13)
      at new Client (node_modules/openwhisk/lib/client.js:60:25)
      at OpenWhisk (node_modules/openwhisk/lib/main.js:15:18)
      at main (dbread.js:3:12)
      at Object.<anonymous>.test (dbread.test.js:5:4)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        1.021s
Ran all test suites matching /dbread/i.

As we discussed in Chapter 3 when we introduced the API, the OpenWhisk library needs to know the host to contact to perform requests (the API host) and must provide an authentication key to be able to interact with it.

When your application is running in the cloud in OpenWhisk, those keys are available through two environment variables \\__OW_API_HOST and \\__OW_API_KEY. It is the OpenWhisk environment that sets them before executing the code.

When your code is running locally, those variables are not available, unless your test code takes care of setting them. Luckily, it is it pretty easy to provide them locally. Indeed, if you are using the tool wsk and you have configured properly, it stores credentials in a file named .wskprops in the home directory.

Because the format of this is compatible with the syntax of the shell, if you are using bash (as we always assumed you are doing in this book) you can load those environment variables with the following commands:

$ source ~/.wskprops
$ export __OW_API_HOST=$APIHOST
$ export __OW_API_KEY=$APIKEY

Now, with those environment variables set, you can try again to run the test, and this time you will be successful:

$ jest dbread
 PASS  ./dbread.test.js
  ✓ read record (22ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.951s, estimated 1s
Ran all test suites matching /dbread/i.

Your local code is using credentials and can contact and interact with the real server to run the test.

 "scripts": {
    "test": "source $HOME/.wskprops;               
 __OW_API_HOST=$APIHOST
 __OW_API_KEY=$AUTH jest"
  },

this is actually one long line split in three lines for typesetting purposes

Snapshot Testing

A common problem, in the test phase, is the burden of having to check results. You may end up to writing a lot of code that the result against the expected values. Luckily, there are techniques (that we are going to see) to reduce the amount of repetitive and pointless code you have to write.

When you test, you decide on a set of data corresponding to the various scenarios you want to verify. Then you write your test, invoking your code against the test data, and check the results. While defining the test data is generally an exciting experience, because you have to think about your code and what it does, verifying that the results are the expected one is typically not an exciting activity.

Jest provides a large number of “matchers” to make easy result verification. Matchers work well when results are small. But sometimes test results are pretty large; hence the code to check the result can be not only dull but also substantial.

There is an alternative to automate this activity, to focus more on checking the results and less on writing repetitive and naive code: snapshot testing.

The idea of snapshot testings is pretty simple: when you run a test the first time, you save the test results in a file. This file is called a “snapshot.” You can then check the result is correct. You do not have to write code, only verify the expected result checking the snapshot.

If the result is correct, you can commit the snapshot into the version control system. When you rerun a test, if there is already a snapshot in place, the test tool will automatically compare the new result of the test with the snapshot. If it is the same, the test passes, otherwise, it fails.

Let’s see snapshot testing in Jest with an example. You implement snapshot testing using the simple matcher called toMatchSnapshot().

We now modify the two tests in the preceding paragraph to use snapshot testing. While the test for checkEmail simply checks if the result is true or false (so there is not any significant advantage in using snapshot testing), the test for validateEmail is a bit more complicated.

Indeed, we wrote a test expressions like this:

expect(main({email: "michele@sciabarra.com"})
   .message[0])
   .toBe('email: michele@sciabarra.com')
expect(main({email: "michele.sciabarra.com"})
   .errors[0])
   .toBe('michele.sciabarra.com does not look like an email')

Here we are taking the test output, extracting some pieces (.message[0] or .errors[0]) to verify only a part of the result.

We could save yourself from the burden of thinking which parts to inspect just writing:

test("validate email with snapshot", () => {
  expect(main({email: "michele@sciabarra.com"})
   .toMatchSnapshot()
  expect(main({email: "michele.sciabarra.com"})
   .toMatchSnapshot()
})

Now, if you run the test, Jest will save the results of the tests. Of course, we should always check that the snapshot is correct. Here is the first execution of the tests, when you create the snapshots:

$ jest email-snap
 PASS  ./email-snap.test.js
  ✓ validate email with snapshot (7ms)

 › 2 snapshots written.                         
Snapshot Summary
 › 2 snapshots written in 1 test suite.

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   2 added, 2 total                   
Time:        0.899s, estimated 1s

running the test creates two snapshots

summary of the snapshots in the test

Jest creates a folder named __snapshots__ to store snapshots; then, for each test, it writes a file named after the filename containing the snapshots:

__snapshots__/email-snap.test.js.snap

This file is human readable, and it was designed e expecting that a human can reads it to be sure the result of the snapshot are as expected.

For example, this is the content of the snapshot file just created:

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`validate email with snapshot 1`] = `  
Object {
  "email": "michele@sciabarra.com",
  "errors": Array [],
  "message": Array [                           
    "email: michele@sciabarra.com",
  ],
}
`;

exports[`validate email with snapshot 2`] = `  
Object {
  "email": "michele.sciabarra.com",
  "errors": Array [                            
    "michele.sciabarra.com does not look like an email",
  ],
  "message": Array [],
}
`;

result of the first test, with a correct email

we produce an array of messages

result of the second test, with a wrong email

we produce an array of errors

Now, once we have verified the snapshot to be correct, all we have to do is to keep it, saving in the version control system. If the snapshot is already present, running again the tests will compare the test execution against the snapshot, as follows:

$ jest email-snap.test.js
 PASS  ./email-snap.test.js
  ✓ validate email with snapshot (7ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   2 passed, 2 total
Time:        0.876s, estimated 1s

Updating a Snapshot when something change

Once a snapshot is in place, Jest will verify the tests always returns the same result. But of course, snapshots cannot be set on stone. It may happen that something change and we will have to update the snapshot. So let’s make now an example of a failed test verified comparing a snapshot, then update that snapshot.

For example, assume we decide that from now we want to consider acceptable only emails having a dot in the username. This example is, of course, non-realistic, made only to add another constraints to fail on purpose some snapshot tests and act as a consequence.

So, we change the regular epression to validate the emails:

before: var re = /\S+@\S+\.\S+/;
after : var re = /\S+\.\S+@\S+\.\S+/;

If we now run the tests, we see they are now failing:

FAIL ./email-snap.test.js
  ✕ validate email with snapshot (17ms)

  ● validate email with snapshot

    expect(value).toMatchSnapshot()

    Received value does not match stored snapshot 1.

    - Snapshot
    + Received

      Object {
        "email": "michele@sciabarra.com",
    -   "errors": Array [],
    -   "message": Array [
    -     "email: michele@sciabarra.com",
    +   "errors": Array [
    +     "michele@sciabarra.com does not look like an email",
        ],
    +   "message": Array [],
      }

      2 |
      3 | test("validate email with snapshot", () => {
    > 4 |     expect(main({email: "michele@sciabarra.com"})).toMatchSnapshot()
      5 |     expect(main({email: "michele.sciabarra.com"})).toMatchSnapshot()
      6 | })
      7 |

      at Object.<anonymous>.test (testing/strategy/email-snap.test.js:4:52)

 › 1 snapshot test failed.
Snapshot Summary
 › 1 snapshot test failed in 1 test suite. Inspect your code changes or re-run \
      jest with `-u` to update them.

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   1 failed, 1 passed, 2 total
Time:        0.967s, estimated 1s
Ran all test suites matching /email-snap.test.js/i.

We can fix the test replacing the first email:

expect(main({email: "michele.sciabarra@gmail.com"}))
.toMatchSnapshot()

However, if we run the test again, it will still be failing because the snapshot expects a michele@sciabarra.com somewhere.

We need to update the tests using jest -u. The flag -u tells to Jest to discard the current content of the snapshot cache and recreate them.

After updating tests of course, you should check that the new snapshot is correct. Indeed we have now:

 "message": Array [
    "email: michele.sciabarra@gmail.com",
  ],

and the new snapshot is ready to be used for further tests.

Mocking an https request

The concept behind mocking is pretty simple: you run your code replacing a system you interface with, using a simulation that you can execute locally. The simulation generally runs without connecting to any real system and providing dummy data.

To better understand how it works, and which problem mocking solves, let’s consider a common problem: testing code that executes a remote HTTP call. We are going for this purpose to write a simple action httptime.js, that just return the current time.

However, to make it a case of an action “hard” to test it, the implementation is going to use another action, invoked via http, that will return the date and time in full format, from where our action will extract the time.

We will have to use the NodeJS https module, that is a bit low level; also we need to wrap the call in a Promise, to conform to OpenWhisk requirements. For those reasons the code is a bit more convoluted than we would like it to be. However, since mocking https call is a frequent and important case, it is worth to follow this example in full.

The action to be tested by Mocking

The code in the following listing, implementing an action that returns current time via another action providing date and time, works this way:

• wraps everything in a promise, providing a resolve function

• opens an http request to an url, provide as a parameter

• define event handlers for two events: data and end

• collect data as they are received

• at the end extract the time with a regular expression

const https = require("https")

function main(args) {
  return new Promise(resolve => {                    
    let time = ""                                    
    https.get(args.url, (resp) => {                  
      resp.on('data', (data) => {                    
        time += data                                 
      })
      resp.on('end', () => {                         
        var a = /(\d\d:\d\d:\d\d)/.exec(time)        
        resolve({body:a[0]})                         
      })
     })
   })
}

wrap everything in a promise

this variable collects the input

use the https module

handle the data event, new data received

collect the data

handle the end event, all data received

this regexp extract the time from the date

return the value extracted

For convenience, let’s test first the real thing, deploying it in OpenWhisk. We need to create also the action service that returns the current time and date.

Note the following commands, that create on the fly an action on the command line and pass its url to our action:

$ CODE="function main() {\                           
>  return { body: new Date() } }"
$ wsk action update testing/now <(echo $CODE) \      
   --kind nodejs:6 --web true
$ URL=$(wsk action get testing/now --url | tail -1)  
$ curl $URL                                          
2018-05-02T19:42:34.289Z

store some code in a variable

use a bash feature to create a temporary file

get the url of the newly created action

invoke the action in http

We can now deploy and invoke the action to see if it works:

$ wsk action update testing/httptime httptime.js \
  -p url "$URL" --web true
$ TIMEURL=$(wsk action get testing/httptime --url | tail -1)
$ curl $TIMEURL
20:06:55

Mocking the https module

The example action we just wrote is a typical example of an action difficult to unit test, for many common reasons:

• it invokes a remote service, so to run tests you need to be connected to the internet

• you also need to be sure the invoked service is readily available

• data returned changes every time, so you cannot compare results with fixed values

Hence we have a is a perfect candidate for testing by mocking the remote service. We need to replace the https call with a mock that will not perform any remote call. Let see how to do it with Jest.

To replace the https module with a mock the following steps are required:

• put code that replaces the https modules with your code in a directory called __mocks__

• use jest.mock('https') in your test code before importing the module to test

• write your test code as if you were using the real service

When you perform a require in a jest test, it will load your mocking code instead of the regular code. Since we want to replace the https module, we need to write a __mocks__\https.js mock code.

Now it is time to write the mock code that should replace the https call.

To better understand it, let’s split the description into two steps. At the top level, it works mostly in this way:

https.get(URL, (resp) =>
   resp.on('data', (data) => {

     // COLLECT_DATA

   }

   resp.on('end', () => {

      // COMPLETE_REQUEST

   }

}

The “real” https module receives an object (resp) as a gatherer of event handling functions, that mimic how https works. The protocol https, when performing a request, opens a connection to an URL, then read and return results in multiple chunks. For this reason, you can have multiple calls to the data event executing the code marked as COLLECT_DATA. Hence you need to collect data before analyzing them. When all the data are collected, you get one (and only one) invocation to execute the code marked as COMPLETE_REQUEST.

If we want to emulate this code with a mock, we need to do the following steps:

1. first create an object that store the event handler

2. invoke once (or more) the data event handler

3. invoke once the end event handler

So, the code to gather the events is:

var observer = {               
   on(event, fun) {            
       observer[event] = fun   
    }
}

create an object

define an on function

assign to a field named as the event a function

This code is simple, but is it not so obvious. It defines an object that can register event handlers, and then can invoke them by name, as follows:

observer.on('something', doSomething)

observer.something(1)

So if you pass the observer to the https.get function, you will get being able to invoke the two handlers registered. Code will register resp.on('data', dataFunc) and resp.on('end', endFunc). Afterwards you will invoke just resp.data("some data") and resp.end().

Now that we have our observer, the full mock is much simpler to write.

// observer here, omitted for brevity

function get(url, handler) {       

    handler(observer)              

    observer.data(url)             

    observer.end()                 

}

module.exports.get = get

it will be invoked as https.get(url, handler)

to fully understand this, review the first listing in this section

important: we are using the URL itself as the value returned by the mocked https call

invoke the end handler

Now, we can use the our __mock__/https.js to write a test https.test.js:

jest.mock('https')                        
const main = require('./httptime').main   
test('https', () => {                     
  main({
    url: '2000-01-01T00:00:00.000Z'       
  }).then(res => {                        
    expect(res.body).toBe('00:00:00')     
  })
})

enable the mock

import the action locally for test

declare a test

invoke the main, remember we use the URL as the data!

the action returns a promise, so we have to handle it

check the handler extracts the time from the date

To be sure, we try to rerun the test with different data:

test('https2', () => {
  main({ url: '2018-05-02T19:42:34.289Z' })
  .then(res => {
    expect(res.body).toBe('19:42:34')
  })
})

The final result:

$ jest httptime
 PASS  ./httptime.test.js
  ✓ https (5ms)
  ✓ https2 (1ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.222s
Ran all test suites matching /httptime/i.

Using the mocking library to invoke an action

To use our library, we have to follow some conventions in the layout of our code.

When your application runs in OpenWhisk, you do not have the problem of locating the code when invoking an action. You deploy them with the name you choose, then use this name in the action invocation. It is the OpenWhisk runtime that resolves the names.

When you test your code locally and simulate invocations by mocking, you do not deploy your action code, but you still invoke it by name. So our mocking library must be to locate the actual code locally. It does following some conventions.

To illustrate the conventions it follows, let’s see an example. We write a test that will invoke an action using the OpenWhisk API.

const ow = require('openwhisk')             
test("invoke email validation", () => {
    ow()                                    
      .actions.invoke({                     
        name: "testing/strategy-email",     
        params: {
          email: "michele.sciabarra.com"    
        }
      }).then(res =>
        expect(res).toMatchSnapshot())
})

initialization of the OpenWhisk library

create the actual invocation instance

perform the invocation

action name

parameters

You must translate the testing/strategy-email name in a file name located in the local filesystem. We use, as the base in the filesystem, the folder with our package.json and node_modules, that is the project root.

By convention, we name our actions according to this structure:

<package>/<prefix>-<action>

Then we expect actions code to be placed in a file named:

<package>/<prefix>/<file>.js

So, when you test locally code invoking the testing/strategy-email action, the mocking library works in this way:

• the require("openwhisk") will actually load the __mocks__/openwhisk.js library

• the mocking library can locate its position from the __dirname variable, hence find the project root (that is, the parent directory)

• using the name of the action, it can now locate the code of the action to invoke: in our case <project-root>/testing/strategy/email.js

Mocking action parameters

There is another essential feature required to complete our simulation for testing.

In OpenWhisk, actions can have additional parameters. Those parameters can be specified when you deploy the action or can be inherited from the package to which the action belongs. When we use our library mocking library, we can simulate those parameters by adding a file with the same name as the action and extension .json.

For example, in our case we have the file testing/strategy/email.json, in the same folder as the email.js with the content:

{
    "errmsg": " is not an email address"
}

The mocking library uses this file, preloading the parameters and passing them as args. Indeed we can check the test has used the parameter errmsg. We need to check the snapshot to see:

$ cat __snapshots__/invoke.test.js.snap                    
// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`invoke email validation 1`] = `
Object {
  "email": "michele.sciabarra.com",
  "errors": Array [
    "michele.sciabarra.com is not an email address",      
  ],
  "message": Array [],
}
`;

dump on the terminal the snapshot file

the error message produced is the one specified in the email.json file

Mocking a sequence

We can now complete our analysis of the mocking library by describing how to mock a sequence.

In Chapter 5 we saw the pattern “Chain of Responsibility” implemented as a sequence.

A sequence does not have a corresponding action, but it does exist as a deployment declaration only. We can simulate an action sequence with a particular value in the JSON file we use to pass parameters.

For example, let consider a test to a sequence:

test('validate4', () =>
 ow().actions.invoke({
   name: 'testing/chainresp-validate',
   params: {
     name: 'Michele',
     email: 'michele.sciabarra.com',
     phone: '1234567890'
   }
}).then(res => expect(res).toMatchSnapshot()))

There is not a testing/chainresp/validate.js file, but there is a testing/chainresp/validate.json with this content:

{
  "__sequence__": [
    "testing/strategy-name",
    "testing/strategy-email",
    "testing/strategy-phone"
  ]
}

You can now write a test for example as follows:

const ow = require('openwhisk')
test('validate', () =>
  ow().actions
    .invoke({
      name: 'testing/chainresp-validate',
      params: {
        name: 'Michele',
        email: 'michele.sciabarra.com',
        phone: '1234567890'
      }
    })
    .then(res => expect(res).toMatchSnapshot()))

The mocking library then read the __sequence__ property from the validate.json and translate in a sequence of invocations (as it would happen in the real OpenWhisk) allowing to test the result of a chained invocation locally.

We can see that the mocking of the sequence works inspecting the snapshot.

// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`validate 1`] = `
Object {
  "email": "michele.sciabarra.com",
  "errors": Array [
    "michele.sciabarra.com is not an email address",  
  ],
  "message": Array [
    "name: Michele",
    "phone: 1234567890",
  ],
  "name": "Michele",
  "phone": "1234567890",
}
`;

error message defined as a parameter