ref(utils): Add property flag to skip normalization

Author: Luca Forstner

packages/utils/src/normalize.ts

@@ -33,7 +33,7 @@ type ObjOrArray<T> = { [key: string]: T };
  */
 export function normalize(input: unknown, depth: number = +Infinity, maxProperties: number = +Infinity): any {
   try {
-    // since we're at the outermost level, there is no key
+    // since we're at the outermost level, we don't provide a key
     return visit('', input, depth, maxProperties);
   } catch (err) {
     return { ERROR: `**non-serializable** (${err})` };
@@ -98,17 +98,27 @@ function visit(
     return stringified;
   }
 
-  // We're also done if we've reached the max depth
-  if (depth === 0) {
-    // At this point we know `serialized` is a string of the form `"[object XXXX]"`. Clean it up so it's just `"[XXXX]"`.
-    return stringified.replace('object ', '');
-  }
+  // From here on, we can assert that `value` is either an object or an array!
 
   // If we've already visited this branch, bail out, as it's circular reference. If not, note that we're seeing it now.
   if (memoize(value)) {
     return '[Circular ~]';
   }
 
+  // Do not normalize objects that we know have already been normalized. This MUST be below the circ-ref check otherwise
+  // we might somehow accidentally produce circular references by skipping normalization.
+  // As a general rule, the "__sentry_skip_normalization__" property should only be used sparingly and only should only
+  // be set on objects that have already been normalized.
+  if ((value as ObjOrArray<unknown>)['__sentry_skip_normalization__']) {
+    return value as ObjOrArray<unknown>;
+  }
+
+  // We're also done if we've reached the max depth
+  if (depth === 0) {
+    // At this point we know `serialized` is a string of the form `"[object XXXX]"`. Clean it up so it's just `"[XXXX]"`.
+    return stringified.replace('object ', '');
+  }
+
   // At this point we know we either have an object or an array, we haven't seen it before, and we're going to recurse
   // because we haven't yet reached the max depth. Create an accumulator to hold the results of visiting each
   // property/entry, and keep track of the number of items we add to it.

packages/utils/test/normalize.test.ts

@@ -4,6 +4,7 @@
 
 import * as isModule from '../src/is';
 import { normalize } from '../src/normalize';
+import { addNonEnumerableProperty } from '../src/object';
 import * as stacktraceModule from '../src/stacktrace';
 
 describe('normalize()', () => {
@@ -504,4 +505,52 @@ describe('normalize()', () => {
       qux: '[Function: qux]',
     });
   });
+
+  describe.only('skips normalizing objects marked with a non-enumerable property __sentry_skip_normalization__', () => {
+    test('by leaving non-serializable values intact', () => {
+      const someFun = () => undefined;
+      const alreadyNormalizedObj = {
+        nan: NaN,
+        fun: someFun,
+      };
+
+      addNonEnumerableProperty(alreadyNormalizedObj, '__sentry_skip_normalization__', true);
+
+      const result = normalize(alreadyNormalizedObj);
+      expect(result).toEqual({
+        nan: NaN,
+        fun: someFun,
+      });
+    });
+
+    test('by ignoring normalization depth', () => {
+      const alreadyNormalizedObj = {
+        three: {
+          more: {
+            layers: '!',
+          },
+        },
+      };
+
+      addNonEnumerableProperty(alreadyNormalizedObj, '__sentry_skip_normalization__', true);
+
+      const obj = {
+        foo: {
+          bar: {
+            baz: alreadyNormalizedObj,
+            boo: {
+              bam: {
+                pow: 'poof',
+              },
+            },
+          },
+        },
+      };
+
+      const result = normalize(obj, 4);
+
+      expect(result?.foo?.bar?.baz?.three?.more?.layers).toBe('!');
+      expect(result?.foo?.bar?.boo?.bam?.pow).not.toBe('poof');
+    });
+  });
 });