Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

9.0 KB
Raw Blame
import { spawn, ChildProcess } from 'child_process';
import { randomBytes } from 'crypto';
import * as path from 'path';
import * as fs from 'fs';
import * as os from 'os';
import { getCheckoutBinaryPath, resolveManagedBinaryPath } from './platform';
import { withAuthedFetch } from './http';
import {
  SnapshotParams,
  SnapshotResponse,
  TabClickParams,
  TabLockParams,
  TabUnlockParams,
  CreateTabParams,
  CreateTabResponse,
  PinchtabOptions,
} from './types';

export * from './types';
export * from './platform';

const servingHealthStatuses: readonly unknown[] = ['ok', 'degraded'];

export function isPinchtabHealthy(body: unknown): boolean {
  return (
    typeof body === 'object' &&
    body !== null &&
    servingHealthStatuses.includes((body as { status?: unknown }).status)
  );
}

export class Pinchtab {
  private baseUrl: string;
  private timeout: number;
  private port: number;
  private process: ChildProcess | null = null;
  private binaryPath: string | null = null;
  private tempConfigDir: string | null = null;
  private token: string | null;
  private readonly configuredToken: string | null;
  private readonly shutdownTimeout: number;

  constructor(options: PinchtabOptions = {}) {
    this.port = options.port || 9867;
    this.baseUrl = options.baseUrl || `http://localhost:${this.port}`;
    this.timeout = options.timeout || 30000;
    this.configuredToken = options.token?.trim() || null;
    this.token = this.configuredToken;
    this.shutdownTimeout = options.shutdownTimeout ?? 10000;
  }

  /**
   * Start the Pinchtab server process
   */
  async start(binaryPath?: string): Promise<void> {
    if (this.process) {
      throw new Error('Pinchtab process already running');
    }

    if (!binaryPath) {
      binaryPath = await this.getBinaryPathInternal();
    }

    this.binaryPath = binaryPath;
    const tempConfigPath = this.createTempConfig();

    return new Promise((resolve, reject) => {
      let settled = false;
      const fail = (message: string) => {
        if (settled) {
          return;
        }
        settled = true;
        this.cleanupTempConfig();
        reject(new Error(message));
      };

      this.process = spawn(binaryPath, ['server'], {
        stdio: 'inherit',
        env: {
          ...process.env,
          PINCHTAB_CONFIG: tempConfigPath,
        },
      });

      this.process.on('error', (err) => {
        fail(`Failed to start Pinchtab: ${err.message}`);
      });

      this.process.on('exit', (code, signal) => {
        this.cleanupTempConfig();
        if (!settled) {
          const reason = signal ? `signal ${signal}` : `exit code ${code ?? 0}`;
          reject(new Error(`Pinchtab exited before becoming ready (${reason})`));
        }
      });

      void this.waitForServerReady()
        .then(() => {
          if (settled) {
            return;
          }
          settled = true;
          resolve();
        })
        .catch((err: Error) => {
          if (this.process) {
            this.process.kill();
            this.process = null;
          }
          fail(err.message);
        });
    });
  }

  /**
   * Stop the Pinchtab server process
   */
  async stop(): Promise<void> {
    const proc = this.process;
    this.process = null;
    if (!proc) {
      this.cleanupTempConfig();
      return;
    }
    try {
      await this.terminateProcess(proc);
    } finally {
      // Always clean up, even if the child never exited — the previous
      // implementation only cleaned the temp dir on the 'exit' event, leaking
      // it when a wedged child ignored the signal.
      this.cleanupTempConfig();
    }
  }

  /**
   * Terminate a child with SIGTERM, escalating to SIGKILL after shutdownTimeout
   * so a wedged process can never hang stop() indefinitely.
   */
  private terminateProcess(proc: ChildProcess): Promise<void> {
    return new Promise<void>((resolve) => {
      if (proc.exitCode !== null || proc.signalCode !== null) {
        resolve();
        return;
      }

      let resolved = false;
      let graceTimer: ReturnType<typeof setTimeout> | undefined;
      const done = () => {
        if (resolved) {
          return;
        }
        resolved = true;
        clearTimeout(forceTimer);
        if (graceTimer) {
          clearTimeout(graceTimer);
        }
        resolve();
      };

      proc.once('exit', done);

      const forceTimer = setTimeout(() => {
        proc.kill('SIGKILL');
        // Safety net: resolve even if 'exit' never fires after SIGKILL.
        graceTimer = setTimeout(done, 2000);
        graceTimer.unref?.();
      }, this.shutdownTimeout);
      forceTimer.unref?.();

      proc.kill('SIGTERM');
    });
  }

