@servicetitan/journey 2.0.0 → 3.0.0

package/src/core/sanitize.ts

@@ -0,0 +1,177 @@
+import { isUnsafeKey, MAX_ATTRIBUTE_KEYS, MAX_TAG_KEYS, MAX_TAG_VALUE_LEN } from './limits';
+import type { JourneyEvent, JourneyStepEvent, TagValue } from './types';
+
+const SANITIZED_EVENT = Symbol.for('st.journey.sanitized');
+
+/** Match Datadog metric-tag value rules so RUM attributes / globals join derived SLO tags. */
+export function normalizeTagValue(value: string): string {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9_\-:./]/g, '_')
+        .replace(/_+/g, '_')
+        .slice(0, MAX_TAG_VALUE_LEN)
+        .replace(/_+$/, '');
+}
+
+export function emptyRecord(): Record<string, TagValue> {
+    return Object.create(null) as Record<string, TagValue>;
+}
+
+function asTagValue(value: unknown): TagValue | undefined {
+    if (typeof value === 'string') {
+        return normalizeTagValue(value);
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    return undefined;
+}
+
+export interface CopyRecordOptions {
+    maxKeys: number;
+    /** When true, keys are run through {@link normalizeTagValue} (sink / wire). */
+    normalizeKeys?: boolean;
+    /** When true (default), string values are normalized. */
+    normalizeStringValues?: boolean;
+}
+
+/**
+ * Own-key copy onto a null-prototype object. Skips unsafe keys and excess keys.
+ */
+export function copyRecord(
+    src: Record<string, unknown> | undefined,
+    options: CopyRecordOptions
+): Record<string, TagValue> {
+    const out = emptyRecord();
+    if (src == null || typeof src !== 'object') {
+        return out;
+    }
+    const normalizeKeys = options.normalizeKeys === true;
+    const normalizeStringValues = options.normalizeStringValues !== false;
+    for (const key of Object.keys(src)) {
+        if (isUnsafeKey(key)) {
+            continue;
+        }
+        const destKey = normalizeKeys ? normalizeTagValue(key) : key;
+        if (!destKey || isUnsafeKey(destKey)) {
+            continue;
+        }
+        const raw = src[key];
+        const value = normalizeStringValues
+            ? asTagValue(raw)
+            : typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean'
+              ? raw
+              : undefined;
+        if (value === undefined) {
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(out, destKey)) {
+            out[destKey] = value;
+            continue;
+        }
+        if (Object.keys(out).length >= options.maxKeys) {
+            continue;
+        }
+        out[destKey] = value;
+    }
+    return out;
+}
+
+/** Merge `src` into `target` (null-prototype), honouring caps and unsafe-key skips. */
+export function assignRecord(
+    target: Record<string, TagValue>,
+    src: Record<string, unknown> | undefined,
+    maxKeys: number
+): void {
+    if (src == null || typeof src !== 'object') {
+        return;
+    }
+    let room = maxKeys - Object.keys(target).length;
+    for (const key of Object.keys(src)) {
+        if (isUnsafeKey(key)) {
+            continue;
+        }
+        const raw = src[key];
+        if (typeof raw !== 'string' && typeof raw !== 'number' && typeof raw !== 'boolean') {
+            continue;
+        }
+        const exists = Object.prototype.hasOwnProperty.call(target, key);
+        if (!exists && room <= 0) {
+            continue;
+        }
+        if (!exists) {
+            room -= 1;
+        }
+        target[key] = raw;
+    }
+}
+
+export function setSafeAttribute(
+    attributes: Record<string, TagValue>,
+    key: string,
+    value: string | number | boolean
+): void {
+    if (isUnsafeKey(key)) {
+        return;
+    }
+    const exists = Object.prototype.hasOwnProperty.call(attributes, key);
+    if (!exists && Object.keys(attributes).length >= MAX_ATTRIBUTE_KEYS) {
+        return;
+    }
+    const next = asTagValue(value);
+    if (next !== undefined) {
+        attributes[key] = next;
+    }
+}
+
+function sanitizeStep(step: JourneyStepEvent): JourneyStepEvent {
+    const name = normalizeTagValue(step.name);
+    return {
+        ...step,
+        name: name || step.name,
+        ...(step.reason ? { reason: normalizeTagValue(step.reason) } : {}),
+        ...(step.attributes
+            ? {
+                  attributes: copyRecord(step.attributes, {
+                      maxKeys: MAX_ATTRIBUTE_KEYS,
+                      normalizeKeys: true,
+                  }),
+              }
+            : {}),
+    };
+}
+
+/** Default-sink payload: normalized keys/names, capped maps, no unsafe keys. */
+export function sanitizeJourneyEvent(event: JourneyEvent): JourneyEvent {
+    const j = event.journey;
+    const expected = j.expected?.map(name => normalizeTagValue(name)).filter(name => name !== '');
+    const tags = j.tags
+        ? copyRecord(j.tags, { maxKeys: MAX_TAG_KEYS, normalizeKeys: true })
+        : undefined;
+    const tagKeys = tags ? Object.keys(tags) : [];
+    const sanitized: JourneyEvent = {
+        journey: {
+            name: normalizeTagValue(j.name),
+            team: normalizeTagValue(j.team),
+            group: normalizeTagValue(j.group),
+            service: normalizeTagValue(j.service),
+            outcome: j.outcome,
+            ...(j.reason ? { reason: normalizeTagValue(j.reason) } : {}),
+            durationMs: j.durationMs,
+            steps: j.steps.map(sanitizeStep),
+            ...(expected?.length ? { expected } : {}),
+            ...(tagKeys.length ? { tags } : {}),
+        },
+    };
+    Object.defineProperty(sanitized, SANITIZED_EVENT, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+    });
+    return sanitized;
+}
+
+/** True when payload already passed through sanitizeJourneyEvent. */
+export function isSanitizedJourneyEvent(event: JourneyEvent): boolean {
+    return (event as unknown as Record<PropertyKey, unknown>)[SANITIZED_EVENT] === true;
+}

