td-feature-node 0.0.0-stage → 0.0.2

package/dist/report/expose-reporter.d.ts

@@ -0,0 +1,40 @@
+import type { ExposureAdapter, ExposureProperties, ResolvedClientOptions } from '../types';
+import { Feature } from '../feature';
+/** One asynchronous worker, a bounded FIFO, and one pending flush control slot. */
+export declare class ExposeReporter {
+    private readonly adapter;
+    private readonly ownsAdapter;
+    private readonly config;
+    private readonly dedup;
+    private head;
+    private tail;
+    private queueSize;
+    private active;
+    private scheduled;
+    private remainingInTurn;
+    private barrier;
+    private activeBarrier;
+    private sequence;
+    private completed;
+    private closing;
+    private stopped;
+    private finalizing;
+    private adapterClosed;
+    private closePromise;
+    private closeTimer;
+    private closeDeadline;
+    private finishClose;
+    constructor(adapter: ExposureAdapter, ownsAdapter: boolean, config: Readonly<ResolvedClientOptions>);
+    report(feature: Feature | null | undefined, custom?: ExposureProperties | null): boolean;
+    private schedule;
+    private pump;
+    private unmarkTask;
+    private completeTask;
+    flush(): Promise<void>;
+    private settleBarrier;
+    private completeBarrier;
+    close(): Promise<void>;
+    private closeAdapter;
+    private finalize;
+    private stop;
+}

