Openwhisk Action Utilities

Utilities for OpenWhisk actions.

Status

API Reference

Modules

expressify

Helper to turn a OpenWhisk web action into a express request which can be handled with normal express handlers.

Expressify maps the query and most of action params to req.query. The original action params are available under req.owActionParams.

Usage:

const { expressify, errorHandler } = require('@adobe/openwhisk-action-utils');

async function main(params) {
  const app = express();
  app.use(cookieParser());
  app.use(express.static('static'));
  app.get('/', homepageHandler);
  app.get('/ping', pingHandler);
  app.use(errorHandler(log));

  return expressify(app)(params);
}

middleware

Helper functions for expressified actions.

Usage:

const {
  expressify, logRequest, errorHandler, asyncHandler, cacheControl, createBunyanLogger,
} = require('@adobe/openwhisk-action-utils');

async function startHandler(params, req, res) {
   res.send('Hello, world.');
}
async function main(params) {
  const log = createBunyanLogger();
  const app = express();
  app.use(logRequest(log));
  app.use(cacheControl());
  app.get('/', asyncHandler(startHandler));
  app.get('/ping', asyncHandler(pingHandler));
  app.use(errorHandler(log));

  return expressify(app)(params);
}

wrap

Helper function to easily chain OpenWhisk actions.

Usage:

const { wrap } = require('@adobe/openwhisk-action-utils');

async main(params) {
  // …my action code…
}

module.exports.main = wrap(main)
  .with(epsagon)
  .with(status)
  .with(logger);

Classes

VersionLock

Helper class that uses the information in the x-ow-version-lock header to lock the version of an openwhisk action.

Functions

createBunyanLogger([logger]) ⇒ BunyanLogger

Sets up a bunyan logger suitable to use with an openwhisk action. The bunyan logger will stream to the given helix logger.

expressify

Helper to turn a OpenWhisk web action into a express request which can be handled with normal express handlers.

Expressify maps the query and most of action params to req.query. The original action params are available under req.owActionParams.

Usage:

const { expressify, errorHandler } = require('@adobe/openwhisk-action-utils');

async function main(params) {
  const app = express();
  app.use(cookieParser());
  app.use(express.static('static'));
  app.get('/', homepageHandler);
  app.get('/ping', pingHandler);
  app.use(errorHandler(log));

  return expressify(app)(params);
}

expressify~expressify(app) ⇒ ActionFunction

Creates an OpenWhisk action function that uses the express framework to handle the invocation.

Kind: inner method of expressify
Returns: ActionFunction - An action function.
See: https://expressjs.com/en/4x/api.html#app

middleware

Helper functions for expressified actions.

Usage:

const {
  expressify, logRequest, errorHandler, asyncHandler, cacheControl, createBunyanLogger,
} = require('@adobe/openwhisk-action-utils');

async function startHandler(params, req, res) {
   res.send('Hello, world.');
}
async function main(params) {
  const log = createBunyanLogger();
  const app = express();
  app.use(logRequest(log));
  app.use(cacheControl());
  app.get('/', asyncHandler(startHandler));
  app.get('/ping', asyncHandler(pingHandler));
  app.use(errorHandler(log));

  return expressify(app)(params);
}

• middleware
  • ~errorHandler(log) ⇒ ExpressMiddleware
  • ~cacheControl([value]) ⇒ ExpressMiddleware
  • ~hideHeaders(headerNames) ⇒ ExpressMiddleware
  • ~logRequest(logger, [level]) ⇒ ExpressMiddleware
  • ~asyncHandler(fn) ⇒ ExpressMiddleware
  • ~ActionMiddlewareFunction : function

middleware~errorHandler(log) ⇒ ExpressMiddleware

Error handler. Reports errors that happen during the request processing and responds with a 500 if not already set.

Kind: inner method of middleware
Returns: ExpressMiddleware - an express middleware function.

Example

// install last
app.use(errorHandler(log));

middleware~cacheControl([value]) ⇒ ExpressMiddleware

Ensures cache control. Sets cache control headers.

Kind: inner method of middleware
Returns: ExpressMiddleware - an express middleware function.

