adobe/openwhisk-action-utils

Utilities for OpenWhisk Actions

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

Param	Type	Description
app	ExpressApp	The express application

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.

Param	Type	Description
log	BunyanLogger	The logger to use for reporting errors.

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.

Param	Type	Default	Description
[value]	string	"no-store, private, must-revalidate"	Cache control header value.

Example

app.use(cacheControl());

middleware~hideHeaders(headerNames) ⇒ ExpressMiddleware

Hides headers from enumeration.

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

Param	Type	Description
headerNames	Array.<string>	Names of headers to make un-enumerable

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.

Param	Type	Default	Description
logger	BunyanLogger		the bunyan logger
[level]	string	"debug"	the log level to use for logging the request information.

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.

Param	Type	Description
fn	ExpressMiddleware	an extended 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

Param	Type	Description
params	*	The action params
req	ExpressRequest	The express request
res	ExpressResponse	The express response
next	ExpressMiddleware	The next handler in chain.

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

Param	Type	Description
main	ActionFunction	the main function to prepare for wrapping

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

Param	Type	Description
params	object	the parameters of the action function

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

Param	Type	Description
params	object	the parameters of the action function

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

Param	Type	Description
main	ActionFunction	your main function
...opts	*	configuration options for the wrapping 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.

Param	Type	Description
params	object	the openwhisk action params
defaults	object	the action name defaults.

versionLock.transformActionURL(url)

Transforms an action url according to the lock information.

Kind: instance method of VersionLock

Param	Type	Description
url	string	the action url.

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

Param	Type	Description
ow	OpenWhisk	openwhisk 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

Param	Type	Default	Description
[logger]	Logger	rootLogger	a helix multi logger. defaults to the helix rootLogger.