cloudevents
/
sdk-javascript
mirror of https://github.com/cloudevents/sdk-javascript.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the examples to v1 

Signed-off-by: Fabio José <fabiojose@gmail.com>
This commit is contained in:
Fabio José 2019-11-06 10:49:51 -03:00
parent 6600663993
commit c7cfa46e9d
1 changed files with 64 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
README.md
View File

@ -28,40 +28,35 @@ To see working examples, point to [examples](./examples).
## :newspaper: Newsletter :newspaper: ## :newspaper: Newsletter :newspaper:
> all the API developed before, for 0.1 and 0.2, works as the same. > all the API developed before, for 0.1, 0.2 and 0.3, works as the same.
Checkout the new expressive additions. Checkout the new expressive additions.
### New way to import the specifications stuff ### Use typed CloudEvents with Typescript
```js > There is full example: [typescript-ex](,/examples/typescript-ex)
// Import the v0.3 stuff
const v03 = require("cloudevents-sdk/v03");
// Access the spec ```ts
v03.Spec; import Cloudevent, {
event,
StructuredHTTPEmitter,
BinaryHTTPEmitter,
// Access the structured http event emitter StructuredHTTPReceiver,
v03.StructuredHTTPEmitter; BinaryHTTPReceiver
} from 'cloudevents-sdk/v1';
// Access the binary http event emitter let myevent: Cloudevent = event()
v03.BinaryHTTPEmitter; .source('/source')
.type('type')
.dataContentType('text/plain')
.dataschema('http://d.schema.com/my.json')
.subject('cha.json')
.data('my-data')
.addExtension("my-ext", "0x600");
// Access http unmarshaller to process incoming events, Binary or Structured // . . .
v03.HTTPUnmarshaller;
```
### An easy way to create events
```js
// Import the v0.3 stuff
const v03 = require("cloudevents-sdk/v03");
// Creates an event using the v0.3 spec
let ce =
v03.event()
.type("com.github.pull.create")
.source("urn:event:from:myapi/resourse/123");
``` ```
## Versioning ## Versioning
@ -89,26 +84,28 @@ npm install cloudevents-sdk
These are the supported specifications by this version. These are the supported specifications by this version.
| **Specifications** | **v0.1** | **v0.2** | **v0.3** | | **Specifications** | v0.1 | v0.2 | v0.3 | **v1.0** |
|---------------------------------------|----------|----------|----------| |---------------------------------------|------|------|------|----------|
| CloudEvents | yes | yes | yes | | CloudEvents | yes | yes | yes | yes |
| HTTP Transport Binding - Structured | yes | yes | yes | | HTTP Transport Binding - Structured | yes | yes | yes | yes |
| HTTP Transport Binding - Binary | yes | yes | yes | | HTTP Transport Binding - Binary | yes | yes | yes | yes |
| JSON Event Format | yes | yes | yes | | JSON Event Format | yes | yes | yes | yes |
### What we can do ### What we can do
| **What** | **v0.1** | **v0.2** | **v0.3** | | **What** | v0.1 | v0.2 | v0.3 | **v1.0** |
|-------------------------------------|----------|----------|----------| |-------------------------------------|--------|------|------|----------|
| Create events | yes | yes | yes | | Create events | yes | yes | yes | yes |
| Emit Structured events over HTTP | yes | yes | yes | | Emit Structured events over HTTP | yes | yes | yes | yes |
| Emit Binary events over HTTP | yes | yes | yes | | Emit Binary events over HTTP | yes | yes | yes | yes |
| JSON Event Format | yes | yes | yes | | JSON Event Format | yes | yes | yes | yes |
| Receice Structured events over HTTP | no | yes | yes | | Receice Structured events over HTTP | **no** | yes | yes | yes |
| Receice Binary events over HTTP | no | yes | yes | | Receice Binary events over HTTP | **no** | yes | yes | yes |
## How to use ## How to use
> If you want old examples, they are [here](./OLDOCS.md)
The `Cloudevent` constructor arguments. The `Cloudevent` constructor arguments.
```js ```js
@ -123,93 +120,57 @@ Cloudevent(spec, format);
### Usage ### Usage
```js ```js
var Cloudevent = require("cloudevents-sdk"); const v1 = require("cloudevents-sdk/v1");
var Spec02 = require("cloudevents-sdk/v02");
/* /*
* Constructs a default instance with: * Creating an event
* - Spec 0.1
* - JSON Format 0.1
*/ */
var cloudevent01 = new Cloudevent(); let myevent = v1.event()
/*
* Implemented using Builder Design Pattern
*/
cloudevent01
.type("com.github.pull.create") .type("com.github.pull.create")
.source("urn:event:from:myapi/resourse/123"); .source("urn:event:from:myapi/resourse/123");
/*
* Backward compatibility to spec 0.1 by injecting methods from spec
* implementation to Cloudevent
*/
cloudevent01
.eventTypeVersion("1.0");
/*
* Constructs an instance with:
* - Spec 0.2
* - JSON Format 0.1
*/
var cloudevent02 = new Cloudevent(Cloudevent.specs["0.2"]);
/*
* Different specs, but the same API.
*/
cloudevent02
.type("com.github.pull.create")
.source("urn:event:from:myapi/resourse/123");
``` ```
#### Formatting #### Formatting
```js ```js
var Cloudevent = require("cloudevents-sdk"); const v1 = require("cloudevents-sdk/v1");
/* /*
* Creates an instance with default spec and format * Creating an event
*/ */
var cloudevent = let myevent = v1.event()
new Cloudevent() .type("com.github.pull.create")
.type("com.github.pull.create") .source("urn:event:from:myapi/resourse/123");
.source("urn:event:from:myapi/resourse/123");
/* /*
* Format the payload and return it * Format the payload and return it
*/ */
var formatted = cloudevent.format(); let formatted = myevent.format();
``` ```
#### Emitting #### Emitting
```js ```js
var Cloudevent = require("cloudevents-sdk"); const v1 = require("cloudevents-sdk/v1");
// The event /*
var cloudevent = * Creating an event
new Cloudevent() */
.type("com.github.pull.create") let myevent = v1.event()
.source("urn:event:from:myapi/resourse/123"); .type("com.github.pull.create")
.source("urn:event:from:myapi/resourse/123");
// The binding configuration using POST // The binding configuration using POST
var config = { let config = {
method: "POST", method: "POST",
url : "https://myserver.com" url : "https://myserver.com"
}; };
/*
* To use HTTP Binary:
* Cloudevent.bindings["http-binary0.2"](config);
*/
// The binding instance // The binding instance
var binding = new Cloudevent.bindings["http-structured0.1"](config); let binding = new v1.StructuredHTTPEmitter(config);
// Emit the event using Promise // Emit the event using Promise
binding.emit(cloudevent) binding.emit(myevent)
.then(response => { .then(response => {
// Treat the response // Treat the response
console.log(response.data); console.log(response.data);
@ -219,27 +180,26 @@ binding.emit(cloudevent)
console.error(err); console.error(err);
}); });
``` ```
#### Receiving Events #### Receiving Events
You can choose any framework for port binding. But, use the Unmarshaller You can choose any framework for port binding. But, use the
to process the HTTP Payload and HTTP Headers, extracting the CloudEvents. StructuredHTTPReceiver or BinaryHTTPReceiver to process the HTTP Payload and
HTTP Headers, extracting the CloudEvents.
The Unmarshaller will parse the HTTP Request and decides if it is a binary
or a structured version of transport binding.
:smiley: **Checkout the full working example: [here](./examples/express-ex).** :smiley: **Checkout the full working example: [here](./examples/express-ex).**
```js ```js
// some parts were removed // // some parts were removed //
const v02 = require("cloudevents-sdk/v02"); const v1 = require("cloudevents-sdk/v1");
const unmarshaller = new v02.HTTPUnmarshaller(); const receiver = new v1.StructuredHTTPReceiver();
// some parts were removed // // some parts were removed //
app.post('/', function (req, res) { app.post("/", function (req, res) {
unmarshaller.unmarshall(req.body, req.headers) receiver.parse(req.body, req.headers)
.then(cloudevent => { .then(myevent => {
// TODO use the cloudevent // TODO use the cloudevent
@ -253,8 +213,6 @@ app.post('/', function (req, res) {
.send(JSON.stringify(err)); .send(JSON.stringify(err));
}); });
}); });
``` ```
## Repository Structure ## Repository Structure
@ -409,29 +367,6 @@ Receiver.check(Object, Map)
Cloudevent Receiver.parse(Object, Map) Cloudevent Receiver.parse(Object, Map)
``` ```
### `Unmarshaller` classes
The Unmarshaller classes uses the receiver API, abstracting the formats:
- structured
- binary
Choosing the right implementation based on the `headers` map.
```js
/*
* Constructor without arguments
*/
Unmarshaller()
/*
* The method to unmarshall the payload.
* @arg payload could be a string or a object
* @arg headers a map of headers
*/
Promise Unmarshaller.unmarshall(payload, headers)
```
> See how to implement the method injection [here](lib/specs/spec_0_1.js#L17) > See how to implement the method injection [here](lib/specs/spec_0_1.js#L17)
> >
> Learn about [Builder Design Pattern](https://en.wikipedia.org/wiki/Builder_pattern) > Learn about [Builder Design Pattern](https://en.wikipedia.org/wiki/Builder_pattern)