@push.rocks/smartpuppeteer 2.2.0 → 2.3.0

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

@@ -28,6 +28,12 @@ export interface ILiveBrowserSecurityOptions {
   denyFileChoosers?: boolean;
   denyPermissions?: boolean;
   httpNavigationOnly?: boolean;
+  proxyCredentials?: ILiveBrowserProxyCredentials;
+}
+
+export interface ILiveBrowserProxyCredentials {
+  username: string;
+  password: string;
 }
 
 export interface ILiveBrowserOperationOptions {
@@ -66,6 +72,27 @@ export interface ILiveBrowserSessionOptions extends Omit<IEnvAwareOptions, 'laun
   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 {
   id: string;
   url: string;

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';