144 lines
5.6 KiB
Markdown
144 lines
5.6 KiB
Markdown
# JavaScript SDK for CloudEvents
|
|
|
|
## WARNING: This module has changed its name to 'cloudevents'.
|
|
### PLEASE CONSIDER UPGRADING YOUR DEPENDENCY
|
|
|
|
`npm install cloudevents`
|
|
|
|
---
|
|
|
|
[](https://www.codacy.com/app/fabiojose/sdk-javascript?utm_source=github.com&utm_medium=referral&utm_content=cloudevents/sdk-javascript&utm_campaign=Badge_Grade)
|
|
[](https://www.codacy.com/app/fabiojose/sdk-javascript?utm_source=github.com&utm_medium=referral&utm_content=cloudevents/sdk-javascript&utm_campaign=Badge_Coverage)
|
|
|
|
[](https://www.npmjs.com/package/cloudevents-sdk)
|
|
[](https://snyk.io/test/github/cloudevents/sdk-javascript)
|
|
|
|
The CloudEvents SDK for JavaScript.
|
|
|
|
## Features
|
|
|
|
* Represent CloudEvents in memory
|
|
* Serialize and deserialize CloudEvents in different [event formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format).
|
|
* Send and recieve CloudEvents with via different [protocol bindings](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding).
|
|
|
|
_Note:_ Supports CloudEvent versions 0.3, 1.0
|
|
|
|
## Installation
|
|
|
|
The CloudEvents SDK requires a current LTS version of Node.js. At the moment
|
|
those are Node.js 10.x and Node.js 12.x. To install in your Node.js project:
|
|
|
|
```console
|
|
npm install cloudevents-sdk
|
|
```
|
|
|
|
### Receiving and Emitting Events
|
|
|
|
#### Receiving Events
|
|
|
|
You can choose almost any popular web framework for port binding. Use an
|
|
`HTTPReceiver` to process the incoming HTTP request. The receiver accepts
|
|
binary and structured events in either the 1.0 or 0.3 protocol formats.
|
|
|
|
```js
|
|
const {
|
|
CloudEvent,
|
|
HTTPReceiver
|
|
} = require("cloudevents-sdk");
|
|
|
|
// Create a receiver to accept events over HTTP
|
|
const receiver = new HTTPReceiver();
|
|
|
|
// body and headers come from an incoming HTTP request, e.g. express.js
|
|
const receivedEvent = receiver.accept(req.body, req.headers);
|
|
console.log(receivedEvent.format());
|
|
```
|
|
|
|
#### Emitting Events
|
|
|
|
To emit events, you'll need to decide whether the event should be sent in
|
|
binary or structured format, and determine what version of the CloudEvents
|
|
specification you want to send the event as.
|
|
|
|
By default, the `HTTPEmitter` will emit events over HTTP POST using the
|
|
1.0 specification, in binary mode. You can emit 0.3 events by providing
|
|
the specication version in the constructor to `HTTPEmitter`. To send
|
|
structured events, add that string as a parameter to `emitter.sent()`.
|
|
|
|
```js
|
|
const { CloudEvent, HTTPEmitter } = require("cloudevents-sdk");
|
|
|
|
// With only an endpoint URL, this creates a v1 emitter
|
|
const v1Emitter = new HTTPEmitter({
|
|
url: "https://cloudevents.io/example"
|
|
});
|
|
const event = new CloudEvent({
|
|
type, source, data
|
|
});
|
|
|
|
// By default, the emitter will send binary events
|
|
v1Emitter.send(event).then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
// To send a structured event, just add that as an option
|
|
v1Emitter.send(event, { mode: "structured" })
|
|
.then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
// To send an event to an alternate URL, add that as an option
|
|
v1Emitter.send(event, { url: "https://alternate.com/api" })
|
|
.then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
// Sending a v0.3 event works the same, just let the emitter know when
|
|
// you create it that you are working with the 0.3 spec
|
|
const v03Emitter = new HTTPEmitter({
|
|
url: "https://cloudevents.io/example",
|
|
version: "0.3"
|
|
});
|
|
|
|
// Again, the default is to send binary events
|
|
// To send a structured event or to an alternate URL, provide those
|
|
// as parameters in a options object as above
|
|
v3Emitter.send(event)
|
|
.then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
```
|
|
|
|
## Supported specification features
|
|
|
|
| | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/tree/v1.0) |
|
|
| ----------------------------- | --- | --- |
|
|
| CloudEvents Core | :heavy_check_mark: | :heavy_check_mark: |
|
|
| AMQP Protocol Binding | :x: | :x: |
|
|
| AVRO Event Format | :x: | :x: |
|
|
| HTTP Protocol Binding | :heavy_check_mark: | :heavy_check_mark: |
|
|
| JSON Event Format | :heavy_check_mark: | :heavy_check_mark: |
|
|
| Kafka Protocol Binding | :x: | :x: |
|
|
| NATS Protocol Binding | :x: | :x: |
|
|
| STAN Protocol Binding | :x: | :x: |
|
|
|
|
## Community
|
|
|
|
- There are bi-weekly calls immediately following the [Serverless/CloudEvents
|
|
call](https://github.com/cloudevents/spec#meeting-time) at
|
|
9am PT (US Pacific). Which means they will typically start at 10am PT, but
|
|
if the other call ends early then the SDK call will start early as well.
|
|
See the [CloudEvents meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#)
|
|
to determine which week will have the call.
|
|
- Slack: #cloudeventssdk channel under
|
|
[CNCF's Slack workspace](https://slack.cncf.io/).
|
|
- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
|
|
- Contact for additional information: Fabio José (`@fabiojose` on slack).
|
|
|
|
## Contributing
|
|
|
|
We love contributions from the community! Please check the
|
|
[Contributor's Guide](https://github.com/cloudevents/sdk-javascript/blob/master/CONTRIBUTING.md)
|
|
for information on how to get involved.
|