@crawlee/core 4.0.0-beta.99 → 4.0.0-rc.1

package/autoscaling/concurrency_system.js

@@ -1,350 +0,0 @@
-import ow from 'ow';
-import { betterClearInterval, betterSetInterval } from '@apify/utilities';
-import { serviceLocator } from '../service_locator.js';
-import { Snapshotter } from './snapshotter.js';
-import { SystemStatus } from './system_status.js';
-/**
- * The shareable "governor" behind an {@link AutoscaledPool}: it decides whether there is free compute for one more
- * task by combining live system load (via an internal {@link Snapshotter}) with a concurrency budget it autoscales
- * over time.
- *
- * Sharing one instance between several pools (and therefore several crawlers) caps their *combined* compute, instead
- * of letting each scale independently and oversubscribe the machine.
- *
- * Whoever builds the instance owns its lifecycle: call {@link ConcurrencySystem.start|`start()`} before any
- * borrowing pool runs and {@link ConcurrencySystem.stop|`stop()`} once they are all done (crawlers do this for the
- * default system they build, never for an injected one). Both calls are idempotent, and the first `stop()` tears the
- * system down for every borrower.
- * @category Scaling
- */
-export class ConcurrencySystem {
-    log;
-    desiredConcurrencyRatio;
-    scaleUpStepRatio;
-    scaleDownStepRatio;
-    loggingIntervalMillis;
-    autoscaleIntervalMillis;
-    maxTasksPerMinute;
-    _minConcurrency;
-    _maxConcurrency;
-    _desiredConcurrency;
-    _currentConcurrency = 0;
-    lastLoggingTime;
-    _tasksPerMinute = Array.from({ length: 60 }, () => 0);
-    snapshotter;
-    loadSignals;
-    systemStatus;
-    autoscaleInterval;
-    tasksDonePerSecondInterval;
-    /** Whether the snapshotter and autoscaling intervals are currently running. */
-    running = false;
-    /** The in-flight (or completed) startup, memoized so concurrent `start()` calls await one boot. */
-    startPromise;
-    /** Set once per session, so a pool outliving `stop()` is reported once rather than every half second. */
-    warnedAboutQueryWhileStopped = false;
-    constructor(options = {}) {
-        ow(options, ow.object.exactShape({
-            maxConcurrency: ow.optional.number.integer.greaterThanOrEqual(1),
-            minConcurrency: ow.optional.number.integer.greaterThanOrEqual(1),
-            desiredConcurrency: ow.optional.number.integer.greaterThanOrEqual(1),
-            desiredConcurrencyRatio: ow.optional.number.greaterThan(0).lessThan(1),
-            scaleUpStepRatio: ow.optional.number.greaterThan(0).lessThan(1),
-            scaleDownStepRatio: ow.optional.number.greaterThan(0).lessThan(1),
-            loggingIntervalSecs: ow.any(ow.number.greaterThan(0), ow.nullOrUndefined),
-            autoscaleIntervalSecs: ow.optional.number.greaterThan(0),
-            loadSignals: ow.optional.object,
-            snapshotHistorySecs: ow.optional.number.greaterThan(0),
-            currentHistorySecs: ow.optional.number.greaterThan(0),
-            log: ow.optional.object,
-            maxTasksPerMinute: ow.optional.number.integerOrInfinite.greaterThanOrEqual(1),
-        }));
-        const { maxConcurrency = 200, minConcurrency = 1, desiredConcurrency, desiredConcurrencyRatio = 0.9, scaleUpStepRatio = 0.05, scaleDownStepRatio = 0.05, loggingIntervalSecs = 60, autoscaleIntervalSecs = 10, loadSignals = {}, snapshotHistorySecs, currentHistorySecs, log = serviceLocator.getLogger(), maxTasksPerMinute = Infinity, } = options;
-        this.log = log.child({ prefix: 'ConcurrencySystem' });
-        this.desiredConcurrencyRatio = desiredConcurrencyRatio;
-        this.scaleUpStepRatio = scaleUpStepRatio;
-        this.scaleDownStepRatio = scaleDownStepRatio;
-        this.loggingIntervalMillis = (loggingIntervalSecs ?? 0) * 1000;
-        this.autoscaleIntervalMillis = autoscaleIntervalSecs * 1000;
-        this.maxTasksPerMinute = maxTasksPerMinute;
-        this._minConcurrency = minConcurrency;
-        this._maxConcurrency = maxConcurrency;
-        this._desiredConcurrency = desiredConcurrency ?? minConcurrency;
-        this.clampDesiredConcurrency();
-        this._autoscale = this._autoscale.bind(this);
-        this._incrementTasksDonePerSecond = this._incrementTasksDonePerSecond.bind(this);
-        // The built-in signals are collected by the snapshotter; custom ones are simply evaluated alongside them.
-        const { custom: customLoadSignals = [], ...builtinSignalOptions } = loadSignals;
-        this.snapshotter = new Snapshotter(builtinSignalOptions);
-        this.loadSignals = customLoadSignals;
-        this.systemStatus = new SystemStatus({
-            snapshotter: this.snapshotter,
-            loadSignals: customLoadSignals,
-            currentHistorySecs,
-            // Both windows are requested from the signals explicitly, so a signal's own retention can neither widen
-            // nor (given the start context below) narrow what it contributes.
-            historySecs: snapshotHistorySecs,
-        });
-    }
-    /**
-     * Gets the minimum number of tasks running in parallel.
-     */
-    get minConcurrency() {
-        return this._minConcurrency;
-    }
-    /**
-     * Sets the minimum number of tasks running in parallel.
-     *
-     * *WARNING:* If you set this value too high with respect to the available system memory and CPU, your code might run extremely slow or crash.
-     * If you're not sure, just keep the default value and the concurrency will scale up automatically.
-     */
-    set minConcurrency(value) {
-        ow(value, ow.optional.number.integer.greaterThanOrEqual(1));
-        this._minConcurrency = value;
-        this.clampDesiredConcurrency();
-    }
-    /**
-     * Gets the maximum number of tasks running in parallel.
-     */
-    get maxConcurrency() {
-        return this._maxConcurrency;
-    }
-    /**
-     * Sets the maximum number of tasks running in parallel. Lowering it below the current
-     * {@link ConcurrencySystem.desiredConcurrency|`desiredConcurrency`} pulls that down to the new ceiling too, so
-     * the change takes effect immediately (in-flight tasks are never cancelled — the budget simply drains to the new
-     * limit as they settle).
-     */
-    set maxConcurrency(value) {
-        ow(value, ow.optional.number.integer.greaterThanOrEqual(1));
-        this._maxConcurrency = value;
-        this.clampDesiredConcurrency();
-    }
-    /**
-     * Gets the desired concurrency for the system,
-     * which is an estimated number of parallel tasks that the system can currently support.
-     */
-    get desiredConcurrency() {
-        return this._desiredConcurrency;
-    }
-    /**
-     * Sets the desired concurrency for the system, i.e. the number of tasks that should be running
-     * in parallel if there's large enough supply of tasks.
-     */
-    set desiredConcurrency(value) {
-        ow(value, ow.optional.number.integer.greaterThanOrEqual(1));
-        this._desiredConcurrency = value;
-        this.clampDesiredConcurrency();
-    }
-    /**
-     * Re-establishes `minConcurrency <= desiredConcurrency <= maxConcurrency` after any of the three is retuned.
-     * Dispatch gates on the desired value alone, so one stranded above `maxConcurrency` would make the ceiling
-     * meaningless. A contradictory pair (`minConcurrency > maxConcurrency`) resolves in favour of the maximum, since
-     * that is the limit callers set in order to protect something.
-     */
-    clampDesiredConcurrency() {
-        const atLeastMin = Math.max(this._desiredConcurrency, this._minConcurrency);
-        this._desiredConcurrency = Math.min(atLeastMin, this._maxConcurrency);
-    }
-    get currentConcurrency() {
-        return this._currentConcurrency;
-    }
-    /** Whether the system is currently monitoring load and autoscaling the budget. */
-    get isRunning() {
-        return this.running;
-    }
-    /**
-     * Boots the underlying snapshotter and the autoscaling interval. Idempotent, so a shared system isn't restarted
-     * when handed to another consumer; concurrent callers await one startup. Rejects, leaving nothing running, if a
-     * signal fails to start.
-     */
-    async start() {
-        // Unwound and dropped again on failure, so a later `start()` retries instead of resolving instantly against
-        // a system that is down.
-        this.startPromise ??= this.boot().catch(async (error) => {
-            this.startPromise = undefined;
-            await this.shutDown();
-            throw error;
-        });
-        await this.startPromise;
-    }
-    async boot() {
-        // Per-session measurement state, reset so a restarted system isn't judged on the previous session. The
-        // per-minute window matters most: its ageing interval is cleared while we are down, so starts from before an
-        // arbitrarily long stop would otherwise still count against "this minute" and trip the cap immediately.
-        this._tasksPerMinute = Array.from({ length: 60 }, () => 0);
-        this.lastLoggingTime = undefined;
-        this.warnedAboutQueryWhileStopped = false;
-        // Signals are told how much history to keep when they start: exactly the longest window they will be sampled
-        // over, so nobody has to guess a retention value that matches this system's configuration.
-        const startContext = { maxSampleWindowMillis: this.systemStatus.maxSampleWindowMillis };
-        await this.snapshotter.start(startContext);
-        await Promise.all(this.loadSignals.map(async (s) => s.start(startContext)));
-        this.autoscaleInterval = betterSetInterval(this._autoscale, this.autoscaleIntervalMillis);
-        if (this.maxTasksPerMinute !== Infinity) {
-            this.tasksDonePerSecondInterval = betterSetInterval(this._incrementTasksDonePerSecond, 1000);
-        }
-        // Last, so `isRunning` never claims a system whose signals aren't collecting yet.
-        this.running = true;
-    }
-    /**
-     * Stops the snapshotter and intervals. Idempotent and safe to call even if the system was never started.
-     */
-    async stop() {
-        if (this.startPromise === undefined) {
-            return;
-        }
-        // Waited out rather than interrupted, or the intervals a starting signal is about to register outlive us.
-        await this.startPromise.catch(() => { });
-        this.startPromise = undefined;
-        this.running = false;
-        await this.shutDown();
-    }
-    async shutDown() {
-        if (this.autoscaleInterval)
-            betterClearInterval(this.autoscaleInterval);
-        if (this.tasksDonePerSecondInterval)
-            betterClearInterval(this.tasksDonePerSecondInterval);
-        await this.snapshotter.stop();
-        await Promise.all(this.loadSignals.map(async (s) => s.stop()));
-    }
-    /**
-     * Reports, once per session, that capacity is being queried on a system that isn't running — a mistake nothing
-     * else catches, since {@link AutoscaledPool.run|`pool.run()`} only checks
-     * {@link ConcurrencySystem.isRunning|`isRunning`} on the way in. Both the overload verdict and
-     * `desiredConcurrency` are frozen at that point, so the borrowing pool would otherwise just quietly mis-scale.
-     */
-    warnIfNotRunning() {
-        if (this.running || this.warnedAboutQueryWhileStopped) {
-            return;
-        }
-        this.warnedAboutQueryWhileStopped = true;
-        this.log.warning('Capacity is being queried on a ConcurrencySystem that is not running, so system load is no longer being ' +
-            'monitored and the concurrency will no longer be adjusted. Whoever creates a ConcurrencySystem owns ' +
-            'its lifecycle: call `await concurrencySystem.stop()` only once every pool and crawler borrowing it ' +
-            'has finished.');
-    }
-    /**
-     * May **one more** task start right now? Returns `false` when the shared budget is spent (desired concurrency
-     * reached) or when the machine is overloaded past `minConcurrency`.
-     *
-     * One budget for the whole machine, so the asking consumer is ignored — and therefore optional here, unlike in the
-     * interface, letting the answer be queried directly.
-     */
-    hasCapacityForTask(_consumer) {
-        this.warnIfNotRunning();
-        if (this._currentConcurrency >= this._desiredConcurrency) {
-            this.log.perf('Task will not run. Desired concurrency achieved.');
-            return false;
-        }
-        const currentStatus = this.systemStatus.getCurrentStatus();
-        const { isSystemIdle } = currentStatus;
-        if (!isSystemIdle && this._currentConcurrency >= this._minConcurrency) {
-            this.log.perf('Task will not be run. System is overloaded.', currentStatus);
-            return false;
-        }
-        return true;
-    }
-    /** Whether the per-minute task cap has been reached. */
-    get isOverMaxRequestLimit() {
-        if (this.maxTasksPerMinute === Infinity) {
-            return false;
-        }
-        return this._tasksPerMinute.reduce((acc, curr) => acc + curr, 0) >= this.maxTasksPerMinute;
-    }
-    /**
-     * Atomically books a task against the shared budget: re-checks
-     * {@link ConcurrencySystem.hasCapacityForTask|`hasCapacityForTask()`} plus the per-minute task cap and
-     * increments the current concurrency in one synchronous step, returning `false` (without booking) when there is no
-     * room. Call right before the task actually runs.
-     *
-     * The cap is enforced here rather than in the pre-check so that an empty queue never blocks the pool for a whole
-     * extra minute.
-     */
-    tryRegisterTaskStart(consumer) {
-        if (!this.hasCapacityForTask(consumer)) {
-            return false;
-        }
-        if (this.isOverMaxRequestLimit) {
-            this.log.perf('Task will not run. Maximum tasks per minute reached.');
-            return false;
-        }
-        this._currentConcurrency++;
-        this._tasksPerMinute[0]++;
-        return true;
-    }
-    /** Returns a slot to the shared budget, whoever booked it. */
-    registerTaskEnd(_consumer) {
-        this._currentConcurrency--;
-    }
-    /**
-     * What the system currently makes of the machine: the per-signal overload verdicts, evaluated over the
-     * task-gating window, exactly as {@link ConcurrencySystem.hasCapacityForTask|`hasCapacityForTask()`} sees them.
-     * The one public window into load monitoring — useful for answering *why* a crawl is not scaling up.
-     */
-    getCurrentStatus() {
-        return this.systemStatus.getCurrentStatus();
-    }
-    /**
-     * Evaluates the historical system status and scales the shared desired concurrency up or down accordingly. Driven
-     * by the autoscaling interval started in {@link ConcurrencySystem.start|`start()`}.
-     */
-    _autoscale(intervalCallback) {
-        if (this.isOverMaxRequestLimit)
-            return intervalCallback();
-        const systemStatus = this.systemStatus.getHistoricalStatus();
-        const { isSystemIdle } = systemStatus;
-        const weAreNotAtMax = this._desiredConcurrency < this._maxConcurrency;
-        const minCurrentConcurrency = Math.floor(this._desiredConcurrency * this.desiredConcurrencyRatio);
-        const weAreReachingDesiredConcurrency = this._currentConcurrency >= minCurrentConcurrency;
-        if (isSystemIdle && weAreNotAtMax && weAreReachingDesiredConcurrency)
-            this._scaleUp(systemStatus);
-        const isSystemOverloaded = !isSystemIdle;
-        const weAreNotAtMin = this._desiredConcurrency > this._minConcurrency;
-        if (isSystemOverloaded && weAreNotAtMin)
-            this._scaleDown(systemStatus);
-        if (this.loggingIntervalMillis > 0) {
-            const now = Date.now();
-            if (this.lastLoggingTime == null) {
-                this.lastLoggingTime = now;
-            }
-            else if (now > this.lastLoggingTime + this.loggingIntervalMillis) {
-                this.lastLoggingTime = now;
-                this.log.info('state', {
-                    currentConcurrency: this._currentConcurrency,
-                    desiredConcurrency: this._desiredConcurrency,
-                    systemStatus,
-                });
-            }
-        }
-        return intervalCallback();
-    }
-    /**
-     * Scales the system up by increasing the desired concurrency by the scaleUpStepRatio.
-     */
-    _scaleUp(systemStatus) {
-        const step = Math.ceil(this._desiredConcurrency * this.scaleUpStepRatio);
-        this._desiredConcurrency = Math.min(this._maxConcurrency, this._desiredConcurrency + step);
-        this.log.debug('scaling up', {
-            oldConcurrency: this._desiredConcurrency - step,
-            newConcurrency: this._desiredConcurrency,
-            systemStatus,
-        });
-    }
-    /**
-     * Scales the system down by decreasing the desired concurrency by the scaleDownStepRatio.
-     */
-    _scaleDown(systemStatus) {
-        const step = Math.ceil(this._desiredConcurrency * this.scaleDownStepRatio);
-        this._desiredConcurrency = Math.max(this._minConcurrency, this._desiredConcurrency - step);
-        this.log.debug('scaling down', {
-            oldConcurrency: this._desiredConcurrency + step,
-            newConcurrency: this._desiredConcurrency,
-            systemStatus,
-        });
-    }
-    _incrementTasksDonePerSecond(intervalCallback) {
-        this._tasksPerMinute.unshift(0);
-        this._tasksPerMinute.pop();
-        return intervalCallback();
-    }
-}

