run.go

package patchright

import (
	"archive/tar"
	"archive/zip"
	"bytes"
	"compress/gzip"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"net/http"
	"os"
	"os/exec"
	"path/filepath"
	"runtime"
	"strings"
)

const (
	patchrightCliVersion = "1.61.1"
	// nodeVersion is the Node.js runtime downloaded alongside the driver when no
	// PATCHRIGHT_NODEJS_PATH is provided. It is kept in line with the Node.js
	// version upstream Playwright bundles in its own driver.
	nodeVersion = "24.18.0"

	// defaultNpmRegistry serves the platform-independent patchright package.
	// Override with the PATCHRIGHT_NPM_REGISTRY environment variable.
	defaultNpmRegistry = "https://registry.npmjs.org"
	// defaultNodejsDistHost serves the per-platform Node.js binaries.
	// Override with the NODE_MIRROR environment variable (nvm/n convention).
	defaultNodejsDistHost = "https://nodejs.org/dist"
)

var logger = slog.Default()

// PatchrightDriver wraps the Patchright CLI (patched Playwright).
//
// It's required for patchright-go to work.
type PatchrightDriver struct {
	Version string
	options *RunOptions
}

func NewDriver(options ...*RunOptions) (*PatchrightDriver, error) {
	transformed, err := transformRunOptions(options...) // get default values
	if err != nil {
		return nil, err
	}
	return &PatchrightDriver{
		options: transformed,
		Version: transformed.Version,
	}, nil
}

func getDefaultCacheDirectory() (string, error) {
	userHomeDir, err := os.UserHomeDir()
	if err != nil {
		return "", fmt.Errorf("could not get user home directory: %w", err)
	}
	switch runtime.GOOS {
	case "windows":
		return filepath.Join(userHomeDir, "AppData", "Local"), nil
	case "darwin":
		return filepath.Join(userHomeDir, "Library", "Caches"), nil
	case "linux":
		return filepath.Join(userHomeDir, ".cache"), nil
	}
	return "", errors.New("could not determine cache directory")
}

func (d *PatchrightDriver) isUpToDateDriver() (bool, error) {
	if _, err := os.Stat(d.options.DriverDirectory); os.IsNotExist(err) {
		if err := os.MkdirAll(d.options.DriverDirectory, 0o777); err != nil {
			return false, fmt.Errorf("could not create driver directory: %w", err)
		}
	}
	if _, err := os.Stat(getDriverCliJs(d.options)); os.IsNotExist(err) {
		return false, nil
	} else if err != nil {
		return false, fmt.Errorf("could not check if driver is up2date: %w", err)
	}
	cmd := d.Command("--version")
	output, err := cmd.Output()
	if err != nil {
		return false, fmt.Errorf("could not run driver: %w", err)
	}
	if bytes.Contains(output, []byte(d.Version)) {
		return true, nil
	}
	// avoid triggering downloads and accidentally overwriting files
	return false, fmt.Errorf("driver exists but version not %s in : %s", d.Version, d.options.DriverDirectory)
}

// Command returns an exec.Cmd for the driver.
func (d *PatchrightDriver) Command(arg ...string) *exec.Cmd {
	cmd := exec.Command(getNodeExecutable(d.options), append([]string{getDriverCliJs(d.options)}, arg...)...)
	cmd.SysProcAttr = defaultSysProcAttr
	if d.options.BrowsersPath != "" {
		cmd.Env = append(os.Environ(), "PLAYWRIGHT_BROWSERS_PATH="+d.options.BrowsersPath)
	}
	return cmd
}

// Install downloads the driver and the browsers depending on [RunOptions].
func (d *PatchrightDriver) Install() error {
	if err := d.DownloadDriver(); err != nil {
		return fmt.Errorf("could not install driver: %w", err)
	}
	if d.options.SkipInstallBrowsers {
		return nil
	}

	d.log("Downloading browsers...")
	if err := d.installBrowsers(); err != nil {
		return fmt.Errorf("could not install browsers: %w", err)
	}
	d.log("Downloaded browsers successfully")

	return nil
}

