fix(shell): terminate the process on timeout (#574)

Author: azjezz

docs/component/shell.md

@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [execute](./../../src/Psl/Shell/execute.php#L44)
+- [execute](./../../src/Psl/Shell/execute.php#L45)
 - [stream_unpack](./../../src/Psl/Shell/stream_unpack.php#L30)
 - [unpack](./../../src/Psl/Shell/unpack.php#L16)
 

src/Psl/Shell/execute.php

@@ -19,6 +19,7 @@
 use function pack;
 use function proc_close;
 use function proc_open;
+use function proc_terminate;
 use function strpbrk;
 
 /**
@@ -146,6 +147,7 @@ static function (array $m) use (&$environment, &$variable_cache, &$variable_coun
     $stderr = new IO\CloseReadStreamHandle($pipes[2]);
 
     $code = 0;
+    $timed_out = false;
     try {
         $result = '';
 
@@ -157,16 +159,23 @@ static function (array $m) use (&$environment, &$variable_cache, &$variable_coun
             $result .= pack('C1N1', $type, Str\Byte\length($chunk)) . $chunk;
         }
     } catch (IO\Exception\TimeoutException $previous) {
+        $timed_out = true;
+
         throw new Exception\TimeoutException(
             'reached timeout while the process output is still not readable.',
             0,
             $previous,
         );
     } finally {
         $stdout->close();
-
         $stderr->close();
 
+        // Kill the process before closing if it timed out, otherwise
+        // proc_close() will block indefinitely waiting for it to exit.
+        if ($timed_out) {
+            proc_terminate($process, 9);
+        }
+
         $code = proc_close($process);
     }
 

tests/unit/Shell/ExecuteTest.php

@@ -5,6 +5,8 @@
 namespace Psl\Tests\Unit\Shell;
 
 use PHPUnit\Framework\TestCase;
+use Psl\DateTime;
+use Psl\DateTime\Duration;
 use Psl\Env;
 use Psl\OS;
 use Psl\SecureRandom;
@@ -141,4 +143,38 @@ public function testErrorOutputIsPacked(): void
         static::assertSame('hello', $stdout);
         static::assertSame(' world', $stderr);
     }
+
+    public function testTimeoutDoesNotAffectFastCommands(): void
+    {
+        $result = Shell\execute(PHP_BINARY, ['-r', 'echo "hello";'], timeout: Duration::seconds(5));
+
+        static::assertSame('hello', $result);
+    }
+
+    public function testTimeoutException(): void
+    {
+        if (OS\is_windows()) {
+            static::markTestSkipped(
+                'Timeout relies on IO\\streaming() which behaves differently on Windows with non-blocking pipes.',
+            );
+        }
+
+        $start = DateTime\Timestamp::monotonic();
+
+        try {
+            Shell\execute(PHP_BINARY, ['-r', 'sleep(10);'], timeout: Duration::seconds(2));
+        } catch (Shell\Exception\TimeoutException $_) {
+            $elapsed = DateTime\Timestamp::monotonic()->since($start);
+
+            static::assertLessThan(
+                3.0,
+                $elapsed->getTotalSeconds(),
+                'Process was not killed after timeout — proc_close() likely blocked.',
+            );
+
+            return;
+        }
+
+        static::fail('Expected timeout exception');
+    }
 }