package/autoscaling/cpu_load_signal.d.ts

@@ -1,44 +0,0 @@
-import type { LoadSignal, LoadSignalStartContext, LoadSnapshot } from './load_signal.js';
-import type { SystemInfo } from './system_status.js';
-/**
- * A snapshot produced by the built-in CPU signal.
- * @internal
- */
-export interface CpuSnapshot extends LoadSnapshot {
-    usedRatio: number;
-    ticks?: {
-        idle: number;
-        total: number;
-    };
-}
-/**
- * Tuning for the built-in **CPU** load signal, as accepted both by {@link CpuLoadSignal} and by the
- * {@link LoadSignalsOptions.cpu|`cpu`} shorthand on {@link LoadSignalsOptions}.
- */
-export interface CpuLoadSignalOptions {
-    /**
-     * Maximum ratio of overloaded snapshots in a sample before the CPU counts as overloaded.
-     * @default 0.4
-     */
-    overloadedRatio?: number;
-}
-/**
- * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when the platform or local OS metrics indicate the
- * CPU is overloaded.
- *
- * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
- *
- * @category Scaling
- */
-export declare class CpuLoadSignal implements LoadSignal {
-    readonly name = "cpuInfo";
-    readonly overloadedRatio: number;
-    private readonly store;
-    private events?;
-    constructor(options?: CpuLoadSignalOptions);
-    start(context: LoadSignalStartContext): Promise<void>;
-    stop(): Promise<void>;
-    getSample(sampleDurationMillis?: number): LoadSnapshot[];
-    /** @internal Records a snapshot from a `SYSTEM_INFO` payload. Exposed for tests. */
-    handle(systemInfo: SystemInfo): void;
-}