// Uninstall removes the driver and the browsers.
func (d *PatchrightDriver) Uninstall() error {
	d.log("Removing browsers...")
	if err := d.uninstallBrowsers(); err != nil {
		return fmt.Errorf("could not uninstall browsers: %w", err)
	}

	d.log("Removing driver...")
	if err := os.RemoveAll(d.options.DriverDirectory); err != nil {
		return fmt.Errorf("could not remove driver directory: %w", err)
	}

	d.log("Uninstall driver successfully")
	return nil
}

// DownloadDriver downloads the driver only.
//
// The driver is assembled from two upstream sources:
//   - the platform-independent patchright package from the npm registry,
//     extracted into <DriverDirectory>/package (this contains cli.js); and
//   - the matching per-platform Node.js binary from nodejs.org, placed at
//     <DriverDirectory>/node[.exe].
//
// When PATCHRIGHT_NODEJS_PATH is set the Node.js download is skipped and the
// preinstalled Node.js is used instead, which also covers platforms for which
// nodejs.org has no prebuilt binary (e.g. linux/arm).
func (d *PatchrightDriver) DownloadDriver() error {
	up2Date, err := d.isUpToDateDriver()
	if err != nil {
		return err
	}
	if up2Date {
		return d.patchDriverBundle()
	}

	d.log("Downloading driver", "path", d.options.DriverDirectory)

	if err := d.downloadPatchrightPackage(); err != nil {
		return err
	}
	if err := d.downloadPatchrightCore(); err != nil {
		return err
	}
	if err := d.downloadNode(); err != nil {
		return err
	}

	d.log("Downloaded driver successfully")

	return d.patchDriverBundle()
}

// downloadPatchrightPackage downloads the platform-independent patchright
// package from the npm registry and extracts its "package/" contents into the
// driver directory, so that <DriverDirectory>/package/cli.js exists.
func (d *PatchrightDriver) downloadPatchrightPackage() error {
	url := fmt.Sprintf("%s/patchright/-/patchright-%s.tgz", npmRegistry(d.options), d.Version)
	body, err := downloadWithRetry(url)
	if err != nil {
		return fmt.Errorf("could not download patchright: %w", err)
	}

	gzReader, err := gzip.NewReader(bytes.NewReader(body))
	if err != nil {
		return fmt.Errorf("could not read patchright archive: %w", err)
	}
	defer gzReader.Close() //nolint:errcheck

	tarReader := tar.NewReader(gzReader)
	extracted := false
	for {
		header, err := tarReader.Next()
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			return fmt.Errorf("could not read patchright archive: %w", err)
		}
		// npm tarballs nest everything under a top-level "package/" directory,
		// which is exactly the layout the driver expects on disk.
		if header.Typeflag != tar.TypeReg || !strings.HasPrefix(header.Name, "package/") {
			continue
		}
		diskPath, err := safeJoin(d.options.DriverDirectory, header.Name)
		if err != nil {
			return err
		}
		if err := writeFileFromReader(diskPath, tarReader, header.FileInfo().Mode()); err != nil {
			return err
		}
		extracted = true
	}
	if !extracted {
		return fmt.Errorf("no files extracted from patchright %s", d.Version)
	}
	return nil
}

// downloadPatchrightCore downloads patchright-core, the actual driver
// implementation, and installs it as a node_module within the patchright
// package so that require('patchright-core') resolves correctly.
func (d *PatchrightDriver) downloadPatchrightCore() error {
	url := fmt.Sprintf("%s/patchright-core/-/patchright-core-%s.tgz", npmRegistry(d.options), d.Version)
	body, err := downloadWithRetry(url)
	if err != nil {
		return fmt.Errorf("could not download patchright-core: %w", err)
	}

	gzReader, err := gzip.NewReader(bytes.NewReader(body))
	if err != nil {
		return fmt.Errorf("could not read patchright-core archive: %w", err)
	}
	defer gzReader.Close() //nolint:errcheck

	// Extract into <DriverDirectory>/package/node_modules/patchright-core/
	// so that require('patchright-core') from the patchright package resolves.
	nodeModulesDir := filepath.Join(d.options.DriverDirectory, "package", "node_modules", "patchright-core")
	tarReader := tar.NewReader(gzReader)
	extracted := false
	for {
		header, err := tarReader.Next()
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			return fmt.Errorf("could not read patchright-core archive: %w", err)
		}
		if header.Typeflag != tar.TypeReg || !strings.HasPrefix(header.Name, "package/") {
			continue
		}
		relativePath := strings.TrimPrefix(header.Name, "package/")
		diskPath, err := safeJoin(nodeModulesDir, relativePath)
		if err != nil {
			return err
		}
		if err := writeFileFromReader(diskPath, tarReader, header.FileInfo().Mode()); err != nil {
			return err
		}
		extracted = true
	}
	if !extracted {
		return fmt.Errorf("no files extracted from patchright-core %s", d.Version)
	}
	return nil
}

