hpropagate

This package automatically propagates HTTP headers from inbound to outbound HTTP requests.

The why

We use a micro-service architecture with a growing number of HTTP endpoints. We want to propagate certain HTTP headers received from the incoming HTTP requests to all subsequent outbound HTTP requests without the need for our engineers to do it programmatically in each services:

By default, the following headers are automatically propagated:

x-correlation-id. If the header is missing from the inbound request, it will be created with a UUID as value.
x-variant-id to allow us to deploy multiple versions of the same services at the same time.
x-feature-flags to allow us to dynamically turn on feature flags.
x-request-id for tracing
x-b3-traceid for tracing
x-b3-spanid for tracing
x-b3-parentspanid for tracing
x-b3-sampled for tracing
x-b3-flags for tracing
x-ot-span-context for tracing

Apart from x-correlation-id, only headers received on the incoming request will be propagated to outbound calls.

The list of headers can be overriden and the initialisation of x-correlation-id disabled, see below

Getting started

To use the default configuration:

// should have this line as early as possible in your code
// it must be before loading express and request
const hpropagate = require("hpropagate");

// then start it
hpropagate();

Or do it in one go:

require("hpropagate")();

Override Defaults

to disable the initialisation and generation of the correlation id header:

hpropagate({
  setAndPropagateCorrelationId: false,
});

to override the list of headers to propagate:

hpropagate({
  headersToPropagate: ["x-my-header", "x-another-header"],
});

You can also combine those, for example to disable the initialisation of the correlation id and only propagate it:

hpropagate({
  setAndPropagateCorrelationId: false,
  headersToPropagate: ["x-correlation-id"],
});

to enable the propagation of the headers in the response (to allow more traceability):

hpropagate({
  propagateInResponses: true,
});

The How

Inspiration from this talk (Slides and Code) and this module

The first goal is to be able to propagate certain headers (i.e. X-Correlation-ID) to outbound HTTP requests without the need to do it programmatically in the service.

It works by using a global tracer object which keeps a records of traces (a trace object per http request). The header value is saved in the trace object associated with the current request. The http core code is wrapped to record headers on the trace (on the request listener of the http server set with http.createServer) and inject headers to the outbound requests (currently only on http.request).

Node's async_hooks module (new in Node 8) is used to set/reset tracer.currentTrace to the trace relevant to the current execution context. tracer.currentTrace is used in the wrapped functions to record/access the headers data.

Limitations