package/dist/report/expose-reporter.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExposeReporter = void 0;
+const errors_1 = require("../errors");
+const exposure_dedup_1 = require("./exposure-dedup");
+const event_1 = require("./event");
+const request_operation_1 = require("../core/request-operation");
+/** One asynchronous worker, a bounded FIFO, and one pending flush control slot. */
+class ExposeReporter {
+    constructor(adapter, ownsAdapter, config) {
+        this.adapter = adapter;
+        this.ownsAdapter = ownsAdapter;
+        this.config = config;
+        this.head = null;
+        this.tail = null;
+        this.queueSize = 0;
+        this.active = null;
+        this.remainingInTurn = 0;
+        this.barrier = null;
+        this.activeBarrier = null;
+        this.sequence = 0;
+        this.completed = 0;
+        this.closing = false;
+        this.stopped = false;
+        this.finalizing = false;
+        this.adapterClosed = false;
+        this.closePromise = null;
+        this.closeDeadline = 0;
+        this.finishClose = function () { };
+        this.dedup = new exposure_dedup_1.ExposureDedup(config.exposureDedupMaxSize, config.exposureDedupExpireSeconds);
+    }
+    report(feature, custom) {
+        if (!feature || !feature.experiment)
+            return false;
+        const source = feature.experiment;
+        const bucket = source.bucketId;
+        // Capture metadata before copying caller properties, which may have getters.
+        const info = Object.assign({}, source, {
+            bucketId: bucket ? Object.assign(Object.create(null), bucket) : null,
+        });
+        if (!info.experimentId || !info.experimentGroupId)
+            return false;
+        if (this.closing || this.stopped) {
+            return false;
+        }
+        const subject = (0, event_1.exposureSubject)(info, feature.accountId, feature.distinctId);
+        const key = (0, exposure_dedup_1.exposureKey)(subject, info.experimentId, info.experimentGroupId);
+        const mark = this.dedup.mark(key);
+        if (!mark) {
+            return false;
+        }
+        let accepted = false;
+        try {
+            if (this.queueSize >= this.config.exposureQueueCapacity) {
+                return false;
+            }
+            const event = (0, event_1.exposureEvent)(feature.accountId, feature.distinctId, info, custom);
+            // Caller property getters can re-enter exposure() or close() while copying.
+            if (this.closing || this.stopped || this.queueSize >= this.config.exposureQueueCapacity) {
+                return false;
+            }
+            const task = {
+                event: event,
+                key: key,
+                mark: mark,
+                sequence: ++this.sequence,
+                next: null,
+            };
+            if (this.tail)
+                this.tail.next = task;
+            else
+                this.head = task;
+            this.tail = task;
+            this.queueSize++;
+            accepted = true;
+            this.schedule();
+            return true;
+        }
+        finally {
+            if (!accepted)
+                this.dedup.unmark(key, mark);
+        }
+    }
+    schedule() {
+        if (this.stopped || this.scheduled || this.active || this.activeBarrier)
+            return;
+        this.scheduled = setImmediate(() => {
+            this.scheduled = undefined;
+            this.remainingInTurn = 64;
+            this.pump();
+        });
+    }
+    pump() {
+        if (this.stopped || this.active || this.activeBarrier)
+            return;
+        if (this.barrier && this.completed >= this.barrier.target) {
+            const barrier = this.barrier;
+            this.barrier = null;
+            this.activeBarrier = barrier;
+            if ((0, request_operation_1.monotonicNow)() >= barrier.deadline) {
+                this.completeBarrier(barrier);
+                return;
+            }
+            Promise.resolve()
+                .then(() => this.adapter.flush())
+                .then(() => this.completeBarrier(barrier), (error) => this.completeBarrier(barrier, error));
+            return;
+        }
+        const task = this.head;
+        if (!task) {
+            if (this.closing)
+                this.finalize();
+            return;
+        }
+        this.head = task.next;
+        if (!this.head)
+            this.tail = null;
+        task.next = null;
+        this.queueSize--;
+        this.active = task;
+        Promise.resolve()
+            .then(() => this.adapter.track(task.event, () => this.unmarkTask(task)))
+            .then((accepted) => {
+            if (accepted === false)
+                throw new Error('Exposure adapter rejected submission');
+        })
+            .then(() => this.completeTask(task), () => {
+            this.unmarkTask(task);
+            this.completeTask(task);
+        });
+    }
+    unmarkTask(task) {
+        this.dedup.unmark(task.key, task.mark);
+    }
+    completeTask(task) {
+        if (this.active !== task)
+            return;
+        this.active = null;
+        this.completed = task.sequence;
+        // Drain a bounded group per turn instead of paying one event-loop turn per
+        // event. Yield after 64 so a full queue cannot monopolize microtasks.
+        if (--this.remainingInTurn > 0)
+            this.pump();
+        else
+            this.schedule();
+    }
+    flush() {
+        if (this.closing || this.stopped)
+            return this.closePromise || Promise.resolve();
+        const current = this.barrier || this.activeBarrier;
+        if (current) {
+            if (this.sequence <= current.target)
+                return current.promise;
+            return Promise.reject(new errors_1.FeatureError('Another exposure flush barrier is pending', 'QUEUE_FULL'));
+        }
+        let resolve, reject;
+        const promise = new Promise((yes, no) => {
+            resolve = yes;
+            reject = no;
+        });
+        const barrier = {
+            target: this.sequence,
+            promise: promise,
+            resolve: resolve,
+            reject: reject,
+            settled: false,
+            deadline: (0, request_operation_1.monotonicNow)() + this.config.exposureFlushTimeoutMillis,
+            timer: setTimeout(() => {
+                this.settleBarrier(barrier, new errors_1.FeatureError('Exposure flush exceeded its wait budget', 'TIMEOUT'));
+                if (this.barrier === barrier)
+                    this.barrier = null;
+                this.schedule();
+            }, this.config.exposureFlushTimeoutMillis),
+        };
+        this.barrier = barrier;
+        this.schedule();
+        return promise;
+    }
+    settleBarrier(barrier, error) {
+        if (barrier.settled)
+            return;
+        barrier.settled = true;
+        clearTimeout(barrier.timer);
+        if (error) {
+            barrier.reject(error instanceof errors_1.FeatureError
+                ? error
+                : new errors_1.FeatureError('Collection flush failed', 'EXPOSURE_ERROR', { cause: error }));
+        }
+        else
+            barrier.resolve();
+    }
+    completeBarrier(barrier, error) {
+        if (!error && (0, request_operation_1.monotonicNow)() >= barrier.deadline)
+            error = new errors_1.FeatureError('Exposure flush exceeded its wait budget', 'TIMEOUT');
+        this.settleBarrier(barrier, error);
+        if (this.activeBarrier === barrier)
+            this.activeBarrier = null;
+        this.schedule();
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closing = true;
+        this.closeDeadline = (0, request_operation_1.monotonicNow)() + this.config.exposureFlushTimeoutMillis;
+        this.closePromise = new Promise((resolve) => {
+            this.finishClose = resolve;
+        });
+        this.closeTimer = setTimeout(() => this.stop(true), this.config.exposureFlushTimeoutMillis);
+        this.schedule();
+        return this.closePromise;
+    }
+    closeAdapter() {
+        if (!this.ownsAdapter || this.adapterClosed)
+            return;
+        this.adapterClosed = true;
+        if (this.adapter.close)
+            return this.adapter.close();
+    }
+    finalize() {
+        if (this.finalizing || this.stopped)
+            return;
+        if ((0, request_operation_1.monotonicNow)() >= this.closeDeadline) {
+            this.stop(true);
+            return;
+        }
+        this.finalizing = true;
+        Promise.resolve()
+            .then(() => {
+            if (this.ownsAdapter && !this.stopped)
+                return this.adapter.flush();
+        })
+            .then(() => {
+            if (this.stopped)
+                return;
+            if ((0, request_operation_1.monotonicNow)() >= this.closeDeadline) {
+                this.stop(true);
+                return;
+            }
+            return this.closeAdapter();
+        })
+            .then(() => this.stop((0, request_operation_1.monotonicNow)() >= this.closeDeadline), () => {
+            this.stop(true);
+        });
+    }
+    stop(timedOut) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.closeTimer)
+            clearTimeout(this.closeTimer);
+        if (this.scheduled) {
+            clearImmediate(this.scheduled);
+            this.scheduled = undefined;
+        }
+        this.head = null;
+        this.tail = null;
+        this.queueSize = 0;
+        this.active = null;
+        const closed = new errors_1.FeatureError('Client closed before exposure flush completed', 'CLIENT_CLOSED');
+        if (this.barrier) {
+            this.settleBarrier(this.barrier, closed);
+            this.barrier = null;
+        }
+        if (this.activeBarrier) {
+            this.settleBarrier(this.activeBarrier, closed);
+            this.activeBarrier = null;
+        }
+        if (timedOut) {
+            // Only SDK-owned adapters may be closed or aborted here.
+            try {
+                Promise.resolve(this.closeAdapter()).then(function () { }, function () { });
+            }
+            catch (_) { }
+            const owned = this.adapter;
+            try {
+                if (this.ownsAdapter && owned.abort)
+                    owned.abort();
+            }
+            catch (_) { }
+        }
+        this.dedup.clear();
+        this.finishClose();
+    }
+}
+exports.ExposeReporter = ExposeReporter;

