@browserless.io/browserless 2.9.0 → 2.10.0

package/build/routes/management/http/pressure.get.response.json

@@ -0,0 +1,76 @@
+{
+  "type": "object",
+  "properties": {
+    "cpu": {
+      "description": "An integer representing the percentage of CPU being used. For instance 92 means 92%",
+      "type": [
+        "null",
+        "number"
+      ]
+    },
+    "date": {
+      "description": "A number of milliseconds since epoch, or \"Date.now()\" equivalent.",
+      "type": "number"
+    },
+    "isAvailable": {
+      "description": "Whether or not a session can be connected and immediately ran on a health instance.",
+      "type": "boolean"
+    },
+    "maxConcurrent": {
+      "description": "The maximum amount of browsers that can be ran at a single time.",
+      "type": "number"
+    },
+    "maxQueued": {
+      "description": "The maximum amount of queued connections allowed at a single time.",
+      "type": "number"
+    },
+    "memory": {
+      "description": "An integer representing the percentage of Memory being used. For instance 95 means 95%",
+      "type": [
+        "null",
+        "number"
+      ]
+    },
+    "message": {
+      "description": "A human-readable message as the overall status of the instance.",
+      "type": "string"
+    },
+    "queued": {
+      "description": "The current number of connect or API calls pending to run.",
+      "type": "number"
+    },
+    "reason": {
+      "description": "A simple single-word reason as to why an instance may or may not be available.",
+      "enum": [
+        "",
+        "cpu",
+        "full",
+        "memory"
+      ],
+      "type": "string"
+    },
+    "recentlyRejected": {
+      "description": "The number of recent connections that were rejected due to the queue and concurrency\nlimits having been filled.",
+      "type": "number"
+    },
+    "running": {
+      "description": "The current number of running connections or API calls.",
+      "type": "number"
+    }
+  },
+  "additionalProperties": false,
+  "required": [
+    "cpu",
+    "date",
+    "isAvailable",
+    "maxConcurrent",
+    "maxQueued",
+    "memory",
+    "message",
+    "queued",
+    "reason",
+    "recentlyRejected",
+    "running"
+  ],
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/build/routes/management/tests/management.spec.js

@@ -31,6 +31,13 @@ describe('Management APIs', function () {
             expect(res.status).to.equal(200);
         });
     });
