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);
}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);
}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);Helper class that uses the information in the x-ow-version-lock header to lock the version
of an openwhisk action.
BunyanLoggerSets up a bunyan logger suitable to use with an openwhisk action. The bunyan logger will stream to the given helix logger.
ActionFunction](#module_wrap..ActionFunction)
Creates an OpenWhisk action function that uses the express framework to handle the invocation.
**Kind**: inner method of [expressify](#module_expressify)
**Returns**: [ActionFunction](#module_wrap..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:**
```js
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](#module_middleware)
* [~errorHandler(log)](#module_middleware..errorHandler) ⇒ ExpressMiddleware
* [~cacheControl([value])](#module_middleware..cacheControl) ⇒ ExpressMiddleware
* [~hideHeaders(headerNames)](#module_middleware..hideHeaders) ⇒ ExpressMiddleware
* [~logRequest(logger, [level])](#module_middleware..logRequest) ⇒ ExpressMiddleware
* [~asyncHandler(fn)](#module_middleware..asyncHandler) ⇒ ExpressMiddleware
* [~ActionMiddlewareFunction](#module_middleware..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](#module_middleware)
**Returns**: ExpressMiddleware - an express middleware function.
| Param | Type | Description |
| --- | --- | --- |
| log | BunyanLogger | The logger to use for reporting errors. |
**Example**
```js
// install last
app.use(errorHandler(log));
```
### middleware~cacheControl([value]) ⇒ ExpressMiddleware
Ensures cache control. Sets cache control headers.
**Kind**: inner method of [middleware](#module_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](#module_middleware)
**Returns**: ExpressMiddleware - an express middleware function.
| Param | Type | Description |
| --- | --- | --- |
| headerNames | Array.<string> | Names of headers to make un-enumerable |
**Example**
```js
// 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](#module_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**
```js
// 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](#module_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](#module_middleware..asyncHandler).
**Kind**: inner typedef of [middleware](#module_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:**
```js
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](#module_wrap)
* [~wrap(main)](#module_wrap..wrap) ⇒ WrappableActionFunction
* [~ActionFunction](#module_wrap..ActionFunction) ⇒ object
* [~WrappableActionFunction](#module_wrap..WrappableActionFunction) ⇒ object
* [~WrapFunction](#module_wrap..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](#module_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**
```js
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](#module_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](#module_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](#module_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**
```js
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](#VersionLock)
* [new VersionLock(params, defaults)](#new_VersionLock_new)
* _instance_
* [.transformActionURL(url)](#VersionLock+transformActionURL)
* [.wrapOpenwhisk(ow)](#VersionLock+wrapOpenwhisk) ⇒ OpenWhisk
* _static_
* [.X_OW_VERSION_LOCK](#VersionLock.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](#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](#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](#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`. |