package/dist/report/exposure-dedup.d.ts

@@ -0,0 +1,16 @@
+export declare function exposureKey(subject: string, experiment: string, group: string): string;
+export interface ExposureMark {
+    readonly expires: number;
+}
+/** Bounded, non-sliding TTL. Tokens keep an old failure from deleting a newer reservation. */
+export declare class ExposureDedup {
+    private readonly capacity;
+    private readonly seconds;
+    private readonly now;
+    private readonly entries;
+    constructor(capacity: number, seconds: number, now?: () => number);
+    mark(key: string): ExposureMark | null;
+    unmark(key: string, mark: ExposureMark): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/report/exposure-dedup.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExposureDedup = void 0;
+exports.exposureKey = exposureKey;
+const crypto_1 = require("crypto");
+const request_operation_1 = require("../core/request-operation");
+function exposureKey(subject, experiment, group) {
+    return (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify([subject, experiment, group]), 'utf8')
+        .digest('hex');
+}
+/** Bounded, non-sliding TTL. Tokens keep an old failure from deleting a newer reservation. */
+class ExposureDedup {
+    constructor(capacity, seconds, now = request_operation_1.monotonicNow) {
+        this.capacity = capacity;
+        this.seconds = seconds;
+        this.now = now;
+        this.entries = new Map();
+    }
+    mark(key) {
+        const existing = this.entries.get(key);
+        if (existing && existing.expires > this.now()) {
+            this.entries.delete(key);
+            this.entries.set(key, existing);
+            return null;
+        }
+        this.entries.delete(key);
+        while (this.entries.size >= this.capacity)
+            this.entries.delete(this.entries.keys().next().value);
+        const mark = { expires: this.now() + this.seconds * 1000 };
+        this.entries.set(key, mark);
+        return mark;
+    }
+    unmark(key, mark) {
+        if (this.entries.get(key) === mark)
+            this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    get size() {
+        return this.entries.size;
+    }
+}
+exports.ExposureDedup = ExposureDedup;

package/dist/report/owned-collection-adapter.d.ts

@@ -0,0 +1,22 @@
+import type { ExposureAdapter, ExposureEvent, ResolvedClientOptions } from '../types';
+/** Official npm Batch collector with instance-owned, cancellable transport. */
+export declare class OwnedCollectionAdapter implements ExposureAdapter {
+    private readonly config;
+    private analytics;
+    private buffered;
+    private sending;
+    private flushTimer;
+    private readonly requests;
+    private readonly agent;
+    private closed;
+    constructor(config: Readonly<ResolvedClientOptions>);
+    track(event: ExposureEvent, onFailure?: (error: Error) => void): void | Promise<void>;
+    private newBatch;
+    private startBatch;
+    private completeBatch;
+    private request;
+    private failedRequest;
+    flush(): Promise<void>;
+    close(): void;
+    abort(): void;
+}

package/dist/report/owned-collection-adapter.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OwnedCollectionAdapter = void 0;
+const http = require("http");
+const https = require("https");
+const events_1 = require("events");
+/** Official npm Batch collector with instance-owned, cancellable transport. */
+class OwnedCollectionAdapter {
+    constructor(config) {
+        this.config = config;
+        this.analytics = null;
+        this.buffered = null;
+        this.sending = null;
+        this.requests = new Map();
+        this.closed = false;
+        this.agent = /^https:/.test(config.serverUrl)
+            ? new https.Agent({
+                keepAlive: true,
+                maxSockets: 1,
+                ca: config.tlsCa,
+            })
+            : new http.Agent({ keepAlive: true, maxSockets: 1 });
+    }
+    track(event, onFailure) {
+        if (this.closed)
+            throw new Error('Collection adapter is closed');
+        // Keep one batch in flight, including compression and HTTP. The reporter
+        // retains subsequent events in its bounded queue while this promise waits.
+        if (this.sending)
+            return this.sending.promise.then(() => this.track(event, onFailure));
+        if (!this.analytics) {
+            const module = require('thinkingdata-node');
+            const analytics = module.initWithBatchMode(this.config.appId, this.config.serverUrl, {
+                batchSize: this.config.exposureBatchSize,
+                compress: true,
+            });
+            // The pinned official 1.5.0 Batch consumer exposes its per-instance server
+            // config. Adapt only this instance; never patch the package or global HTTP.
+            const transport = analytics.consumer && analytics.consumer.config;
+            if (!transport || !transport.requestLib || typeof transport.requestLib.request !== 'function')
+                throw new Error('Unsupported official thinkingdata-node Batch transport');
+            transport.hostname = new URL(this.config.serverUrl).hostname.replace(/^\[|\]$/g, '');
+            transport.requestLib = { request: this.request.bind(this) };
+            this.analytics = analytics;
+        }
+        const batch = this.buffered || (this.buffered = this.newBatch());
+        let calling = true;
+        let localError;
+        const params = {
+            event: event.event,
+            properties: event.properties,
+            callback: (error) => {
+                if (calling)
+                    localError = error || undefined;
+                else
+                    this.completeBatch(batch, error || undefined);
+            },
+        };
+        if (event.accountId !== null)
+            params.accountId = event.accountId;
+        if (event.distinctId !== null)
+            params.distinctId = event.distinctId;
+        try {
+            this.analytics.track(params);
+        }
+        catch (error) {
+            if (!batch.failures.length)
+                this.buffered = null;
+            throw error;
+        }
+        calling = false;
+        if (localError) {
+            if (!batch.failures.length)
+                this.buffered = null;
+            throw localError;
+        }
+        batch.failures.push(onFailure);
+        if (batch.failures.length >= this.config.exposureBatchSize) {
+            // The threshold event has already triggered the native Batch flush.
+            this.startBatch(batch);
+            return batch.promise;
+        }
+        if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flushTimer = undefined;
+                this.flush();
+            }, this.config.exposureFlushIntervalMillis);
+            this.flushTimer.unref();
+        }
+    }
+    newBatch() {
+        let resolve;
+        const promise = new Promise((done) => {
+            resolve = done;
+        });
+        return { failures: [], promise, resolve, settled: false };
+    }
+    startBatch(batch) {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        this.buffered = null;
+        this.sending = batch;
+    }
+    completeBatch(batch, error) {
+        if (batch.settled)
+            return;
+        batch.settled = true;
+        if (this.buffered === batch)
+            this.buffered = null;
+        if (this.sending === batch)
+            this.sending = null;
+        if (error) {
+            for (const notify of batch.failures)
+                if (notify)
+                    notify(error);
+        }
+        batch.failures.length = 0;
+        // Individual submission failures roll back dedup, as for custom adapters;
+        // flush waits for settlement and does not assert successful ingestion.
+        batch.resolve();
+    }
+    request(options, callback) {
+        if (this.closed) {
+            // Upstream gzip is asynchronous and may finish after close. Never start late I/O.
+            return this.failedRequest(new Error('Collection adapter is closed'));
+        }
+        const native = /^https:/.test(this.config.serverUrl) ? https : http;
+        options.agent = this.agent;
+        let response;
+        let request;
+        try {
+            request = native.request(options, (incoming) => {
+                response = incoming;
+                let bytes = 0, ended = false;
+                incoming.on('data', (chunk) => {
+                    bytes += chunk.length;
+                    if (bytes > 1024 * 1024)
+                        fail(new Error('Collection response exceeds 1 MiB'));
+                });
+                incoming.on('end', () => {
+                    ended = true;
+                    cleanup();
+                });
+                incoming.on('error', fail);
+                incoming.on('aborted', () => fail(new Error('Collection response aborted')));
+                incoming.on('close', () => {
+                    if (!ended)
+                        fail(new Error('Collection response ended prematurely'));
+                });
+                if (incoming.statusCode === 200)
+                    callback(incoming);
+                else {
+                    // The official consumer reports non-200 responses at headers. Drain
+                    // their bounded body first so the next batch cannot queue behind it.
+                    incoming.once('end', () => callback(incoming));
+                    incoming.resume();
+                }
+            });
+        }
+        catch (error) {
+            // This call can run in upstream's gzip callback. Convert sync native
+            // errors into its error event instead of throwing out of that callback.
+            return this.failedRequest(error);
+        }
+        let failed = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            this.requests.delete(request);
+        };
+        const fail = (error) => {
+            if (failed)
+                return;
+            failed = true;
+            cleanup();
+            // The upstream Batch callback listens on ClientRequest.error.
+            request.emit('error', error);
+            request.abort();
+            if (response)
+                response.destroy();
+        };
+        const timer = setTimeout(() => fail(new Error('Collection request timed out')), this.config.exposureFlushTimeoutMillis);
+        this.requests.set(request, () => fail(new Error('Collection adapter closed')));
+        request.on('error', () => {
+            failed = true;
+            cleanup();
+        });
+        return request;
+    }
+    failedRequest(error) {
+        const dead = Object.assign(new events_1.EventEmitter(), {
+            write: function () {
+                return false;
+            },
+            end: function () { },
+            abort: function () { },
+        });
+        process.nextTick(() => dead.emit('error', error));
+        return dead;
+    }
+    flush() {
+        if (this.closed)
+            return Promise.resolve();
+        if (this.sending)
+            return this.sending.promise.then(() => this.flush());
+        const batch = this.buffered;
+        if (!batch)
+            return Promise.resolve();
+        this.startBatch(batch);
+        try {
+            this.analytics.flush((error) => this.completeBatch(batch, error || undefined));
+        }
+        catch (error) {
+            this.completeBatch(batch, error);
+        }
+        return batch.promise;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.analytics)
+            this.analytics.close();
+        this.abort();
+    }
+    abort() {
+        this.closed = true;
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        Array.from(this.requests.values()).forEach(function (cancel) {
+            cancel();
+        });
+        this.requests.clear();
+        this.agent.destroy();
+        const error = new Error('Collection adapter closed');
+        if (this.buffered)
+            this.completeBatch(this.buffered, error);
+        if (this.sending)
+            this.completeBatch(this.sending, error);
+    }
+}
+exports.OwnedCollectionAdapter = OwnedCollectionAdapter;

package/dist/report/thinking-data-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { ExposureAdapter, ExposureEvent, ExposureSubmission, ThinkingDataAnalytics } from '../types';
+/** Converts SDK-owned exposure fields to the official Node track({ ... }) API. */
+export declare class ThinkingDataAdapter implements ExposureAdapter {
+    private readonly analytics;
+    constructor(analytics: ThinkingDataAnalytics);
+    track(event: ExposureEvent, onFailure?: (error: Error) => void): ExposureSubmission;
+    flush(): void | PromiseLike<void>;
+    close(): void | PromiseLike<void>;
+}
+/** Adapt an existing collection SDK instance; its lifecycle stays caller-owned. */
+export declare function createThinkingDataAdapter(analytics: ThinkingDataAnalytics): ExposureAdapter;