  /**
   * Take a snapshot of the current tab
   */
  async snapshot(params?: SnapshotParams): Promise<SnapshotResponse> {
    return this.request<SnapshotResponse>('/snapshot', params);
  }

  /**
   * Click on a UI element
   */
  async click(params: TabClickParams): Promise<void> {
    await this.request('/tab/click', params);
  }

  /**
   * Lock a tab
   */
  async lock(params: TabLockParams): Promise<void> {
    await this.request('/lock', params);
  }

  /**
   * Unlock a tab
   */
  async unlock(params: TabUnlockParams): Promise<void> {
    await this.request('/unlock', params);
  }

  /**
   * Create a new tab
   */
  async createTab(params: CreateTabParams): Promise<CreateTabResponse> {
    return this.request<CreateTabResponse>('/tab/create', params);
  }

  /**
   * Make a request to the Pinchtab API
   */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  private async request<T = any>(path: string, body?: any): Promise<T> {
    const url = `${this.baseUrl}${path}`;

    return withAuthedFetch(this.token, this.timeout, async (doFetch) => {
      const response = await doFetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: body ? JSON.stringify(body) : undefined,
      });

      if (!response.ok) {
        const error = await response.text();
        throw new Error(`${response.status}: ${error}`);
      }

      return response.json() as Promise<T>;
    });
  }

  /**
   * Get the path to the Pinchtab binary
   */
  private async getBinaryPathInternal(): Promise<string> {
    const checkoutBinaryPath = getCheckoutBinaryPath(__dirname);
    if (checkoutBinaryPath) {
      if (!fs.existsSync(checkoutBinaryPath)) {
        throw new Error(
          `Pinchtab source-checkout binary not found at ${checkoutBinaryPath}.\n` +
            `Build it first with: bash scripts/npm-dev-binary.sh`
        );
      }
      return checkoutBinaryPath;
    }

    // Shared resolver: package-relative managed location first, then the legacy
    // $HOME fallback (issue #628). Keeps the SDK, the CLI wrapper, and the
    // installer agreeing on one binary location.
    const binaryPath = resolveManagedBinaryPath(__dirname);
    if (!fs.existsSync(binaryPath)) {
      throw new Error(
        `Pinchtab binary not found at ${binaryPath}.\n` +
          `Please run: npm rebuild pinchtab\n` +
          `Or pass an explicit path to pinch.start('/path/to/pinchtab')`
      );
    }

    return binaryPath;
  }

  private createTempConfig(): string {
    this.cleanupTempConfig();

    const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pinchtab-npm-'));
    const configPath = path.join(configDir, 'config.json');
    const stateDir = path.join(configDir, 'state');
    const token = this.configuredToken || `npm-${randomBytes(16).toString('hex')}`;
    this.token = token;

    fs.writeFileSync(
      configPath,
      JSON.stringify(
        {
          server: {
            bind: '127.0.0.1',
            port: String(this.port),
            stateDir,
            token,
          },
        },
        null,
        2
      )
    );

    this.tempConfigDir = configDir;
    return configPath;
  }

  private cleanupTempConfig(): void {
    if (!this.tempConfigDir) {
      return;
    }
    fs.rmSync(this.tempConfigDir, { recursive: true, force: true });
    this.tempConfigDir = null;
  }

  private async waitForServerReady(): Promise<void> {
    const deadline = Date.now() + 10000;

    while (Date.now() < deadline) {
      if (await this.probeHealthy()) {
        return;
      }
      await new Promise((resolve) => setTimeout(resolve, 250));
    }

    throw new Error(`Pinchtab did not become ready at ${this.baseUrl} within 10s`);
  }

  /**
   * Probe GET /health for an actual PinchTab-ready shape, so a foreign process
   * on the port can't satisfy startup. Bounded per-probe so one hung fetch can't
   * consume the whole readiness budget.
   */
  private async probeHealthy(): Promise<boolean> {
    try {
      return await withAuthedFetch(this.token, 2000, async (doFetch) => {
        const response = await doFetch(`${this.baseUrl}/health`);
        if (!response.ok) {
          return false;
        }
        const body = await response.json().catch(() => null);
        return isPinchtabHealthy(body);
      });
    } catch {
      // Server not ready yet (not listening, hung, or not PinchTab).
      return false;
    }
  }
}

export default Pinchtab;