Version 1.0.0

Author: greendrake

.gitignore

@@ -0,0 +1,3 @@
+/vendor
+/composer.lock
+/.phpunit.result.cache

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2023, Eugene
+Copyright (c) 2023, Eugene Greendrake
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -1,2 +1,20 @@
 # php-asyncprocess
-ReactPHP Promise implementation for truly asyncronous background processes
+[ReactPHP Promise](https://reactphp.org/promise/) implementation for truly asynchronous background processes.
+
+This library allows to run commands in background shaped as ReactPHP Promises. Non-blocking.
+Tested on Linux only.
+
+Under the hood, it works this way:
+
+1. A child process is forked using [pcntl_fork](https://www.php.net/manual/en/function.pcntl-fork.php). This runs the specified command and reports the result back to the parent process via a local HTTP call (using a one-off [reactphp/http](https://github.com/reactphp/http) server/client).
+
+2. Once the parent process gets the result, it fulfils (or rejects, depending on the exit code) the Promise. Profit.
+
+Example:
+
+```php
+use function React\Async\await;
+$p = new \Greendrake\AsyncProcess\Promise('a=$( expr 10 - 3 ); echo $a'); // Kick off the process in background.
+$result = await($p->get()); // Get the instance of React\Promise\Promise, wait for it to resolve.
+echo $result; // outputs "7"
+```

composer.json

@@ -0,0 +1,36 @@
+{
+    "name": "greendrake/php-asyncprocess",
+    "type": "library",
+    "description": "ReactPHP Promise implementation for truly asynchronous background processes",
+    "version": "1.0.0",
+    "authors": [
+        {
+            "name": "Eugene Greendrake",
+            "email": "[email protected]",
+            "role": "Developer"
+        }
+    ],
+    "license": "BSD-3-Clause",
+    "keywords": [
+        "async",
+        "asynchronous",
+        "promise",
+        "background",
+        "process"
+    ],
+    "minimum-stability": "dev",
+    "require": {
+        "php": ">=8.2.0",
+        "react/promise": "3.x-dev",
+        "react/http": "1.x-dev",
+        "react/async": "4.x-dev"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "10"
+    },
+    "autoload": {
+        "psr-4": {
+            "Greendrake\\AsyncProcess\\": ["src/", "test/"]
+        }
+    }
+}

phpunit.xml

@@ -0,0 +1,7 @@
+<phpunit colors="true" bootstrap="src/bootstrap.php">
+    <testsuites>
+        <testsuite name="default">
+            <directory>test/</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/NonZeroExitException.php

@@ -0,0 +1,6 @@
+<?php
+declare (strict_types = 1);
+namespace Greendrake\AsyncProcess;
+class NonZeroExitException extends \RuntimeException
+{
+}

src/Promise.php

@@ -0,0 +1,166 @@
+<?php
+declare (strict_types = 1);
+namespace Greendrake\AsyncProcess;
+use Ds\Set;
+use function React\Async\await;
+use Psr\Http\Message\RequestInterface as Request;
+use React\Http\Browser;
+use React\Http\Server;
+use React\Promise as BasePromise;
+use React\Socket\ConnectionInterface;
+use React\Socket\Server as SocketServer;
+
+class Promise {
+
+    protected BasePromise\Deferred $deferred;
+    protected BasePromise\Promise $promise;
+    protected ?int $pid = null;
+
+    private static $sigHoldHandlerSetup = false;
+    private static $sigHoldDefaultHandler;
+
+    public function __construct(protected string $command) {
+        $this->deferred = new BasePromise\Deferred;
+        $this->promise = $this->deferred->promise();
+        if (!self::$sigHoldHandlerSetup) {
+            self::$sigHoldDefaultHandler = pcntl_signal_get_handler(SIGCHLD);
+            // When the forked process exits, it sends the parent process SIGCHLD signal.
+            // Handling it properly is required to avoid the exited children becoming zombies.
+            // (For whatever reason it doesn't actually work for me, so there is a posix_kill call underneath, but trying it anyway).
+            pcntl_signal(SIGCHLD, SIG_IGN);
+            self::$sigHoldHandlerSetup = true;
+        }
+        $httpAddress = '127.0.0.1:' . self::findUnusedPort();
+        $pid = pcntl_fork();
+        if ($pid == -1) {
+            throw new \RuntimeException('Could not fork process');
+        } else if ($pid) {
+            // The original, now parent process. Setup an HTTP server and wait for the forked process to post the result to it:
+            $this->pid = $pid; // The PID of the forked process, not the parent.
+            $result = null;
+            $socket = new SocketServer($httpAddress);
+            // This is a one-off request/response HTTP server.
+            // After the connection is closed, close the socket and pass the response over to the deferred promise.
+            $socket->on('connection', function (ConnectionInterface $conn) use ($socket, &$result) {
+                $conn->on('close', function () use ($socket, &$result) {
+                    $socket->close();
+                    // We've made the forked process session leader, we've set SIGCHLD handler to SIG_IGN above,
+                    // and yet it may remain a zombie process even after calling exit in itself. Fuck knows why.
+                    // Kill the zombie in case it is still walking:
+                    posix_kill($this->pid, SIGKILL);
+                    // Now that the job is done, cleanup our mess — bring the original handler back:
+                    pcntl_signal(SIGCHLD, self::$sigHoldDefaultHandler);
+                    // Report the results (whatever they are) as per our promise:
+                    if ($result['success']) {
+                        $m = $result['code'] === 0 ? 'resolve' : 'reject';
+                        $output = implode(PHP_EOL, $result['result']);
+                        if ($m === 'reject') {
+                            $output = new NonZeroExitException(sprintf('Exit code %s: %s', $result['code'], $output));
+                        }
+                        $this->deferred->$m($output);
+                    } else {
+                        $this->deferred->reject($result['error']);
+                    }
+                });
+            });
+            // Actually run the one-off HTTP server to wait for what the forked process has to say:
+            $server = new Server(function (Request $request) use (&$result) {
+                $result = unserialize((string) $request->getBody());
+            });
+            $server->listen($socket);
+        } else {
+            // The forked process.
+            // Re-instate the default handler (otherwise the reported exit code will be -1, see https://stackoverflow.com/questions/77288724):
+            pcntl_signal(SIGCHLD, self::$sigHoldDefaultHandler);
+            $browser = new Browser;
+            // Define the function that will report results back to the parent:
+            $reportBack = function (int $forkExitCode = 0, ?int $jobExitCode = null, ?array $result = null, ?\Throwable $error = null) use ($browser, $httpAddress) {
+                await($browser->post('http://' . $httpAddress, [], serialize([
+                    'success' => $error === null,
+                    'result' => $result,
+                    'code' => $jobExitCode,
+                    'error' => $error,
+                ]))->catch(function () {
+                    // Don't give a fuck. This is the forked background process, and if anything is wrong, no one is gonna hear anyway.
+                }));
+                // This forked process will probably be killed by the parent before it reaches this point,
+                // but, just in case, we put an explicit exit here to make sure it does not do anything else:
+                exit($forkExitCode);
+            };
+            if (false === ($pid = getmypid())) {
+                // This is very unlikely, but let's handle it.
+                $reportBack(
+                    forkExitCode : 1,
+                    error: new \RuntimeException('Could not get child process PID within itself')
+                );
+            } else {
+                try {
+                    $this->pid = $pid;
+                    // Make this process the session leader so that it does not depend on the parent anymore:
+                    if (posix_setsid() < 0) {
+                        $reportBack(
+                            forkExitCode: 1,
+                            error: new \RuntimeException('Could not make background process ' . $pid . ' session leader')
+                        );
+                    } else {
+                        // Do the actual job however long it takes, suppress STDERR (otherwise it'll make its way to the parent's shell):
+                        exec($this->command . ' 2> /dev/null', $output, $resultCode);
+                        if ($output === false) {
+                            $reportBack(
+                                forkExitCode: 1,
+                                error: new \RuntimeException(sprintf('Could not run the command "%s" (PID %s)', $this->command, $this->pid))
+                            );
+                        } else {
+                            $reportBack(
+                                jobExitCode: $resultCode,
+                                result: $output
+                            );
+                        }
+                    }
+                } catch (\Throwable $e) {
+                    $reportBack(
+                        forkExitCode: 1,
+                        error: $e
+                    );
+                }
+            }
+        }
+    }
+
+    public function getPid(): int {
+        return $this->pid;
+    }
+
+    public function get(): BasePromise\PromiseInterface
+    {
+        return $this->promise;
+    }
+
+    private static function findUnusedPort(): int {
+        $tried = new Set;
+        $add = function (int $port) use ($tried) {
+            $tried->add($port);
+            return true;
+        };
+        do {
+            $port = mt_rand(1024, 65535);
+        } while ($tried->contains($port) || (self::isPortOpen($port) && $add($port)));
+        return $port;
+    }
+
+    private static function isPortOpen(int $port): bool {
+        $result = false;
+        try {
+            if ($pf = fsockopen('127.0.0.1', $port)) {
+                $result = true;
+                fclose($pf);
+            }
+        } catch (\ErrorException $e) {
+            if (!str_contains($e->getMessage(), 'Connection refused')) {
+                throw $e; // Unexpected exception
+            }
+        }
+        return $result;
+    }
+
+}

src/bootstrap.php

@@ -0,0 +1,6 @@
+<?php
+declare (strict_types = 1);
+require_once __DIR__ . '/../vendor/autoload.php';
+set_error_handler(function ($severity, $message, $file, $line) {
+	throw new \ErrorException($message, 0, $severity, $file, $line);
+});

test/Test.php

@@ -0,0 +1,21 @@
+<?php
+declare (strict_types = 1);
+namespace Greendrake\AsyncProcess;
+use function React\Async\await;
+use PHPUnit\Framework\TestCase;
+
+class Test extends TestCase {
+
+    public function testFailure() {
+        $this->expectException(NonZeroExitException::class);
+        $p = new Promise('no-bananas');
+        await($p->get());
+    }
+
+    public function testSuccess() {
+        $p = new Promise('a=$( expr 10 - 3 ); echo $a');
+        $result = await($p->get());
+        $this->assertSame('7', $result);
+    }
+
+}

unittest

@@ -0,0 +1,2 @@
+#!/bin/bash
+./vendor/bin/phpunit --testdox