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.