@loadstrike/loadstrike-sdk 1.0.22601 → 1.0.22801

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InfluxDbReportingSinkOptions = exports.InfluxDbReportingSink = exports.GrafanaLokiReportingSinkOptions = exports.GrafanaLokiReportingSink = exports.DatadogReportingSinkOptions = exports.DatadogReportingSink = exports.HttpAuthOptions = exports.HttpOAuth2ClientCredentialsOptions = exports.PushDiffusionEndpointDefinition = exports.DelegateStreamEndpointDefinition = exports.AzureEventHubsEndpointDefinition = exports.RedisStreamsEndpointDefinition = exports.NatsEndpointDefinition = exports.RabbitMqEndpointDefinition = exports.KafkaSaslOptions = exports.KafkaEndpointDefinition = exports.HttpEndpointDefinition = exports.TrafficEndpointDefinition = exports.LOADSTRIKE_TRACE_ID_TRACKING_FIELD = exports.LOADSTRIKE_TRACE_ID_HEADER = exports.EndpointAdapterFactory = exports.TrackingFieldSelector = exports.TrackingPayloadBuilder = exports.RedisCorrelationStore = exports.RedisCorrelationStoreOptions = exports.InMemoryCorrelationStore = exports.CrossPlatformTrackingRuntime = exports.CorrelationStoreConfiguration = exports.LoadStrikeThreshold = exports.LoadStrikeStep = exports.LoadStrikeGauge = exports.LoadStrikeCounter = exports.LoadStrikeMetric = exports.LoadStrikeSimulation = exports.LoadStrikeScenario = exports.LoadStrikeRunner = exports.LoadStrikeOperationType = exports.LoadStrikeScenarioOperation = exports.LoadStrikeLogLevel = exports.LoadStrikeResponse = exports.LoadStrikeReportFormat = exports.LoadStrikeNodeType = exports.LoadStrikePluginDataTable = exports.LoadStrikePluginData = exports.LoadStrikeContext = exports.ScenarioTrackingExtensions = exports.CrossPlatformScenarioConfigurator = exports.LoadStrikeAutopilotReadiness = exports.LoadStrikeAutopilotResult = exports.LoadStrikeAutopilot = void 0;
-exports.TimescaleDbReportingSinkOptions = exports.TimescaleDbReportingSink = exports.SplunkReportingSinkOptions = exports.SplunkReportingSink = exports.OtelCollectorReportingSinkOptions = exports.OtelCollectorReportingSink = void 0;
+exports.InfluxDbReportingSink = exports.GrafanaLokiReportingSinkOptions = exports.GrafanaLokiReportingSink = exports.DatadogReportingSinkOptions = exports.DatadogReportingSink = exports.HttpAuthOptions = exports.HttpOAuth2ClientCredentialsOptions = exports.PushDiffusionEndpointDefinition = exports.DelegateStreamEndpointDefinition = exports.AzureEventHubsEndpointDefinition = exports.RedisStreamsEndpointDefinition = exports.NatsEndpointDefinition = exports.RabbitMqEndpointDefinition = exports.KafkaSaslOptions = exports.KafkaEndpointDefinition = exports.HttpEndpointDefinition = exports.TrafficEndpointDefinition = exports.LOADSTRIKE_TRACE_ID_TRACKING_FIELD = exports.LOADSTRIKE_TRACE_ID_HEADER = exports.EndpointAdapterFactory = exports.TrackingFieldSelector = exports.TrackingPayloadBuilder = exports.RedisCorrelationStore = exports.RedisCorrelationStoreOptions = exports.InMemoryCorrelationStore = exports.CrossPlatformTrackingRuntime = exports.CorrelationStoreConfiguration = exports.LoadStrikeThreshold = exports.LoadStrikeStep = exports.LoadStrikeGauge = exports.LoadStrikeCounter = exports.LoadStrikeMetric = exports.CrossPlatformTrackingConfiguration = exports.LoadStrikeSimulation = exports.LoadStrikeScenario = exports.LoadStrikeRunner = exports.LoadStrikeOperationType = exports.LoadStrikeScenarioOperation = exports.LoadStrikeLogLevel = exports.LoadStrikeResponse = exports.LoadStrikeReportFormat = exports.LoadStrikeNodeType = exports.LoadStrikePluginDataTable = exports.LoadStrikePluginData = exports.LoadStrikeContext = exports.ScenarioTrackingExtensions = exports.CrossPlatformScenarioConfigurator = exports.LoadStrikeAutopilotReadiness = exports.LoadStrikeAutopilotResult = exports.LoadStrikeAutopilot = void 0;
+exports.TimescaleDbReportingSinkOptions = exports.TimescaleDbReportingSink = exports.SplunkReportingSinkOptions = exports.SplunkReportingSink = exports.OtelCollectorReportingSinkOptions = exports.OtelCollectorReportingSink = exports.InfluxDbReportingSinkOptions = void 0;
 var autopilot_js_1 = require("./autopilot.js");
 Object.defineProperty(exports, "LoadStrikeAutopilot", { enumerable: true, get: function () { return autopilot_js_1.LoadStrikeAutopilot; } });
 Object.defineProperty(exports, "LoadStrikeAutopilotResult", { enumerable: true, get: function () { return autopilot_js_1.LoadStrikeAutopilotResult; } });
