refactor(core)!: drop EventEmitter dependency from SessionPool

SessionPool no longer extends EventEmitter and no longer fires a
sessionRetired event. The Session->SessionPool back-reference, the
sessionPool constructor option on Session, and the EVENT_SESSION_RETIRED
constant are gone with it. The only consumer of that event was the
browser crawler, which now retires browsers via the per-request context
pipeline cleanup. Custom createSessionFunction implementations that
manually constructed Session instances should drop the sessionPool
argument.

Author: barjin

docs/upgrading/upgrading_v4.md

@@ -127,16 +127,37 @@ new SessionPool({
 ```typescript
 new SessionPool({
     sessionOptions: { maxUsageCount: 5 },
-    createSessionFunction: async (pool, opts) =>
+    createSessionFunction: async (_pool, opts) =>
         new Session({
             ...opts?.sessionOptions, // already merged with pool-wide defaults
-            sessionPool: pool,
         }),
 });
 ```
 
 If you were already spreading `pool.sessionOptions`, the change is harmless - pool defaults now appear twice in the spread chain, with the later (per-call) one winning, exactly as before.
 
+## `Session` no longer requires a `sessionPool` reference
+
+`Session` no longer holds a back-reference to its `SessionPool` and no longer emits a `sessionRetired` event when retired. The `sessionPool` constructor option is gone, `SessionPool` is no longer an `EventEmitter`, and the `EVENT_SESSION_RETIRED` constant is no longer exported. Custom `createSessionFunction` implementations that constructed `Session` instances manually should drop the `sessionPool` argument.
+
+**Before:**
+```typescript
+new SessionPool({
+    createSessionFunction: async (pool, opts) =>
+        new Session({ ...opts?.sessionOptions, sessionPool: pool }),
+});
+```
+
+**After:**
+```typescript
+new SessionPool({
+    createSessionFunction: async (_pool, opts) =>
+        new Session({ ...opts?.sessionOptions }),
+});
+```
+
+If you previously subscribed to `sessionRetired` on the pool to clean up resources tied to a session, perform the cleanup at the end of your request handler (or via a context-pipeline cleanup hook) by checking `session.isUsable()` instead. `Session.retire()` is now a terminal state — once retired, `isUsable()` returns `false` permanently and cannot be undone by a subsequent `markGood()`.
+
 ## `retireOnBlockedStatusCodes` is removed from `Session`
 
 `Session.retireOnBlockedStatusCodes` is removed. Blocked status code handling is now internal to the crawler. Configure blocked status codes via the `blockedStatusCodes` crawler option (moved from `sessionPoolOptions`).

packages/basic-crawler/src/internals/basic-crawler.ts

@@ -869,15 +869,13 @@ export class BasicCrawler<
             this.sessionPool =
                 sessionPool ??
                 new SessionPool({
-                    createSessionFunction: async (pool, opts) =>
+                    createSessionFunction: async (_pool, opts) =>
                         new Session({
                             ...opts?.sessionOptions,
                             proxyInfo:
                                 opts?.sessionOptions?.proxyInfo ?? (await this.proxyConfiguration?.newProxyInfo()),
-                            sessionPool: pool,
                         }),
                 });
-            this.sessionPool.setMaxListeners(20);
 
             this.ownsSessionPool = !sessionPool;
 

packages/core/src/session_pool/events.ts

@@ -1,5 +1,4 @@
 export * from './errors.js';
-export * from './events.js';
 export * from './session.js';
 export * from './session_pool.js';
 export * from './consts.js';

packages/core/src/session_pool/index.ts

@@ -1,5 +1,3 @@
-import { EventEmitter } from 'node:events';
-
 import type { Cookie as CookieObject, Dictionary, ISession, ProxyInfo, SessionState } from '@crawlee/types';
 import ow from 'ow';
 import type { Cookie } from 'tough-cookie';
@@ -15,7 +13,6 @@ import {
 } from '../cookie_utils.js';
 import type { CrawleeLogger } from '../log.js';
 import { serviceLocator } from '../service_locator.js';
-import { EVENT_SESSION_RETIRED } from './events.js';
 
 export interface SessionOptions {
     /** Id of session used for generating fingerprints. It is used as proxy session name. */
@@ -66,9 +63,6 @@ export interface SessionOptions {
      */
     maxUsageCount?: number;
 
-    /** SessionPool instance. Session will emit the `sessionRetired` event on this instance. */
-    sessionPool?: import('./session_pool.js').SessionPool;
-
     log?: CrawleeLogger;
     errorScore?: number;
     cookieJar?: CookieJar;
@@ -91,7 +85,6 @@ export class Session implements ISession {
     private _expiresAt: Date;
     private _usageCount: number;
     private _maxUsageCount: number;
-    private sessionPool: import('./session_pool.js').SessionPool;
     private _errorScore: number;
     private _retired = false;
     private _proxyInfo?: ProxyInfo;
@@ -137,11 +130,10 @@ export class Session implements ISession {
     /**
      * Session configuration.
      */
-    constructor(options: SessionOptions) {
+    constructor(options: SessionOptions = {}) {
         ow(
             options,
             ow.object.exactShape({
-                sessionPool: ow.object.instanceOf(EventEmitter),
                 id: ow.optional.string,
                 cookieJar: ow.optional.object,
                 proxyInfo: ow.optional.object,
@@ -159,7 +151,6 @@ export class Session implements ISession {
         );
 
         const {
-            sessionPool,
             id = `session_${cryptoRandomObjectId(10)}`,
             cookieJar = new CookieJar(),
             proxyInfo = undefined,
@@ -192,7 +183,6 @@ export class Session implements ISession {
         this._usageCount = usageCount; // indicates how many times the session has been used
         this._errorScore = errorScore; // indicates number of markBaded request with the session
         this._maxUsageCount = maxUsageCount;
-        this.sessionPool = sessionPool;
     }
 
     /**
@@ -273,9 +263,6 @@ export class Session implements ISession {
         this._errorScore += this._maxErrorScore;
         this._usageCount += 1;
         this._retired = true;
-
-        // emit event so we can retire browser in puppeteer pool
-        this.sessionPool.emit(EVENT_SESSION_RETIRED, this);
     }
 
     /**

packages/core/src/session_pool/session.ts

@@ -1,5 +1,3 @@
-import { EventEmitter } from 'node:events';
-
 import type { Dictionary } from '@crawlee/types';
 import { AsyncQueue } from '@sapphire/async-queue';
 import ow from 'ow';
@@ -132,7 +130,7 @@ export interface SessionPoolOptions {
  *
  * @category Scaling
  */
-export class SessionPool extends EventEmitter {
+export class SessionPool {
     private static nextId = 0;
 
     readonly id: string;
@@ -155,8 +153,6 @@ export class SessionPool extends EventEmitter {
     private roundRobinIndex = 0;
 
     constructor(options: SessionPoolOptions = {}) {
-        super();
-
         ow(
             options,
             ow.object.exactShape({
@@ -453,16 +449,13 @@ export class SessionPool extends EventEmitter {
      * @returns New session.
      */
     protected async _defaultCreateSessionFunction(
-        sessionPool: SessionPool,
+        _sessionPool: SessionPool,
         options: { sessionOptions?: SessionOptions } = {},
     ): Promise<Session> {
         ow(options, ow.object.exactShape({ sessionOptions: ow.optional.object }));
         const { sessionOptions = {} } = options;
 
-        return new Session({
-            ...sessionOptions,
-            sessionPool,
-        });
+        return new Session(sessionOptions);
     }
 
     /**
@@ -532,7 +525,6 @@ export class SessionPool extends EventEmitter {
         });
 
         for (const sessionObject of loadedSessionPool.sessions) {
-            sessionObject.sessionPool = this;
             sessionObject.createdAt = new Date(sessionObject.createdAt as string);
             sessionObject.expiresAt = new Date(sessionObject.expiresAt as string);
             const recreatedSession = await this._invokeCreateSessionFunction(sessionObject);

packages/core/src/session_pool/session_pool.ts

@@ -331,8 +331,8 @@ describe('PuppeteerCrawler', () => {
 
             saveResponseCookies: true,
             sessionPool: new SessionPool({
-                createSessionFunction: (sessionPool) => {
-                    const session = new Session({ sessionPool });
+                createSessionFunction: () => {
+                    const session = new Session();
                     session.setCookies(cookies, serverUrl);
                     return session;
                 },

test/core/crawlers/puppeteer_crawler.test.ts

@@ -1,15 +1,13 @@
-import { EVENT_SESSION_RETIRED, log, Session, SessionPool } from '@crawlee/core';
+import { log, Session } from '@crawlee/core';
 import { ResponseWithUrl } from '@crawlee/http-client';
 import { entries, sleep } from '@crawlee/utils';
 import { CookieJar } from 'tough-cookie';
 
 describe('Session - testing session behaviour', () => {
-    let sessionPool: SessionPool;
     let session: Session;
 
     beforeEach(() => {
-        sessionPool = new SessionPool();
-        session = new Session({ sessionPool });
+        session = new Session();
     });
 
     test('should markGood session and lower the errorScore', () => {
@@ -24,20 +22,14 @@ describe('Session - testing session behaviour', () => {
         expect(session.errorScore).toBe(0.5);
     });
 
-    test('should throw error when param sessionPool is not EventEmitter instance', () => {
-        const err = 'Expected property object `sessionPool` `{}` to be of type `EventEmitter` in object';
-        // @ts-expect-error JS-side validation
-        expect(() => new Session({ sessionPool: {} })).toThrow(err);
-    });
-
     test('should mark session markBad', () => {
         session.markBad();
         expect(session.errorScore).toBe(1);
         expect(session.usageCount).toBe(1);
     });
 
     test('should expire session', async () => {
-        session = new Session({ maxAgeSecs: 1 / 100, sessionPool });
+        session = new Session({ maxAgeSecs: 1 / 100 });
         await sleep(101);
         expect(session.isExpired()).toBe(true);
         expect(session.isUsable()).toBe(false);
@@ -81,13 +73,7 @@ describe('Session - testing session behaviour', () => {
     });
 
     test('should retire session', () => {
-        let discarded = false;
-        sessionPool.on(EVENT_SESSION_RETIRED, (ses) => {
-            expect(ses instanceof Session).toBe(true);
-            discarded = true;
-        });
         session.retire();
-        expect(discarded).toBe(true);
         expect(session.usageCount).toBe(1);
         expect(session.isUsable()).toBe(false);
     });
@@ -160,7 +146,7 @@ describe('Session - testing session behaviour', () => {
     });
 
     test('should use cookieJar', () => {
-        session = new Session({ sessionPool });
+        session = new Session();
         expect(session.cookieJar.setCookie).toBeDefined();
     });
 
@@ -171,7 +157,7 @@ describe('Session - testing session behaviour', () => {
             { name: 'cookie2', value: 'your-cookie' },
         ];
 
-        session = new Session({ sessionPool });
+        session = new Session();
         session.setCookies(cookies, url);
         expect(session.getCookieString(url)).toBe('cookie1=my-cookie; cookie2=your-cookie');
     });
@@ -180,7 +166,7 @@ describe('Session - testing session behaviour', () => {
         const url = 'https://example.com';
         const cookies = [{ name: 'session_cookie', value: 'session-cookie-value', expires: -1 }];
 
-        session = new Session({ sessionPool });
+        session = new Session();
         session.setCookies(cookies, url);
         expect(session.getCookieString(url)).toBe('session_cookie=session-cookie-value');
     });
@@ -192,7 +178,7 @@ describe('Session - testing session behaviour', () => {
             { name: 'cookie2', value: 'your-cookie', domain: '.example.com' },
         ];
 
-        session = new Session({ sessionPool });
+        session = new Session();
         session.setCookies(cookies, url);
         expect(session.getCookieString(url)).toBe('cookie2=your-cookie');
     });
@@ -206,14 +192,14 @@ describe('Session - testing session behaviour', () => {
             spy: true,
         });
 
-        session = new Session({ sessionPool, log: mockedLog } as any);
+        session = new Session({ log: mockedLog } as any);
         session.setCookies(cookies, url);
         expect(session.getCookieString(url)).toBe('');
         expect(mockedLog.warning).toHaveBeenCalledOnce();
     });
 
     test('setCookie does not throw on malformed raw cookie string', () => {
-        session = new Session({ sessionPool });
+        session = new Session();
         expect(() => session.setCookie('garbled!!!@#$%nonsense', 'https://www.example.com')).not.toThrow();
     });
 
@@ -224,7 +210,7 @@ describe('Session - testing session behaviour', () => {
             { name: 'cookie2', value: 'your-cookie', domain: 'example.com' },
         ];
 
-        session = new Session({ sessionPool });
+        session = new Session();
         session.setCookies(cookies, url);
         expect(session.getCookieString(url)).toBe('');
         expect(session.getCookieString('https://example.com')).toBe('cookie2=your-cookie');
@@ -234,7 +220,6 @@ describe('Session - testing session behaviour', () => {
         const url = 'https://www.example.com';
 
         session = new Session({
-            sessionPool,
             cookieJar: CookieJar.fromJSON(
                 JSON.stringify({
                     cookies: [
@@ -264,7 +249,6 @@ describe('Session - testing session behaviour', () => {
         const url = 'https://www.example.com';
 
         session = new Session({
-            sessionPool,
             cookieJar: CookieJar.fromJSON(
                 JSON.stringify({
                     cookies: [
@@ -297,7 +281,7 @@ describe('Session - testing session behaviour', () => {
             headers.append('set-cookie', 'CSRF=e8b667; Domain=example.com; Secure ');
             headers.append('set-cookie', 'id=a3fWa; Expires=Wed, Domain=example.com; 21 Oct 2015 07:28:00 GMT');
 
-            const newSession = new Session({ sessionPool: new SessionPool() });
+            const newSession = new Session();
             const url = 'https://example.com';
             newSession.setCookiesFromResponse(new ResponseWithUrl('', { headers, url }));
             let cookies = newSession.getCookieString(url);
@@ -317,7 +301,7 @@ describe('Session - testing session behaviour', () => {
         headers.append('set-cookie', 'CSRF=e8b667; Domain=example.com; Secure ');
         headers.append('set-cookie', 'id=a3fWa; Expires=Wed, Domain=example.com; 21 Oct 2015 07:28:00 GMT');
 
-        const newSession = new Session({ sessionPool: new SessionPool() });
+        const newSession = new Session();
         const url = 'https://example.com';
         newSession.setCookiesFromResponse(new ResponseWithUrl('', { headers, url }));
 
@@ -329,7 +313,7 @@ describe('Session - testing session behaviour', () => {
         old.expiresAt = new Date(old.expiresAt);
 
         // @ts-expect-error string -> Date for createdAt has been overridden
-        const reinitializedSession = new Session({ sessionPool, ...old });
+        const reinitializedSession = new Session({ ...old });
         expect(reinitializedSession.getCookieString(url)).toEqual('CSRF=e8b667; id=a3fWa');
     });
 });

test/core/session_pool/session.test.ts

@@ -69,8 +69,6 @@ describe('SessionPool - testing session pool', () => {
             expect(session.maxAgeSecs).toEqual(sessionPool.sessionOptions.maxAgeSecs);
             // @ts-expect-error Accessing private property
             expect(session.maxUsageCount).toEqual(sessionPool.sessionOptions.maxUsageCount);
-            // @ts-expect-error Accessing private property
-            expect(session.sessionPool).toEqual(sessionPool);
         });
 
         test('should pick session when pool is full', async () => {
@@ -336,7 +334,7 @@ describe('SessionPool - testing session pool', () => {
         const createSessionFunction = (sessionPool2: SessionPool) => {
             isCalled = true;
             expect(sessionPool2 instanceof SessionPool).toBe(true);
-            return new Session({ sessionPool: sessionPool2 });
+            return new Session();
         };
         const newSessionPool = new SessionPool({ createSessionFunction });
         const session = await newSessionPool.getSession();
@@ -361,7 +359,7 @@ describe('SessionPool - testing session pool', () => {
     });
 
     test('should be able to add session instance and create new session with provided sessionOptions with addSession()', async () => {
-        const session = new Session({ sessionPool, id: 'test-session-instance' });
+        const session = new Session({ id: 'test-session-instance' });
         await sessionPool.addSession(session);
 
         await sessionPool.addSession({ id: 'test-session' });