09b0c76826
This change adds a `ValidationError` type that extends `TypeError`. Any time a `CloudEvent` cannot be received and created with the given input, this error will be thrown. Tests have all been updated to check for the error type. Signed-off-by: Lance Ball <lball@redhat.com> |
||
|---|---|---|
| .github/workflows | ||
| docs | ||
| examples | ||
| lib | ||
| test | ||
| v1 | ||
| v03 | ||
| .eslintrc | ||
| .gitignore | ||
| .jsdoc.json | ||
| .npmignore | ||
| .travis.yml | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
| index.js | ||
| maintainer_guidelines.md | ||
| package-lock.json | ||
| package.json | ||
| pr_guidelines.md | ||
README.md
JavaScript SDK for CloudEvents
The CloudEvents SDK for JavaScript.
This module will help you to:
- Represent CloudEvents in memory
- Use Event Formats to serialize/deserialize CloudEvents
- Use Protocol Bindings to send/receive CloudEvents
Note: Supported CloudEvents specification: 0.3, 1.0
A Note on Versioning
The CloudEvents protocol version is distinct from this module's version number. For example, this module may be versioned as v2.0.0 but support the v0.3 and v1.0 versions of the CloudEvent specification.
Usage
See the full working example: here.
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:
npm install --save 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.
const {
CloudEvent,
HTTPReceiever
} = 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
Currently, to emit events, you'll need to decide whether the event is in binary or structured format, and determine what version of the CloudEvents specification you want to send the event as.
const { CloudEvent } = require("cloudevents-sdk");
const { StructuredHTTPEmitter } = require("cloudevents-sdk/v1");
const myevent = new CloudEvent()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");
const emitter = new StructuredHTTPEmitter({
method: "POST",
url : "https://myserver.com"
});
// Emit the event
emitter.emit(myevent)
Supported specification features
| v0.3 | v1.0 | |
|---|---|---|
| CloudEvents Core | ✔️ | ✔️ |
| AMQP Protocol Binding | ❌ | ❌ |
| AVRO Event Format | ❌ | ❌ |
| HTTP Protocol Binding | ✔️ | ✔️ |
| JSON Event Format | ✔️ | ✔️ |
| Kafka Protocol Binding | ❌ | ❌ |
| NATS Protocol Binding | ❌ | ❌ |
| STAN Protocol Binding | ❌ | ❌ |
Community
- There are bi-weekly calls immediately following the Serverless/CloudEvents call 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 to determine which week will have the call.
- Slack: #cloudeventssdk channel under CNCF's Slack workspace.
- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
- Contact for additional information: Fabio José (
@fabiojoseon slack).
Contributing
We love contributions from the community! Please check the Contributor's Guide for information on how to get involved.