hpropagate

    1.0.1 • Public • Published

    NPM

    hpropagate CircleCI

    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:

    1. x-correlation-id. If the header is missing from the inbound request, it will be created with a UUID as value.
    2. x-variant-id to allow us to deploy multiple versions of the same services at the same time.
    3. x-feature-flags to allow us to dynamically turn on feature flags.
    4. x-request-id for tracing
    5. x-b3-traceid for tracing
    6. x-b3-spanid for tracing
    7. x-b3-parentspanid for tracing
    8. x-b3-sampled for tracing
    9. x-b3-flags for tracing
    10. 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

    • Only tested with Express 4
    • Need Node >= 8
    • Many more....

    Keywords

    none

    Install

    npm i hpropagate

    DownloadsWeekly Downloads

    7,420

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    12.5 kB

    Total Files

    7

    Last publish

    Collaborators

    • wealthwizards