package/autoscaling/cpu_load_signal.js

@@ -1,46 +0,0 @@
-import { serviceLocator } from '../service_locator.js';
-import { SnapshotStore } from './load_signal.js';
-/**
- * Tracks CPU usage via `SYSTEM_INFO` events and reports overload when the platform or local OS metrics indicate the
- * CPU is overloaded.
- *
- * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
- *
- * @category Scaling
- */
-export class CpuLoadSignal {
-    name = 'cpuInfo';
-    overloadedRatio;
-    store = new SnapshotStore();
-    events;
-    constructor(options = {}) {
-        this.overloadedRatio = options.overloadedRatio ?? 0.4;
-        this.handle = this.handle.bind(this);
-    }
-    async start(context) {
-        this.store.useSampleWindow(context.maxSampleWindowMillis);
-        // A new session starts from a clean slate, so it is not judged on measurements from before the downtime.
-        this.store.clear();
-        // Resolved here rather than in the constructor, so an instance built ahead of time (to be wrapped, or shared
-        // between systems) cannot capture whichever event manager happened to be registered at that moment.
-        this.events = serviceLocator.getEventManager();
-        this.events.on("systemInfo" /* EventType.SYSTEM_INFO */, this.handle);
-    }
-    async stop() {
-        this.events?.off("systemInfo" /* EventType.SYSTEM_INFO */, this.handle);
-        this.events = undefined;
-    }
-    getSample(sampleDurationMillis) {
-        return this.store.getSample(sampleDurationMillis);
-    }
-    /** @internal Records a snapshot from a `SYSTEM_INFO` payload. Exposed for tests. */
-    handle(systemInfo) {
-        const { cpuCurrentUsage, isCpuOverloaded } = systemInfo;
-        const createdAt = systemInfo.createdAt ? new Date(systemInfo.createdAt) : new Date();
-        this.store.push({
-            createdAt,
-            isOverloaded: isCpuOverloaded,
-            usedRatio: Math.ceil(cpuCurrentUsage / 100),
-        }, createdAt);
-    }
-}

