chore(refactor): protocol bindings use interfaces

This change modifies the protocol binding interfaces such as `Binding`,
`Serializer` and the like to use the `CloudEventV1` interface instead of the
implementation class `CloudEvent`. This should make extending the interfaces
simpler as this work has grown out of efforts around the implementation of
a second transport interface, Kafka.

See: cloudevents#455

This commit also includes the addition of a generic type to the `Message`
interface, defaulting to `string`.

There is also some minor clean up involving what is exported from the
`message/http` modules. Now, instead of exporting the entire implementation,
only the `HTTP` binding implementation is exported, and it is then reexported
by `message`.

Also, a static `CloudEvent.cloneWith()` method has been added which the
instance methods now use.

Signed-off-by: Lance Ball <[email protected]>

Author: lance

package.json

@@ -10,9 +10,9 @@
     "lint:js": "eslint 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' cucumber.js",
     "lint:md": "remark .",
     "lint:fix": "eslint 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' --fix",
-    "apretest": "npm run lint && npm run conformance",
-    "test": "mocha --require ts-node/register ./test/integration/**/kafka_tests.ts",
-    "conformance": "cucumber-js ./conformance/features/http-protocol-binding.feature -p default",
+    "pretest": "npm run lint && npm run conformance",
+    "test": "mocha --require ts-node/register ./test/integration/**/*.ts",
+    "conformance": "cucumber-js ./conformance/features/*-protocol-binding.feature -p default",
     "coverage": "nyc --reporter=lcov --reporter=text npm run test",
     "coverage-publish": "wget -qO - https://coverage.codacy.com/get.sh | bash -s report -l JavaScript -r coverage/lcov.info",
     "generate-docs": "typedoc --excludeNotDocumented --out docs src",

src/event/cloudevent.ts

@@ -198,7 +198,7 @@ See: https://github.com/cloudevents/spec/blob/v1.0/spec.md#type-system`);
    * @throws if the CloudEvent does not conform to the schema
    * @return {CloudEvent} returns a new CloudEvent<D>
    */
-  public cloneWith<D>(options: Partial<CloudEvent<D>>, strict?: boolean): CloudEvent<D>;
+  public cloneWith<D>(options: Partial<CloudEventV1<D>>, strict?: boolean): CloudEvent<D>;
   /**
    * Clone a CloudEvent with new/update attributes
    * @param {object} options attributes to augment the CloudEvent
@@ -207,7 +207,7 @@ See: https://github.com/cloudevents/spec/blob/v1.0/spec.md#type-system`);
    * @return {CloudEvent} returns a new CloudEvent
    */
   public cloneWith<D>(options: Partial<CloudEventV1<D>>, strict = true): CloudEvent<D | T> {
-    return new CloudEvent(Object.assign({}, this.toJSON(), options), strict);
+    return CloudEvent.cloneWith(this as CloudEvent<T>, options, strict);
   }
 
   /**
@@ -217,4 +217,11 @@ See: https://github.com/cloudevents/spec/blob/v1.0/spec.md#type-system`);
   [Symbol.for("nodejs.util.inspect.custom")](): string {
     return this.toString();
   }
+
+  public static cloneWith(
+    event: CloudEvent<any>, // Must be a concrete CloudEvent class
+    options: Partial<CloudEventV1<any>>, // May take any 
+    strict = true): CloudEvent<any> {
+      return new CloudEvent(Object.assign({}, event.toJSON(), options), strict);
+    }
 }

src/index.ts

@@ -8,7 +8,9 @@ import { ValidationError } from "./event/validation";
 import { CloudEventV1, CloudEventV1Attributes } from "./event/interfaces";
 
 import { Options, TransportFunction, EmitterFunction, emitterFor, Emitter } from "./transport/emitter";
-import { Headers, Mode, Binding, HTTP, Message, Serializer, Deserializer } from "./message";
+import { 
+  Headers, Mode, Binding, HTTP, Kafka, KafkaEvent, KafkaMessage, Message,
+  Serializer, Deserializer } from "./message";
 
 import CONSTANTS from "./constants";
 
@@ -27,6 +29,9 @@ export {
   Deserializer,
   Serializer,
   HTTP,
+  Kafka,
+  KafkaEvent,
+  KafkaMessage,
   // From transport
   TransportFunction,
   EmitterFunction,

src/message/http/headers.ts

@@ -4,7 +4,7 @@
 */
 
 import { PassThroughParser, DateParser, MappedParser } from "../../parsers";
-import { CloudEvent } from "../..";
+import { CloudEventV1 } from "../..";
 import { Headers } from "../";
 import { Version } from "../../event/cloudevent";
 import CONSTANTS from "../../constants";
