@loadstrike/loadstrike-sdk 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# LoadStrike for TypeScript and JavaScript
+
+LoadStrike is a TypeScript and JavaScript SDK for defining and running load, traffic-correlation, and reporting scenarios directly inside your application or test process.
+
+## Requirements
+
+- Node.js 20 or later
+
+## Install
+
+```bash
+npm install @loadstrike/loadstrike-sdk
+```
+
+## What It Provides
+
+- Scenario, step, load-simulation, threshold, and metric primitives
+- Native in-process execution with structured run results
+- Local and distributed cluster execution helpers
+- HTML, TXT, CSV, and Markdown report generation
+
+## Supported Transports
+
+- HTTP
+- Kafka
+- RabbitMQ
+- NATS
+- Redis Streams
+- Azure Event Hubs
+- Push Diffusion
+- Delegate and custom stream endpoints
+
+## Supported Reporting Sinks
+
+- InfluxDB
+- TimescaleDB
+- Grafana Loki
+- Datadog
+- Splunk HEC
+- OpenTelemetry Collector
+
+## Quick Start
+
+```ts
+import {
+  LoadStrikeResponse,
+  LoadStrikeRunner,
+  LoadStrikeScenario,
+  LoadStrikeSimulation,
+  LoadStrikeStep
+} from "@loadstrike/loadstrike-sdk";
+
+const scenario = LoadStrikeScenario
+  .create("orders", async (context) => {
+    return LoadStrikeStep.run(
+      "publish-order",
+      context,
+      async () => LoadStrikeResponse.ok("200")
+    );
+  })
+  .withLoadSimulations(LoadStrikeSimulation.inject(10, 1, 20));
+
+const result = await LoadStrikeRunner
+  .registerScenarios(scenario)
+  .withRunnerKey("rkl_your_runner_key")
+  .run();
+```
+
+A valid `RunnerKey` is required to execute live workloads.
+
+## Documentation
+
+https://loadstrike.com/documentation

package/dist/cjs/cluster.js