@@ -22,6 +22,7 @@ Object.defineProperty(exports, "LoadStrikeOperationType", { enumerable: true, ge
 Object.defineProperty(exports, "LoadStrikeRunner", { enumerable: true, get: function () { return runtime_js_1.LoadStrikeRunner; } });
 Object.defineProperty(exports, "LoadStrikeScenario", { enumerable: true, get: function () { return runtime_js_1.LoadStrikeScenario; } });
 Object.defineProperty(exports, "LoadStrikeSimulation", { enumerable: true, get: function () { return runtime_js_1.LoadStrikeSimulation; } });
+Object.defineProperty(exports, "CrossPlatformTrackingConfiguration", { enumerable: true, get: function () { return runtime_js_1.CrossPlatformTrackingConfiguration; } });
 Object.defineProperty(exports, "LoadStrikeMetric", { enumerable: true, get: function () { return runtime_js_1.LoadStrikeMetric; } });
 Object.defineProperty(exports, "LoadStrikeCounter", { enumerable: true, get: function () { return runtime_js_1.LoadStrikeCounter; } });
 Object.defineProperty(exports, "LoadStrikeGauge", { enumerable: true, get: function () { return runtime_js_1.LoadStrikeGauge; } });

package/dist/cjs/local.js

@@ -1047,10 +1047,20 @@ function validateTrackingConfiguration(tracking, sourceEndpoint, destinationEndp
     if (!metricPrefix.trim()) {
         throw new Error("MetricPrefix must be provided.");
     }
+    const observationDurationOverride = pickValue(tracking, "ObservationDurationMs", "observationDurationMs");
+    const observationDurationSeconds = pickValue(tracking, "ObservationDurationSeconds", "observationDurationSeconds", "ObservationDuration");
+    const observationDurationMs = observationDurationOverride != null && String(observationDurationOverride).trim() !== ""
+        ? asNumber(observationDurationOverride)
+        : (observationDurationSeconds == null || String(observationDurationSeconds).trim() === ""
+            ? 0
+            : asNumber(observationDurationSeconds) * 1000);
     validateRedisCorrelationStoreConfiguration(tracking);
     const runModeRaw = stringOrDefault(pickValue(tracking, "RunMode", "runMode"), "GenerateAndCorrelate").trim().toLowerCase();
     const runMode = runModeRaw === "sourceonly" ? "generateandcorrelate" : runModeRaw;
     if (runMode === "generateandcorrelate") {
+        if (observationDurationMs > 0) {
+            throw new Error("ForDuration is only supported for CorrelateExistingTraffic.");
+        }
         if (sourceEndpoint.mode !== "Produce") {
             throw new Error("Source endpoint mode must be Produce for GenerateAndCorrelate mode.");
         }
@@ -1060,6 +1070,9 @@ function validateTrackingConfiguration(tracking, sourceEndpoint, destinationEndp
         return;
     }
     if (runMode === "correlateexistingtraffic") {
+        if (observationDurationMs <= 0) {
+            throw new Error("CorrelateExistingTraffic requires ForDuration with a duration greater than zero.");
+        }
         if (!destinationEndpoint) {
             throw new Error("Destination endpoint must be provided for CorrelateExistingTraffic mode.");
         }

package/dist/cjs/runtime.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__loadstrikeTestExports = exports.LoadStrikeRunner = exports.LoadStrikeScenario = exports.LoadStrikeContext = exports.ScenarioTrackingExtensions = exports.CrossPlatformScenarioConfigurator = exports.LoadStrikeThreshold = exports.LoadStrikeMetric = exports.LoadStrikeGauge = exports.LoadStrikeCounter = exports.LoadStrikeSimulation = exports.LoadStrikeStep = exports.LoadStrikeResponse = exports.LoadStrikePluginData = exports.LoadStrikePluginDataTable = exports.LoadStrikeOperationType = exports.LoadStrikeScenarioOperation = exports.LoadStrikeLogLevel = exports.LoadStrikeReportFormat = exports.LoadStrikeNodeType = void 0;
+exports.__loadstrikeTestExports = exports.LoadStrikeRunner = exports.LoadStrikeScenario = exports.LoadStrikeContext = exports.ScenarioTrackingExtensions = exports.CrossPlatformScenarioConfigurator = exports.LoadStrikeThreshold = exports.LoadStrikeMetric = exports.LoadStrikeGauge = exports.LoadStrikeCounter = exports.LoadStrikeSimulation = exports.LoadStrikeStep = exports.LoadStrikeResponse = exports.LoadStrikePluginData = exports.LoadStrikePluginDataTable = exports.CrossPlatformTrackingConfiguration = exports.LoadStrikeOperationType = exports.LoadStrikeScenarioOperation = exports.LoadStrikeLogLevel = exports.LoadStrikeReportFormat = exports.LoadStrikeNodeType = void 0;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
 const node_os_1 = __importDefault(require("node:os"));
@@ -47,6 +47,33 @@ exports.LoadStrikeOperationType = {
     Complete: "Complete",
     Error: "Error"
 };
+exports.CrossPlatformTrackingConfiguration = {
+    forDuration(configuration, durationSeconds, cancellationSignal) {
+        if (!configuration || typeof configuration !== "object" || Array.isArray(configuration)) {
+            throw new TypeError("Tracking configuration must be provided.");
+        }
+        if (normalizeTrackingRunMode(pickTrackingString(configuration, "RunMode", "runMode", "GenerateAndCorrelate")) !== "correlateexistingtraffic") {
+            throw new Error("ForDuration can only be used with CorrelateExistingTraffic.");
+        }
+        if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+            throw new RangeError("ForDuration duration must be greater than zero.");
+        }
+        const result = {
+            ...configuration,
+            ObservationDurationSeconds: durationSeconds
+        };
+        if (cancellationSignal !== undefined) {
+            if (!(cancellationSignal instanceof AbortSignal)) {
+                throw new TypeError("ForDuration cancellation signal must be an AbortSignal.");
+            }
+            result.ObservationCancellationSignal = cancellationSignal;
+        }
+        return result;
+    },
+    ForDuration(configuration, durationSeconds, cancellationSignal) {
+        return this.forDuration(configuration, durationSeconds, cancellationSignal);
+    }
+};
 class LoadStrikePluginDataTable {
     /**
      * Exposes the public constructor operation.
@@ -1730,6 +1757,9 @@ class LoadStrikeScenario {
             ? mapRuntimeTrackingEndpointSpec(destinationSpec, useLoadStrikeTraceIdHeader)
             : null;
         validateRuntimeTrackingConfiguration(copied, sourceEndpoint, destinationEndpoint);
+        if (isCorrelateExistingTrafficTracking(copied) && this.loadSimulations.length > 0) {
+            throw new Error("CorrelateExistingTraffic uses ForDuration and cannot be combined with WithLoadSimulations.");
+        }
         return new LoadStrikeScenario(this.name, this.runHandler, this.initHandler, this.cleanHandler, this.loadSimulations, this.thresholds, copied, this.maxFailCount, this.withoutWarmUpValue, this.warmUpDurationSeconds, this.weight, this.restartIterationOnFail, this.internalLicenseFeatures);
     }
     /**
@@ -1740,6 +1770,9 @@ class LoadStrikeScenario {
         if (!simulations.length) {
             throw new Error("At least one load simulation should be provided.");
         }
+        if (isCorrelateExistingTrafficTracking(this.trackingConfiguration)) {
+            throw new Error("CorrelateExistingTraffic uses ForDuration and cannot be combined with WithLoadSimulations.");
+        }
         return new LoadStrikeScenario(this.name, this.runHandler, this.initHandler, this.cleanHandler, simulations.map((simulation) => attachLoadSimulationProjection({ ...simulation })), this.thresholds, this.trackingConfiguration, this.maxFailCount, this.withoutWarmUpValue, this.warmUpDurationSeconds, this.weight, this.restartIterationOnFail, this.internalLicenseFeatures);
     }
     /**
@@ -5741,6 +5774,14 @@ class ManagedScenarioTrackingRuntime {
         this.sourceOnlyMode = this.destinationEndpoint == null;
         this.executeOriginalScenarioRun = pickTrackingBoolean(tracking, "ExecuteOriginalScenarioRun", "executeOriginalScenarioRun", false);
         this.correlationTimeoutMs = Math.trunc(pickTrackingNumber(tracking, ["CorrelationTimeoutMs", "correlationTimeoutMs"], pickTrackingNumber(tracking, ["CorrelationTimeoutSeconds", "correlationTimeoutSeconds", "CorrelationTimeout"], 30) * 1000));
+        this.observationDurationMs = Math.trunc(readObservationDurationMs(tracking));
+        const observationCancellationSignal = pickTrackingValue(tracking, "ObservationCancellationSignal", "observationCancellationSignal");
+        if (observationCancellationSignal !== undefined) {
+            if (!(observationCancellationSignal instanceof AbortSignal)) {
+                throw new TypeError("ObservationCancellationSignal must be an AbortSignal.");
+            }
+            this.observationCancellationSignal = observationCancellationSignal;
+        }
         this.timeoutSweepIntervalMs = Math.trunc(pickTrackingNumber(tracking, ["TimeoutSweepIntervalMs", "timeoutSweepIntervalMs"], pickTrackingNumber(tracking, ["TimeoutSweepIntervalSeconds", "timeoutSweepIntervalSeconds"], 1) * 1000));
         this.timeoutBatchSize = Math.trunc(pickTrackingNumber(tracking, ["TimeoutBatchSize", "timeoutBatchSize"], 200));
         this.timeoutCountsAsFailure = pickTrackingBoolean(tracking, "TimeoutCountsAsFailure", "timeoutCountsAsFailure", true);
@@ -5881,8 +5922,7 @@ class ManagedScenarioTrackingRuntime {
             return this.executeSourceOnly();
         }
         if (this.runMode === "correlateexistingtraffic") {
-            const outcome = await this.waitForOutcome(context.scenarioCancellationToken);
-            return this.toResponse(outcome);
+            return await this.observeExistingTraffic(context.scenarioCancellationToken);
         }
         let producedPayload;
         try {
@@ -5958,6 +5998,45 @@ class ManagedScenarioTrackingRuntime {
         });
         return LoadStrikeResponse.ok("source_success");
     }
+    async observeExistingTraffic(signal) {
+        const deadline = Date.now() + this.observationDurationMs;
+        const observationSignal = this.observationCancellationSignal
+            ? combineAbortSignals(signal, this.observationCancellationSignal)
+            : signal;
+        let failureSeen = false;
+        while (Date.now() < deadline && !observationSignal.aborted) {
+            let outcome;
+            try {
+                outcome = await this.waitForOutcomeUntil(deadline, observationSignal);
+            }
+            catch (error) {
+                if (this.observationCancellationSignal?.aborted && !signal.aborted) {
+                    break;
+                }
+                throw error;
+            }
+            if (!outcome) {
+                break;
+            }
+            failureSeen = failureSeen || this.isFailedObservationOutcome(outcome);
+        }
+        this.shutdown = true;
+        await Promise.all([
+            this.sourceLoop,
+            this.destinationLoop,
+            this.timeoutLoop
+        ].filter(Boolean).map((value) => value.catch(() => { })));
+        await this.correlationRuntime.sweepTimeouts(Date.now() + this.correlationTimeoutMs + 1, this.timeoutBatchSize);
+        while (this.outcomeQueue.length > 0) {
+            const outcome = this.outcomeQueue.shift();
+            if (outcome) {
+                failureSeen = failureSeen || this.isFailedObservationOutcome(outcome);
+            }
+        }
+        return failureSeen
+            ? LoadStrikeResponse.fail("tracking_failures", "One or more observed source or destination events did not correlate successfully.", 0)
+            : LoadStrikeResponse.ok("observed");
+    }
     async consumeSourceLoop() {
         while (!this.shutdown) {
             try {
@@ -6171,6 +6250,34 @@ class ManagedScenarioTrackingRuntime {
             }
         }
     }
+    async waitForOutcomeUntil(deadlineMs, signal) {
+        const existing = this.outcomeQueue.shift();
+        if (existing) {
+            return existing;
+        }
+        const remainingMs = deadlineMs - Date.now();
+        if (remainingMs <= 0) {
+            return null;
+        }
+        const waiter = createManagedTrackingWaiter();
+        this.outcomeWaiters.push(waiter);
+        const timeout = sleep(remainingMs).then(() => null);
+        try {
+            return await Promise.race([waiter.promise, timeout, waitForAbort(signal)]);
+        }
+        finally {
+            const index = this.outcomeWaiters.indexOf(waiter);
+            if (index >= 0) {
+                this.outcomeWaiters.splice(index, 1);
+            }
+        }
+    }
+    isFailedObservationOutcome(outcome) {
+        if (outcome.status === "timeout") {
+            return this.timeoutCountsAsFailure;
+        }
+        return outcome.status !== "matched";
+    }
     rejectOutstandingWaiters() {
         for (const rows of this.waiters.values()) {
             for (const waiter of rows) {
@@ -6290,8 +6397,12 @@ function validateRuntimeTrackingConfiguration(tracking, sourceEndpoint, destinat
     if (!metricPrefix.trim()) {
         throw new Error("MetricPrefix must be provided.");
     }
+    const observationDurationMs = readObservationDurationMs(tracking);
     validateRuntimeRedisCorrelationStoreConfiguration(tracking);
     if (runMode === "generateandcorrelate") {
+        if (observationDurationMs > 0) {
+            throw new Error("ForDuration is only supported for CorrelateExistingTraffic.");
+        }
         if (sourceEndpoint.mode !== "Produce") {
             throw new Error("Source endpoint mode must be Produce for GenerateAndCorrelate mode.");
         }
@@ -6301,6 +6412,9 @@ function validateRuntimeTrackingConfiguration(tracking, sourceEndpoint, destinat
         return;
     }
     if (runMode === "correlateexistingtraffic") {
+        if (observationDurationMs <= 0) {
+            throw new Error("CorrelateExistingTraffic requires ForDuration with a duration greater than zero.");
+        }
         if (!destinationEndpoint) {
             throw new Error("Destination endpoint must be provided for CorrelateExistingTraffic mode.");
         }
@@ -6314,6 +6428,15 @@ function validateRuntimeTrackingConfiguration(tracking, sourceEndpoint, destinat
     }
     throw new RangeError(`Unsupported tracking run mode: ${runMode}.`);
 }
+function readObservationDurationMs(tracking) {
+    return pickTrackingNumber(tracking, ["ObservationDurationMs", "observationDurationMs"], pickTrackingNumber(tracking, ["ObservationDurationSeconds", "observationDurationSeconds", "ObservationDuration"], 0) * 1000);
+}
+function isCorrelateExistingTrafficTracking(configuration) {
+    if (!configuration) {
+        return false;
+    }
+    return normalizeTrackingRunMode(pickTrackingString(configuration, "RunMode", "runMode", "GenerateAndCorrelate")) === "correlateexistingtraffic";
+}
 function readUseLoadStrikeTraceIdHeader(tracking) {
     return pickTrackingBoolean(tracking, "UseLoadStrikeTraceIdHeader", "useLoadStrikeTraceIdHeader", false);
 }

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 export { LoadStrikeAutopilot, LoadStrikeAutopilotResult } from "./autopilot.js";
 export { LoadStrikeAutopilotReadiness } from "./autopilot-contracts.js";
-export { CrossPlatformScenarioConfigurator, ScenarioTrackingExtensions, LoadStrikeContext, LoadStrikePluginData, LoadStrikePluginDataTable, LoadStrikeNodeType, LoadStrikeReportFormat, LoadStrikeResponse, LoadStrikeLogLevel, LoadStrikeScenarioOperation, LoadStrikeOperationType, LoadStrikeRunner, LoadStrikeScenario, LoadStrikeSimulation, LoadStrikeMetric, LoadStrikeCounter, LoadStrikeGauge, LoadStrikeStep, LoadStrikeThreshold } from "./runtime.js";
+export { CrossPlatformScenarioConfigurator, ScenarioTrackingExtensions, LoadStrikeContext, LoadStrikePluginData, LoadStrikePluginDataTable, LoadStrikeNodeType, LoadStrikeReportFormat, LoadStrikeResponse, LoadStrikeLogLevel, LoadStrikeScenarioOperation, LoadStrikeOperationType, LoadStrikeRunner, LoadStrikeScenario, LoadStrikeSimulation, CrossPlatformTrackingConfiguration, LoadStrikeMetric, LoadStrikeCounter, LoadStrikeGauge, LoadStrikeStep, LoadStrikeThreshold } from "./runtime.js";
 export { CorrelationStoreConfiguration, CrossPlatformTrackingRuntime, InMemoryCorrelationStore, RedisCorrelationStoreOptions, RedisCorrelationStore, TrackingPayloadBuilder, TrackingFieldSelector } from "./correlation.js";
 export { EndpointAdapterFactory, LOADSTRIKE_TRACE_ID_HEADER, LOADSTRIKE_TRACE_ID_TRACKING_FIELD, TrafficEndpointDefinition, HttpEndpointDefinition, KafkaEndpointDefinition, KafkaSaslOptions, RabbitMqEndpointDefinition, NatsEndpointDefinition, RedisStreamsEndpointDefinition, AzureEventHubsEndpointDefinition, DelegateStreamEndpointDefinition, PushDiffusionEndpointDefinition, HttpOAuth2ClientCredentialsOptions, HttpAuthOptions } from "./transports.js";
 export { DatadogReportingSink, DatadogReportingSinkOptions, GrafanaLokiReportingSink, GrafanaLokiReportingSinkOptions, InfluxDbReportingSink, InfluxDbReportingSinkOptions, OtelCollectorReportingSink, OtelCollectorReportingSinkOptions, SplunkReportingSink, SplunkReportingSinkOptions, TimescaleDbReportingSink, TimescaleDbReportingSinkOptions } from "./sinks.js";

package/dist/esm/local.js

@@ -1007,10 +1007,20 @@ function validateTrackingConfiguration(tracking, sourceEndpoint, destinationEndp
     if (!metricPrefix.trim()) {
         throw new Error("MetricPrefix must be provided.");
     }
+    const observationDurationOverride = pickValue(tracking, "ObservationDurationMs", "observationDurationMs");
+    const observationDurationSeconds = pickValue(tracking, "ObservationDurationSeconds", "observationDurationSeconds", "ObservationDuration");
+    const observationDurationMs = observationDurationOverride != null && String(observationDurationOverride).trim() !== ""
+        ? asNumber(observationDurationOverride)
+        : (observationDurationSeconds == null || String(observationDurationSeconds).trim() === ""
+            ? 0
+            : asNumber(observationDurationSeconds) * 1000);
     validateRedisCorrelationStoreConfiguration(tracking);
     const runModeRaw = stringOrDefault(pickValue(tracking, "RunMode", "runMode"), "GenerateAndCorrelate").trim().toLowerCase();
     const runMode = runModeRaw === "sourceonly" ? "generateandcorrelate" : runModeRaw;
     if (runMode === "generateandcorrelate") {
+        if (observationDurationMs > 0) {
+            throw new Error("ForDuration is only supported for CorrelateExistingTraffic.");
+        }
         if (sourceEndpoint.mode !== "Produce") {
             throw new Error("Source endpoint mode must be Produce for GenerateAndCorrelate mode.");
         }
@@ -1020,6 +1030,9 @@ function validateTrackingConfiguration(tracking, sourceEndpoint, destinationEndp
         return;
     }
     if (runMode === "correlateexistingtraffic") {
+        if (observationDurationMs <= 0) {
+            throw new Error("CorrelateExistingTraffic requires ForDuration with a duration greater than zero.");
+        }
         if (!destinationEndpoint) {
             throw new Error("Destination endpoint must be provided for CorrelateExistingTraffic mode.");
         }

package/dist/esm/runtime.js

@@ -41,6 +41,33 @@ export const LoadStrikeOperationType = {
     Complete: "Complete",
     Error: "Error"
 };
+export const CrossPlatformTrackingConfiguration = {
+    forDuration(configuration, durationSeconds, cancellationSignal) {
+        if (!configuration || typeof configuration !== "object" || Array.isArray(configuration)) {
+            throw new TypeError("Tracking configuration must be provided.");
+        }
+        if (normalizeTrackingRunMode(pickTrackingString(configuration, "RunMode", "runMode", "GenerateAndCorrelate")) !== "correlateexistingtraffic") {
+            throw new Error("ForDuration can only be used with CorrelateExistingTraffic.");
+        }
+        if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+            throw new RangeError("ForDuration duration must be greater than zero.");
+        }
+        const result = {
+            ...configuration,
+            ObservationDurationSeconds: durationSeconds
+        };
+        if (cancellationSignal !== undefined) {
+            if (!(cancellationSignal instanceof AbortSignal)) {
+                throw new TypeError("ForDuration cancellation signal must be an AbortSignal.");
+            }
+            result.ObservationCancellationSignal = cancellationSignal;
+        }
+        return result;
+    },
+    ForDuration(configuration, durationSeconds, cancellationSignal) {
+        return this.forDuration(configuration, durationSeconds, cancellationSignal);
+    }
+};
 export class LoadStrikePluginDataTable {
     /**
      * Exposes the public constructor operation.
@@ -1712,6 +1739,9 @@ export class LoadStrikeScenario {
             ? mapRuntimeTrackingEndpointSpec(destinationSpec, useLoadStrikeTraceIdHeader)
             : null;
         validateRuntimeTrackingConfiguration(copied, sourceEndpoint, destinationEndpoint);
+        if (isCorrelateExistingTrafficTracking(copied) && this.loadSimulations.length > 0) {
+            throw new Error("CorrelateExistingTraffic uses ForDuration and cannot be combined with WithLoadSimulations.");
+        }
         return new LoadStrikeScenario(this.name, this.runHandler, this.initHandler, this.cleanHandler, this.loadSimulations, this.thresholds, copied, this.maxFailCount, this.withoutWarmUpValue, this.warmUpDurationSeconds, this.weight, this.restartIterationOnFail, this.internalLicenseFeatures);
     }
     /**
@@ -1722,6 +1752,9 @@ export class LoadStrikeScenario {
         if (!simulations.length) {
             throw new Error("At least one load simulation should be provided.");
         }
+        if (isCorrelateExistingTrafficTracking(this.trackingConfiguration)) {
+            throw new Error("CorrelateExistingTraffic uses ForDuration and cannot be combined with WithLoadSimulations.");
+        }
         return new LoadStrikeScenario(this.name, this.runHandler, this.initHandler, this.cleanHandler, simulations.map((simulation) => attachLoadSimulationProjection({ ...simulation })), this.thresholds, this.trackingConfiguration, this.maxFailCount, this.withoutWarmUpValue, this.warmUpDurationSeconds, this.weight, this.restartIterationOnFail, this.internalLicenseFeatures);
     }
     /**
@@ -5721,6 +5754,14 @@ class ManagedScenarioTrackingRuntime {
         this.sourceOnlyMode = this.destinationEndpoint == null;
         this.executeOriginalScenarioRun = pickTrackingBoolean(tracking, "ExecuteOriginalScenarioRun", "executeOriginalScenarioRun", false);
         this.correlationTimeoutMs = Math.trunc(pickTrackingNumber(tracking, ["CorrelationTimeoutMs", "correlationTimeoutMs"], pickTrackingNumber(tracking, ["CorrelationTimeoutSeconds", "correlationTimeoutSeconds", "CorrelationTimeout"], 30) * 1000));
+        this.observationDurationMs = Math.trunc(readObservationDurationMs(tracking));
+        const observationCancellationSignal = pickTrackingValue(tracking, "ObservationCancellationSignal", "observationCancellationSignal");
+        if (observationCancellationSignal !== undefined) {
+            if (!(observationCancellationSignal instanceof AbortSignal)) {
+                throw new TypeError("ObservationCancellationSignal must be an AbortSignal.");
+            }
+            this.observationCancellationSignal = observationCancellationSignal;
+        }
         this.timeoutSweepIntervalMs = Math.trunc(pickTrackingNumber(tracking, ["TimeoutSweepIntervalMs", "timeoutSweepIntervalMs"], pickTrackingNumber(tracking, ["TimeoutSweepIntervalSeconds", "timeoutSweepIntervalSeconds"], 1) * 1000));
         this.timeoutBatchSize = Math.trunc(pickTrackingNumber(tracking, ["TimeoutBatchSize", "timeoutBatchSize"], 200));
         this.timeoutCountsAsFailure = pickTrackingBoolean(tracking, "TimeoutCountsAsFailure", "timeoutCountsAsFailure", true);
@@ -5861,8 +5902,7 @@ class ManagedScenarioTrackingRuntime {
             return this.executeSourceOnly();
         }
         if (this.runMode === "correlateexistingtraffic") {
-            const outcome = await this.waitForOutcome(context.scenarioCancellationToken);
-            return this.toResponse(outcome);
+            return await this.observeExistingTraffic(context.scenarioCancellationToken);
         }
         let producedPayload;
         try {
@@ -5938,6 +5978,45 @@ class ManagedScenarioTrackingRuntime {
         });
         return LoadStrikeResponse.ok("source_success");
     }
+    async observeExistingTraffic(signal) {
+        const deadline = Date.now() + this.observationDurationMs;
+        const observationSignal = this.observationCancellationSignal
+            ? combineAbortSignals(signal, this.observationCancellationSignal)
+            : signal;
+        let failureSeen = false;
+        while (Date.now() < deadline && !observationSignal.aborted) {
+            let outcome;
+            try {
+                outcome = await this.waitForOutcomeUntil(deadline, observationSignal);
+            }
+            catch (error) {
+                if (this.observationCancellationSignal?.aborted && !signal.aborted) {
+                    break;
+                }
+                throw error;
+            }
+            if (!outcome) {
+                break;
+            }
+            failureSeen = failureSeen || this.isFailedObservationOutcome(outcome);
+        }
+        this.shutdown = true;
+        await Promise.all([
+            this.sourceLoop,
+            this.destinationLoop,
+            this.timeoutLoop
+        ].filter(Boolean).map((value) => value.catch(() => { })));
+        await this.correlationRuntime.sweepTimeouts(Date.now() + this.correlationTimeoutMs + 1, this.timeoutBatchSize);
+        while (this.outcomeQueue.length > 0) {
+            const outcome = this.outcomeQueue.shift();
+            if (outcome) {
+                failureSeen = failureSeen || this.isFailedObservationOutcome(outcome);
+            }
+        }
+        return failureSeen
+            ? LoadStrikeResponse.fail("tracking_failures", "One or more observed source or destination events did not correlate successfully.", 0)
+            : LoadStrikeResponse.ok("observed");
+    }
     async consumeSourceLoop() {
         while (!this.shutdown) {
             try {
@@ -6151,6 +6230,34 @@ class ManagedScenarioTrackingRuntime {
             }
         }
     }
+    async waitForOutcomeUntil(deadlineMs, signal) {
+        const existing = this.outcomeQueue.shift();
+        if (existing) {
+            return existing;
+        }
+        const remainingMs = deadlineMs - Date.now();
+        if (remainingMs <= 0) {
+            return null;
+        }
+        const waiter = createManagedTrackingWaiter();
+        this.outcomeWaiters.push(waiter);
+        const timeout = sleep(remainingMs).then(() => null);
+        try {
+            return await Promise.race([waiter.promise, timeout, waitForAbort(signal)]);
+        }
+        finally {
+            const index = this.outcomeWaiters.indexOf(waiter);
+            if (index >= 0) {
+                this.outcomeWaiters.splice(index, 1);
+            }
+        }
+    }
+    isFailedObservationOutcome(outcome) {
+        if (outcome.status === "timeout") {
+            return this.timeoutCountsAsFailure;
+        }
+        return outcome.status !== "matched";
+    }
     rejectOutstandingWaiters() {
         for (const rows of this.waiters.values()) {
             for (const waiter of rows) {
@@ -6270,8 +6377,12 @@ function validateRuntimeTrackingConfiguration(tracking, sourceEndpoint, destinat
     if (!metricPrefix.trim()) {
         throw new Error("MetricPrefix must be provided.");
     }
+    const observationDurationMs = readObservationDurationMs(tracking);
     validateRuntimeRedisCorrelationStoreConfiguration(tracking);
     if (runMode === "generateandcorrelate") {
+        if (observationDurationMs > 0) {
+            throw new Error("ForDuration is only supported for CorrelateExistingTraffic.");
+        }
         if (sourceEndpoint.mode !== "Produce") {
             throw new Error("Source endpoint mode must be Produce for GenerateAndCorrelate mode.");
         }
@@ -6281,6 +6392,9 @@ function validateRuntimeTrackingConfiguration(tracking, sourceEndpoint, destinat
         return;
     }
     if (runMode === "correlateexistingtraffic") {
+        if (observationDurationMs <= 0) {
+            throw new Error("CorrelateExistingTraffic requires ForDuration with a duration greater than zero.");
+        }
         if (!destinationEndpoint) {
             throw new Error("Destination endpoint must be provided for CorrelateExistingTraffic mode.");
         }
@@ -6294,6 +6408,15 @@ function validateRuntimeTrackingConfiguration(tracking, sourceEndpoint, destinat
     }
     throw new RangeError(`Unsupported tracking run mode: ${runMode}.`);
 }
+function readObservationDurationMs(tracking) {
+    return pickTrackingNumber(tracking, ["ObservationDurationMs", "observationDurationMs"], pickTrackingNumber(tracking, ["ObservationDurationSeconds", "observationDurationSeconds", "ObservationDuration"], 0) * 1000);
+}
+function isCorrelateExistingTrafficTracking(configuration) {
+    if (!configuration) {
+        return false;
+    }
+    return normalizeTrackingRunMode(pickTrackingString(configuration, "RunMode", "runMode", "GenerateAndCorrelate")) === "correlateexistingtraffic";
+}
 function readUseLoadStrikeTraceIdHeader(tracking) {
     return pickTrackingBoolean(tracking, "UseLoadStrikeTraceIdHeader", "useLoadStrikeTraceIdHeader", false);
 }

package/dist/types/contracts.d.ts

@@ -69,6 +69,7 @@ export interface LoadStrikeTrackingConfigurationSpec {
     Source: LoadStrikeEndpointSpec;
     Destination?: LoadStrikeEndpointSpec;
     RunMode?: string;
+    ObservationDurationSeconds?: number;
     CorrelationTimeoutSeconds?: number;
     TimeoutSweepIntervalSeconds?: number;
     TimeoutBatchSize?: number;

package/dist/types/index.d.ts

@@ -2,8 +2,8 @@ export type { LoadStrikeDateValue, LoadStrikeObject, LoadStrikeRunContext as Loa
 export { LoadStrikeAutopilot, LoadStrikeAutopilotResult } from "./autopilot.js";
 export type { LoadStrikeAutopilotEndpoint, LoadStrikeAutopilotEndpointBinding, LoadStrikeAutopilotLoadSimulationSuggestion, LoadStrikeAutopilotMessageSample, LoadStrikeAutopilotOptions, LoadStrikeAutopilotPlan, LoadStrikeAutopilotPreviewReport, LoadStrikeAutopilotReadinessFailure, LoadStrikeAutopilotRedaction, LoadStrikeAutopilotRequest, LoadStrikeAutopilotResultShape, LoadStrikeAutopilotScenarioPlan, LoadStrikeAutopilotSecretBinding, LoadStrikeAutopilotThresholdSuggestion, LoadStrikeAutopilotTrackingSelectorSuggestion } from "./autopilot-contracts.js";
 export { LoadStrikeAutopilotReadiness } from "./autopilot-contracts.js";
-export { CrossPlatformScenarioConfigurator, ScenarioTrackingExtensions, LoadStrikeContext, LoadStrikePluginData, LoadStrikePluginDataTable, LoadStrikeNodeType, LoadStrikeReportFormat, LoadStrikeResponse, LoadStrikeLogLevel, LoadStrikeScenarioOperation, LoadStrikeOperationType, LoadStrikeRunner, LoadStrikeScenario, LoadStrikeSimulation, LoadStrikeMetric, LoadStrikeCounter, LoadStrikeGauge, LoadStrikeStep, LoadStrikeThreshold } from "./runtime.js";
-export type { ILoadStrikeReportingSink, ILoadStrikeWorkerPlugin, LoadStrikeRunResult, LoadStrikeReportingSink, LoadStrikeRuntimePolicy, LoadStrikeRunnerOptions, LoadStrikeRunContext as LoadStrikeRuntimeContext, LoadStrikeRunContext, LoadStrikeBaseContext, LoadStrikeCounterStats, LoadStrikeDataTransferStats, LoadStrikeGaugeStats, LoadStrikeLogger, LoadStrikeLoadSimulationStats, LoadStrikeMeasurementStats, LoadStrikeMetricStats, LoadStrikeNodeInfo, LoadStrikeMetricValue, LoadStrikeRandom, LoadStrikeReply, LoadStrikeLatencyCount, LoadStrikeLatencyStats, LoadStrikeLoadSimulation, LoadStrikeScenarioInfo, LoadStrikeScenarioInitContext, LoadStrikeScenarioPartition, LoadStrikeScenarioStartInfo, LoadStrikeScenarioContext, LoadStrikeScenarioStats, LoadStrikeTestInfo, LoadStrikeScenarioRuntime, LoadStrikeSessionStartInfo, LoadStrikeSinkSession, LoadStrikeSinkError, LoadStrikeStatusCodeStats, LoadStrikeThresholdResult, LoadStrikeThresholdPredicateContext, CrossPlatformTrackingConfiguration, LoadStrikeStepReply, LoadStrikeStepStats, LoadStrikeStepRuntime, LoadStrikeThresholdOptions, LoadStrikeRequestStats, LoadStrikeWorkerPlugin } from "./runtime.js";
+export { CrossPlatformScenarioConfigurator, ScenarioTrackingExtensions, LoadStrikeContext, LoadStrikePluginData, LoadStrikePluginDataTable, LoadStrikeNodeType, LoadStrikeReportFormat, LoadStrikeResponse, LoadStrikeLogLevel, LoadStrikeScenarioOperation, LoadStrikeOperationType, LoadStrikeRunner, LoadStrikeScenario, LoadStrikeSimulation, CrossPlatformTrackingConfiguration, LoadStrikeMetric, LoadStrikeCounter, LoadStrikeGauge, LoadStrikeStep, LoadStrikeThreshold } from "./runtime.js";
+export type { ILoadStrikeReportingSink, ILoadStrikeWorkerPlugin, LoadStrikeRunResult, LoadStrikeReportingSink, LoadStrikeRuntimePolicy, LoadStrikeRunnerOptions, LoadStrikeRunContext as LoadStrikeRuntimeContext, LoadStrikeRunContext, LoadStrikeBaseContext, LoadStrikeCounterStats, LoadStrikeDataTransferStats, LoadStrikeGaugeStats, LoadStrikeLogger, LoadStrikeLoadSimulationStats, LoadStrikeMeasurementStats, LoadStrikeMetricStats, LoadStrikeNodeInfo, LoadStrikeMetricValue, LoadStrikeRandom, LoadStrikeReply, LoadStrikeLatencyCount, LoadStrikeLatencyStats, LoadStrikeLoadSimulation, LoadStrikeScenarioInfo, LoadStrikeScenarioInitContext, LoadStrikeScenarioPartition, LoadStrikeScenarioStartInfo, LoadStrikeScenarioContext, LoadStrikeScenarioStats, LoadStrikeTestInfo, LoadStrikeScenarioRuntime, LoadStrikeSessionStartInfo, LoadStrikeSinkSession, LoadStrikeSinkError, LoadStrikeStatusCodeStats, LoadStrikeThresholdResult, LoadStrikeThresholdPredicateContext, LoadStrikeStepReply, LoadStrikeStepStats, LoadStrikeStepRuntime, LoadStrikeThresholdOptions, LoadStrikeRequestStats, LoadStrikeWorkerPlugin } from "./runtime.js";
 export { CorrelationStoreConfiguration, CrossPlatformTrackingRuntime, InMemoryCorrelationStore, RedisCorrelationStoreOptions, RedisCorrelationStore, TrackingPayloadBuilder, TrackingFieldSelector } from "./correlation.js";
 export type { CorrelationEntry, DestinationConsumeResult, GatheredRow, CorrelationStoreKind, CorrelationRuntimeOptions, CorrelationRuntimePlugin, CorrelationRuntimeStats, CorrelationStore, SourceProduceResult, TrackingFieldLocation, TrackingPayload } from "./correlation.js";
 export { EndpointAdapterFactory, LOADSTRIKE_TRACE_ID_HEADER, LOADSTRIKE_TRACE_ID_TRACKING_FIELD, TrafficEndpointDefinition, HttpEndpointDefinition, KafkaEndpointDefinition, KafkaSaslOptions, RabbitMqEndpointDefinition, NatsEndpointDefinition, RedisStreamsEndpointDefinition, AzureEventHubsEndpointDefinition, DelegateStreamEndpointDefinition, PushDiffusionEndpointDefinition, HttpOAuth2ClientCredentialsOptions, HttpAuthOptions } from "./transports.js";

package/dist/types/runtime.d.ts

@@ -43,6 +43,10 @@ export declare const LoadStrikeOperationType: {
 export type LoadStrikeOperationType = typeof LoadStrikeOperationType[keyof typeof LoadStrikeOperationType];
 export type LoadStrikeLoadSimulation = Record<string, unknown>;
 export type CrossPlatformTrackingConfiguration = Record<string, unknown>;
+export declare const CrossPlatformTrackingConfiguration: {
+    readonly forDuration: (configuration: Record<string, unknown>, durationSeconds: number, cancellationSignal?: AbortSignal) => CrossPlatformTrackingConfiguration;
+    readonly ForDuration: (configuration: Record<string, unknown>, durationSeconds: number, cancellationSignal?: AbortSignal) => CrossPlatformTrackingConfiguration;
+};
 export interface LoadStrikeRandom {
     next(): number;
     next(maxValue: number): number;
@@ -2056,6 +2060,8 @@ declare class ManagedScenarioTrackingRuntime {
     private readonly sourceOnlyMode;
     private readonly executeOriginalScenarioRun;
     private readonly correlationTimeoutMs;
+    private readonly observationDurationMs;
+    private readonly observationCancellationSignal?;
     private readonly timeoutSweepIntervalMs;
     private readonly timeoutBatchSize;
     private readonly timeoutCountsAsFailure;
@@ -2078,6 +2084,7 @@ declare class ManagedScenarioTrackingRuntime {
     executeIteration(context: InternalScenarioContext, originalRun: () => Promise<LoadStrikeStepReply>, _operation: "WarmUp" | "Bombing"): Promise<LoadStrikeStepReply>;
     dispose(): Promise<void>;
     private executeSourceOnly;
+    private observeExistingTraffic;
     private consumeSourceLoop;
     private consumeDestinationLoop;
     private runTimeoutSweepLoop;
@@ -2090,6 +2097,8 @@ declare class ManagedScenarioTrackingRuntime {
     private resolveTrackingWaiter;
     private pushOutcome;
     private waitForOutcome;
+    private waitForOutcomeUntil;
+    private isFailedObservationOutcome;
     private rejectOutstandingWaiters;
 }
 declare function buildTrackingLeaseKey(sessionId: string, scenarioName: string, tracking: Record<string, unknown>): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadstrike/loadstrike-sdk",
-  "version": "1.0.22601",
+  "version": "1.0.22801",
   "description": "TypeScript and JavaScript SDK for in-process load execution, traffic correlation, and reporting.",
   "keywords": [
     "load-testing",