README

Helix Vulcain Filters

Vulcain-like fields filters for OpenWhisk web actions

Status

Background

Vulcain is a protocol using HTTP/2 Server Push to create fast and idiomatic client-driven REST APIs. It uses a combination of the Fields and Preload request headers to enable clients to restrict the fields they want to get in a JSON response (Fields) and request server pushes for linked hypermedia resources (Preload).

The Vulcain repository linked above contains a reference implementation and describes the spec. Helix Vulcain Filters is an implementation of the spec that is not re-using any code of the reference implementation to make it usable in a serverless environment using Apache OpenWhisk and Fastly.

Architecture

Helix Vulcain Filters provides two wrapper functions that implement key parts of the Vulcain protocol.

The wrapFields function takes an existing OpenWhisk main function and returns a new function that implements the Fields header-based filtering of JSON responses.

The wrapPreload function takes an existing OpenWhisk main function and returns a new function that implements the Preload header-based pushing of related resources. The wrapPreload function does that by adding a Link header with a rel=preload value for every resource that should be pushed. It relies on Fastly to perfom the actual HTTP2 server push.

Installation

$ npm install -S @adobe/helix-vulcain-filters

Usage

Add this to your main function:

const { wrapFields, wrapPreload } = require('@adobe/helix-vulcain-filters');

function main(params) {
    return {
        statusCode: 200,
        body: {
            hello: params.name || world,
            more: '/foo.json'
        }
    }
}

module.exports.main = wrapFields(wrapPreload(main));

The wrappers only operate on:

web actions
that have JSON responses
when either the Preload or Fields headers are set

Note: as usual in OpenWhisk, the headers are case-insensitive.

Development

Build

$ npm install

Test

$ npm test

Lint

$ npm run lint

Usage no npm install needed!