adobe / openwhisk-action-utils

Utilities for OpenWhisk Actions
Apache License 2.0
2 stars 3 forks source link
helix helix2 helper library openwhisk utilities

Openwhisk Action Utilities

Utilities for OpenWhisk actions.

Status

GitHub license GitHub issues CircleCI codecov LGTM Code Quality Grade: JavaScript

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

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

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

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.