backtrace-service

Backtrace Service Layer nodejs library

This library consists of a single express.js middleware function. It may contain other common Service Layer related capabilities later.

Quick Example

TypeScript:

import { ICoronerRequestOption, IdentityManager } from 'backtrace-service';
...

const identityManager = new IdentityManager();
app.post(
  '/api/{serviceName}/service',
  identityManager.serviceRequest({
    name: serviceName,
    secret: serviceSecret,
    coronerdCallback: (url: string) => {
      //coroner callback
    },
    logger: logger
  } as ICoronerRequestOption),
);

JavaScript:

const identityManager = require('backtrace-service').IdentityManager;
app.post("${url_prefix}/service", btservice.serviceRequest({
  name: 'simple',
  secret: 'asdfghjk',
  coronerdCallback: (url) => {
    console.log('heard from coronerd at: ' + url);
  },
}));

Options for serviceRequest

The following options are accepted as the sole argument for the call:

• name: Name of the service (usually its type).
• secret: The shared secret that the service will use to authenticate incoming requests and config replies from a coronerd.
• coronerdCallback: A callback that takes an URL parameter, and performs any service specific setup associated with integrating a new coronerd instance.
• logger (optional): An object that has a log function which can be logged to. For example, winston logger instances.

Service flow

Services are expected to configure one or more authentication tokens, which will be distributed to coronerd instances using the service. While a service is running, it may receive registration requests at ${url_prefix}/service, which enable the service to integrate new coronerd instances on the fly.

Coronerd URLs provided as the url parameter to coronerdCallback are the base URLs, for example, https://backtrace.sp.backtrace.io/. Services may expect to append the appropriate resource for their needs, e.g. /api/config, to reach that resource on the coronerd instance.

authenticateRequest usage

This function is intended as an additional middleware which may be used in application routes to validate requests that involve a session token issued by a remote coronerd. The actual call can reuse the same options argument used for serviceRequest, although it does not use coronerdCallback.

In the route middleware list, prior to authenticateRequest, the application must attach a req.coronerAuth object which contains:

• url: The full URL to the remote coronerd instance.
• token: The user's session token to be validated.

For example:

req.coronerAuth = {
  url: "https://backtrace.sp.backtrace.io/",
  token: "f5af46b8eb32adb860ef46a9e714cfde",
}

This normalized form is used due to the fact that different services take these parameters from clients in different ways.

Middlewares that come after authenticateRequest will have access to the validated coronerd /api/config response in req.coronerAuth.cfg.