Session

Sessions are used to store information such as cookies and can be used for generating fingerprints and proxy sessions. You can imagine each session as a specific user, with its own cookies, IP (via proxy) and potentially a unique browser fingerprint. Session internal state can be enriched with custom user data for example some authorization tokens and specific headers in general.

Implements

• ISession

Index

Constructors

• constructor

Properties

• id
• userData

Accessors

• cookieJar
• createdAt
• errorScore
• errorScoreDecrement
• expiresAt
• fingerprint
• maxErrorScore
• maxUsageCount
• proxyInfo
• retired
• usageCount

Methods

• getCookieString
• getState
• isBlocked
• isExpired
• isMaxUsageCountReached
• isUsable
• markBad
• markGood
• retire
• setCookie

Constructors

constructor

• new Session(options): Session

• Session configuration.

  ---

  Parameters

  • options: SessionOptions = {}

  Returns Session

Properties

readonlyid

id: string

Implementation of ISession.id

readonlyuserData

userData: Dictionary

Accessors

cookieJar

• get cookieJar(): CookieJar

• Implementation of ISession.cookieJar

  Returns CookieJar

createdAt

• get createdAt(): Date

• Returns Date

errorScore

• get errorScore(): number

• Returns number

errorScoreDecrement

• get errorScoreDecrement(): number

• Returns number

expiresAt

• get expiresAt(): Date

• Returns Date

fingerprint

• get fingerprint(): undefined | SessionFingerprint
• set fingerprint(fingerprint): void

• Implementation of ISession.fingerprint

  Returns undefined | SessionFingerprint

• Implementation of ISession.fingerprint

  Parameters

  • fingerprint: undefined | SessionFingerprint

  Returns void

maxErrorScore

• get maxErrorScore(): number

• Returns number

maxUsageCount

• get maxUsageCount(): number

• Returns number

proxyInfo

• get proxyInfo(): undefined | ProxyInfo

• Implementation of ISession.proxyInfo

  Returns undefined | ProxyInfo

retired

• get retired(): boolean

• true once retire() has been called. Retirement is terminal: a retired session is never picked by the pool and cannot be revived via markGood().

  ---

  Returns boolean

usageCount

• get usageCount(): number

• Returns number

Methods

getCookieString

• getCookieString(url): Promise<string>

• Returns cookies saved with the session in the typical key1=value1; key2=value2 format, ready to be used in a cookie header or elsewhere.

  ---

  Parameters

  • url: string

  Returns Promise<string>

  Represents Cookie header.

getState

• getState(): SessionState

• Gets session state for persistence in KeyValueStore.

  ---

  Returns SessionState

  Represents session internal state.

isBlocked

• isBlocked(): boolean

• Indicates whether the session is blocked. Session is blocked once it reaches the maxErrorScore.

  ---

  Returns boolean

isExpired

• isExpired(): boolean

• Indicates whether the session is expired. Session expiration is determined by the maxAgeSecs. Once the session is older than createdAt + maxAgeSecs the session is considered expired.

  ---

  Returns boolean

isMaxUsageCountReached

• isMaxUsageCountReached(): boolean

• Indicates whether the session is used maximum number of times. Session maximum usage count can be changed by maxUsageCount parameter.

  ---

  Returns boolean

isUsable

• isUsable(): boolean

• Implementation of ISession.isUsable

  Indicates whether the session can be used for next requests. Session is usable when it is not retired, not expired, not blocked and the maximum usage count has not be reached.

  ---

  Returns boolean

markBad

• markBad(): void

• Implementation of ISession.markBad

  Increases usage and error count. Should be used when the session has been used unsuccessfully. For example because of timeouts.

  ---

  Returns void

markGood

• markGood(): void

• Implementation of ISession.markGood

  This method should be called after a successful session usage. It increases usageCount and potentially lowers the errorScore by the errorScoreDecrement.

  ---

  Returns void

retire

• retire(): void

• Implementation of ISession.retire

  Permanently retires the session — isUsable() will return false from here on, and no markGood() / markBad() can revive it. Calling retire() again is a no-op.

  Use this when you're confident the session itself is the problem (e.g. a 403 response). For transient external failures (such as 5XX responses), use markBad() instead.

  ---

  Returns void

setCookie

• setCookie(rawCookie, url): Promise<void>

• Sets a cookie within this session for the specific URL.

  ---

  Parameters

  • rawCookie: string

  • url: string

  Returns Promise<void>