Example

app.use(cacheControl());

middleware~hideHeaders(headerNames) ⇒ ExpressMiddleware

Hides headers from enumeration.

Kind: inner method of middleware
Returns: ExpressMiddleware - an express middleware function.

Example

// install first
app.use(hideHeaders(['x-token', 'authentication'));
app.use(logRequest(log));

middleware~logRequest(logger, [level]) ⇒ ExpressMiddleware

Creates a bunyan child logger for the request and adds it to the request. This ensures that important header values, like x-request-id are included in every log entry. It also logs the request and response lines.

Kind: inner method of middleware
Returns: ExpressMiddleware - an express middleware function.

Example

// install first
app.use(logRequest(log));

middleware~asyncHandler(fn) ⇒ ExpressMiddleware

Wraps the route middleware so it can catch potential promise rejections during the async invocation.

Kind: inner method of middleware
Returns: ExpressMiddleware - an express middleware function.

middleware~ActionMiddlewareFunction : function

Extended middleware function to be use with the asyncHandler.

Kind: inner typedef of middleware
See: https://expressjs.com/en/4x/api.html#middleware-callback-function-examples

wrap

Helper function to easily chain OpenWhisk actions.

Usage:

const { wrap } = require('@adobe/openwhisk-action-utils');

async main(params) {
  // …my action code…
}

module.exports.main = wrap(main)
  .with(epsagon)
  .with(status)
  .with(logger);

• wrap
  • ~wrap(main) ⇒ WrappableActionFunction
  • ~ActionFunction ⇒ object
  • ~WrappableActionFunction ⇒ object
  • ~WrapFunction ⇒ ActionFunction

wrap~wrap(main) ⇒ WrappableActionFunction

A function that makes your action function (i.e. main) wrappable, so that using with a number of wrappers can be applied. This allows you to export the result as a new function.

Kind: inner method of wrap
Returns: WrappableActionFunction - the same main function, now including a with method

Example

async main(params) {
  //…my action code…
}

module.exports.main = wrap(main)
.with(epsagon)
.with(status)
.with(logger);

Note: the execution order is that the last wrapper added will be executed first.

wrap~ActionFunction ⇒ object

The main function of an OpenWhisk action.

Kind: inner typedef of wrap
Returns: object - a result

wrap~WrappableActionFunction ⇒ object

An ActionFunction that has been augmented to become wrappable using the with method.

Kind: inner typedef of wrap
Returns: object - a result

wrap~WrapFunction ⇒ ActionFunction

A function that wraps (and invokes your main function). It can be used to decorate inputs or outputs, or to provide additional functionality like logging, tracing, debugging, etc.

Kind: inner typedef of wrap
Returns: ActionFunction - a new function with the same signature as your original main function

Example

function tracer(fn, level) {
  return (params) => {
    log[level]('enter');
    const ret = fn(params);
    log[level]('exit');
    return ret;
  }
}

VersionLock

Helper class that uses the information in the x-ow-version-lock header to lock the version of an openwhisk action.

Kind: global class

• VersionLock
  • new VersionLock(params, defaults)
  • instance
    • .transformActionURL(url)
    • .wrapOpenwhisk(ow) ⇒ OpenWhisk
  • static
    • .X_OW_VERSION_LOCK ⇒ string

new VersionLock(params, defaults)

Creates a version lock class.

versionLock.transformActionURL(url)

Transforms an action url according to the lock information.

Kind: instance method of VersionLock

versionLock.wrapOpenwhisk(ow) ⇒ OpenWhisk

Enhances an openwhisk client by wrapping the invoke method for automatic action name replacement.

Kind: instance method of VersionLock
Returns: OpenWhisk - the wrapped client

VersionLock.X_OW_VERSION_LOCK ⇒ string

The name of the version lock header.

Kind: static property of VersionLock
Returns: string - 'x-ow-version-lock'

createBunyanLogger([logger]) ⇒ BunyanLogger

Sets up a bunyan logger suitable to use with an openwhisk action. The bunyan logger will stream to the given helix logger.

Kind: global function
Returns: BunyanLogger - A bunyan logger