chore: initial commit of hooks

Author: bizob2828

.gitignore

@@ -0,0 +1 @@
+node_modules

.npmrc

@@ -0,0 +1,2 @@
+package-lock=false
+

README.md

@@ -0,0 +1,68 @@
+# Tracing Hooks
+This repository contains a ESM loader for injecting tracing channel hooks into Node.js modules. It also has a patch ofr Module to be used to patch CJS modules.
+
+
+## Usage
+
+To load esm loader:
+
+```js
+import { register } from 'node:module';
+const packages = new Set('pkg1', 'pkg2');
+const instrumentations = [
+  {
+    channelName: 'channel1',
+    module: { name: 'pkg1', verisonRange: '>=1.0.0', filePath: 'index.js' },
+    functionQuery: {
+      className: 'Class1',
+      methodName: 'method1', 
+      kind: 'Async'
+    }
+  },
+  {
+    channelName: 'channel2',
+    module: { name: 'pkg2', verisonRange: '>=1.0.0', filePath: 'index.js' },
+    functionQuery: {
+      className: 'Class2,
+      methodName: 'method2', 
+      kind: 'Sync'
+    }
+  }
+]
+
+register('@apm-js-collab/tracing-hooks/hook.mjs', import.meta.url, {
+  data: { instrumentations, packages }
+});
+```
+
+To load CJS patch:
+
+```js
+const ModulePatch = require('@apm-js-collab/tracing-hooks')
+const packages = new Set('pkg1', 'pkg2');
+const instrumentations = [
+  {
+    channelName: 'channel1',
+    module: { name: 'pkg1', verisonRange: '>=1.0.0', filePath: 'index.js' },
+    functionQuery: {
+      className: 'Class1',
+      methodName: 'method1', 
+      kind: 'Async'
+    }
+  },
+  {
+    channelName: 'channel2',
+    module: { name: 'pkg2', verisonRange: '>=1.0.0', filePath: 'index.js' },
+    functionQuery: {
+      className: 'Class2,
+      methodName: 'method2', 
+      kind: 'Sync'
+    }
+  }
+]
+
+
+const modulePatch = new ModulePatch({ instrumentations, packages });
+modulePatch.patch()
+```
+

hook.mjs

@@ -0,0 +1,59 @@
+'use strict'
+import createDebug from 'debug';
+import { readFile } from 'node:fs/promises'
+import { create } from '@apm-js-collab/code-transformer'
+import parse from 'module-details-from-path'
+import { fileURLToPath } from 'node:url'
+import getPackageVersion from './lib/get-package-version.js'
+const debug = createDebug('@apm-js-collab/tracing-hooks:esm-hook')
+const transformers = new Map()
+let instrumentator = null
+let packages 
+
+export async function initialize(data) {
+  instrumentator = create(data?.instrumentations || [])
+  packages = data?.packages || new Set()
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  const url = await nextResolve(specifier, context)
+  const resolvedModule = parse(url.url)
+  if (resolvedModule && packages.has(resolvedModule.name)) {
+    const path = fileURLToPath(resolvedModule.basedir)
+    const version = getPackageVersion(path)
+    const transformer = instrumentator.getTransformer(resolvedModule.name, version, resolvedModule.path)
+    if (transformer) {
+      transformers.set(url.url, transformer)
+    }
+  }
+  return url
+}
+
+export async function load(url, context, nextLoad) {
+  const result = await nextLoad(url, context)
+  if (transformers.has(url) === false) {
+    return result
+  }
+
+  if (result.format === 'commonjs') {
+    const parsedUrl = new URL(result.responseURL ?? url)
+    result.source ??= await readFile(parsedUrl)
+  }
+
+  const code = result.source
+  if (code) {
+    const transformer = transformers.get(url)
+    try {
+      const transformedCode = transformer.transform(code.toString('utf8'), 'unknown')
+      result.source = transformedCode
+      result.shortCircuit = true
+    } catch(err) {
+      debug('Error transforming module %s: %o', filename, error)
+    } finally {
+      transformer.free()
+    }
+  }
+
+  return result
+}
+

