Skip to content

Commit b866edd

Browse files
lancelance
authored
docs: update README and examples with new API (#138)
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: #128 Signed-off-by: Lance Ball <[email protected]>
1 parent 5a6cde5 commit b866edd

File tree

4 files changed

+85
-349
lines changed

4 files changed

+85
-349
lines changed

‎README.md

Lines changed: 60 additions & 237 deletions
Original file line numberDiff line numberDiff line change
@@ -3,281 +3,98 @@
33
[![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)
44
[![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)
55
[![Build Status](https://travis-ci.org/cloudevents/sdk-javascript.svg?branch=master)](https://travis-ci.org/cloudevents/sdk-javascript)
6-
[![downloads](https://img.shields.io/npm/dy/cloudevents-sdk.svg)](https://www.npmjs.com/package/cloudevents-sdk)
76
[![npm version](https://img.shields.io/npm/v/cloudevents-sdk.svg)](https://www.npmjs.com/package/cloudevents-sdk)
87
[![vulnerabilities](https://snyk.io/test/github/cloudevents/sdk-javascript/badge.svg)](https://snyk.io/test/github/cloudevents/sdk-javascript)
98
[![licence](https://img.shields.io/github/license/cloudevents/sdk-javascript)](http://www.apache.org/licenses/LICENSE-2.0)
109

1110

1211
The CloudEvents SDK for JavaScript.
1312

14-
## Status
13+
This module will help you to:
1514

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

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

20-
- v1.0
22+
### A Note on Versioning
2123

22-
**Checkout the [changelog](CHANGELOG.md) to see what's going on!**
24+
The CloudEvents protocol version is distinct from this module's version number.
25+
For example, this module may be versioned as v2.0.0 but support the v0.3 and v1.0
26+
versions of the CloudEvent specification.
2327

24-
## Installation
28+
## Usage
2529

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

28-
### Nodejs
32+
### Installation
2933

30-
```sh
31-
npm install cloudevents-sdk
32-
```
33-
## Specification Support
34-
35-
These are the supported specifications by this version.
36-
37-
| **Specifications** | v0.3 | **v1.0** |
38-
|---------------------------------------|------|----------|
39-
| CloudEvents | yes | yes |
40-
| HTTP Transport Binding - Structured | yes | yes |
41-
| HTTP Transport Binding - Binary | yes | yes |
42-
| JSON Event Format | yes | yes |
43-
44-
### What we can do
45-
46-
| **What** | v0.3 | **v1.0** |
47-
|-------------------------------------|------|----------|
48-
| Create events | yes | yes |
49-
| Emit Structured events over HTTP | yes | yes |
50-
| Emit Binary events over HTTP | yes | yes |
51-
| JSON Event Format | yes | yes |
52-
| Receive Structured events over HTTP | yes | yes |
53-
| Receive Binary events over HTTP | yes | yes |
34+
The CloudEvents SDK requires a current LTS version of Node.js. At the moment
35+
those are Node.js 10.x and Node.js 12.x. To install in your Node.js project:
5436

55-
## How to use
56-
57-
### Usage
37+
```console
38+
npm install --save cloudevents-sdk
39+
```
5840

59-
```js
60-
const v1 = require("cloudevents-sdk/v1");
41+
### Receiving and Emitting Events
6142

62-
/*
63-
* Creating an event
64-
*/
65-
let myevent = v1.event()
66-
.type("com.github.pull.create")
67-
.source("urn:event:from:myapi/resource/123");
68-
```
43+
#### Receiving Events
6944

70-
#### Formatting
45+
You can choose almost any popular web framework for port binding. Use an
46+
`HTTPReceiver` to process the incoming HTTP request. The receiver accepts
47+
binary and structured events in either the 1.0 or 0.3 protocol formats.
7148

7249
```js
73-
const v1 = require("cloudevents-sdk/v1");
50+
const {
51+
CloudEvent,
52+
HTTPReceiever
53+
} = require("cloudevents-sdk");
7454

75-
/*
76-
* Creating an event
77-
*/
78-
let myevent = v1.event()
79-
.type("com.github.pull.create")
80-
.source("urn:event:from:myapi/resource/123");
55+
// Create a receiver to accept events over HTTP
56+
const receiver = new HTTPReceiver();
8157

82-
/*
83-
* Format the payload and return it
84-
*/
85-
let formatted = myevent.format();
58+
// body and headers come from an incoming HTTP request, e.g. express.js
59+
const receivedEvent = receiver.accept(req.body, req.headers);
60+
console.log(receivedEvent.format());
8661
```
8762

88-
#### Emitting
63+
#### Emitting Events
64+
65+
Currently, to emit events, you'll need to decide whether the event is in
66+
binary or structured format, and determine what version of the CloudEvents
67+
specification you want to send the event as.
8968

9069
```js
91-
const v1 = require("cloudevents-sdk/v1");
70+
const { CloudEvent } = require("cloudevents-sdk");
71+
const { StructuredHTTPEmitter } = require("cloudevents-sdk/v1");
9272

93-
/*
94-
* Creating an event
95-
*/
96-
let myevent = v1.event()
73+
const myevent = new CloudEvent()
9774
.type("com.github.pull.create")
9875
.source("urn:event:from:myapi/resource/123");
9976

100-
// The binding configuration using POST
101-
let config = {
77+
const emitter = new StructuredHTTPEmitter({
10278
method: "POST",
10379
url : "https://myserver.com"
104-
};
105-
106-
// The binding instance
107-
let binding = new v1.StructuredHTTPEmitter(config);
108-
109-
// Emit the event using Promise
110-
binding.emit(myevent)
111-
.then(response => {
112-
// Treat the response
113-
console.log(response.data);
114-
115-
}).catch(err => {
116-
// Deal with errors
117-
console.error(err);
118-
});
119-
```
120-
121-
#### Receiving Events
122-
123-
You can choose any framework for port binding. But, use the
124-
StructuredHTTPReceiver or BinaryHTTPReceiver to process the HTTP Payload and
125-
HTTP Headers, extracting the CloudEvents.
126-
127-
:smiley: **Checkout the full working example: [here](./examples/express-ex).**
128-
129-
```js
130-
// some parts were removed //
131-
132-
const v1 = require("cloudevents-sdk/v1");
133-
134-
const receiver = new v1.StructuredHTTPReceiver();
135-
136-
// some parts were removed //
137-
138-
app.post("/", (req, res) => {
139-
try {
140-
let myevent = receiver.parse(req.body, req.headers);
141-
142-
// TODO use the event
143-
144-
res.status(201).send("Event Accepted");
145-
146-
} catch(err) {
147-
// TODO deal with errors
148-
console.error(err);
149-
res.status(415)
150-
.header("Content-Type", "application/json")
151-
.send(JSON.stringify(err));
152-
}
15380
});
154-
```
155-
156-
## Unit Testing
157-
158-
The unit test checks the result of formatted payload and the constraints.
15981

160-
```bash
161-
npm test
82+
// Emit the event
83+
emitter.emit(myevent)
16284
```
16385

164-
## The API
86+
## Supported specification features
16587

166-
### `CloudEvent` class
167-
168-
```js
169-
/*
170-
* Format the payload and return an Object.
171-
*/
172-
Object CloudEvent.format()
173-
174-
/*
175-
* Format the payload as String.
176-
*/
177-
String CloudEvent.toString()
178-
```
179-
180-
### `Formatter` classes
181-
182-
Every formatter class must implement these methods to work properly.
183-
184-
```js
185-
/*
186-
* Format the CloudEvent payload argument and return an Object.
187-
*/
188-
Object Formatter.format(Object)
189-
190-
/*
191-
* Format the CloudEvent payload as String.
192-
*/
193-
String Formatter.toString(Object)
194-
```
195-
196-
### `Parser` classes
197-
198-
Every Parser class must implement these methods to work properly.
199-
200-
```js
201-
/*
202-
* The default constructor with Parser as decorator
203-
*/
204-
Parser(Parser)
205-
206-
/*
207-
* Try to parse the payload to some event format
208-
*/
209-
Object Parser.parse(payload)
210-
```
211-
212-
### `Spec` classes
213-
214-
Every Spec class must implement these methods to work properly.
215-
216-
```js
217-
/*
218-
* The constructor must receives the CloudEvent type.
219-
*/
220-
Spec(CloudEvent)
221-
222-
/*
223-
* Checks the spec constraints, throwing an error if do not pass.
224-
* @throws Error when it is an invalid event
225-
*/
226-
Spec.check()
227-
228-
/*
229-
* Checks if the argument pass through the spec constraints
230-
* @throws Error when it is an invalid event
231-
*/
232-
Spec.check(Object)
233-
```
234-
235-
### `Binding` classes
236-
237-
Every Binding class must implement these methods to work properly.
238-
239-
#### Emitter Binding
240-
241-
Following we have the signature for the binding to emit CloudEvents.
242-
243-
```js
244-
/*
245-
* The constructor must receives the map of configurations.
246-
*/
247-
Binding(config)
248-
249-
/*
250-
* Emits the event using an instance of CloudEvent.
251-
*/
252-
Binding.emit(cloudEvent)
253-
```
254-
255-
#### Receiver Binding
256-
257-
Following we have the signature for the binding to receive CloudEvents.
258-
259-
```js
260-
/*
261-
* The constructor must receives the map of configurations.
262-
*/
263-
Receiver(config)
264-
265-
/*
266-
* Checks if some Object and a Map of headers
267-
* follows the binding definition, throwing an error if did not follow
268-
*/
269-
Receiver.check(Object, Map)
270-
271-
/*
272-
* Checks and parse as CloudEvent
273-
*/
274-
CloudEvent Receiver.parse(Object, Map)
275-
```
276-
277-
## Versioning
278-
279-
- `x.M.p`: where `x` relates to spec version, `M` relates to minor and `p` relates
280-
to fixes. See [semver](https://semver.org/)
88+
| | [v0.3](https://github.com/cloudevents/spec/tree/v0.3) | [v1.0](https://github.com/cloudevents/spec/tree/v1.0) |
89+
| ----------------------------- | --- | --- |
90+
| CloudEvents Core | :heavy_check_mark: | :heavy_check_mark: |
91+
| AMQP Protocol Binding | :x: | :x: |
92+
| AVRO Event Format | :x: | :x: |
93+
| HTTP Protocol Binding | :heavy_check_mark: | :heavy_check_mark: |
94+
| JSON Event Format | :heavy_check_mark: | :heavy_check_mark: |
95+
| Kafka Protocol Binding | :x: | :x: |
96+
| NATS Protocol Binding | :x: | :x: |
97+
| STAN Protocol Binding | :x: | :x: |
28198

28299
## Community
283100

@@ -291,3 +108,9 @@ to fixes. See [semver](https://semver.org/)
291108
[CNCF's Slack workspace](https://slack.cncf.io/).
292109
- Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
293110
- Contact for additional information: Fabio José (`@fabiojose` on slack).
111+
112+
## Contributing
113+
114+
We love contributions from the community! Please check the
115+
[Contributor's Guide](https://github.com/cloudevents/sdk-javascript/blob/master/CONTRIBUTING.md)
116+
for information on how to get involved.

0 commit comments

Comments
 (0)