@@ -0,0 +1,410 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DistributedClusterAgent = exports.DistributedClusterCoordinator = exports.LocalClusterCoordinator = void 0;
+exports.planAgentScenarioAssignments = planAgentScenarioAssignments;
+const node_crypto_1 = require("node:crypto");
+const transports_js_1 = require("./transports.js");
+class LocalClusterCoordinator {
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async dispatch(agents, scenarioNames, assignmentOptions = {}) {
+        const timeoutMs = Math.max(this.options.commandTimeoutMs ?? 120000, 1);
+        const retryCount = Math.max(this.options.retryCount ?? 0, 0);
+        const assignments = planAgentScenarioAssignments(scenarioNames, agents.length, assignmentOptions);
+        const tasks = agents.map((agent, index) => {
+            const dispatch = { scenarioNames: assignments[index] ?? [] };
+            return this.executeWithRetry(agent, dispatch, timeoutMs, retryCount);
+        });
+        const nodeResults = await Promise.all(tasks);
+        return {
+            nodeResults,
+            allRequestCount: nodeResults.reduce((sum, x) => sum + x.allRequestCount, 0),
+            allOkCount: nodeResults.reduce((sum, x) => sum + x.allOkCount, 0),
+            allFailCount: nodeResults.reduce((sum, x) => sum + x.allFailCount, 0),
+            failedNodes: nodeResults.filter((x) => !x.success).length
+        };
+    }
+    async executeWithRetry(agent, dispatch, timeoutMs, retryCount) {
+        let lastResult = {
+            nodeId: agent.nodeId,
+            success: false,
+            allRequestCount: 0,
+            allOkCount: 0,
+            allFailCount: 0,
+            error: "agent did not execute"
+        };
+        for (let attempt = 0; attempt <= retryCount; attempt += 1) {
+            lastResult = await this.withTimeout(agent.execute(dispatch), timeoutMs, agent.nodeId);
+            if (lastResult.success) {
+                return lastResult;
+            }
+        }
+        return lastResult;
+    }
+    async withTimeout(run, timeoutMs, nodeId) {
+        let timeoutHandle;
+        const timeout = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => {
+                resolve({
+                    nodeId,
+                    success: false,
+                    allRequestCount: 0,
+                    allOkCount: 0,
+                    allFailCount: 0,
+                    error: `node timed out after ${timeoutMs}ms`
+                });
+            }, timeoutMs);
+        });
+        const result = await Promise.race([run, timeout]);
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+        return result;
+    }
+}
+exports.LocalClusterCoordinator = LocalClusterCoordinator;
+function planAgentScenarioAssignments(scenarioNames, agentCount, options = {}) {
+    const totalAgents = Math.max(agentCount, 0);
+    const assignments = Array.from({ length: totalAgents }, () => []);
+    if (totalAgents === 0) {
+        return assignments;
+    }
+    if (options.explicitAssignments?.length) {
+        for (let i = 0; i < totalAgents; i += 1) {
+            assignments[i] = [...(options.explicitAssignments[i] ?? [])];
+        }
+        return assignments;
+    }
+    const selected = new Set((options.selectedScenarioNames ?? scenarioNames).map((x) => String(x)));
+    const ordered = scenarioNames.filter((name) => selected.has(name));
+    if (!ordered.length) {
+        return assignments;
+    }
+    const weights = Array.from({ length: totalAgents }, (_, i) => {
+        const raw = options.agentWeights?.[i];
+        if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+            return Math.max(Math.trunc(raw), 1);
+        }
+        return 1;
+    });
+    const weightedCycle = buildWeightedCycle(weights);
+    let cycleIndex = 0;
+    const targets = Array.from({ length: totalAgents }, (_, i) => {
+        const values = options.agentTargets?.[i];
+        if (!values?.length) {
+            return null;
+        }
+        return new Set(values.map((x) => String(x)));
+    });
+    for (const scenarioName of ordered) {
+        const eligible = targets
+            .map((target, index) => ({ index, target }))
+            .filter((row) => row.target == null || row.target.has(scenarioName))
+            .map((row) => row.index);
+        if (!eligible.length) {
+            continue;
+        }
+        let selectedAgent = eligible[0];
+        for (let attempt = 0; attempt < weightedCycle.length; attempt += 1) {
+            const candidate = weightedCycle[(cycleIndex + attempt) % weightedCycle.length];
+            if (eligible.includes(candidate)) {
+                selectedAgent = candidate;
+                cycleIndex = (cycleIndex + attempt + 1) % weightedCycle.length;
+                break;
+            }
+        }
+        assignments[selectedAgent].push(scenarioName);
+    }
+    return assignments;
+}
+class DistributedClusterCoordinator {
+    constructor(options) {
+        this.options = options;
+    }
+    async dispatch(assignments) {
+        const expected = Math.max(this.options.expectedAgentResults, 0);
+        const timeoutMs = Math.max(this.options.commandTimeoutMs ?? 120000, 1);
+        const runSubject = this.buildRunSubject();
+        const replySubject = this.buildReplySubject();
+        const commandProducer = transports_js_1.EndpointAdapterFactory.create(this.natsEndpoint("Produce", "coordinator-command", runSubject));
+        const resultConsumer = transports_js_1.EndpointAdapterFactory.create(this.natsEndpoint("Consume", "coordinator-result", replySubject));
+        try {
+            // Prime the reply subscription before commands are published because core NATS subjects do not retain messages.
+            await resultConsumer.consume();
+            for (let i = 0; i < assignments.length; i += 1) {
+                const commandId = (0, node_crypto_1.randomUUID)().replace(/-/g, "");
+                const command = {
+                    commandId,
+                    sessionId: this.options.sessionId,
+                    testSuite: this.options.testSuite,
+                    testName: this.options.testName,
+                    agentIndex: i,
+                    agentCount: expected,
+                    targetScenarios: assignments[i] ?? [],
+                    replySubject
+                };
+                await commandProducer.produce({
+                    headers: {
+                        "x-cluster-command-id": commandId,
+                        "x-cluster-reply-subject": replySubject
+                    },
+                    body: command
+                });
+            }
+            const byCommand = new Map();
+            const deadline = Date.now() + timeoutMs;
+            while (byCommand.size < expected && Date.now() < deadline) {
+                const payload = await resultConsumer.consume();
+                if (!payload?.body || typeof payload.body !== "object" || Array.isArray(payload.body)) {
+                    await sleep(5);
+                    continue;
+                }
+                const result = parseRunResult(payload.body);
+                if (!result.commandId) {
+                    continue;
+                }
+                byCommand.set(result.commandId, result);
+            }
+            const nodeResults = Array.from(byCommand.values()).map((result) => convertRunResult(result));
+            return {
+                nodeResults,
+                allRequestCount: nodeResults.reduce((sum, x) => sum + x.allRequestCount, 0),
+                allOkCount: nodeResults.reduce((sum, x) => sum + x.allOkCount, 0),
+                allFailCount: nodeResults.reduce((sum, x) => sum + x.allFailCount, 0),
+                failedNodes: nodeResults.filter((x) => !x.success).length + Math.max(expected - nodeResults.length, 0),
+                missingNodes: Math.max(expected - nodeResults.length, 0),
+                runSubject,
+                replySubject
+            };
+        }
+        finally {
+            await resultConsumer.dispose?.().catch(() => { });
+            await commandProducer.dispose?.().catch(() => { });
+        }
+    }
+    buildRunSubject() {
+        return `loadstrike.${sanitizeToken(this.options.clusterId)}.${sanitizeToken(this.options.agentGroup ?? "default")}.run`;
+    }
+    buildReplySubject() {
+        return `loadstrike.${sanitizeToken(this.options.clusterId)}.${sanitizeToken(this.options.sessionId)}.reply.${(0, node_crypto_1.randomUUID)().replace(/-/g, "")}`;
+    }
+    natsEndpoint(mode, name, subject) {
+        return {
+            kind: "Nats",
+            mode,
+            name,
+            trackingField: "header:x-cluster-command-id",
+            nats: {
+                ...(this.options.nats ?? {}),
+                Subject: subject,
+                StartFromEarliest: true
+            }
+        };
+    }
+}
+exports.DistributedClusterCoordinator = DistributedClusterCoordinator;
+class DistributedClusterAgent {
+    constructor(options) {
+        this.commandConsumer = null;
+        this.options = options;
+    }
+    async dispose() {
+        await this.commandConsumer?.dispose?.().catch(() => { });
+        this.commandConsumer = null;
+    }
+    async pollAndExecuteOnce(execute) {
+        const runSubject = `loadstrike.${sanitizeToken(this.options.clusterId)}.${sanitizeToken(this.options.agentGroup ?? "default")}.run`;
+        const queueGroup = `loadstrike.${sanitizeToken(this.options.clusterId)}.${sanitizeToken(this.options.agentGroup ?? "default")}.agents`;
+        if (!this.commandConsumer) {
+            this.commandConsumer = transports_js_1.EndpointAdapterFactory.create({
+                kind: "Nats",
+                mode: "Consume",
+                name: `agent-${this.options.agentId}`,
+                trackingField: "header:x-cluster-command-id",
+                nats: {
+                    ...(this.options.nats ?? {}),
+                    Subject: runSubject,
+                    QueueGroup: queueGroup,
+                    StartFromEarliest: true
+                }
+            });
+        }
+        const payload = await this.commandConsumer.consume();
+        if (!payload?.body || typeof payload.body !== "object" || Array.isArray(payload.body)) {
+            return false;
+        }
+        const command = parseRunCommand(payload.body);
+        if (!command.commandId) {
+            return false;
+        }
+        const replySubject = stringOrDefault(payload.headers?.["x-cluster-reply-subject"], command.replySubject ?? "");
+        const resultProducer = replySubject
+            ? transports_js_1.EndpointAdapterFactory.create({
+                kind: "Nats",
+                mode: "Produce",
+                name: `agent-${this.options.agentId}-result`,
+                trackingField: "header:x-cluster-command-id",
+                nats: {
+                    ...(this.options.nats ?? {}),
+                    Subject: replySubject
+                }
+            })
+            : null;
+        try {
+            let result;
+            try {
+                const nodeResult = await execute({ scenarioNames: command.targetScenarios });
+                result = {
+                    commandId: command.commandId,
+                    agentId: this.options.agentId,
+                    isSuccess: nodeResult.success,
+                    errorMessage: nodeResult.error,
+                    stats: nodeResult.stats ?? {
+                        allRequestCount: nodeResult.allRequestCount,
+                        allOkCount: nodeResult.allOkCount,
+                        allFailCount: nodeResult.allFailCount
+                    }
+                };
+            }
+            catch (error) {
+                result = {
+                    commandId: command.commandId,
+                    agentId: this.options.agentId,
+                    isSuccess: false,
+                    errorMessage: String(error ?? "agent execution failed")
+                };
+            }
+            if (resultProducer) {
+                await resultProducer.produce({
+                    headers: {
+                        "x-cluster-command-id": result.commandId
+                    },
+                    body: result
+                });
+            }
+            return true;
+        }
+        finally {
+            await resultProducer?.dispose?.().catch(() => { });
+        }
+    }
+}
+exports.DistributedClusterAgent = DistributedClusterAgent;
+function parseRunCommand(value) {
+    const targetScenarios = Array.isArray(value.targetScenarios)
+        ? value.targetScenarios.map((x) => String(x))
+        : Array.isArray(value.TargetScenarios)
+            ? value.TargetScenarios.map((x) => String(x))
+            : [];
+    return {
+        commandId: stringOrDefault(value.commandId, stringOrDefault(value.CommandId, "")),
+        sessionId: stringOrDefault(value.sessionId, stringOrDefault(value.SessionId, "")),
+        testSuite: stringOrDefault(value.testSuite, stringOrDefault(value.TestSuite, "")),
+        testName: stringOrDefault(value.testName, stringOrDefault(value.TestName, "")),
+        agentIndex: numberOrDefault(value.agentIndex, numberOrDefault(value.AgentIndex, 0)),
+        agentCount: numberOrDefault(value.agentCount, numberOrDefault(value.AgentCount, 0)),
+        targetScenarios,
+        replySubject: stringOrDefault(value.replySubject, stringOrDefault(value.ReplySubject, ""))
+    };
+}
+function parseRunResult(value) {
+    const statsValue = value.stats ?? value.Stats;
+    const statsRecord = statsValue && typeof statsValue === "object" && !Array.isArray(statsValue)
+        ? statsValue
+        : null;
+    return {
+        commandId: stringOrDefault(value.commandId, stringOrDefault(value.CommandId, "")),
+        agentId: stringOrDefault(value.agentId, stringOrDefault(value.AgentId, "")),
+        isSuccess: booleanOrDefault(value.isSuccess, booleanOrDefault(value.IsSuccess, false)),
+        errorMessage: stringOrDefault(value.errorMessage, stringOrDefault(value.ErrorMessage, "")),
+        stats: statsRecord
+            ? {
+                allBytes: numberOrDefault(statsRecord.allBytes, numberOrDefault(statsRecord.AllBytes, 0)),
+                allRequestCount: numberOrDefault(statsRecord.allRequestCount, numberOrDefault(statsRecord.AllRequestCount, 0)),
+                allOkCount: numberOrDefault(statsRecord.allOkCount, numberOrDefault(statsRecord.AllOkCount, 0)),
+                allFailCount: numberOrDefault(statsRecord.allFailCount, numberOrDefault(statsRecord.AllFailCount, 0)),
+                durationMs: numberOrDefault(statsRecord.durationMs, numberOrDefault(statsRecord.DurationMs, 0)),
+                metrics: recordOrUndefined(statsRecord.metrics ?? statsRecord.Metrics),
+                scenarioStats: arrayOrUndefined(statsRecord.scenarioStats ?? statsRecord.ScenarioStats),
+                thresholds: arrayOrUndefined(statsRecord.thresholds ?? statsRecord.Thresholds),
+                pluginsData: arrayOrUndefined(statsRecord.pluginsData ?? statsRecord.PluginsData),
+                nodeInfo: recordOrUndefined(statsRecord.nodeInfo ?? statsRecord.NodeInfo),
+                testInfo: recordOrUndefined(statsRecord.testInfo ?? statsRecord.TestInfo)
+            }
+            : undefined
+    };
+}
+function convertRunResult(result) {
+    return {
+        nodeId: result.agentId || "unknown-agent",
+        success: result.isSuccess,
+        allRequestCount: result.stats?.allRequestCount ?? 0,
+        allOkCount: result.stats?.allOkCount ?? 0,
+        allFailCount: result.stats?.allFailCount ?? 0,
+        stats: result.stats,
+        error: result.errorMessage ?? ""
+    };
+}
+function sanitizeToken(value) {
+    if (!value.trim()) {
+        return "default";
+    }
+    return value.replace(/[^a-zA-Z0-9\-_]/g, "_");
+}
+function buildWeightedCycle(weights) {
+    const cycle = [];
+    for (let i = 0; i < weights.length; i += 1) {
+        for (let repeat = 0; repeat < Math.max(weights[i], 1); repeat += 1) {
+            cycle.push(i);
+        }
+    }
+    return cycle.length ? cycle : [0];
+}
+function stringOrDefault(value, fallback) {
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    return fallback;
+}
+function numberOrDefault(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return fallback;
+}
+function recordOrUndefined(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function arrayOrUndefined(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+function booleanOrDefault(value, fallback) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return value !== 0;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === "true" || normalized === "1" || normalized === "yes") {
+            return true;
+        }
+        if (normalized === "false" || normalized === "0" || normalized === "no") {
+            return false;
+        }
+    }
+    return fallback;
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/cjs/contracts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });