@crawlee/core 4.0.0-beta.20 → 4.0.0-beta.201

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/core",
-    "version": "4.0.0-beta.20",
+    "version": "4.0.0-beta.201",
     "description": "The scalable web crawling and scraping library for JavaScript/Node.js. Enables development of data extraction and web automation jobs (not only) with headless Chrome and Puppeteer.",
     "engines": {
         "node": ">=22.0.0"
@@ -8,6 +8,7 @@
     "type": "module",
     "exports": {
         ".": "./index.js",
+        "./internal": "./internal.js",
         "./package.json": "./package.json"
     },
     "keywords": [
@@ -38,7 +39,7 @@
     },
     "homepage": "https://crawlee.dev",
     "scripts": {
-        "build": "yarn clean && yarn compile && yarn copy",
+        "build": "pnpm clean && pnpm compile && pnpm copy",
         "clean": "rimraf ./dist",
         "compile": "tsc -p tsconfig.build.json",
         "copy": "tsx ../../scripts/copy.ts"
@@ -47,28 +48,26 @@
         "access": "public"
     },
     "dependencies": {
-        "@apify/consts": "^2.41.0",
-        "@apify/datastructures": "^2.0.3",
-        "@apify/log": "^2.5.18",
-        "@apify/pseudo_url": "^2.0.59",
-        "@apify/timeout": "^0.3.2",
-        "@apify/utilities": "^2.15.5",
-        "@crawlee/memory-storage": "4.0.0-beta.20",
-        "@crawlee/types": "4.0.0-beta.20",
-        "@crawlee/utils": "4.0.0-beta.20",
+        "@apify/consts": "^3.0.1",
+        "@apify/datastructures": "^3.0.1",
+        "@apify/log": "^3.0.1",
+        "@apify/timeout": "^1.0.1",
+        "@apify/utilities": "^3.0.1",
+        "@crawlee/fs-storage": "4.0.0-beta.201",
+        "@crawlee/http-client": "4.0.0-beta.201",
+        "@crawlee/types": "4.0.0-beta.201",
+        "@crawlee/utils": "4.0.0-beta.201",
         "@sapphire/async-queue": "^1.5.5",
+        "@standard-schema/spec": "^1.0.0",
         "@vladfrangu/async_event_emitter": "^2.4.6",
+        "content-type": "^1.0.5",
         "csv-stringify": "^6.5.2",
-        "fs-extra": "^11.3.0",
-        "got-scraping": "^4.1.1",
         "json5": "^2.2.3",
-        "minimatch": "^10.0.1",
-        "ow": "^2.0.0",
-        "stream-json": "^1.9.1",
-        "tldts": "^7.0.6",
-        "tough-cookie": "^6.0.0",
+        "mime-types": "^3.0.1",
+        "stream-json": "^3.7.0",
         "tslib": "^2.8.1",
-        "type-fest": "^4.41.0"
+        "type-fest": "^4.41.0",
+        "zod": "^4.5.4"
     },
     "lerna": {
         "command": {
@@ -77,5 +76,5 @@
             }
         }
     },
-    "gitHead": "8e04fea33d3b7ca5a386a941c990e9212275e221"
+    "gitHead": "5b29925251e92eb69252045f4980153844f58462"
 }

package/proxy_configuration.d.ts

@@ -1,129 +1,45 @@
-import type { Request } from './request.js';
+import type { ProxyInfo } from '@crawlee/types';
 export interface ProxyConfigurationFunction {
-    (options?: {
-        request?: Request;
-    }): string | null | Promise<string | null>;
+    (): string | null | Promise<string | null>;
 }