package/autoscaling/event_loop_load_signal.d.ts

@@ -1,54 +0,0 @@
-import type { LoadSignal, LoadSignalStartContext, LoadSnapshot } from './load_signal.js';
-/**
- * A snapshot produced by the built-in event loop signal.
- * @internal
- */
-export interface EventLoopSnapshot extends LoadSnapshot {
-    exceededMillis: number;
-}
-/**
- * Tuning for the built-in **event loop** load signal, as accepted both by {@link EventLoopLoadSignal} and by the
- * {@link LoadSignalsOptions.eventLoop|`eventLoop`} shorthand on {@link LoadSignalsOptions}.
- */
-export interface EventLoopLoadSignalOptions {
-    /**
-     * Defines the interval of measuring the event loop response time, in seconds.
-     * @default 0.5
-     */
-    snapshotIntervalSecs?: number;
-    /**
-     * Maximum allowed delay of the event loop in milliseconds.
-     * Exceeding this limit overloads the event loop.
-     * @default 50
-     */
-    maxBlockedMillis?: number;
-    /**
-     * Maximum ratio of overloaded snapshots in a sample before the event loop counts as overloaded.
-     * @default 0.6
-     */
-    overloadedRatio?: number;
-}
-/**
- * Periodically measures event loop delay and reports overload when the delay exceeds a configured threshold.
- *
- * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
- *
- * @category Scaling
- */
-export declare class EventLoopLoadSignal implements LoadSignal {
-    readonly name = "eventLoopInfo";
-    readonly overloadedRatio: number;
-    private readonly store;
-    private readonly intervalMillis;
-    private readonly maxBlockedMillis;
-    private interval?;
-    constructor(options?: EventLoopLoadSignalOptions);
-    start(context: LoadSignalStartContext): Promise<void>;
-    stop(): Promise<void>;
-    getSample(sampleDurationMillis?: number): LoadSnapshot[];
-    /**
-     * Records one snapshot: how much later than scheduled this tick ran is how long the loop was blocked.
-     * @internal Also lets tests drive the measurement without waiting on a timer.
-     */
-    handle(intervalCallback: () => unknown): void;
-}

