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

package/dist/AvoNetworkCallsHandler.js

@@ -4,103 +4,242 @@ exports.AvoNetworkCallsHandler = void 0;
 const AvoGuid_1 = require("./AvoGuid");
 const AvoInspector_1 = require("./AvoInspector");
 const AvoEncryption_1 = require("./AvoEncryption");
+const AvoLog_1 = require("./AvoLog");
+const AvoInspectorVersion_1 = require("./AvoInspectorVersion");
+const utils_1 = require("./utils");
 const https_1 = require("https");
+const http_1 = require("http");
+const zlib_1 = require("zlib");
 class AvoNetworkCallsHandler {
     constructor(apiKey, envName, appName, appVersion, libVersion, publicEncryptionKey) {
         this.samplingRate = 1.0;
+        this.inFlightRequests = new Set();
+        this.aborted = false;
         this.apiKey = apiKey;
         this.envName = envName;
         this.appName = appName;
         this.appVersion = appVersion;
         this.libVersion = libVersion;
         this.publicEncryptionKey = publicEncryptionKey;
+        this.mockEndpoint = AvoNetworkCallsHandler.mockEndpointFor(envName);
     }
+    /**
+     * The test-only endpoint override. Fail-closed: a prod instance never honors it,
+     * whatever the surrounding process environment says. A value that is not an http(s)
+     * URL is ignored (with a one-time warning), so callers only ever see a valid URL.
+     */
+    static mockEndpointFor(envName) {
+        if (envName === "prod") {
+            return null;
+        }
+        const override = process.env[AvoNetworkCallsHandler.mockEndpointEnvVar];
+        if (!override) {
+            return null;
+        }
+        // The warnings name the reason only, never the value: it may carry credentials or tokens.
+        // The value is used solely as the key that keeps each warning to one per value.
+        let url;
+        try {
+            url = new URL(override);
+        }
+        catch (e) {
+            AvoNetworkCallsHandler.warnOnce("invalid:" + override, "[Avo Inspector] Ignoring invalid AVO_INSPECTOR_MOCK_ENDPOINT: not a valid URL");
+            return null;
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            AvoNetworkCallsHandler.warnOnce("invalid:" + override, "[Avo Inspector] Ignoring invalid AVO_INSPECTOR_MOCK_ENDPOINT: unsupported protocol " + url.protocol);
+            return null;
+        }
+        return override;
+    }
+    // Printed on the first send redirected to the override.
+    static warnRedirect(url) {
+        // Scheme, host and port only: the path or query may carry sensitive values.
+        AvoNetworkCallsHandler.warnOnce("redirect", "[Avo Inspector] AVO_INSPECTOR_MOCK_ENDPOINT is set: sending to " + url.protocol + "//" +
+            url.host + " instead of api.avo.app (ignored in prod).");
+    }
+    static warnOnce(key, message) {
+        if (AvoNetworkCallsHandler.warnedMockEndpoint === null) {
+            AvoNetworkCallsHandler.warnedMockEndpoint = new Set();
+        }
+        if (!AvoNetworkCallsHandler.warnedMockEndpoint.has(key)) {
+            AvoNetworkCallsHandler.warnedMockEndpoint.add(key);
+            console.warn(message);
+        }
+    }
+    /** The sampling rate last returned by the Inspector API (1 until a response sets it). */
+    getSamplingRate() {
+        return this.samplingRate;
+    }
+    /** @internal Test-only hook used by the conformance harness. */
+    _setSamplingRateForTesting(samplingRate) {
+        this.samplingRate = samplingRate;
+    }
+    /** Aborts every request still in flight (used by AvoInspector.destroy). */
+    abortInFlight() {
+        // Also stops sends still being compressed from starting a request afterwards.
+        this.aborted = true;
+        const requests = Array.from(this.inFlightRequests);
+        this.inFlightRequests.clear();
+        requests.forEach((req) => req.destroy());
+    }
+    /**
+     * POSTs one batch. Resolves with the HTTP status code (the batch is never retried);
+     * rejects with "Request failed" / "Request timed out" on transport failures, or when
+     * a header value cannot be transmitted safely.
+     */
     callInspectorWithBatchBody(inEvents) {
         const events = inEvents.filter((x) => x != null);
         if (events.length === 0) {
             return Promise.resolve();
         }
-        if (Math.random() > this.samplingRate) {
-            if (AvoInspector_1.AvoInspector.shouldLog) {
-                console.log("Avo Inspector: last event schema dropped due to sampling rate.");
-            }
-            return Promise.resolve();
-        }
         if (AvoInspector_1.AvoInspector.shouldLog) {
             events.forEach(function (event) {
-                const eventProps = event.eventProperties
-                    .map(p => '\t"' + p.propertyName + '": "' + p.propertyType + '"')
-                    .join(";\n");
                 const validated = event.eventSpecMetadata ? " (validated)" : "";
                 console.log("Avo Inspector: Sending event " +
                     event.eventName + validated +
-                    " with schema {\n" + eventProps + "\n}");
+                    " with schema " + (0, utils_1.formatSchema)(event.eventProperties));
             });
         }
+        const json = Buffer.from(JSON.stringify(events), "utf8");
+        // Compressed off the event loop; on a compression error the body is sent as-is.
+        const body = json.length >= AvoNetworkCallsHandler.gzipThresholdBytes
+            ? AvoNetworkCallsHandler.gzipAsync(json).then((data) => ({ data, compressed: true }), () => ({ data: json, compressed: false }))
+            : Promise.resolve({ data: json, compressed: false });
+        return body.then(({ data, compressed }) => this.post(data, compressed));
+    }
+    static gzipAsync(input) {
         return new Promise((resolve, reject) => {
-            const data = JSON.stringify(events);
-            const options = {
-                hostname: "api.avo.app",
-                port: 443,
-                path: AvoNetworkCallsHandler.trackingEndpoint,
-                method: "POST",
-                headers: {
-                    "Accept": "application/json",
-                    "Content-Type": "application/json",
-                    "Content-Length": Buffer.byteLength(data),
-                },
+            (0, zlib_1.gzip)(input, (err, output) => (err ? reject(err) : resolve(output)));
+        });
+    }
+    post(data, compressed) {
+        return new Promise((resolve, reject) => {
+            if (this.aborted) {
+                reject("Request failed");
+                return;
+            }
+            const headers = {
+                "api-key": this.apiKey,
+                "env": this.envName,
+                "X-Avo-Client": AvoInspectorVersion_1.LIB_PLATFORM,
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Content-Length": data.length,
             };
+            if (compressed) {
+                headers["Content-Encoding"] = "gzip";
+            }
+            for (const name of Object.keys(headers)) {
+                const value = headers[name];
+                if (typeof value === "string" && ((0, utils_1.hasHeaderControlChar)(value) || (0, utils_1.hasNonLatin1Char)(value))) {
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.error("Avo Inspector: [network] Header " + name +
+                            " contains a character that cannot be sent in a header. Batch dropped.");
+                    }
+                    reject("Request failed");
+                    return;
+                }
+            }
+            const url = new URL(this.mockEndpoint || AvoNetworkCallsHandler.trackingEndpoint);
+            if (this.mockEndpoint) {
+                AvoNetworkCallsHandler.warnRedirect(url);
+            }
+            const send = url.protocol === "http:" ? http_1.request : https_1.request;
             if (AvoInspector_1.AvoInspector.shouldLog) {
-                console.log("Avo Inspector: [network] POST https://" + options.hostname + options.path);
-                console.log("Avo Inspector: [network] Request body (" + Buffer.byteLength(data) + " bytes)");
+                // An override's path may carry a token, so only its origin is printed.
+                console.log("Avo Inspector: [network] POST " + url.origin + (this.mockEndpoint ? "" : url.pathname));
+                console.log("Avo Inspector: [network] Request body (" + data.length + " bytes" +
+                    (compressed ? ", gzip" : "") + ")");
             }
-            const req = (0, https_1.request)(options, (res) => {
-                if (AvoInspector_1.AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: [network] Response status: " + res.statusCode + " " + res.statusMessage);
+            let settled = false;
+            const finish = (fn) => {
+                if (settled) {
+                    return;
                 }
-                const chunks = [];
-                res.on("data", (data) => chunks.push(data));
-                res.on("end", () => {
-                    if (res.statusCode === 200) {
-                        try {
-                            const responseBody = Buffer.concat(chunks).toString();
-                            const data = JSON.parse(responseBody);
-                            if (typeof data.samplingRate === "number" && data.samplingRate >= 0 && data.samplingRate <= 1) {
-                                this.samplingRate = data.samplingRate;
+                settled = true;
+                clearTimeout(timer);
+                this.inFlightRequests.delete(req);
+                fn();
+            };
+            let req;
+            try {
+                req = send(url, { method: "POST", headers }, (res) => {
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.log("Avo Inspector: [network] Response status: " + res.statusCode + " " + res.statusMessage);
+                    }
+                    const chunks = [];
+                    res.on("data", (chunk) => chunks.push(chunk));
+                    res.on("end", () => {
+                        if (res.statusCode === 200) {
+                            try {
+                                const responseBody = Buffer.concat(chunks).toString();
+                                const body = JSON.parse(responseBody);
+                                if (body && typeof body.samplingRate === "number" && body.samplingRate >= 0 && body.samplingRate <= 1) {
+                                    this.samplingRate = body.samplingRate;
+                                }
                             }
+                            catch (e) {
+                                if (AvoInspector_1.AvoInspector.shouldLog) {
+                                    console.warn("Avo Inspector: [network] Failed to parse response JSON: " + e);
+                                }
+                            }
+                        }
+                        else if (AvoInspector_1.AvoInspector.shouldLog) {
+                            console.warn("Avo Inspector: [network] Non-200 response: " + res.statusCode);
                         }
-                        catch (e) {
-                            if (AvoInspector_1.AvoInspector.shouldLog) {
-                                console.warn("Avo Inspector: [network] Failed to parse response JSON: " + e);
+                        finish(() => resolve(res.statusCode));
+                    });
+                    // A response cut off mid-body emits neither "end" nor a request "error". Its status
+                    // already arrived and decides, as for an unparseable body: a 200 is delivered (the
+                    // sampling rate is unchanged), anything else a non-200.
+                    const truncated = () => {
+                        if (!res.complete) {
+                            if (AvoInspector_1.AvoInspector.shouldLog && !settled) {
+                                console.warn("Avo Inspector: [network] Response ended before its body was complete");
                             }
+                            finish(() => resolve(res.statusCode));
                         }
-                    }
-                    else if (AvoInspector_1.AvoInspector.shouldLog) {
-                        console.warn("Avo Inspector: [network] Non-200 response: " + res.statusCode);
-                    }
-                    resolve();
+                    };
+                    res.on("aborted", truncated);
+                    res.on("error", truncated);
+                    res.on("close", truncated);
                 });
-            });
-            req.write(data);
-            req.setTimeout(10000);
-            req.on("error", (err) => {
+            }
+            catch (e) {
+                // A synchronous throw (for example invalid request options) is a failed send, with
+                // the documented reason; nothing was started, so there is nothing to clean up.
                 if (AvoInspector_1.AvoInspector.shouldLog) {
-                    console.error("Avo Inspector: [network] Request error: " + err);
+                    console.error("Avo Inspector: [network] Request could not be started");
                 }
                 reject("Request failed");
-            });
-            req.on("timeout", () => {
+                return;
+            }
+            this.inFlightRequests.add(req);
+            // An in-flight send must not hold the process open: at exit the beforeExit drain
+            // keeps it alive, under one deadline, while it sends what is left.
+            req.on("socket", (socket) => socket.unref());
+            // A wall-clock budget for the whole request, not just socket idleness.
+            const timer = setTimeout(() => {
                 if (AvoInspector_1.AvoInspector.shouldLog) {
                     console.error("Avo Inspector: [network] Request timed out after 10s");
                 }
+                finish(() => reject("Request timed out"));
                 req.destroy();
-                reject("Request timed out");
+            }, AvoNetworkCallsHandler.requestTimeoutMs);
+            timer.unref();
+            req.on("error", (err) => {
+                if (AvoInspector_1.AvoInspector.shouldLog && !settled) {
+                    console.error("Avo Inspector: [network] Request error: " + err);
+                }
+                finish(() => reject("Request failed"));
             });
-            req.end();
+            req.end(data);
         });
     }
-    bodyForEventSchemaCall(anonymousId, eventName, eventProperties, eventId, eventHash, rawEventProperties) {
-        let eventSchemaBody = this.createBaseCallBody(anonymousId);
+    /** Builds the wire body for one event, encrypting property values when configured. */
+    bodyForEventSchemaCall(anonymousId, eventName, eventProperties, eventId, eventHash, rawEventProperties, gatewayFields, stamp) {
+        let eventSchemaBody = this.createBaseCallBody(anonymousId, gatewayFields, stamp);
         eventSchemaBody.type = "event";
         eventSchemaBody.eventName = eventName;
         if (AvoEncryption_1.AvoEncryption.shouldEncrypt(this.envName, this.publicEncryptionKey) && rawEventProperties) {
@@ -109,51 +248,65 @@ class AvoNetworkCallsHandler {
         else {
             eventSchemaBody.eventProperties = eventProperties;
         }
-        if (eventId != null) {
-            eventSchemaBody.avoFunction = true;
-            eventSchemaBody.eventId = eventId;
-            eventSchemaBody.eventHash = eventHash;
-        }
-        else {
-            eventSchemaBody.avoFunction = false;
-            eventSchemaBody.eventId = null;
-            eventSchemaBody.eventHash = null;
-        }
+        AvoNetworkCallsHandler.applyAvoFunctionFields(eventSchemaBody, eventId, eventHash);
         return eventSchemaBody;
     }
+    /** Returns the event properties, with values encrypted when encryption applies. */
     buildEventProperties(eventProperties, rawEventProperties) {
         if (AvoEncryption_1.AvoEncryption.shouldEncrypt(this.envName, this.publicEncryptionKey) && rawEventProperties) {
             return this.encryptProperties(eventProperties, rawEventProperties);
         }
         return eventProperties;
     }
-    bodyForValidatedEventSchemaCall(anonymousId, eventName, eventProperties, eventId, eventHash, eventSpecMetadata, propertyResults) {
-        // Build a map of validation results by property name
+    /** Builds the wire body for one event, including its event-spec validation results. */
+    bodyForValidatedEventSchemaCall(anonymousId, eventName, eventProperties, eventId, eventHash, eventSpecMetadata, propertyResults, gatewayFields, stamp) {
         const validationMap = new Map();
         for (const result of propertyResults) {
             validationMap.set(result.propertyName, result);
         }
         // Merge validation results into eventProperties (matching Android)
-        const mergedProperties = eventProperties.map((prop) => {
-            const validation = validationMap.get(prop.propertyName);
-            if (validation) {
-                const merged = Object.assign({}, prop);
-                if (validation.failedEventIds.length > 0) {
-                    merged.failedEventIds = validation.failedEventIds;
-                }
-                if (validation.passedEventIds.length > 0) {
-                    merged.passedEventIds = validation.passedEventIds;
-                }
-                return merged;
-            }
-            return prop;
-        });
-        let body = this.createBaseCallBody(anonymousId);
+        const mergedProperties = eventProperties.map((prop) => AvoNetworkCallsHandler.withValidation(prop, validationMap.get(prop.propertyName)));
+        let body = this.createBaseCallBody(anonymousId, gatewayFields, stamp);
         body.type = "event";
         body.eventName = eventName;
         body.eventProperties = mergedProperties;
-        body.streamId = anonymousId;
         body.eventSpecMetadata = eventSpecMetadata;
+        AvoNetworkCallsHandler.applyAvoFunctionFields(body, eventId, eventHash);
+        return body;
+    }
+    /**
+     * A property with its failed event IDs, and those of its object properties merged into its
+     * children. A list's children are its element schemas; each object element gets the
+     * results of the properties it has (a list of objects is validated across all its items).
+     */
+    static withValidation(prop, outcome) {
+        if (outcome === undefined) {
+            return prop;
+        }
+        const merged = Object.assign({}, prop);
+        if (outcome.failedEventIds.length > 0) {
+            merged.failedEventIds = outcome.failedEventIds;
+        }
+        const childOutcomes = outcome.children;
+        if (childOutcomes !== undefined && Array.isArray(prop.children)) {
+            const mergeChild = (child) => {
+                if (Array.isArray(child)) {
+                    return child.map(mergeChild);
+                }
+                if (child !== null && typeof child === "object" && typeof child.propertyName === "string") {
+                    const childOutcome = Object.prototype.hasOwnProperty.call(childOutcomes, child.propertyName)
+                        ? childOutcomes[child.propertyName]
+                        : undefined;
+                    return AvoNetworkCallsHandler.withValidation(child, childOutcome);
+                }
+                return child;
+            };
+            merged.children = prop.children.map(mergeChild);
+        }
+        return merged;
+    }
+    // An event with an eventId came from an Avo function (Codegen): it carries the id and hash.
+    static applyAvoFunctionFields(body, eventId, eventHash) {
         if (eventId != null) {
             body.avoFunction = true;
             body.eventId = eventId;
@@ -164,7 +317,6 @@ class AvoNetworkCallsHandler {
             body.eventId = null;
             body.eventHash = null;
         }
-        return body;
     }
     encryptProperties(properties, rawEventProperties) {
         var _a;
@@ -175,7 +327,16 @@ class AvoNetworkCallsHandler {
                 continue;
             }
             const rawValue = rawEventProperties[prop.propertyName];
-            const jsonValue = (_a = JSON.stringify(rawValue)) !== null && _a !== void 0 ? _a : "null";
+            let jsonValue;
+            try {
+                jsonValue = (_a = JSON.stringify(rawValue)) !== null && _a !== void 0 ? _a : "null";
+            }
+            catch (e) {
+                // A value that cannot be serialized (e.g. cyclic) is omitted, like an encryption failure.
+                // Only the error's type is printed: toJSON, getters and proxies can put the value in it.
+                console.warn(`[Avo Inspector] Warning: could not serialize property "${prop.propertyName}" for encryption, omitting it. (${AvoLog_1.AvoLog.errorType(e)})`);
+                continue;
+            }
             const encrypted = AvoEncryption_1.AvoEncryption.encryptValue(jsonValue, this.publicEncryptionKey);
             if (encrypted === null) {
                 // Encryption failure: omit the property (warning already logged by encryptValue)
@@ -185,21 +346,28 @@ class AvoNetworkCallsHandler {
         }
         return result;
     }
-    createBaseCallBody(anonymousId) {
+    // `stamp` defaults to now and the current sampling rate.
+    createBaseCallBody(anonymousId, gatewayFields, stamp) {
         const body = {
             apiKey: this.apiKey,
             appName: this.appName,
-            appVersion: this.appVersion,
+            appVersion: gatewayFields ? gatewayFields.appVersion : this.appVersion,
             libVersion: this.libVersion,
             env: this.envName,
-            libPlatform: "node",
+            libPlatform: AvoInspectorVersion_1.LIB_PLATFORM,
             messageId: AvoGuid_1.AvoGuid.newGuid(),
-            trackingId: "",
-            sessionId: "",
+            streamId: anonymousId,
             anonymousId: anonymousId,
-            createdAt: new Date().toISOString(),
-            samplingRate: this.samplingRate,
+            createdAt: stamp ? stamp.createdAt : new Date().toISOString(),
+            samplingRate: stamp ? stamp.samplingRate : this.samplingRate,
         };
+        // Gateway coordinates are sent only when present; never as null or "".
+        if (gatewayFields && gatewayFields.outputReference !== undefined) {
+            body.outputReference = gatewayFields.outputReference;
+        }
+        if (gatewayFields && gatewayFields.originHint !== undefined) {
+            body.originHint = gatewayFields.originHint;
+        }
         if (this.publicEncryptionKey && this.publicEncryptionKey.length > 0) {
             body.publicEncryptionKey = this.publicEncryptionKey;
         }
@@ -207,4 +375,10 @@ class AvoNetworkCallsHandler {
     }
 }
 exports.AvoNetworkCallsHandler = AvoNetworkCallsHandler;
-AvoNetworkCallsHandler.trackingEndpoint = "/inspector/v1/track";
+AvoNetworkCallsHandler.trackingEndpoint = "https://api.avo.app/inspector/v2/track";
+AvoNetworkCallsHandler.mockEndpointEnvVar = "AVO_INSPECTOR_MOCK_ENDPOINT";
+AvoNetworkCallsHandler.requestTimeoutMs = 10000;
+AvoNetworkCallsHandler.gzipThresholdBytes = 1024;
+// Warnings about the override print once per process, whatever the logging flag, on
+// stderr (console.warn).
+AvoNetworkCallsHandler.warnedMockEndpoint = null;

package/dist/AvoSchemaParser.d.ts

@@ -1,4 +1,9 @@
 export declare class AvoSchemaParser {
+    /**
+     * Maps each property to its name, type and (for objects and lists) child schema.
+     * Values nested deeper than MAX_DEPTH, cyclic references, and complex values past the
+     * MAX_EXPANSIONS budget are reported as "object".
+     */
     static extractSchema(eventProperties: {
         [propName: string]: any;
     }): Array<{
@@ -7,6 +12,7 @@ export declare class AvoSchemaParser {
         children?: any;
     }>;
     private static removeDuplicates;
+    private static childKey;
     private static getBasicPropType;
     private static getPropValueType;
 }