feat: session locking

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

@@ -1014,6 +1014,7 @@ export class BasicCrawler<Context extends CrawlingContext = BasicCrawlingContext
             // reclaim session if request finishes successfully
             request.state = RequestState.DONE;
             crawlingContext.session?.markGood();
+            session?.unlockSession();
         } catch (err) {
             try {
                 request.state = RequestState.ERROR_HANDLER;
@@ -1035,6 +1036,7 @@ export class BasicCrawler<Context extends CrawlingContext = BasicCrawlingContext
             }
             // decrease the session score if the request fails (but the error handler did not throw)
             crawlingContext.session?.markBad();
+            session?.unlockSession();
         } finally {
             await this._cleanupContext(crawlingContext);
 

packages/core/src/session_pool/session.ts

@@ -93,6 +93,7 @@ export interface SessionOptions {
  */
 export class Session {
     readonly id: string;
+    private _isLocked = false;
     private maxAgeSecs: number;
     userData: Dictionary;
     private maxErrorScore: number;
@@ -161,6 +162,10 @@ export class Session {
         this.sessionPool = sessionPool;
     }
 
+    isLocked(): boolean {
+        return this._isLocked;
+    }
+
     /**
      * Indicates whether the session is blocked.
      * Session is blocked once it reaches the `maxErrorScore`.
@@ -194,6 +199,23 @@ export class Session {
         return !this.isBlocked() && !this.isExpired() && !this.isMaxUsageCountReached();
     }
 
+    lockSession() {
+        if (this.isLocked()) {
+            throw new Error(`Session ${this.id} is already locked.`);
+        }
+        this._isLocked = true;
+        return this;
+    }
+
+    unlockSession() {
+        if (!this.isLocked()) {
+            throw new Error(`Session ${this.id} is not locked.`);
+        }
+
+        this._isLocked = false;
+        return this;
+    }
+
     /**
      * This method should be called after a successful session usage.
      * It increases `usageCount` and potentially lowers the `errorScore` by the `errorScoreDecrement`.

packages/core/src/session_pool/session_pool.ts

@@ -271,7 +271,7 @@ export class SessionPool extends EventEmitter {
         this._throwIfNotInitialized();
         if (sessionId) {
             const session = this.sessionMap.get(sessionId);
-            if (session && session.isUsable()) return session;
+            if (session && session.isUsable() && !session.isLocked()) return session.lockSession();
             return undefined;
         }
 
@@ -280,8 +280,8 @@ export class SessionPool extends EventEmitter {
         }
 
         const pickedSession = this._pickSession();
-        if (pickedSession.isUsable()) {
-            return pickedSession;
+        if (pickedSession?.isUsable()) {
+            return pickedSession?.lockSession();
         }
 
         this._removeRetiredSessions();
@@ -333,7 +333,7 @@ export class SessionPool extends EventEmitter {
      */
     protected _removeRetiredSessions() {
         this.sessions = this.sessions.filter((storedSession) => {
-            if (storedSession.isUsable()) return true;
+            if (storedSession.isUsable() || storedSession.isLocked()) return true;
 
             this.sessionMap.delete(storedSession.id);
             this.log.debug(`Removed Session - ${storedSession.id}`);
@@ -384,7 +384,7 @@ export class SessionPool extends EventEmitter {
         this._addSession(newSession);
         this.log.debug(`Created new Session - ${newSession.id}`);
 
-        return newSession;
+        return newSession.lockSession();
     }
 
     /**
@@ -398,8 +398,12 @@ export class SessionPool extends EventEmitter {
      * Picks random session from the `SessionPool`.
      * @returns Picked `Session`.
      */
-    protected _pickSession(): Session {
-        return this.sessions[this._getRandomIndex()]; // Or maybe we should let the developer to customize the picking algorithm
+    protected _pickSession(): Session | undefined {
+        const availableSessions = this.sessions.filter((session) => {
+            return session.isUsable() && !session.isLocked();
+        });
+
+        return availableSessions[0];
     }
 
     /**