@softprobe/softprobe-js 2.0.0

package/dist/cli/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/cli/diff.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for softprobe. Usage: softprobe diff <cassette.ndjson> <targetUrl>
+ * Task 21.3.1: on mismatch, prints colored diff of recorded vs live and exits 1.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CLI entry point for softprobe. Usage: softprobe diff <cassette.ndjson> <targetUrl>
+ * Task 21.3.1: on mismatch, prints colored diff of recorded vs live and exits 1.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const diff_1 = require("./cli/diff");
+const diff_reporter_1 = require("./cli/diff-reporter");
+const args = process.argv.slice(2);
+const command = args[0];
+const HELP_COMMANDS = new Set(['help', '--help', '-h']);
+const VERSION_COMMANDS = new Set(['version', '--version', '-v']);
+const ignoreBodyPaths = [];
+const positional = [];
+for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--ignore-paths' && args[i + 1]) {
+        ignoreBodyPaths.push(args[++i]);
+    }
+    else {
+        positional.push(args[i]);
+    }
+}
+const file = positional[0];
+const target = positional[1];
+function usage() {
+    console.error('Usage: softprobe diff [--ignore-paths <path> ...] <cassette.ndjson> <targetUrl>');
+    console.error('       softprobe --help');
+    console.error('       softprobe --version');
+    console.error('  Replays the recorded inbound request to the target with coordination headers.');
+    console.error('  --ignore-paths  JSON path to omit from body comparison (e.g. http.headers for upstream variance).');
+}
+function printVersion() {
+    // Read version from package metadata at runtime for both dist and ts-node execution.
+    // dist/cli.js -> ../package.json, src/cli.ts -> ../package.json
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const pkg = require('../package.json');
+    process.stdout.write(`softprobe ${pkg.version ?? '0.0.0'}\n`);
+}
+/** Extracts recorded status and body from cassette inbound (responsePayload or top-level). */
+function getRecordedResponse(inbound) {
+    const payload = inbound.responsePayload;
+    return {
+        statusCode: payload?.statusCode ?? payload?.status ?? inbound.statusCode,
+        body: payload?.body,
+    };
+}
+async function main() {
+    if (!command || HELP_COMMANDS.has(command)) {
+        usage();
+        return command ? 0 : 1;
+    }
+    if (VERSION_COMMANDS.has(command)) {
+        printVersion();
+        return 0;
+    }
+    if (command !== 'diff' || !file || !target) {
+        usage();
+        return 1;
+    }
+    try {
+        const { response, inbound } = await (0, diff_1.runDiff)(file, target);
+        const liveBody = await response.text();
+        const recorded = getRecordedResponse(inbound);
+        const match = (0, diff_reporter_1.reportDiff)(recorded, { status: response.status, body: liveBody }, { ignoreBodyPaths: ignoreBodyPaths.length ? ignoreBodyPaths : undefined });
+        if (!match)
+            return 1;
+        process.stderr.write('softprobe diff: PASS (response matches recording)\n');
+        if (liveBody)
+            process.stdout.write(liveBody + (liveBody.endsWith('\n') ? '' : '\n'));
+        return 0;
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config/config-manager.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Config loader for .softprobe/config.yml.
+ * Must be discoverable synchronously at boot (softprobe/init first).
+ */
+/**
+ * Reads and caches .softprobe/config.yml. Exposes parsed config via get().
+ * Accepts optional configPath for testing (fixture path).
+ */
+export declare class ConfigManager {
+    private cfg;
+    private ignoreRegexes;
+    constructor(configPath?: string);
+    /** Returns the parsed config object. */
+    get(): Record<string, unknown>;
+    /** Returns compiled ignore-url patterns (for bypass checks). */
+    getIgnoreRegexes(): RegExp[];
+    /** Returns true if url matches any replay.ignoreUrls pattern; false if no url or no match. */
+    shouldIgnore(url?: string): boolean;
+}
+//# sourceMappingURL=config-manager.d.ts.map

package/dist/config/config-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../../src/config/config-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,aAAa,CAAgB;gBAEzB,UAAU,GAAE,MAA4B;IAWpD,wCAAwC;IACxC,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI9B,gEAAgE;IAChE,gBAAgB,IAAI,MAAM,EAAE;IAI5B,8FAA8F;IAC9F,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO;CAIpC"}

package/dist/config/config-manager.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Config loader for .softprobe/config.yml.
+ * Must be discoverable synchronously at boot (softprobe/init first).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigManager = void 0;
+const fs_1 = __importDefault(require("fs"));
+const yaml_1 = require("yaml");
+const DEFAULT_CONFIG_PATH = './.softprobe/config.yml';
+/**
+ * Reads and caches .softprobe/config.yml. Exposes parsed config via get().
+ * Accepts optional configPath for testing (fixture path).
+ */
+class ConfigManager {
+    constructor(configPath = DEFAULT_CONFIG_PATH) {
+        this.ignoreRegexes = [];
+        const raw = fs_1.default.readFileSync(configPath, 'utf8');
+        this.cfg = (0, yaml_1.parse)(raw);
+        /** Default mode when not set in YAML (design: global default for bootstrap). */
+        if (this.cfg.mode === undefined) {
+            this.cfg.mode = 'PASSTHROUGH';
+        }
+        const urls = this.cfg.replay?.ignoreUrls ?? [];
+        this.ignoreRegexes = urls.map((p) => new RegExp(p));
+    }
+    /** Returns the parsed config object. */
+    get() {
+        return this.cfg;
+    }
+    /** Returns compiled ignore-url patterns (for bypass checks). */
+    getIgnoreRegexes() {
+        return this.ignoreRegexes;
+    }
+    /** Returns true if url matches any replay.ignoreUrls pattern; false if no url or no match. */
+    shouldIgnore(url) {
+        if (url == null || url === '')
+            return false;
+        return this.ignoreRegexes.some((re) => re.test(url));
+    }
+}
+exports.ConfigManager = ConfigManager;
+//# sourceMappingURL=config-manager.js.map

package/dist/config/config-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/config/config-manager.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;AAEH,4CAAoB;AACpB,+BAA6B;AAE7B,MAAM,mBAAmB,GAAG,yBAAyB,CAAC;AAEtD;;;GAGG;AACH,MAAa,aAAa;IAIxB,YAAY,aAAqB,mBAAmB;QAF5C,kBAAa,GAAa,EAAE,CAAC;QAGnC,MAAM,GAAG,GAAG,YAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,GAAG,IAAA,YAAK,EAAC,GAAG,CAA4B,CAAC;QACjD,gFAAgF;QAChF,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,aAAa,CAAC;QAChC,CAAC;QACD,MAAM,IAAI,GAAI,IAAI,CAAC,GAAG,CAAC,MAAgD,EAAE,UAAU,IAAI,EAAE,CAAC;QAC1F,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,wCAAwC;IACxC,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,gEAAgE;IAChE,gBAAgB;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,8FAA8F;IAC9F,YAAY,CAAC,GAAY;QACvB,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;QAC5C,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;CACF;AA9BD,sCA8BC"}

package/dist/context.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Single immutable context API for Softprobe (design-context.md).
+ * One module: read via SoftprobeContext getters, write via withData/initGlobal/fromHeaders/run.
+ */
+import type { Context } from '@opentelemetry/api';
+import type { Cassette, SoftprobeCassetteRecord, SoftprobeRunOptions } from './types/schema';
+import type { SemanticMatcher } from './core/matcher/matcher';
+import { SoftprobeMatcher } from './core/matcher/softprobe-matcher';
+/** Context key under which softprobe state is stored in OTel Context. Exported for tests. */
+export declare const SOFTPROBE_CONTEXT_KEY: symbol;
+/** Internal stored shape (not exported). */
+interface Stored {
+    mode: 'CAPTURE' | 'REPLAY' | 'PASSTHROUGH';
+    storage?: Cassette;
+    cassetteDirectory?: string;
+    traceId?: string;
+    strictReplay?: boolean;
+    strictComparison?: boolean;
+    matcher?: SemanticMatcher | SoftprobeMatcher;
+    inboundRecord?: SoftprobeCassetteRecord;
+}
+/** Partial context for run() and withData(); all fields optional. */
+interface PartialData {
+    mode?: 'CAPTURE' | 'REPLAY' | 'PASSTHROUGH';
+    storage?: Cassette;
+    cassetteDirectory?: string;
+    traceId?: string;
+    strictReplay?: boolean;
+    strictComparison?: boolean;
+    matcher?: SemanticMatcher | SoftprobeMatcher | unknown;
+    inboundRecord?: SoftprobeCassetteRecord;
+}
+/**
+ * Returns a cached cassette for a given (cassetteDirectory, traceId) pair.
+ * Task 13.5/13.6: only this module creates NdjsonCassette; request-storage and middleware call this.
+ */
+declare function getOrCreateCassette(cassetteDirectory: string, traceId: string): Cassette;
+/**
+ * Returns the current softprobe state from the given OTel context, or global default when empty.
+ * When otelContext is omitted, uses context.active().
+ */
+declare function active(otelContext?: Context): Stored;
+/**
+ * Returns a new OTel context with the given softprobe data. Does not mutate otelContext.
+ */
+declare function withData(otelContext: Context, data: PartialData): Context;
+/**
+ * Seeds the global default from config. Call at boot.
+ * Task 13.1: accepts cassetteDirectory; when set, runtime cassette paths are derived as {cassetteDirectory}/{traceId}.ndjson.
+ */
+declare function initGlobal(config: {
+    mode?: string;
+    cassetteDirectory?: string;
+    storage?: Cassette;
+    strictReplay?: boolean;
+    strictComparison?: boolean;
+}): void;
+/**
+ * Returns a new softprobe state by applying coordination headers over base. Used by middleware.
+ */
+declare function fromHeaders(base: Stored, headers: Record<string, string | string[] | undefined>): Stored;
+/**
+ * Sets the global matcher used when active context has no matcher (e.g. server REPLAY mode).
+ */
+declare function setGlobalReplayMatcher(matcher: SoftprobeMatcher | undefined): void;
+declare function getTraceId(otelContext?: Context): string;
+declare function getMode(otelContext?: Context): 'CAPTURE' | 'REPLAY' | 'PASSTHROUGH';
+declare function getCassette(otelContext?: Context): Cassette | undefined;
+/** Task 13.1: directory for per-trace cassette files; paths are {cassetteDirectory}/{traceId}.ndjson. */
+declare function getCassetteDirectory(otelContext?: Context): string | undefined;
+declare function getScopedCassette(otelContext?: Context): Cassette | undefined;
+declare function getStrictReplay(otelContext?: Context): boolean;
+declare function getStrictComparison(otelContext?: Context): boolean;
+/** Returns the matcher from active context only. */
+declare function getMatcher(otelContext?: Context): SemanticMatcher | SoftprobeMatcher | undefined;
+declare function getInboundRecord(otelContext?: Context): SoftprobeCassetteRecord | undefined;
+declare function run<T>(options: SoftprobeRunOptions, fn: () => T | Promise<T>): T | Promise<T>;
+export declare const SoftprobeContext: {
+    active: typeof active;
+    getTraceId: typeof getTraceId;
+    getMode: typeof getMode;
+    getCassette: typeof getCassette;
+    getCassetteDirectory: typeof getCassetteDirectory;
+    getScopedCassette: typeof getScopedCassette;
+    getStrictReplay: typeof getStrictReplay;
+    getStrictComparison: typeof getStrictComparison;
+    getMatcher: typeof getMatcher;
+    getInboundRecord: typeof getInboundRecord;
+    withData: typeof withData;
+    initGlobal: typeof initGlobal;
+    fromHeaders: typeof fromHeaders;
+    setGlobalReplayMatcher: typeof setGlobalReplayMatcher;
+    run: typeof run;
+    /** Task 13.6: Obtain cassette for (directory, traceId) without constructing; used by request-storage/middleware. */
+    getOrCreateCassette: typeof getOrCreateCassette;
+};
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/context.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Single immutable context API for Softprobe (design-context.md).
+ * One module: read via SoftprobeContext getters, write via withData/initGlobal/fromHeaders/run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoftprobeContext = exports.SOFTPROBE_CONTEXT_KEY = void 0;
+const crypto_1 = require("crypto");
+const api_1 = require("@opentelemetry/api");
+const softprobe_matcher_1 = require("./core/matcher/softprobe-matcher");
+const extract_key_1 = require("./core/matcher/extract-key");
+const ndjson_cassette_1 = require("./core/cassette/ndjson-cassette");
+/** Context key under which softprobe state is stored in OTel Context. Exported for tests. */
+exports.SOFTPROBE_CONTEXT_KEY = (0, api_1.createContextKey)('softprobe_context');
+let globalDefault = {
+    mode: 'PASSTHROUGH',
+    strictReplay: false,
+    strictComparison: false,
+};
+let globalReplayMatcher;
+const cassetteByPath = new Map();
+/**
+ * Returns a cached cassette for a given (cassetteDirectory, traceId) pair.
+ * Task 13.5/13.6: only this module creates NdjsonCassette; request-storage and middleware call this.
+ */
+function getOrCreateCassette(cassetteDirectory, traceId) {
+    const key = `${cassetteDirectory}::${traceId}`;
+    const existing = cassetteByPath.get(key);
+    if (existing)
+        return existing;
+    const created = new ndjson_cassette_1.NdjsonCassette(cassetteDirectory, traceId);
+    cassetteByPath.set(key, created);
+    return created;
+}
+function merge(base, partial) {
+    return {
+        ...base,
+        ...(partial.mode !== undefined && { mode: partial.mode }),
+        ...(partial.storage !== undefined && { storage: partial.storage }),
+        ...(partial.cassetteDirectory !== undefined && { cassetteDirectory: partial.cassetteDirectory }),
+        ...(partial.traceId !== undefined && { traceId: partial.traceId }),
+        ...(partial.strictReplay !== undefined && { strictReplay: partial.strictReplay }),
+        ...(partial.strictComparison !== undefined && { strictComparison: partial.strictComparison }),
+        ...(partial.matcher !== undefined && { matcher: partial.matcher }),
+        ...(partial.inboundRecord !== undefined && { inboundRecord: partial.inboundRecord }),
+    };
+}
+/**
+ * Returns the current softprobe state from the given OTel context, or global default when empty.
+ * When otelContext is omitted, uses context.active().
+ */
+function active(otelContext = api_1.context.active()) {
+    const value = otelContext.getValue(exports.SOFTPROBE_CONTEXT_KEY);
+    return value ?? globalDefault;
+}
+/**
+ * Returns a new OTel context with the given softprobe data. Does not mutate otelContext.
+ */
+function withData(otelContext, data) {
+    const stored = merge(globalDefault, data);
+    return otelContext.setValue(exports.SOFTPROBE_CONTEXT_KEY, stored);
+}
+/**
+ * Seeds the global default from config. Call at boot.
+ * Task 13.1: accepts cassetteDirectory; when set, runtime cassette paths are derived as {cassetteDirectory}/{traceId}.ndjson.
+ */
+function initGlobal(config) {
+    globalDefault = {
+        mode: config.mode || 'PASSTHROUGH',
+        ...(config.storage !== undefined && { storage: config.storage }),
+        ...(config.cassetteDirectory !== undefined && { cassetteDirectory: config.cassetteDirectory }),
+        strictReplay: config.strictReplay ?? false,
+        strictComparison: config.strictComparison ?? false,
+    };
+}
+const HEADER_MODE = 'x-softprobe-mode';
+const HEADER_TRACE_ID = 'x-softprobe-trace-id';
+function readHeaderValue(headers, key) {
+    const value = headers[key];
+    if (typeof value === 'string' && value)
+        return value;
+    if (Array.isArray(value) && typeof value[0] === 'string' && value[0])
+        return value[0];
+    return undefined;
+}
+/**
+ * Returns a new softprobe state by applying coordination headers over base. Used by middleware.
+ */
+function fromHeaders(base, headers) {
+    const mode = readHeaderValue(headers, HEADER_MODE);
+    const traceId = readHeaderValue(headers, HEADER_TRACE_ID);
+    return {
+        ...base,
+        ...(mode && (mode === 'REPLAY' || mode === 'CAPTURE' || mode === 'PASSTHROUGH') && { mode: mode }),
+        ...(traceId && { traceId }),
+    };
+}
+/**
+ * Sets the global matcher used when active context has no matcher (e.g. server REPLAY mode).
+ */
+function setGlobalReplayMatcher(matcher) {
+    globalReplayMatcher = matcher;
+}
+function getTraceId(otelContext) {
+    return active(otelContext).traceId ?? '';
+}
+function getMode(otelContext) {
+    return active(otelContext).mode;
+}
+function getCassette(otelContext) {
+    return active(otelContext).storage;
+}
+/** Task 13.1: directory for per-trace cassette files; paths are {cassetteDirectory}/{traceId}.ndjson. */
+function getCassetteDirectory(otelContext) {
+    return active(otelContext).cassetteDirectory;
+}
+function getScopedCassette(otelContext = api_1.context.active()) {
+    const value = otelContext.getValue(exports.SOFTPROBE_CONTEXT_KEY);
+    return value?.storage;
+}
+function getStrictReplay(otelContext) {
+    return active(otelContext).strictReplay ?? false;
+}
+function getStrictComparison(otelContext) {
+    return active(otelContext).strictComparison ?? false;
+}
+/** Returns the matcher from active context only. */
+function getMatcher(otelContext) {
+    const ctx = otelContext ?? api_1.context.active();
+    const stored = active(ctx);
+    return stored.matcher;
+}
+function getInboundRecord(otelContext) {
+    return active(otelContext).inboundRecord;
+}
+/** Runs fn inside an OTel scope seeded from required Softprobe run options. */
+function ensureTraceId(stored, fallback) {
+    return stored.traceId ? stored : { ...stored, traceId: fallback };
+}
+function resolveStorage(merged, traceId) {
+    if (merged.storage)
+        return merged.storage;
+    const dir = merged.cassetteDirectory;
+    if (dir && traceId)
+        return getOrCreateCassette(dir, traceId);
+    return undefined;
+}
+function run(options, fn) {
+    const otelContextAtCall = api_1.context.active();
+    const base = active(otelContextAtCall);
+    const mergedBase = merge(base, options);
+    const defaultTraceId = () => (0, crypto_1.randomBytes)(16).toString('hex');
+    if (options.mode === 'REPLAY') {
+        const traceId = options.traceId !== undefined && options.traceId !== null
+            ? options.traceId
+            : mergedBase.traceId || base.traceId || defaultTraceId();
+        const storage = resolveStorage(mergedBase, traceId);
+        return (async () => {
+            if (!storage)
+                throw new Error('Softprobe REPLAY requires storage or cassetteDirectory + traceId');
+            const records = await storage.loadTrace();
+            const matcher = new softprobe_matcher_1.SoftprobeMatcher();
+            matcher._setRecords(records);
+            matcher.use(options.matcher ?? (0, extract_key_1.createDefaultMatcher)());
+            const withReplayData = merge(mergedBase, { matcher, storage });
+            const withTraceId = ensureTraceId(withReplayData, traceId);
+            // Use context captured when run() was called (e.g. from middleware) so REPLAY scope
+            // is attached to the right parent; context.active() here would be wrong after await.
+            const ctxWith = withData(otelContextAtCall, withTraceId);
+            return api_1.context.with(ctxWith, fn);
+        })();
+    }
+    const withTraceId = ensureTraceId(mergedBase, mergedBase.traceId || base.traceId || defaultTraceId());
+    const storage = resolveStorage(mergedBase, withTraceId.traceId);
+    const finalStored = storage ? merge(withTraceId, { storage }) : withTraceId;
+    const ctxWith = withData(api_1.context.active(), finalStored);
+    return api_1.context.with(ctxWith, fn);
+}
+exports.SoftprobeContext = {
+    active,
+    getTraceId,
+    getMode,
+    getCassette,
+    getCassetteDirectory,
+    getScopedCassette,
+    getStrictReplay,
+    getStrictComparison,
+    getMatcher,
+    getInboundRecord,
+    withData,
+    initGlobal,
+    fromHeaders,
+    setGlobalReplayMatcher,
+    run,
+    /** Task 13.6: Obtain cassette for (directory, traceId) without constructing; used by request-storage/middleware. */
+    getOrCreateCassette,
+};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/core/bindings/http-span.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed binding for HTTP spans (design §7.2).
+ * tagRequest sets protocol, identifier (via httpIdentifier), and optional request body.
+ */
+/** Span-like with setAttribute (OTel Span or test span). */
+type SpanLike = {
+    setAttribute?(key: string, value: unknown): void;
+} | undefined;
+/** Span-like with readable attributes. */
+type ReadableSpan = {
+    attributes?: Record<string, unknown>;
+} | undefined;
+/** Data extracted from an http-tagged span by fromSpan. */
+export type HttpSpanData = {
+    protocol: 'http';
+    identifier: string;
+};
+/**
+ * Tags the span with http protocol and identifier from method + url.
+ * Optionally stores a small request body (e.g. bodyText) when provided.
+ *
+ * @param method - HTTP method (e.g. 'GET', 'POST').
+ * @param url - Request URL.
+ * @param bodyText - Optional request body string (stored as-is when provided).
+ * @param span - Target span; pass test span in tests.
+ */
+export declare function tagRequest(method: string, url: string, bodyText?: string, span?: SpanLike): void;
+/**
+ * Reads protocol and identifier from a span. Returns http data when the span
+ * is tagged with softprobe.protocol === 'http'; otherwise null.
+ */
+export declare function fromSpan(span: ReadableSpan): HttpSpanData | null;
+/** HttpSpan namespace for tagRequest and fromSpan. */
+export declare const HttpSpan: {
+    tagRequest: typeof tagRequest;
+    fromSpan: typeof fromSpan;
+};
+export {};
+//# sourceMappingURL=http-span.d.ts.map

package/dist/core/bindings/http-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-span.d.ts","sourceRoot":"","sources":["../../../src/core/bindings/http-span.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,4DAA4D;AAC5D,KAAK,QAAQ,GAAG;IAAE,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,CAAC;AAEjF,0CAA0C;AAC1C,KAAK,YAAY,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,SAAS,CAAC;AAEzE,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,QAAQ,GACd,IAAI,CAON;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,IAAI,CAqBhE;AAED,sDAAsD;AACtD,eAAO,MAAM,QAAQ;;;CAA2B,CAAC"}

package/dist/core/bindings/http-span.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Typed binding for HTTP spans (design §7.2).
+ * tagRequest sets protocol, identifier (via httpIdentifier), and optional request body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpSpan = void 0;
+exports.tagRequest = tagRequest;
+exports.fromSpan = fromSpan;
+const identifier_1 = require("../identifier");
+/**
+ * Tags the span with http protocol and identifier from method + url.
+ * Optionally stores a small request body (e.g. bodyText) when provided.
+ *
+ * @param method - HTTP method (e.g. 'GET', 'POST').
+ * @param url - Request URL.
+ * @param bodyText - Optional request body string (stored as-is when provided).
+ * @param span - Target span; pass test span in tests.
+ */
+function tagRequest(method, url, bodyText, span) {
+    if (!span?.setAttribute)
+        return;
+    span.setAttribute('softprobe.protocol', 'http');
+    span.setAttribute('softprobe.identifier', (0, identifier_1.httpIdentifier)(method, url));
+    if (bodyText !== undefined) {
+        span.setAttribute('softprobe.request.body', bodyText);
+    }
+}
+/**
+ * Reads protocol and identifier from a span. Returns http data when the span
+ * is tagged with softprobe.protocol === 'http'; otherwise null.
+ */
+function fromSpan(span) {
+    const protocol = span?.attributes?.['softprobe.protocol'];
+    if (protocol === 'http') {
+        const identifier = span?.attributes?.['softprobe.identifier'];
+        if (typeof identifier === 'string')
+            return { protocol: 'http', identifier };
+    }
+    // OTel HTTP client span fallback (no softprobe tagging required).
+    const attrs = span?.attributes ?? {};
+    const methodRaw = attrs['http.request.method'] ??
+        attrs['http.method'] ??
+        attrs['http.request.method_original'];
+    const urlRaw = attrs['url.full'] ??
+        attrs['http.url'] ??
+        attrs['http.target'];
+    if (typeof methodRaw === 'string' && typeof urlRaw === 'string') {
+        return { protocol: 'http', identifier: (0, identifier_1.httpIdentifier)(methodRaw, urlRaw) };
+    }
+    return null;
+}
+/** HttpSpan namespace for tagRequest and fromSpan. */
+exports.HttpSpan = { tagRequest, fromSpan };
+//# sourceMappingURL=http-span.js.map

package/dist/core/bindings/http-span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-span.js","sourceRoot":"","sources":["../../../src/core/bindings/http-span.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAyBH,gCAYC;AAMD,4BAqBC;AA9DD,8CAA+C;AAc/C;;;;;;;;GAQG;AACH,SAAgB,UAAU,CACxB,MAAc,EACd,GAAW,EACX,QAAiB,EACjB,IAAe;IAEf,IAAI,CAAC,IAAI,EAAE,YAAY;QAAE,OAAO;IAChC,IAAI,CAAC,YAAY,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,YAAY,CAAC,sBAAsB,EAAE,IAAA,2BAAc,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACvE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,YAAY,CAAC,wBAAwB,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,QAAQ,CAAC,IAAkB;IACzC,MAAM,QAAQ,GAAG,IAAI,EAAE,UAAU,EAAE,CAAC,oBAAoB,CAAC,CAAC;IAC1D,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,EAAE,CAAC,sBAAsB,CAAC,CAAC;QAC9D,IAAI,OAAO,UAAU,KAAK,QAAQ;YAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9E,CAAC;IAED,kEAAkE;IAClE,MAAM,KAAK,GAAG,IAAI,EAAE,UAAU,IAAI,EAAE,CAAC;IACrC,MAAM,SAAS,GACb,KAAK,CAAC,qBAAqB,CAAC;QAC5B,KAAK,CAAC,aAAa,CAAC;QACpB,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACxC,MAAM,MAAM,GACV,KAAK,CAAC,UAAU,CAAC;QACjB,KAAK,CAAC,UAAU,CAAC;QACjB,KAAK,CAAC,aAAa,CAAC,CAAC;IACvB,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,IAAA,2BAAc,EAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sDAAsD;AACzC,QAAA,QAAQ,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC"}

package/dist/core/bindings/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared span helper contracts and adapters.
+ */
+export { HttpSpan, tagRequest as tagHttpRequest, fromSpan as parseHttpSpan } from './http-span';
+export type { HttpSpanData } from './http-span';
+export { PostgresSpan, tagQuery as tagPostgresQuery, fromSpan as parsePostgresSpan } from './postgres-span';
+export type { PostgresSpanData } from './postgres-span';
+export { RedisSpan, tagCommand as tagRedisCommand, fromSpan as parseRedisSpan } from './redis-span';
+export type { RedisSpanData } from './redis-span';
+export { testSpan } from './test-span';
+export type { TestSpan } from './test-span';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/bindings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/bindings/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,UAAU,IAAI,cAAc,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,aAAa,CAAC;AAChG,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,QAAQ,IAAI,gBAAgB,EAAE,QAAQ,IAAI,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC5G,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,UAAU,IAAI,eAAe,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,cAAc,CAAC;AACpG,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}