sdk-javascript

Official CloudEvents' SDK for JavaScript.

Contributing

Before create an awesome PR, please read our guidelines.

Versioning

Before Spec reaches 1.0

• 0.x.p: where x relates to spec version and p relates to fixes and releases.

After Spec reaches 1.0

• x.M.p: where x relates to spec version, M relates to minor and p relates to fixes. See semver

Installation

This CloudEvents SDK requires nodejs 6.11+

Nodejs

npm install cloudevents-sdk

Specification Support

These are the supported specifications by this version.

Specifications	v0.1	v0.2
CloudEvents	yes	yes
HTTP Transport Binding - Structured	yes	yes
HTTP Transport Binding - Binary	yes	yes
JSON Event Format	yes	yes

What we can do?

What	v0.1	v0.2
Create events	yes	yes
Emit Structured events over HTTP	yes	yes
Emit Binary events over HTTP	yes	yes
JSON Event Format	yes	yes
Receice Structure events over HTTP	no	yes
Receice Binary events over HTTP	no	yes

How to use

The Cloudevent constructor arguments.

/*
 * spec  : if is null, set the spec 0.1 impl
 * format: if is null, set the JSON Format 0.1 impl
 */
Cloudevent(spec, format);

Usage

var Cloudevent = require("cloudevents-sdk");

/*
 * Constructs a default instance with:
 *   - Spec 0.1
 *   - JSON Format 0.1
 */
var cloudevent01 = new Cloudevent();

/*
 * Implemented using Builder Design Pattern
 */
cloudevent01
  .type("com.github.pull.create")
  .source("urn:event:from:myapi/resourse/123");

/*
 * Backward compatibility to spec 0.1 by injecting methods from spec implementation
 * to Cloudevent
 */
cloudevent01
 .eventTypeVersion("1.0");

/*
 * Constructs an instance with:
 *   - Spec 0.2
 *   - JSON Format 0.1
 */
var cloudevent02 = new Cloudevent(Cloudevent.specs["0.2"]);

/*
 * Different specs, but the same API.
 */
cloudevent02
  .type("com.github.pull.create")
  .source("urn:event:from:myapi/resourse/123");

Formatting

var Cloudevent = require("cloudevents-sdk");

/*
 * Creates an instance with default spec and format
 */
var cloudevent =
  new Cloudevent()
        .type("com.github.pull.create")
        .source("urn:event:from:myapi/resourse/123");

/*
 * Format the payload and return it
 */
var formatted = cloudevent.format();

var ce =

Emitting

var Cloudevent = require("cloudevents-sdk");

// The event
var cloudevent = new Cloudevent()
                       .type("com.github.pull.create")
                       .source("urn:event:from:myapi/resourse/123");

// The binding configuration using POST
var config = {
  method: "POST",
  url   : "https://myserver.com"
};

/*
 * To use HTTP Binary:
 *   Cloudevent.bindings["http-binary0.2"](config);
 */

// The binding instance
var binding = Cloudevent.bindings["http-structured0.1"](config);

// Emit the event using Promise
binding.emit(cloudevent)
  .then(response => {
    // Treat the response
    console.log(response.data);

  }).catch(err => {
    // Deal with errors
    console.error(err);
  });

Receiving

var Cloudevent = require("cloudevents-sdk");

// The binding configuration
var config = {
  path   : "/events",
  port   : 10300,
  method : "POST"
};

// The binding instance
var binding = new Cloudevent.bindings["http-structured0.2"](config);

binding.receive()
  .then(cloudevent => {
    // do something with event
  })
  .catch(err => {
    // deal with errors
    console.error(err);
  });

Repository Structure

├── index.js
├── ext
├── lib
│   ├── bindings
│   │   └── http
│   ├── cloudevent.js
│   ├── formats
│   │   └── json
│   └── specs
├── LICENSE
├── package.json
├── README.md

• index.js: library exports
• ext: external stuff, e.g, Cloud Events JSONSchema
• lib/bindings: every binding implementation goes here
• lib/bindings/http: every http binding implementation goes here
• lib/cloudevent.js: implementation of Cloudevent, an interface
• lib/formats/: every format implementation goes here
• lib/specs/: every spec implementation goes here

Unit Testing

The unit test checks the result of formatted payload and the constraints.

npm test

The API

Cloudevent class

/*
 * Format the payload and return an Object.
 */
Object Cloudevent.format()

/*
 * Format the payload as String.
 */
String Cloudevent.toString()

/*
 * Create a Cloudevent instance from String.
 */
Cloudevent Cloudevent.fromString(String)

Formatter classes

Every formatter class must implement these methods to work properly.

/*
 * Format the Cloudevent payload argument and return an Object.
 */
Object Formatter.format(Object)

/*
 * Format the Cloudevent payload as String.
 */
String Formatter.toString(Object)

Parser classes

Every Parser class must implement these methods to work properly.

/*
 * The default constructor with Spec as parameter
 */
Parser(Spec)

/*
 * Try to parse the payload to some event format
 */
Object Parser.parse(payload)

Spec classes

Every Spec class must implement these methods to work properly.

/*
 * The constructor must receives the Cloudevent type.
 */
Spec(Cloudevent)

/*
 * Checks the spec constraints, throwing an error if do not pass.
 * @throws Error when it is an invalid event
 */
Spec.check()

/*
 * Checks if the argument pass through the spec constraints
 * @throws Error when it is an invalid event
 */
Spec.check(Object)

Binding classes

Every Binding class must implement these methods to work properly.

Emitter Binding

Following we have the signature for the binding to emit Cloudevents.

/*
 * The constructor must receives the map of configurations.
 */
Binding(config)

/*
 * Emits the event using an instance of Cloudevent.
 */
Binding.emit(cloudevent)

Receiver Binding

Following we have the signature for the binding to receive Cloudevents.

/*
 * The constructor must receives the map of configurations.
 */
Receiver(config)

/*
 * Checks if some Object and a Map of headers
 * follows the binding definition, throwing an error if did not follow
 */
Receiver.check(Object, Map)

/*
 * Checks and parse as Cloudevent
 */
Cloudevent Receiver.parse(Object, Map)

Receiver Binding Server

Use this API to start a HTTP server and listen to events.

/*
 * The constructor must receives the map of configurations.
 */
Receiver(config)

/*
 * Listen to events and returns a Promise.
 */
Promise Receiver.listen()

/*
 * Stops the listen to events
 */
Receiver.stop()

See how to implement the method injection here

Learn about Builder Design Pattern

Check out the produced event payload using this tool