rollbar 2.26.3 → 3.0.0-alpha.1

package/CLAUDE.md

@@ -0,0 +1,201 @@
+## About Rollbar.js
+
+Rollbar.js is the official JavaScript SDK for the Rollbar error monitoring service. This library is not standalone - it works in tandem with the Rollbar platform to help developers detect, diagnose, and fix errors in real-time. The SDK sends error data to Rollbar's cloud service where errors are processed, grouped, and notifications are triggered.
+
+The library works across platforms, supporting both browser and server-side JavaScript including frameworks like React, Angular, Express, and Next.js. Key features include:
+
+- Cross-platform error tracking for client and server-side code
+- Telemetry to provide context around errors (breadcrumbs of events)
+- Automatic error grouping to reduce noise
+- Real-time notifications for critical issues
+- Detailed stack traces with source maps support
+- Distributed tracing and session management
+- Session replay capabilities for reproducing user actions
+
+## Project Structure
+
+```
+src/
+├── browser/      # Browser-specific implementation
+├── server/       # Node.js-specific implementation
+├── react-native/ # React Native implementation
+├── tracing/      # Distributed tracing support
+└── utility/      # Shared utility functions
+```
+
+## Build & Test Commands
+
+- Build: `npm run build` (runs Grunt)
+- Lint: `npm run lint` (ESLint)
+- Test all: `npm run test` (runs both server and browser tests)
+- Test browser only: `npm run test-browser`
+- Test server only: `npm run test-server`
+- Test specific browser test: `grunt test-browser:specificTestName`
+  - Example: `grunt test-browser:transforms`
+- Single test: `./node_modules/.bin/karma start --single-run --files={path/to/test}`
+
+## Modern Development Environment
+
+As of version 3.0.0, the SDK has been updated to use modern JavaScript features with appropriate transpilation:
+
+- **ES Modules**: The codebase supports ES modules (`import/export`) syntax
+- **Target Compatibility**:
+  - Source code uses ECMAScript 2021 features
+  - Builds target ES5 for broad browser compatibility
+  - Lower versions can use the ES5/CommonJS compatible bundles
+- **Build System**:
+  - Webpack 5 with Babel for transpilation
+  - ESLint for code quality
+  - Configurable output formats (UMD, AMD, vanilla)
+- **Minimum Node.js**: Version 18+ for absolute imports
+- **Toolchain Configuration**:
+  - `babel.config.json`: Controls transpilation options
+  - `eslint.config.mjs`: Modern ESLint flat config format
+  - `webpack.config.js`: Manages bundling and output formats
+
+## Code Style Guidelines
+
+- Use single quotes for strings
+- Use camelCase for variables (underscore prefix for private)
+- Indentation: 2 spaces
+- Include trailing commas in multiline objects/arrays
+- Max function complexity: 35
+- Unused parameters prefixed with underscore: `function(a, _unused) {}`
+- No whitespace in empty lines
+- Files should end with exactly one newline
+- Control statements (if, for, while, etc.) MUST use braces and newlines, even for single statements
+- Opening braces should be on the same line as the control statement
+- ESLint is used for enforcing code style
+- Prettier for code formatting
+
+### Documentation vs. Comments
+
+- **Function Documentation (JSDoc/TSDoc)**: Always include comprehensive documentation for functions, classes, and methods using JSDoc/TSDoc format (`/** ... */`). These serve as API documentation, appear in IDE tooltips, and help developers understand purpose, parameters, and return values.
+
+- **Inline Code Comments**: Avoid redundant comments that merely restate what the code is doing. Only add comments to explain:
+  - Why the code works a certain way (decisions and reasoning)
+  - Non-obvious behavior or edge cases
+  - Complex algorithms or business logic
+  - Workarounds for bugs or limitations
+  
+- **Self-documenting Code**: Write clear, readable code that explains itself through descriptive variable/function names and straightforward logic. Well-written code rarely needs explanatory comments.
+
+- **Examples**:
+  ```javascript
+  // BAD - Redundant comment
+  // Add one to x
+  x += 1;
+  
+  // GOOD - Explains the non-obvious "why"
+  // Increment before sending to API to account for zero-indexing
+  x += 1;
+  ```
+
+## SDK Design Principles
+
+- **User Problems Are SDK Improvement Opportunities**: When users encounter integration issues, treat these as SDK design improvements rather than user implementation mistakes.
+  - Focus on enhancing the SDK to be more robust, intuitive and resilient
+  - Implement automatic environment detection and appropriate behavior selection
+  - Design APIs that work correctly across all supported contexts without requiring special user handling
+  - Errors should be informative and suggest correct usage patterns
+  - The burden of complexity should rest with the SDK, not its users
+
+## Error Handling
+
+- Prefer try/catch blocks around risky operations
+- Log errors through Rollbar's own logger system
+- Scrub sensitive fields in error payloads (see package.json defaults)
+- The codebase uses a comprehensive error tracking approach with appropriate levels:
+  - Debug level for development info
+  - Warning level for non-critical issues
+  - Error level for uncaught exceptions
+
+## TypeScript Support
+
+- Type definitions in index.d.ts
+- Add JSDoc types to enable intellisense when needed
+
+## Common Patterns
+
+When working with this codebase, be aware of these patterns:
+
+- Error transformation and normalization before sending
+- Telemetry collection for context
+- Queue-based sending with retry logic
+- Environment and context detection
+- Scrubbing of sensitive data
+
+## Testing Philosophy
+
+- **Analyze Test Failures Objectively**: When tests fail, evaluate both possibilities objectively:
+
+  - The test could be correctly identifying an actual code issue
+  - The test itself might contain errors or invalid expectations
+
+- **Diagnostic Process**:
+
+  1. Examine what the test is expecting vs. what the code actually does
+  2. Consider the intended behavior and design of the system
+  3. If the test is correct and identifying a legitimate bug, fix the code
+  4. If the test contains misconceptions or errors, fix the test
+
+- **Default to Code Quality**: When in doubt and both seem potentially valid, prioritize improving code quality over modifying tests to pass
+
+## Tracing & Session Replay
+
+The `src/tracing/` directory contains an OpenTelemetry-inspired tracing implementation that powers both distributed tracing and session recording features:
+
+### Components
+
+- **Context & ContextManager**: Manages propagation of tracing context through the application
+- **Span**: Represents a unit of work or operation with timing information and attributes
+- **Tracer**: Creates and manages spans for tracking operations
+- **SpanProcessor & SpanExporter**: Processes and exports spans to their destination
+- **Session**: Manages browser session data persistence and creation
+
+### Usage Patterns
+
+- **Tracing initialization**: Initialize via the main Tracing class with appropriate configuration
+- **Context propagation**: Use context to pass trace information between components
+- **Span creation**: Create spans to measure operations with `startSpan()`
+- **Attributes and events**: Add metadata to spans with `setAttribute()` and `addEvent()`
+- **Session management**: Automatically manages user sessions via browser sessionStorage
+
+### Session Replay Implementation
+
+The `src/browser/replay` directory contains the implementation of the Session Replay feature:
+
+- **Recorder**: Core class that integrates with rrweb to record DOM events
+- **ReplayMap**: Manages the mapping between error occurrences and session recordings
+- **Configuration**: Configurable options in `defaults.js` for replay behavior
+
+The Session Replay feature utilizes our tracing infrastructure to:
+
+- Record user interactions using rrweb in a memory-efficient way
+- Store recordings with checkpoints for better performance
+- Generate spans that contain replay events with proper timing
+- Associate recordings with user sessions for complete context
+- Transport recordings to Rollbar servers via the API
+
+### Session Replay Flow
+
+1. **Recording**: The Recorder class continuously records DOM events using rrweb
+2. **Error Occurrence**: When an error occurs, Queue.addItem() calls ReplayMap.add()
+3. **Correlation**: ReplayMap generates a replayId and attaches it to the error
+4. **Coordination**: After successful error submission, Queue triggers ReplayMap.send()
+5. **Transport**: ReplayMap retrieves stored replay data and sends via api.postSpans()
+
+### Testing Infrastructure
+
+- **Unit Tests**: Component-focused tests in `test/replay/unit/`
+- **Integration Tests**: Test component interactions in `test/replay/integration/`
+- **End-to-End Tests**: Full flow verification in `test/replay/integration/e2e.test.js`
+- **Mock Implementation**: `test/replay/util/mockRecordFn.js` provides a deterministic mock of rrweb
+- **Fixtures**: Realistic rrweb events in `test/fixtures/replay/` for testing
+- **Test Tasks**: Custom Grunt tasks for testing replay code specifically
+
+## File Creation Guidelines
+
+- **Newlines**: All new files MUST end with exactly one newline character
+- **Encoding**: Use UTF-8 encoding for all text files
+- **Line Endings**: Use LF (Unix-style) line endings, not CRLF