// downloadNode downloads the per-platform Node.js binary. It is a no-op when
// NodeJSPath is set or PATCHRIGHT_NODEJS_PATH env var is set.
func (d *PatchrightDriver) downloadNode() error {
	if d.options.NodeJSPath != "" {
		d.log("Skipping Node.js download, using provided NodeJSPath")
		return nil
	}
	if os.Getenv("PATCHRIGHT_NODEJS_PATH") != "" {
		d.log("Skipping Node.js download, using PATCHRIGHT_NODEJS_PATH")
		return nil
	}

	suffix, err := nodePlatformSuffix()
	if err != nil {
		return err
	}

	archiveDir := fmt.Sprintf("node-v%s-%s", nodeVersion, suffix)
	isWindows := runtime.GOOS == "windows"
	ext := "tar.gz"
	if isWindows {
		ext = "zip"
	}
	url := fmt.Sprintf("%s/v%s/%s.%s", nodejsMirror(d.options), nodeVersion, archiveDir, ext)

	body, err := downloadWithRetry(url)
	if err != nil {
		return fmt.Errorf("could not download Node.js: %w", err)
	}

	node := "node"
	if isWindows {
		node = "node.exe"
	}
	nodeDiskPath := filepath.Join(d.options.DriverDirectory, node)
	if isWindows {
		return extractZipEntry(body, archiveDir+"/node.exe", nodeDiskPath)
	}
	return extractTarGzEntry(body, archiveDir+"/bin/node", nodeDiskPath)
}

func (d *PatchrightDriver) patchDriverBundle() error {
	coreBundlePath := filepath.Join(d.options.DriverDirectory, "package", "lib", "coreBundle.js")
	data, err := os.ReadFile(coreBundlePath)
	if err != nil {
		if os.IsNotExist(err) {
			return nil
		}
		return fmt.Errorf("could not read driver bundle: %w", err)
	}

	replacements := map[string]string{
		"pageError.location.url":          `pageError.location?.url || ""`,
		"pageError.location.lineNumber":   "pageError.location?.lineNumber || 0",
		"pageError.location.columnNumber": "pageError.location?.columnNumber || 0",
	}
	changed := false
	for original, patched := range replacements {
		originalBytes := []byte(original)
		patchedBytes := []byte(patched)
		if bytes.Contains(data, originalBytes) {
			data = bytes.ReplaceAll(data, originalBytes, patchedBytes)
			changed = true
		}
	}
	if !changed {
		alreadyPatched := true
		for _, patched := range replacements {
			if !bytes.Contains(data, []byte(patched)) {
				alreadyPatched = false
				break
			}
		}
		if alreadyPatched {
			return nil
		}
		return fmt.Errorf("could not patch driver bundle: pageError location pattern not found")
	}
	if err := os.WriteFile(coreBundlePath, data, 0o644); err != nil {
		return fmt.Errorf("could not write patched driver bundle: %w", err)
	}
	return nil
}

func (d *PatchrightDriver) log(msg string, args ...any) {
	if d.options.Verbose {
		d.options.Logger.Info(msg, args...)
	}
}

func (d *PatchrightDriver) run() (*connection, error) {
	transport, err := newPipeTransport(d, d.options.Stderr)
	if err != nil {
		return nil, err
	}
	connection := newConnection(transport)
	return connection, nil
}

