Fetch

package.json

@@ -9,11 +9,11 @@
     }
   },
   "devDependencies": {
+    "@hapi/hapi": "^20.0.0",
     "@smithy/config-resolver": "^2.0.15",
     "@smithy/middleware-stack": "^2.0.6",
     "@smithy/node-config-provider": "^2.1.3",
     "@smithy/smithy-client": "^2.1.11",
-    "@hapi/hapi": "^20.0.0",
     "@types/chai": "^4.2.12",
     "@types/koa": "^2.11.3",
     "@types/mocha": "^8.0.0",
@@ -45,7 +45,7 @@
     "grunt-contrib-clean": "^1.0.0",
     "grunt-jsdoc": "^2.4.0",
     "koa": "^2.13.0",
-    "lerna": "^5.5.2",
+    "lerna": "^5.6.2",
     "mocha": "^10.2.0",
     "nock": "^13.2.9",
     "nyc": "^15.1.0",
@@ -66,6 +66,7 @@
     "aws-xray-sdk-core": "file:packages/core",
     "aws-xray-sdk-express": "file:packages/express",
     "aws-xray-sdk-fastify": "file:sdk_contrib/fastify",
+    "aws-xray-sdk-fetch": "file:sdk_contrib/fetch",
     "aws-xray-sdk-hapi": "file:sdk_contrib/hapi",
     "aws-xray-sdk-koa2": "file:sdk_contrib/koa",
     "aws-xray-sdk-mysql": "file:packages/mysql",

packages/core/lib/aws-xray.d.ts

@@ -58,6 +58,7 @@ export { middleware };
 export {
   getNamespace,
   resolveSegment,
+  resolveManualSegmentParams,
   getSegment,
   setSegment,
   isAutomaticMode,

packages/core/lib/aws-xray.js

@@ -276,6 +276,17 @@ var AWSXRay = {
 
   resolveSegment: contextUtils.resolveSegment,
 
+
+  /**
+   * Resolves the segment or subsegment given manual mode and params on the call required.
+   * @param [Segment|Subsegment] segment - The segment manually provided via params.XraySegment, if provided.
+   * @returns {Segment|Subsegment}
+   * @alias module:context_utils.resolveManualSegmentParams
+   * @see module.context_utils.resolveManualSegmentParams
+   */
+
+  resolveManualSegmentParams: contextUtils.resolveManualSegmentParams,
+
   /**
    * Returns the current segment or subsegment. For use with automatic mode only.
    * @memberof AWSXRay

packages/core/lib/context_utils.d.ts

@@ -6,6 +6,8 @@ export function getNamespace(): Namespace;
 
 export function resolveSegment(segment?: Segment | Subsegment | null): Segment | Subsegment | undefined;
 
+export function resolveManualSegmentParams(segment?: Segment | Subsegment | null): Segment | Subsegment | undefined;
+
 export function getSegment(): Segment | Subsegment | undefined;
 
 export function setSegment(segment: Segment | Subsegment): void;

packages/core/package.json

@@ -55,4 +55,4 @@
   ],
   "license": "Apache-2.0",
   "repository": "https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core"
-}
+}

sdk_contrib/fetch/.eslintignore

@@ -0,0 +1 @@
+dist

sdk_contrib/fetch/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+    "extends": "../../.eslintrc.json"
+}

sdk_contrib/fetch/README.md

@@ -0,0 +1,45 @@
+# fetch-xray
+
+A patcher for AWSXRay to support fetch, implemented via either the [node-fetch module](https://www.npmjs.com/package/node-fetch) or the built-in 
+global fetch support starting with [NodeJS 18](https://nodejs.org/en/blog/announcements/v18-release-announce).
+
+## Usage
+
+```js
+const { captureFetchGlobal } = require('aws-xray-sdk-fetch');
+
+// To use globally defined fetch (available in NodeJS 18+)
+const fetch = captureFetchGloba();
+const result = await fetch('https://foo.com');
+
+// To use node-fetch module
+const { captureFetchModule } = require('aws-xray-sdk-fetch');
+const fetchModule = require('node-fetch');
+const fetch = captureFetchModule(fetchModule); // Note, first parameter *must* be the node-fetch module
+const result = await fetch('https://foo.com');
+```
+
+There are two optional parameters you can pass when calling `captureFetchGlobal` / `captureFetchModule`:
+
+* **downstreamXRayEnabled**: when True, adds a "traced:true" property to the subsegment so the AWS X-Ray service expects a corresponding segment from the downstream service (default = False)
+* **subsegmentCallback**: a callback that is called with the subsegment, the fetch request, the fetch response and any error issued, allowing custom annotations and metadata to be added
+
+TypeScript bindings for the capture functions are included.
+
+## Testing
+
+Unit and integration tests can be run using `npm run test`.  Typings file tess can be run using `npm run test-d`.
+
+## Errata
+
+1. This package CommonJS to conform with the rest of the AWSXRay codebase.  As such, it is incompatible with node-fetch 3, which is ESM only.  As such, it is written
+to be compatible with [node-fetch version 2](https://www.npmjs.com/package/node-fetch#CommonJS), which should still receive critical fixes.  If you are using global
+fetch (available in NodeJS 18+) then this isn't an issue for you.
+
+2. This package is designed working under the assumption that the NodeJS implementation of fetch is compatible with node-fetch, albeit with its own separate, 
+built-in typings.  If NodeJS takes fetch in a different direction (breaks compatibility) then that would most likely break this package.  There is no indication that
+I could find that this will happen, but throwing it out there "just in case".
+
+## Contributors
+
+- [Jason Terando](https://github.com/jasonterando)

sdk_contrib/fetch/lib/fetch_p.d.ts

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { Subsegment } from 'aws-xray-sdk-core/lib/aws-xray';
+import * as fetchModule from 'node-fetch';
+
+type FetchModuleType = typeof fetchModule;
+
+type fetchModuleFetch = (url: URL | fetchModule.RequestInfo, init?: fetchModule.RequestInit | undefined) => Promise<fetchModule.Response>;
+
+export function captureFetchGlobal(
+  downstreamXRayEnabled?: boolean,
+  subsegmentCallback?: (subsegment: Subsegment, req: Request, res: Response | null, error: Error) => void):
+  typeof globalThis.fetch;
+
+export function captureFetchModule(
+  fetch: FetchModuleType,
+  downstreamXRayEnabled?: boolean,
+  subsegmentCallback?: (subsegment: Subsegment, req: fetchModule.Request, res: fetchModule.Response | null, error: Error) => void):
+  (url: URL | fetchModule.RequestInfo, init?: fetchModule.RequestInit | undefined) => Promise<fetchModule.Response>;
+

sdk_contrib/fetch/lib/fetch_p.js

@@ -0,0 +1,163 @@
+/**
+ * @module fetch_p
+ */
+
+/**
+ * This module patches the global fetch instance for NodeJS 18+
+ */
+const AWSXRay = require('aws-xray-sdk-core');
+const utils = AWSXRay.utils;
+const getLogger = AWSXRay.getLogger;
+
+/**
+ * Wrap fetch global instance for recent NodeJS to automatically capture information for the segment.
+ * This patches the built-in fetch function globally.
+ * @param {boolean} downstreamXRayEnabled - when true, adds a "traced:true" property to the subsegment
+ *   so the AWS X-Ray service expects a corresponding segment from the downstream service.
+ * @param {function} subsegmentCallback - a callback that is called with the subsegment, the fetch request,
+ *   the fetch response and any error issued, allowing custom annotations and metadata to be added.
+ * @alias module:fetch_p.captureFetch
+ */
+function captureFetchGlobal(downstreamXRayEnabled, subsegmentCallback) {
+  if (globalThis.fetch === undefined) {
+    throw new Error('Global fetch is not available in NodeJS');
+  }
+  if (!globalThis.__fetch) {
+    globalThis.__fetch = globalThis.fetch;
+    globalThis.fetch = enableCapture(globalThis.__fetch, globalThis.Request,
+      downstreamXRayEnabled, subsegmentCallback);
+  }
+  return globalThis.fetch;
+}
+
+/**
+ * Wrap fetch module to capture information for the segment.
+ * This patches the fetch function distributed in node-fetch package.
+ * @param {fetch} module - The fetch module
+ * @param {boolean} downstreamXRayEnabled - when true, adds a "traced:true" property to the subsegment
+ *   so the AWS X-Ray service expects a corresponding segment from the downstream service.
+ * @param {function} subsegmentCallback - a callback that is called with the subsegment, the fetch request,
+ *   the fetch response and any error issued, allowing custom annotations and metadata to be added.
+ * @alias module:fetch_p.captureFetchModule
+ */
+function captureFetchModule(module, downstreamXRayEnabled, subsegmentCallback) {
+  if (!module.default) {
+    getLogger().warn('X-ray capture did not find fetch function in module');
+    return null;
+  }
+  if (!module.__fetch) {
+    module.__fetch = module.default;
+    module.default = enableCapture(module.__fetch, module.Request,
+      downstreamXRayEnabled, subsegmentCallback);
+  }
+  return module.default;
+}
+
+const enableCapture = function enableCapture(baseFetchFunction, requestClass, downstreamXRayEnabled, subsegmentCallback) {
+
+  const overridenFetchAsync = async (...args) => {
+    const thisDownstreamXRayEnabled = !!downstreamXRayEnabled;
+    const thisSubsegmentCallback = subsegmentCallback;
+    // Standardize request information
+    const request = typeof args[0] === 'object' ?
+      args[0] :
+      new requestClass(...args);
+
+    // Facilitate the addition of Segment information via the request arguments
+    const params = args.length > 1 ? args[1] : {};
+
+    // Short circuit if the HTTP is already being captured
+    if (request.headers.has('X-Amzn-Trace-Id')) {
+      return await baseFetchFunction(...args);
+    }
+
+    const url = new URL(request.url);
+    const isAutomaticMode = AWSXRay.isAutomaticMode();
+
+    const parent = AWSXRay.resolveSegment(AWSXRay.resolveManualSegmentParams(params));
+    const hostname = url.hostname || url.host || 'Unknown host';
+
+    if (!parent) {
+      let output = '[ host: ' + hostname +
+        (request.method ? (', method: ' + request.method) : '') +
+        ', path: ' + url.pathname + ' ]';
+
+      if (isAutomaticMode) {
+        getLogger().info('RequestInit for request ' + output +
+          ' is missing the sub/segment context for automatic mode. Ignoring.');
+      } else {
+        getLogger().info('RequestInit for request ' + output +
+          ' requires a segment object on the options params as "XRaySegment" for tracing in manual mode. Ignoring.');
+      }
+
+      // Options are not modified, only parsed for logging. We can pass in the original arguments.
+      return await baseFetchFunction(...args);
+    }
+
+    let subsegment;
+    if (parent.notTraced) {
+      subsegment = parent.addNewSubsegmentWithoutSampling(hostname);
+    } else {
+      subsegment = parent.addNewSubsegment(hostname);
+    }
+
+    subsegment.namespace = 'remote';
+
+    request.headers.set('X-Amzn-Trace-Id',
+      'Root=' + (parent.segment ? parent.segment : parent).trace_id +
+      ';Parent=' + subsegment.id +
+      ';Sampled=' + (subsegment.notTraced ? '0' : '1'));
+
+    // Set up fetch call and capture any thrown errors
+    const capturedFetch = async () => {
+      const requestClone = request.clone();
+      let response;
+      try {
+        response = await baseFetchFunction(requestClone);
+
+        if (thisSubsegmentCallback) {
+          thisSubsegmentCallback(subsegment, requestClone, response);
+        }
+
+        const statusCode = response.status;
+        if (statusCode === 429) {
+          subsegment.addThrottleFlag();
+        }
+
+        const cause = utils.getCauseTypeFromHttpStatus(statusCode);
+        if (cause) {
+          subsegment[cause] = true;
+        }
+
+        subsegment.addRemoteRequestData(requestClone, response, thisDownstreamXRayEnabled);
+        subsegment.close();
+        return response;
+      } catch (e) {
+        if (thisSubsegmentCallback) {
+          thisSubsegmentCallback(subsegment, requestClone, response, e);
+        }
+        const madeItToDownstream = (e.code !== 'ECONNREFUSED');
+        subsegment.addErrorFlag();
+        subsegment.addRemoteRequestData(requestClone, response, madeItToDownstream && thisDownstreamXRayEnabled);
+        subsegment.close(e);
+        throw (e);
+      }
+    };
+
+    if (isAutomaticMode) {
+      const session = AWSXRay.getNamespace();
+      return await session.runPromise(async () => {
+        AWSXRay.setSegment(subsegment);
+        return await capturedFetch();
+      });
+    } else {
+      return await capturedFetch();
+    }
+  };
+
+  return overridenFetchAsync;
+};
+
+module.exports.captureFetchGlobal = captureFetchGlobal;
+module.exports.captureFetchModule = captureFetchModule;
+module.exports._fetchEnableCapture = enableCapture;

sdk_contrib/fetch/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "aws-xray-sdk-fetch",
+  "version": "3.5.3",
+  "description": "AWS X-Ray plugin for node-fetch",
+  "author": "Amazon Web Services",
+  "contributors": [
+    "Jason Terando <[email protected]>"
+  ],
+  "main": "lib/fetch_p.js",
+  "files": [
+    "lib"
+  ],
+  "types": "lib/fetch_p.d.ts",
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "mocha --recursive --exit ./test/ -R spec && tsd",
+    "test-d": "tsd"
+  },
+  "engines": {
+    "node": ">= 14.x"
+  },
+  "peerDependencies": {
+    "aws-xray-sdk-core": "^3.5.3"
+  },
+  "keywords": [
+    "amazon",
+    "api",
+    "aws",
+    "fetch",
+    "node-fetch",
+    "xray",
+    "x-ray",
+    "x ray"
+  ],
+  "directories": {
+    "lib": "lib"
+  },
+  "license": "Apache-2.0",
+  "repository": "https://github.com/aws/aws-xray-sdk-node/tree/sdk_contrib/fetch",
+  "devDependencies": {
+    "@types/node-fetch": "^2.6.4",
+    "chai-as-promised": "^7.1.1",
+    "node-fetch": "^2.6.11",
+    "ts-expect": "^1.3.0"
+  },
+  "dependencies": {
+    "tsd": "^0.28.1"
+  }
+}

sdk_contrib/fetch/test-d/index.test-d.ts

@@ -0,0 +1,35 @@
+import * as AWSXRay from 'aws-xray-sdk-core/lib';
+import { captureFetch, captureFetchGlobal, captureFetchModule } from '../lib/fetch_p';
+import * as fetchModule from 'node-fetch';
+import { expectType } from 'ts-expect';
+
+type ModuleFetch = (url: URL | fetchModule.RequestInfo, init?: fetchModule.RequestInit | undefined) => Promise<fetchModule.Response>;
+
+if (globalThis.fetch !== undefined) {
+  function fetchGlobalCallback(subsegment: AWSXRay.Subsegment, req: Request, res: Response | null, error: Error) {
+    console.log({ subsegment, req, res, error });
+  }
+
+  expectType<typeof globalThis.fetch>(captureFetchGlobal());
+  expectType<typeof globalThis.fetch>(captureFetchGlobal(true));
+  expectType<typeof globalThis.fetch>(captureFetchGlobal(false));
+  expectType<typeof globalThis.fetch>(captureFetchGlobal(true, fetchGlobalCallback));
+  expectType<typeof globalThis.fetch>(captureFetchGlobal(false, fetchGlobalCallback));
+
+
+  expectType<typeof globalThis.fetch | ModuleFetch>(captureFetch());
+  expectType<typeof globalThis.fetch | ModuleFetch>(captureFetch(true));
+  expectType<typeof globalThis.fetch | ModuleFetch>(captureFetch(false));
+  expectType<typeof globalThis.fetch | ModuleFetch>(captureFetch(true, fetchGlobalCallback));
+  expectType<typeof globalThis.fetch | ModuleFetch>(captureFetch(false, fetchGlobalCallback));
+}
+
+function fetchModuleCallback(subsegment: AWSXRay.Subsegment, req: fetchModule.Request, res: fetchModule.Response | null, error: Error) {
+  console.log({ subsegment, req, res, error });
+}
+
+expectType<ModuleFetch>(captureFetchModule(fetchModule));
+expectType<ModuleFetch>(captureFetchModule(fetchModule, true));
+expectType<ModuleFetch>(captureFetchModule(fetchModule, false));
+expectType<ModuleFetch>(captureFetchModule(fetchModule, true, fetchModuleCallback));
+expectType<ModuleFetch>(captureFetchModule(fetchModule, false, fetchModuleCallback));