Source: builder.js

  1. /*
  2.  * Copyright 2018-2022 the original author or authors.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  *     http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Unless required by applicable law or agreed to in writing, software
  11.  * distributed under the License is distributed on an "AS IS" BASIS,
  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13.  * See the License for the specific language governing permissions and
  14.  * limitations under the License.
  15.  */
  16. 'use strict'
  18. /**
  19.  * Builder:
  20.  * Utility module to export builder functions useful for creating
  21.  * values (grouped or not) to use in Cloudevents.
  22.  * Should not be used outside of the plugin.
  23.  * @module utility
  24.  */
  26. /**
  27.  * Get a reference to CloudEvent class definition and related utilities.
  28.  * See {@link CloudEvent}.
  29.  * @private
  30.  */
  31. const { CloudEvent, CloudEventTransformer } = require('cloudevent')
  33. /**
  34.  * Utility function for creating grouped values to use in Cloudevents.
  35.  * Should not be used outside of the plugin.
  36.  *
  37.  * @param {!object} options configuration options
  38.  * @return {object} an object with builder functions (configured) to use
  39.  * @private
  40.  */
  41. function builder (options = {}) {
  42.   const {
  43.     pluginName,
  44.     pluginVersion,
  45.     serverUrl,
  46.     serverUrlMode,
  47.     baseNamespace,
  48.     idGenerator,
  49.     includeHeaders,
  50.     includeRedundantAttributes,
  51.     cloudEventOptions,
  52.     cloudEventExtensions
  53.   } = options
  55.   return {
  56.     /**
  57.      * Build the value for the source field of the CloudEvent,
  58.      * depending on the plugin configuration of options
  59.      * `serverUrlMode`, `serverUrl`,
  60.      * and the uri part of the current request.
  61.      * Note that this is mainly for usage inside the plugin,
  62.      * but in some cases could be useful even outside.
  63.      *
  64.      * @param {string} [url='']  the uri part of the current request
  65.      * @return {string} the source value to use, as a string
  66.      * @private
  67.      */
  68.     buildSourceUrl (url = '') {
  69.       let sourceUrl
  70.       switch (serverUrlMode) {
  71.         case null:
  72.         case 'pluginAndRequestSimplified':
  73.           sourceUrl = serverUrl + CloudEventTransformer.uriStripArguments(url)
  74.           break
  75.         case 'pluginAndRequestUrl':
  76.           sourceUrl = serverUrl + url
  77.           break
  78.         case 'pluginServerUrl':
  79.           sourceUrl = serverUrl
  80.           break
  81.         case 'requestUrl':
  82.           sourceUrl = url
  83.           break
  84.         default:
  85.           throw new Error(`Illegal value for serverUrlMode: '${serverUrlMode}'`)
  86.       }
  87.       return sourceUrl
  88.     },
  90.     /**
  91.      * Extract and build the value for the client IP address,
  92.      * useful to add into the CloudEvent in a custom attribute inside data,
  93.      * otherwise nothing.
  94.      *
  95.      * @param {!object} request the request
  96.      * @return {string} the IP address, as a string or undefined
  97.      * @private
  98.      */
  99.     buildClientIP (request) {
  100.       if (request === undefined || request === null) {
  101.         throw new Error('Illegal value for request: undefined or null')
  102.       }
  103.       return request.ip || undefined
  104.     },
  106.     /**
  107.      * Extract and build the value for the HTTP headers,
  108.      * useful to add into the CloudEvent in a custom attribute inside data.
  109.      * If plugin flag 'includeHeaders' is enabled, headers will be returned,
  110.      * otherwise nothing.
  111.      * Note that some config options for builders are used here.
  112.      *
  113.      * @param {!object} request the request
  114.      * @return {string} HTTP request headers, as a string, or undefined
  115.      * @private
  116.      */
  117.     buildHeaders (request) {
  118.       if (request === undefined || request === null) {
  119.         throw new Error('Illegal value for request: undefined or null')
  120.       }
  121.       const headers = (includeHeaders === null || includeHeaders === false) ? undefined : request.headers
  122.       return headers
  123.     },
  125.     /**
  126.      * Extract and build values from the given arguments,
  127.      * and returns them inside a wrapper object.
  128.      *
  129.      * @param {!object} request the request
  130.      * @return {object} an object containing headers, source URL, the IP address
  131.      * @private
  132.      */
  133.     buildValues (request) {
  134.       const clientIp = this.buildClientIP(request)
  135.       const headers = this.buildHeaders(request)
  136.       const sourceUrl = this.buildSourceUrl(request.raw.url)
  137.       return { clientIp, headers, sourceUrl }
  138.     },
  140.     /**
  141.      * Extract some values from the given arguments,
  142.      * and returns them inside a wrapper object
  143.      * to be used in a CloudEvent data (sub-)property.
  144.      *
  145.      * @param {!object} request the request
  146.      * @return {object} an object containing extracted attributes
  147.      * @private
  148.      */
  149.     buildRequestDataForCE (request) {
  150.       return {
  151.         id: request.id,
  152.         headers: this.buildHeaders(request),
  153.         clientIp: this.buildClientIP(request),
  154.         params: request.params,
  155.         query: request.query,
  156.         body: request.body,
  157.         method: request.raw.method,
  158.         url: request.raw.url
  159.       }
  160.     },
  162.     /**
  163.      * Extract some values from the given arguments,
  164.      * and returns them inside a wrapper object
  165.      * to be used in a CloudEvent data (sub-)property.
  166.      *
  167.      * @param {!object} reply the reply
  168.      * @return {object} an object containing extracted attributes
  169.      * @private
  170.      */
  171.     buildReplyDataForCE (reply) {
  172.       return {
  173.         statusCode: reply.raw.statusCode,
  174.         statusMessage: reply.raw.statusMessage,
  175.         finished: reply.raw.finished
  176.       }
  177.     },
  179.     /**
  180.      * Extract some values from the given arguments,
  181.      * and returns them inside a wrapper object
  182.      * to be used in a CloudEvent data (sub-)property.
  183.      * Note that some config options for builders are used here.
  184.      *
  185.      * @param {object} [description='']  the description (maybe related to the event)
  186.      * @return {object} an object containing extracted attributes
  187.      * @private
  188.      */
  189.     buildPluginDataForCE (description = '') {
  190.       return {
  191.         timestamp: CloudEventTransformer.timestampToNumber(),
  192.         description,
  193.         name: pluginName,
  194.         version: pluginVersion
  195.       }
  196.     },
  198.     /**
  199.      * Build a CloudEvent instance from the given arguments,
  200.      * useful for simplify plugin hooks.
  201.      * If plugin flag 'includeRedundantAttributes' is enabled,
  202.      * some redundant attributes will be added to data.
  203.      * Note that some config options for builders are used here.
  204.      *
  205.      * @param {!string} hookName the name of the hook
  206.      * @param {!object} request the request
  207.      * @param {object} reply the reply
  208.      * @param {object} payload the payload
  209.      * @return {object} the CloudEvent instance
  210.      * @private
  211.      */
  212.     buildCloudEventForHook (hookName, request, reply, payload) {
  213.       if (!hookName || !request) {
  214.         throw new Error('Illegal arguments: mandatory argument undefined or null')
  215.       }
  216.       const ceData = {
  217.         request: this.buildRequestDataForCE(request),
  218.         reply: (reply === null) ? undefined : this.buildReplyDataForCE(reply),
  219.         payload
  220.       }
  221.       if (includeRedundantAttributes !== null && includeRedundantAttributes === true) {
  222.         ceData.id = request.id
  223.         ceData.timestamp = CloudEventTransformer.timestampToNumber()
  224.       }
  225.       const ce = new CloudEvent(idGenerator.next().value,
  226.         `${baseNamespace}.${hookName}`,
  227.         this.buildSourceUrl(request.raw.url),
  228.         ceData,
  229.         cloudEventOptions,
  230.         cloudEventExtensions
  231.       )
  232.       return ce
  233.     }
  234.   }
  235. }
  237. module.exports = builder