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.

Fixes: cloudevents#128

Signed-off-by: Lance Ball <lball@redhat.com>
  • Loading branch information
@lance
lance committed May 8, 2020
1 parent c1fda94 commit 424cfb0
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 339 deletions.
275 changes: 48 additions & 227 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,28 +11,9 @@

The CloudEvents SDK for JavaScript.

## Status
## CloudEvents Specification Support

This SDK is still considered a work in progress.

This SDK current supports the following versions of CloudEvents:

- v1.0

**Checkout the [changelog](CHANGELOG.md) to see what's going on!**

## Installation

This CloudEvents SDK requires nodejs 6.11+

### Nodejs

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

These are the supported specifications by this version.
This SDK supports the 0.3 and 1.0 versions of the CloudEvents specification:

| **Specifications** | v0.3 | **v1.0** |
|---------------------------------------|------|----------|
Expand All @@ -41,244 +22,78 @@ These are the supported specifications by this version.
| HTTP Transport Binding - Binary | yes | yes |
| JSON Event Format | yes | yes |

### What we can do

| **What** | v0.3 | **v1.0** |
| **Capabilities** | 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 |

## How to use
### A Note on Versioning

### Usage
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.

```js
const v1 = require("cloudevents-sdk/v1");
## Usage

/*
* Creating an event
*/
let myevent = v1.event()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");
```
**See the full working example: [here](./examples/express-ex).**

#### Formatting

```js
const v1 = require("cloudevents-sdk/v1");
### Installation

/*
* Creating an event
*/
let myevent = v1.event()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");
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:

/*
* Format the payload and return it
*/
let formatted = myevent.format();
```console
npm install --save cloudevents-sdk
```

#### Emitting

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

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

// The binding configuration using POST
let config = {
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 and Emitting Events

#### 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
```

## The API

### `CloudEvent` class
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
/*
* Format the payload and return an Object.
*/
Object CloudEvent.format()

/*
* Format the payload as String.
*/
String CloudEvent.toString()
```
const {
CloudEvent,
HTTPReceiever
} = require("cloudevents-sdk");

### `Formatter` classes
// Create a receiver to accept events over HTTP
const receiver = new HTTPReceiver();

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)
// 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());
```

### `Spec` classes
#### Emitting Events

Every Spec class must implement these methods to work properly.
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
/*
* 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)
```
const { CloudEvent } = require("cloudevents-sdk");
const { StructuredHTTPEmitter } = require("cloudevents-sdk/v1");

### `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)
const myevent = new CloudEvent()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resource/123");

/*
* Checks if some Object and a Map of headers
* follows the binding definition, throwing an error if did not follow
*/
Receiver.check(Object, Map)
const emitter = new StructuredHTTPEmitter({
method: "POST",
url : "https://myserver.com"
});

/*
* Checks and parse as CloudEvent
*/
CloudEvent Receiver.parse(Object, Map)
// Emit the event
emitter.emit(myevent)
```

## Versioning

- `x.M.p`: where `x` relates to spec version, `M` relates to minor and `p` relates
to fixes. See [semver](https://semver.org/)

## Community

- There are bi-weekly calls immediately following the [Serverless/CloudEvents
Expand All @@ -291,3 +106,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 424cfb0

Please sign in to comment.