8000 Merge pull request #39 from cloudevents/develop · lance/sdk-javascript@b0d6dff · GitHub
[go: up one dir, main page]
Skip to content

Commit b0d6dff

Browse files
fabiojosefabiojose
authored
Merge pull request cloudevents#39 from cloudevents/develop
Support for Spec v1.0
2 parents 0ac40bc + 68ca47c commit b0d6dff

37 files changed

+2556
-679
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ bower_components
3131

3232
# Compiled binary addons (https://nodejs.org/api/addons.html)
3333
build/Release
34+
build/
3435

3536
# Dependency directories
3637
node_modules/
@@ -78,3 +79,5 @@ typings/
7879
# Vim
7980
*.swp
8081

82+
# Package lock
83+
package-lock.json

‎CHANGELOG.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
66

77
## [Unreleased]
88

9+
## [1.0.0]
10+
11+
### Added
12+
13+
- Support for [Spec v1.0](https://github.com/cloudevents/spec/tree/v1.0)
14+
- Typescript types for Spec v1.0: [see an example](./examples/typescript-ex)
15+
16+
### Removed
17+
18+
- Unmarshaller docs from README, moving them to [OLDOCS.md](./OLDOCS.md)
19+
920
## [0.3.2]
1021

1122
### Fixed
@@ -21,6 +32,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
2132
- Fix the `subject` attribute unmarshal error: issue
2233
[#32](https://github.com/cloudevents/sdk-javascript/issues/32)
2334

24-
[Unreleased]: https://github.com/cloudevents/sdk-javascript/compare/v0.3.2...HEAD
35+
[Unreleased]: https://github.com/cloudevents/sdk-javascript/compare/v1.0.0...HEAD
36+
[1.0.0]: https://github.com/cloudevents/sdk-javascript/compare/v0.3.2...v1.0.0
2537
[0.3.2]: https://github.com/cloudevents/sdk-javascript/compare/v0.3.1...v0.3.2
2638
[0.3.1]: https://github.com/cloudevents/sdk-javascript/compare/v0.3.0...v0.3.1

‎OLDOCS.md

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Docs for old spec versions
2+
3+
Here are living the examples of old specs implementations.
4+
5+
## How to use
6+
7+
The `Cloudevent` constructor arguments.
8+
9+
```js
10+
/*
11+
* spec : if is null, set the spec 0.1 impl
12+
* format: if is null, set the JSON Format 0.1 impl
13+
*/
14+
Cloudevent(spec, format);
15+
16+
```
17+
18+
### Usage
19+
20+
```js
21+
var Cloudevent = require("cloudevents-sdk");
22+
23+
var Spec02 = require("cloudevents-sdk/v02");
24+
25+
/*
26+
* Constructs a default instance with:
27+
* - Spec 0.1
28+
* - JSON Format 0.1
29+
*/
30+
var cloudevent01 = new Cloudevent();
31+
32+
/*
33+
* Implemented using Builder Design Pattern
34+
*/
35+
cloudevent01
36+
.type("com.github.pull.create")
37+
.source("urn:event:from:myapi/resourse/123");
38+
39+
/*
40+
* Backward compatibility to spec 0.1 by injecting methods from spec
41+
* implementation to Cloudevent
42+
*/
43+
cloudevent01
44+
.eventTypeVersion("1.0");
45+
46+
/*
47+
* Constructs an instance with:
48+
* - Spec 0.2
49+
* - JSON Format 0.1
50+
*/
51+
var cloudevent02 = new Cloudevent(Cloudevent.specs["0.2"]);
52+
53+
/*
54+
* Different specs, but the same API.
55+
*/
56+
cloudevent02
57+
.type("com.github.pull.create")
58+
.source("urn:event:from:myapi/resourse/123");
59+
60+
```
61+
62+
#### Formatting
63+
64+
```js
65+
var Cloudevent = require("cloudevents-sdk");
66+
67+
/*
68+
* Creates an instance with default spec and format
69+
*/
70+
var cloudevent =
71+
new Cloudevent()
72+
.type("com.github.pull.create")
73+
.source("urn:event:from:myapi/resourse/123");
74+
75+
/*
76+
* Format the payload and return it
77+
*/
78+
var formatted = cloudevent.format();
79+
```
80+
81+
#### Emitting
82+
83+
```js
84+
var Cloudevent = require("cloudevents-sdk");
85+
86+
// The event
87+
var cloudevent =
88+
new Cloudevent()
89+
.type("com.github.pull.create")
90+
.source("urn:event:from:myapi/resourse/123");
91+
92+
// The binding configuration using POST
93+
var config = {
94+
method: "POST",
95+
url : "https://myserver.com"
96+
};
97+
98+
/*
99+
* To use HTTP Binary:
100+
* Cloudevent.bindings["http-binary0.2"](config);
101+
*/
102+
103+
// The binding instance
104+
var binding = new Cloudevent.bindings["http-structured0.1"](config);
105+
106+
// Emit the event using Promise
107+
binding.emit(cloudevent)
108+
.then(response => {
109+
// Treat the response
110+
console.log(response.data);
111+
112+
}).catch(err => {
113+
// Deal with errors
114+
console.error(err);
115+
});
116+
```
117+
118+
#### Receiving Events
119+
120+
You can choose any framework for port binding. But, use the Unmarshaller
121+
to process the HTTP Payload and HTTP Headers, extracting the CloudEvents.
122+
123+
The Unmarshaller will parse the HTTP Request and decides if it is a binary
124+
or a structured version of transport binding.
125+
126+
:smiley: **Checkout the full working example: [here](./examples/express-ex).**
127+
128+
```js
129+
// some parts were removed //
130+
131+
const v02 = require("cloudevents-sdk/v02");
132+
const unmarshaller = new v02.HTTPUnmarshaller();
133+
134+
// some parts were removed //
135+
136+
app.post('/', function (req, res) {
137+
unmarshaller.unmarshall(req.body, req.headers)
138+
.then(cloudevent => {
139+
140+
// TODO use the cloudevent
141+
142+
res.status(201)
143+
.send("Event Accepted");
144+
})
145+
.catch(err => {
146+
console.error(err);
147+
res.status(415)
148+
.header("Content-Type", "application/json")
149+
.send(JSON.stringify(err));
150+
});
151+
});
152+
```
153+
154+
## The API
155+
156+
### `Unmarshaller` classes
157+
158+
The Unmarshaller classes uses the receiver API, abstracting the formats:
159+
160+
- structured
161+
- binary
162+
163+
Choosing the right implementation based on the `headers` map.
164+
165+
```js
166+
/*
167+
* Constructor without arguments
168+
*/
169+
Unmarshaller()
170+
171+
/*
172+
* The method to unmarshall the payload.
173+
* @arg payload could be a string or a object
174+
* @arg headers a map of headers
175+
*/
176+
Promise Unmarshaller.unmarshall(payload, headers)
177+
```

0 commit comments

Comments
 (0)
0