package/Gruntfile.js

@@ -2,7 +2,6 @@
  * Build and test rollbar.js
  */
 
-
 'use strict';
 
 var glob = require('glob');
@@ -12,7 +11,6 @@ var fs = require('fs');
 
 var webpackConfig = require('./webpack.config.js');
 
-
 function findTests(context) {
   if (context !== 'browser') {
     return {};
@@ -20,7 +18,7 @@ function findTests(context) {
   var files = glob.sync('test/**/!(server.)*.test.js');
   var mapping = {};
 
-  files.forEach(function(file) {
+  files.forEach(function (file) {
     var testName = path.basename(file, '.test.js');
     mapping[testName] = file;
   });
@@ -39,19 +37,19 @@ function buildGruntKarmaConfig(singleRun, tests, reporters) {
           pattern: 'dist/**/*.js',
           included: false,
           served: true,
-          watched: false
+          watched: false,
         },
         {
           pattern: 'src/**/*.js',
           included: false,
           served: true,
-          watched: false
+          watched: false,
         },
         {
           pattern: 'examples/**/*.js',
           included: false,
           served: true,
-          watched: false
+          watched: false,
         },
 
         // Examples HTML, set `included: true`, but they won't be executed or added
@@ -60,9 +58,9 @@ function buildGruntKarmaConfig(singleRun, tests, reporters) {
           pattern: 'examples/**/*.html',
           included: true,
           served: true,
-          watched: false
-        }
-      ]
+          watched: false,
+        },
+      ],
     },
   };
 
