fastify-cloudevents - npm Package Compare versions

Comparing version 2.2.1 to 2.3.0

CHANGELOG.md

 # Change Log
 
+## [2.3.0](https://github.com/smartiniOnGitHub/fastify-cloudevents/releases/tag/2.3.0) (2019-11-08)
+[Full Changelog](https://github.com/smartiniOnGitHub/fastify-cloudevents/compare/2.2.0...2.3.0)
+Summary Changelog:
+- Update dependency on cloudevent to '0.6.x' which implements the 
+  [v0.3 - CloudEvents Spec](https://github.com/cloudevents/spec/releases/tag/v0.3) 
+  with all breaking changes since its v0.2
+- Breaking Change: CloudEvent constructor signature has changed a little, 
+  to handle extensions as per spec
+- Breaking Change: CloudEvent attributes has been renamed for better consistency with the spec, 
+  and renamed related methods too
+- Updated all dependencies
+- Update requirements to a more recent Fastify, release '^2.7.1'
+- Updated documentation and samples to describe/show changes and the new behavior
+- Export even JSONBatch via Fastify decorators
+- Add plugin option flags to enable the output of redundant attributes and HTTP attributes
+- Fix usage of request url (fix already present in 2.2.1)
+- Clarify and cleanup docs and examples
+- Add npm custom commands to run examples and tests in debug mode
+- Other minor changes
+
 ## [2.2.1](https://github.com/smartiniOnGitHub/fastify-cloudevents/releases/tag/2.2.1) (2019-10-23)
@@ -4,0 +24,0 @@ Summary Changelog:

example/example-enhanced.js

@@ -33,5 +33,11 @@ /*
   includeHeaders: true, // change from default value, as a sample
+  includeHttpAttributes: true, // change from default value, as a sample
+  includeRedundantAttributes: true, // change from default value, as a sample
   cloudEventOptions: {
     strict: true // enable strict mode in generated CloudEvents, optional
-  }
+  },
+  // to be able to store serverUrlMode in CloudEvents extensions, set it
+  cloudEventExtensions: null // sample null extension, good even in strict mode
+  // cloudEventExtensions: {} // ok, but no empty extensions in strict mode
+  // cloudEventExtensions: { exampleExtension: 'value' } // sample extension
 }
@@ -66,2 +72,4 @@ k.serverUrl = `${k.protocol}://${k.address}:${k.port}`
   includeHeaders: k.includeHeaders,
+  includeHttpAttributes: k.includeHttpAttributes,
+  includeRedundantAttributes: k.includeRedundantAttributes,
   onRequestCallback: loggingCallback,
@@ -79,3 +87,4 @@ preParsingCallback: loggingCallback,
   onReadyCallback: loggingCallback,
-  cloudEventOptions: k.cloudEventOptions
+  cloudEventOptions: k.cloudEventOptions,
+  cloudEventExtensions: k.cloudEventExtensions
 })
@@ -107,3 +116,4 @@
       }, // data
-      k.cloudEventOptions
+      k.cloudEventOptions,
+      k.cloudEventExtensions
     )
@@ -160,3 +170,4 @@ console.log(`console - server-script.start: created CloudEvent ${CloudEventUtilityConstructor.CloudEventTransformer.dumpObject(ce, 'ce')}`)
       }, // data
-      k.cloudEventOptions
+      k.cloudEventOptions,
+      k.cloudEventExtensions
     )
@@ -176,3 +187,4 @@ loggingCallback(ce) // forward generated event to a callback before exiting ...
     }, // data
-    k.cloudEventOptions
+    k.cloudEventOptions,
+    k.cloudEventExtensions
   )
@@ -197,3 +209,4 @@ loggingCallback(ce)
       }, // data
-      k.cloudEventOptions
+      k.cloudEventOptions,
+      k.cloudEventExtensions
     )
@@ -213,3 +226,4 @@ loggingCallback(ce) // forward generated event to a callback before exiting ...
     }, // data
-    k.cloudEventOptions
+    k.cloudEventOptions,
+    k.cloudEventExtensions
   )
@@ -216,0 +230,0 @@ loggingCallback(ce)

package.json

 {
   "name": "fastify-cloudevents",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Fastify Plugin to serialize events in the CloudEvents standard format",
@@ -21,4 +21,4 @@ "main": "src/plugin",
     "fastify-plugin": "^1.6.0",
-    "fast-json-stringify": "^1.15.5",
-    "cloudevent": "~0.5.0"
+    "fast-json-stringify": "^1.15.6",
+    "cloudevent": "~0.6.0"
   },
@@ -28,3 +28,3 @@ "devDependencies": {
     "standard": "^14.3.1",
-    "tap": "^14.8.2"
+    "tap": "^14.9.2"
   },
@@ -31,0 +31,0 @@ "peerDependencies": {},

README.md

@@ -9,6 +9,7 @@ # fastify-cloudevents
   [![devDependencies Status](https://david-dm.org/smartiniOnGitHub/fastify-cloudevents/dev-status.svg)](https://david-dm.org/smartiniOnGitHub/fastify-cloudevents?type=dev)
+  [![Known Vulnerabilities](https://snyk.io//test/github/smartiniOnGitHub/fastify-cloudevents/badge.svg?targetFile=package.json)](https://snyk.io//test/github/smartiniOnGitHub/fastify-cloudevents?targetFile=package.json)
 
 Fastify Plugin to transform events in/from the CloudEvents standard format.
 
-Current release implements the v0.3 of the CloudEvents Spec.
+Current release uses the v0.3 of the CloudEvents Spec.
 
@@ -70,2 +71,3 @@ The purpose of this plugin is to let Fastify web applications create instances of CloudEvents
 - `CloudEventTransformer`, the CloudEventTransformer utility class
+- `JSONBatch`, the class to handle JSONBatch instances
 - `cloudEventSerializeFast`, a serialize function implemented here using `fast-json-stringify` 
@@ -78,4 +80,4 @@ and not standard JSON serialization functions; note that similar features of the underlying library
   to use as a base `source` in generated CloudEvents
-- `serverUrlMode`, the mode to build the `source` attribute in generated CloudEvents 
-  (any non null value will cause this setting to be aded to the extension attribute):
+- `serverUrlMode`, the mode to build the `source` attribute in generated CloudEvents; 
+  any not null value will cause this setting to be added to extensions (if set not null in plugin options):
   - null, (default value) same as 'pluginAndRequestSimplified'
@@ -91,4 +93,8 @@ - 'pluginServerUrl', use only the given `serverUrl`
 - `idGenerator`, a generator function that returns the id (if possible, unique) for any CloudEvent
-- `includeHeaders`, a boolean flag that when `true` tells that request headers will be put 
-  in generated CloudEvents (but by default is `false`)
+- `includeHeaders`, a boolean flag to add request headers in generated CloudEvents when `true`
+  (by default is `false`)
+- `includeHttpAttributes`, a boolean flag to add some HTTP attributes in generated CloudEvents when `true`
+  (by default is `false`)
+- `includeRedundantAttributes`, a boolean flag to add some redundant attributes
+  in the data section of generated CloudEvents when `true` (by default is `false`)
 - `onRequestCallback`, callback to handle generated CloudEvents in Fastify hook `onRequest`
@@ -118,7 +124,8 @@ - `preParsingCallback`, callback to handle generated CloudEvents in Fastify hook `preParsing`
 and for example add a version in the 'type' attribute 
-(for example '-v1.0.0' at the end of its base value, or at the end of its full value) ,
+(for example '-v1.0.0' at the end of its base value, or at the end of its full value),
 or into the 'schemaurl' attribute but only its major version 
 (like '-v1' or '/v1/' at the end).
-Since v0.3 of the spec, extensions are no more inside a specific attribute, 
-so even mine (for the 'strict' mode for example) has been moved into a namespaced one.
+Since v0.3 of the spec, extensions are no more inside a specific attribute; 
+as recommended even mine (for the 'strict' mode for example) has been moved into a namespaced one;
+plugin extensions ('serverUrlMode') has been moved in another (specific) namespace.
 
@@ -125,0 +132,0 @@ For more info on the standard, see the [CloudEvents Specification](https://github.com/cloudevents/spec).

src/builder.js

@@ -40,3 +40,5 @@ /*
     includeHeaders,
-    cloudEventOptions
+    includeRedundantAttributes,
+    cloudEventOptions,
+    cloudEventExtensions
   } = options
@@ -53,3 +55,3 @@
      *
-     * @param {string} url the uri part of the current request
+     * @param {string} [url='']  the uri part of the current request
      * @return {string} the source value to use, as a string
@@ -99,3 +101,3 @@ * @private
      * useful to add into the CloudEvent in a custom attribute inside data.
-     * If related plugin flag 'includeHeaders' is enabled headers will be returned,
+     * If plugin flag 'includeHeaders' is enabled, headers will be returned,
      * otherwise nothing.
@@ -176,3 +178,3 @@ * Note that some config options for builders are used here.
      *
-     * @param {object} description the description (maybe related to the event)
+     * @param {object} [description='']  the description (maybe related to the event)
      * @return {object} an object containing extracted attributes
@@ -193,2 +195,4 @@ * @private
      * useful for simplify plugin hooks.
+     * If plugin flag 'includeRedundantAttributes' is enabled,
+     * some redundant attributes will be added to data.
      * Note that some config options for builders are used here.
@@ -198,3 +202,3 @@ *
      * @param {!object} request the request
-     * @param {!object} reply the reply
+     * @param {object} reply the reply
      * @param {object} payload the payload
@@ -205,16 +209,20 @@ * @return {object} the CloudEvent instance
     buildCloudEventForHook (hookName, request, reply, payload) {
-      if (!hookName || !request || !reply) {
+      if (!hookName || !request) {
         throw new Error('Illegal arguments: mandatory argument undefined or null')
       }
+      const ceData = {
+        request: this.buildRequestDataForCE(request),
+        reply: (reply === null) ? undefined : this.buildReplyDataForCE(reply),
+        payload
+      }
+      if (includeRedundantAttributes !== null && includeRedundantAttributes === true) {
+        ceData.id = request.id
+        ceData.timestamp = CloudEventTransformer.timestampToNumber()
+      }
       const ce = new CloudEvent(idGenerator.next().value,
         `${baseNamespace}.${hookName}`,
         this.buildSourceUrl(request.req.url),
-        {
-          id: request.id,
-          timestamp: CloudEventTransformer.timestampToNumber(),
-          request: this.buildRequestDataForCE(request),
-          reply: this.buildReplyDataForCE(reply),
-          payload
-        }, // data
-        cloudEventOptions
+        ceData,
+        cloudEventOptions,
+        cloudEventExtensions
       )
@@ -221,0 +229,0 @@ return ce

src/plugin.js

@@ -19,3 +19,3 @@ /*
 const fp = require('fastify-plugin')
-const { CloudEvent, CloudEventTransformer } = require('cloudevent') // get CloudEvent definition and related utilities
+const { CloudEvent, CloudEventTransformer, JSONBatch } = require('cloudevent') // get CloudEvent definition and related utilities
 
@@ -25,3 +25,3 @@ const pluginName = require('../package.json').name // get plugin name
 
-function fastifyCloudEvents (fastify, options, next) {
+function fastifyCloudEvents (fastify, options, done) {
   const {
@@ -33,2 +33,4 @@ serverUrl = '/',
     includeHeaders = false,
+    includeHttpAttributes = false,
+    includeRedundantAttributes = false,
     onRequestCallback = null,
@@ -46,3 +48,4 @@ preParsingCallback = null,
     onReadyCallback = null,
-    cloudEventOptions = {}
+    cloudEventOptions = {},
+    cloudEventExtensions = null
   } = options
@@ -55,2 +58,4 @@
   ensureIsBoolean(includeHeaders, 'includeHeaders')
+  ensureIsBoolean(includeHttpAttributes, 'includeHttpAttributes')
+  ensureIsBoolean(includeRedundantAttributes, 'includeRedundantAttributes')
   ensureIsFunction(onRequestCallback, 'onRequestCallback')
@@ -68,2 +73,4 @@ ensureIsFunction(preParsingCallback, 'preParsingCallback')
   ensureIsFunction(onReadyCallback, 'onReadyCallback')
+  ensureIsObjectPlain(cloudEventOptions, 'cloudEventOptions')
+  ensureIsObjectPlain(cloudEventExtensions, 'cloudEventExtensions')
 
@@ -81,5 +88,5 @@ const fastJson = require('fast-json-stringify')
    * @param {!object} event the CloudEvent to serialize
-   * @param {object} options optional serialization attributes:
+   * @param {object} [options={}] optional serialization attributes:
    *        encoder (function, no default) a function that takes data and returns encoded data,
-   *        encodedData (string, no default) already encoded data (but consistency with the contenttype is not checked),
+   *        encodedData (string, no default) already encoded data (but consistency with the datacontenttype is not checked),
    *        onlyValid (boolean, default false) to serialize only if it's a valid instance,
@@ -91,5 +98,5 @@ * @return {string} the serialized event, as a string
   function serialize (event, { encoder, encodedData, onlyValid = false } = {}) {
-    ensureIsObject(event, 'event')
+    ensureIsObjectPlain(event, 'event')
 
-    if (event.contenttype === CloudEvent.contenttypeDefault()) {
+    if (event.datacontenttype === CloudEvent.datacontenttypeDefault()) {
       if ((onlyValid === false) || (onlyValid === true && CloudEvent.isValidEvent(event) === true)) {
@@ -104,3 +111,3 @@ return stringify(event)
       if (typeof encoder !== 'function') {
-        throw new Error(`Missing or wrong encoder function: '${encoder}' for the given content type: '${event.contenttype}'.`)
+        throw new Error(`Missing or wrong encoder function: '${encoder}' for the given content type: '${event.datacontenttype}'.`)
       }
@@ -111,7 +118,7 @@ encodedData = encoder(event.payload)
       if (encodedData === undefined || encodedData === null) {
-        throw new Error(`Missing encoder function: use encoder function or already encoded data with the given content type: '${event.contenttype}'.`)
+        throw new Error(`Missing encoder function: use encoder function or already encoded data with the given content type: '${event.datacontenttype}'.`)
       }
     }
     if (typeof encodedData !== 'string') {
-      throw new Error(`Missing or wrong encoded data: '${encodedData}' for the given content type: '${event.contenttype}'.`)
+      throw new Error(`Missing or wrong encoded data: '${encodedData}' for the given content type: '${event.datacontenttype}'.`)
     }
@@ -130,8 +137,9 @@ const newEvent = CloudEventTransformer.mergeObjects(event, { data: encodedData })
   fastify.decorate('CloudEventTransformer', CloudEventTransformer)
+  fastify.decorate('JSONBatch', JSONBatch)
   fastify.decorate('cloudEventSerializeFast', serialize)
 
   // add to extensions the serverUrlMode defined, if set
-  if (serverUrlMode !== null) {
-    cloudEventOptions.extensions = cloudEventOptions.extensions || {}
-    cloudEventOptions.extensions.serverUrlMode = serverUrlMode
+  if (serverUrlMode !== null && cloudEventExtensions !== null) {
+    cloudEventExtensions.com_github_smartiniOnGitHub_fastifycloudevents = {}
+    cloudEventExtensions.com_github_smartiniOnGitHub_fastifycloudevents.serverUrlMode = serverUrlMode
   }
@@ -148,3 +156,5 @@
     includeHeaders,
-    cloudEventOptions
+    includeRedundantAttributes,
+    cloudEventOptions,
+    cloudEventExtensions
   })
@@ -154,10 +164,11 @@
   if (onRequestCallback !== null) {
-    fastify.addHook('onRequest', (request, reply, next) => {
-      const ce = builders.buildCloudEventForHook('onRequest', request, reply)
-      // add more attributes to data, could be useful to have
-      ce.data.request.httpVersion = request.req.httpVersion
-      ce.data.request.originalUrl = request.req.originalUrl
-      ce.data.request.upgrade = request.req.upgrade
-      // remove the reply attribute from data, for less verbose data
-      delete ce.data.reply
+    fastify.addHook('onRequest', (request, reply, done) => {
+      // small optimization: pass a null reply because no useful here
+      const ce = builders.buildCloudEventForHook('onRequest', request, null)
+      // add some http related attributes to data, could be useful to have
+      if (includeHttpAttributes !== null && includeHttpAttributes === true) {
+        ce.data.request.httpVersion = request.req.httpVersion
+        ce.data.request.originalUrl = request.req.originalUrl
+        ce.data.request.upgrade = request.req.upgrade
+      }
       // console.log(`DEBUG - onRequest: created CloudEvent ${CloudEventTransformer.dumpObject(ce, 'ce')}`)
@@ -167,3 +178,3 @@ // send the event to the callback
 
-      next()
+      done()
     })
@@ -173,7 +184,7 @@ }
   if (preParsingCallback !== null) {
-    fastify.addHook('preParsing', (request, reply, next) => {
+    fastify.addHook('preParsing', (request, reply, done) => {
       const ce = builders.buildCloudEventForHook('preParsing', request, reply)
       preParsingCallback(ce)
 
-      next()
+      done()
     })
@@ -183,7 +194,7 @@ }
   if (preValidationCallback !== null) {
-    fastify.addHook('preValidation', (request, reply, next) => {
+    fastify.addHook('preValidation', (request, reply, done) => {
       const ce = builders.buildCloudEventForHook('preValidation', request, reply)
       preValidationCallback(ce)
 
-      next()
+      done()
     })
@@ -193,7 +204,7 @@ }
   if (preHandlerCallback !== null) {
-    fastify.addHook('preHandler', (request, reply, next) => {
+    fastify.addHook('preHandler', (request, reply, done) => {
       const ce = builders.buildCloudEventForHook('preHandler', request, reply)
       preHandlerCallback(ce)
 
-      next()
+      done()
     })
@@ -203,7 +214,7 @@ }
   if (preSerializationCallback !== null) {
-    fastify.addHook('preSerialization', (request, reply, payload, next) => {
+    fastify.addHook('preSerialization', (request, reply, payload, done) => {
       const ce = builders.buildCloudEventForHook('preSerialization', request, reply, payload)
       preSerializationCallback(ce)
 
-      next()
+      done()
     })
@@ -213,3 +224,3 @@ }
   if (onErrorCallback !== null) {
-    fastify.addHook('onError', (request, reply, error, next) => {
+    fastify.addHook('onError', (request, reply, error, done) => {
       const processInfoAsData = CloudEventTransformer.processInfoToData()
@@ -221,18 +232,22 @@ const errorAsData = CloudEventTransformer.errorToData(error, {
       })
+      const ceData = {
+        request: builders.buildRequestDataForCE(request),
+        reply: builders.buildReplyDataForCE(reply),
+        error: errorAsData,
+        process: processInfoAsData
+      }
+      if (includeRedundantAttributes !== null && includeRedundantAttributes === true) {
+        ceData.id = request.id
+        ceData.timestamp = CloudEventTransformer.timestampToNumber()
+      }
       const ce = new fastify.CloudEvent(idGenerator.next().value,
         `${baseNamespace}.onError`,
         builders.buildSourceUrl(request.url),
-        {
-          id: request.id,
-          timestamp: CloudEventTransformer.timestampToNumber(),
-          request: builders.buildRequestDataForCE(request),
-          reply: builders.buildReplyDataForCE(reply),
-          error: errorAsData,
-          process: processInfoAsData
-        }, // data
-        cloudEventOptions
+        ceData,
+        cloudEventOptions,
+        cloudEventExtensions
       )
       onErrorCallback(ce)
 
-      next() // do not pass the error to the next callback here
+      done() // do not pass the error to the done callback here
     })
@@ -242,6 +257,7 @@ }
   if (onSendCallback !== null) {
-    fastify.addHook('onSend', (request, reply, payload, next) => {
+    fastify.addHook('onSend', (request, reply, payload, done) => {
       const ce = builders.buildCloudEventForHook('onSend', request, reply, payload)
       onSendCallback(ce)
-      next()
+
+      done()
     })
@@ -251,9 +267,8 @@ }
   if (onResponseCallback !== null) {
-    fastify.addHook('onResponse', (request, reply, next) => {
+    fastify.addHook('onResponse', (request, reply, done) => {
       const ce = builders.buildCloudEventForHook('onResponse', request, reply)
-      // remove the request attribute from data, for less verbose data
-      delete ce.data.request
+      // keep the request attribute from data, even if more data will be shown here
       onResponseCallback(ce)
 
-      next()
+      done()
     })
@@ -269,3 +284,4 @@ }
         builders.buildPluginDataForCE('plugin shutdown'), // data
-        cloudEventOptions
+        cloudEventOptions,
+        cloudEventExtensions
       )
@@ -284,3 +300,4 @@ onCloseCallback(ce)
         routeOptions, // data
-        cloudEventOptions
+        cloudEventOptions,
+        cloudEventExtensions
       )
@@ -297,3 +314,4 @@ onRouteCallback(ce)
         builders.buildPluginDataForCE('plugin registration'), // data
-        cloudEventOptions
+        cloudEventOptions,
+        cloudEventExtensions
       )
@@ -310,3 +328,4 @@ onRegisterCallback(ce)
       builders.buildPluginDataForCE('plugin startup successfully'), // data
-      cloudEventOptions
+      cloudEventOptions,
+      cloudEventExtensions
     )
@@ -316,6 +335,6 @@ fastify.ready(onReadyCallback(ce))
 
-  next()
+  done()
 }
 
-function ensureIsString (arg, name) {
+function ensureIsString (arg, name = 'arg') {
   if (arg !== null && typeof arg !== 'string') {
@@ -326,3 +345,3 @@ throw new TypeError(`The argument '${name}' must be a string, instead got a '${typeof arg}'`)
 
-function ensureIsBoolean (arg, name) {
+function ensureIsBoolean (arg, name = 'arg') {
   if (arg !== null && typeof arg !== 'boolean') {
@@ -333,3 +352,3 @@ throw new TypeError(`The argument '${name}' must be a boolean, instead got a '${typeof arg}'`)
 
-function ensureIsObject (arg, name) {
+function ensureIsObject (arg, name = 'arg') {
   if (arg !== null && typeof arg !== 'object') {
@@ -340,3 +359,9 @@ throw new TypeError(`The argument '${name}' must be a object, instead got a '${typeof arg}'`)
 
-function ensureIsFunction (arg, name) {
+function ensureIsObjectPlain (arg, name = 'arg') {
+  if (arg !== null && Object.prototype.toString.call(arg) === '[object Object]') {
+    return new TypeError(`The argument '${name}' must be a plain object, instead got a '${typeof arg}'`)
+  }
+}
+
+function ensureIsFunction (arg, name = 'arg') {
   if (arg !== null && typeof arg !== 'function') {
@@ -357,4 +382,4 @@ throw new TypeError(`The argument '${name}' must be a function, instead got a '${typeof arg}'`)
 module.exports = fp(fastifyCloudEvents, {
-  fastify: '^2.1.0',
+  fastify: '^2.7.1',
   name: 'fastify-cloudevents'
 })

No alert changes

Improved metrics

Total package byte prevSize

63641

7.04%

Lines of code

886

5.35%

Number of lines in readme file

144

5.11%

Dependency changes

• + Added

  cloudevent@0.6.0
  (transitive)

• - Removed

  cloudevent@0.5.0
  (transitive)

• Updated

  cloudevent@~0.6.0

• Updated

  fast-json-stringify@^1.15.6