@crawlee/core 4.0.0-beta.12 → 4.0.0-beta.121

package/autoscaling/concurrency_system.js

@@ -0,0 +1,351 @@
+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;
+    // kept as TS-private _-prefixed: autoscaled_pool tests write this backing field directly
+    _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

@@ -0,0 +1,43 @@
+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 {
+    #private;
+    readonly name = "cpuInfo";
+    readonly overloadedRatio: number;
+    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

@@ -0,0 +1,47 @@
+import { EventType } from '../events/event_manager.js';
+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(EventType.SYSTEM_INFO, this.handle);
+    }
+    async stop() {
+        this.#events?.off(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

@@ -0,0 +1,51 @@
+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 {
+    #private;
+    readonly name = "eventLoopInfo";
+    readonly overloadedRatio: number;
+    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

@@ -0,0 +1,60 @@
+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,4 +1,9 @@
 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';
-//# sourceMappingURL=index.d.ts.map

package/autoscaling/index.js

@@ -1,4 +1,9 @@
 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';
-//# sourceMappingURL=index.js.map

package/autoscaling/load_signal.d.ts

@@ -0,0 +1,99 @@
+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;
+    /** 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;