Official CloudEvents' SDK for JavaScript.
Before create an awesome PR, please read our guidelines.
To see working examples, point to examples.
0.x.p: wherexrelates to spec version andprelates to fixes and releases.
x.M.p: wherexrelates to spec version,Mrelates to minor andprelates to fixes. See semver
This CloudEvents SDK requires nodejs 6.11+
npm install cloudevents-sdkThese 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 | 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 Structured events over HTTP | no | yes |
| Receice Binary events over HTTP | no | yes |
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);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");var Cloudevent = require("cloudevents-sdk");
/*
* Create
8000
s 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 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 = new 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);
});You can choose any framework for port binding. But, use the Unmarshaller to process the HTTP Payload and HTTP Headers, extracting the CloudEvents.
The Unmarshaller will parse the HTTP Request and decides if it is a binary or a structured version of transport binding.
😃 Checkout the full working example: here.
// some parts were removed //
var Unmarshaller02 = require("cloudevents-sdk/http/unmarshaller/v02");
// some parts were removed //
app.post('/', function (req, res) {
unmarshaller.unmarshall(req.body, req.headers)
.then(cloudevent => {
// TODO use the cloudevent
res.status(201)
.send("Event Accepted");
})
.catch(err => {
console.error(err);
res.status(400)
.header("Content-Type", "application/json")
.send(JSON.stringify(err));
});
});
├── index.js
├── ext
├── lib
│ ├── bindings
│ │ └── http
│ ├── cloudevent.js
│ ├── formats
│ │ └── json
│ └── specs
├── LICENSE
├── package.json
├── README.md
index.js: library exportsext: external stuff, e.g, Cloud Events JSONSchemalib/bindings: every binding implementation goes herelib/bindings/http: every http binding implementation goes herelib/cloudevent.js: implementation of Cloudevent, an interfacelib/formats/: every format implementation goes herelib/specs/: every spec implementation goes here
The unit test checks the result of formatted payload and the constraints.
npm test/*
* 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)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)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)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)Every Binding class must implement these methods to work properly.
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)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)The Unmarshaller classes uses the receiver API, abstracting the formats:
- structured
- binary
Choosing the right implementation based on the headers map.
/*
* Constructor without arguments
*/
Unmarshaller()
/*
* The method to unmarshall the payload.
* @arg payload could be a string or a object
* @arg headers a map of headers
*/
Promise Unmarshaller.unmarshall(payload, headers)See how to implement the method injection here
Learn about Builder Design Pattern
Check out the produced event payload using this tool