package/src/core/step-tag.ts

@@ -1,24 +1,103 @@
-import type { JourneyStepRef, StepRecord } from './types';
+import type { JourneyHttpScore, JourneyStampOptions } from './request-policy';
+import type { StepRecord } from './types';
+
+/** Cross-realm brand so duplicate package copies can unwrap stamps safely. */
+export const JOURNEY_STEP_STAMP_BRAND = Symbol.for('st.journey.stamp');
 
 /**
- * Non-plain wrapper for {@link StepHandle.tag}.
+ * Non-plain wrapper for {@link StepHandle.stamp}.
  *
  * jQuery `ajaxSetup` / axios `mergeConfig` deep-merge plain objects. A raw
  * {@link StepRecord} is circular (`step.journey.steps → step`), so putting it
  * on ajax/axios options causes "Maximum call stack size exceeded". Class
  * instances are assigned by reference instead of recursed.
  */
-export class JourneyStepTag {
-    constructor(readonly step: StepRecord) {}
+export class JourneyStepStamp {
+    readonly [JOURNEY_STEP_STAMP_BRAND] = true as const;
+    /** Present only on explicit `step.stamp(score)` — never on auto-attribute. */
+    readonly score?: JourneyHttpScore;
+    /** Present only on explicit `step.stamp({ ignore: true })` — never on auto-attribute. */
+    readonly ignore?: boolean;
+
+    /**
+     * @internal Engine record — adapters unwrap via `resolveStamp` /
+     * `onHttpComplete`. Not part of the supported public surface.
+     */
+    readonly step: StepRecord;
+
+    constructor(step: StepRecord, opts?: JourneyStampOptions) {
+        this.step = step;
+        this.score = opts?.score;
+        this.ignore = opts?.ignore;
+    }
+
+    /**
+     * Circular by design (`step.journey.steps → step`) for mergeConfig/deep-merge
+     * safety. Prevent accidental `JSON.stringify` (e.g. AxiosError.toJSON() includes
+     * config by reference) elsewhere in the app from throwing "circular structure".
+     */
+    toJSON(): string {
+        return '[JourneyStepStamp]';
+    }
+}
+
+function isStepRecord(value: object): value is StepRecord {
+    const record = value as StepRecord;
+    return (
+        typeof record.name === 'string' &&
+        record.journey != null &&
+        typeof record.journey === 'object' &&
+        typeof (record.journey as { name?: unknown }).name === 'string'
+    );
+}
+
+/**
+ * Same-realm stamp, or a branded foreign copy with score/ignore copied.
+ * Does not fall back to ambient. Raw StepRecords are not stamps.
+ */
+export function adoptJourneyStepStamp(value: unknown): JourneyStepStamp | undefined {
+    if (value == null || typeof value !== 'object') {
+        return undefined;
+    }
+    if (value instanceof JourneyStepStamp) {
+        return value;
+    }
+    const branded = value as {
+        [JOURNEY_STEP_STAMP_BRAND]?: unknown;
+        step?: unknown;
+        score?: unknown;
+        ignore?: unknown;
+    };
+    if (branded[JOURNEY_STEP_STAMP_BRAND] !== true || branded.step == null) {
+        return undefined;
+    }
+    if (typeof branded.step !== 'object' || !isStepRecord(branded.step)) {
+        return undefined;
+    }
+    const opts: JourneyStampOptions = {};
+    if (typeof branded.score === 'function') {
+        opts.score = branded.score as JourneyHttpScore;
+    }
+    if (branded.ignore === true) {
+        opts.ignore = true;
+    }
+    return new JourneyStepStamp(branded.step, opts);
+}
+
+/** @internal Unwrap a stamp to the engine record. */
+export function resolveJourneyStep(value: unknown): StepRecord | undefined {
+    return adoptJourneyStepStamp(value)?.step;
 }
 
-/** Unwrap `step.tag().journeyStep` or a JourneyStepTag / StepRecord stamp. */
-export function resolveJourneyStep(value: unknown): JourneyStepRef | undefined {
-    if (value instanceof JourneyStepTag) {
-        return value.step;
+/** Normalize `step.stamp(fn)` / `step.stamp({ score, ignore })`. */
+export function resolveStampOpts(
+    scoreOrOpts?: JourneyHttpScore | JourneyStampOptions
+): JourneyStampOptions | undefined {
+    if (scoreOrOpts == null) {
+        return undefined;
     }
-    if (value && typeof value === 'object') {
-        return value as JourneyStepRef;
+    if (typeof scoreOrOpts === 'function') {
+        return { score: scoreOrOpts };
     }
-    return undefined;
+    return scoreOrOpts;
 }

package/src/core/types.ts

@@ -1,11 +1,17 @@
-import type { EndpointPolicy } from '../endpoint-policy';
+import type { EndpointPolicy } from './endpoint-policy';
+import type { JourneyHttpScore, JourneyStampOptions, RequestPolicyConfig } from './request-policy';
+import type { JourneyStepStamp } from './step-tag';
 
 /** Arbitrary tag values a developer can attach. */
 export type TagValue = string | number | boolean;
 
 /** Config for one journey — supplied by the caller (typically `<JourneyScope>` props). */
 export interface JourneyDef {
-    /** Journey name — lifecycle key, event field, and concurrency map key. */
+    /**
+     * Journey name — lifecycle key, event field, and concurrency map key.
+     * Must be unique among concurrently open journeys on the same runtime
+     * (a second start with the same name restarts / excludes the previous).
+     */
     name: string;
     /** Owner team (required tag). */
     team: string;
@@ -13,16 +19,23 @@ export interface JourneyDef {
     group: string;
     /** Business component label, e.g. "checkout" — not the Datadog RUM service. */
     service: string;
-    /** Whole-journey budget in ms; omit / 0 to disable. */
+    /**
+     * Whole-journey timeout in ms.
+     * - Omit to use the runtime idle timeout default (15m unless overridden)
+     * - Set `0` to disable the journey countdown
+     * - Set `N > 0` to enforce an explicit SLO budget
+     */
     timeoutMs?: number;
     /** Default per-step timeout in ms; per-call option overrides. Omit / 0 to disable. */
     stepTimeoutMs?: number;
-    /** Slow-request threshold for this journey; falls back to app-wide default. */
-    requestTimeoutMs?: number;
+    /** Slow-request threshold for this journey; omit to fall through. `0` disables latency scoring. */
+    slowRequestMs?: number;
     /** Per-endpoint overrides for this journey (longest prefix wins over app-wide). */
     endpoints?: readonly EndpointPolicy[];
-    /** Optional expected step names (rides as `expected` on the event). */
-    steps?: readonly string[];
+    /** Optional expected happy-path step names (copied onto the event as `expected`). */
+    expected?: readonly string[];
+    /** Cap recorded steps for this journey; falls back to the runtime default (50). */
+    maxSteps?: number;
     /** Custom tags on every event of this journey. */
     tags?: Record<string, TagValue>;
 }
@@ -32,27 +45,31 @@ export type Outcome = 'good' | 'bad' | 'excluded';
 /** Handle passed to each step function. */
 export interface StepHandle {
     /** Resolved journey name for this step, or null if untraced. */
-    readonly name: string | null;
+    readonly journeyName: string | null;
     setAttribute(key: string, value: string | number | boolean): void;
     /** Journey-level tags without closing. */
     setTags(tags: Record<string, TagValue>): void;
-    /** Apply optional tags then completeJourney. No-op if name is null. */
-    complete(tags?: Record<string, TagValue>): void;
-    /** Soft business Bad without throw. No-op if name is null. */
-    fail(reason: string): void;
+    /** Apply optional tags then complete the whole journey. No-op if journeyName is null. */
+    completeJourney(tags?: Record<string, TagValue>): void;
+    /** Soft business Bad without throw. Closes the whole journey. No-op if journeyName is null. */
+    failJourney(reason: string): void;
     /**
-     * Bind this step to a request explicitly (spread into axios config / fetch init /
-     * jQuery ajax settings). Needed when requests fire after an await or while steps
-     * overlap — see docs soft ambient. Untraced (noop) steps omit `journeyStep`.
+     * Bind this step to a request explicitly. Pass as `{ stamp: step.stamp() }` on
+     * axios config / fetch init / jQuery ajax settings. Needed when requests fire
+     * after an await, while steps overlap, or when `autoAttributeRequests` is false.
+     * Untraced (noop) steps return `undefined`.
+     *
+     * Pass `score` (or `{ score, ignore }`) to score or skip this stamped request.
+     * Auto-attributed requests never run a score function and never set ignore.
      *
-     * The value is a non-plain {@link JourneyStepTag} so jQuery/axios deep-merge will
+     * The value is a non-plain {@link JourneyStepStamp} so jQuery/axios deep-merge will
      * not recurse into the circular StepRecord graph.
      */
-    tag(): { journeyStep?: unknown };
+    stamp(scoreOrOpts?: JourneyHttpScore | JourneyStampOptions): JourneyStepStamp | undefined;
 }
 
-/** A journey name, or anything with a `name` (e.g. a JourneyHandle / JourneyDef). */
-export type JourneyNameLike = string | { readonly name: string };
+/** A journey name, a config object, or a handle (`handle.config.name`). */
+export type JourneyNameLike = string | { readonly name: string } | { readonly config: JourneyDef };
 
 /** First argument to journeyStep / journeyMountStep. */
 export type JourneyStepTarget = JourneyNameLike | null | readonly JourneyNameLike[];
@@ -63,6 +80,32 @@ export interface JourneyStepOptions {
     timeoutMs?: number;
 }
 
+/**
+ * @internal Cross-bundle key for the engine that created a {@link JourneyState}.
+ * Host adapters read this off an MFE `step.stamp()` so abort/4xx/5xx close the owning copy.
+ */
+export const JOURNEY_ENGINE = Symbol.for('st.journey.engine');
+
+/**
+ * @internal Bound fail/exclude/report hooks for a journey's creating engine.
+ * Name lookup on another package copy cannot see this journey.
+ */
+export interface JourneyEngine {
+    /** Close this journey as bad on the creating engine — not a by-name lookup. */
+    failJourney(reason: string): void;
+    exclude(): void;
+    shouldIgnoreRequest(key: string): boolean;
+    reportBackendRequest(
+        step: StepRecord,
+        status: number | undefined,
+        durationMs: number,
+        requestKey: string
+    ): void;
+    getHttpAbortedRequestsPolicy(): RequestPolicyConfig;
+    getHttpClientErrorRequestsPolicy(): RequestPolicyConfig;
+}
+
+/** @internal Engine open-journey record — not part of the supported public API. */
 export interface JourneyState {
     name: string;
     team: string;
@@ -71,6 +114,8 @@ export interface JourneyState {
     verdict: Outcome;
     startedAt: number;
     timeoutMs: number;
+    /** True when JourneyDef.timeoutMs was explicitly provided by caller. */
+    timeoutExplicit: boolean;
     stepTimeoutMs?: number;
     /**
      * Why the journey closed as bad, else null.
@@ -81,12 +126,17 @@ export interface JourneyState {
     steps: StepRecord[];
     expected: string[] | null;
     tags: Record<string, TagValue>;
-    requestTimeoutMs?: number;
+    slowRequestMs?: number;
     endpoints?: readonly EndpointPolicy[];
     timer: ReturnType<typeof setTimeout> | null;
     closed: boolean;
+    maxSteps?: number;
+    /** Frozen snapshot taken at start — not the caller's original object. */
+    config: JourneyDef;
+    [JOURNEY_ENGINE]?: JourneyEngine;
 }
 
+/** @internal Engine in-flight / completed step record — not part of the supported public API. */
 export interface StepRecord {
     name: string;
     startedAt: number;
@@ -96,11 +146,12 @@ export interface StepRecord {
     httpStatus?: number;
     attributes: Record<string, string | number | boolean>;
     journey: JourneyState;
+    /** True after onHttpComplete handled an abort for this step (including ignore). */
+    onHttpAborted?: boolean;
+    /** @internal Request keys attributed while this step was in flight (debug). */
+    attributedRequestKeys?: string[];
 }
 
-/** Opaque handle to a step, captured at request initiation for response attribution. */
-export type JourneyStepRef = StepRecord;
-
 export interface JourneyStepEvent {
     name: string;
     /** Offset from the journey start, ms. */
@@ -131,9 +182,14 @@ export interface JourneyEvent {
 /** Destination for a terminal journey event. */
 export type JourneySink = (event: JourneyEvent) => void;
 
-/** Callable journey — config plus lifecycle helpers bound to `name`. Prefer this over free helpers. */
-export interface JourneyHandle extends JourneyDef {
-    /** Open this journey (restarts if already open). */
+/** Callable journey — `config` plus lifecycle helpers. Prefer this over free helpers. */
+export interface JourneyHandle {
+    /** Same config object passed to `defineJourney` / used to start. */
+    readonly config: JourneyDef;
+    /**
+     * Always opens a new instance. If this name is already open, the previous
+     * instance is finished (Bad if it had breached, else Excluded).
+     */
     start(tags?: Record<string, TagValue>): void;
     /**
      * Record a step. Opens the journey first when it isn't already open