package/autoscaling/event_loop_load_signal.js

@@ -1,60 +0,0 @@
-import { betterClearInterval, betterSetInterval } from '@apify/utilities';
-import { SnapshotStore } from './load_signal.js';
-/**
- * Periodically measures event loop delay and reports overload when the delay exceeds a configured threshold.
- *
- * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
- *
- * @category Scaling
- */
-export class EventLoopLoadSignal {
-    name = 'eventLoopInfo';
-    overloadedRatio;
-    store = new SnapshotStore();
-    intervalMillis;
-    maxBlockedMillis;
-    interval;
-    constructor(options = {}) {
-        this.overloadedRatio = options.overloadedRatio ?? 0.6;
-        this.intervalMillis = (options.snapshotIntervalSecs ?? 0.5) * 1000;
-        this.maxBlockedMillis = options.maxBlockedMillis ?? 50;
-        this.handle = this.handle.bind(this);
-    }
-    async start(context) {
-        this.store.useSampleWindow(context.maxSampleWindowMillis);
-        // A new session starts from a clean slate, or the downtime gets charged to the event loop: `handle()` measures
-        // the gap since the previous snapshot, which across a restart is however long the system was stopped.
-        this.store.clear();
-        this.interval = betterSetInterval(this.handle, this.intervalMillis);
-    }
-    async stop() {
-        if (this.interval)
-            betterClearInterval(this.interval);
-        this.interval = undefined;
-    }
-    getSample(sampleDurationMillis) {
-        return this.store.getSample(sampleDurationMillis);
-    }
-    /**
-     * Records one snapshot: how much later than scheduled this tick ran is how long the loop was blocked.
-     * @internal Also lets tests drive the measurement without waiting on a timer.
-     */
-    handle(intervalCallback) {
-        const now = new Date();
-        const snapshot = {
-            createdAt: now,
-            isOverloaded: false,
-            exceededMillis: 0,
-        };
-        const all = this.store.getAll();
-        const previousSnapshot = all[all.length - 1];
-        if (previousSnapshot) {
-            const delta = now.getTime() - +previousSnapshot.createdAt - this.intervalMillis;
-            if (delta > this.maxBlockedMillis)
-                snapshot.isOverloaded = true;
-            snapshot.exceededMillis = Math.max(delta - this.maxBlockedMillis, 0);
-        }
-        this.store.push(snapshot, now);
-        intervalCallback();
-    }
-}

