Skip to content

Commit

Permalink
docs: update README and examples with new API
Browse files Browse the repository at this point in the history 
This commit modifies the README to show new API usage for the
`HTTPReceiver` and `CloudEvent` classes, and updates the examples
to use this as well.

Overall structure and content has been modified to look more like
the sdk-go README.

Fixes: cloudevents#128

Signed-off-by: Lance Ball <lball@redhat.com>
  • Loading branch information
@lance
lance committed May 9, 2020
1 parent 5a6cde5 commit ff5d965
Show file tree
Hide file tree
Showing 4 changed files with 85 additions and 349 deletions.
297 changes: 60 additions & 237 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,281 +3,98 @@
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/bd66e7c52002481993cd6d610534b0f7)](https://www.codacy.com/app/fabiojose/sdk-javascript?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=cloudevents/sdk-javascript&amp;utm_campaign=Badge_Grade)
[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/bd66e7c52002481993cd6d610534b0f7)](https://www.codacy.com/app/fabiojose/sdk-javascript?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=cloudevents/sdk-javascript&amp;utm_campaign=Badge_Coverage)
[![Build Status](https://travis-ci.org/cloudevents/sdk-javascript.svg?branch=master)](https://travis-ci.org/cloudevents/sdk-javascript)
[![downloads](https://img.shields.io/npm/dy/cloudevents-sdk.svg)](https://www.npmjs.com/package/cloudevents-sdk)
[![npm version](https://img.shields.io/npm/v/cloudevents-sdk.svg)](https://www.npmjs.com/package/cloudevents-sdk)
[![vulnerabilities](https://snyk.io/test/github/cloudevents/sdk-javascript/badge.svg)](https://snyk.io/test/github/cloudevents/sdk-javascript)
[![licence](https://img.shields.io/github/license/cloudevents/sdk-javascript)](http://www.apache.org/licenses/LICENSE-2.0)


The CloudEvents SDK for JavaScript.

## Status
This module will help you to:

This SDK is still considered a work in progress.
* Represent CloudEvents in memory
* Use [Event Formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format) to serialize/deserialize CloudEvents
* Use [Protocol Bindings](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding) to send/receive CloudEvents

This SDK current supports the following versions of CloudEvents:
_Note:_ Supported
[CloudEvents specification](https://github.com/cloudevents/spec): 0.3, 1.0

- v1.0
### A Note on Versioning

**Checkout the [changelog](CHANGELOG.md) to see what's going on!**
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.

## Installation
## Usage

This CloudEvents SDK requires nodejs 6.11+
**See the full working example: [here](./examples/express-ex).**

### Nodejs
### Installation

```sh
npm install cloudevents-sdk
```
## Specification Support

These are the supported specifications by this version.

| **Specifications** | v0.3 | **v1.0** |
|---------------------------------------|------|----------|
| 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.3 | **v1.0** |
|-------------------------------------|------|----------|
| Create events | yes | yes |
| Emit Structured events over HTTP | yes | yes |
| Emit Binary events over HTTP | yes | yes |
| JSON Event Format | yes | yes |
| Receive Structured events over HTTP | yes | yes |
| Receive Binary events over HTTP | yes | yes |
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:

## How to use

### Usage
```console
npm install --save cloudevents-sdk
```

```js
const v1 = require("cloudevents-sdk/v1");
### Receiving and Emitting Events

/*
* Creating an event
*/
let myevent = v1.event()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");
```
#### Receiving Events

#### Formatting
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 v1 = require("cloudevents-sdk/v1");
const {
CloudEvent,
HTTPReceiever
} = require("cloudevents-sdk");

/*
* Creating an event
*/
let myevent = v1.event()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");
// Create a receiver to accept events over HTTP
const receiver = new HTTPReceiver();

/*
* Format the payload and return it
*/
let formatted = myevent.format();
// 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
#### 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.

```js
const v1 = require("cloudevents-sdk/v1");
const { CloudEvent } = require("cloudevents-sdk");
const { StructuredHTTPEmitter } = require("cloudevents-sdk/v1");

/*
* Creating an event
*/
let myevent = v1.event()
const myevent = new CloudEvent()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");

// The binding configuration using POST
let config = {
const emitter = new StructuredHTTPEmitter({
method: "POST",
url : "https://myserver.com"
};

// The binding instance
let binding = new v1.StructuredHTTPEmitter(config);

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

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

#### Receiving Events

You can choose any framework for port binding. But, use the
StructuredHTTPReceiver or BinaryHTTPReceiver to process the HTTP Payload and
HTTP Headers, extracting the CloudEvents.

:smiley: **Checkout the full working example: [here](./examples/express-ex).**

```js
// some parts were removed //

const v1 = require("cloudevents-sdk/v1");

const receiver = new v1.StructuredHTTPReceiver();

// some parts were removed //

app.post("/", (req, res) => {
try {
let myevent = receiver.parse(req.body, req.headers);

// TODO use the event

res.status(201).send("Event Accepted");

} catch(err) {
// TODO deal with errors
console.error(err);
res.status(415)
.header("Content-Type", "application/json")
.send(JSON.stringify(err));
}
});
```

## Unit Testing

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

```bash
npm test
// Emit the event
emitter.emit(myevent)
```

## The API
## Supported specification features

### `CloudEvent` class

```js
/*
* Format the payload and return an Object.
*/
Object CloudEvent.format()

/*
* Format the payload as String.
*/
String CloudEvent.toString()
```

### `Formatter` classes

Every formatter class must implement these methods to work properly.

```js
/*
* 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.

```js
/*
* The default constructor with Parser as decorator
*/
Parser(Parser)

/*
* 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.

```js
/*
* 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.

```js
/*
* 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.

```js
/*
* 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)
```

## Versioning

- `x.M.p`: where `x` relates to spec version, `M` relates to minor and `p` relates
to fixes. See [semver](https://semver.org/)
| | [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

Expand All @@ -291,3 +108,9 @@ to fixes. See [semver](https://semver.org/)
[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.
Loading

0 comments on commit ff5d965

Please sign in to comment.