node-avo-inspector 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/eventSpec/AvoEventSpecFetcher.js

@@ -2,43 +2,181 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AvoEventSpecFetcher = void 0;
 const https_1 = require("https");
+const http_1 = require("http");
+const AvoEventSpecCache_1 = require("./AvoEventSpecCache");
 const AvoInspector_1 = require("../AvoInspector");
+const AvoLog_1 = require("../AvoLog");
+// Nesting the parser follows in a spec's children; deeper levels are left empty. Validation
+// itself stops at the second level (EventValidator), so this only bounds the parse.
+const MAX_PARSE_DEPTH = 10;
+const isWireObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+// A constraint key -> event IDs mapping; IDs that are not strings, and keys left with none,
+// are dropped. Undefined when nothing is left.
+const parseIdMapping = (wire) => {
+    if (!isWireObject(wire)) {
+        return undefined;
+    }
+    const result = Object.create(null);
+    let found = false;
+    for (const key of Object.keys(wire)) {
+        const ids = wire[key];
+        if (!Array.isArray(ids)) {
+            continue;
+        }
+        const eventIds = ids.filter((id) => typeof id === "string");
+        if (eventIds.length > 0) {
+            result[key] = eventIds;
+            found = true;
+        }
+    }
+    return found ? result : undefined;
+};
+// One keep-alive agent for every instance, so creating many instances (for example one per
+// request) cannot pile up idle TLS sockets. Idle sockets are capped and do not hold the
+// process open.
+const sharedAgent = new https_1.Agent({ keepAlive: true, maxSockets: 8, maxFreeSockets: 2 });
+// The same, for an http: mock endpoint.
+const sharedHttpAgent = new http_1.Agent({ keepAlive: true, maxSockets: 8, maxFreeSockets: 2 });
 class AvoEventSpecFetcher {
-    constructor(apiKey) {
+    /** `mockEndpoint`: a valid override URL (AvoNetworkCallsHandler.mockEndpoint), or null. */
+    constructor(apiKey, mockEndpoint = null) {
+        // Where spec requests go: api.avo.app, or the origin of the mock-endpoint override.
+        this.protocol = "https:";
+        this.hostname = "api.avo.app";
+        this.port = 443;
+        // Scheme, host and port (when not the default) for log lines: never the override's path.
+        this.origin = "https://api.avo.app";
         this.inFlight = new Map();
+        this.agent = sharedAgent;
+        this.requests = new Set();
         this.apiKey = apiKey;
-        this.agent = new https_1.Agent({ keepAlive: true });
+        if (mockEndpoint !== null) {
+            const url = new URL(mockEndpoint);
+            this.protocol = url.protocol === "http:" ? "http:" : "https:";
+            // URL keeps the brackets of an IPv6 host; request() takes the bare address.
+            this.hostname = url.hostname.replace(/^\[(.*)\]$/, "$1");
+            this.port = url.port ? Number(url.port) : this.protocol === "http:" ? 80 : 443;
+            this.origin = this.protocol + "//" + url.host;
+        }
     }
-    fetch(eventName, streamId, callback) {
-        const dedupeKey = `${this.apiKey}:${streamId}:${eventName}`;
+    /**
+     * `coordinates`: the event's gateway coordinates. Each non-blank one is sent as a query
+     * parameter and is part of the dedupe key; without any, the request and key are those of
+     * a plain source fetch.
+     */
+    fetch(eventName, streamId, callback, coordinates) {
+        var _a;
+        const dedupeKey = (_a = (0, AvoEventSpecCache_1.coordinatesKey)([this.apiKey, streamId, eventName], coordinates)) !== null && _a !== void 0 ? _a : `${this.apiKey}:${streamId}:${eventName}`;
         // In-flight dedup: if there's already a request in flight for this key,
         // queue the callback
-        const existingCallbacks = this.inFlight.get(dedupeKey);
-        if (existingCallbacks) {
-            existingCallbacks.push(callback);
+        const existing = this.inFlight.get(dedupeKey);
+        if (existing) {
+            existing.callbacks.push(callback);
             return;
         }
         // Register the callback and start the request
-        this.inFlight.set(dedupeKey, [callback]);
-        const queryParams = new URLSearchParams({
-            apiKey: this.apiKey,
-            eventName,
-            streamId,
-        });
-        const options = {
-            hostname: "api.avo.app",
-            port: 443,
-            path: `${AvoEventSpecFetcher.specEndpoint}?${queryParams.toString()}`,
-            method: "GET",
-            agent: this.agent,
-            headers: {
-                Accept: "application/json",
-            },
+        const owner = {};
+        this.inFlight.set(dedupeKey, { callbacks: [callback], owner });
+        // A request settles its key once. A late event (for example the error from a request
+        // destroyed on timeout) must not settle a newer fetch that has taken the key since.
+        // `deferCallbacks` is for settling inside fetch() itself: the key is freed and the
+        // deadline cleared at once, but callbacks still run asynchronously.
+        let settled = false;
+        let deadline;
+        const settle = (result, deferCallbacks = false, notFound = false) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(deadline);
+            this.resolveCallbacks(dedupeKey, owner, result, deferCallbacks, result === null && notFound);
         };
-        if (AvoInspector_1.AvoInspector.shouldLog) {
-            console.log("Avo Inspector: [network] GET https://" + options.hostname + AvoEventSpecFetcher.specEndpoint + "?eventName=" + encodeURIComponent(eventName));
+        // Anything that throws from here on would leave the key registered with no request
+        // behind it, and every later fetch of the key would wait on it forever.
+        let req;
+        try {
+            const queryParams = new URLSearchParams({
+                apiKey: this.apiKey,
+                eventName,
+                streamId,
+            });
+            // Appended after the source params, so a fetch without coordinates is unchanged.
+            const { originHint, outputReference } = (0, AvoEventSpecCache_1.normalizeCoordinates)(coordinates);
+            if (originHint !== undefined) {
+                queryParams.append("originHint", originHint);
+            }
+            if (outputReference !== undefined) {
+                queryParams.append("outputReference", outputReference);
+            }
+            const options = {
+                hostname: this.hostname,
+                port: this.port,
+                path: `${AvoEventSpecFetcher.specEndpoint}?${queryParams.toString()}`,
+                method: "GET",
+                agent: this.protocol === "http:" ? sharedHttpAgent : this.agent,
+                headers: {
+                    Accept: "application/json",
+                },
+            };
+            if (AvoInspector_1.AvoInspector.shouldLog) {
+                console.log("Avo Inspector: [network] GET " + this.origin + AvoEventSpecFetcher.specEndpoint + "?eventName=" + eventName);
+            }
+            const sent = this.send(options, eventName, settle);
+            req = sent;
+            this.requests.add(sent);
+            // `deadline` is first the wait for a socket, then the fetch's own budget; settling
+            // clears whichever is armed.
+            deadline = setTimeout(() => {
+                if (AvoInspector_1.AvoInspector.shouldLog) {
+                    console.error("Avo Inspector: [network] Spec fetch got no connection within " + AvoEventSpecFetcher.socketWaitTimeoutMs + "ms");
+                }
+                AvoEventSpecFetcher.timeouts++;
+                sent.destroy();
+                settle(null);
+            }, AvoEventSpecFetcher.socketWaitTimeoutMs);
+            deadline.unref();
+            // Unref'd like track sockets, so a fetch never holds the process open by itself: at
+            // exit, a pending validation is awaited by the exit drain, within its deadline. On
+            // every assignment, since the keep-alive agent re-refs a socket when it reuses it.
+            sent.on("socket", (socket) => socket.unref());
+            sent.once("socket", () => {
+                if (settled) {
+                    return;
+                }
+                clearTimeout(deadline);
+                deadline = setTimeout(() => {
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.error("Avo Inspector: [network] Spec fetch timed out after " + AvoEventSpecFetcher.fetchTimeoutMs + "ms");
+                    }
+                    AvoEventSpecFetcher.timeouts++;
+                    sent.destroy();
+                    settle(null);
+                }, AvoEventSpecFetcher.fetchTimeoutMs);
+                deadline.unref();
+            });
+            sent.on("close", () => {
+                clearTimeout(deadline);
+                this.requests.delete(sent);
+                // A request destroyed before it got a socket can close with no response and no
+                // error. settle is idempotent and owner-checked, so this is a no-op otherwise.
+                settle(null);
+            });
+            sent.end();
         }
-        const req = (0, https_1.request)(options, (res) => {
+        catch (e) {
+            if (AvoInspector_1.AvoInspector.shouldLog) {
+                console.error("Avo Inspector: [network] Spec fetch error (" + AvoLog_1.AvoLog.errorType(e) + ")");
+            }
+            if (req) {
+                req.destroy();
+            }
+            settle(null, true);
+        }
+    }
+    // Starts the GET; every outcome (response, parse failure, transport error) goes to settle.
+    send(options, eventName, settle) {
+        const send = this.protocol === "http:" ? http_1.request : https_1.request;
+        const req = send(options, (res) => {
             if (AvoInspector_1.AvoInspector.shouldLog) {
                 console.log("Avo Inspector: [network] Spec response status: " + res.statusCode + " " + res.statusMessage);
             }
@@ -51,7 +189,7 @@ class AvoEventSpecFetcher {
                         const body = Buffer.concat(chunks).toString();
                         console.warn("Avo Inspector: [network] Spec fetch failed with status " + res.statusCode + ": " + body);
                     }
-                    this.resolveCallbacks(dedupeKey, null);
+                    settle(null, false, res.statusCode === 404);
                     return;
                 }
                 try {
@@ -70,90 +208,162 @@ class AvoEventSpecFetcher {
                         console.warn("Avo Inspector: [network] Failed to parse spec response: " + e);
                     }
                 }
-                this.resolveCallbacks(dedupeKey, result);
+                settle(result);
             });
+            // A response cut off mid-body emits neither "end" nor a request "error"; without this
+            // the fetch would wait for its deadline, holding the key for every same-key fetch.
+            const truncated = () => {
+                if (!res.complete) {
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.error("Avo Inspector: [network] Spec response ended before its body was complete");
+                    }
+                    settle(null);
+                }
+            };
+            res.on("aborted", truncated);
+            res.on("error", truncated);
+            res.on("close", truncated);
         });
         req.on("error", (err) => {
             if (AvoInspector_1.AvoInspector.shouldLog) {
                 console.error("Avo Inspector: [network] Spec fetch error: " + err);
             }
-            this.resolveCallbacks(dedupeKey, null);
+            settle(null);
         });
-        req.setTimeout(10000);
-        req.on("timeout", () => {
-            if (AvoInspector_1.AvoInspector.shouldLog) {
-                console.error("Avo Inspector: [network] Spec fetch timed out after 10s");
-            }
-            req.destroy();
-            this.resolveCallbacks(dedupeKey, null);
-        });
-        req.end();
+        return req;
     }
-    resolveCallbacks(key, result) {
-        const callbacks = this.inFlight.get(key);
+    resolveCallbacks(key, owner, result, deferCallbacks = false, notFound = false) {
+        const pending = this.inFlight.get(key);
+        if (!pending || pending.owner !== owner) {
+            return;
+        }
         this.inFlight.delete(key);
-        if (callbacks) {
-            for (const cb of callbacks) {
+        const invoke = () => {
+            for (const cb of pending.callbacks) {
                 try {
-                    cb(result);
+                    cb(result, notFound);
                 }
                 catch (e) {
                     // Don't let one callback failure affect others
                 }
             }
+        };
+        if (deferCallbacks) {
+            process.nextTick(invoke);
+        }
+        else {
+            invoke();
         }
     }
     /**
      * Parse the wire format from /trackingPlan/eventSpec into our internal types.
      *
      * Wire format:
-     *   { events: [{ b, id, vids, p: { "PropName": { t: "string", r: true, v: {...}, rx: {...} } } }],
+     *   { events: [{ b, id, vids, p: { "PropName": { t, r, l?, p?, v?, rx?, minmax?, children? } } }],
      *     metadata: { schemaId, branchId, latestActionId, sourceId } }
+     *   where p, v, rx and minmax each map a constraint key to the event IDs that require it.
      *
      * Internal format:
-     *   { eventSpec: { eventName, properties: [{ propertyName, propertyType, regex? }] } | null,
+     *   { eventSpec: { eventName, events: [{ branchId, baseEventId, variantIds, props }] } | null,
      *     metadata: { schemaId, branchId, latestActionId, sourceId } }
      */
     static parseWireResponse(wire, eventName) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const metadata = {
             schemaId: (_b = (_a = wire.metadata) === null || _a === void 0 ? void 0 : _a.schemaId) !== null && _b !== void 0 ? _b : "",
             branchId: (_d = (_c = wire.metadata) === null || _c === void 0 ? void 0 : _c.branchId) !== null && _d !== void 0 ? _d : "",
             latestActionId: (_f = (_e = wire.metadata) === null || _e === void 0 ? void 0 : _e.latestActionId) !== null && _f !== void 0 ? _f : "",
             sourceId: (_h = (_g = wire.metadata) === null || _g === void 0 ? void 0 : _g.sourceId) !== null && _h !== void 0 ? _h : "",
         };
-        if (!wire.events || !Array.isArray(wire.events) || wire.events.length === 0) {
+        const events = [];
+        if (Array.isArray(wire.events)) {
+            for (const entry of wire.events) {
+                const parsed = AvoEventSpecFetcher.parseEventEntry(entry);
+                if (parsed !== null) {
+                    events.push(parsed);
+                }
+            }
+        }
+        if (events.length === 0) {
             return { eventSpec: null, metadata };
         }
-        // Use the first event entry (the endpoint returns specs for the requested event)
-        const entry = wire.events[0];
-        const properties = [];
-        if (entry.p && typeof entry.p === "object") {
-            for (const propName of Object.keys(entry.p)) {
-                const constraint = entry.p[propName];
-                const prop = {
-                    propertyName: propName,
-                    propertyType: (_j = constraint === null || constraint === void 0 ? void 0 : constraint.t) !== null && _j !== void 0 ? _j : "unknown",
-                };
-                // Extract regex pattern if present (rx field maps regex patterns to event IDs)
-                if ((constraint === null || constraint === void 0 ? void 0 : constraint.rx) && typeof constraint.rx === "object") {
-                    const patterns = Object.keys(constraint.rx);
-                    if (patterns.length > 0) {
-                        prop.regex = patterns[0];
-                    }
-                }
-                properties.push(prop);
+        return { eventSpec: { eventName, events }, metadata };
+    }
+    // An entry without a string id has no event to attribute results to, so it is skipped.
+    static parseEventEntry(entry) {
+        if (!isWireObject(entry) || typeof entry.id !== "string") {
+            return null;
+        }
+        return {
+            branchId: typeof entry.b === "string" ? entry.b : "",
+            baseEventId: entry.id,
+            variantIds: Array.isArray(entry.vids)
+                ? entry.vids.filter((id) => typeof id === "string")
+                : [],
+            props: AvoEventSpecFetcher.parseConstraintsByName(entry.p, 0),
+        };
+    }
+    // Null-prototype, so a property named "constructor" or "__proto__" is an ordinary key.
+    static parseConstraintsByName(wire, depth) {
+        const result = Object.create(null);
+        if (!isWireObject(wire) || depth >= MAX_PARSE_DEPTH) {
+            return result;
+        }
+        for (const name of Object.keys(wire)) {
+            const constraints = AvoEventSpecFetcher.parseConstraints(wire[name], depth);
+            if (constraints !== null) {
+                result[name] = constraints;
             }
         }
-        const eventSpec = {
-            eventName,
-            properties,
+        return result;
+    }
+    static parseConstraints(wire, depth) {
+        if (!isWireObject(wire)) {
+            return null;
+        }
+        const constraints = {
+            type: typeof wire.t === "string" ? wire.t : "unknown",
+            required: wire.r === true,
         };
-        return { eventSpec, metadata };
+        if (wire.l === true) {
+            constraints.isList = true;
+        }
+        const pinnedValues = parseIdMapping(wire.p);
+        if (pinnedValues) {
+            constraints.pinnedValues = pinnedValues;
+        }
+        const allowedValues = parseIdMapping(wire.v);
+        if (allowedValues) {
+            constraints.allowedValues = allowedValues;
+        }
+        const regexPatterns = parseIdMapping(wire.rx);
+        if (regexPatterns) {
+            constraints.regexPatterns = regexPatterns;
+        }
+        const minMaxRanges = parseIdMapping(wire.minmax);
+        if (minMaxRanges) {
+            constraints.minMaxRanges = minMaxRanges;
+        }
+        if (isWireObject(wire.children)) {
+            constraints.children = AvoEventSpecFetcher.parseConstraintsByName(wire.children, depth + 1);
+        }
+        return constraints;
     }
+    /** Aborts this instance's in-flight requests; the shared agent stays usable. */
     destroy() {
-        this.agent.destroy();
+        const requests = Array.from(this.requests);
+        this.requests.clear();
+        requests.forEach((req) => req.destroy());
     }
 }
 exports.AvoEventSpecFetcher = AvoEventSpecFetcher;
 AvoEventSpecFetcher.specEndpoint = "/trackingPlan/eventSpec";
+// Budget per fetch, from the moment the shared agent assigns it a socket. Counting from
+// the request instead would expire fetches queued behind 8 slow ones before they were
+// ever sent.
+AvoEventSpecFetcher.fetchTimeoutMs = 10000;
+// Budget for the wait before a socket is assigned. Without it, fetches queued behind 8
+// hung ones would wait for every earlier deadline in turn.
+AvoEventSpecFetcher.socketWaitTimeoutMs = 10000;
+/** @internal Fetches given up at a deadline, process-wide: the exit drain reads it. */
+AvoEventSpecFetcher.timeouts = 0;

package/dist/eventSpec/EventValidator.d.ts

@@ -1,15 +1,21 @@
 import { EventSpec, PropertyValidationResult } from "./AvoEventSpecFetchTypes";
-interface EventProperty {
-    propertyName: string;
-    propertyType: string;
-    propertyValue?: string;
-}
+/**
+ * Checks event property values against the value constraints of an event spec: pinned values,
+ * allowed values, regex patterns and min/max ranges, on a property and on the properties of an
+ * object (or of each object in a list).
+ *
+ * Each constraint applies to the tracking-plan event IDs (base event and variants) the spec
+ * lists for it, so a value can pass for one variant and fail for another. Types and required
+ * properties are not checked here; Avo compares the reported schema with the plan for those.
+ */
 export declare class EventValidator {
     /**
-     * Validates event properties against the spec.
-     * Returns per-property validation results with bandwidth optimization:
-     * passedEventIds is returned only when strictly smaller than failedEventIds.
+     * Returns one result per property that failed for at least one event ID, or whose object
+     * properties did. Properties the spec has no constraints for are left out.
      */
-    validate(spec: EventSpec, eventProperties: EventProperty[], eventId: string): PropertyValidationResult[];
+    validate(spec: EventSpec, eventSchema: Array<{
+        propertyName: string;
+    }>, rawEventProperties: {
+        [propName: string]: any;
+    } | undefined): PropertyValidationResult[];
 }
-export {};