-type UrlList = (string | null)[];
 export interface ProxyConfigurationOptions {
     /**
      * An array of custom proxy URLs to be rotated.
      * Custom proxies are not compatible with Apify Proxy and an attempt to use both
      * configuration options will cause an error to be thrown on initialize.
      */
-    proxyUrls?: UrlList;
+    proxyUrls?: (string | null)[];
     /**
-     * Custom function that allows you to generate the new proxy URL dynamically. It gets an optional parameter with the `Request` object when applicable.
+     * Custom function that allows you to generate the new proxy URL dynamically.
      * Can return either stringified proxy URL or `null` if the proxy should not be used. Can be asynchronous.
      *
      * This function is used to generate the URL when {@link ProxyConfiguration.newUrl} or {@link ProxyConfiguration.newProxyInfo} is called.
      */
     newUrlFunction?: ProxyConfigurationFunction;
     /**
-     * An array of custom proxy URLs to be rotated stratified in tiers.
-     * This is a more advanced version of `proxyUrls` that allows you to define a hierarchy of proxy URLs
-     * If everything goes well, all the requests will be sent through the first proxy URL in the list.
-     * Whenever the crawler encounters a problem with the current proxy on the given domain, it will switch to the higher tier for this domain.
-     * The crawler probes lower-level proxies at intervals to check if it can make the tier downshift.
-     *
-     * This feature is useful when you have a set of proxies with different performance characteristics (speed, price, antibot performance etc.) and you want to use the best one for each domain.
-     *
-     * Use `null` as a proxy URL to disable the proxy for the given tier.
+     * When truthy, the constructor throws unless one of `proxyUrls` / `newUrlFunction` was given. Falsy by
+     * default, so a bare `ProxyConfiguration` can be constructed. Set by the Apify SDK, which builds the options
+     * object itself; declared here only so that it stays type-checkable.
+     * @internal
      */
-    tieredProxyUrls?: UrlList[];
-}
-export interface TieredProxy {
-    proxyUrl: string | null;
-    proxyTier?: number;
+    validateRequired?: boolean;
 }
 /**
- * The main purpose of the ProxyInfo object is to provide information
- * about the current proxy connection used by the crawler for the request.
- * Outside of crawlers, you can get this object by calling {@link ProxyConfiguration.newProxyInfo}.
- *
- * **Example usage:**
- *
- * ```javascript
- * const proxyConfiguration = new ProxyConfiguration({
- *   proxyUrls: ['...', '...'] // List of Proxy URLs to rotate
- * });
- *
- * // Getting proxyInfo object by calling class method directly
- * const proxyInfo = await proxyConfiguration.newProxyInfo();
- *
- * // In crawler
- * const crawler = new CheerioCrawler({
- *   // ...
- *   proxyConfiguration,
- *   requestHandler({ proxyInfo }) {
- *      // Getting used proxy URL
- *       const proxyUrl = proxyInfo.url;
- *   }
- * })
+ * Minimal contract that any object passed to a crawler as its `proxyConfiguration`
+ * option must satisfy.
  *
- * ```
- */
-export interface ProxyInfo {
-    /**
-     * The URL of the proxy.
-     */
-    url: string;
-    /**
-     * Username for the proxy.
-     */
-    username?: string;
-    /**
-     * User's password for the proxy.
-     */
-    password: string;
-    /**
-     * Hostname of your proxy.
-     */
-    hostname: string;
-    /**
-     * Proxy port.
-     */
-    port: number | string;
-    /**
-     * Proxy tier for the current proxy, if applicable (only for `tieredProxyUrls`).
-     */
-    proxyTier?: number;
-    /**
-     * When `true`, the proxy is likely intercepting HTTPS traffic and is able to view and modify its content.
-     *
-     * @default false
-     */
-    ignoreTlsErrors?: boolean;
-}
-interface TieredProxyOptions {
-    request?: Request;
-    proxyTier?: number;
-}
-/**
- * Internal class for tracking the proxy tier history for a specific domain.
+ * Implement this interface to plug a custom proxy-provisioning strategy into any Crawlee
+ * crawler — for example a remote proxy service or a thin wrapper around the built-in
+ * `ProxyConfiguration` with different rotation rules. *
  *
- * Predicts the best proxy tier for the next request based on the error history for different proxy tiers.
+ * @category Scaling
  */