+    it('allows requests to /pressure', async () => {
+        await start();
+        await fetch('http://localhost:3000/pressure?token=6R0W53R135510').then(async (res) => {
+            expect(res.headers.get('content-type')).to.equal('application/json; charset=UTF-8');
+            expect(res.status).to.equal(200);
+        });
+    });
     it('allows requests to /sessions', async () => {
         await start();
         await fetch('http://localhost:3000/sessions?token=6R0W53R135510').then(async (res) => {

package/build/types.d.ts

@@ -54,7 +54,8 @@ declare abstract class Route {
     protected _metrics: Browserless['metrics'];
     protected _monitoring: Browserless['monitoring'];
     protected _staticSDKDir: Browserless['staticSDKDir'];
-    constructor(_browserManager: Browserless['browserManager'], _config: Browserless['config'], _fileSystem: Browserless['fileSystem'], _metrics: Browserless['metrics'], _monitoring: Browserless['monitoring'], _staticSDKDir: Browserless['staticSDKDir']);
+    protected _limiter: Browserless['limiter'];
+    constructor(_browserManager: Browserless['browserManager'], _config: Browserless['config'], _fileSystem: Browserless['fileSystem'], _metrics: Browserless['metrics'], _monitoring: Browserless['monitoring'], _staticSDKDir: Browserless['staticSDKDir'], _limiter: Browserless['limiter']);
     /**
      * A unique name to identify this route. Used in downstream
      * SDKs to potentially remove or disable.
@@ -133,6 +134,12 @@ declare abstract class Route {
      * @returns {string | null} The full path location of the SDK's static directory
      */
     staticSDKDir: () => string | null;
+    /**
+     * Helper function that loads the limiter module into the router's
+     * handler scope.
+     * @returns Limiter
+     */
+    limiter: () => import("@browserless.io/browserless").Limiter;
     /**
      * The HTTP path that this route handles, eg '/my-route' OR an
      * array of paths that this route can handle.
@@ -510,6 +517,7 @@ export declare const BrowserlessManagementRoutes: {
     ConfigGetRoute: string;
     MetricsGetRoute: string;
     MetricsTotalGetRoute: string;
+    PressureGetRoute: string;
     SessionsGetRoute: string;
     StaticGetRoute: string;
 };
@@ -518,6 +526,7 @@ export declare const BrowserlessRoutes: {
     ConfigGetRoute: string;
     MetricsGetRoute: string;
     MetricsTotalGetRoute: string;
+    PressureGetRoute: string;
     SessionsGetRoute: string;
     StaticGetRoute: string;
     WebKitPlaywrightWebSocketRoute: string;

package/build/types.js

@@ -5,13 +5,15 @@ class Route {
     _metrics;
     _monitoring;
     _staticSDKDir;
-    constructor(_browserManager, _config, _fileSystem, _metrics, _monitoring, _staticSDKDir) {
+    _limiter;
+    constructor(_browserManager, _config, _fileSystem, _metrics, _monitoring, _staticSDKDir, _limiter) {
         this._browserManager = _browserManager;
         this._config = _config;
         this._fileSystem = _fileSystem;
         this._metrics = _metrics;
         this._monitoring = _monitoring;
         this._staticSDKDir = _staticSDKDir;
+        this._limiter = _limiter;
     }
     /**
      * A boolean, or a function that returns a boolean, on
@@ -86,6 +88,12 @@ class Route {
      * @returns {string | null} The full path location of the SDK's static directory
      */
     staticSDKDir = () => this._staticSDKDir;
+    /**
+     * Helper function that loads the limiter module into the router's
+     * handler scope.
+     * @returns Limiter
+     */
+    limiter = () => this._limiter;
 }
 /**
  * A primitive HTTP-based route that doesn't require a
@@ -184,6 +192,7 @@ export const BrowserlessManagementRoutes = {
     ConfigGetRoute: 'ConfigGetRoute',
     MetricsGetRoute: 'MetricsGetRoute',
     MetricsTotalGetRoute: 'MetricsTotalGetRoute',
+    PressureGetRoute: 'PressureGetRoute',
     SessionsGetRoute: 'SessionsGetRoute',
     StaticGetRoute: 'StaticGetRoute',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserless.io/browserless",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "license": "SSPL",
   "description": "The browserless platform",
   "author": "browserless.io",
@@ -59,11 +59,11 @@
     "lighthouse": "^12.0.0",
     "micromatch": "^4.0.4",
     "playwright-core": "1.44.0",
-    "puppeteer-core": "^22.8.0",
+    "puppeteer-core": "^22.8.1",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "queue": "^7.0.0",
-    "systeminformation": "^5.22.8",
+    "systeminformation": "^5.22.9",
     "tar-fs": "^3.0.6"
   },
   "optionalDependencies": {
@@ -73,10 +73,10 @@
     "@types/http-proxy": "^1.17.14",
     "@types/micromatch": "^4.0.7",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^20.12.11",
+    "@types/node": "^20.12.12",
     "@types/sinon": "^17.0.3",
-    "@typescript-eslint/eslint-plugin": "^7.8.0",
-    "@typescript-eslint/parser": "^7.8.0",
+    "@typescript-eslint/eslint-plugin": "^7.9.0",
+    "@typescript-eslint/parser": "^7.9.0",
     "assert": "^2.0.0",
     "chai": "^5.1.1",
     "cross-env": "^7.0.3",

package/src/browserless.ts

@@ -272,12 +272,14 @@ export class Browserless extends EventEmitter {
           this.metrics,
           this.monitoring,
           this.staticSDKDir,
+          this.limiter,
         );
 
         if (!this.routeIsDisabled(route)) {
           route.bodySchema = safeParse(bodySchema);
           route.querySchema = safeParse(querySchema);
           route.config = () => this.config;
+          route.limiter = () => this.limiter;
           route.metrics = () => this.metrics;
           route.monitoring = () => this.monitoring;
           route.fileSystem = () => this.fileSystem;
@@ -321,11 +323,13 @@ export class Browserless extends EventEmitter {
           this.metrics,
           this.monitoring,
           this.staticSDKDir,
+          this.limiter,
         );
 
         if (!this.routeIsDisabled(route)) {
           route.querySchema = safeParse(querySchema);
           route.config = () => this.config;
+          route.limiter = () => this.limiter;
           route.metrics = () => this.metrics;
           route.monitoring = () => this.monitoring;
           route.fileSystem = () => this.fileSystem;

package/src/http.ts

@@ -128,6 +128,7 @@ export enum HTTPManagementRoutes {
   config = '/config',
   metrics = '/metrics',
   metricsTotal = '/metrics/total',
+  pressure = '/pressure',
   sessions = '/sessions',
   static = '/',
 }

package/src/routes/management/http/pressure.get.ts

@@ -0,0 +1,135 @@
+import {
+  APITags,
+  BrowserlessRoutes,
+  HTTPManagementRoutes,
+  HTTPRoute,
+  Methods,
+  Request,
+  contentTypes,
+  jsonResponse,
+} from '@browserless.io/browserless';
+import { ServerResponse } from 'http';
+
+export type ResponseSchema = {
+  /**
+   * An integer representing the percentage of CPU being used. For instance 92 means 92%
+   */
+  cpu: number | null;
+
+  /**
+   * A number of milliseconds since epoch, or "Date.now()" equivalent.
+   */
+  date: number;
+
+  /**
+   * Whether or not a session can be connected and immediately ran on a health instance.
+   */
+  isAvailable: boolean;
+
+  /**
+   * The maximum amount of browsers that can be ran at a single time.
+   */
+  maxConcurrent: number;
+
+  /**
+   * The maximum amount of queued connections allowed at a single time.
+   */
+  maxQueued: number;
+
+  /**
+   * An integer representing the percentage of Memory being used. For instance 95 means 95%
+   */
+  memory: number | null;
+
+  /**
+   * A human-readable message as the overall status of the instance.
+   */
+  message: string;
+
+  /**
+   * The current number of connect or API calls pending to run.
+   */
+  queued: number;
+
+  /**
+   * A simple single-word reason as to why an instance may or may not be available.
+   */
+  reason: 'full' | 'cpu' | 'memory' | '';
+
+  /**
+   * The number of recent connections that were rejected due to the queue and concurrency
+   * limits having been filled.
+   */
+  recentlyRejected: number;
+
+  /**
+   * The current number of running connections or API calls.
+   */
+  running: number;
+};
+
+export default class PressureGetRoute extends HTTPRoute {
+  name = BrowserlessRoutes.PressureGetRoute;
+  accepts = [contentTypes.any];
+  auth = true;
+  browser = null;
+  concurrency = false;
+  contentTypes = [contentTypes.json];
+  description = `Returns a JSON body of stats related to the pressure being created on the instance.`;
+  method = Methods.get;
+  path = HTTPManagementRoutes.pressure;
+  tags = [APITags.management];
+  handler = async (_req: Request, res: ServerResponse): Promise<void> => {
+    const monitoring = this.monitoring();
+    const config = this.config();
+    const limiter = this.limiter();
+    const metrics = this.metrics();
+
+    const {
+      cpuInt: cpu,
+      memoryInt: memory,
+      cpuOverloaded,
+      memoryOverloaded,
+    } = await monitoring.overloaded();
+    const date = Date.now();
+    const hasCapacity = limiter.hasCapacity;
+    const queued = limiter.waiting;
+    const isAvailable = hasCapacity && !cpuOverloaded && !memoryOverloaded;
+    const running = limiter.executing;
+    const recentlyRejected = metrics.get().rejected;
+    const maxConcurrent = config.getConcurrent();
+    const maxQueued = config.getQueued();
+
+    const reason = !hasCapacity
+      ? 'full'
+      : cpuOverloaded
+        ? 'cpu'
+        : memoryOverloaded
+          ? 'memory'
+          : '';
+
+    const message = !hasCapacity
+      ? 'Concurrency and queue are full'
+      : cpuOverloaded
+        ? 'CPU is over the configured maximum for cpu percent'
+        : memoryOverloaded
+          ? 'Memory is over the configured maximum for memory percent'
+          : '';
+
+    const response: ResponseSchema = {
+      cpu,
+      date,
+      isAvailable,
+      maxConcurrent,
+      maxQueued,
+      memory,
+      message,
+      queued,
+      reason,
+      recentlyRejected,
+      running,
+    };
+
+    return jsonResponse(res, 200, response);
+  };
+}

package/src/routes/management/tests/management.spec.ts

@@ -56,6 +56,19 @@ describe('Management APIs', function () {
     );
   });
 
+  it('allows requests to /pressure', async () => {
+    await start();
+
+    await fetch('http://localhost:3000/pressure?token=6R0W53R135510').then(
+      async (res) => {
+        expect(res.headers.get('content-type')).to.equal(
+          'application/json; charset=UTF-8',
+        );
+        expect(res.status).to.equal(200);
+      },
+    );
+  });
+
   it('allows requests to /sessions', async () => {
     await start();
 
@@ -87,13 +100,11 @@ describe('Management APIs', function () {
 
     await fetch('http://localhost:3000/active?token=6R0W53R135510', {
       method: 'HEAD',
-    }).then(
-      async (res) => {
-        expect(res.headers.get('content-type')).to.equal(
-          'text/plain; charset=UTF-8',
-        );
-        expect(res.status).to.equal(204);
-      },
-    );
+    }).then(async (res) => {
+      expect(res.headers.get('content-type')).to.equal(
+        'text/plain; charset=UTF-8',
+      );
+      expect(res.status).to.equal(204);
+    });
   });
 });

package/src/types.ts

@@ -103,6 +103,7 @@ abstract class Route {
     protected _metrics: Browserless['metrics'],
     protected _monitoring: Browserless['monitoring'],
     protected _staticSDKDir: Browserless['staticSDKDir'],
+    protected _limiter: Browserless['limiter'],
   ) {}
 
   /**
@@ -196,6 +197,13 @@ abstract class Route {
    */
   staticSDKDir = () => this._staticSDKDir;
 
+  /**
+   * Helper function that loads the limiter module into the router's
+   * handler scope.
+   * @returns Limiter
+   */
+  limiter = () => this._limiter;
+
   /**
    * The HTTP path that this route handles, eg '/my-route' OR an
    * array of paths that this route can handle.
@@ -650,6 +658,7 @@ export const BrowserlessManagementRoutes = {
   ConfigGetRoute: 'ConfigGetRoute',
   MetricsGetRoute: 'MetricsGetRoute',
   MetricsTotalGetRoute: 'MetricsTotalGetRoute',
+  PressureGetRoute: 'PressureGetRoute',
   SessionsGetRoute: 'SessionsGetRoute',
   StaticGetRoute: 'StaticGetRoute',
 };