func (d *PatchrightDriver) installBrowsers() error {
	additionalArgs := []string{"install"}
	if d.options.Browsers != nil {
		additionalArgs = append(additionalArgs, d.options.Browsers...)
	}

	if d.options.OnlyInstallShell {
		additionalArgs = append(additionalArgs, "--only-shell")
	}

	if d.options.NoInstallShell {
		additionalArgs = append(additionalArgs, "--no-shell")
	}

	if d.options.DryRun {
		additionalArgs = append(additionalArgs, "--dry-run")
	}

	if d.options.WithDeps {
		additionalArgs = append(additionalArgs, "--with-deps")
	}

	cmd := d.Command(additionalArgs...)
	cmd.Stdout = d.options.Stdout
	cmd.Stderr = d.options.Stderr
	return cmd.Run()
}

func (d *PatchrightDriver) uninstallBrowsers() error {
	cmd := d.Command("uninstall")
	cmd.Stdout = d.options.Stdout
	cmd.Stderr = d.options.Stderr
	return cmd.Run()
}

// RunOptions are custom options to run the driver
type RunOptions struct {
	// DriverDirectory is the path to the patchright driver directory.
	// Falls back to PATCHRIGHT_DRIVER_PATH env var, then <cwd>/bin/patchright-driver.
	DriverDirectory string
	// NodeJSPath overrides the Node.js binary path. Falls back to
	// PATCHRIGHT_NODEJS_PATH env var. Required on platforms without a prebuilt
	// Node.js binary (e.g. linux/arm).
	NodeJSPath string
	// CLIPath overrides the cli.js path. Falls back to PATCHRIGHT_CLI_PATH
	// env var. Useful for custom driver layouts.
	CLIPath string
	// Version overrides the patchright driver version to download and use.
	// When empty, the library's built-in default version is used.
	Version string
	// NpmRegistry overrides the npm registry URL for downloading the patchright
	// package. Falls back to PATCHRIGHT_NPM_REGISTRY env var. Default:
	// https://registry.npmjs.org
	NpmRegistry string
	// NodeMirror overrides the Node.js distribution mirror URL. Falls back to
	// NODE_MIRROR env var. Default: https://nodejs.org/dist
	NodeMirror string
	// BrowsersPath overrides where browsers are downloaded to.
	// Falls back to PLAYWRIGHT_BROWSERS_PATH env var, then the Playwright
	// default (~/.cache/ms-playwright on Linux).
	BrowsersPath string
	// OnlyInstallShell only downloads the headless shell. (For chromium browsers only)
	OnlyInstallShell bool
	// NoInstallShell does not install chromium headless shell. (For chromium browsers only)
	NoInstallShell      bool
	SkipInstallBrowsers bool
	// Browsers to install. Patchright only supports chromium-based browsers.
	// If not set and SkipInstallBrowsers is false, will download chromium.
	Browsers []string
	// install system dependencies for browsers
	WithDeps bool
	Verbose  bool // default true
	Stdout   io.Writer
	Stderr   io.Writer
	Logger   *slog.Logger
	// DryRun does not install browser/dependencies. It will only print information.
	DryRun bool
}

// Install downloads the driver and the browsers depending on [RunOptions].
//
// It is idempotent: if the driver and browsers are already present and
// up-to-date, the call is a fast no-op.
func Install(options ...*RunOptions) error {
	driver, err := NewDriver(options...)
	if err != nil {
		return fmt.Errorf("could not get driver instance: %w", err)
	}
	if err := driver.Install(); err != nil {
		return fmt.Errorf("could not install driver: %w", err)
	}
	return nil
}

// Run starts a Patchright instance.
//
// If the driver (or browsers) are not yet installed in [RunOptions.DriverDirectory],
// they are downloaded automatically. Subsequent calls with an up-to-date
// driver skip the download.
func Run(options ...*RunOptions) (*Patchright, error) {
	driver, err := NewDriver(options...)
	if err != nil {
		return nil, fmt.Errorf("could not get driver instance: %w", err)
	}
	if err := driver.Install(); err != nil {
		return nil, fmt.Errorf("could not install driver: %w", err)
	}
	connection, err := driver.run()
	if err != nil {
		return nil, err
	}
	playwright, err := connection.Start()
	return playwright, err
}

