@atomist/sdm-pack-event-relay

This extension pack allows an SDM to function as an event relay between event sources and Cortex. Reasons for doing this include air-gapped services and needing to "scrub" data from outbound payloads.

An example configuration for a relay configuration:

 const bitbucketRelay: EventRelayer<BitbucketTestData> = {
     name: "bitbucketRelay",
     test: payload => !!payload.body.actor && !!payload.body.date && !!payload.body.eventKey,
     processor: async payload => {
         (payload.body as any)["x-bitbucket-type"] = payload.headers["x-event-key"];
         return {body: payload.body, headers: payload.headers};
     },
     targetEvent: {
         eventType: "public",
         eventTarget: sdm.configuration.sdm.git.webhookdest,
         headers: (ctx, payload) => {
             payload.headers = addAtomistSignatureHeader(
                 sdm.configuration.sdm.git.key,
                 payload.body,
                 payload.headers as HttpClientOptions["headers"],
             );
             return payload.headers as HttpClientOptions["headers"];
         },
     },
 };

sdm.addExtensionPacks(
    eventRelaySupport({
        eventRelayers: [
            bitbucketRelay,
        ],
    }),
);

See the EventRelayer interface for details on creating EventRelayer(s). For details on the extension pack configuration, see the eventRelaySupport type documentation.

Authentication and/or Validation

By default the event relay pack uses the Atomist API key configured to authorize incoming relay requests. This key must be supplied in an authorization header (as a bearer token). However, this is not appropriate for all use cases. The authentication/validation used by the relay pack is pluggable using the validation option on eventRelaySupport or by adding a validator to an EventRelayer. The validator on the EventRelayer will be used first, if not present the validation global option will be used, if none are supplied the Atomist API key method will be used.

There are the 3 built-in validators, or you can build your own (see the Validator interface).

nullValidator: By using this validator you disable auth/verification completely. All messages are accepted and then evaluated to see if any configured relayer knows how to send it.

apiKeyValidator: This is the default, and functions as documented above.

githubHmacValidator: This validator uses a signature header sent by Github when you supply a secret for your pull requests (x-hub-signature). The validator loads the shared key from your SDM configuration located at sdm.eventRelay.secret and uses this to validate the signature in the incoming message. Should the signatures match, the message is accepted and the normal event relay process continues.

Multiple Workspaces

When using a private event type (which sends messages over the web socket), you need to configure your webhooks to include the workspace they should post to. If you do not supply the workspace in the URL (see below), the first workspace from your configuration will automatically be selected and used as the destination workspace for this event.

To use the first configured (or only) workspace, simply send your webhook payloads to <host>:2866/relay. To send to a specific workspace send your webhook payloads to <host>:2866/relay/:workspace.

Note: This has no impact on public event types because you provide the full destination URL in the relayer defined

Getting started

See the Developer Quick Start to jump straight to creating an SDM.

Contributing

Contributions to this project from community members are encouraged and appreciated. Please review the Contributing Guidelines for more information. Also see the Development section in this document.

Code of conduct

This project is governed by the Code of Conduct. You are expected to act in accordance with this code by participating. Please report any unacceptable behavior to code-of-conduct@atomist.com.

Documentation

Please see docs.atomist.com for developer documentation.

Connect

Follow @atomist and The Composition blog related to SDM.

Support

General support questions should be discussed in the #help channel in the Atomist community Slack workspace.

If you find a problem, please create an issue.

Development

You will need to install Node.js to build and test this project.

Build and test

Install dependencies.

$ npm install

Use the build package script to compile, test, lint, and build the documentation.

$ npm run build

Release

Releases are handled via the Atomist SDM. Just press the 'Approve' button in the Atomist dashboard or Slack.

Created by Atomist. Need Help? Join our Slack workspace.