279 lines
12 KiB
HTML
279 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>
|
|
Home - Documentation
|
|
</title>
|
|
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.7.0/highlight.min.js"></script>
|
|
<script>hljs.initHighlightingOnLoad();</script>
|
|
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
|
|
|
|
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
|
|
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
|
|
|
|
<link type="text/css" rel="stylesheet" href="styles/collapse.css">
|
|
|
|
|
|
|
|
</head>
|
|
|
|
<body>
|
|
<svg style="display: none;">
|
|
<defs>
|
|
<symbol id="linkIcon" fill="#706d77" height="24" viewBox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg">
|
|
<path d="M0 0h24v24H0z" fill="none"/>
|
|
<path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/>
|
|
</symbol>
|
|
</defs>
|
|
</svg>
|
|
|
|
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
|
|
<label for="nav-trigger" class="navicon-button x">
|
|
<div class="navicon"></div>
|
|
</label>
|
|
|
|
<label for="nav-trigger" class="overlay"></label>
|
|
|
|
<div class="top-nav-wrapper">
|
|
<ul>
|
|
<li class="active" >
|
|
<a href="index.html">
|
|
|
|
|
|
<svg fill="#0095dd" height="24" viewBox="0 0 24 24" width="24" xmlns="http://www.w3.org/2000/svg">
|
|
<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
|
|
<path d="M0 0h24v24H0z" fill="none"/>
|
|
</svg>
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
<nav>
|
|
<h3 class="reference-title">
|
|
cloudevents-sdk
|
|
</h3>
|
|
|
|
|
|
<h3>
|
|
Resources
|
|
</h3>
|
|
|
|
<a href="concepts.html">Concepts</a>
|
|
|
|
|
|
|
|
<h3>Classes</h3><ul><li id="BinaryHTTPEmitter-nav"><a href="BinaryHTTPEmitter.html">BinaryHTTPEmitter</a><ul class='methods'><li data-type="method" id="BinaryHTTPEmitter-emit-nav"><a href="BinaryHTTPEmitter.html#emit">emit</a></li></ul></li><li id="BinaryHTTPReceiver-nav"><a href="BinaryHTTPReceiver.html">BinaryHTTPReceiver</a><ul class='methods'><li data-type="method" id="BinaryHTTPReceiver-check-nav"><a href="BinaryHTTPReceiver.html#check">check</a></li><li data-type="method" id="BinaryHTTPReceiver-parse-nav"><a href="BinaryHTTPReceiver.html#parse">parse</a></li></ul></li><li id="CloudEvent-nav"><a href="CloudEvent.html">CloudEvent</a><ul class='methods'><li data-type="method" id="CloudEvent-addExtension-nav"><a href="CloudEvent.html#addExtension">addExtension</a></li><li data-type="method" id="CloudEvent-format-nav"><a href="CloudEvent.html#format">format</a></li><li data-type="method" id="CloudEvent-getExtensions-nav"><a href="CloudEvent.html#getExtensions">getExtensions</a></li><li data-type="method" id="CloudEvent-toString-nav"><a href="CloudEvent.html#toString">toString</a></li></ul></li><li id="HTTPEmitter-nav"><a href="HTTPEmitter.html">HTTPEmitter</a><ul class='methods'><li data-type="method" id="HTTPEmitter-headers-nav"><a href="HTTPEmitter.html#headers">headers</a></li><li data-type="method" id="HTTPEmitter-send-nav"><a href="HTTPEmitter.html#send">send</a></li></ul></li><li id="HTTPReceiver-nav"><a href="HTTPReceiver.html">HTTPReceiver</a><ul class='methods'><li data-type="method" id="HTTPReceiver-accept-nav"><a href="HTTPReceiver.html#accept">accept</a></li></ul></li><li id="StructuredHTTPEmitter-nav"><a href="StructuredHTTPEmitter.html">StructuredHTTPEmitter</a><ul class='methods'><li data-type="method" id="StructuredHTTPEmitter-emit-nav"><a href="StructuredHTTPEmitter.html#emit">emit</a></li></ul></li><li id="StructuredHTTPReceiver-nav"><a href="StructuredHTTPReceiver.html">StructuredHTTPReceiver</a><ul class='methods'><li data-type="method" id="StructuredHTTPReceiver-check-nav"><a href="StructuredHTTPReceiver.html#check">check</a></li><li data-type="method" id="StructuredHTTPReceiver-parse-nav"><a href="StructuredHTTPReceiver.html#parse">parse</a></li></ul></li><li id="ValidationError-nav"><a href="ValidationError.html">ValidationError</a></li></ul><h3 id="global-nav">Global</h3><ul><li><a href="global.html#headerMap">headerMap</a></li></ul>
|
|
</nav>
|
|
|
|
<div id="main">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section class="readme">
|
|
<article>
|
|
<h1>JavaScript SDK for CloudEvents</h1>
|
|
<p><a href="https://www.codacy.com/app/fabiojose/sdk-javascript?utm_source=github.com&utm_medium=referral&utm_content=cloudevents/sdk-javascript&utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/bd66e7c52002481993cd6d610534b0f7" alt="Codacy Badge"></a>
|
|
<a href="https://www.codacy.com/app/fabiojose/sdk-javascript?utm_source=github.com&utm_medium=referral&utm_content=cloudevents/sdk-javascript&utm_campaign=Badge_Coverage"><img src="https://api.codacy.com/project/badge/Coverage/bd66e7c52002481993cd6d610534b0f7" alt="Codacy Badge"></a>
|
|
<a href="https://travis-ci.org/cloudevents/sdk-javascript"><img src="https://travis-ci.org/cloudevents/sdk-javascript.svg?branch=master" alt="Build Status"></a>
|
|
<a href="https://www.npmjs.com/package/cloudevents-sdk"><img src="https://img.shields.io/npm/v/cloudevents-sdk.svg" alt="npm version"></a>
|
|
<a href="https://snyk.io/test/github/cloudevents/sdk-javascript"><img src="https://snyk.io/test/github/cloudevents/sdk-javascript/badge.svg" alt="vulnerabilities"></a>
|
|
<a href="http://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/github/license/cloudevents/sdk-javascript" alt="licence"></a></p>
|
|
<p>The CloudEvents SDK for JavaScript.</p>
|
|
<p>This module will help you to:</p>
|
|
<ul>
|
|
<li>Represent CloudEvents in memory</li>
|
|
<li>Use <a href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format">Event Formats</a> to serialize/deserialize CloudEvents</li>
|
|
<li>Use <a href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding">Protocol Bindings</a> to send/receive CloudEvents</li>
|
|
</ul>
|
|
<p><em>Note:</em> Supported
|
|
<a href="https://github.com/cloudevents/spec">CloudEvents specification</a>: 0.3, 1.0</p>
|
|
<h3>A Note on Versioning</h3>
|
|
<p>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.</p>
|
|
<h2>Usage</h2>
|
|
<p><strong>See the full working example: <a href="./examples/express-ex">here</a>.</strong></p>
|
|
<h3>Installation</h3>
|
|
<p>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:</p>
|
|
<pre class="prettyprint source lang-console"><code>npm install --save cloudevents-sdk
|
|
</code></pre>
|
|
<h3>Receiving and Emitting Events</h3>
|
|
<h4>Receiving Events</h4>
|
|
<p>You can choose almost any popular web framework for port binding. Use an
|
|
<code>HTTPReceiver</code> to process the incoming HTTP request. The receiver accepts
|
|
binary and structured events in either the 1.0 or 0.3 protocol formats.</p>
|
|
<pre class="prettyprint source lang-js"><code>const {
|
|
CloudEvent,
|
|
HTTPReceiever
|
|
} = require("cloudevents-sdk");
|
|
|
|
// Create a receiver to accept events over HTTP
|
|
const receiver = new HTTPReceiver();
|
|
|
|
// 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());
|
|
</code></pre>
|
|
<h4>Emitting Events</h4>
|
|
<p>To emit events, you'll need to decide whether the event should be sent in
|
|
binary or structured format, and determine what version of the CloudEvents
|
|
specification you want to send the event as.</p>
|
|
<p>By default, the <code>HTTPEmitter</code> will emit events over HTTP POST using the
|
|
1.0 specification, in binary mode. You can emit 0.3 events by providing
|
|
the specication version in the constructor to <code>HTTPEmitter</code>. To send
|
|
structured events, add that string as a parameter to <code>emitter.sent()</code>.</p>
|
|
<pre class="prettyprint source lang-js"><code>const { CloudEvent, HTTPEmitter } = require("cloudevents-sdk");
|
|
|
|
// With only an endpoint URL, this creates a v1 emitter
|
|
const v1Emitter = new HTTPEmitter({
|
|
url: "https://cloudevents.io/example"
|
|
});
|
|
const event = new CloudEvent({
|
|
type, source, data
|
|
});
|
|
|
|
// By default, the emitter will send binary events
|
|
v1Emitter.send(event).then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
// To send a structured event, just add that as an option
|
|
v1Emitter.send(event, { mode: "structured" })
|
|
.then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
// To send an event to an alternate URL, add that as an option
|
|
v1Emitter.send(event, { url: "https://alternate.com/api" })
|
|
.then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
// Sending a v0.3 event works the same, just let the emitter know when
|
|
// you create it that you are working with the 0.3 spec
|
|
const v03Emitter = new HTTPEmitter({
|
|
url: "https://cloudevents.io/example",
|
|
version: "0.3"
|
|
});
|
|
|
|
// Again, the default is to send binary events
|
|
// To send a structured event or to an alternate URL, provide those
|
|
// as parameters in a options object as above
|
|
v3Emitter.send(event)
|
|
.then((response) => {
|
|
// handle the response
|
|
}).catch(console.error);
|
|
|
|
</code></pre>
|
|
<h2>Supported specification features</h2>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th></th>
|
|
<th><a href="https://github.com/cloudevents/spec/tree/v0.3">v0.3</a></th>
|
|
<th><a href="https://github.com/cloudevents/spec/tree/v1.0">v1.0</a></th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>CloudEvents Core</td>
|
|
<td>:heavy_check_mark:</td>
|
|
<td>:heavy_check_mark:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>AMQP Protocol Binding</td>
|
|
<td>:x:</td>
|
|
<td>:x:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>AVRO Event Format</td>
|
|
<td>:x:</td>
|
|
<td>:x:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HTTP Protocol Binding</td>
|
|
<td>:heavy_check_mark:</td>
|
|
<td>:heavy_check_mark:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>JSON Event Format</td>
|
|
<td>:heavy_check_mark:</td>
|
|
<td>:heavy_check_mark:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Kafka Protocol Binding</td>
|
|
<td>:x:</td>
|
|
<td>:x:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>NATS Protocol Binding</td>
|
|
<td>:x:</td>
|
|
<td>:x:</td>
|
|
</tr>
|
|
<tr>
|
|
<td>STAN Protocol Binding</td>
|
|
<td>:x:</td>
|
|
<td>:x:</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h2>Community</h2>
|
|
<ul>
|
|
<li>There are bi-weekly calls immediately following the <a href="https://github.com/cloudevents/spec#meeting-time">Serverless/CloudEvents
|
|
call</a> at
|
|
9am PT (US Pacific). Which means they will typically start at 10am PT, but
|
|
if the other call ends early then the SDK call will start early as well.
|
|
See the <a href="https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#">CloudEvents meeting minutes</a>
|
|
to determine which week will have the call.</li>
|
|
<li>Slack: #cloudeventssdk channel under
|
|
<a href="https://slack.cncf.io/">CNCF's Slack workspace</a>.</li>
|
|
<li>Email: https://lists.cncf.io/g/cncf-cloudevents-sdk</li>
|
|
<li>Contact for additional information: Fabio José (<code>@fabiojose</code> on slack).</li>
|
|
</ul>
|
|
<h2>Contributing</h2>
|
|
<p>We love contributions from the community! Please check the
|
|
<a href="https://github.com/cloudevents/sdk-javascript/blob/master/CONTRIBUTING.md">Contributor's Guide</a>
|
|
for information on how to get involved.</p>
|
|
</article>
|
|
</section>
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<br class="clear">
|
|
|
|
<footer>
|
|
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.4</a>
|
|
</footer>
|
|
|
|
<script src="scripts/linenumber.js"></script>
|
|
<script src="scripts/pagelocation.js"></script>
|
|
|
|
|
|
|
|
</body>
|
|
</html> |