@push.rocks/smartpuppeteer 2.1.0 → 2.3.0

package/ts/smartpuppeteer.classes.smartpuppeteer.ts

@@ -2,10 +2,18 @@ import * as plugins from './smartpuppeteer.plugins.js';
 
 export interface IEnvAwareOptions {
   forceNoSandbox?: boolean;
+  requireSandbox?: boolean;
   usePipe?: boolean;
   launchOptions?: plugins.puppeteer.LaunchOptions;
 }
 
+const sandboxDisablingArguments = [
+  '--disable-gpu-sandbox',
+  '--disable-seccomp-filter-sandbox',
+  '--disable-setuid-sandbox',
+  '--no-sandbox',
+];
+
 export const resolveBrowserExecutablePath = (
   candidateNamesArg: string[] = [
     'google-chrome',
@@ -29,15 +37,30 @@ export const getEnvAwareBrowserInstance = async (
 ): Promise<plugins.puppeteer.Browser> => {
   const options: IEnvAwareOptions = {
     forceNoSandbox: false,
+    requireSandbox: false,
     ...optionsArg,
   };
 
+  if (options.forceNoSandbox && options.requireSandbox) {
+    throw new Error('forceNoSandbox and requireSandbox are mutually exclusive');
+  }
+
   const launchOptions = options.launchOptions ?? {};
   let chromeArgs: string[] = [...(launchOptions.args ?? [])];
-  if (
-    process.env.CI ||
-    options.forceNoSandbox ||
-    plugins.os.userInfo().username === 'root'
+  if (options.requireSandbox) {
+    const forbiddenArgument = chromeArgs.find((argument) => (
+      sandboxDisablingArguments.includes(argument.split('=', 1)[0]!)
+    ));
+    if (forbiddenArgument) {
+      throw new Error(`Sandbox-required browser launch rejects argument: ${forbiddenArgument}`);
+    }
+    if (process.platform === 'linux' && process.getuid?.() === 0) {
+      throw new Error('Sandbox-required Chromium cannot be launched as root');
+    }
+  } else if (
+    process.env.CI
+    || options.forceNoSandbox
+    || plugins.os.userInfo().username === 'root'
   ) {
     for (const sandboxArg of ['--no-sandbox', '--disable-setuid-sandbox']) {
       if (!chromeArgs.includes(sandboxArg)) {

package/ts/smartpuppeteer.helpers.process.ts

@@ -0,0 +1,169 @@
+import * as plugins from './smartpuppeteer.plugins.js';
+
+export interface IOwnedProcessIdentity {
+  pid: number;
+  parentPid: number;
+  processGroupId: number;
+  sessionId: number;
+  startTime: string;
+  state: string;
+}
+
+const maxOwnedGroupProcesses = 4096;
+const maxVisibleProcesses = 65536;
+const processReadBatchSize = 64;
+
+const parseProcessStat = (pid: number, stat: string): IOwnedProcessIdentity => {
+  const commandEnd = stat.lastIndexOf(')');
+  if (commandEnd < 0) {
+    throw new Error(`Unable to parse process identity for PID ${pid}`);
+  }
+  const fields = stat.slice(commandEnd + 2).trim().split(/\s+/);
+  const state = fields[0];
+  const parentPid = Number(fields[1]);
+  const processGroupId = Number(fields[2]);
+  const sessionId = Number(fields[3]);
+  const startTime = fields[19];
+  if (
+    typeof state !== 'string'
+    || state.length !== 1
+    || !Number.isInteger(parentPid)
+    || parentPid < 0
+    || !Number.isInteger(processGroupId)
+    || processGroupId < 0
+    || !Number.isInteger(sessionId)
+    || sessionId < 0
+    || typeof startTime !== 'string'
+    || !/^[0-9]+$/.test(startTime)
+  ) {
+    throw new Error(`Unable to parse process identity for PID ${pid}`);
+  }
+  return { pid, parentPid, processGroupId, sessionId, startTime, state };
+};
+
+export const readOwnedProcessIdentity = async (
+  pid: number,
+): Promise<IOwnedProcessIdentity | undefined> => {
+  if (process.platform !== 'linux') {
+    throw new Error('Confirmed browser process ownership is supported on Linux only');
+  }
+  try {
+    const stat = await plugins.fs.promises.readFile(`/proc/${pid}/stat`, 'utf8');
+    return parseProcessStat(pid, stat);
+  } catch (error) {
+    if (
+      (error as NodeJS.ErrnoException).code === 'ENOENT'
+      || (error as NodeJS.ErrnoException).code === 'ESRCH'
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+const listProcessIdentities = async (): Promise<IOwnedProcessIdentity[]> => {
+  const entries = await plugins.fs.promises.readdir('/proc', { withFileTypes: true });
+  const pids = entries
+    .filter((entry) => entry.isDirectory() && /^[0-9]+$/.test(entry.name))
+    .map((entry) => Number(entry.name));
+  if (pids.length > maxVisibleProcesses) {
+    throw new Error(`Refusing to inspect more than ${maxVisibleProcesses} processes`);
+  }
+  const identities: Array<IOwnedProcessIdentity | undefined> = [];
+  for (let index = 0; index < pids.length; index += processReadBatchSize) {
+    identities.push(...await Promise.all(
+      pids.slice(index, index + processReadBatchSize).map((pid) => readOwnedProcessIdentity(pid)),
+    ));
+  }
+  return identities.filter((identity): identity is IOwnedProcessIdentity => Boolean(identity));
+};
+
+export const listOwnedProcessGroupMembers = async (
+  rootIdentity: IOwnedProcessIdentity,
+): Promise<IOwnedProcessIdentity[]> => {
+  const currentRoot = await readOwnedProcessIdentity(rootIdentity.pid);
+  if (currentRoot && currentRoot.startTime !== rootIdentity.startTime) {
+    throw new Error('The owned browser PID was reused by another process');
+  }
+  if (
+    currentRoot
+    && (
+      currentRoot.processGroupId !== rootIdentity.processGroupId
+      || currentRoot.sessionId !== rootIdentity.sessionId
+    )
+  ) {
+    throw new Error('The owned browser process changed its process-group identity');
+  }
+  const members = (await listProcessIdentities()).filter((identity) => (
+    identity.processGroupId === rootIdentity.processGroupId
+    && identity.sessionId === rootIdentity.sessionId
+  ));
+  if (members.length > maxOwnedGroupProcesses) {
+    throw new Error(`Owned browser process group exceeded ${maxOwnedGroupProcesses} processes`);
+  }
+  return members;
+};
+
+export const killFrozenOwnedProcessGroup = (rootIdentity: IOwnedProcessIdentity): boolean => {
+  try {
+    process.kill(-rootIdentity.processGroupId, 'SIGKILL');
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') {
+      return false;
+    }
+    throw error;
+  }
+};
+
+export const signalOwnedProcessGroup = async (
+  rootIdentity: IOwnedProcessIdentity,
+  signal: NodeJS.Signals,
+): Promise<boolean> => {
+  const currentRoot = await readOwnedProcessIdentity(rootIdentity.pid);
+  if (!currentRoot) {
+    return false;
+  }
+  if (
+    currentRoot.startTime !== rootIdentity.startTime
+    || currentRoot.processGroupId !== rootIdentity.processGroupId
+    || currentRoot.sessionId !== rootIdentity.sessionId
+  ) {
+    throw new Error('Refusing to signal a reused browser process-group leader');
+  }
+  try {
+    process.kill(-rootIdentity.processGroupId, signal);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') {
+      return false;
+    }
+    throw error;
+  }
+};
+
+export const signalOwnedProcessIdentity = async (
+  identity: IOwnedProcessIdentity,
+  signal: NodeJS.Signals,
+): Promise<boolean> => {
+  const currentIdentity = await readOwnedProcessIdentity(identity.pid);
+  if (!currentIdentity) {
+    return false;
+  }
+  if (currentIdentity.startTime !== identity.startTime) {
+    throw new Error(`Refusing to signal reused PID ${identity.pid}`);
+  }
+  try {
+    process.kill(identity.pid, signal);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') {
+      return false;
+    }
+    throw error;
+  }
+};
+
+export const delay = async (milliseconds: number): Promise<void> => {
+  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
+};

package/ts/smartpuppeteer.interfaces.livebrowser.ts

@@ -23,6 +23,42 @@ export interface ILiveBrowserScreencastOptions {
   everyNthFrame?: number;
 }
 
+export interface ILiveBrowserSecurityOptions {
+  denyDownloads?: boolean;
+  denyFileChoosers?: boolean;
+  denyPermissions?: boolean;
+  httpNavigationOnly?: boolean;
+  proxyCredentials?: ILiveBrowserProxyCredentials;
+}
+
+export interface ILiveBrowserProxyCredentials {
+  username: string;
+  password: string;
+}
+
+export interface ILiveBrowserOperationOptions {
+  signal?: AbortSignal;
+}
+
+export type TLiveBrowserJsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | TLiveBrowserJsonValue[]
+  | { [key: string]: TLiveBrowserJsonValue };
+
+export interface ILiveBrowserEvaluateOptions {
+  tabId?: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  maxDepth?: number;
+  maxNodes?: number;
+  maxStringBytes?: number;
+  maxArrayLength?: number;
+  maxObjectKeys?: number;
+}
+
 export type TLiveBrowserLaunchOptions = Omit<
   NonNullable<IEnvAwareOptions['launchOptions']>,
   'signal'
@@ -32,6 +68,29 @@ export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'laun
   launchOptions?: TLiveBrowserLaunchOptions;
   viewport?: ILiveBrowserViewport;
   screencast?: ILiveBrowserScreencastOptions;
+  security?: ILiveBrowserSecurityOptions;
+  allowEvaluation?: boolean;
+}
+
+export interface ILiveBrowserProcessState {
+  generation: number;
+  pid: number | null;
+  processGroupId: number | null;
+  running: boolean;
+  exitCode: number | null;
+  signalCode: NodeJS.Signals | null;
+}
+
+export interface ILiveBrowserTerminationOptions {
+  gracefulTimeoutMs?: number;
+  forceTimeoutMs?: number;
+}
+
+export interface ILiveBrowserTerminationResult extends ILiveBrowserProcessState {
+  forced: boolean;
+  shutdownComplete: boolean;
+  confirmedDead: boolean;
+  errors: string[];
 }
 
 export interface ILiveBrowserTabState {

package/ts/smartpuppeteer.plugins.ts

@@ -1,8 +1,10 @@
 // node native scope
 import { Buffer } from 'node:buffer';
-import * as os from 'os';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
 
-export { Buffer, os };
+export { Buffer, fs, http, os };
 
 // @pushrocks scope
 import * as smartdelay from '@push.rocks/smartdelay';