-declare class ProxyTierTracker {
-    private histogram;
-    private currentTier;
-    constructor(tieredProxyUrls: (string | null)[][]);
-    /**
-     * Processes a single step of the algorithm and updates the current tier prediction based on the error history.
-     */
-    private processStep;
-    /**
-     * Increases the error score for the given proxy tier. This raises the chance of picking a different proxy tier for the subsequent requests.
-     *
-     * The error score is increased by 10 for the given tier. This means that this tier will be disadvantaged for the next 10 requests (every new request prediction decreases the error score by 1).
-     * @param tier The proxy tier to mark as problematic.
-     */
-    addError(tier: number): void;
+export interface IProxyConfiguration {
     /**
-     * Returns the best proxy tier for the next request based on the error history for different proxy tiers.
-     * @returns The proxy tier prediction
+     * Creates a new {@link ProxyInfo} object describing the proxy to use.
+     * Returns `undefined` when no proxy should be used.
      */
-    predictTier(): number;
+    newProxyInfo(): Promise<ProxyInfo | undefined>;
 }
 /**
  * Configures connection to a proxy server with the provided options. Proxy servers are used to prevent target websites from blocking
@@ -153,16 +69,9 @@ declare class ProxyTierTracker {
  * ```
  * @category Scaling
  */
-export declare class ProxyConfiguration {
-    isManInTheMiddle: boolean;
-    protected nextCustomUrlIndex: number;
-    protected proxyUrls?: UrlList;
-    protected tieredProxyUrls?: UrlList[];
-    protected usedProxyUrls: Map<string, string | null>;
-    protected newUrlFunction?: ProxyConfigurationFunction;
-// @ts-ignore optional peer dependency or compatibility with es2022
-    protected log: import("@apify/log").Log;
-    protected domainTiers: Map<string, ProxyTierTracker>;
+export declare class ProxyConfiguration implements IProxyConfiguration {
+    #private;
+    readonly isManInTheMiddle = false;
     /**
      * Creates a {@link ProxyConfiguration} instance based on the provided options. Proxy servers are used to prevent target websites from
      * blocking your crawlers based on IP address rate limits or blacklists. Setting proxy configuration in your crawlers automatically configures
@@ -193,35 +102,19 @@ export declare class ProxyConfiguration {
      *
      * @return Represents information about used proxy and its configuration.
      */
-    newProxyInfo(options?: TieredProxyOptions): Promise<ProxyInfo | undefined>;
-    /**
-     * Given a request / proxy tier, this function returns a new proxy URL based on the provided configuration options.
-     * @param options Options for the tiered proxy rotation
-     * @returns An object with the proxy URL and the proxy tier used.
-     */
-    protected _handleTieredUrl(options?: TieredProxyOptions): TieredProxy;
-    /**
-     * Given a `Request` object, this function returns the tier of the proxy that should be used for the request.
-     *
-     * This returns `null` if `tieredProxyUrls` option is not set.
-     */
-    protected predictProxyTier(request: Request): number | null;
+    newProxyInfo(): Promise<ProxyInfo | undefined>;
     /**
      * Returns a new proxy URL based on provided configuration options.
      *
      * @return A string with a proxy URL, including authentication credentials and port number.
      *  For example, `http://bob:password123@proxy.example.com:8000`
      */
-    newUrl(options?: TieredProxyOptions): Promise<string | undefined>;
-    protected _handleProxyUrlsList(): string | null;
+    newUrl(): Promise<string | undefined>;
+    private handleProxyUrlsList;
     /**
      * Calls the custom newUrlFunction and checks format of its return value
      */
-    protected _callNewUrlFunction(options?: {
-        request?: Request;
-    }): Promise<string | null>;
-    protected _throwCannotCombineCustomMethods(): never;
-    protected _throwNoOptionsProvided(): never;
+    private callNewUrlFunction;
+    private throwCannotCombineCustomMethods;
+    private throwNoOptionsProvided;
 }
-export {};
-//# sourceMappingURL=proxy_configuration.d.ts.map

package/proxy_configuration.js

@@ -1,54 +1,12 @@
-import ow from 'ow';
-import log from '@apify/log';
-/**
- * Internal class for tracking the proxy tier history for a specific domain.
- *
- * Predicts the best proxy tier for the next request based on the error history for different proxy tiers.
- */
-class ProxyTierTracker {
-    histogram;
-    currentTier;
-    constructor(tieredProxyUrls) {
-        this.histogram = tieredProxyUrls.map(() => 0);
-        this.currentTier = 0;
-    }
-    /**
-     * Processes a single step of the algorithm and updates the current tier prediction based on the error history.
-     */
-    processStep() {
-        this.histogram.forEach((x, i) => {
-            if (this.currentTier === i)
-                return;
-            if (x > 0)
-                this.histogram[i]--;
-        });
-        const left = this.currentTier > 0 ? this.histogram[this.currentTier - 1] : Infinity;
-        const right = this.currentTier < this.histogram.length - 1 ? this.histogram[this.currentTier + 1] : Infinity;
-        if (this.histogram[this.currentTier] > Math.min(left, right)) {
-            this.currentTier = left <= right ? this.currentTier - 1 : this.currentTier + 1;
-        }
-        else if (this.histogram[this.currentTier] === left) {
-            this.currentTier--;
-        }
-    }
-    /**
-     * Increases the error score for the given proxy tier. This raises the chance of picking a different proxy tier for the subsequent requests.
-     *
-     * The error score is increased by 10 for the given tier. This means that this tier will be disadvantaged for the next 10 requests (every new request prediction decreases the error score by 1).
-     * @param tier The proxy tier to mark as problematic.
-     */
-    addError(tier) {
-        this.histogram[tier] += 10;
-    }
-    /**
-     * Returns the best proxy tier for the next request based on the error history for different proxy tiers.
-     * @returns The proxy tier prediction
-     */
-    predictTier() {
-        this.processStep();
-        return this.currentTier;
-    }
-}
+import { z } from 'zod';
+import { parseArgument, schemas } from './validators.js';
+const proxyConfigurationOptionsSchema = z.strictObject({
+    proxyUrls: z
+        .array(z.union([z.url(), z.null()]))
+        .nonempty()
+        .optional(),
+    newUrlFunction: schemas.anyFunction.optional(),
+});
 /**
  * Configures connection to a proxy server with the provided options. Proxy servers are used to prevent target websites from blocking
  * your crawlers based on IP address rate limits or blacklists. Setting proxy configuration in your crawlers automatically configures
@@ -79,13 +37,9 @@ class ProxyTierTracker {
  */
 export class ProxyConfiguration {
     isManInTheMiddle = false;
-    nextCustomUrlIndex = 0;
-    proxyUrls;
-    tieredProxyUrls;
-    usedProxyUrls = new Map();
-    newUrlFunction;
-    log = log.child({ prefix: 'ProxyConfiguration' });
-    domainTiers = new Map();
+    #nextCustomUrlIndex = 0;
+    #proxyUrls;
+    #newUrlFunction;
     /**
      * Creates a {@link ProxyConfiguration} instance based on the provided options. Proxy servers are used to prevent target websites from
      * blocking your crawlers based on IP address rate limits or blacklists. Setting proxy configuration in your crawlers automatically configures
@@ -107,20 +61,21 @@ export class ProxyConfiguration {
      * ```
      */
     constructor(options = {}) {
+        // `validateRequired` is destructured off before the strict-object parse on purpose: the Apify SDK passes it
+        // through a computed key (`['validateRequired' as string]: false`), and leaving it in `rest` would make
+        // `Actor.createProxyConfiguration()` fail the `z.strictObject` check with a `ZodError`.
         const { validateRequired, ...rest } = options;
-        ow(rest, ow.object.exactShape({
-            proxyUrls: ow.optional.array.nonEmpty.ofType(ow.any(ow.string.url, ow.null)),
-            newUrlFunction: ow.optional.function,
-            tieredProxyUrls: ow.optional.array.nonEmpty.ofType(ow.array.nonEmpty.ofType(ow.any(ow.string.url, ow.null))),
-        }));
-        const { proxyUrls, newUrlFunction, tieredProxyUrls } = options;
-        if ([proxyUrls, newUrlFunction, tieredProxyUrls].filter((x) => x).length > 1)
-            this._throwCannotCombineCustomMethods();
+        if ('tieredProxyUrls' in rest) {
+            throw new Error('The `tieredProxyUrls` option has been removed in Crawlee v4. ' +
+                'See the v4 upgrading guide for the recommended migration to named sessions.');
+        }
+        const { proxyUrls, newUrlFunction } = parseArgument(rest, proxyConfigurationOptionsSchema);
+        if (proxyUrls && newUrlFunction)
+            this.throwCannotCombineCustomMethods();
         if (!proxyUrls && !newUrlFunction && validateRequired)
-            this._throwNoOptionsProvided();
-        this.proxyUrls = proxyUrls;
-        this.newUrlFunction = newUrlFunction;
-        this.tieredProxyUrls = tieredProxyUrls;
+            this.throwNoOptionsProvided();
+        this.#proxyUrls = proxyUrls;
+        this.#newUrlFunction = newUrlFunction;
     }
     /**
      * This function creates a new {@link ProxyInfo} info object.
@@ -131,17 +86,8 @@ export class ProxyConfiguration {
      *
      * @return Represents information about used proxy and its configuration.
      */
-    async newProxyInfo(options) {
-        let url;
-        let tier;
-        if (this.tieredProxyUrls) {
-            const { proxyUrl, proxyTier } = this._handleTieredUrl(options);
-            url = proxyUrl ?? undefined;
-            tier = proxyTier;
-        }
-        else {
-            url = await this.newUrl(options);
-        }
+    async newProxyInfo() {
+        const url = await this.newUrl();
         if (!url)
             return undefined;
         const { username, password, port, hostname } = new URL(url);
@@ -151,82 +97,28 @@ export class ProxyConfiguration {
             password: decodeURIComponent(password),
             hostname,
             port: port,
-            proxyTier: tier,
-        };
-    }
-    /**
-     * Given a request / proxy tier, this function returns a new proxy URL based on the provided configuration options.
-     * @param options Options for the tiered proxy rotation
-     * @returns An object with the proxy URL and the proxy tier used.
-     */
-    _handleTieredUrl(options) {
-        if (!this.tieredProxyUrls)
-            throw new Error('Tiered proxy URLs are not set');
-        if (!options || (!options?.request && options?.proxyTier === undefined)) {
-            const allProxyUrls = this.tieredProxyUrls.flat();
-            return {
-                proxyUrl: allProxyUrls[this.nextCustomUrlIndex++ % allProxyUrls.length],
-            };
-        }
-        let tierPrediction = options.proxyTier;
-        if (typeof tierPrediction !== 'number') {
-            tierPrediction = this.predictProxyTier(options.request);
-        }
-        const proxyTier = this.tieredProxyUrls[tierPrediction];
-        return {
-            proxyUrl: proxyTier[this.nextCustomUrlIndex++ % proxyTier.length],
-            proxyTier: tierPrediction,
         };
     }
-    /**
-     * Given a `Request` object, this function returns the tier of the proxy that should be used for the request.
-     *
-     * This returns `null` if `tieredProxyUrls` option is not set.
-     */
-    predictProxyTier(request) {
-        if (!this.tieredProxyUrls)
-            return null;
-        const domain = new URL(request.url).hostname;
-        if (!this.domainTiers.has(domain)) {
-            this.domainTiers.set(domain, new ProxyTierTracker(this.tieredProxyUrls));
-        }
-        request.userData.__crawlee ??= {};
-        const tracker = this.domainTiers.get(domain);
-        if (typeof request.userData.__crawlee.lastProxyTier === 'number') {
-            tracker.addError(request.userData.__crawlee.lastProxyTier);
-        }
-        const tierPrediction = tracker.predictTier();
-        if (typeof request.userData.__crawlee.lastProxyTier === 'number' &&
-            request.userData.__crawlee.lastProxyTier !== tierPrediction) {
-            log.debug(`Changing proxy tier for domain "${domain}" from ${request.userData.__crawlee.lastProxyTier} to ${tierPrediction}.`);
-        }
-        request.userData.__crawlee.lastProxyTier = tierPrediction;
-        request.userData.__crawlee.forefront = true;
-        return tierPrediction;
-    }
     /**
      * Returns a new proxy URL based on provided configuration options.
      *
      * @return A string with a proxy URL, including authentication credentials and port number.
      *  For example, `http://bob:password123@proxy.example.com:8000`
      */
-    async newUrl(options) {
-        if (this.newUrlFunction) {
-            return (await this._callNewUrlFunction({ request: options?.request })) ?? undefined;
-        }
-        if (this.tieredProxyUrls) {
-            return this._handleTieredUrl(options).proxyUrl ?? undefined;
+    async newUrl() {
+        if (this.#newUrlFunction) {
+            return (await this.callNewUrlFunction()) ?? undefined;
         }
-        return this._handleProxyUrlsList() ?? undefined;
+        return this.handleProxyUrlsList() ?? undefined;
     }
-    _handleProxyUrlsList() {
-        return this.proxyUrls[this.nextCustomUrlIndex++ % this.proxyUrls.length];
+    handleProxyUrlsList() {
+        return this.#proxyUrls[this.#nextCustomUrlIndex++ % this.#proxyUrls.length];
     }
     /**
      * Calls the custom newUrlFunction and checks format of its return value
      */
-    async _callNewUrlFunction(options) {
-        const proxyUrl = await this.newUrlFunction(options);
+    async callNewUrlFunction() {
+        const proxyUrl = await this.#newUrlFunction();
         try {
             if (proxyUrl) {
                 new URL(proxyUrl); // eslint-disable-line no-new
@@ -237,11 +129,10 @@ export class ProxyConfiguration {
             throw new Error(`The provided newUrlFunction did not return a valid URL.\nCause: ${err.message}`);
         }
     }
-    _throwCannotCombineCustomMethods() {
+    throwCannotCombineCustomMethods() {
         throw new Error('Cannot combine custom proxies "options.proxyUrls" with custom generating function "options.newUrlFunction".');
     }
-    _throwNoOptionsProvided() {
+    throwNoOptionsProvided() {
         throw new Error('One of "options.proxyUrls" or "options.newUrlFunction" needs to be provided.');
     }
 }
-//# sourceMappingURL=proxy_configuration.js.map