@compassdigital/service

Compass Digital Common Service

A library for building internal microservices for Compass Digital.

Requirements

• node.js 12.*
• mocha (globally)

Installation

npm install @compassdigital/service --save

Service class

The Service class has the following functions available that can be called directly from AWS Lambda via the service instance's "lambda" property. See Usage below.

Provider calls

The function catchall will call back to an appropriate provider with a method based on the query path.

For example, in Serverless you would setup catchall like this.

functions:
    get_menu:
        handler: lambda.catchall
        events:
            - http:
                  path: menu/{id}
                  method: get

The provider is chosen based on the "provider" params encoded in the (compassdigital.id) id of the request. To learn more about ids, visit the project compassdigital/compassdigital.id.

The query path is parsed to create a provider method based on the HTTP method, HTTP path, and AWS Lambda event path (configured in Serverless) . Examples:

Example 1

Service request:

• HTTP method: GET
• HTTP path: /menu/abcd1234
• AWS Lambda event path: /menu/{id}

Provider request:

• Method: get_menu
• Params: {id: "abcd1234"}
• ID: hijk7890 (encrypted user ID)

Example 2

Service request:

• HTTP method: PUT
• HTTP path: /foo/bar/abcd1234/toronto
• AWS Lambda event path: /foo/bar/{id}/{city}

Provider request:

• Method: put_foo_bar
• Params: {id: "abcd1234", city: "toronto"}
• ID: hijk7890 (encrypted user ID)

Usage

index.js:

// commonjs
const Service = require("@compassdigital/service").default;

const MyService = new Service({
    type: "menu",
    swagger: {...}, // Swagger 2
    request_validation: true, // validates request payloads against swagger schema
});

module.exports = MyService;

// esm
import Service from '@compassdigital/service';

const MyService = new Service({
    type: "menu",
    swagger: {...} // Swagger 2
});

export default MyService;

Request validations can be enabled on per handler basis by providing an object instead.

const Service = require("@compassdigital/service").default;

const MyService = new Service({
    type: "mealplan",
    swagger: {...},
    request_validation: {
        post_test_handler: true,
    },
});

module.exports = MyService;

lambda.js:

// const MyService = require('./lib'); //commonjs
const MyService = require('./lib').default; // esm
module.exports = MyService.lambda;

Registering a provider:

You can pass the URL of the provider

service.add_provider({
	id: 'PROVIDER_NAME',
	url: 'https://www.example.com/',
	default: true, // Optional: uses this provider for requests without a provider specified
});

or pass a reference to a DataProvider:

service.add_provider({
    id: "PROVIDER_NAME",
    provider: new DataProvider(...) // compassdigital.provider.data
    default: true // Optional: uses this provider for requests without a provider specified
});

Optionally, you can also pass request_validation at the provider level. This will override request validation configuration from service level.

Testing

npm test

Installing CDL Plugin (Warmup + other misc configs)

Install via npm in the root of your Serverless service:

npm install @compassdigital/serverless-plugin-cdl --save-dev

• Add the plugin to the plugins array in your Serverless serverless.yml:

plugins:
    - '@compassdigital/serverless-plugin-cdl'

That's it!

Logging

The service will log all requests and responses. By default, individual property values on objects are truncated to 200 characters. This limit can be controlled with the LOG_MAX_DATA_LENGTH environment variable.

Note: Unbounded logging has associated costs. The limit should only be lifted temporarily for debugging purposes.