@@ -24,7 +24,7 @@ export const requiredHeaders = [
  * @param {CloudEvent} event a CloudEvent
  * @returns {Object} the headers that will be sent for the event
  */
-export function headersFor<T>(event: CloudEvent<T>): Headers {
+export function headersFor<T>(event: CloudEventV1<T>): Headers {
   const headers: Headers = {};
   let headerMap: Readonly<{ [key: string]: MappedParser }>;
   if (event.specversion === Version.V1) {

src/message/http/index.ts

@@ -4,7 +4,7 @@
 */
 
 import { CloudEvent, CloudEventV1, CONSTANTS, Mode, Version } from "../..";
-import { Message, Headers } from "..";
+import { Message, Headers, Binding } from "..";
 
 import {
   headersFor,
@@ -25,7 +25,7 @@ import { JSONParser, MappedParser, Parser, parserByContentType } from "../../par
  * @param {CloudEvent} event The event to serialize
  * @returns {Message} a Message object with headers and body
  */
-export function binary<T>(event: CloudEvent<T>): Message {
+function binary<T>(event: CloudEventV1<T>): Message {
   const contentType: Headers = { [CONSTANTS.HEADER_CONTENT_TYPE]: CONSTANTS.DEFAULT_CONTENT_TYPE };
   const headers: Headers = { ...contentType, ...headersFor(event) };
   let body = event.data;
@@ -47,10 +47,10 @@ export function binary<T>(event: CloudEvent<T>): Message {
  * @param {CloudEvent} event the CloudEvent to be serialized
  * @returns {Message} a Message object with headers and body
  */
-export function structured<T>(event: CloudEvent<T>): Message {
+function structured<T>(event: CloudEventV1<T>): Message {
   if (event.data_base64) {
     // The event's data is binary - delete it
-    event = event.cloneWith({ data: undefined });
+    event = (event as CloudEvent).cloneWith({ data: undefined });
   }
   return {
     headers: {
@@ -67,7 +67,7 @@ export function structured<T>(event: CloudEvent<T>): Message {
  * @param {Message} message an incoming Message object
  * @returns {boolean} true if this Message is a CloudEvent
  */
-export function isEvent(message: Message): boolean {
+function isEvent(message: Message): boolean {
   // TODO: this could probably be optimized
   try {
     deserialize(message);
@@ -84,7 +84,7 @@ export function isEvent(message: Message): boolean {
  * @param {Message} message the incoming message
  * @return {CloudEvent} A new {CloudEvent} instance
  */
-export function deserialize<T>(message: Message): CloudEvent<T> | CloudEvent<T>[] {
+function deserialize<T>(message: Message): CloudEvent<T> | CloudEvent<T>[] {
   const cleanHeaders: Headers = sanitize(message.headers);
   const mode: Mode = getMode(cleanHeaders);
   const version = getVersion(mode, cleanHeaders, message.body);
@@ -261,3 +261,14 @@ function parseBatched<T>(message: Message): CloudEvent<T> | CloudEvent<T>[] {
   });
   return ret;
 }
+
+/**
+ * Bindings for HTTP transport support
+ * @implements {@linkcode Binding}
+ */
+ export const HTTP: Binding = {
+  binary,
+  structured,
+  toEvent: deserialize,
+  isEvent: isEvent,
+};

src/message/index.ts

@@ -4,8 +4,11 @@
 */
 
 import { IncomingHttpHeaders } from "http";
-import { CloudEvent } from "..";
-import { binary, deserialize, structured, isEvent } from "./http";
+import { CloudEventV1 } from "..";
+
+// reexport the protocol bindings
+export * from "./http";
+export * from "./kafka";
 
 /**
  * Binding is an interface for transport protocols to implement,
@@ -62,7 +65,7 @@ export enum Mode {
  * @interface
  */
 export interface Serializer {
-  <T>(event: CloudEvent<T>): Message;
+  <T>(event: CloudEventV1<T>): Message;
 }
 
 /**
@@ -71,7 +74,7 @@ export interface Serializer {
  * @interface
  */
 export interface Deserializer {
-  <T>(message: Message): CloudEvent<T> | CloudEvent<T>[];
+  <T>(message: Message): CloudEventV1<T> | CloudEventV1<T>[];
 }
 
 /**
@@ -82,16 +85,3 @@ export interface Deserializer {
 export interface Detector {
   (message: Message): boolean;
 }
-
-/**
- * Bindings for HTTP transport support
- * @implements {@linkcode Binding}
- */
-export const HTTP: Binding = {
-  binary: binary as Serializer,
-  structured: structured as Serializer,
-  toEvent: deserialize as Deserializer,
-  isEvent: isEvent as Detector,
-};
-
-export * from "./kafka";

src/message/kafka/headers.ts

@@ -3,7 +3,7 @@
  SPDX-License-Identifier: Apache-2.0
 */
 
-import { CloudEvent, CONSTANTS, Headers } from "../..";
+import { CloudEventV1, CONSTANTS, Headers } from "../..";
 
 type KafkaHeaders = Readonly<{
   ID: string;
@@ -55,7 +55,7 @@ export const HEADER_MAP: { [key: string]: string } = {
  * @param {CloudEvent} event a CloudEvent object
  * @returns {Headers} the CloudEvent attribute as Kafka headers
  */
-export function headersFor<T>(event: CloudEvent<T>): Headers {
+export function headersFor<T>(event: CloudEventV1<T>): Headers {
   const headers: Headers = {};
 
   Object.getOwnPropertyNames(event).forEach((property) => {