feat(helpers): support hapi request object to http formatters (#51)

Author: trentm

helpers/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add support for the hapi request object being passed to `formatHttpRequest`
+  and `formatHttpResponse`.
 - Fix the setting of the remote IP and port
   [ECS client fields](https://www.elastic.co/guide/en/ecs/current/ecs-client.html):
   `client.address`, `client.ip`, `client.port`. This also supports using

helpers/README.md

@@ -46,7 +46,7 @@ of objects with circular references. This generally means that ecs-logging-nodej
 libraries will throw a "Converting circular structure to JSON" exception if an
 attempt is made to log an object with circular references.
 
-### `formatError`
+### `formatError(obj, err)`
 
 A function that adds [ECS Error fields](https://www.elastic.co/guide/en/ecs/current/ecs-error.html)
 for a given `Error` object.
@@ -79,56 +79,93 @@ metadata field passed to a logging statement. E.g.
 `log.warn({err: myErr}, '...')` for pino, `log.warn('...', {err: myErr})`
 for winston.
 
-### `formatHttpRequest`
+### `formatHttpRequest(obj, req)`
 
 Function that enhances an ECS object with http request data.
-The request object should be Node.js's core
-[`http.IncomingMessage`](https://nodejs.org/api/all.html#http_class_http_incomingmessage),
-or [Express's request object](https://expressjs.com/en/5x/api.html#req) that
-extends it.
+The given request object, `req`, must be one of the following:
+- Node.js's core [`http.IncomingMessage`](https://nodejs.org/api/all.html#http_class_http_incomingmessage),
+- [Express's request object](https://expressjs.com/en/5x/api.html#req) that extends IncomingMessage, or
+- a [hapi request object](https://hapi.dev/api/#request).
 
 ```js
+const http = require('http')
 const { formatHttpRequest } = require('@elastic/ecs-helpers')
-const ecs = {
-  '@timestamp': new Date().toISOString(),
-  'log.level': 'info',
-  message: 'hello world',
-  log: {
-    logger: 'test'
-  },
-  ecs: {
-    version: '1.4.0'
-  }
-}
 
-formatHttpRequest(ecs, request)
-console.log(ecs)
+http.createServer(function (req, res) {
+  res.end('hi')
+
+  const obj = {}
+  formatHttpRequest(obj, req)
+  console.log('obj:', JSON.stringify(obj, null, 4))
+}).listen(3000)
 ```
 
-### `formatHttpResponse`
+Running this and making a request via `curl http://localhost:3000/` will
+print something close to:
+
+```
+obj: {
+    "http": {
+        "version": "1.1",
+        "request": {
+            "method": "get",
+            "headers": {
+                "host": "localhost:3000",
+                "accept": "*/*"
+            }
+        }
+    },
+    "url": {
+        "full": "http://localhost:3000/",
+        "path": "/"
+    },
+    "client": {
+        "address": "::1",
+        "ip": "::1",
+        "port": 61969
+    },
+    "user_agent": {
+        "original": "curl/7.64.1"
+    }
+}
+```
+
+### `formatHttpResponse(obj, res)`
 
 Function that enhances an ECS object with http response data.
-The response object should be Node.js's core
-[`http.ServerResponse`](https://nodejs.org/api/all.html#http_class_http_serverresponse),
-or [Express's response object](https://expressjs.com/en/5x/api.html#res) that
-extends it.
+The given request object, `req`, must be one of the following:
+- Node.js's core [`http.ServerResponse`](https://nodejs.org/api/all.html#http_class_http_serverresponse),
+- [Express's response object](https://expressjs.com/en/5x/api.html#res) that extends ServerResponse, or
+- a [hapi **request** object](https://hapi.dev/api/#request)
 
 ```js
-const { formatHttpResponse } = require('@elastic/ecs-helpers')
-const ecs = {
-  '@timestamp': new Date().toISOString(),
-  'log.level': 'info',
-  message: 'hello world',
-  log: {
-    logger: 'test'
-  },
-  ecs: {
-    version: '1.4.0'
-  }
-}
+const http = require('http')
+const { formatHttpRequest } = require('@elastic/ecs-helpers')
+
+http.createServer(function (req, res) {
+  res.setHeader('Foo', 'Bar')
+  res.end('hi')
+
+  const obj = {}
+  formatHttpResponse(obj, res)
+  console.log('obj:', JSON.stringify(obj, null, 4))
+}).listen(3000)
+```
+
+Running this and making a request via `curl http://localhost:3000/` will
+print something close to:
 
-formatHttpResponse(ecs, request)
-console.log(ecs)
+```
+rec: {
+    "http": {
+        "response": {
+            "status_code": 200,
+            "headers": {
+                "foo": "Bar"
+            }
+        }
+    }
+}
 ```
 
 ## License

helpers/lib/http-formatters.js

@@ -18,6 +18,13 @@
 'use strict'
 
 function formatHttpRequest (ecs, req) {
+  if (req.raw && req.raw.req && req.raw.req.httpVersion) {
+    // This looks like a hapi request object (https://hapi.dev/api/#request),
+    // use the raw Node.js http.IncomingMessage that it references.
+    // TODO: Use hapi's already parsed `req.url` for speed.
+    req = req.raw.req
+  }
+
   const {
     id,
     method,
@@ -100,6 +107,12 @@ function formatHttpRequest (ecs, req) {
 }
 
 function formatHttpResponse (ecs, res) {
+  if (res.raw && res.raw.res && typeof (res.raw.res.getHeaders) === 'function') {
+    // This looks like a hapi request object (https://hapi.dev/api/#request),
+    // use the raw Node.js http.ServerResponse that it references.
+    res = res.raw.res
+  }
+
   const { statusCode } = res
   ecs.http = ecs.http || {}
   ecs.http.response = ecs.http.response || {}

helpers/package.json

@@ -26,6 +26,7 @@
     "fast-json-stringify": "^2.4.1"
   },
   "devDependencies": {
+    "@hapi/hapi": "^20.1.0",
     "ajv": "^7.0.3",
     "ajv-formats": "^1.5.1",
     "express": "^4.17.1",

helpers/test/hapi.test.js

@@ -0,0 +1,102 @@
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+'use strict'
+
+const http = require('http')
+
+const semver = require('semver')
+const test = require('tap').test
+const hapiNodeEngines = require('@hapi/hapi/package.json').engines.node
+
+const {
+  formatHttpRequest,
+  formatHttpResponse
+} = require('../')
+
+const testOpts = {
+  skip: !semver.satisfies(process.versions.node, hapiNodeEngines) &&
+    `node ${process.version} is not supported by this hapi (${hapiNodeEngines})`
+}
+
+test('hapi res/req serialization', testOpts, t => {
+  const Hapi = require('@hapi/hapi')
+  const server = Hapi.server({ host: 'localhost' })
+
+  server.route({
+    method: 'GET',
+    path: '/',
+    handler: (request, h) => {
+      return h.response('hi')
+        .header('Foo', 'Bar')
+    }
+  })
+
+  server.events.on('response', (request) => {
+    const rec = {}
+    formatHttpRequest(rec, request)
+    formatHttpResponse(rec, request)
+
+    t.deepEqual(rec.user_agent, { original: 'cool-agent' })
+    t.deepEqual(rec.url, {
+      path: '/',
+      full: `http://localhost:${server.info.port}/`
+    })
+    t.deepEqual(rec.http, {
+      version: '1.1',
+      request: {
+        method: 'get',
+        headers: {
+          host: `localhost:${server.info.port}`,
+          connection: 'close'
+        }
+      },
+      response: {
+        status_code: 200,
+        headers: {
+          foo: 'Bar',
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': 'no-cache',
+          'accept-ranges': 'bytes'
+        },
+        body: {
+          bytes: 2
+        }
+      }
+    })
+    // https://www.elastic.co/guide/en/ecs/current/ecs-client.html fields
+    t.ok(rec.client, 'client fields are set')
+    t.ok(rec.client.address === '127.0.0.1' || rec.client.address === '::ffff:127.0.0.1',
+      'client.address is set')
+    t.ok(rec.client.ip === rec.client.address,
+      'client.address duplicated to client.ip')
+    t.equal(typeof (rec.client.port), 'number')
+
+    server.stop().then(function () {
+      t.end()
+    })
+  })
+
+  server.start().then(function () {
+    t.comment('hapi server running on %s', server.info.uri)
+
+    // Make a request so we trigger a 'response' event above.
+    const req = http.get(`http://localhost:${server.info.port}/`,
+      { headers: { 'user-agent': 'cool-agent' } })
+    req.on('error', t.ifErr)
+  })
+})