From 816ae140d62ab11ecb3ed858a2bfde52998f2573 Mon Sep 17 00:00:00 2001 From: Riddhesh Sanghvi Date: Thu, 19 Nov 2026 09:36:02 +0530 Subject: [PATCH 1/2] feat(site): add ee site php-compat to check a site's code against a PHP version `ee site php-compat --php=` runs the easyengine/compat-scanner image (PHPCompatibility) over a wp or php site's code and prints a verdict: safe to upgrade (every file checked, no errors), not safe (at least one error, listed per plugin, theme or other component with file, line, message and sniff), or can't confirm (some files couldn't be checked). Warnings don't change it. --format=json prints only the summary; --output writes the full report, root-owned 0600; --estimate prints how long a check should take; --timeout bounds the run (default 7200 s). Every printed result exits 0, including busy and tool_error; usage errors exit 1. The check runs in a throwaway container with no network, the site's code mounted read-only, uid 33, 1 GB of memory, 1 CPU, no capabilities and no core dumps. Its working directory is a fresh root-only directory under /opt/easyengine/tmp/php-compat/. One check and one estimate run per site at a time (a second one reports busy); a leftover of a killed check is removed by the next one, and a signal or a fatal error stops the container and removes the directory. ee validates the container's output and report before printing anything, and ee.log gets only the command lines and one result line, never findings. The image is pulled on first use, with the tag core pins in img-versions.json; after a pull, older scanner tags no container uses are removed. Until core pins the image, the command reports tool_error. --- composer.json | 1 + src/helper/Site_PHP_Compat.php | 1446 ++++++++++++++++++++++++++++++++ src/helper/class-ee-site.php | 87 ++ 3 files changed, 1534 insertions(+) create mode 100644 src/helper/Site_PHP_Compat.php diff --git a/composer.json b/composer.json index e68476f6..81a11ab0 100644 --- a/composer.json +++ b/composer.json @@ -23,6 +23,7 @@ "src/helper/Site_Self_Signed.php", "src/helper/Site_Letsencrypt.php", "src/helper/Site_Backup_Restore.php", + "src/helper/Site_PHP_Compat.php", "src/helper/Shutdown_Handler.php", "src/clone/Cloner.php", "src/clone/clone-utils.php" diff --git a/src/helper/Site_PHP_Compat.php b/src/helper/Site_PHP_Compat.php new file mode 100644 index 00000000..c8a506b4 --- /dev/null +++ b/src/helper/Site_PHP_Compat.php @@ -0,0 +1,1446 @@ +site = $site_data->site_url; + $this->target = (string) get_flag_value( $assoc_args, 'php', '' ); + $this->estimate = (bool) get_flag_value( $assoc_args, 'estimate', false ); + $format = get_flag_value( $assoc_args, 'format', 'table' ); + $output = get_flag_value( $assoc_args, 'output', null ); + $timeout = get_flag_value( $assoc_args, 'timeout', null ); + + // The dispatcher drops a valueless optional flag with only a warning; the runner still has it. + $raw = (array) EE::get_runner()->assoc_args; + foreach ( [ 'format', 'output', 'timeout' ] as $key ) { + if ( ! array_key_exists( $key, $assoc_args ) && isset( $raw[ $key ] ) && true === $raw[ $key ] ) { + EE::error( "--$key needs a value." ); + } + } + if ( ! in_array( $site_data->site_type, self::SITE_TYPES, true ) ) { + EE::error( "ee site php-compat supports wp and php sites; {$this->site} is a {$site_data->site_type} site." ); + } + // The dispatcher compares loosely, so `--php=8` or `--php=8.10` (== 8.1) would pass its check. + if ( ! in_array( $this->target, self::php_versions(), true ) ) { + EE::error( 'Invalid --php value. Use one of: ' . implode( ', ', self::php_versions() ) . '.' ); + } + if ( ! in_array( $format, [ 'table', 'json' ], true ) ) { + EE::error( 'Invalid --format value. Use table or json.' ); + } + if ( $this->estimate && ( null !== $output || null !== $timeout ) ) { + EE::error( '--output and --timeout don\'t apply to --estimate.' ); + } + if ( null === $timeout ) { + $timeout = self::DEFAULT_TIMEOUT; + } elseif ( ! is_string( $timeout ) || ! preg_match( '/^[1-9][0-9]{0,8}$/', $timeout ) ) { + EE::error( '--timeout must be a positive whole number of seconds.' ); + } + if ( null !== $output ) { + $output = $this->validate_output_path( $output ); + } + + $this->dispatch = $dispatch; + if ( null !== $dispatch && 'json' === $format ) { + self::keep_stdout_for_json(); + } + + delem_log( 'site php-compat start' ); + EE::debug( sprintf( 'php-compat: site %s, PHP %s, %s', $this->site, $this->target, $this->estimate ? 'estimate' : "scan, timeout $timeout s" ) ); + $started = microtime( true ); + + try { + $result = $this->estimate ? $this->run_estimate( $site_data ) : $this->run_scan( $site_data, (int) $timeout, $output ); + } finally { + $this->cleanup(); + } + + if ( 'json' === $format ) { + echo self::encode( $result['doc'] ) . "\n"; + } elseif ( $this->estimate ) { + echo $this->estimate_text( $result['doc'] ); + } else { + // Line by line: a large report isn't copied into one more string. + foreach ( $this->table_lines( $result['doc'], $result['report'] ) as $line ) { + echo $line, "\n"; + } + } + + $this->log_result( $result['doc'], microtime( true ) - $started ); + delem_log( 'site php-compat end' ); + } + + /** + * The --php values of this command's docblock, the same list as `ee site update --php`. + * + * @return string[] + */ + public static function php_versions() { + $doc = ( new \ReflectionMethod( EE_Site_Command::class, 'php_compat' ) )->getDocComment(); + $options = ( new \EE\DocParser( $doc ) )->get_param_args( 'php' ); + + // YAML reads 8.0 as a float. + return array_map( + function ( $version ) { + return is_float( $version ) ? number_format( $version, 1, '.', '' ) : (string) $version; + }, + isset( $options['options'] ) ? $options['options'] : [] + ); + } + + /** + * Refuse an --output the report couldn't be written to, before the scan runs. + * + * @param string $output --output value. + * + * @return string The path. + */ + protected function validate_output_path( $output ) { + $output = (string) $output; + if ( '' === $output || '/' !== $output[0] ) { + EE::error( '--output must be an absolute path.' ); + } + $name = basename( $output ); + if ( '/' === substr( $output, -1 ) || '' === $name || '.' === $name || '..' === $name ) { + EE::error( '--output must name a file.' ); + } + $dir = realpath( dirname( $output ) ); + if ( false === $dir || ! is_dir( $dir ) ) { + EE::error( 'The directory of --output does not exist: ' . dirname( $output ) ); + } + if ( is_dir( $output ) && ! is_link( $output ) ) { + EE::error( "--output is a directory: $output" ); + } + // tempnam() falls back to the system temp dir when $dir isn't writable (read-only mount, not root). + $probe = @tempnam( $dir, '.ee-php-compat-' ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- checked below. + $writable = false !== $probe && realpath( dirname( $probe ) ) === $dir; + if ( false !== $probe ) { + @unlink( $probe ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged + } + if ( ! $writable ) { + EE::error( 'The directory of --output is not writable: ' . dirname( $output ) ); + } + $stat = stat( $dir ); + $this->output_dir = [ + 'path' => $dir, + 'dev' => $stat['dev'], + 'ino' => $stat['ino'], + ]; + + return $output; + } + + /** + * @param object $site_data Site record. + * @param int $timeout --timeout. + * @param string $output --output path, or null. + * + * @return array 'doc' (summary to print) and 'report' (decoded report, ok only). + */ + protected function run_scan( $site_data, $timeout, $output ) { + + $image = $this->image(); + if ( null === $image ) { + return $this->doc( 'tool_error', 'no ' . self::IMAGE . ' tag in img-versions.json' ); + } + $code = $this->code_dir( $site_data->site_fs_path ); + if ( null === $code ) { + return $this->doc( 'no_code_found' ); + } + if ( false !== strpbrk( $code, ',"' ) ) { + return $this->doc( 'tool_error', 'the site code path has a comma or a quote' ); + } + + // Two EE runs can't both pass the container check below and then clear each other's directory as a leftover. + if ( ! $this->lock_site( $site_data->site_fs_path ) ) { + return $this->doc( 'busy' ); + } + $name = 'ee-php-compat-' . $this->site; + $status = $this->container_status( $name ); + if ( 'running' === $status ) { + return $this->doc( 'busy' ); + } + if ( 'exited' === $status ) { + EE::debug( "Removing the leftover container $name." ); + // Known limit: a container whose --rm is still in progress can't be removed again, which reads as this tool_error. + if ( 0 !== $this->docker( [ 'docker', 'rm', '-f', $name ], 60 )['code'] ) { + return $this->doc( 'tool_error', "could not remove the leftover container $name" ); + } + } + + if ( ! $this->ensure_image( $image ) ) { + return $this->doc( 'tool_error', 'image pull failed' ); + } + + $out = $this->make_temp_dir(); + if ( null === $out ) { + return $this->doc( 'tool_error', 'could not create the temporary directory' ); + } + if ( false !== strpbrk( $out, ',"' ) ) { + return $this->doc( 'tool_error', 'the temporary directory path has a comma or a quote' ); + } + + // From here until cleanup() confirms it is gone, /out may be in use by this container. + $this->active_container = $name; + $run = $this->docker( $this->docker_run_args( 'scan', $image, $site_data, $code, $out, $timeout ), $timeout + self::PROCESS_MARGIN, true ); + if ( $run['timed_out'] ) { + return $this->doc( 'tool_error', "timed out after $timeout s" ); + } + + // Docker refuses a taken name before creating anything, so nothing is printed, and the other container exists. + if ( 125 === $run['code'] && '' === trim( $run['stdout'] ) && false !== stripos( $run['stderr'], 'Conflict' ) && false !== strpos( $run['stderr'], $name ) && false !== $this->container_status( $name ) ) { + // That container is another run's: leave it alone. + $this->active_container = null; + + return $this->doc( 'busy' ); + } + + $doc = empty( $run['overflow'] ) ? $this->parse_document( $run['stdout'] ) : null; + if ( null === $doc || ! $this->valid_scan_doc( $doc ) ) { + return $this->doc( 'tool_error', self::exit_detail( $run, 'without a valid result' ) ); + } + if ( 'ok' !== $doc['status'] ) { + return $this->doc( $doc['status'], 'tool_error' === $doc['status'] ? $doc['detail'] : null ); + } + + // The container ended (docker run --rm returns once it is removed), so nothing changes /out any more. + $file = $out . '/report.json'; + clearstatcache( true, $file ); + $size = @filesize( $file ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- a missing file is refused below. + if ( false !== $size && $size > self::REPORT_MAX ) { + return $this->doc( 'tool_error', 'the report is larger than ' . ( self::REPORT_MAX >> 20 ) . ' MiB' ); + } + + $raw = null; + $report = null; + try { + self::raise_memory_limit(); + $raw = \EE\Site\Utils\get_container_file_contents( $file, $out, self::REPORT_MAX ); + if ( self::decode_cost( $raw ) > $this->memory_available() ) { + return $this->doc( 'tool_error', sprintf( 'the report (%s) needs more memory to read than is available', self::size( strlen( $raw ) ) ) ); + } + $report = json_decode( $raw, true, 512, self::JSON_UTF8 ); + } catch ( \Exception $e ) { + EE::debug( 'php-compat report: ' . self::clean( $e->getMessage() ) ); + } + if ( ! is_array( $report ) || ! $this->valid_report( $report, $doc ) ) { + return $this->doc( 'tool_error', self::exit_detail( $run, 'without a valid report' ) ); + } + + $summary = $this->summary( $doc ); + if ( null !== $output ) { + if ( ! $this->write_report( $output, $raw ) ) { + return $this->doc( 'tool_error', "could not write the report to $output" ); + } + $summary['report'] = $output; + $summary['report_bytes'] = strlen( $raw ); + } + + return [ + 'doc' => $summary, + 'report' => $report, + ]; + } + + /** + * @param object $site_data Site record. + * + * @return array 'doc' (estimate to print) and 'report' (always null). + */ + protected function run_estimate( $site_data ) { + + $image = $this->image(); + if ( null === $image ) { + return $this->doc( 'tool_error', 'no ' . self::IMAGE . ' tag in img-versions.json' ); + } + $code = $this->code_dir( $site_data->site_fs_path ); + if ( null === $code ) { + return $this->doc( 'no_code_found' ); + } + if ( false !== strpbrk( $code, ',"' ) ) { + return $this->doc( 'tool_error', 'the site code path has a comma or a quote' ); + } + // One estimate per site at a time; it never waits for a scan. + $locked = $this->lock_estimate(); + if ( null === $locked ) { + return $this->doc( 'tool_error', 'could not create the estimate lock' ); + } + if ( ! $locked ) { + return $this->doc( 'busy' ); + } + if ( ! $this->ensure_image( $image ) ) { + return $this->doc( 'tool_error', 'image pull failed' ); + } + + $run = $this->docker( $this->docker_run_args( 'estimate', $image, $site_data, $code ), self::ESTIMATE_TIMEOUT + self::PROCESS_MARGIN, true ); + if ( $run['timed_out'] ) { + return $this->doc( 'tool_error', 'timed out after ' . self::ESTIMATE_TIMEOUT . ' s' ); + } + + $doc = empty( $run['overflow'] ) ? $this->parse_document( $run['stdout'] ) : null; + if ( null === $doc || ! $this->valid_estimate_doc( $doc ) ) { + return $this->doc( 'tool_error', self::exit_detail( $run, 'without a valid result' ) ); + } + if ( 'ok' !== $doc['status'] ) { + return $this->doc( $doc['status'], 'tool_error' === $doc['status'] ? $doc['detail'] : null ); + } + + return [ + 'doc' => $this->with_site( self::pick( $doc, self::ESTIMATE_KEYS ) ), + 'report' => null, + ]; + } + + /** + * The `docker run` command line. Estimates have no name, so they never conflict, and no /out. + * + * @param string $mode scan or estimate. + * @param string $image Image with tag. + * @param object $site_data Site record. + * @param string $code Real path of the site's code. + * @param string|null $out Directory mounted at /out (scan only). + * @param int|null $timeout --timeout (scan only). + * + * @return string[] + */ + public function docker_run_args( $mode, $image, $site_data, $code, $out = null, $timeout = null ) { + $args = [ 'docker', 'run', '--rm', '--init' ]; + if ( 'scan' === $mode ) { + array_push( $args, '--name', 'ee-php-compat-' . $this->site ); + } + // No log driver: the daemon would otherwise keep its own unbounded copy of the container's stdout. + array_push( + $args, + '--network', 'none', '--log-driver', 'none', '--read-only', '--tmpfs', '/tmp:size=64m', + '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '64', + '--memory', '1g', '--memory-swap', '1g', '--cpus', '1', '--cpu-shares', '256', + '--ulimit', 'core=0', + '--user', '33:33', + // The scanner stops at the same report size EE accepts. + '-e', 'COMPAT_SITE=' . $this->site, '-e', 'COMPAT_IMAGE=' . $image, '-e', 'COMPAT_REPORT_MAX=' . self::REPORT_MAX, + '--mount', "type=bind,src=$code,dst=/var/www,readonly" + ); + if ( 'scan' === $mode ) { + array_push( $args, '--mount', "type=bind,src=$out,dst=/out" ); + } + array_push( $args, $image, $mode, $site_data->site_type, $site_data->site_container_fs_path, $this->target ); + if ( 'scan' === $mode ) { + $args[] = (string) $timeout; + } + + return $args; + } + + /** + * @return string|null Image with its tag from img-versions.json. + */ + protected function image() { + $versions = \EE\Utils\get_image_versions(); + + return empty( $versions[ self::IMAGE ] ) ? null : self::IMAGE . ':' . $versions[ self::IMAGE ]; + } + + /** + * `app` is a symlink to the htdocs volume; Docker needs its real path. + * + * @param string $site_fs_path Site directory. + * + * @return string|null Real path, or null when it isn't a directory. + */ + protected function code_dir( $site_fs_path ) { + $real = realpath( $site_fs_path . '/app' ); + + return ( false !== $real && is_dir( $real ) ) ? $real : null; + } + + /** + * @param string $site_fs_path Site directory. + * + * @return bool False when another php-compat run holds it. + */ + protected function lock_site( $site_fs_path ) { + $handle = @fopen( $site_fs_path, 'r' ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- handled below. + if ( false === $handle ) { + EE::debug( "Could not open $site_fs_path to lock it; relying on the container name." ); + + return true; + } + if ( ! flock( $handle, LOCK_EX | LOCK_NB, $would_block ) ) { + fclose( $handle ); + if ( ! $would_block ) { + EE::debug( "Could not lock $site_fs_path; relying on the container name." ); + + return true; + } + + return false; + } + $this->lock = $handle; + + return true; + } + + /** + * @return bool|null False when another estimate of the site holds the lock; null when the lock file can't be made. + */ + protected function lock_estimate() { + $parent = $this->temp_parent(); + // Not in the per-site directory, whose leftovers a scan removes; a site name never starts with a dot. + $handle = null === $parent ? false : @fopen( "$parent/.estimate-{$this->site}.lock", 'c' ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- handled below. + if ( false === $handle ) { + return null; + } + if ( ! flock( $handle, LOCK_EX | LOCK_NB, $would_block ) ) { + fclose( $handle ); + if ( ! $would_block ) { + EE::debug( "Could not lock the estimate of {$this->site}; running without the lock." ); + + return true; + } + + return false; + } + $this->lock = $handle; + + return true; + } + + /** + * @param string $name Container name. + * + * @return string|false running, exited, or false when there is none. + */ + protected function container_status( $name ) { + return \EE_DOCKER::container_status( $name ); + } + + /** + * Remove a container if it still exists and confirm it is gone. + * + * @param string $name Container name. + * + * @return bool + */ + protected function container_gone( $name ) { + $this->docker( [ 'docker', 'rm', '-f', $name ], 60 ); + for ( $try = 1; ; $try++ ) { + if ( false === $this->container_status( $name ) ) { + return true; + } + if ( 3 === $try ) { + return false; + } + sleep( 1 ); + } + } + + /** + * Pull on first use; most servers never run a check, so a fresh install doesn't pull it. + * + * @param string $image Image with tag. + * + * @return bool Whether it is present. + */ + protected function ensure_image( $image ) { + if ( 0 === $this->docker( [ 'docker', 'image', 'inspect', '--format', '{{.Id}}', $image ], 60 )['code'] ) { + return true; + } + EE::debug( "Pulling $image." ); + if ( 0 !== $this->docker( [ 'docker', 'pull', $image ], self::PULL_TIMEOUT )['code'] ) { + return false; + } + $this->remove_other_tags( $image ); + + return true; + } + + /** + * After pulling a new tag, remove the scanner's other tags that no container uses; failures only cost disk. + * + * @param string $image The pinned image with its tag, never removed. + */ + protected function remove_other_tags( $image ) { + $list = $this->docker( [ 'docker', 'image', 'ls', '--format', '{{.Tag}}', self::IMAGE ], 60 ); + if ( 0 !== $list['code'] ) { + EE::debug( 'Could not list the ' . self::IMAGE . ' tags.' ); + + return; + } + foreach ( array_unique( preg_split( '/\s+/', trim( $list['stdout'] ), -1, PREG_SPLIT_NO_EMPTY ) ) as $tag ) { + $old = self::IMAGE . ':' . $tag; + if ( $old === $image || ! preg_match( '/^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/', $tag ) ) { + continue; + } + $users = $this->docker( [ 'docker', 'ps', '-a', '-q', '--filter', "ancestor=$old" ], 60 ); + if ( 0 !== $users['code'] || '' !== trim( $users['stdout'] ) ) { + EE::debug( "Keeping $old: a container uses it." ); + continue; + } + // Without -f, Docker also refuses an image a container started in the meantime. + if ( 0 !== $this->docker( [ 'docker', 'image', 'rm', $old ], 60 )['code'] ) { + EE::debug( "Could not remove $old." ); + } + } + } + + /** + * This run's /out: a new random directory in a root-only per-site directory, after removing what a killed run left there. + * + * Only called with the site lock held and no container of the site left, so nothing else uses that directory. + * + * @return string|null Its real path. + */ + protected function make_temp_dir() { + $parent = $this->temp_parent(); + if ( null === $parent ) { + return null; + } + $site_dir = $parent . '/' . $this->site; + if ( ! $this->own_dir( $site_dir ) ) { + EE::debug( "Refusing $site_dir as a temporary directory: not a directory of this user with mode 0700." ); + + return null; + } + + foreach ( array_diff( (array) @scandir( $site_dir ), [ '.', '..', false ] ) as $entry ) { // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- an unreadable dir has nothing to remove. + EE::debug( "Removing the leftover temporary directory $site_dir/" . self::clean( $entry ) . '.' ); + // One that can't be removed doesn't block this run: it gets its own directory. + $this->remove_tree( "$site_dir/$entry" ); + } + + $dir = $site_dir . '/' . bin2hex( random_bytes( 8 ) ); + if ( ! @mkdir( $dir, 0700 ) ) { // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- reported as tool_error. + return null; + } + $this->temp_dir = $dir; + $this->register_cleanup(); + clearstatcache( true, $dir ); + // Without root (macOS), Docker Desktop's file sharing maps the owner itself. + if ( is_link( $dir ) || ! is_dir( $dir ) || ! chmod( $dir, 0700 ) || ( 0 === self::euid() && ! ( chown( $dir, 33 ) && chgrp( $dir, 33 ) ) ) ) { + return null; + } + $real = realpath( $dir ); + if ( false === $real ) { + return null; + } + $this->temp_dir = $real; + + return $real; + } + + /** + * @return string|null EE_ROOT_DIR/tmp/php-compat, checked to be root-only; null when it isn't. + */ + protected function temp_parent() { + $base = rtrim( $this->temp_base(), '/' ); + foreach ( [ $base, $base . '/' . self::TEMP_DIR ] as $dir ) { + if ( ! $this->own_dir( $dir ) ) { + EE::debug( "Refusing $dir as a temporary directory: not a directory of this user with mode 0700." ); + + return null; + } + } + + return $base . '/' . self::TEMP_DIR; + } + + /** + * Create a directory 0700 when missing, and accept it only as a real directory of this user that no one else can enter. + * + * @param string $dir Path. + * + * @return bool + */ + protected function own_dir( $dir ) { + @mkdir( $dir, 0700 ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- it may exist; checked below. + clearstatcache( true, $dir ); + $stat = @lstat( $dir ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- checked below. + $euid = self::euid(); + if ( ! $stat || 0040000 !== ( $stat['mode'] & 0170000 ) || ( null !== $euid && $stat['uid'] !== $euid ) ) { + return false; + } + + return 0 === ( $stat['mode'] & 0077 ) || chmod( $dir, 0700 ); + } + + /** + * Remove a tree without following symlinks: rm's *at() calls also survive a directory swapped mid-way and any depth. + * + * @param string $path Path. + * + * @return bool Whether it is gone. + */ + protected function remove_tree( $path ) { + $argv = ( defined( 'IS_DARWIN' ) && IS_DARWIN ) ? [ 'rm', '-rf', '--', $path ] : [ 'rm', '-rf', '--one-file-system', '--', $path ]; + $run = $this->run_process( $argv, 600 ); + clearstatcache( true, $path ); + if ( file_exists( $path ) || is_link( $path ) ) { + // stderr can hold names chosen inside the container. + EE::debug( 'rm: ' . self::clean( trim( $run['stderr'] ) ) ); + + return false; + } + + return true; + } + + /** + * @return string Base directory with a trailing slash. + */ + protected function temp_base() { + return EE_ROOT_DIR . '/tmp/'; + } + + /** + * Run a docker command without EE::exec()/EE::launch(), which would copy its output into ee.log. + * + * @param string[] $argv Command and arguments. + * @param int $timeout Seconds. + * @param bool $bounded Stop it once stdout or stderr passes its cap. + * + * @return array code (int|null), stdout, stderr, timed_out, overflow, signal (int|null). + */ + protected function docker( array $argv, $timeout, $bounded = false ) { + EE::debug( 'COMMAND: ' . implode( ' ', array_map( 'escapeshellarg', $argv ) ) ); + $run = $this->run_process( $argv, $timeout, $bounded ); + EE::debug( 'RETURN CODE: ' . var_export( $run['code'], true ) ); + + return $run; + } + + /** + * @param string[] $argv Command and arguments. + * @param int $timeout Seconds. + * @param bool $bounded Stop it once stdout or stderr passes its cap. + * + * @return array See docker(). + */ + protected function run_process( array $argv, $timeout, $bounded = false ) { + $result = [ + 'code' => null, + 'stdout' => '', + 'stderr' => '', + 'timed_out' => false, + 'overflow' => false, + 'signal' => null, + ]; + $process = new Process( $argv ); + $process->setTimeout( $timeout ); + // Process keeps its own copy of all output unless disabled; the callback keeps a capped one. + $process->disableOutput(); + try { + $process->start( + function ( $type, $buffer ) use ( &$result ) { + $key = Process::OUT === $type ? 'stdout' : 'stderr'; + $max = 'stdout' === $key ? self::STDOUT_MAX : self::STDERR_MAX; + // One callback can carry everything a fast writer produced since the last read. + $room = $max + 1 - strlen( $result[ $key ] ); + if ( $room > 0 ) { + $result[ $key ] .= substr( $buffer, 0, $room ); + } + if ( strlen( $result[ $key ] ) > $max ) { + $result['overflow'] = true; + } + } + ); + // wait() never dispatches signals, so poll: SIGTERM/SIGINT then reach the command's handlers, whose exit runs cleanup(). + while ( $process->isRunning() ) { + if ( ! $this->cleaning && function_exists( 'pcntl_signal_dispatch' ) ) { + null === $this->dispatch ? pcntl_signal_dispatch() : call_user_func( $this->dispatch ); + } + $process->checkTimeout(); + if ( $bounded && $result['overflow'] ) { + $process->stop( 0 ); + + return $result; + } + usleep( 20000 ); + } + $process->wait(); + $result['code'] = $process->getExitCode(); + } catch ( ProcessTimedOutException $e ) { + $result['timed_out'] = true; + } catch ( ProcessSignaledException $e ) { + $result['signal'] = $e->getSignal(); + } catch ( \Exception $e ) { + EE::debug( 'Could not run ' . $argv[0] . ': ' . self::clean( $e->getMessage() ) ); + } + + return $result; + } + + /** + * @param string $stdout Container stdout. + * + * @return array|null One JSON object with v and status. + */ + protected function parse_document( $stdout ) { + if ( strlen( $stdout ) > self::STDOUT_MAX ) { + return null; + } + $doc = json_decode( trim( $stdout ), true, 32, self::JSON_UTF8 ); + if ( ! is_array( $doc ) || array_values( $doc ) === $doc || ! array_key_exists( 'v', $doc ) || ! array_key_exists( 'status', $doc ) ) { + return null; + } + + return $doc; + } + + /** + * @param array $doc Container stdout document. + * + * @return bool + */ + protected function valid_scan_doc( array $doc ) { + if ( 1 !== $doc['v'] || ! in_array( $doc['status'], self::SCAN_STATUSES, true ) ) { + return false; + } + if ( 'tool_error' === $doc['status'] ) { + return isset( $doc['detail'] ) && is_string( $doc['detail'] ); + } + if ( 'ok' !== $doc['status'] ) { + return true; + } + if ( ! isset( $doc['target'] ) || $this->target !== $doc['target'] || ! array_key_exists( 'safe_to_upgrade', $doc ) || ! isset( $doc['tool'] ) || ! is_array( $doc['tool'] ) ) { + return false; + } + foreach ( self::SUMMARY_INTS as $key ) { + if ( ! isset( $doc[ $key ] ) || ! is_int( $doc[ $key ] ) || $doc[ $key ] < 0 ) { + return false; + } + } + if ( $doc['errors'] > 0 ) { + $verdict = false; + } else { + $verdict = $doc['files_not_checked'] > 0 ? null : true; + } + + return $verdict === $doc['safe_to_upgrade']; + } + + /** + * @param array $doc Container stdout document. + * + * @return bool + */ + protected function valid_estimate_doc( array $doc ) { + if ( 1 !== $doc['v'] || ! in_array( $doc['status'], self::SCAN_STATUSES, true ) ) { + return false; + } + if ( 'tool_error' === $doc['status'] ) { + return isset( $doc['detail'] ) && is_string( $doc['detail'] ); + } + if ( 'ok' !== $doc['status'] ) { + return true; + } + if ( ! isset( $doc['estimate'], $doc['target'], $doc['inputs'] ) || true !== $doc['estimate'] || $this->target !== $doc['target'] || ! is_array( $doc['inputs'] ) ) { + return false; + } + foreach ( self::ESTIMATE_INTS as $key ) { + if ( ! isset( $doc[ $key ] ) || ! is_int( $doc[ $key ] ) || $doc[ $key ] < 0 ) { + return false; + } + } + + return true; + } + + /** + * The report must carry the stdout summary, and its lists must add up to it. + * + * @param array $report Decoded /out/report.json. + * @param array $doc Validated stdout summary. + * + * @return bool + */ + protected function valid_report( array $report, array $doc ) { + foreach ( $doc as $key => $value ) { + if ( ! array_key_exists( $key, $report ) || $report[ $key ] !== $value ) { + return false; + } + } + if ( ! isset( $report['components'], $report['not_checked'] ) || ! is_array( $report['components'] ) || ! is_array( $report['not_checked'] ) ) { + return false; + } + if ( count( $report['components'] ) !== $doc['components_checked'] || count( $report['not_checked'] ) !== $doc['files_not_checked'] ) { + return false; + } + $errors = 0; + $warnings = 0; + $with_errors = 0; + foreach ( $report['components'] as $component ) { + if ( ! is_array( $component ) || ! self::valid_place( $component ) || ! isset( $component['errors'], $component['warnings'], $component['findings'] ) || ! is_int( $component['errors'] ) || ! is_int( $component['warnings'] ) || ! is_array( $component['findings'] ) ) { + return false; + } + foreach ( [ 'name', 'version' ] as $key ) { + if ( ! array_key_exists( $key, $component ) || ! ( null === $component[ $key ] || is_string( $component[ $key ] ) ) ) { + return false; + } + } + $counts = [ + 'ERROR' => 0, + 'WARNING' => 0, + ]; + foreach ( $component['findings'] as $finding ) { + if ( ! is_array( $finding ) || ! isset( $finding['file'], $finding['line'], $finding['type'], $finding['source'], $finding['message'] ) || ! is_string( $finding['file'] ) || ! is_int( $finding['line'] ) || ! in_array( $finding['type'], [ 'ERROR', 'WARNING' ], true ) || ! is_string( $finding['source'] ) || ! is_string( $finding['message'] ) ) { + return false; + } + ++$counts[ $finding['type'] ]; + } + // Every error and warning is listed, so the component's counts are its findings'. + if ( $counts['ERROR'] !== $component['errors'] || $counts['WARNING'] !== $component['warnings'] ) { + return false; + } + $errors += $component['errors']; + $warnings += $component['warnings']; + $with_errors += $component['errors'] > 0 ? 1 : 0; + } + foreach ( $report['not_checked'] as $entry ) { + if ( ! is_array( $entry ) || ! self::valid_place( $entry ) || ! isset( $entry['file'], $entry['reason'] ) || ! is_string( $entry['file'] ) || ! is_string( $entry['reason'] ) ) { + return false; + } + } + + return $errors === $doc['errors'] && $warnings === $doc['warnings'] && $with_errors === $doc['components_with_errors']; + } + + /** + * @param array $item Component or not_checked entry. + * + * @return bool Whether type, slug and branch have the right types. + */ + private static function valid_place( array $item ) { + return isset( $item['type'], $item['slug'] ) && is_string( $item['type'] ) && is_string( $item['slug'] ) && array_key_exists( 'branch', $item ) && ( null === $item['branch'] || is_string( $item['branch'] ) ); + } + + /** + * Upper bound of what json_decode() allocates: a non-empty array or object costs far more than its bytes. + * + * @param string $raw JSON. + * + * @return int Bytes. + */ + protected static function decode_cost( $raw ) { + $nodes = substr_count( $raw, '{' ) + substr_count( $raw, '[' ); + + // Measured on 7.4 and 8.5: up to ~450 per array or object, ~80 per element (hash growth), ~40 per string, plus the bytes. + return strlen( $raw ) + $nodes * 450 + ( substr_count( $raw, ',' ) + $nodes ) * 80 + (int) ( substr_count( $raw, '"' ) / 2 ) * 40; + } + + /** + * @return int Bytes the report may still take: up to MEMORY_FLOOR when there is no limit. + */ + protected function memory_available() { + $limit = self::bytes( ini_get( 'memory_limit' ) ); + + return ( $limit > 0 ? $limit : self::MEMORY_FLOOR ) - memory_get_usage(); + } + + /** + * Write the report as root, 0600, through a temporary file and a rename, into the directory validated at the start. + * + * @param string $path --output. + * @param string $content Report, byte for byte. + * + * @return bool + */ + protected function write_report( $path, $content ) { + $dir = $this->output_dir['path']; + if ( ! $this->output_dir_unchanged( $path ) ) { + EE::debug( "The directory of $path changed during the check." ); + + return false; + } + $tmp = @tempnam( $dir, '.ee-php-compat-' ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- checked below. + if ( false === $tmp ) { + return false; + } + $this->output_tmp = $tmp; + $written = @file_put_contents( $tmp, $content ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- checked below. + // Checked again right before the rename, so a directory swapped for a symlink meanwhile isn't written through. + $ok = realpath( dirname( $tmp ) ) === $dir && strlen( $content ) === $written && chmod( $tmp, 0600 ) && ( 0 !== self::euid() || ( chown( $tmp, 0 ) && chgrp( $tmp, 0 ) ) ) && $this->output_dir_unchanged( $path ) && @rename( $tmp, $dir . '/' . basename( $path ) ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- reported as tool_error. + if ( ! $ok ) { + @unlink( $tmp ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged + } + $this->output_tmp = null; + + return $ok; + } + + /** + * @param string $path --output. + * + * @return bool Whether its directory still resolves to the one validated at the start. + */ + protected function output_dir_unchanged( $path ) { + clearstatcache(); + $real = realpath( dirname( $path ) ); + $stat = false === $real ? false : @stat( $real ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- checked below. + + return $real === $this->output_dir['path'] && $stat && $stat['dev'] === $this->output_dir['dev'] && $stat['ino'] === $this->output_dir['ino']; + } + + /** + * Container scan summary to print: findings never, `site` always. + * + * @param array $doc Validated stdout summary. + * + * @return array + */ + protected function summary( array $doc ) { + return $this->with_site( self::pick( $doc, self::SUMMARY_KEYS ) ); + } + + /** + * Only the documented keys, in their order; tool strings and estimate input numbers only. + * + * @param array $doc Validated document. + * @param string[] $keys Keys to keep. + * + * @return array + */ + protected static function pick( array $doc, array $keys ) { + $picked = []; + foreach ( $keys as $key ) { + if ( array_key_exists( $key, $doc ) ) { + $picked[ $key ] = $doc[ $key ]; + } + } + if ( isset( $picked['tool'] ) ) { + $picked['tool'] = array_filter( array_intersect_key( $picked['tool'], array_flip( self::TOOL_KEYS ) ), 'is_string' ); + } + if ( isset( $picked['inputs'] ) ) { + $picked['inputs'] = array_filter( + array_intersect_key( $picked['inputs'], array_flip( self::INPUT_KEYS ) ), + function ( $value ) { + return is_int( $value ) || is_float( $value ); + } + ); + } + + return $picked; + } + + /** + * Put `site` after v, status and estimate, whatever the container sent. + * + * @param array $doc Document. + * + * @return array + */ + protected function with_site( array $doc ) { + $head = [ + 'v' => $doc['v'], + 'status' => $doc['status'], + ]; + if ( array_key_exists( 'estimate', $doc ) ) { + $head['estimate'] = $doc['estimate']; + } + $head['site'] = $this->site; + + return $head + $doc; + } + + /** + * A document other than `ok`: only v, status, site, target, safe_to_upgrade and, for tool_error, detail. + * + * @param string $status busy, no_code_found or tool_error. + * @param string|null $detail tool_error only. + * + * @return array 'doc' and 'report'. + */ + protected function doc( $status, $detail = null ) { + $doc = [ + 'v' => 1, + 'status' => $status, + ]; + if ( $this->estimate ) { + $doc['estimate'] = true; + } + $doc += [ + 'site' => $this->site, + 'target' => $this->target, + 'safe_to_upgrade' => null, + ]; + if ( 'tool_error' === $status ) { + $doc['detail'] = (string) $detail; + } + + return [ + 'doc' => $doc, + 'report' => null, + ]; + } + + /** + * Detail of a tool_error EE reports for the container: its exit code and, for Docker's own errors, Docker's message. + * + * @param array $run docker() result. + * @param string $what What was missing. + * + * @return string + */ + protected static function exit_detail( array $run, $what ) { + if ( ! empty( $run['overflow'] ) ) { + return 'the scanner printed more output than a result can have'; + } + if ( ! empty( $run['signal'] ) ) { + return "the scanner was interrupted by signal {$run['signal']}"; + } + if ( null === $run['code'] ) { + return 'the scanner could not be started'; + } + $detail = "the scanner exited with code {$run['code']} $what"; + // 125-127 come from Docker itself, not from the scanned code. + if ( in_array( $run['code'], [ 125, 126, 127 ], true ) && '' !== trim( $run['stderr'] ) ) { + $line = strtok( trim( $run['stderr'] ), "\n" ); + $detail .= ': ' . self::clean( strlen( $line ) > 300 ? substr( $line, 0, 300 ) . '...' : $line ); + } + + return $detail; + } + + /** + * The table, for tests and callers that want one string. + * + * @param array $doc Summary. + * @param array|null $report Decoded report (ok only). + * + * @return string + */ + protected function table( array $doc, $report ) { + return implode( "\n", iterator_to_array( $this->table_lines( $doc, $report ), false ) ) . "\n"; + } + + /** + * @param array $doc Summary. + * @param array|null $report Decoded report (ok only). + * + * @return \Generator Lines without newlines. + */ + protected function table_lines( array $doc, $report ) { + $site = $this->site; + $target = $this->target; + switch ( $doc['status'] ) { + case 'busy': + yield "A check of $site is already running."; + return; + case 'no_code_found': + yield "No PHP code found to check in $site."; + return; + case 'tool_error': + yield "The check of $site for PHP $target didn't finish: " . self::clean( $doc['detail'] ); + return; + } + + $tail = sprintf( '%s. %s checked.', self::count_of( $doc['warnings'], 'warning' ), self::count_of( $doc['files_checked'], 'file' ) ); + if ( false === $doc['safe_to_upgrade'] ) { + yield sprintf( 'Not safe to upgrade %s to PHP %s: %s in %s. %s', $site, $target, self::count_of( $doc['errors'], 'error' ), self::count_of( $doc['components_with_errors'], 'component' ), $tail ); + } elseif ( true === $doc['safe_to_upgrade'] ) { + yield sprintf( 'Safe to upgrade %s to PHP %s: 0 errors. %s', $site, $target, $tail ); + } else { + $could = 1 === $doc['files_not_checked'] ? 'file couldn\'t' : 'files couldn\'t'; + yield sprintf( 'Can\'t confirm %s is safe for PHP %s: %d %s be checked. %s', $site, $target, $doc['files_not_checked'], $could, $tail ); + } + yield ''; + + $warnings_only = []; + foreach ( $report['components'] as $component ) { + if ( $component['errors'] > 0 ) { + yield sprintf( '%s: %s, %s', self::component_heading( $component ), self::count_of( $component['errors'], 'error' ), self::count_of( $component['warnings'], 'warning' ) ); + foreach ( $component['findings'] as $finding ) { + if ( 'ERROR' !== $finding['type'] ) { + continue; + } + yield ' ' . self::clean( $finding['file'] ) . ':' . $finding['line']; + yield ' ' . self::clean( $finding['message'] ); + yield ' ' . self::clean( $finding['source'] ); + } + yield ''; + } elseif ( $component['warnings'] > 0 ) { + $warnings_only[] = self::component_name( $component ) . ' (' . $component['warnings'] . ')'; + } + } + if ( $warnings_only ) { + yield 'Warnings only: ' . implode( ', ', $warnings_only ); + yield ''; + } + + if ( $report['not_checked'] ) { + yield 'Not checked:'; + foreach ( $report['not_checked'] as $entry ) { + yield ' ' . self::place( $entry ) . ': ' . self::clean( $entry['file'] ) . ' (' . self::clean( $entry['reason'] ) . ')'; + } + yield ''; + } + + if ( isset( $doc['report'] ) ) { + yield 'Full report: ' . $doc['report']; + yield ''; + } + + $tool = isset( $doc['tool']['phpcompatibility'] ) && is_string( $doc['tool']['phpcompatibility'] ) ? ' ' . self::clean( $doc['tool']['phpcompatibility'] ) : ''; + yield "This is static analysis with PHPCompatibility$tool. Its coverage isn't complete and it can't see breakage that only shows at runtime."; + } + + /** + * @param array $doc Estimate document. + * + * @return string + */ + protected function estimate_text( array $doc ) { + $site = $this->site; + $target = $this->target; + switch ( $doc['status'] ) { + case 'busy': + return "An estimate for $site is already running.\n"; + case 'no_code_found': + return "No PHP code found to check in $site.\n"; + case 'tool_error': + return "Couldn't estimate a check of $site for PHP $target: " . self::clean( $doc['detail'] ) . "\n"; + } + + return sprintf( + "A check of %s for PHP %s should take %s: %s, %s, %s. This is an estimate.\n", + $site, + $target, + self::duration( $doc['estimated_seconds'], $doc['estimated_seconds_low'], $doc['estimated_seconds_high'] ), + self::count_of( $doc['php_files'], 'PHP file', true ), + self::size( $doc['php_bytes'] ), + self::count_of( $doc['components'], 'component', true ) + ); + } + + /** + * "about 3 minutes (2 to 4)", in one unit for all three. + * + * @return string + */ + public static function duration( $seconds, $low, $high ) { + if ( $high < 120 ) { + list( $unit, $name, $precision ) = [ 1, 'second', 0 ]; + } elseif ( $seconds < 5400 ) { + list( $unit, $name, $precision ) = [ 60, 'minute', 0 ]; + } else { + list( $unit, $name, $precision ) = [ 3600, 'hour', 1 ]; + } + $value = function ( $s ) use ( $unit, $precision ) { + return max( $precision ? 0.1 : 1, round( $s / $unit, $precision ) ); + }; + $main = $value( $seconds ); + + return sprintf( 'about %s %s%s (%s to %s)', $main, $name, 1 == $main ? '' : 's', $value( $low ), $value( $high ) ); + } + + /** + * @return string "87 MB", "6.9 MB", "512 KB". + */ + public static function size( $bytes ) { + $mb = $bytes / 1048576; + if ( $mb >= 10 ) { + return round( $mb ) . ' MB'; + } + if ( $mb >= 1 ) { + return round( $mb, 1 ) . ' MB'; + } + + return max( 1, (int) round( $bytes / 1024 ) ) . ' KB'; + } + + /** + * @return string "1 error", "3 errors", "14,614 PHP files". + */ + protected static function count_of( $n, $noun, $separators = false ) { + return ( $separators ? number_format( $n ) : $n ) . " $noun" . ( 1 === $n ? '' : 's' ); + } + + /** + * @return string "WPForms Lite 1.9.2 (plugin wpforms-lite)", "mu-plugins (mu-plugin)". + */ + protected static function component_heading( array $component ) { + $detail = $component['type']; + if ( null !== $component['name'] && '' !== $component['slug'] ) { + $detail .= ' ' . $component['slug']; + } + if ( null !== $component['branch'] ) { + $detail .= ', branch ' . $component['branch']; + } + + return self::component_name( $component ) . ' (' . self::clean( $detail ) . ')'; + } + + /** + * @return string Name and version, or the slug, or "other files". + */ + protected static function component_name( array $component ) { + if ( null !== $component['name'] && '' !== $component['name'] ) { + $name = $component['name']; + } else { + $name = '' !== $component['slug'] ? $component['slug'] : 'other files'; + } + if ( null !== $component['version'] && '' !== $component['version'] ) { + $name .= ' ' . $component['version']; + } + + return self::clean( $name ); + } + + /** + * @return string "plugin huge-plugin", "other, branch main". + */ + protected static function place( array $entry ) { + $place = $entry['type'] . ( '' !== $entry['slug'] ? ' ' . $entry['slug'] : '' ) . ( null !== $entry['branch'] ? ', branch ' . $entry['branch'] : '' ); + + return self::clean( $place ); + } + + /** + * Text from the scanned code must not drive the terminal: control, bidi and zero-width characters become '?'. + * + * @param string $text Text. + * + * @return string + */ + public static function clean( $text ) { + $text = (string) $text; + // Invalid UTF-8 would make the /u pattern fail, and a raw 0x9B byte is a C1 CSI. + if ( ! preg_match( '//u', $text ) ) { + $text = preg_replace( '/[\x80-\xFF]/', '?', $text ); + } + + return preg_replace( '/[\x00-\x1F\x7F' . self::UNSAFE_CHARS . ']/u', '?', $text ); + } + + /** + * One line of JSON, with characters a terminal would act on escaped (the data stays the same). + * + * @return string + */ + public static function encode( array $doc ) { + $json = json_encode( $doc, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | self::JSON_UTF8 ); + + return preg_replace_callback( + '/[' . self::UNSAFE_CHARS . ']/u', + function ( $char ) { + return substr( json_encode( $char[0] ), 1, -1 ); + }, + $json + ); + } + + /** + * Command, target, duration, verdict and counts only; findings and details never reach ee.log. + * + * @param array $doc Printed document. + * @param float $elapsed Seconds. + */ + protected function log_result( array $doc, $elapsed ) { + $counts = ''; + $keys = $this->estimate ? [ 'php_files', 'php_bytes', 'components', 'estimated_seconds' ] : [ 'errors', 'warnings', 'files_checked', 'files_not_checked', 'components_with_errors' ]; + foreach ( $keys as $key ) { + if ( isset( $doc[ $key ] ) && is_int( $doc[ $key ] ) ) { + $counts .= ", $key {$doc[ $key ]}"; + } + } + EE::debug( + sprintf( + 'php-compat %s of %s for PHP %s: status %s, safe_to_upgrade %s%s, %d s.', + $this->estimate ? 'estimate' : 'scan', + $this->site, + $this->target, + $doc['status'], + var_export( isset( $doc['safe_to_upgrade'] ) ? $doc['safe_to_upgrade'] : null, true ), + $counts, + (int) round( $elapsed ) + ) + ); + } + + /** + * @param string|false $value php.ini size such as 128M. + * + * @return int Bytes; -1 for no limit. + */ + protected static function bytes( $value ) { + $value = trim( (string) $value ); + if ( '-1' === $value || '' === $value ) { + return -1; + } + $bytes = (int) $value; + switch ( strtolower( substr( $value, -1 ) ) ) { + case 'g': + $bytes *= 1024; + // Fall through. + case 'm': + $bytes *= 1024; + // Fall through. + case 'k': + $bytes *= 1024; + } + + return $bytes; + } + + /** + * Raise PHP's memory limit to at least MEMORY_FLOOR before reading a report. + */ + protected static function raise_memory_limit() { + $limit = self::bytes( ini_get( 'memory_limit' ) ); + if ( $limit > 0 && $limit < self::MEMORY_FLOOR ) { + ini_set( 'memory_limit', (string) self::MEMORY_FLOOR ); + } + } + + /** + * With --format=json stdout holds the document or nothing: a signal ends the run in rollback(), whose "Success:" line goes to stderr instead. + */ + protected static function keep_stdout_for_json() { + $runner = EE::get_runner(); + if ( ! empty( $runner->config['quiet'] ) ) { + return; + } + EE::set_logger( + new class( $runner->in_color() ) extends \EE\Loggers\Regular { + public function info( $message ) { + $this->write( STDERR, $message . "\n" ); + } + + public function success( $message ) { + $this->_line( $message, 'Success', '%G', STDERR ); + } + } + ); + } + + /** + * @return int|null Effective uid, null without the posix extension. + */ + protected static function euid() { + return function_exists( 'posix_geteuid' ) ? posix_geteuid() : null; + } + + protected function register_cleanup() { + if ( ! $this->cleanup_registered ) { + $this->cleanup_registered = true; + // EE::error() exits without running finally blocks. EE_Site_Command::shut_down_function() also calls cleanup(), before its rollback() exits. + register_shutdown_function( [ $this, 'cleanup' ] ); + } + } + + /** + * Remove a scan container that may still exist, then, once it is gone, the temporary directory; release the lock. Safe to call twice. + */ + public function cleanup() { + $this->cleaning = true; + if ( null !== $this->active_container ) { + $name = $this->active_container; + $this->active_container = null; + // /out is the container's until it is gone: never remove it under a running one. + if ( ! $this->container_gone( $name ) && null !== $this->temp_dir ) { + EE::warning( "Left {$this->temp_dir} in place: the container $name could not be removed." ); + $this->temp_dir = null; + } + } + if ( null !== $this->temp_dir ) { + $dir = $this->temp_dir; + $this->temp_dir = null; + if ( $this->remove_tree( $dir ) ) { + // The per-site directory, once empty. + @rmdir( dirname( $dir ) ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged -- a leftover in it keeps it. + } else { + EE::warning( "Could not remove $dir." ); + } + } + if ( null !== $this->output_tmp ) { + @unlink( $this->output_tmp ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged + $this->output_tmp = null; + } + if ( null !== $this->lock ) { + flock( $this->lock, LOCK_UN ); + fclose( $this->lock ); + $this->lock = null; + } + $this->cleaning = false; + } +} diff --git a/src/helper/class-ee-site.php b/src/helper/class-ee-site.php index f34b1546..cc3c2284 100644 --- a/src/helper/class-ee-site.php +++ b/src/helper/class-ee-site.php @@ -86,6 +86,11 @@ abstract class EE_Site_Command { */ private static $le_renewal_started = false; + /** + * @var Site_PHP_Compat|null $php_compat_check The running `site php-compat`, cleaned up on a fatal error or a signal. + */ + private $php_compat_check; + public function __construct() { $this->fs = new Filesystem(); @@ -2892,6 +2897,14 @@ protected function shut_down_function( $error = null ) { if ( null === $error ) { $error = error_get_last(); } + // rollback() below and the signal handlers exit, so later shutdown functions, like the check's own, wouldn't run. + if ( null !== $this->php_compat_check ) { + if ( isset( $error['type'] ) && E_ERROR === $error['type'] ) { + // After running out of memory, cleanup() needs some to stop the container. + @ini_set( 'memory_limit', '-1' ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged + } + $this->php_compat_check->cleanup(); + } $logger = \EE::get_file_logger()->withName( 'site-command' ); // Check if the $this->site_data is set and it is array and $this->site_data['site_url'] is set. @@ -3219,6 +3232,80 @@ public function sync( $args, $assoc_args ) { } } + /** + * Checks a site's PHP code for compatibility with a PHP version. + * + * Runs PHPCompatibility in a throwaway container with no network against a read-only mount of the site's code: plugins, themes, mu-plugins, drop-ins and other code under wp-content for WordPress sites (not WordPress core), everything under htdocs for PHP sites. It ends with a verdict: safe to upgrade (every file checked, no errors), not safe (at least one error), or can't confirm (some files couldn't be checked). Warnings never change the verdict. The verdict comes from static analysis, which can't see breakage that only shows at runtime. + * + * The command exits 0 whenever it printed a result, including when a check of the site is already running (`busy`) or the check couldn't run (`tool_error`). + * + * ## OPTIONS + * + * [] + * : Name of the website. + * + * --php= + * : PHP version to check the code against. + * --- + * options: + * - 5.6 + * - 7.0 + * - 7.2 + * - 7.3 + * - 7.4 + * - 8.0 + * - 8.1 + * - 8.2 + * - 8.3 + * - 8.4 + * - 8.5 + * --- + * + * [--estimate] + * : Print how long a check of this site should take on this server, without checking anything. + * + * [--format=] + * : Render output in a particular format. json prints the verdict and the counts, never the findings. + * --- + * default: table + * options: + * - table + * - json + * --- + * + * [--output=] + * : Also write the full report, with every error and warning, as JSON to this absolute path. The file is owned by root with mode 0600 and replaces an existing one. It is written only when the check finishes with a result (status ok); otherwise an existing file is left as it was. Not with --estimate. + * + * [--timeout=] + * : Safety limit for the whole check, in seconds. A check that hits it reports tool_error and no verdict. Default: 7200. Not with --estimate. + * + * ## EXAMPLES + * + * # Check whether a site's code works on PHP 8.4 + * $ ee site php-compat example.com --php=8.4 + * + * # See how long the check will take first + * $ ee site php-compat example.com --php=8.4 --estimate + * + * # Print the summary as JSON and write the full report to a file + * $ ee site php-compat example.com --php=8.4 --format=json --output=/root/example.com-php84.json + * + * @subcommand php-compat + */ + public function php_compat( $args, $assoc_args ) { + $args = auto_site_name( $args, 'site', 'php-compat' ); + $this->site_data = get_site_info( $args, false, true, false ); + $this->php_compat_check = new Site_PHP_Compat(); + // Dispatched from this class's scope: the SIGTERM/SIGINT handlers are the site type's protected rollback(). + $this->php_compat_check->run( + $this->site_data, + $assoc_args, + function () { + pcntl_signal_dispatch(); + } + ); + } + /** * Function to take backup of site. * From 69ad6a1bb8775208714806d13faf0597bc051724 Mon Sep 17 00:00:00 2001 From: Riddhesh Sanghvi Date: Thu, 19 Nov 2026 10:16:03 +0530 Subject: [PATCH 2/2] test(behat): cover ee site php-compat 12 scenarios (16 with the outline) on wp and php sites: the JSON summary, the table's first and last lines, --output (root 0600, replaces a stale file, matches the summary), no finding text in ee.log, an html site and bad --php values refused, busy while a check of the same site runs, --estimate beside a running check, --timeout leaving nothing behind, and the leftovers of a killed check removed by the next one. New steps: background commands, running a command without logging it, file owner and mode, JSON file vs STDOUT, text appended to a log, generated PHP files, and the scanner image (pulled with the tag core pins when missing). Scenarios that ran checks remove the suite's php-compat containers and temporary directories afterwards. The scan scenarios need core's img-versions.json to pin a published easyengine/compat-scanner tag. --- features/COVERAGE.md | 40 ++- features/bootstrap/FeatureContext.php | 363 +++++++++++++++++++++++++- features/php-compat.feature | 212 +++++++++++++++ 3 files changed, 604 insertions(+), 11 deletions(-) create mode 100644 features/php-compat.feature diff --git a/features/COVERAGE.md b/features/COVERAGE.md index e00f0f0c..e493fff8 100644 --- a/features/COVERAGE.md +++ b/features/COVERAGE.md @@ -1,24 +1,24 @@ # site-command Behat coverage -Suite for `easyengine/site-command` (the `ee site` command and the html site type). 18 features, 179 scenarios (211 with outlines expanded): main lane 190, `@wp` 10, `@le` 11. Run it the CI way (`.github/workflows/behat.yml`): the files are copied into a core checkout's `features/` and core's `vendor/bin/behat` runs from the core root as root. +Suite for `easyengine/site-command` (the `ee site` command and the html site type, plus `ee site php-compat` on php and wp sites). 19 features, 191 scenarios (227 with outlines expanded): main lane 204, `@wp` 12, `@le` 11. Run it the CI way (`.github/workflows/behat.yml`): the files are copied into a core checkout's `features/` and core's `vendor/bin/behat` runs from the core root as root. ## Tags | Tag | Scenarios | Meaning | |---|---|---| -| (none of the tags below) | 171 | Local only: `*.test` sites, no public DNS, no remote storage, no global restarts. This is the default safe run. | +| (none of the tags below) | 181 | Local only: `*.test` sites, no public DNS, no remote storage, no global restarts. This is the default safe run. The php-compat scenarios pull the scanner image from Docker Hub when it isn't present. | | `@known-bug` | 0 | Scenarios that expose open bugs are kept outside this suite and come back with their fixes. The CI lanes still exclude the tag. | | `@destructive` | 12 | Restarts the GLOBAL nginx-proxy (proxy cache) or runs `ssl-renew --all` (refuses to start when an enabled LE site that isn't the suite's exists). Every scenario leaves the proxy running. | | `@remote` | 10 | Uses the REAL rclone remote (`rclone-path` in config.yml). Touches only `/bh-site-command-*`: the rclone path is listed first and only listed suite directories are purged (per site before a scenario, all of them after the feature). | | `@le` | 11 | Let's Encrypt issuance on `*.ee4-test.rt.gw`. Locally: real LE, at most 4 certificates per full run; names contain `{RUN_ID}`, so repeated runs never hit the duplicate-certificate limit. On CI all 11 run against Pebble (`.github/behat/pebble-setup.sh`: EE's hardcoded LE host is redirected to Pebble, `{LE_ISSUER}` comes from `EE_BEHAT_LE_ISSUER`). The failed-alias rollback and the ACME cleanup on delete are regression checks for EasyEngine/site-command#505. | | `@le-real` | 0 | Needs the public LE service itself (rate limits, the real chain); never runs on CI. None so far: every `@le` scenario works on Pebble. | -| `@wp` | 10 | Needs the `wp` site type (site-type-wp in the core checkout) and `ee` on PATH; slow. | +| `@wp` | 12 | Needs the `wp` site type (site-type-wp in the core checkout) and `ee` on PATH; slow. | Default safe run: `--tags='~@le&&~@remote&&~@destructive&&~@wp'`. ## Environment rules -- Every site, alias, hosts entry and remote backup path contains `bh-site-command-`. `@AfterFeature` deletes only sites matching `(^|\.)bh-site-command-`, never other sites; once none is left it also removes suite-named leftovers of known bugs (proxy `certs/`, `acme-conf/certs|var/`, site dirs, volumes labelled with a suite name); `@remote` features also purge the listed `/bh-site-command-*` directories. `@AfterScenario` removes hosts entries the scenario added, the scenario's `{TMP}` dir under `/var/tmp`, and `{BACKUP_DIR}/bh-site-command-*` leftovers. +- Every site, alias, hosts entry and remote backup path contains `bh-site-command-`. `@AfterFeature` deletes only sites matching `(^|\.)bh-site-command-`, never other sites; once none is left it also removes suite-named leftovers of known bugs (proxy `certs/`, `acme-conf/certs|var/`, site dirs, volumes labelled with a suite name); `@remote` features also purge the listed `/bh-site-command-*` directories. `@AfterScenario` removes hosts entries the scenario added, the scenario's `{TMP}` dir under `/var/tmp`, and `{BACKUP_DIR}/bh-site-command-*` leftovers; it also ends a background command the scenario left running and, after php-compat scans, removes `ee-php-compat-bh-site-command-*` containers and `{EE_ROOT_DIR}/tmp/php-compat/bh-site-command-*` directories. - The file-writing, hosts, delete and rclone steps refuse names and paths without the prefix (or outside `{TMP}`). - HTTP steps resolve the site name to 127.0.0.1 (whitelisted, so no HTTP auth, and no /etc/hosts entry needed); `through the public IP` goes through `hostname -I` instead; `verified` uses real DNS and full TLS verification (LE only). Redirects are never followed. - Waits poll (`I wait up to N seconds for URL to return CODE`, `... until the command ... succeeds`); there are no fixed sleeps, except `I wait for the next second` between back-to-back backups of one site (backup ids have one-second resolution). @@ -29,20 +29,20 @@ Default safe run: `--tags='~@le&&~@remote&&~@destructive&&~@wp'`. ## Estimated runtime (4 CPU test host) -html create about 15-20 s, delete 5-10 s, proxy-cache toggle 10-15 s (proxy restart), html backup/restore 15-40 s, WordPress create 1.5-2.5 min, LE issuance 30-60 s. +html create about 15-20 s, php create 20-30 s, delete 5-10 s, proxy-cache toggle 10-15 s (proxy restart), html backup/restore 15-40 s, WordPress create 1.5-2.5 min, php-compat scan of the 5,000-file fixture 1-1.5 min (first run: plus the scanner image pull), LE issuance 30-60 s. | Selection | Estimate | |---|---| -| Default safe run | ~40 min | +| Default safe run | ~45 min | | `@destructive` | ~7 min | | `@remote` (html part) | ~7 min | -| `@wp` (clone/sync + WP backup/restore) | ~16 min | +| `@wp` (clone/sync + WP backup/restore + php-compat on WP) | ~19 min | | `@le` | ~6 min | -| Everything | ~75-80 min | +| Everything | ~85-90 min | ## Inventory and mapping -Legend: covered / partial / not covered (reason). Feature files are abbreviated: site, create, delete, list, info, en-dis (enable-disable), rr (restart-reload), alias (update-alias), ussl (update-ssl-php), pcache (proxy-cache), clean, share, ssl, redirect, labels, backup (backup-restore), clone (clone-sync), le. +Legend: covered / partial / not covered (reason). Feature files are abbreviated: site, create, delete, list, info, en-dis (enable-disable), rr (restart-reload), alias (update-alias), ussl (update-ssl-php), pcache (proxy-cache), clean, share, ssl, redirect, labels, backup (backup-restore), clone (clone-sync), le, compat (php-compat). ### Routing and global behaviour (`Site_Command::__invoke`, hooks.php) @@ -218,13 +218,33 @@ Legend: covered / partial / not covered (reason). Feature files are abbreviated: | clone `--ssl=...`, `--wildcard`, cert copy, admin-tools/mailhog replication | not covered | same-host clone of an SSL WP site is possible but slow; LE options need the LE budget | | Remote clone/sync over SSH, production guard (`env: production`), non-JSON site list output, inherit-site checks on the other host | not covered | needs a second SSH-reachable EE host (or a fake ssh shim); the production guard needs a global config change | +### php-compat + +Every scan scenario needs core's `img-versions.json` to pin `easyengine/compat-scanner` and that image locally or pullable (`Given the compat-scanner image is available`). What the scanner itself finds (scope, components, retries, the `null` verdict) is covered by the image's fixture test in `EasyEngine/dockerfiles`. + +| Item | Status | Scenarios | +|---|---|---| +| `--format=json` on a wp and a php site: one-line summary, exit 0, no findings | covered (wp part @wp) | compat: The JSON summary of a WordPress site; The JSON summary of a php site | +| Table: verdict line first ("Not safe", "Safe"), every error with file, line and sniff, static-analysis line last | covered ("Not safe" part @wp) | compat: The table starts with the verdict line...; The table of a php site without errors says it is safe | +| "Can't confirm" verdict line | not covered | needs a file uid 33 can't read; the scanner side is in the dockerfiles fixture test | +| `--output`: root-owned 0600, replaces an existing file, same fields as the summary, `report`/`report_bytes` | covered | compat: --output writes a root-owned 0600 report... | +| No finding text in ee.log | covered | compat: ee.log holds no finding text after a check with findings | +| html site refused, bad or missing `--php` (dispatcher and command checks) | covered | compat: An html site is refused; A bad --php value is rejected (outline) | +| `busy` while a scan of the same site runs (json and table) | covered | compat: A second check while one of the same site runs reports busy | +| `--estimate` (json and table) while a scan of the same site runs | covered | compat: --estimate prints its JSON while a check of the same site runs | +| `--timeout`: `tool_error`, exit 0, no temporary directory or container left | covered | compat: No temporary directory or container is left behind... | +| Leftover temporary directory and stopped container of a killed run removed | covered | compat: A leftover of a killed check is removed by the next check | +| Invalid `--output`/`--timeout`, `--output` or `--timeout` with `--estimate` | not covered | usage errors raised before Docker runs; not in the spec's scenario list | +| Disabled site can be scanned | not covered | not in the spec's scenario list | +| Image pull on first use, failed pull (`tool_error`) | not covered | needs a missing image or no route to Docker Hub | + ### Not in scope DB and container migrations under `migrations/` (core upgrade flow), the AcmePhp repository classes (only through LE scenarios), macOS-only code. ## Coverage estimate -Counting the rows above as items: 124 items, 91 covered, 1 partial, 32 not covered (8 of them, marked "not covered yet", are open bugs whose scenarios come back with their fixes), i.e. about 73% of the inventory. Every user-facing subcommand and option of the html type has at least one scenario except `ssl-renew --force`, `clone --ssl/--wildcard` and a live `share`. +Counting the rows above as items: 137 items, 100 covered, 1 partial, 36 not covered (8 of them, marked "not covered yet", are open bugs whose scenarios come back with their fixes), i.e. about 73% of the inventory. Every user-facing subcommand and option of the html type has at least one scenario except `ssl-renew --force`, `clone --ssl/--wildcard` and a live `share`. ## Known bugs left out diff --git a/features/bootstrap/FeatureContext.php b/features/bootstrap/FeatureContext.php index 0b70cd03..ac438fe1 100644 --- a/features/bootstrap/FeatureContext.php +++ b/features/bootstrap/FeatureContext.php @@ -124,6 +124,27 @@ class FeatureContext implements Context */ private static $run_id = ''; + /** + * Command started by "I start ... in the background": proc, stdout and stderr files, command, start time, exit code. + * + * @var array|null + */ + private $background = null; + + /** + * Byte offsets noted by "I note the size of the file ...". + * + * @var array + */ + private $noted_sizes = []; + + /** + * Whether the scenario ran php-compat scans, whose containers and temporary directories are purged afterwards. + * + * @var bool + */ + private $compat_used = false; + /** * Initializes context. */ @@ -444,7 +465,7 @@ public function thereShouldBeContainersWithLabel($expected_running_containers, P * * Written to be copied as-is into other packages' contexts: only SITE_PREFIX changes. * Every string argument goes through v(), so {NAME} variables work everywhere: - * built-ins are {EE}, {EE_ROOT_DIR}, {SITES_DIR}, {PROXY_DIR}, {BACKUP_DIR}, {TMP}, {RUN_ID}, {PUBLIC_IP}, + * built-ins are {EE}, {EE_ROOT_DIR}, {SITES_DIR}, {PROXY_DIR}, {BACKUP_DIR}, {TMP}, {SYS_TMP}, {RUN_ID}, {PUBLIC_IP}, * {RCLONE_PATH} and {LE_ISSUER}; others come from the "I save ..." steps. * ===================================================================== */ @@ -458,6 +479,8 @@ public function prepareScenario( BeforeScenarioScope $scope ) $this->variables = []; $this->response = null; $this->start_times = []; + $this->noted_sizes = []; + $this->compat_used = false; } /** @@ -473,6 +496,12 @@ public function cleanupScenario(AfterScenarioScope $scope) } $this->added_hosts = []; + // Before {TMP} goes: the background command writes its output there. + $this->stop_background(); + if ( $this->compat_used ) { + self::purge_compat_leftovers(); + } + if ( $this->tmp_dir && 0 === strpos( $this->tmp_dir, '/var/tmp/' . self::SITE_PREFIX ) ) { EE::launch( 'rm -rf ' . escapeshellarg( $this->tmp_dir ), false, true ); } @@ -1387,8 +1416,337 @@ public function iDownloadTheRemoteBackup( $backup_id, $site ) } } + /* ----- background commands, logs and php-compat ----- */ + + /** + * Runs a command like "I run", but without EE::launch(), which copies the command and its output into ee.log. + * + * @When /^I run (['"])(.*)\1 without logging it$/ + */ + public function iRunWithoutLoggingIt( $quote, $command ) + { + $this->commands[] = \EE\Process::create( $this->v( $command ), null, null )->run(); + } + + /** + * One command at a time; "I wait up to N seconds for the background command to finish" makes it the last command. + * + * @When /^I start (['"])(.*)\1 in the background$/ + */ + public function iStartInTheBackground( $quote, $command ) + { + if ( null !== $this->background ) { + throw new Exception( 'A background command is already running in this scenario.' ); + } + $command = $this->v( $command ); + $out = $this->tmp_dir . '/background.stdout'; + $err = $this->tmp_dir . '/background.stderr'; + $proc = proc_open( $command, [ 0 => [ 'file', '/dev/null', 'r' ], 1 => [ 'file', $out, 'w' ], 2 => [ 'file', $err, 'w' ] ], $pipes ); + if ( ! is_resource( $proc ) ) { + throw new Exception( "Could not start $command" ); + } + $this->background = [ + 'proc' => $proc, + 'stdout' => $out, + 'stderr' => $err, + 'command' => $command, + 'start' => microtime( true ), + 'exitcode' => null, + ]; + } + + /** + * @Then the background command should still be running + */ + public function theBackgroundCommandShouldStillBeRunning() + { + if ( ! $this->background_running() ) { + throw new Exception( "The background command has already finished.\n" . $this->describe( $this->background_result() ) ); + } + } + + /** + * @When /^I wait up to (\d+) seconds for the background command to finish$/ + */ + public function iWaitForTheBackgroundCommandToFinish( $seconds ) + { + $deadline = time() + (int) $seconds; + while ( $this->background_running() ) { + if ( time() >= $deadline ) { + throw new Exception( "The background command is still running after $seconds seconds: " . $this->background['command'] ); + } + usleep( 200000 ); + } + $this->commands[] = $this->background_result(); + proc_close( $this->background['proc'] ); + $this->background = null; + } + + /** + * @When /^I note the size of the file "([^"]*)"$/ + */ + public function iNoteTheSizeOfTheFile( $path ) + { + $path = $this->v( $path ); + clearstatcache( true, $path ); + $this->noted_sizes[ $path ] = is_file( $path ) ? filesize( $path ) : 0; + } + + /** + * @Then /^what was appended to the file "([^"]*)" since its size was noted should (not )?contain "(.*)"$/ + */ + public function whatWasAppendedShouldContain( $path, $not, $text ) + { + $path = $this->v( $path ); + $text = $this->v( $text ); + if ( ! isset( $this->noted_sizes[ $path ] ) ) { + throw new Exception( "The size of $path was not noted." ); + } + $added = (string) file_get_contents( $path, false, null, $this->noted_sizes[ $path ] ); + if ( ( false !== strpos( $added, $text ) ) === (bool) $not ) { + throw new Exception( "Expected what was appended to $path {$not}to contain $text.\n--- appended ---\n$added" ); + } + } + + /** + * @Then /^the file "([^"]*)" should be owned by uid (\d+) with mode ([0-7]{3,4})$/ + */ + public function theFileShouldBeOwnedByWithMode( $path, $uid, $mode ) + { + $path = $this->v( $path ); + clearstatcache( true, $path ); + if ( ! is_file( $path ) || is_link( $path ) ) { + throw new Exception( "$path is not a regular file." ); + } + $actual_uid = fileowner( $path ); + $actual_mode = fileperms( $path ) & 07777; + if ( (int) $uid !== $actual_uid || octdec( $mode ) !== $actual_mode ) { + throw new Exception( sprintf( 'Expected %s to be owned by uid %d with mode %s, it is uid %d with mode %04o.', $path, $uid, $mode, $actual_uid, $actual_mode ) ); + } + } + + /** + * Every top-level field of the STDOUT JSON, except a comma-separated list, has the same value in the JSON file. + * + * @Then /^the JSON file "([^"]*)" should hold every field of the STDOUT JSON except "([^"]*)"$/ + */ + public function theJsonFileShouldHoldEveryFieldOfStdout( $path, $except ) + { + $path = $this->v( $path ); + $stdout = $this->decode_stdout_json(); + $file = is_file( $path ) ? json_decode( file_get_contents( $path ), true ) : null; + if ( ! is_array( $stdout ) || ! is_array( $file ) ) { + throw new Exception( "STDOUT and $path must both hold a JSON object.\n" . $this->describe( $this->last_command() ) ); + } + $skip = array_map( 'trim', explode( ',', $except ) ); + foreach ( $stdout as $key => $value ) { + if ( in_array( $key, $skip, true ) ) { + continue; + } + if ( ! array_key_exists( $key, $file ) || $file[ $key ] !== $value ) { + throw new Exception( sprintf( "Field %s is %s in STDOUT but %s in %s.", $key, json_encode( $value ), array_key_exists( $key, $file ) ? json_encode( $file[ $key ] ) : 'missing', $path ) ); + } + } + } + + /** + * @Then /^the JSON field "([^"]*)" in STDOUT should be the size of the file "([^"]*)"$/ + */ + public function theJsonFieldShouldBeTheSizeOfTheFile( $field, $path ) + { + $path = $this->v( $path ); + $actual = $this->json_path( $this->decode_stdout_json(), $field ); + clearstatcache( true, $path ); + $size = is_file( $path ) ? filesize( $path ) : null; + if ( $actual !== $size ) { + throw new Exception( sprintf( 'Expected JSON field %s (%s) to be the size of %s (%s).', $field, var_export( $actual, true ), $path, var_export( $size, true ) ) ); + } + } + + /** + * The scanner runs as uid 33, so fixtures written as root must be world-readable whatever the umask. + * + * @When /^I make everything under "([^"]*)" readable by everyone$/ + */ + public function iMakeEverythingReadable( $path ) + { + $path = $this->v( $path ); + $this->assert_writable_path( $path ); + $paths = [ $path ]; + if ( is_dir( $path ) && ! is_link( $path ) ) { + $items = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $path, FilesystemIterator::SKIP_DOTS ), RecursiveIteratorIterator::SELF_FIRST ); + foreach ( $items as $item ) { + $paths[] = $item->getPathname(); + } + } + foreach ( $paths as $item ) { + if ( ! is_link( $item ) && ! chmod( $item, is_dir( $item ) ? 0755 : 0644 ) ) { + throw new Exception( "Could not chmod $item" ); + } + } + } + + /** + * Clean PHP files of about 6 KB each, to make a php-compat scan last long enough to overlap with other commands. + * + * @Given /^the directory "([^"]*)" holds (\d+) generated PHP files$/ + */ + public function theDirectoryHoldsGeneratedPhpFiles( $dir, $count ) + { + $dir = $this->v( $dir ); + $this->assert_writable_path( $dir ); + if ( ! is_dir( $dir ) && ! mkdir( $dir, 0755, true ) ) { + throw new Exception( "Could not create $dir" ); + } + for ( $i = 1; $i <= (int) $count; $i++ ) { + $file = sprintf( '%s/gen-%05d.php', $dir, $i ); + if ( is_file( $file ) ) { + continue; + } + $body = " 'value $i $j',\n"; + } + $body .= "\t);\n}\n"; + if ( false === file_put_contents( $file, $body ) ) { + throw new Exception( "Could not write $file" ); + } + } + $this->iMakeEverythingReadable( $dir ); + } + + /** + * Pulls the image once when it is missing, as the command itself would. + * + * @Given the compat-scanner image is available + */ + public function theCompatScannerImageIsAvailable() + { + $this->compat_used = true; + $image = $this->compat_image(); + if ( 0 === EE::launch( "docker image inspect --format '{{.Id}}' " . escapeshellarg( $image ), false, true )->return_code ) { + return; + } + $pull = EE::launch( 'docker pull ' . escapeshellarg( $image ), false, true ); + if ( 0 !== $pull->return_code ) { + throw new Exception( "$image is not present and could not be pulled.\n" . $this->describe( $pull ) ); + } + } + + /** + * What a php-compat scan killed before its cleanup leaves: its temporary directory and a stopped container with its name. + * + * @Given /^a killed php-compat scan of site "([^"]*)" left its temporary directory and container behind$/ + */ + public function aKilledPhpCompatScanLeftovers( $site ) + { + $site = $this->v( $site ); + $this->assert_own_name( $site ); + $this->compat_used = true; + $name = 'ee-php-compat-' . $site; + // A run's /out: a random directory in the root-only per-site one. + $dir = $this->variable( 'EE_ROOT_DIR' ) . '/tmp/php-compat/' . $site . '/0123456789abcdef'; + if ( ! is_dir( $dir ) && ! mkdir( $dir . '/.work', 0700, true ) ) { + throw new Exception( "Could not create $dir" ); + } + file_put_contents( $dir . '/report.json.tmp', '{"v":1,"status":"ok"' ); + EE::launch( 'chown -R 33:33 ' . escapeshellarg( $dir ), false, true ); + + EE::launch( 'docker rm -f ' . escapeshellarg( $name ), false, true ); + $create = EE::launch( 'docker create --name ' . escapeshellarg( $name ) . ' --entrypoint true ' . escapeshellarg( $this->compat_image() ), false, true ); + if ( 0 !== $create->return_code ) { + throw new Exception( "Could not create the leftover container $name.\n" . $this->describe( $create ) ); + } + } + /* ----- helpers ----- */ + /** + * @return string The scanner image with the tag core's img-versions.json pins. + */ + private function compat_image() + { + $versions = json_decode( (string) file_get_contents( EE_ROOT . '/img-versions.json' ), true ); + if ( empty( $versions['easyengine/compat-scanner'] ) ) { + throw new Exception( 'img-versions.json of this core has no easyengine/compat-scanner tag; php-compat scenarios need a core that pins the scanner image.' ); + } + + return 'easyengine/compat-scanner:' . $versions['easyengine/compat-scanner']; + } + + private function background_running() + { + if ( null === $this->background ) { + throw new Exception( 'No background command was started in this scenario.' ); + } + if ( null !== $this->background['exitcode'] ) { + return false; + } + $status = proc_get_status( $this->background['proc'] ); + if ( $status['running'] ) { + return true; + } + // proc_get_status() reports the exit code only once. + $this->background['exitcode'] = $status['exitcode']; + + return false; + } + + private function background_result() + { + return new \EE\ProcessRun( + [ + 'stdout' => (string) @file_get_contents( $this->background['stdout'] ), + 'stderr' => (string) @file_get_contents( $this->background['stderr'] ), + 'return_code' => $this->background['exitcode'], + 'command' => $this->background['command'], + 'cwd' => getcwd(), + 'env' => null, + 'run_time' => microtime( true ) - $this->background['start'], + ] + ); + } + + /** + * Ends a background command left by a failed scenario, so it can't hold a site's lock into the next one. + */ + private function stop_background() + { + if ( null === $this->background ) { + return; + } + if ( $this->background_running() ) { + // A running scan keeps bin/ee waiting; removing its container lets bin/ee clean up after itself. + self::purge_compat_leftovers(); + $deadline = time() + 30; + while ( $this->background_running() && time() < $deadline ) { + usleep( 200000 ); + } + if ( $this->background_running() ) { + proc_terminate( $this->background['proc'], 9 ); + } + } + proc_close( $this->background['proc'] ); + $this->background = null; + } + + /** + * Removes php-compat containers and temporary directories of this suite's sites, never others. + */ + private static function purge_compat_leftovers() + { + $prefix = 'ee-php-compat-' . self::SITE_PREFIX; + $run = EE::launch( "docker ps -a --format '{{.Names}}'", false, true ); + foreach ( array_filter( explode( "\n", trim( $run->stdout ) ) ) as $name ) { + if ( 0 === strpos( $name, $prefix ) ) { + EE::launch( 'docker rm -f ' . escapeshellarg( $name ), false, true ); + } + } + foreach ( glob( EE_ROOT_DIR . '/tmp/php-compat/' . self::SITE_PREFIX . '*' ) ?: [] as $path ) { + EE::launch( 'rm -rf ' . escapeshellarg( $path ), false, true ); + } + } + /** * Expands {NAME} variables. */ @@ -1427,6 +1785,9 @@ private function variable( $name ) return EE_ROOT_DIR . '/.backup'; case 'TMP': return $this->tmp_dir; + case 'SYS_TMP': + // What bin/ee's get_temp_dir() resolves to: it inherits this process's TMPDIR. + return rtrim( \EE\Utils\get_temp_dir(), '/' ); case 'RUN_ID': return self::$run_id; case 'PUBLIC_IP': diff --git a/features/php-compat.feature b/features/php-compat.feature new file mode 100644 index 00000000..41773718 --- /dev/null +++ b/features/php-compat.feature @@ -0,0 +1,212 @@ +Feature: Check the PHP compatibility of a site's code + `ee site php-compat` scans wp and php sites with the easyengine/compat-scanner image. Every scan scenario needs core's img-versions.json to pin that image, and the image locally or pullable ("the compat-scanner image is available"). + Fixtures are written as root and made world-readable, since the scanner reads the code as uid 33. Commands whose output holds findings run "without logging it" where ee.log is checked, because "I run" copies a command's output into ee.log. + + @wp + Scenario: The JSON summary of a WordPress site + Given "ee" is installed + And the compat-scanner image is available + And the site "bh-site-command-180.test" exists, created with "--type=wp" + And I write "' + Then the command should fail + And STDERR should contain "" + And the docker container "ee-php-compat-bh-site-command-181.test" should not exist + + Examples: + | flags | message | + | --php=9.9 | Invalid value specified for 'php' | + | --php=8 | Invalid --php value. Use one of: 5.6, 7.0 | + | --php=8.4- | Invalid | + | --php=abc | Invalid value specified for 'php' | + | | missing --php parameter | + + # The 5,000 generated files (about 30 MB) keep the first scan running for tens of seconds, well past the second command. + Scenario: A second check while one of the same site runs reports busy + Given the compat-scanner image is available + And the site "bh-site-command-183.test" exists, created with "--type=php" + And the directory "{SITES_DIR}/bh-site-command-183.test/app/htdocs/bulk" holds 5000 generated PHP files + When I start 'bin/ee site php-compat bh-site-command-183.test --php=8.4 --format=json' in the background + And I wait up to 120 seconds until the command "docker inspect -f '{{.State.Running}}' ee-php-compat-bh-site-command-183.test | grep -qx true" succeeds + And I run 'bin/ee site php-compat bh-site-command-183.test --php=8.4 --format=json' + Then the command should succeed + And STDOUT should be exactly: + """ + {"v":1,"status":"busy","site":"bh-site-command-183.test","target":"8.4","safe_to_upgrade":null} + """ + When I run 'bin/ee site php-compat bh-site-command-183.test --php=8.4' + Then the command should succeed + And STDOUT should be exactly: + """ + A check of bh-site-command-183.test is already running. + """ + When I wait up to 900 seconds for the background command to finish + Then the command should succeed + And the JSON field "status" in STDOUT should be "ok" + And the directory "{EE_ROOT_DIR}/tmp/php-compat/bh-site-command-183.test" should not exist + And the docker container "ee-php-compat-bh-site-command-183.test" should not exist + + Scenario: --estimate prints its JSON while a check of the same site runs + Given the compat-scanner image is available + And the site "bh-site-command-183.test" exists, created with "--type=php" + And the directory "{SITES_DIR}/bh-site-command-183.test/app/htdocs/bulk" holds 5000 generated PHP files + When I start 'bin/ee site php-compat bh-site-command-183.test --php=8.4 --format=json' in the background + And I wait up to 120 seconds until the command "docker inspect -f '{{.State.Running}}' ee-php-compat-bh-site-command-183.test | grep -qx true" succeeds + And I run 'bin/ee site php-compat bh-site-command-183.test --php=8.4 --estimate --format=json' + Then the command should succeed + And STDOUT should be valid JSON + And STDOUT should match "/^\{.*\}\n?$/" + And the JSON field "status" in STDOUT should be "ok" + And the JSON field "estimate" in STDOUT should be "true" + And the JSON field "site" in STDOUT should be "bh-site-command-183.test" + And the JSON field "target" in STDOUT should be "8.4" + And STDOUT should match "/"php_files":[1-9][0-9]{3}/" + And STDOUT should match "/"estimated_seconds":[1-9]/" + And the background command should still be running + When I run 'bin/ee site php-compat bh-site-command-183.test --php=8.4 --estimate' + Then the command should succeed + And STDOUT should match "/^A check of bh-site-command-183\.test for PHP 8\.4 should take about .+ This is an estimate\.\n$/" + When I wait up to 900 seconds for the background command to finish + Then the command should succeed + And the JSON field "status" in STDOUT should be "ok" + And the directory "{EE_ROOT_DIR}/tmp/php-compat/bh-site-command-183.test" should not exist + + Scenario: No temporary directory or container is left behind, also when the check times out + Given the compat-scanner image is available + And the site "bh-site-command-183.test" exists, created with "--type=php" + And the directory "{SITES_DIR}/bh-site-command-183.test/app/htdocs/bulk" holds 5000 generated PHP files + When I run 'bin/ee site php-compat bh-site-command-183.test --php=8.4 --format=json --timeout=1' + Then the command should succeed + And the JSON field "status" in STDOUT should be "tool_error" + And the JSON field "safe_to_upgrade" in STDOUT should be "" + And the JSON field "detail" in STDOUT should contain "timed out after 1 s" + And the directory "{EE_ROOT_DIR}/tmp/php-compat/bh-site-command-183.test" should not exist + And the docker container "ee-php-compat-bh-site-command-183.test" should not exist + + Scenario: A leftover of a killed check is removed by the next check + Given the compat-scanner image is available + And the site "bh-site-command-184.test" exists, created with "--type=php" + And I write "