index.js

@@ -0,0 +1,67 @@
+'use strict'
+const { create } = require('@apm-js-collab/code-transformer')
+const Module = require('node:module')
+const parse = require('module-details-from-path')
+const getPackageVersion = require('./lib/get-package-version')
+const debug = require('debug')('@apm-js-collab/tracing-hooks:module-patch')
+
+class ModulePatch {
+  constructor({ packages = new Set(), instrumentations = [] } = {}) {
+    this.packages = packages
+    this.instrumentator = create(instrumentations)
+    this.transformers = new Map()
+    this.resolve = Module._resolveFilename
+    this.compile = Module.prototype._compile
+  }
+
+  /**
+   * Patches the Node.js module class methods that are responsible for resolving filePaths and compiling code.
+   * If a module is found that has an instrumentator, it will transform the code before compiling it
+   * with tracing channel methods.
+   */
+  patch() {
+    const self = this
+    Module._resolveFilename = function wrappedResolveFileName() {
+      const resolvedName = self.resolve.apply(this, arguments)
+      const resolvedModule = parse(resolvedName)
+      if (resolvedModule && self.packages.has(resolvedModule.name)) {
+        const version = getPackageVersion(resolvedModule.basedir, resolvedModule.name)
+        const transformer = self.instrumentator.getTransformer(resolvedModule.name, version, resolvedModule.path)
+        if (transformer) {
+          self.transformers.set(resolvedName, transformer)
+        }
+      }
+      return resolvedName
+    }
+
+    Module.prototype._compile = function wrappedCompile(...args) {
+      const [content, filename] = args
+      if (self.transformers.has(filename)) {
+        const transformer = self.transformers.get(filename)
+        try {
+          const transformedCode = transformer.transform(content, 'unknown')
+          args[0] = transformedCode
+        } catch (error) {
+          debug('Error transforming module %s: %o', filename, error)
+        } finally {
+          transformer.free()
+        }
+      }
+
+      return self.compile.apply(this, args)
+    }
+  }
+
+  /**
+   * Clears all the transformers and restores the original Module methods that were wrapped.
+   * **Note**: This is intended to be used in testing only.
+   */
+  unpatch() {
+    this.transformers.clear()
+    Module._resolveFilename = this.resolve
+    Module.prototype._compile = this.compile
+  }
+}
+
+module.exports = ModulePatch
+

lib/get-package-version.js

@@ -0,0 +1,30 @@
+'use strict'
+const { readFileSync } = require('node:fs')
+const { join } = require('node:path')
+
+const packageVersions = new Map()
+
+/**
+ * Retrieves the version of a package from its package.json file.
+ * If the package.json file cannot be read, it defaults to the Node.js version.
+ * @param {string} baseDir - The base directory where the package.json file is located.
+ * @returns {string} The version of the package or the Node.js version if the package.json cannot be read.
+ */
+function getPackageVersion(baseDir) {
+  if (packageVersions.has(baseDir)) {
+    return packageVersions.get(baseDir)
+  }
+
+  try {
+    const packageJsonPath = join(baseDir, 'package.json')
+    const jsonFile = readFileSync(packageJsonPath)
+    const { version } = JSON.parse(jsonFile)
+    packageVersions.set(baseDir, version)
+    return version
+  } catch {
+    return process.version.slice(1)
+  }
+}
+
+module.exports = getPackageVersion
+

package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@apm-js-collab/tracing-hooks",
+  "version": "0.0.1",
+  "description": "CJS and ESM hooks for orchestrion",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+    "repository": {
+    "type": "git",
+    "url": "https://github.com/apm-js-collab/tracing-hooks.git"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "files": [
+    "index.js",
+    "hook.mjs",
+    "lib"
+  ],
+  "dependencies": {
+    "@apm-js-collab/code-transformer": "^0.6.0",
+    "debug": "^4.4.1",
+    "module-details-from-path": "^1.0.4"
+  }
+}