From 093a1c10116d0d447474de2da8afbad8eed31650 Mon Sep 17 00:00:00 2001
From: Ali Ok <aliok@redhat.com>
Date: Fri, 22 May 2020 10:36:22 +0300
Subject: [PATCH 1/6] Add tutorial for writing an event source - easy way

---
 .../writing-event-source-easy-way/README.md   | 305 ++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 docs/eventing/samples/writing-event-source-easy-way/README.md

diff --git a/docs/eventing/samples/writing-event-source-easy-way/README.md b/docs/eventing/samples/writing-event-source-easy-way/README.md
new file mode 100644
index 00000000000..1662161ba72
--- /dev/null
+++ b/docs/eventing/samples/writing-event-source-easy-way/README.md
@@ -0,0 +1,305 @@
+---
+title: "Writing an Event Source using the easy way"
+linkTitle: "Event Source - easy way"
+weight: 10
+type: "docs"
+---
+
+# Introduction
+
+As stated in [tutorial on writing a Source with a Receive Adapter](../writing-receive-adapter-source/README.md), there are multiple ways to 
+create event sources. The way in that tutorial is to create an independent event source that has its own CRD.
+
+In this tutorial though, you will build an event source in Javascript and use it with 
+[ContainerSource](../../../eventing/sources/README.md#meta-sources) and / or [SinkBinding](../../../eventing/sources/README.md#meta-sources).
+
+[ContainerSource](../../../eventing/sources/README.md#meta-sources) is an easy way to turn any dispatcher container into an Event Source. 
+Similarly, another option is using [SinkBinding](../../../eventing/sources/README.md#meta-sources)
+which provides a framework for injecting environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable). 
+
+Code for this tutorial is available at [Github](https://github.com/aliok/node-knative-heartbeat-source).
+
+# Bootstrapping
+
+Create the project and add the dependencies:
+```bash 
+npm init
+npm install cloudevents-sdk --save
+```
+
+## Making use of ContainerSource
+
+`ContainerSource` and `SinkBinding` both work by injecting environment variables to an application. 
+Injected environment variables at minimum contain the URL of a sink that will receive events.
+
+Following example emits an event to the sink every 1000 milliseconds.
+The sink URL to post the events will be made available to the application via the `K_SINK` environment variable by `ContainerSource`. 
+
+```javascript
+// File - index.js
+
+const v1 = require("cloudevents-sdk/v1");
+
+let sinkUrl = process.env['K_SINK'];
+
+console.log("Sink URL is " + sinkUrl);
+
+let config = {
+    method: "POST",
+    url: sinkUrl
+};
+
+// The binding instance
+let binding = new v1.BinaryHTTPEmitter(config);
+
+let eventIndex = 0;
+setInterval(function () {
+    console.log("Emitting event #" + ++eventIndex);
+
+    // create the event
+    let myevent = v1.event()
+        .id('your-event-id')
+        .type("your.event.source.type")
+        .source("urn:event:from:your-api/resource/123")
+        .dataContentType("application/json")
+        .data({"hello": "World " + eventIndex});
+
+    // Emit the event
+    binding.emit(myevent)
+        .then(response => {
+            // Treat the response
+            console.log("Event posted successfully");
+            console.log(response.data);
+        })
+        .catch(err => {
+            // Deal with errors
+            console.log("Error during event post");
+            console.error(err);
+        });
+}, 1000);
+```
+
+```dockerfile 
+// File - Dockerfile
+
+FROM node:10
+WORKDIR /usr/src/app
+COPY package*.json ./
+RUN npm install
+COPY . .
+EXPOSE 8080
+CMD [ "node", "index.js" ]
+
+```
+
+Build and push the image:
+```bash 
+docker build . -t path/to/image/registry/node-knative-heartbeat-source:v1
+docker push path/to/image/registry/node-knative-heartbeat-source:v1 
+```
+
+Create the event display service which simply logs any cloudevents posted to it.
+```bash
+cat <<EOS |kubectl apply -f -
+---
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: event-display
+spec:
+  template:
+    spec:
+      containers:
+        - image: docker run --name event_display --rm -p 8080:8080 docker.io/aliok/event_display-864884f202126ec3150c5fcef437d90c@sha256:93cb4dcda8fee80a1f68662ae6bf20301471b046ede628f3c3f94f39752fbe08
+EOS
+```
+
+Create the `ContainerSource`:
+```bash
+cat <<EOS |kubectl apply -f -
+---
+apiVersion: sources.knative.dev/v1alpha2
+kind: ContainerSource
+metadata:
+  name: test-heartbeats
+spec:
+  template:
+    spec:
+      containers:
+        - image: path/to/image/registry/node-knative-heartbeat-source:v1
+          name: heartbeats
+  sink:
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display
+EOS
+```
+
+Check the logs of the event display service. You will see a new message is pushed every second:
+```bash
+$ kubectl logs event-display-dpplv-deployment-67c9949cf9-bvjvk -c user-container
+
+☁️  cloudevents.Event
+Validation: valid
+Context Attributes,
+  specversion: 1.0
+  type: your.event.source.type
+  source: urn:event:from:your-api/resource/123
+  id: your-event-id
+  datacontenttype: application/json
+Data,
+  {
+    "hello": "World 1"
+  }
+```
+
+If you are interested in to see what is injected into the event source, check the logs of it:
+```bash 
+$ kubectl logs test-heartbeats-deployment-7575c888c7-85w5t 
+
+Sink URL is http://event-display.default.svc.cluster.local
+Emitting event #1
+Emitting event #2
+Event posted successfully
+Event posted successfully
+```
+
+Please note that the example code above is using _Binary_ mode for CloudEvents.
+Simply change
+```javascript
+let binding = new v1.BinaryHTTPEmitter(config);
+```
+with
+```javascript 
+let binding = new v1.StructuredHTTPEmitter(config);
+```
+to employ structured mode.
+
+However, binary mode should be used in most of the cases as:
+- It is faster in terms of serialization and deserialization
+- It works better with cloudevents-aware proxies (like Knative Channels) can simply check the header instead of parsing the payload
+
+## Making use of SinkBinding
+
+`SinkBinding` is a more powerful way of making any Kubernetes resource an event source.
+
+`ContainerSource` will create the container for your event source's image and it will be `ContainerSource` responsibility to manage the container.
+
+`SinkBinding` though, will not create any containers. It will inject the sink information to the already existing Kubernetes resources.
+This is a more flexible approach as you can use any Kubernetes `PodSpecable` as an event source, such as `Deployment`, `Job`, `Knative Service`, `DaemonSet` etc.
+
+We don't need any code changes in our source for making it work with `SinkBinding`.
+
+Create the event display as in the section before:
+```bash
+cat <<EOS |kubectl apply -f -
+---
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: event-display
+spec:
+  template:
+    spec:
+      containers:
+        - image: docker run --name event_display --rm -p 8080:8080 docker.io/aliok/event_display-864884f202126ec3150c5fcef437d90c@sha256:93cb4dcda8fee80a1f68662ae6bf20301471b046ede628f3c3f94f39752fbe08
+EOS
+```
+
+Create a Kubernetes deployment that runs the event source:
+```bash 
+cat <<EOS |kubectl apply -f -
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: node-heartbeats-deployment
+  labels:
+    app: node-heartbeats
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: node-heartbeats
+  template:
+    metadata:
+      labels:
+        app: node-heartbeats
+    spec:
+      containers:
+      - name: node-heartbeats
+        image: path/to/image/registry/node-knative-heartbeat-source:v1
+        ports:
+        - containerPort: 8080
+EOS
+```
+
+As the `SinkBinding` is not created yet, `K_SINK` environment variable is not yet injected and the event source will complain about that.
+
+```
+$ kubectl logs node-heartbeats-deployment-9ffbb644b-llkzk
+
+Sink URL is undefined
+Emitting event #1
+Error during event post
+TypeError [ERR_INVALID_ARG_TYPE]: The "url" argument must be of type string. Received type undefined
+```
+
+Create the `SinkBinding`:
+```bash
+cat <<EOS |kubectl apply -f -
+---
+apiVersion: sources.knative.dev/v1alpha1
+kind: SinkBinding
+metadata:
+  name: bind-node-heartbeat
+spec:
+  subject:
+    apiVersion: apps/v1
+    kind: Deployment
+    selector:
+      matchLabels:
+        app: node-heartbeats
+  sink:
+    ref:
+      apiVersion: serving.knative.dev/v1
+      kind: Service
+      name: event-display
+EOS
+```
+
+
+You will see the pods are recreated and this time the `K_SINK` environment variable is injected.
+
+Also note that since the `replicas` is set to 2, there will be 2 pods that are posting events to the sink. 
+
+```bash
+$ kubectl logs event-display-dpplv-deployment-67c9949cf9-bvjvk -c user-container  
+
+☁️  cloudevents.Event
+Validation: valid
+Context Attributes,
+  specversion: 1.0
+  type: your.event.source.type
+  source: urn:event:from:your-api/resource/123
+  id: your-event-id
+  datacontenttype: application/json
+Data,
+  {
+    "hello": "World 1"
+  }
+
+☁️  cloudevents.Event
+Validation: valid
+Context Attributes,
+  specversion: 1.0
+  type: your.event.source.type
+  source: urn:event:from:your-api/resource/123
+  id: your-event-id
+  datacontenttype: application/json
+Data,
+  {
+    "hello": "World 1"
+  }
+```

From ac3781b775bfc2ed282d33cdfec20d9a5d1b18cc Mon Sep 17 00:00:00 2001
From: Ali Ok <aliok@redhat.com>
Date: Fri, 22 May 2020 10:39:50 +0300
Subject: [PATCH 2/6] Fix image ref

---
 docs/eventing/samples/writing-event-source-easy-way/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/eventing/samples/writing-event-source-easy-way/README.md b/docs/eventing/samples/writing-event-source-easy-way/README.md
index 1662161ba72..db4ec5e1fed 100644
--- a/docs/eventing/samples/writing-event-source-easy-way/README.md
+++ b/docs/eventing/samples/writing-event-source-easy-way/README.md
@@ -110,7 +110,7 @@ spec:
   template:
     spec:
       containers:
-        - image: docker run --name event_display --rm -p 8080:8080 docker.io/aliok/event_display-864884f202126ec3150c5fcef437d90c@sha256:93cb4dcda8fee80a1f68662ae6bf20301471b046ede628f3c3f94f39752fbe08
+        - image: docker.io/aliok/event_display-864884f202126ec3150c5fcef437d90c@sha256:93cb4dcda8fee80a1f68662ae6bf20301471b046ede628f3c3f94f39752fbe08
 EOS
 ```
 

From ffe62e635c842e53d4643bb27f84d363ddfd8ddf Mon Sep 17 00:00:00 2001
From: Ali Ok <aliok@redhat.com>
Date: Fri, 22 May 2020 10:42:58 +0300
Subject: [PATCH 3/6] Fix whitespace issues

---
 .../writing-event-source-easy-way/README.md   | 34 +++++++++----------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/docs/eventing/samples/writing-event-source-easy-way/README.md b/docs/eventing/samples/writing-event-source-easy-way/README.md
index db4ec5e1fed..f881cee49a0 100644
--- a/docs/eventing/samples/writing-event-source-easy-way/README.md
+++ b/docs/eventing/samples/writing-event-source-easy-way/README.md
@@ -7,33 +7,33 @@ type: "docs"
 
 # Introduction
 
-As stated in [tutorial on writing a Source with a Receive Adapter](../writing-receive-adapter-source/README.md), there are multiple ways to 
+As stated in [tutorial on writing a Source with a Receive Adapter](../writing-receive-adapter-source/README.md), there are multiple ways to
 create event sources. The way in that tutorial is to create an independent event source that has its own CRD.
 
-In this tutorial though, you will build an event source in Javascript and use it with 
+In this tutorial though, you will build an event source in Javascript and use it with
 [ContainerSource](../../../eventing/sources/README.md#meta-sources) and / or [SinkBinding](../../../eventing/sources/README.md#meta-sources).
 
-[ContainerSource](../../../eventing/sources/README.md#meta-sources) is an easy way to turn any dispatcher container into an Event Source. 
+[ContainerSource](../../../eventing/sources/README.md#meta-sources) is an easy way to turn any dispatcher container into an Event Source.
 Similarly, another option is using [SinkBinding](../../../eventing/sources/README.md#meta-sources)
-which provides a framework for injecting environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable). 
+which provides a framework for injecting environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable).
 
 Code for this tutorial is available at [Github](https://github.com/aliok/node-knative-heartbeat-source).
 
 # Bootstrapping
 
 Create the project and add the dependencies:
-```bash 
+```bash
 npm init
 npm install cloudevents-sdk --save
 ```
 
 ## Making use of ContainerSource
 
-`ContainerSource` and `SinkBinding` both work by injecting environment variables to an application. 
+`ContainerSource` and `SinkBinding` both work by injecting environment variables to an application.
 Injected environment variables at minimum contain the URL of a sink that will receive events.
 
 Following example emits an event to the sink every 1000 milliseconds.
-The sink URL to post the events will be made available to the application via the `K_SINK` environment variable by `ContainerSource`. 
+The sink URL to post the events will be made available to the application via the `K_SINK` environment variable by `ContainerSource`.
 
 ```javascript
 // File - index.js
@@ -79,8 +79,8 @@ setInterval(function () {
 }, 1000);
 ```
 
-```dockerfile 
-// File - Dockerfile
+```dockerfile
+# File - Dockerfile
 
 FROM node:10
 WORKDIR /usr/src/app
@@ -93,9 +93,9 @@ CMD [ "node", "index.js" ]
 ```
 
 Build and push the image:
-```bash 
+```bash
 docker build . -t path/to/image/registry/node-knative-heartbeat-source:v1
-docker push path/to/image/registry/node-knative-heartbeat-source:v1 
+docker push path/to/image/registry/node-knative-heartbeat-source:v1
 ```
 
 Create the event display service which simply logs any cloudevents posted to it.
@@ -155,8 +155,8 @@ Data,
 ```
 
 If you are interested in to see what is injected into the event source, check the logs of it:
-```bash 
-$ kubectl logs test-heartbeats-deployment-7575c888c7-85w5t 
+```bash
+$ kubectl logs test-heartbeats-deployment-7575c888c7-85w5t
 
 Sink URL is http://event-display.default.svc.cluster.local
 Emitting event #1
@@ -171,7 +171,7 @@ Simply change
 let binding = new v1.BinaryHTTPEmitter(config);
 ```
 with
-```javascript 
+```javascript
 let binding = new v1.StructuredHTTPEmitter(config);
 ```
 to employ structured mode.
@@ -208,7 +208,7 @@ EOS
 ```
 
 Create a Kubernetes deployment that runs the event source:
-```bash 
+```bash
 cat <<EOS |kubectl apply -f -
 ---
 apiVersion: apps/v1
@@ -272,10 +272,10 @@ EOS
 
 You will see the pods are recreated and this time the `K_SINK` environment variable is injected.
 
-Also note that since the `replicas` is set to 2, there will be 2 pods that are posting events to the sink. 
+Also note that since the `replicas` is set to 2, there will be 2 pods that are posting events to the sink.
 
 ```bash
-$ kubectl logs event-display-dpplv-deployment-67c9949cf9-bvjvk -c user-container  
+$ kubectl logs event-display-dpplv-deployment-67c9949cf9-bvjvk -c user-container
 
 ☁️  cloudevents.Event
 Validation: valid

From 09c51022f6192a2e4eb33465d21e5d05f88c8bd7 Mon Sep 17 00:00:00 2001
From: Ali Ok <aliok@redhat.com>
Date: Fri, 22 May 2020 10:51:48 +0300
Subject: [PATCH 4/6] Fix image ref

---
 docs/eventing/samples/writing-event-source-easy-way/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/eventing/samples/writing-event-source-easy-way/README.md b/docs/eventing/samples/writing-event-source-easy-way/README.md
index f881cee49a0..a61a78a607c 100644
--- a/docs/eventing/samples/writing-event-source-easy-way/README.md
+++ b/docs/eventing/samples/writing-event-source-easy-way/README.md
@@ -203,7 +203,7 @@ spec:
   template:
     spec:
       containers:
-        - image: docker run --name event_display --rm -p 8080:8080 docker.io/aliok/event_display-864884f202126ec3150c5fcef437d90c@sha256:93cb4dcda8fee80a1f68662ae6bf20301471b046ede628f3c3f94f39752fbe08
+        - image: docker.io/aliok/event_display-864884f202126ec3150c5fcef437d90c@sha256:93cb4dcda8fee80a1f68662ae6bf20301471b046ede628f3c3f94f39752fbe08
 EOS
 ```
 

From 8ebfd4d30ec5c17185ee1c7bb05632ec9c30febc Mon Sep 17 00:00:00 2001
From: Ali Ok <aliok@redhat.com>
Date: Fri, 22 May 2020 15:57:25 +0300
Subject: [PATCH 5/6] Add sample code within the tutorial directory

---
 .../writing-event-source-easy-way/Dockerfile  | 19 ++++++
 .../writing-event-source-easy-way/README.md   |  2 +-
 .../writing-event-source-easy-way/index.js    | 58 +++++++++++++++++++
 .../package.json                              | 14 +++++
 4 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 docs/eventing/samples/writing-event-source-easy-way/Dockerfile
 create mode 100644 docs/eventing/samples/writing-event-source-easy-way/index.js
 create mode 100644 docs/eventing/samples/writing-event-source-easy-way/package.json

diff --git a/docs/eventing/samples/writing-event-source-easy-way/Dockerfile b/docs/eventing/samples/writing-event-source-easy-way/Dockerfile
new file mode 100644
index 00000000000..9e7a85fe75b
--- /dev/null
+++ b/docs/eventing/samples/writing-event-source-easy-way/Dockerfile
@@ -0,0 +1,19 @@
+FROM node:10
+
+# Create app directory
+WORKDIR /usr/src/app
+
+# Install app dependencies
+# A wildcard is used to ensure both package.json AND package-lock.json are copied
+# where available (npm@5+)
+COPY package*.json ./
+
+RUN npm install
+# If you are building your code for production
+# RUN npm ci --only=production
+
+# Bundle app source
+COPY . .
+
+EXPOSE 8080
+CMD [ "node", "index.js" ]
diff --git a/docs/eventing/samples/writing-event-source-easy-way/README.md b/docs/eventing/samples/writing-event-source-easy-way/README.md
index a61a78a607c..3f978519a6c 100644
--- a/docs/eventing/samples/writing-event-source-easy-way/README.md
+++ b/docs/eventing/samples/writing-event-source-easy-way/README.md
@@ -17,7 +17,7 @@ In this tutorial though, you will build an event source in Javascript and use it
 Similarly, another option is using [SinkBinding](../../../eventing/sources/README.md#meta-sources)
 which provides a framework for injecting environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable).
 
-Code for this tutorial is available at [Github](https://github.com/aliok/node-knative-heartbeat-source).
+Code for this tutorial is available [here](./).
 
 # Bootstrapping
 
diff --git a/docs/eventing/samples/writing-event-source-easy-way/index.js b/docs/eventing/samples/writing-event-source-easy-way/index.js
new file mode 100644
index 00000000000..be5da7658ba
--- /dev/null
+++ b/docs/eventing/samples/writing-event-source-easy-way/index.js
@@ -0,0 +1,58 @@
+const v1 = require("cloudevents-sdk/v1");
+
+let sinkUrl = process.env['K_SINK'];
+
+console.log("Sink URL is " + sinkUrl);
+
+let config = {
+    method: "POST",
+    url: sinkUrl
+};
+
+// The binding instance
+let binding = new v1.BinaryHTTPEmitter(config);
+
+let eventIndex = 0;
+setInterval(function () {
+    console.log("Emitting event #" + ++eventIndex);
+
+    // create the event
+    let myevent = v1.event()
+        .id('your-event-id')
+        .type("your.event.source.type")
+        .source("urn:event:from:your-api/resource/123")
+        .dataContentType("application/json")
+        .data({"hello": "World " + eventIndex});
+
+    // Emit the event
+    binding.emit(myevent)
+        .then(response => {
+            // Treat the response
+            console.log("Event posted successfully");
+            console.log(response.data);
+        })
+        .catch(err => {
+            // Deal with errors
+            console.log("Error during event post");
+            console.error(err);
+        });
+}, 1000);
+
+registerGracefulExit();
+
+function registerGracefulExit() {
+    let logExit = function () {
+        console.log("Exiting");
+        process.exit();
+    };
+
+    // handle graceful exit
+    //do something when app is closing
+    process.on('exit', logExit);
+    //catches ctrl+c event
+    process.on('SIGINT', logExit);
+    process.on('SIGTERM', logExit);
+    // catches "kill pid" (for example: nodemon restart)
+    process.on('SIGUSR1', logExit);
+    process.on('SIGUSR2', logExit);
+}
diff --git a/docs/eventing/samples/writing-event-source-easy-way/package.json b/docs/eventing/samples/writing-event-source-easy-way/package.json
new file mode 100644
index 00000000000..21339282d10
--- /dev/null
+++ b/docs/eventing/samples/writing-event-source-easy-way/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "event-emitter",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "cloudevents-sdk": "^1.0.0"
+  }
+}

From 87d1f91f93491d0475e5b66c2a90c5b8b6097380 Mon Sep 17 00:00:00 2001
From: Ali Ok <aliok@redhat.com>
Date: Fri, 22 May 2020 16:01:56 +0300
Subject: [PATCH 6/6] Add bundle

---
 .../samples/writing-event-source-easy-way/README.md       | 7 -------
 .../samples/writing-event-source-easy-way/_index.md       | 8 ++++++++
 2 files changed, 8 insertions(+), 7 deletions(-)
 create mode 100644 docs/eventing/samples/writing-event-source-easy-way/_index.md

diff --git a/docs/eventing/samples/writing-event-source-easy-way/README.md b/docs/eventing/samples/writing-event-source-easy-way/README.md
index 3f978519a6c..89ddc86fa45 100644
--- a/docs/eventing/samples/writing-event-source-easy-way/README.md
+++ b/docs/eventing/samples/writing-event-source-easy-way/README.md
@@ -1,10 +1,3 @@
----
-title: "Writing an Event Source using the easy way"
-linkTitle: "Event Source - easy way"
-weight: 10
-type: "docs"
----
-
 # Introduction
 
 As stated in [tutorial on writing a Source with a Receive Adapter](../writing-receive-adapter-source/README.md), there are multiple ways to
diff --git a/docs/eventing/samples/writing-event-source-easy-way/_index.md b/docs/eventing/samples/writing-event-source-easy-way/_index.md
new file mode 100644
index 00000000000..1cce7875145
--- /dev/null
+++ b/docs/eventing/samples/writing-event-source-easy-way/_index.md
@@ -0,0 +1,8 @@
+---
+title: "Writing an Event Source using the easy way"
+linkTitle: "Event Source - easy way"
+weight: 10
+type: "docs"
+---
+
+{{% readfile file="README.md" %}}