func transformRunOptions(options ...*RunOptions) (*RunOptions, error) {
	option := RunOptions{
		Verbose: true,
	}
	if len(options) == 1 {
		option = *options[0]
	}
	if option.OnlyInstallShell && option.NoInstallShell {
		return nil, fmt.Errorf("OnlyInstallShell and NoInstallShell cannot be set at the same time")
	}
	if option.Version == "" {
		option.Version = patchrightCliVersion
	}
	if option.DriverDirectory == "" {
		option.DriverDirectory = os.Getenv("PATCHRIGHT_DRIVER_PATH")
	}
	if option.DriverDirectory == "" {
		cwd, err := os.Getwd()
		if err != nil {
			return nil, fmt.Errorf("could not get working directory: %w", err)
		}
		option.DriverDirectory = filepath.Join(cwd, "bin", "patchright-driver")
	}
	if option.Stdout == nil {
		option.Stdout = os.Stdout
	}
	if option.Stderr == nil {
		option.Stderr = os.Stderr
	}
	if option.Logger == nil {
		option.Logger = slog.New(slog.NewTextHandler(option.Stderr, nil))
	}
	return &option, nil
}

func getNodeExecutable(options *RunOptions) string {
	if options.NodeJSPath != "" {
		return options.NodeJSPath
	}
	if envPath := os.Getenv("PATCHRIGHT_NODEJS_PATH"); envPath != "" {
		return envPath
	}

	node := "node"
	if runtime.GOOS == "windows" {
		node = "node.exe"
	}
	return filepath.Join(options.DriverDirectory, node)
}

func getDriverCliJs(options *RunOptions) string {
	if options.CLIPath != "" {
		return options.CLIPath
	}
	if envPath := os.Getenv("PATCHRIGHT_CLI_PATH"); envPath != "" {
		return envPath
	}
	return filepath.Join(options.DriverDirectory, "package", "cli.js")
}

func npmRegistry(options *RunOptions) string {
	if options.NpmRegistry != "" {
		return strings.TrimRight(options.NpmRegistry, "/")
	}
	if host := os.Getenv("PATCHRIGHT_NPM_REGISTRY"); host != "" {
		return strings.TrimRight(host, "/")
	}
	return defaultNpmRegistry
}

func nodejsMirror(options *RunOptions) string {
	if options.NodeMirror != "" {
		return strings.TrimRight(options.NodeMirror, "/")
	}
	if host := os.Getenv("NODE_MIRROR"); host != "" {
		return strings.TrimRight(host, "/")
	}
	return defaultNodejsDistHost
}

// nodePlatformSuffix maps the current GOOS/GOARCH to the suffix nodejs.org uses
// in its release archive names (e.g. "linux-x64", "darwin-arm64", "win-x64").
// Platforms without a prebuilt Node.js binary (such as linux/arm, 32-bit ARM)
// return an actionable error pointing at PATCHRIGHT_NODEJS_PATH.
func nodePlatformSuffix() (string, error) {
	var os_ string
	switch runtime.GOOS {
	case "windows":
		os_ = "win"
	case "darwin":
		os_ = "darwin"
	case "linux":
		os_ = "linux"
	default:
		return "", unsupportedNodePlatformError()
	}

	var arch string
	switch runtime.GOARCH {
	case "amd64":
		arch = "x64"
	case "arm64":
		arch = "arm64"
	default:
		// Notably linux/arm (32-bit, e.g. Raspberry Pi armv7l): nodejs.org no
		// longer ships a prebuilt binary, so we cannot download one.
		return "", unsupportedNodePlatformError()
	}

	return fmt.Sprintf("%s-%s", os_, arch), nil
}

func unsupportedNodePlatformError() error {
	return fmt.Errorf("no prebuilt Node.js %s is available for %s/%s; "+
		"install Node.js yourself and set PATCHRIGHT_NODEJS_PATH to its path",
		nodeVersion, runtime.GOOS, runtime.GOARCH)
}

// safeJoin joins an archive entry name onto root, guarding against path
// traversal ("zip slip"/"tar slip"): the resulting path must stay within root.
// This matters because PATCHRIGHT_NPM_REGISTRY / NODE_MIRROR allow arbitrary
// mirrors, so archive contents are not fully trusted.
func safeJoin(root, name string) (string, error) {
	diskPath := filepath.Join(root, filepath.FromSlash(name))
	prefix := filepath.Clean(root) + string(os.PathSeparator)
	if diskPath != filepath.Clean(root) && !strings.HasPrefix(diskPath, prefix) {
		return "", fmt.Errorf("invalid path in archive: %s", name)
	}
	return diskPath, nil
}

