@crawlee/basic 4.0.0-beta.21 → 4.0.0-beta.211

package/internals/session_pool/session_pool.d.ts

@@ -0,0 +1,244 @@
+import type { CrawleeLogger } from '@crawlee/core';
+import type { ISessionPool, SessionState } from '@crawlee/types';
+import { z } from 'zod';
+import type { PersistenceOptions } from '../crawlers/statistics.js';
+import type { SessionOptions } from './session.js';
+import { Session } from './session.js';
+export type SessionReuseStrategy = 'random' | 'round-robin' | 'use-until-failure';
+declare const persistedSessionPoolState: z.ZodObject<{
+    usableSessionsCount: z.ZodNumber;
+    retiredSessionsCount: z.ZodNumber;
+    sessions: z.ZodArray<z.ZodCustom<SessionState, SessionState>>;
+}, z.core.$strip>;
+/**
+ * The shape of the persisted {@link SessionPool} record, as returned by {@link SessionPool.getState}.
+ * @internal
+ */
+export type SessionPoolPersistedState = z.infer<typeof persistedSessionPoolState>;
+/**
+ * Factory user-function which creates customized {@link Session} instances.
+ */
+export interface CreateSession {
+    /**
+     * @param options.sessionOptions Per-call session options already merged with the pool-wide defaults.
+     */
+    (options?: {
+        sessionOptions?: SessionOptions;
+    }): Session | Promise<Session>;
+}
+export interface SessionPoolOptions {
+    /**
+     * Unique identifier for this session pool instance. Used to generate a unique
+     * persistence key when `persistStateKey` is not provided.
+     * If not provided, an auto-incrementing ID is used.
+     */
+    id?: string | number;
+    /**
+     * Maximum size of the pool. Indicates how many sessions are rotated.
+     * @default 1000
+     */
+    maxPoolSize?: number;
+    /** The configuration options for {@link Session} instances. */
+    sessionOptions?: SessionOptions;
+    /** Name or Id of `KeyValueStore` where is the `SessionPool` state stored. */
+    persistStateKeyValueStoreId?: string;
+    /**
+     * Session pool persists its state under this key in Key value store.
+     * @default CRAWLEE_SESSION_POOL_STATE_{id}
+     */
+    persistStateKey?: string;
+    /**
+     * Custom function that should return a `Session` instance, or a promise resolving to such instance.
+     * Any error thrown from this function will terminate the process. Receives `{ sessionOptions }`
+     * already merged from the pool-wide defaults and the per-call overrides.
+     */
+    createSessionFunction?: CreateSession;
+    /**
+     * Strategy for picking sessions from the pool.
+     * - `'random'` (default): fills the pool up to `maxPoolSize`, then picks a random usable session
+     * - `'round-robin'`: fills the pool up to `maxPoolSize`, then reuses sessions cycling through them in order
+     * - `'use-until-failure'`: always reuses the same session until it is retired, then moves to the next one
+     * @default 'random'
+     */
+    sessionReuseStrategy?: SessionReuseStrategy;
+    /** @internal */
+    log?: CrawleeLogger;
+    /**
+     * Control how and when to persist the state of the session pool.
+     */
+    persistenceOptions?: PersistenceOptions;
+}
+/**
+ * Handles the rotation, creation and persistence of user-like sessions.
+ * Creates a pool of {@link Session} instances, that are randomly rotated.
+ * When some session is marked as blocked, it is removed and new one is created instead (the pool never returns an unusable session).
+ * Learn more in the {@doclink guides/session-management | Session management guide}.
+ *
+ * Session pool is already integrated into crawlers and is always active.
+ * All public methods are lazy-initialized — the pool initializes itself on first use.
+ *
+ * You can configure the pool with many options. See the {@link SessionPoolOptions}.
+ * Session pool is by default persisted in default {@link KeyValueStore}.
+ * If you want to have one pool for all runs you have to specify
+ * {@link SessionPoolOptions.persistStateKeyValueStoreId}.
+ *
+ * **Advanced usage:**
+ *
+ * ```javascript
+ * const sessionPool = new SessionPool({
+ *     maxPoolSize: 25,
+ *     sessionOptions:{
+ *          maxAgeSecs: 10,
+ *          maxUsageCount: 150, // for example when you know that the site blocks after 150 requests.
+ *     },
+ *     persistStateKeyValueStoreId: 'my-key-value-store-for-sessions',
+ *     persistStateKey: 'my-session-pool',
+ * });
+ *
+ * // Get random session from the pool
+ * const session1 = await sessionPool.getSession();
+ * const session2 = await sessionPool.getSession();
+ * const session3 = await sessionPool.getSession();
+ *
+ * // Now you can mark the session either failed or successful
+ *
+ * // Marks session as bad after unsuccessful usage -> it increases error count (soft retire)
+ * session1.markBad()
+ *
+ * // Marks as successful.
+ * session2.markGood()
+ *
+ * // Retires session -> session is removed from the pool
+ * session3.retire()
+ *
+ * ```
+ *
+ * **Default session allocation flow:*
+ * 1. Until the `SessionPool` reaches `maxPoolSize`, new sessions are created, provided to the user and added to the pool
+ * 2. Blocked/retired sessions stay in the pool but are never provided to the user
+ * 3. Once the pool is full (live plus blocked session count reaches `maxPoolSize`), a random session from the pool is provided.
+ * 4. If a blocked session would be picked, instead all blocked sessions are evicted from the pool and a new session is created and provided
+ *
+ * @category Scaling
+ */
+export declare class SessionPool implements ISessionPool {
+    #private;
+    readonly id: string;
+    constructor(options?: SessionPoolOptions);
+    /**
+     * Gets count of usable sessions in the pool.
+     */
+    usableSessionsCount(): Promise<number>;
+    /**
+     * Gets count of retired sessions in the pool.
+     */
+    retiredSessionsCount(): Promise<number>;
+    /**
+     * Starts periodic state persistence and potentially loads SessionPool state from {@link KeyValueStore}.
+     * Called automatically on first use of any public method.
+     */
+    private ensureInitialized;
+    private setupPool;
+    /**
+     * Adds a new session to the session pool. The pool automatically creates sessions up to the maximum size of the pool,
+     * but this allows you to add more sessions once the max pool size is reached.
+     * This also allows you to add session with overridden session options (e.g. with specific session id).
+     *
+     * If the pool already contains a session with the same id, it is replaced when it is no longer usable
+     * (e.g. retired), and an error is thrown otherwise.
+     * @param [options] The configuration options for the session being added to the session pool.
+     */
+    addSession(options?: Session | SessionOptions): Promise<void>;
+    /**
+     * Adds a new session to the session pool. The pool automatically creates sessions up to the maximum size of the pool,
+     * but this allows you to add more sessions once the max pool size is reached.
+     * This also allows you to add session with overridden session options (e.g. with specific session id).
+     * @param [options] The configuration options for the session being added to the session pool.
+     */
+    newSession(sessionOptions?: SessionOptions): Promise<Session>;
+    /**
+     * Gets session.
+     * If there is space for new session, it creates and returns new session.
+     * If the session pool is full, it picks a session from the pool,
+     * If the picked session is usable it is returned, otherwise it creates and returns a new one.
+     * @param [sessionId] If provided, it returns the usable session with this id, `undefined` otherwise.
+     */
+    getSession(sessionId?: string): Promise<Session | undefined>;
+    /**
+     * Discards all sessions in the pool, both usable and retired, resetting it to a blank state.
+     *
+     * The persisted record is left alone - use {@link SessionPool.resetStore} to clear that as well.
+     */
+    reset(): void;
+    /**
+     * Clears the persisted pool record, leaving the in-memory sessions alone.
+     *
+     * Throws while the state is still being persisted periodically - the next PERSIST_STATE event would write
+     * the record straight back. Call {@link SessionPool.teardown} first, or use {@link SessionPool.reset}
+     * to discard the sessions themselves. A no-op if persistence is disabled.
+     */
+    resetStore(): Promise<void>;
+    /**
+     * Returns an object representing the internal state of the `SessionPool` instance.
+     * @internal
+     */
+    getState(): Promise<SessionPoolPersistedState>;
+    /**
+     * Persists the current state of the `SessionPool` into the default {@link KeyValueStore}.
+     * The state is persisted automatically in regular intervals.
+     */
+    persistState(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Stops the periodic state persistence and persists the state one last time.
+     * This function should be called after you are done with using the `SessionPool` instance.
+     * Using the pool again afterwards initializes it anew.
+     */
+    teardown(): Promise<void>;
+    /**
+     * Removes retired `Session` instances from `SessionPool`.
+     */
+    private removeRetiredSessions;
+    /**
+     * Adds `Session` instance to `SessionPool`.
+     * @param newSession `Session` instance to be added.
+     */
+    private registerSession;
+    /**
+     * Gets random index.
+     */
+    private getRandomIndex;
+    /**
+     * Creates new session without any extra behavior.
+     * @param [options]
+     * @param [options.sessionOptions] The configuration options for the session being created.
+     * @returns New session.
+     */
+    private defaultCreateSessionFunction;
+    /**
+     * Invokes `createSessionFunction` with `sessionOptions` already merged from pool-wide defaults and
+     * the supplied per-call overrides, so custom implementations don't need to spread `pool.sessionOptions` themselves.
+     *
+     * A default {@link SessionFingerprint} is generated up front (host OS as
+     * `platform`, a random valid `browser`/`device` for that platform). Pool-wide
+     * and per-call options override it, and a persisted fingerprint coming
+     * through `maybeLoadSessionPool` naturally wins because it arrives in
+     * `perCallOptions`.
+     */
+    private invokeCreateSessionFunction;
+    /**
+     * Creates new session and adds it to the pool.
+     * @returns Newly created `Session` instance.
+     */
+    private createSession;
+    /**
+     * Decides whether there is enough space for creating new session.
+     */
+    private hasSpaceForSession;
+    /**
+     * Picks a session from the `SessionPool` according to the configured `sessionReuseStrategy`.
+     * Returns `undefined` when no session should be reused and a new one should be created instead.
+     */
+    private pickSession;
+}
+export {};

package/internals/session_pool/session_pool.js

@@ -0,0 +1,453 @@
+import { KeyValueStore, RecoverableState, serviceLocator, validators } from '@crawlee/core';
+import { parseArgument, schemas } from '@crawlee/utils/internal';
+import { AsyncQueue } from '@sapphire/async-queue';
+import { z } from 'zod';
+import { createDefaultSessionFingerprint } from './fingerprint.js';
+import { Session } from './session.js';
+/** Default upper bound on the number of sessions the pool keeps around. */
+const MAX_POOL_SIZE = 1000;
+/** Prefix of the default key the pool persists its state under; the pool id is appended to it. */
+const PERSIST_STATE_KEY = 'CRAWLEE_SESSION_POOL_STATE';
+// Runtime mirror of `SessionReuseStrategy` for the zod schema below. Declared this way round - and not as
+// `typeof SESSION_REUSE_STRATEGIES[number]` - so the public type is a plain literal union that does not drag
+// the array into the API surface. `satisfies` keeps the array from naming a strategy the type does not have.
+const SESSION_REUSE_STRATEGIES = [
+    'random',
+    'round-robin',
+    'use-until-failure',
+];
+// `schemas.anyObject` passes values through by reference (object schemas return a pruned plain
+// copy), so class instances like loggers keep their prototype.
+const sessionPoolOptionsSchema = z.strictObject({
+    id: z.union([schemas.anyNumber, z.string()]).optional(),
+    maxPoolSize: schemas.anyNumber.default(MAX_POOL_SIZE),
+    persistStateKeyValueStoreId: z.string().optional(),
+    persistStateKey: z.string().optional(),
+    createSessionFunction: schemas.anyFunction.optional(),
+    sessionOptions: schemas.anyObject.default(() => ({})),
+    log: validators.logger.default(() => serviceLocator.getLogger()),
+    persistenceOptions: schemas.anyObject.default(() => ({ enable: true })),
+    sessionReuseStrategy: z.enum(SESSION_REUSE_STRATEGIES).default('random'),
+});
+const createSessionOptionsSchema = z.strictObject({
+    sessionOptions: schemas.anyObject.default(() => ({})),
+});
+// Only what the recreation reads is pinned down - the rest of a session's state is the session's own business.
+const persistedSessionState = z.custom((value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.createdAt === 'string' &&
+    typeof value.expiresAt === 'string', 'Expected a persisted session with `createdAt` and `expiresAt` timestamps');
+const persistedSessionPoolState = z.object({
+    usableSessionsCount: z.number(),
+    retiredSessionsCount: z.number(),
+    sessions: z.array(persistedSessionState),
+});
+const sessionPoolInternalState = z.object({
+    sessions: z.array(z.instanceof(Session)),
+});
+/**
+ * The conversion between the pool's sessions and its persisted record. Decoding recreates the sessions through
+ * the pool's factory and keeps only the usable ones, which is why the codec is built per pool.
+ */
+function buildSessionPoolStateCodec(pool) {
+    return z.codec(persistedSessionPoolState, sessionPoolInternalState, {
+        decode: async (record) => {
+            const sessions = [];
+            for (const sessionState of record.sessions) {
+                const session = await pool.recreateSession({
+                    ...sessionState,
+                    createdAt: new Date(sessionState.createdAt),
+                    expiresAt: new Date(sessionState.expiresAt),
+                });
+                if (session.isUsable()) {
+                    sessions.push(session);
+                }
+            }
+            pool.log.debug(`${sessions.length} active sessions loaded from KeyValueStore`);
+            return { sessions };
+        },
+        encode: ({ sessions }) => pool.toRecord(sessions),
+    });
+}
+/**
+ * Handles the rotation, creation and persistence of user-like sessions.
+ * Creates a pool of {@link Session} instances, that are randomly rotated.
+ * When some session is marked as blocked, it is removed and new one is created instead (the pool never returns an unusable session).
+ * Learn more in the {@doclink guides/session-management | Session management guide}.
+ *
+ * Session pool is already integrated into crawlers and is always active.
+ * All public methods are lazy-initialized — the pool initializes itself on first use.
+ *
+ * You can configure the pool with many options. See the {@link SessionPoolOptions}.
+ * Session pool is by default persisted in default {@link KeyValueStore}.
+ * If you want to have one pool for all runs you have to specify
+ * {@link SessionPoolOptions.persistStateKeyValueStoreId}.
+ *
+ * **Advanced usage:**
+ *
+ * ```javascript
+ * const sessionPool = new SessionPool({
+ *     maxPoolSize: 25,
+ *     sessionOptions:{
+ *          maxAgeSecs: 10,
+ *          maxUsageCount: 150, // for example when you know that the site blocks after 150 requests.
+ *     },
+ *     persistStateKeyValueStoreId: 'my-key-value-store-for-sessions',
+ *     persistStateKey: 'my-session-pool',
+ * });
+ *
+ * // Get random session from the pool
+ * const session1 = await sessionPool.getSession();
+ * const session2 = await sessionPool.getSession();
+ * const session3 = await sessionPool.getSession();
+ *
+ * // Now you can mark the session either failed or successful
+ *
+ * // Marks session as bad after unsuccessful usage -> it increases error count (soft retire)
+ * session1.markBad()
+ *
+ * // Marks as successful.
+ * session2.markGood()
+ *
+ * // Retires session -> session is removed from the pool
+ * session3.retire()
+ *
+ * ```
+ *
+ * **Default session allocation flow:*
+ * 1. Until the `SessionPool` reaches `maxPoolSize`, new sessions are created, provided to the user and added to the pool
+ * 2. Blocked/retired sessions stay in the pool but are never provided to the user
+ * 3. Once the pool is full (live plus blocked session count reaches `maxPoolSize`), a random session from the pool is provided.
+ * 4. If a blocked session would be picked, instead all blocked sessions are evicted from the pool and a new session is created and provided
+ *
+ * @category Scaling
+ */
+export class SessionPool {
+    static #nextId = 0;
+    id;
+    #log;
+    #maxPoolSize;
+    #createSessionFunction;
+    #sessionMap = new Map();
+    #sessionOptions;
+    #persistStateKeyValueStoreId;
+    #persistStateKey;
+    #persistenceOptions;
+    #sessionReuseStrategy;
+    /**
+     * The sessions live in a {@link RecoverableState} that handles the loading, recreation and periodic
+     * persistence of the record under `persistStateKey`.
+     */
+    #state;
+    #stateCodec;
+    #initPromise;
+    #queue = new AsyncQueue();
+    #roundRobinIndex = 0;
+    constructor(options = {}) {
+        const { id, maxPoolSize, persistStateKeyValueStoreId, persistStateKey, createSessionFunction, sessionOptions, log, persistenceOptions, sessionReuseStrategy, } = parseArgument(options, sessionPoolOptionsSchema);
+        this.id = id != null ? String(id) : String(SessionPool.#nextId++);
+        this.#sessionReuseStrategy = sessionReuseStrategy;
+        this.#log = log.child({ prefix: 'SessionPool' });
+        this.#persistenceOptions = persistenceOptions;
+        // Pool Configuration
+        this.#maxPoolSize = maxPoolSize;
+        this.#createSessionFunction = createSessionFunction || this.defaultCreateSessionFunction;
+        // Session configuration. The pool-scoped logger is merged into per-call sessionOptions inside
+        // `invokeCreateSessionFunction`, so every Session inherits it without custom createSessionFunctions
+        // having to know about it.
+        this.#sessionOptions = {
+            ...sessionOptions,
+            log: this.#log,
+        };
+        // Session keyValueStore
+        this.#persistStateKeyValueStoreId = persistStateKeyValueStoreId;
+        this.#persistStateKey = persistStateKey ?? `${PERSIST_STATE_KEY}_${this.id}`;
+        this.#stateCodec = buildSessionPoolStateCodec({
+            recreateSession: (sessionState) => this.invokeCreateSessionFunction(sessionState),
+            toRecord: (sessions) => this.#buildPersistedState(sessions),
+            log: this.#log,
+        });
+        this.#state = new RecoverableState({
+            defaultState: () => ({ sessions: [] }),
+            persistStateKey: this.#persistStateKey,
+            persistenceEnabled: !!this.#persistenceOptions.enable,
+            logger: this.#log,
+            keyValueStore: this.#persistenceOptions.enable && persistStateKeyValueStoreId
+                ? KeyValueStore.open({ id: persistStateKeyValueStoreId }, { configuration: serviceLocator.getConfiguration() })
+                : undefined,
+            // The codec validates in the decode direction, so it is a Standard Schema as-is; encoding needs a call.
+            deserialize: this.#stateCodec,
+            serialize: (state) => this.#stateCodec.encode(state),
+        });
+        this.#state.reset();
+    }
+    /**
+     * Gets count of usable sessions in the pool.
+     */
+    async usableSessionsCount() {
+        await this.ensureInitialized();
+        return this.#state.currentValue.sessions.filter((session) => session.isUsable()).length;
+    }
+    /**
+     * Gets count of retired sessions in the pool.
+     */
+    async retiredSessionsCount() {
+        await this.ensureInitialized();
+        return this.#state.currentValue.sessions.filter((session) => !session.isUsable()).length;
+    }
+    /**
+     * Starts periodic state persistence and potentially loads SessionPool state from {@link KeyValueStore}.
+     * Called automatically on first use of any public method.
+     */
+    async ensureInitialized() {
+        if (!this.#initPromise) {
+            this.#initPromise = this.setupPool();
+        }
+        return this.#initPromise;
+    }
+    async setupPool() {
+        await this.#state.initialize();
+        for (const session of this.#state.currentValue.sessions) {
+            this.#sessionMap.set(session.id, session);
+        }
+    }
+    /**
+     * Adds a new session to the session pool. The pool automatically creates sessions up to the maximum size of the pool,
+     * but this allows you to add more sessions once the max pool size is reached.
+     * This also allows you to add session with overridden session options (e.g. with specific session id).
+     *
+     * If the pool already contains a session with the same id, it is replaced when it is no longer usable
+     * (e.g. retired), and an error is thrown otherwise.
+     * @param [options] The configuration options for the session being added to the session pool.
+     */
+    async addSession(options = {}) {
+        await this.ensureInitialized();
+        const { id } = options;
+        if (id) {
+            const existingSession = this.#sessionMap.get(id);
+            if (existingSession) {
+                if (existingSession.isUsable()) {
+                    throw new Error(`Cannot add session with id '${id}' as it already exists in the pool`);
+                }
+                this.#removeSession(existingSession);
+            }
+        }
+        if (!this.hasSpaceForSession()) {
+            this.removeRetiredSessions();
+        }
+        const newSession = options instanceof Session ? options : await this.invokeCreateSessionFunction(options);
+        this.#log.debug(`Adding new Session - ${newSession.id}`);
+        this.registerSession(newSession);
+    }
+    /**
+     * Adds a new session to the session pool. The pool automatically creates sessions up to the maximum size of the pool,
+     * but this allows you to add more sessions once the max pool size is reached.
+     * This also allows you to add session with overridden session options (e.g. with specific session id).
+     * @param [options] The configuration options for the session being added to the session pool.
+     */
+    async newSession(sessionOptions) {
+        await this.ensureInitialized();
+        const newSession = await this.invokeCreateSessionFunction(sessionOptions);
+        this.registerSession(newSession);
+        return newSession;
+    }
+    /**
+     * Gets session.
+     * If there is space for new session, it creates and returns new session.
+     * If the session pool is full, it picks a session from the pool,
+     * If the picked session is usable it is returned, otherwise it creates and returns a new one.
+     * @param [sessionId] If provided, it returns the usable session with this id, `undefined` otherwise.
+     */
+    async getSession(sessionId) {
+        await this.ensureInitialized();
+        await this.#queue.wait();
+        try {
+            if (sessionId) {
+                const session = this.#sessionMap.get(sessionId);
+                if (session?.isUsable())
+                    return session;
+                return undefined;
+            }
+            const pickedSession = this.pickSession();
+            if (pickedSession)
+                return pickedSession;
+            if (this.hasSpaceForSession()) {
+                return await this.createSession();
+            }
+            this.removeRetiredSessions();
+            return await this.createSession();
+        }
+        finally {
+            this.#queue.shift();
+        }
+    }
+    /**
+     * Discards all sessions in the pool, both usable and retired, resetting it to a blank state.
+     *
+     * The persisted record is left alone - use {@link SessionPool.resetStore} to clear that as well.
+     */
+    reset() {
+        this.#state.reset();
+        this.#sessionMap.clear();
+        this.#roundRobinIndex = 0;
+    }
+    /**
+     * Clears the persisted pool record, leaving the in-memory sessions alone.
+     *
+     * Throws while the state is still being persisted periodically - the next PERSIST_STATE event would write
+     * the record straight back. Call {@link SessionPool.teardown} first, or use {@link SessionPool.reset}
+     * to discard the sessions themselves. A no-op if persistence is disabled.
+     */
+    async resetStore() {
+        await this.#state.resetStore();
+    }
+    /**
+     * Returns an object representing the internal state of the `SessionPool` instance.
+     * @internal
+     */
+    async getState() {
+        await this.ensureInitialized();
+        return this.#buildPersistedState(this.#state.currentValue.sessions);
+    }
+    /**
+     * Persists the current state of the `SessionPool` into the default {@link KeyValueStore}.
+     * The state is persisted automatically in regular intervals.
+     */
+    async persistState() {
+        if (!this.#persistenceOptions.enable) {
+            return;
+        }
+        await this.ensureInitialized();
+        this.#log.debug('Persisting state', {
+            persistStateKeyValueStoreId: this.#persistStateKeyValueStoreId,
+            persistStateKey: this.#persistStateKey,
+        });
+        await this.#state
+            .persistState()
+            .catch((error) => this.#log.warning(`Failed to persist the session pool stats to ${this.#persistStateKey}`, { error }));
+    }
+    async [Symbol.asyncDispose]() {
+        await this.teardown();
+    }
+    /**
+     * Stops the periodic state persistence and persists the state one last time.
+     * This function should be called after you are done with using the `SessionPool` instance.
+     * Using the pool again afterwards initializes it anew.
+     */
+    async teardown() {
+        if (!this.#initPromise)
+            return;
+        await this.ensureInitialized();
+        await this.#state.teardown();
+        // The next use initializes the pool again, restoring the record and resuming the periodic persistence -
+        // a crawler that is run twice gets a persisting pool both times.
+        this.#initPromise = undefined;
+    }
+    /**
+     * Removes retired `Session` instances from `SessionPool`.
+     */
+    removeRetiredSessions() {
+        this.#state.currentValue.sessions = this.#state.currentValue.sessions.filter((storedSession) => {
+            if (storedSession.isUsable())
+                return true;
+            this.#sessionMap.delete(storedSession.id);
+            this.#log.debug(`Removed Session - ${storedSession.id}`);
+            return false;
+        });
+    }
+    /**
+     * Removes a `Session` instance from `SessionPool`.
+     */
+    #removeSession(session) {
+        this.#state.currentValue.sessions = this.#state.currentValue.sessions.filter((storedSession) => storedSession !== session);
+        this.#sessionMap.delete(session.id);
+        this.#log.debug(`Removed Session - ${session.id}`);
+    }
+    /**
+     * Adds `Session` instance to `SessionPool`.
+     * @param newSession `Session` instance to be added.
+     */
+    registerSession(newSession) {
+        this.#state.currentValue.sessions.push(newSession);
+        this.#sessionMap.set(newSession.id, newSession);
+    }
+    /**
+     * Gets random index.
+     */
+    getRandomIndex() {
+        return Math.floor(Math.random() * this.#state.currentValue.sessions.length);
+    }
+    /**
+     * Creates new session without any extra behavior.
+     * @param [options]
+     * @param [options.sessionOptions] The configuration options for the session being created.
+     * @returns New session.
+     */
+    async defaultCreateSessionFunction(options = {}) {
+        const { sessionOptions } = parseArgument(options, createSessionOptionsSchema);
+        return new Session(sessionOptions);
+    }
+    /**
+     * Invokes `createSessionFunction` with `sessionOptions` already merged from pool-wide defaults and
+     * the supplied per-call overrides, so custom implementations don't need to spread `pool.sessionOptions` themselves.
+     *
+     * A default {@link SessionFingerprint} is generated up front (host OS as
+     * `platform`, a random valid `browser`/`device` for that platform). Pool-wide
+     * and per-call options override it, and a persisted fingerprint coming
+     * through `maybeLoadSessionPool` naturally wins because it arrives in
+     * `perCallOptions`.
+     */
+    async invokeCreateSessionFunction(perCallOptions) {
+        const sessionOptions = {
+            fingerprint: createDefaultSessionFingerprint(),
+            ...this.#sessionOptions,
+            ...perCallOptions,
+        };
+        return this.#createSessionFunction({ sessionOptions });
+    }
+    /**
+     * Creates new session and adds it to the pool.
+     * @returns Newly created `Session` instance.
+     */
+    async createSession() {
+        const newSession = await this.invokeCreateSessionFunction();
+        this.registerSession(newSession);
+        this.#log.debug(`Created new Session - ${newSession.id}`);
+        return newSession;
+    }
+    /**
+     * Decides whether there is enough space for creating new session.
+     */
+    hasSpaceForSession() {
+        return this.#state.currentValue.sessions.length < this.#maxPoolSize;
+    }
+    /**
+     * Picks a session from the `SessionPool` according to the configured `sessionReuseStrategy`.
+     * Returns `undefined` when no session should be reused and a new one should be created instead.
+     */
+    pickSession() {
+        if (this.#sessionReuseStrategy !== 'use-until-failure' && this.hasSpaceForSession())
+            return undefined;
+        if (this.#sessionReuseStrategy === 'use-until-failure') {
+            return this.#state.currentValue.sessions.find((session) => session.isUsable());
+        }
+        let picked;
+        if (this.#sessionReuseStrategy === 'round-robin') {
+            const index = this.#roundRobinIndex % this.#state.currentValue.sessions.length;
+            this.#roundRobinIndex = index + 1;
+            picked = this.#state.currentValue.sessions[index];
+        }
+        else {
+            picked = this.#state.currentValue.sessions[this.getRandomIndex()];
+        }
+        return picked.isUsable() ? picked : undefined;
+    }
+    /** The persisted form of the pool, which is also what {@link SessionPool.getState} returns. */
+    #buildPersistedState(sessions) {
+        return {
+            usableSessionsCount: sessions.filter((session) => session.isUsable()).length,
+            retiredSessionsCount: sessions.filter((session) => !session.isUsable()).length,
+            sessions: sessions.map((session) => session.getState()),
+        };
+    }
+}