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 Serverlessserverless.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.