// writeFileFromReader writes the contents of r to diskPath, creating parent
// directories as needed and preserving the executable bit on non-Windows hosts.
func writeFileFromReader(diskPath string, r io.Reader, mode os.FileMode) error {
	if err := os.MkdirAll(filepath.Dir(diskPath), 0o777); err != nil {
		return fmt.Errorf("could not create directory: %w", err)
	}
	outFile, err := os.Create(diskPath)
	if err != nil {
		return fmt.Errorf("could not create file: %w", err)
	}
	if _, err := io.Copy(outFile, r); err != nil {
		outFile.Close() //nolint:errcheck
		return fmt.Errorf("could not write file: %w", err)
	}
	if err := outFile.Close(); err != nil {
		return fmt.Errorf("could not close file: %w", err)
	}
	if mode.Perm()&0o100 != 0 && runtime.GOOS != "windows" {
		if err := makeFileExecutable(diskPath); err != nil {
			return err
		}
	}
	return nil
}

// extractTarGzEntry extracts a single named entry from a gzipped tar archive to
// diskPath and marks it executable.
func extractTarGzEntry(archive []byte, entryName, diskPath string) error {
	gzReader, err := gzip.NewReader(bytes.NewReader(archive))
	if err != nil {
		return fmt.Errorf("could not read archive: %w", err)
	}
	defer gzReader.Close() //nolint:errcheck

	tarReader := tar.NewReader(gzReader)
	for {
		header, err := tarReader.Next()
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			return fmt.Errorf("could not read archive: %w", err)
		}
		if header.Name != entryName {
			continue
		}
		// Force the executable bit: the node binary must be runnable.
		return writeFileFromReader(diskPath, tarReader, header.FileInfo().Mode()|0o100)
	}
	return fmt.Errorf("could not find %s in archive", entryName)
}

// extractZipEntry extracts a single named entry from a zip archive to diskPath.
func extractZipEntry(archive []byte, entryName, diskPath string) error {
	zipReader, err := zip.NewReader(bytes.NewReader(archive), int64(len(archive)))
	if err != nil {
		return fmt.Errorf("could not read archive: %w", err)
	}
	for _, file := range zipReader.File {
		if file.Name != entryName {
			continue
		}
		rc, err := file.Open()
		if err != nil {
			return fmt.Errorf("could not open zip entry: %w", err)
		}
		err = writeFileFromReader(diskPath, rc, file.Mode())
		rc.Close() //nolint:errcheck
		return err
	}
	return fmt.Errorf("could not find %s in archive", entryName)
}

func makeFileExecutable(path string) error {
	stats, err := os.Stat(path)
	if err != nil {
		return fmt.Errorf("could not stat driver: %w", err)
	}
	if err := os.Chmod(path, stats.Mode()|0x40); err != nil {
		return fmt.Errorf("could not set permissions: %w", err)
	}
	return nil
}

// downloadWithRetry downloads url, retrying a few times on transient failures.
// It does not retry client errors (4xx), which are not transient.
func downloadWithRetry(url string) ([]byte, error) {
	var lastErr error
	for attempt := 1; attempt <= 3; attempt++ {
		body, retryable, err := download(url)
		if err == nil {
			return body, nil
		}
		lastErr = err
		if !retryable {
			break
		}
	}
	return nil, lastErr
}

// download fetches url. The returned bool reports whether a failure is worth
// retrying (network errors and 5xx are; 4xx are not).
func download(url string) ([]byte, bool, error) {
	resp, err := http.Get(url)
	if err != nil {
		return nil, true, fmt.Errorf("could not download from %s: %w", url, err)
	}
	defer resp.Body.Close() //nolint:errcheck
	if resp.StatusCode != http.StatusOK {
		retryable := resp.StatusCode >= 500
		return nil, retryable, fmt.Errorf("got non 200 status code: %d (%s) from %s", resp.StatusCode, resp.Status, url)
	}
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, true, fmt.Errorf("could not read response body: %w", err)
	}
	return body, false, nil
}