@@ -72,20 +70,18 @@ function buildGruntKarmaConfig(singleRun, tests, reporters) {
 
   for (var testName in tests) {
     var testFile = tests[testName];
-    var testConfig = config[testName] = {};
+    var testConfig = (config[testName] = {});
 
     // Special case for testing requirejs integration.
     // Include the requirejs module as a framework so
     // Karma will inclue it in the web page.
     if (testName === 'requirejs') {
-      testConfig.files = [
-        {src: './dist/rollbar.umd.js', included: false}
-      ];
+      testConfig.files = [{ src: './dist/rollbar.umd.js', included: false }];
       // NOTE: requirejs should go first in case the subsequent libraries
       // check for the existence of `define()`
       testConfig.frameworks = ['requirejs', 'expect', 'mocha'];
     } else {
-      testConfig.files = [{src: [testFile]}];
+      testConfig.files = [{ src: [testFile] }];
     }
 
     // Special config for BrowserStack IE tests
@@ -98,8 +94,7 @@ function buildGruntKarmaConfig(singleRun, tests, reporters) {
   return config;
 }
 
-
-module.exports = function(grunt) {
+module.exports = function (grunt) {
   require('time-grunt')(grunt);
 
   var browserTests = findTests('browser');
@@ -117,8 +112,6 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-karma');
   grunt.loadNpmTasks('grunt-webpack');
   grunt.loadNpmTasks('grunt-text-replace');
-  grunt.loadNpmTasks('grunt-vows');
-
 
   var rollbarJsSnippet = fs.readFileSync('dist/rollbar.snippet.js');
   var rollbarjQuerySnippet = fs.readFileSync('dist/plugins/jquery.min.js');
@@ -126,67 +119,127 @@ module.exports = function(grunt) {
   grunt.initConfig({
     pkg: pkg,
     webpack: webpackConfig,
-    vows: {
-      all: {
-        options: {
-          reporter: 'spec'
-        },
-        src: ['test/server.*.test.js']
-      }
-    },
 
     karma: buildGruntKarmaConfig(singleRun, browserTests, reporters),
 
     replace: {
       snippets: {
-        src: ['*.md', 'src/**/*.js', 'examples/*.+(html|js)', 'examples/*/*.+(html|js)', 'docs/**/*.md'],
+        src: [
+          '*.md',
+          'src/**/*.js',
+          'examples/*.+(html|js)',
+          'examples/*/*.+(html|js)',
+          'docs/**/*.md',
+        ],
         overwrite: true,
         replacements: [
           // Main rollbar snippet
           {
-            from: new RegExp('^(.*// Rollbar Snippet)[\n\r]+(.*[\n\r])*(.*// End Rollbar Snippet)', 'm'), // eslint-disable-line no-control-regex
-            to: function(match, index, fullText, captures) {
+            from: new RegExp(
+              '^(.*// Rollbar Snippet)[\n\r]+(.*[\n\r])*(.*// End Rollbar Snippet)',
+              'm',
+            ),
+            to: function (match, index, fullText, captures) {
               captures[1] = rollbarJsSnippet;
               return captures.join('\n');
-            }
+            },
           },
           // jQuery rollbar plugin snippet
           {
-            from: new RegExp('^(.*// Rollbar jQuery Snippet)[\n\r]+(.*[\n\r])*(.*// End Rollbar jQuery Snippet)', 'm'), // eslint-disable-line no-control-regex
-            to: function(match, index, fullText, captures) {
+            from: new RegExp(
+              '^(.*// Rollbar jQuery Snippet)[\n\r]+(.*[\n\r])*(.*// End Rollbar jQuery Snippet)',
+              'm',
+            ),
+            to: function (match, index, fullText, captures) {
               captures[1] = rollbarjQuerySnippet;
               return captures.join('\n');
-            }
+            },
           },
           // README CI link
           {
-            from: new RegExp('(https://github\\.com/rollbar/rollbar\\.js/workflows/Rollbar\\.js%20CI/badge\\.svg\\?branch=v)([0-9a-zA-Z.-]+)'),
-            to: function(match, index, fullText, captures) {
+            from: new RegExp(
+              '(https://github\\.com/rollbar/rollbar\\.js/workflows/Rollbar\\.js%20CI/badge\\.svg\\?branch=v)([0-9a-zA-Z.-]+)',
+            ),
+            to: function (match, index, fullText, captures) {
               captures[1] = pkg.version;
               return captures.join('');
-            }
-          }
-        ]
-      }
-    }
+            },
+          },
+        ],
+      },
+    },
   });
 
   grunt.registerTask('build', ['webpack', 'replace:snippets']);
   grunt.registerTask('default', ['build']);
-  grunt.registerTask('test', ['test-server', 'test-browser']);
+  grunt.registerTask('test', [
+    'test-browser',
+  ]);
   grunt.registerTask('release', ['build', 'copyrelease']);
 
-  grunt.registerTask('test-server', function(_target) {
-    var tasks = ['vows'];
-    grunt.task.run.apply(grunt.task, tasks);
-  });
 
-  grunt.registerTask('test-browser', function(target) {
+  grunt.registerTask('test-browser', function (target) {
     var karmaTask = 'karma' + (target ? ':' + target : '');
     var tasks = [karmaTask];
     grunt.task.run.apply(grunt.task, tasks);
   });
 
+  function findReplayTests() {
+    return Object.keys(browserTests).filter(function (testName) {
+      var testPath = browserTests[testName];
+      return (
+        testPath.includes('test/replay/') ||
+        testPath.includes('test/tracing/') ||
+        testPath.match(/test\/browser\.replay\..*\.test\.js/)
+      );
+    });
+  }
+
+  grunt.registerTask('test-replay', function () {
+    var replayTests = findReplayTests();
+
+    grunt.log.writeln('Running all replay-related tests:');
+    replayTests.forEach(function (testName) {
+      grunt.log.writeln('- ' + testName + ' (' + browserTests[testName] + ')');
+    });
+
+    replayTests.forEach(function (testName) {
+      grunt.task.run('karma:' + testName);
+    });
+  });
+
+  grunt.registerTask('test-replay-unit', function () {
+    var unitTests = findReplayTests().filter(function (testName) {
+      var testPath = browserTests[testName];
+      return testPath.includes('/replay/unit/');
+    });
+
+    grunt.log.writeln('Running replay unit tests:');
+    unitTests.forEach(function (testName) {
+      grunt.log.writeln('- ' + testName + ' (' + browserTests[testName] + ')');
+    });
+
+    unitTests.forEach(function (testName) {
+      grunt.task.run('karma:' + testName);
+    });
+  });
+
+  grunt.registerTask('test-replay-integration', function () {
+    var integrationTests = findReplayTests().filter(function (testName) {
+      var testPath = browserTests[testName];
+      return testPath.includes('/replay/integration/');
+    });
+
+    grunt.log.writeln('Running replay integration tests:');
+    integrationTests.forEach(function (testName) {
+      grunt.log.writeln('- ' + testName + ' (' + browserTests[testName] + ')');
+    });
+
+    integrationTests.forEach(function (testName) {
+      grunt.task.run('karma:' + testName);
+    });
+  });
+
   grunt.registerTask('copyrelease', function createRelease() {
     var version = pkg.version;
     var builds = ['', '.umd'];
@@ -196,11 +249,11 @@ module.exports = function(grunt) {
       var minJs = 'dist/rollbar' + buildName + '.min.js';
 
       var releaseJs = 'release/rollbar' + buildName + '-' + version + '.js';
-      var releaseMinJs = 'release/rollbar' + buildName + '-' + version + '.min.js';
+      var releaseMinJs =
+        'release/rollbar' + buildName + '-' + version + '.min.js';
 
       grunt.file.copy(js, releaseJs);
       grunt.file.copy(minJs, releaseMinJs);
     });
   });
-
 };

package/Makefile

@@ -17,8 +17,8 @@ test-server:
 	@npm run test-server
 	@echo ""
 
-test_ci:
-	@npm run test_ci
+test-ci:
+	@npm run test-ci
 	@echo ""
 
-.PHONY: test test_ci
+.PHONY: test test-ci

package/README.md

@@ -12,21 +12,20 @@
 [![Code Quality: Javascript](https://img.shields.io/lgtm/grade/javascript/g/rollbar/rollbar.js.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/rollbar/rollbar.js/context:javascript)
 [![Total Alerts](https://img.shields.io/lgtm/alerts/g/rollbar/rollbar.js.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/rollbar/rollbar.js/alerts)
 
-
 ---
 
 ## Key benefits of using Rollbar.js are:
+
 - **Cross platform:** Rollbar.js supports both server-side and client-side Javascript, including frameworks such as <a href="https://docs.rollbar.com/docs/react-ts">React</a>, <a href="https://docs.rollbar.com/docs/angular">Angular</a>, <a href="https://docs.rollbar.com/docs/nodejs#using-express">Express</a>, <a href="https://docs.rollbar.com/docs/nextjs">Next.js</a> and more.
 - **Telemetry:** The telemetry timeline provides a list of “breadcrumbs” events that can help developers understand and fix problems in their client-side javascript. <a href="https://docs.rollbar.com/docs/rollbarjs-telemetry">Learn more about telemetry</a>.
 - **Automatic error grouping:** Rollbar aggregates Occurrences caused by the same error into Items that represent application issues. <a href="https://docs.rollbar.com/docs/grouping-occurrences">Learn more about reducing log noise</a>.
 - **Advanced search:** Filter items by many different properties. <a href="https://docs.rollbar.com/docs/search-items">Learn more about search</a>.
 - **Customizable notifications:** Rollbar supports several messaging and incident management tools where your team can get notified about errors and important events by real-time alerts. <a href="https://docs.rollbar.com/docs/notifications">Learn more about Rollbar notifications</a>.
 
-
 ## Setup Instructions
 
 1. [Sign up for a Rollbar account](https://rollbar.com/signup).
-2. For client-side Javascript, follow the [Browser Quick Start](https://docs.rollbar.com/docs/javascript#section-quick-start-browser) instructions.  For Node.js, follow the [Server Quick Start](https://docs.rollbar.com/docs/javascript#section-quick-start-server).
+2. For client-side Javascript, follow the [Browser Quick Start](https://docs.rollbar.com/docs/javascript#section-quick-start-browser) instructions. For Node.js, follow the [Server Quick Start](https://docs.rollbar.com/docs/javascript#section-quick-start-server).
 
 ## Usage and Reference
 
@@ -46,7 +45,6 @@ For bug reports, please [open an issue on GitHub](https://github.com/rollbar/rol
 
 To set up a development environment, you'll need Node.js and npm.
 
-1. `git submodule update --init`
 2. `npm install -D`
 3. `make`
 

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues to `security@rollbar.com`

package/babel.config.json

@@ -0,0 +1,9 @@
+{
+  "parserOpts": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+  },
+  "presets": [
+    "@babel/preset-env"
+  ]
+}

package/bower.json

@@ -1,9 +1,7 @@
 {
   "name": "rollbar",
   "dependencies": {},
-  "main": [
-    "dist/rollbar.umd.js"
-  ],
+  "main": ["dist/rollbar.umd.js"],
   "ignore": [
     "dist/*.nojson*",
     "dist/*.named-amd*",