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

package/autoscaling/concurrency_system.js

@@ -1,8 +1,34 @@
-import ow from 'ow';
+import { z } from 'zod';
 import { betterClearInterval, betterSetInterval } from '@apify/utilities';
 import { serviceLocator } from '../service_locator.js';
+import { parseArgument, schemas, validators } from '../validators.js';
 import { Snapshotter } from './snapshotter.js';
 import { SystemStatus } from './system_status.js';
+const concurrencySchema = z.number().int().gte(1).optional();
+// `schemas.anyObject` passes values through by reference, so the load signal instances inside
+// `loadSignals` and class instances like loggers keep their prototype.
+const concurrencySystemOptionsSchema = z.strictObject({
+    maxConcurrency: z.number().int().gte(1).default(200),
+    minConcurrency: z.number().int().gte(1).default(1),
+    desiredConcurrency: z.number().int().gte(1).optional(),
+    desiredConcurrencyRatio: z.number().gt(0).lt(1).default(0.9),
+    scaleUpStepRatio: z.number().gt(0).lt(1).default(0.05),
+    scaleDownStepRatio: z.number().gt(0).lt(1).default(0.05),
+    loggingIntervalSecs: schemas.anyNumber
+        .refine((value) => value > 0, 'Expected a number greater than 0')
+        .nullish()
+        .default(60),
+    autoscaleIntervalSecs: schemas.anyNumber
+        .refine((value) => value > 0, 'Expected a number greater than 0')
+        .default(10),
+    loadSignals: schemas.anyObject.default(() => ({})),
+    snapshotHistorySecs: schemas.anyNumber.refine((value) => value > 0, 'Expected a number greater than 0').optional(),
+    currentHistorySecs: schemas.anyNumber.refine((value) => value > 0, 'Expected a number greater than 0').optional(),
+    log: validators.logger.default(() => serviceLocator.getLogger()),
+    maxTasksPerMinute: z
+        .union([z.number().int().gte(1), z.literal(Number.POSITIVE_INFINITY)])
+        .default(Number.POSITIVE_INFINITY),
+});
 /**
  * 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
@@ -22,60 +48,46 @@ export class ConcurrencySystem {
     desiredConcurrencyRatio;
     scaleUpStepRatio;
     scaleDownStepRatio;
-    loggingIntervalMillis;
-    autoscaleIntervalMillis;
+    #loggingIntervalMillis;
+    #autoscaleIntervalMillis;
     maxTasksPerMinute;
-    _minConcurrency;
-    _maxConcurrency;
-    _desiredConcurrency;
+    #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);
+    #lastLoggingTime;
+    #tasksPerMinute = Array.from({ length: 60 }, () => 0);
     snapshotter;
-    loadSignals;
+    #loadSignals;
     systemStatus;
-    autoscaleInterval;
-    tasksDonePerSecondInterval;
+    #autoscaleInterval;
+    #tasksDonePerSecondInterval;
     /** Whether the snapshotter and autoscaling intervals are currently running. */
-    running = false;
+    #running = false;
     /** The in-flight (or completed) startup, memoized so concurrent `start()` calls await one boot. */
-    startPromise;
+    #startPromise;
     /** Set once per session, so a pool outliving `stop()` is reported once rather than every half second. */
-    warnedAboutQueryWhileStopped = false;
+    #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;
+        const { maxConcurrency, minConcurrency, desiredConcurrency, desiredConcurrencyRatio, scaleUpStepRatio, scaleDownStepRatio, loggingIntervalSecs, autoscaleIntervalSecs, loadSignals, snapshotHistorySecs, currentHistorySecs, log, maxTasksPerMinute, } = parseArgument(options, concurrencySystemOptionsSchema, 'ConcurrencySystemOptions');
         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.#loggingIntervalMillis = (loggingIntervalSecs ?? 0) * 1000;
+        this.#autoscaleIntervalMillis = autoscaleIntervalSecs * 1000;
         this.maxTasksPerMinute = maxTasksPerMinute;
