repro-nest 0.0.219 → 0.0.220

package/README.md

@@ -0,0 +1,335 @@
+# Repro Nest SDK
+
+Capture NestJS request/response data, function traces, and Mongoose activity for
+Repro sessions. This SDK is designed for Nest apps running on Express, with
+optional tracing and masking controls.
+
+## 1) Install
+
+Requirements:
+- Node.js 18+
+- NestJS app using Express (default) and optionally Mongoose 6+
+
+Install the package:
+
+```bash
+npm install repro-nest
+# or
+yarn add repro-nest
+# or
+pnpm add repro-nest
+```
+
+## 2) Configure
+
+At minimum, provide your Repro credentials and wire the middleware. If you want
+function tracing, call `initReproTracing` before importing your `AppModule` so
+Nest classes are instrumented at load time.
+
+```ts
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import mongoose from 'mongoose';
+import {
+  initReproTracing,
+  reproMiddleware,
+  reproMongoosePlugin,
+} from 'repro-nest';
+
+const reproConfig = {
+  appId: process.env.REPRO_APP_ID as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+};
+
+async function bootstrap() {
+  // Enable function tracing before loading your modules.
+  initReproTracing({
+    disableFunctionTypes: ['constructor'],
+    logFunctionCalls: false,
+  });
+
+  // Optional: capture MongoDB queries + document diffs.
+  mongoose.plugin(reproMongoosePlugin(reproConfig));
+
+  const { AppModule } = await import('./app.module');
+  const app = await NestFactory.create(AppModule);
+
+  // Capture request/response payloads for tagged Repro sessions.
+  app.use(reproMiddleware(reproConfig));
+
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+Configuration notes:
+- `REPRO_API_BASE` (optional) overrides the backend base URL used to send data.
+
+### initReproTracing
+
+Enables function tracing. Call this before importing `AppModule` so Nest classes
+are loaded through the tracer.
+
+Options (type -> purpose):
+- `instrument` (boolean): enable or disable instrumentation of loaded modules.
+- `include` (RegExp[]): file path include patterns for instrumentation.
+- `exclude` (RegExp[]): file path exclude patterns for instrumentation.
+- `mode` (string): tracer mode (defaults to `TRACE_MODE` or `trace`).
+- `samplingMs` (number): sampling interval in milliseconds.
+- `disableFunctionTraces` (DisableFunctionTraceConfig[] | null): drop trace events
+  that match rule objects or predicates.
+- `disableFunctionTypes` (TraceRulePattern | null): drop events for matching
+  function kinds (for example, constructors).
+- `disableTraceFiles` (DisableTraceFileConfig | DisableTraceFileConfig[] | null):
+  drop events emitted from matching files.
+- `traceInterceptors` (boolean): include Nest interceptors in traces (default false).
+- `logFunctionCalls` (boolean): log enter/exit events to console.
+
+Type reference:
+- `TraceRulePattern`: `string | number | RegExp | Array<string | number | RegExp>`
+- `DisableFunctionTraceConfig`: `DisableFunctionTraceRule | DisableFunctionTracePredicate`
+- `DisableFunctionTracePredicate`: `(event: TraceEventForFilter) => boolean`
+- `DisableFunctionTraceRule` fields (all accept `TraceRulePattern`):
+  - `fn` / `functionName`: function name substring/regex
+  - `wrapper` / `wrapperClass` / `className` / `owner`: wrapper/owner name
+  - `file`: source filename
+  - `line`: source line number
+  - `lib` / `library`: npm package name inferred from path
+  - `type` / `functionType`: function kind (`method`, `constructor`, etc.)
+  - `event` / `eventType`: trace phase (`enter` or `exit`)
+- `DisableTraceByFilename`: `{ file: TraceRulePattern }`
+- `DisableTraceFileConfig`: `TraceRulePattern | DisableTraceByFilename | null | undefined`
+
+Full config example (shows every option; aliases are interchangeable, use one per group in real configs):
+
+```ts
+import { initReproTracing } from 'repro-nest';
+
+initReproTracing({
+  instrument: true,
+  include: [/^\/app\/src\//],
+  exclude: [/node_modules\//, /dist\//],
+  mode: process.env.TRACE_MODE || 'trace',
+  samplingMs: 10,
+  disableFunctionTraces: [
+    {
+      fn: 'findAll',
+      wrapper: 'TasksService',
+      file: 'src/tasks/tasks.service.ts',
+      line: 27,
+      lib: 'mongoose',
+      type: 'method',
+      event: 'exit',
+    },
+    {
+      functionName: 'formatSensitiveData',
+      wrapperClass: 'AuthService',
+      className: 'AuthService',
+      owner: 'AuthService',
+      library: 'bcrypt',
+      functionType: 'method',
+      eventType: 'enter',
+    },
+    (event) => event.fn?.startsWith('debug') ?? false,
+  ],
+  disableFunctionTypes: ['constructor', /getter/i],
+  disableTraceFiles: [
+    /node_modules\/some-logger\//,
+    { file: 'dist/health.check.js' },
+    'dist/generated.js',
+  ],
+  traceInterceptors: true,
+  logFunctionCalls: false,
+});
+```
+
+### reproMiddleware
+
+Captures request/response payloads for active Repro sessions. Requests must
+include `x-bug-session-id` and `x-bug-action-id` headers to be captured.
+
+Options (type -> purpose):
+- `appId` (string): Repro app id.
+- `tenantId` (string): Repro tenant id.
+- `appSecret` (string): Repro app secret.
+- `captureHeaders` (boolean | HeaderCaptureOptions): enable/disable header capture
+  and masking.
+- `masking` (ReproMaskingConfig): mask request/response bodies and trace args/returns.
+
+Header capture options (`HeaderCaptureOptions`):
+- `allowSensitiveHeaders` (boolean): keep default sensitive headers unmasked.
+- `maskHeaders` (HeaderRule | HeaderRule[]): header names to mask.
+- `dropHeaders` (HeaderRule | HeaderRule[]): alias for `maskHeaders`.
+- `unmaskHeaders` (HeaderRule | HeaderRule[]): header names to keep unmasked.
+- `keepHeaders` (HeaderRule | HeaderRule[]): alias for `unmaskHeaders`.
+- `HeaderRule`: `string | RegExp`
+
+Masking options (`ReproMaskingConfig`):
+- `replacement` (any): default replacement value (defaults to `"[REDACTED]"`).
+- `rules` (ReproMaskRule[] | null): list of masking rules.
+
+Masking rule options (`ReproMaskRule`):
+- `when` (ReproMaskWhen): scope rules by request or function trace fields.
+- `target` (ReproMaskTarget | ReproMaskTarget[]): where to apply the mask.
+- `paths` (string | string[]): dot/bracket paths to mask.
+- `keys` (TraceRulePattern): mask keys anywhere in the payload.
+- `replacement` (any): override replacement value for this rule.
+
+`ReproMaskTarget` values:
+- `request.headers`, `request.body`, `request.params`, `request.query`
+- `response.body`, `trace.args`, `trace.returnValue`, `trace.error`
+
+`ReproMaskWhen` fields (all accept `TraceRulePattern` unless noted):
+- Request scope: `method`, `path`, `key`
+- Function scope: `fn` / `functionName`, `wrapper` / `wrapperClass` / `className` / `owner`,
+  `file`, `line`, `lib` / `library`, `type` / `functionType`, `event` / `eventType`
+
+Full config example (shows every option; aliases are interchangeable, use one per group in real configs):
+
+```ts
+import { reproMiddleware } from 'repro-nest';
+
+app.use(reproMiddleware({
+  appId: process.env.REPRO_APP_ID as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+  captureHeaders: {
+    allowSensitiveHeaders: false,
+    maskHeaders: [/authorization/i, /cookie/i],
+    dropHeaders: ['x-api-key'],
+    unmaskHeaders: ['x-request-id'],
+    keepHeaders: ['x-trace-id'],
+  },
+  masking: {
+    replacement: '[REDACTED]',
+    rules: [
+      {
+        when: { method: 'POST', path: '/api/auth/login', key: 'POST /api/auth/login' },
+        target: ['request.body', 'response.body'],
+        paths: ['password'],
+        keys: [/token/i],
+        replacement: '[FILTERED]',
+      },
+      {
+        when: {
+          functionName: 'findAll',
+          wrapperClass: 'TasksService',
+          file: 'src/tasks/tasks.service.ts',
+          line: 27,
+          library: 'mongoose',
+          functionType: 'method',
+          eventType: 'exit',
+        },
+        target: ['trace.args', 'trace.returnValue', 'trace.error'],
+        paths: ['0.user.token'],
+        keys: ['password'],
+      },
+      {
+        when: {
+          fn: 'create',
+          wrapper: 'UsersService',
+          className: 'UsersService',
+          owner: 'UsersService',
+          lib: 'mongoose',
+          type: 'method',
+          event: 'enter',
+        },
+        target: 'trace.args',
+        paths: ['0.password'],
+      },
+    ],
+  },
+}));
+```
+
+See `docs/tracing.md` for full masking and trace filtering details.
+
+### Mongoose plugin
+
+`reproMongoosePlugin` attaches schema middleware to capture query activity and
+document diffs. It emits data only when a Repro session is active (i.e., when
+`reproMiddleware` has set the session context for the current request).
+
+Arguments:
+- `appId` (string): Repro app id
+- `tenantId` (string): Repro tenant id
+- `appSecret` (string): Repro app secret
+
+Example: global plugin (all schemas)
+
+```ts
+import mongoose from 'mongoose';
+import { reproMongoosePlugin } from 'repro-nest';
+
+mongoose.plugin(reproMongoosePlugin({
+  appId: process.env.REPRO_APP_ID as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+}));
+```
+
+Example: Nest `MongooseModule` connection factory
+
+```ts
+import { MongooseModule } from '@nestjs/mongoose';
+import { reproMongoosePlugin } from 'repro-nest';
+
+MongooseModule.forRoot(process.env.MONGO_URL as string, {
+  connectionFactory: (connection) => {
+    connection.plugin(reproMongoosePlugin({
+      appId: process.env.REPRO_APP_ID as string,
+      tenantId: process.env.REPRO_TENANT_ID as string,
+      appSecret: process.env.REPRO_APP_SECRET as string,
+    }));
+    return connection;
+  },
+});
+```
+
+Example: schema-level plugin (single model)
+
+```ts
+import { Schema } from 'mongoose';
+import { reproMongoosePlugin } from 'repro-nest';
+
+const userSchema = new Schema({ email: String });
+userSchema.plugin(reproMongoosePlugin({
+  appId: process.env.REPRO_APP_ID as string,
+  tenantId: process.env.REPRO_TENANT_ID as string,
+  appSecret: process.env.REPRO_APP_SECRET as string,
+}));
+```
+
+## 3) Run
+
+Run your Nest app as usual after wiring the SDK:
+
+```bash
+npm run start:dev
+# or
+node dist/main.js
+```
+
+If you use `initReproTracing`, keep it at the top of your bootstrap so modules
+load after instrumentation is enabled.
+
+## 4) Verify It Works
+
+Send a request with Repro headers and confirm the session shows up in Repro.
+
+```bash
+curl \
+  -H "x-bug-session-id: session-123" \
+  -H "x-bug-action-id: action-123" \
+  http://localhost:3000/health
+```
+
+Verification tips:
+- If the Repro UI does not show the session, confirm `REPRO_API_BASE` and
+  credentials are correct.
+- Temporarily set `logFunctionCalls: true` in `initReproTracing` to see trace
+  enter/exit logs in your console.
+- If you use Mongoose, exercise a query/mutation and verify DB entries appear
+  in the session trace.

package/dist/index.js

@@ -367,6 +367,33 @@ function shouldDropTraceEvent(event) {
     }
     return false;
 }
+function shouldPropagateUserDisabledFunctionTrace(event) {
+    const rules = userDisabledFunctionTraceRules;
+    if (!rules || rules.length === 0)
+        return false;
+    for (const rule of rules) {
+        try {
+            if (typeof rule === 'function') {
+                const enterEvent = { ...event, type: 'enter', eventType: 'enter' };
+                const exitEvent = { ...event, type: 'exit', eventType: 'exit' };
+                if (rule(enterEvent) && rule(exitEvent))
+                    return true;
+            }
+            else if (matchesRule(rule, event)) {
+                const eventTypePattern = rule.eventType ?? rule.event;
+                if (!matchesPattern('enter', eventTypePattern))
+                    continue;
+                if (!matchesPattern('exit', eventTypePattern))
+                    continue;
+                return true;
+            }
+        }
+        catch {
+            // ignore user filter errors
+        }
+    }
+    return false;
+}
 function setDisabledFunctionTraces(rules) {
     if (!rules || !Array.isArray(rules)) {
         userDisabledFunctionTraceRules = null;
@@ -1689,7 +1716,11 @@ function reproMiddleware(cfg) {
                                 evt.unawaited = ev.unawaited === true;
                             }
                             const dropEvent = shouldDropTraceEvent(candidate);
+                            const dropSpanTree = shouldPropagateUserDisabledFunctionTrace(candidate);
                             const spanKey = normalizeSpanId(evt.spanId);
+                            const parentSpanKey = normalizeSpanId(evt.parentSpanId);
+                            const isChildOfExcluded = parentSpanKey ? isExcludedSpanId(parentSpanKey) : false;
+                            const isExcluded = spanKey ? isExcludedSpanId(spanKey) : false;
                             if (evt.type === 'enter') {
                                 lastEventAt = Date.now();
                                 if (spanKey) {
@@ -1708,8 +1739,8 @@ function reproMiddleware(cfg) {
                                     anonymousSpanDepth = Math.max(0, anonymousSpanDepth - 1);
                                 }
                             }
-                            if (dropEvent) {
-                                if (evt.type === 'enter' && spanKey) {
+                            if (dropEvent || isChildOfExcluded || isExcluded) {
+                                if (evt.type === 'enter' && spanKey && (dropSpanTree || isChildOfExcluded || isExcluded)) {
                                     try {
                                         getCtx().excludedSpanIds?.add(spanKey);
                                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repro-nest",
-  "version": "0.0.219",
+  "version": "0.0.220",
   "description": "Repro Nest SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
-    "test": "npm run build && node tmp/unawaited.test.js && node tmp/integration-unawaited.js && node -r ./tracer/register tmp/promise-map.test.js"
+    "test": "npm run build && node tmp/unawaited.test.js && node tmp/integration-unawaited.js && node -r ./tracer/register tmp/promise-map.test.js && node tmp/disable-subtree.test.js"
   },
   "peerDependencies": {
     "express": "^5.1.0",

package/src/index.ts

@@ -532,6 +532,28 @@ function shouldDropTraceEvent(event: TraceEventForFilter): boolean {
     return false;
 }
 
+function shouldPropagateUserDisabledFunctionTrace(event: TraceEventForFilter): boolean {
+    const rules = userDisabledFunctionTraceRules;
+    if (!rules || rules.length === 0) return false;
+    for (const rule of rules) {
+        try {
+            if (typeof rule === 'function') {
+                const enterEvent = { ...event, type: 'enter', eventType: 'enter' } as TraceEventForFilter;
+                const exitEvent = { ...event, type: 'exit', eventType: 'exit' } as TraceEventForFilter;
+                if (rule(enterEvent) && rule(exitEvent)) return true;
+            } else if (matchesRule(rule, event)) {
+                const eventTypePattern = rule.eventType ?? rule.event;
+                if (!matchesPattern('enter', eventTypePattern)) continue;
+                if (!matchesPattern('exit', eventTypePattern)) continue;
+                return true;
+            }
+        } catch {
+            // ignore user filter errors
+        }
+    }
+    return false;
+}
+
 export function setDisabledFunctionTraces(rules?: DisableFunctionTraceConfig[] | null) {
     if (!rules || !Array.isArray(rules)) {
         userDisabledFunctionTraceRules = null;
@@ -1977,16 +1999,20 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                             if (ev.threw !== undefined) {
                                 evt.threw = Boolean(ev.threw);
                             }
-                            if (ev.unawaited !== undefined) {
-                                evt.unawaited = ev.unawaited === true;
-                            }
-
-                            const dropEvent = shouldDropTraceEvent(candidate);
-                            const spanKey = normalizeSpanId(evt.spanId);
-                            if (evt.type === 'enter') {
-                                lastEventAt = Date.now();
-                                if (spanKey) {
-                                    activeSpans.add(spanKey);
+	                            if (ev.unawaited !== undefined) {
+	                                evt.unawaited = ev.unawaited === true;
+	                            }
+
+	                            const dropEvent = shouldDropTraceEvent(candidate);
+	                            const dropSpanTree = shouldPropagateUserDisabledFunctionTrace(candidate);
+	                            const spanKey = normalizeSpanId(evt.spanId);
+	                            const parentSpanKey = normalizeSpanId(evt.parentSpanId);
+	                            const isChildOfExcluded = parentSpanKey ? isExcludedSpanId(parentSpanKey) : false;
+	                            const isExcluded = spanKey ? isExcludedSpanId(spanKey) : false;
+	                            if (evt.type === 'enter') {
+	                                lastEventAt = Date.now();
+	                                if (spanKey) {
+	                                    activeSpans.add(spanKey);
                                 } else {
                                     anonymousSpanDepth = Math.max(0, anonymousSpanDepth + 1);
                                 }
@@ -1996,16 +2022,16 @@ export function reproMiddleware(cfg: ReproMiddlewareConfig) {
                                     activeSpans.delete(spanKey);
                                 } else if (!spanKey && anonymousSpanDepth > 0) {
                                     anonymousSpanDepth = Math.max(0, anonymousSpanDepth - 1);
-                                }
-                            }
-
-                            if (dropEvent) {
-                                if (evt.type === 'enter' && spanKey) {
-                                    try { (getCtx() as Ctx).excludedSpanIds?.add(spanKey); } catch {}
-                                }
-                                if (finished) {
-                                    scheduleIdleFlush();
-                                }
+	                                }
+	                            }
+
+	                            if (dropEvent || isChildOfExcluded || isExcluded) {
+	                                if (evt.type === 'enter' && spanKey && (dropSpanTree || isChildOfExcluded || isExcluded)) {
+	                                    try { (getCtx() as Ctx).excludedSpanIds?.add(spanKey); } catch {}
+	                                }
+	                                if (finished) {
+	                                    scheduleIdleFlush();
+	                                }
                                 return;
                             }
 

package/back-end-node/.dockerignore

@@ -1,59 +0,0 @@
-# compiled output
-/dist
-/node_modules
-/build
-
-# Logs
-logs
-*.log
-npm-debug.log*
-pnpm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# OS
-.DS_Store
-
-# Tests
-/coverage
-/.nyc_output
-
-# IDEs and editors
-/.idea
-.project
-.classpath
-.c9/
-*.launch
-.settings/
-*.sublime-workspace
-
-# IDE - VSCode
-.vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
-
-# dotenv environment variable files
-.env
-.env.*
-
-# temp directory
-.temp
-.tmp
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Temp/Scratch files
-tmp.*
-*.tmp
-**/tmp.*
-**/*.tmp

package/back-end-node/.github/pull_request_template.md

@@ -1,11 +0,0 @@
-## 🎟️ Issue Reference
-
-[SL-123](https://korioclinical.atlassian.net/browse/SL-123)
-
-## 💡 Context
-
-[THIS SECTION IS REQUIRED. Provide a brief (or prolonged, if you prefer) description of this PR. What does it accomplish and how? Is new functionality introduced? Has existing code been refactored? If applicable, you may list individual changes as bullet points, create subsections with detailed specifications, or simply write a sentence or two explaining the result of this code.]
-
-## 🧪 Testing Story
-
-[THIS SECTION IS REQUIRED. In many cases, a simple accounting of the development process will suffice here, e.g. "Opened the Subjects Management grid and confirmed that the detail tray could be opened." For complicated actions, you are of course welcome to provide as detailed of reproduction steps as you feel to be necessary.]

package/back-end-node/.github/workflows/dev-deploy.yaml

@@ -1,21 +0,0 @@
-############################
-### MANAGED BY TERRAFORM ###
-############################
-
-# https://github.com/korio-clinical/terraform-infra/tree/main/org/github_workflows
-name: 'Dev Deploy'
-
-on:
-  workflow_dispatch:
-  push:
-    branches:
-      - main
-    paths-ignore:
-      - '.github/workflows/**'
-
-jobs:
-  deploy:
-    uses: korio-clinical/github-reusable-workflows/.github/workflows/deploy.yml@main
-    with:
-      environment: dev
-    secrets: inherit

package/back-end-node/.github/workflows/node-format-check.yaml

@@ -1,29 +0,0 @@
-# Tech Debt: This Workflow should be moved into the github-reusable-workflows pr.yaml workflow once we have formatting implemented on all repos.
-name: 'NodeJS Formatting Check'
-
-on:
-  pull_request:
-    branches:
-      - main
-      - release/*
-
-jobs:
-  check-formatting:
-    name: 'Check Formatting'
-    continue-on-error: true
-    runs-on: ubuntu-latest
-    steps:
-      - name: 'Checkout'
-        uses: actions/checkout@v4.2.2
-
-      - name: 'Setup Node'
-        uses: actions/setup-node@v4.2.0
-        with:
-          node-version: 18.16
-
-      - name: 'npm ci'
-        run: npm ci
-
-
-      - name: 'prettier --check'
-        run: npm run format:check

package/back-end-node/.github/workflows/platform-deploy.yaml

@@ -1,16 +0,0 @@
-############################
-### MANAGED BY TERRAFORM ###
-############################
-
-# https://github.com/korio-clinical/terraform-infra/tree/main/org/github_workflows
-name: 'Platform Deploy'
-
-on:
-  workflow_dispatch:
-        
-jobs:
-  deploy:
-    uses: korio-clinical/github-reusable-workflows/.github/workflows/deploy.yml@main
-    with:
-      environment: platform
-    secrets: inherit

package/back-end-node/.github/workflows/platform3-deploy.yaml

@@ -1,21 +0,0 @@
-############################
-### MANAGED BY TERRAFORM ###
-############################
-
-# https://github.com/korio-clinical/terraform-infra/tree/main/org/github_workflows
-name: 'Platform3 Deploy'
-
-on:
-  workflow_dispatch:
-    inputs:
-      force_build:
-        description: Build image even if exists
-        type: boolean
-        default: false
-        
-jobs:
-  deploy:
-    uses: korio-clinical/github-reusable-workflows/.github/workflows/deploy.yml@main
-    with:
-      environment: platform3
-    secrets: inherit

package/back-end-node/.github/workflows/pr.yaml

@@ -1,22 +0,0 @@
-############################
-### MANAGED BY TERRAFORM ###
-############################
-
-# https://github.com/korio-clinical/terraform-infra/tree/main/org/github_workflows
-name: PR
-
-on:
-  pull_request:
-    branches:
-      - main
-      - release/*
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  pr:
-    name: 'Checks'
-    uses: korio-clinical/github-reusable-workflows/.github/workflows/pr.yml@main
-    secrets: inherit