package/autoscaling/index.d.ts

@@ -1,9 +0,0 @@
-export * from './autoscaled_pool.js';
-export * from './concurrency_system.js';
-export * from './client_load_signal.js';
-export * from './cpu_load_signal.js';
-export * from './event_loop_load_signal.js';
-export * from './load_signal.js';
-export * from './memory_load_signal.js';
-export * from './snapshotter.js';
-export * from './system_status.js';

package/autoscaling/index.js

@@ -1,9 +0,0 @@
-export * from './autoscaled_pool.js';
-export * from './concurrency_system.js';
-export * from './client_load_signal.js';
-export * from './cpu_load_signal.js';
-export * from './event_loop_load_signal.js';
-export * from './load_signal.js';
-export * from './memory_load_signal.js';
-export * from './snapshotter.js';
-export * from './system_status.js';

package/autoscaling/load_signal.d.ts

@@ -1,99 +0,0 @@
-import type { ClientInfo } from './system_status.js';
-/**
- * A snapshot of a resource's overload state at a point in time.
- */
-export interface LoadSnapshot {
-    createdAt: Date;
-    isOverloaded: boolean;
-}
-/**
- * Handed to a {@link LoadSignal} when it starts, so it can size its snapshot retention to what it will actually
- * be asked for — without having to know how the {@link ConcurrencySystem} that drives it is configured.
- */
-export interface LoadSignalStartContext {
-    /**
-     * The longest sample window the signal will be queried with (the wider of the task-gating and autoscaling
-     * windows). Keeping less history than this contributes a narrower view of the resource than the other signals;
-     * keeping more is wasted memory, as the extra snapshots are never sampled.
-     */
-    maxSampleWindowMillis: number;
-}
-/**
- * A signal that reports whether a particular resource is overloaded. The {@link ConcurrencySystem} aggregates
- * several of them — if any one reports overload, the system is overloaded.
- *
- * The built-in signals cover memory, CPU, event loop and storage-client rate limits. Implement this interface to add
- * your own (navigation timeouts, proxy health, …) and pass them via
- * {@link LoadSignalsOptions.custom|`loadSignals.custom`}; {@link SnapshotStore} does the time-windowed
- * bookkeeping if you want it. Each built-in is also a public class, so one can be *wrapped* rather than reimplemented
- * — construct it yourself and switch the default off with {@link LoadSignalsOptions.cpu|`cpu: false`} or friends.
- */
-export interface LoadSignal {
-    /**
-     * This signal's key in the reported {@link SystemInfo}, also used in logging — so it must be unique among the
-     * signals of one {@link ConcurrencySystem}, which throws on a duplicate. The four built-in names (`memInfo`,
-     * `eventLoopInfo`, `cpuInfo`, `clientInfo`) land in the correspondingly named `SystemInfo` fields rather than the
-     * `loadSignalInfo` bag; taking one over means switching that built-in off.
-     */
-    readonly name: string;
-    /**
-     * Maximum ratio of overloaded snapshots in a sample before the signal
-     * is considered overloaded. For example, `0.2` means the signal fires
-     * when more than 20% of the sample window is overloaded.
-     */
-    readonly overloadedRatio: number;
-    /**
-     * Start collecting snapshots, retaining at least the sample window named in the `context`. Called when the
-     * {@link ConcurrencySystem} starts — which may be a *restart*, so drop anything measured before it.
-     */
-    start(context: LoadSignalStartContext): Promise<void>;
-    /** Stop collecting snapshots. Called when the {@link ConcurrencySystem} shuts down. */
-    stop(): Promise<void>;
-    /**
-     * Return snapshots for a recent time window (used for "current" status).
-     * @param sampleDurationMillis How far back to look, in milliseconds.
-     */
-    getSample(sampleDurationMillis?: number): LoadSnapshot[];
-}
-/**
- * A time-pruning, time-windowed store for `LoadSnapshot` values. All four built-in signals compose with one of these,
- * and so can yours — it is the only part of their machinery worth reusing.
- */
-export declare class SnapshotStore<T extends LoadSnapshot = LoadSnapshot> {
-    private snapshots;
-    /** Retention window in milliseconds. Unbounded until {@link SnapshotStore.useSampleWindow|`useSampleWindow()`}. */
-    private historyMillis;
-    /**
-     * Sizes retention to the window the signal will be sampled over, as handed to it in
-     * {@link LoadSignal.start|`start()`}. Until this is called nothing is pruned at all, so a signal that ignores
-     * its start context grows unboundedly.
-     */
-    useSampleWindow(maxSampleWindowMillis: number): void;
-    /**
-     * Add a snapshot and prune entries older than the history window.
-     */
-    push(snapshot: T, now?: Date): void;
-    /**
-     * Return all snapshots, or only those within the given time window.
-     */
-    getSample(sampleDurationMillis?: number): T[];
-    /**
-     * Direct, unwindowed access to the underlying array — used by signals whose handler needs the previous snapshot
-     * to compute a delta (e.g. the event loop and client signals read the last entry to measure change since it).
-     */
-    getAll(): T[];
-    /**
-     * Discards every retained snapshot. The built-in signals do this when they *start*, so that a session neither
-     * samples nor diffs against measurements from before the preceding downtime — pruning is relative to the newest
-     * snapshot rather than the wall clock, so stale entries would otherwise survive indefinitely. Clearing on start
-     * rather than on stop leaves a finished session readable.
-     */
-    clear(): void;
-}
-/**
- * Evaluate whether a sample of `LoadSnapshot` values exceeds the given
- * overloaded ratio, using a time-weighted average. This is the shared
- * evaluation logic used by `SystemStatus` for all signal types.
- * @internal
- */
-export declare function evaluateLoadSignalSample(sample: LoadSnapshot[], overloadedRatio: number): ClientInfo;