-        this._minConcurrency = minConcurrency;
-        this._maxConcurrency = maxConcurrency;
-        this._desiredConcurrency = desiredConcurrency ?? minConcurrency;
+        this.#minConcurrency = minConcurrency;
+        this.#maxConcurrency = maxConcurrency;
+        this.#desiredConcurrency = desiredConcurrency ?? minConcurrency;
         this.clampDesiredConcurrency();
-        this._autoscale = this._autoscale.bind(this);
-        this._incrementTasksDonePerSecond = this._incrementTasksDonePerSecond.bind(this);
+        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.#loadSignals = customLoadSignals;
         this.systemStatus = new SystemStatus({
             snapshotter: this.snapshotter,
             loadSignals: customLoadSignals,
@@ -89,7 +101,7 @@ export class ConcurrencySystem {
      * Gets the minimum number of tasks running in parallel.
      */
     get minConcurrency() {
-        return this._minConcurrency;
+        return this.#minConcurrency;
     }
     /**
      * Sets the minimum number of tasks running in parallel.
@@ -98,15 +110,15 @@ export class ConcurrencySystem {
      * 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;
+        parseArgument(value, concurrencySchema);
+        this.#minConcurrency = value;
         this.clampDesiredConcurrency();
     }
     /**
      * Gets the maximum number of tasks running in parallel.
      */
     get maxConcurrency() {
-        return this._maxConcurrency;
+        return this.#maxConcurrency;
     }
     /**
      * Sets the maximum number of tasks running in parallel. Lowering it below the current
@@ -115,8 +127,8 @@ export class ConcurrencySystem {
      * limit as they settle).
      */
     set maxConcurrency(value) {
-        ow(value, ow.optional.number.integer.greaterThanOrEqual(1));
-        this._maxConcurrency = value;
+        parseArgument(value, concurrencySchema);
+        this.#maxConcurrency = value;
         this.clampDesiredConcurrency();
     }
     /**
@@ -124,15 +136,15 @@ export class ConcurrencySystem {
      * which is an estimated number of parallel tasks that the system can currently support.
      */
     get desiredConcurrency() {
-        return this._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;
+        parseArgument(value, concurrencySchema);
+        this.#desiredConcurrency = value;
         this.clampDesiredConcurrency();
     }
     /**
@@ -142,15 +154,15 @@ export class ConcurrencySystem {
      * 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);
+        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;
+        return this.#running;
     }
     /**
      * Boots the underlying snapshotter and the autoscaling interval. Idempotent, so a shared system isn't restarted
@@ -160,52 +172,52 @@ export class ConcurrencySystem {
     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;
+        this.#startPromise ??= this.boot().catch(async (error) => {
+            this.#startPromise = undefined;
             await this.shutDown();
             throw error;
         });
-        await this.startPromise;
+        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;
+        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);
+        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);
+            this.#tasksDonePerSecondInterval = betterSetInterval(this.incrementTasksDonePerSecond, 1000);
         }
         // Last, so `isRunning` never claims a system whose signals aren't collecting yet.
-        this.running = true;
+        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) {
+        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.#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);
+        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()));
+        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
@@ -214,10 +226,10 @@ export class ConcurrencySystem {
      * `desiredConcurrency` are frozen at that point, so the borrowing pool would otherwise just quietly mis-scale.
      */
     warnIfNotRunning() {
-        if (this.running || this.warnedAboutQueryWhileStopped) {
+        if (this.#running || this.#warnedAboutQueryWhileStopped) {
             return;
         }
-        this.warnedAboutQueryWhileStopped = true;
+        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 ' +
@@ -232,13 +244,13 @@ export class ConcurrencySystem {
      */
     hasCapacityForTask(_consumer) {
         this.warnIfNotRunning();
-        if (this._currentConcurrency >= this._desiredConcurrency) {
+        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) {
+        if (!isSystemIdle && this._currentConcurrency >= this.#minConcurrency) {
             this.log.perf('Task will not be run. System is overloaded.', currentStatus);
             return false;
         }
@@ -249,7 +261,7 @@ export class ConcurrencySystem {
         if (this.maxTasksPerMinute === Infinity) {
             return false;
         }
-        return this._tasksPerMinute.reduce((acc, curr) => acc + curr, 0) >= this.maxTasksPerMinute;
+        return this.#tasksPerMinute.reduce((acc, curr) => acc + curr, 0) >= this.maxTasksPerMinute;
     }
     /**
      * Atomically books a task against the shared budget: re-checks
@@ -269,7 +281,7 @@ export class ConcurrencySystem {
             return false;
         }
         this._currentConcurrency++;
-        this._tasksPerMinute[0]++;
+        this.#tasksPerMinute[0]++;
         return true;
     }
     /** Returns a slot to the shared budget, whoever booked it. */
@@ -288,30 +300,30 @@ export class ConcurrencySystem {
      * 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) {
+    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 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);
+            this.scaleUp(systemStatus);
         const isSystemOverloaded = !isSystemIdle;
-        const weAreNotAtMin = this._desiredConcurrency > this._minConcurrency;
+        const weAreNotAtMin = this.#desiredConcurrency > this.#minConcurrency;
         if (isSystemOverloaded && weAreNotAtMin)
-            this._scaleDown(systemStatus);
-        if (this.loggingIntervalMillis > 0) {
+            this.scaleDown(systemStatus);
+        if (this.#loggingIntervalMillis > 0) {
             const now = Date.now();
-            if (this.lastLoggingTime == null) {
-                this.lastLoggingTime = now;
+            if (this.#lastLoggingTime == null) {
+                this.#lastLoggingTime = now;
             }
-            else if (now > this.lastLoggingTime + this.loggingIntervalMillis) {
-                this.lastLoggingTime = now;
+            else if (now > this.#lastLoggingTime + this.#loggingIntervalMillis) {
+                this.#lastLoggingTime = now;
                 this.log.info('state', {
                     currentConcurrency: this._currentConcurrency,
-                    desiredConcurrency: this._desiredConcurrency,
+                    desiredConcurrency: this.#desiredConcurrency,
                     systemStatus,
                 });
             }
@@ -321,30 +333,30 @@ export class ConcurrencySystem {
     /**
      * 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);
+    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,
+            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);
+    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,
+            oldConcurrency: this.#desiredConcurrency + step,
+            newConcurrency: this.#desiredConcurrency,
             systemStatus,
         });
     }
-    _incrementTasksDonePerSecond(intervalCallback) {
-        this._tasksPerMinute.unshift(0);
-        this._tasksPerMinute.pop();
+    incrementTasksDonePerSecond(intervalCallback) {
+        this.#tasksPerMinute.unshift(0);
+        this.#tasksPerMinute.pop();
         return intervalCallback();
     }
 }

package/autoscaling/cpu_load_signal.d.ts

@@ -31,10 +31,9 @@ export interface CpuLoadSignalOptions {
  * @category Scaling
  */
 export declare class CpuLoadSignal implements LoadSignal {
+    #private;
     readonly name = "cpuInfo";
     readonly overloadedRatio: number;
-    private readonly store;
-    private events?;
     constructor(options?: CpuLoadSignalOptions);
     start(context: LoadSignalStartContext): Promise<void>;
     stop(): Promise<void>;

package/autoscaling/cpu_load_signal.js

@@ -1,3 +1,4 @@
+import { EventType } from '../events/event_manager.js';
 import { serviceLocator } from '../service_locator.js';
 import { SnapshotStore } from './load_signal.js';
 /**
@@ -11,33 +12,33 @@ import { SnapshotStore } from './load_signal.js';
 export class CpuLoadSignal {
     name = 'cpuInfo';
     overloadedRatio;
-    store = new SnapshotStore();
-    events;
+    #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);
+        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();
+        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);
+        this.#events = serviceLocator.getEventManager();
+        this.#events.on(EventType.SYSTEM_INFO, this.handle);
     }
     async stop() {
-        this.events?.off("systemInfo" /* EventType.SYSTEM_INFO */, this.handle);
-        this.events = undefined;
+        this.#events?.off(EventType.SYSTEM_INFO, this.handle);
+        this.#events = undefined;
     }
     getSample(sampleDurationMillis) {
-        return this.store.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({
+        this.#store.push({
             createdAt,
             isOverloaded: isCpuOverloaded,
             usedRatio: Math.ceil(cpuCurrentUsage / 100),

package/autoscaling/event_loop_load_signal.d.ts

@@ -36,12 +36,9 @@ export interface EventLoopLoadSignalOptions {
  * @category Scaling
  */
 export declare class EventLoopLoadSignal implements LoadSignal {
+    #private;
     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>;

package/autoscaling/event_loop_load_signal.js

@@ -10,30 +10,30 @@ import { SnapshotStore } from './load_signal.js';
 export class EventLoopLoadSignal {
     name = 'eventLoopInfo';
     overloadedRatio;
-    store = new SnapshotStore();
-    intervalMillis;
-    maxBlockedMillis;
-    interval;
+    #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.#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);
+        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);
+        this.#store.clear();
+        this.#interval = betterSetInterval(this.handle, this.#intervalMillis);
     }
     async stop() {
-        if (this.interval)
-            betterClearInterval(this.interval);
-        this.interval = undefined;
+        if (this.#interval)
+            betterClearInterval(this.#interval);
+        this.#interval = undefined;
     }
     getSample(sampleDurationMillis) {
-        return this.store.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.
@@ -46,15 +46,15 @@ export class EventLoopLoadSignal {
             isOverloaded: false,
             exceededMillis: 0,
         };
-        const all = this.store.getAll();
+        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)
+            const delta = now.getTime() - +previousSnapshot.createdAt - this.#intervalMillis;
+            if (delta > this.#maxBlockedMillis)
                 snapshot.isOverloaded = true;
-            snapshot.exceededMillis = Math.max(delta - this.maxBlockedMillis, 0);
+            snapshot.exceededMillis = Math.max(delta - this.#maxBlockedMillis, 0);
         }
-        this.store.push(snapshot, now);
+        this.#store.push(snapshot, now);
         intervalCallback();
     }
 }

package/autoscaling/index.d.ts

@@ -1,9 +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 './storage_backend_load_signal.js';
 export * from './system_status.js';

package/autoscaling/index.js

@@ -1,9 +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 './storage_backend_load_signal.js';
 export * from './system_status.js';

package/autoscaling/load_signal.d.ts

@@ -1,4 +1,4 @@
-import type { ClientInfo } from './system_status.js';
+import type { LoadSignalInfo } from './system_status.js';
 /**
  * A snapshot of a resource's overload state at a point in time.
  */
@@ -22,7 +22,7 @@ export interface LoadSignalStartContext {
  * 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
+ * The built-in signals cover memory, CPU, event loop and storage backend 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
@@ -32,8 +32,8 @@ 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.
+     * `eventLoopInfo`, `cpuInfo`, `storageBackendInfo`) land in the correspondingly named `SystemInfo` fields rather
+     * than the `loadSignalInfo` bag; taking one over means switching that built-in off.
      */
     readonly name: string;
     /**
@@ -60,7 +60,7 @@ export interface LoadSignal {
  * and so can yours — it is the only part of their machinery worth reusing.
  */
 export declare class SnapshotStore<T extends LoadSnapshot = LoadSnapshot> {
-    private snapshots;
+    #private;
     /** Retention window in milliseconds. Unbounded until {@link SnapshotStore.useSampleWindow|`useSampleWindow()`}. */
     private historyMillis;
     /**
@@ -79,7 +79,8 @@ export declare class SnapshotStore<T extends LoadSnapshot = LoadSnapshot> {
     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).
+     * to compute a delta (e.g. the event loop and storage backend signals read the last entry to measure change since
+     * it).
      */
     getAll(): T[];
     /**
@@ -96,4 +97,4 @@ export declare class SnapshotStore<T extends LoadSnapshot = LoadSnapshot> {
  * evaluation logic used by `SystemStatus` for all signal types.
  * @internal
  */
-export declare function evaluateLoadSignalSample(sample: LoadSnapshot[], overloadedRatio: number): ClientInfo;
+export declare function evaluateLoadSignalSample(sample: LoadSnapshot[], overloadedRatio: number): LoadSignalInfo;