HSL subprocess API proposal (library HIP draft)

[Atry]

This proposal includes an API to create subprocess, as an alternative to existing PHP functions shell_exec, proc_open, etc. The proposed subprocess API is consistent with HSL design and easy to be used safely, supporting asynchronous operators everywhere possible.

Getting Started

To start a process, simply call spawn with a vec of the executable and its arguments. For example, the following code executes the command composer update and throws an exception if it failed.

$process = \HH\Lib\Subprocess\spawn(vec["composer", "update"]);
using $process->closeWhenDisposed();
$exit_code = await $process->getExitCodeAsync();
if ($exit_code !== 0) {
  throw new \Exception('Failed to run "composer update"')
}

Note that spawn will return a Process, which could be used to monitor the process status. Internally, a PID is associated with the Process, and the user has the responsibility to close it, or let using statement clean it up with the help of the closeWhenDisposed idiom.

API

Low level API

The low level API includes a thin wrapper of posix_spawnp using raw file handles. posix_spawn_file_action_ functions are replaced by vec<PosixSpawnFileAction>, and posix_spawn_attr_ functions are replaced by PosixSpawnAttr.

namespace HH\Lib\OS;
newtype ProcessID as arraykey = int;
newtype ExitCode as int = int;

/**
 * The setsid behavior, i.e. whether a new session and process group ID should be created for the subprocess.
 */
enum SIDBehavior : bool {
  INHERIT = false;
  NEW = true;
}

type PosixSpawnAttr = shape(

  // whether a new session and process group ID should be created for the subprocess
  SIDBehavior $setsid = SIDBehavior::INHERIT,

  // the process group ID for the subprocess. The subprocess would inherit the process group ID 
  ?int $setpgid = null,

);

<<__Sealed>>
abstract class PosixSpawnFileAction {
  public static function dup2(int $file_number, OS\FileDescriptor $existing_handle): PosixSpawnFileAction;
  public static function open(int $file_number, string $path, int $flags, ?int $mode = null): PosixSpawnFileAction;
  public static function chdir(string $path): PosixSpawnFileAction;
}

function posix_spawnp(string $file, vec<PosixSpawnFileAction> $file_actions, PosixSpawnAttr $attributes, vec<string> $argv, vec<string> $envp): ProcessID;

High level API for long-lived sub-processes

namespace HH\Lib\Subprocess {
  use namespace HH\Lib\IO;
  use namespace HH\Lib\OS;

  namespace FileAction {

    /**
     * A richer type-safe wrapper of `posix_spawn_file_actions_t`.
     *
     * Unlike `OS\PosixSpawnFileAction`, which supports only functions in C `posix_spawn_file_actions_*` function, this `FileActions` can internally create additional pipe or socketpair and return one of the pairs when `spawn` is called.
     *
     * @param TResult the process and any additional native resources created during starting the new subprocess.
     */
    newtype FileActions<TResult>;

    /**
     * Returns a `FileActions` that redirects all standard I/O to `/dev/null`.
     */
    function default()[]: FileActions<Process>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition changes the working directory for the subprocess being created.
     */
    function change_directory<TResult>(FileActions<TResult> $file_actions, string $path)[]: FileActions<TResult>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to /dev/null.
     */
    function dev_null<TResult>(FileActions<TResult> $file_actions, int $file_number)[]: FileActions<TResult>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to `$existing_handle`.
     */
    function duplicate<TResult>(FileActions<TResult> $file_actions, int $file_number, IO\FDHandle $existing_handle)[]: FileActions<TResult>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to the read handle of a newly created pipe.
     *
     * The write handle of the pipe will be appended to the return value of `spawn` invoked with a `FileActions` returned by this function, .
     */
    function pipe_read<TResult>(FileActions<TResult> $file_actions, int $file_number)[]: FileActions<(TResult, IO\CloseableWriteFDHandle)>;


    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to the a file opened in read-only mode.
     */
    function open_read_only<TResult>(FileActions<TResult> $file_actions, int $file_number, string $path)[]: FileActions<TResult>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to the write handle of a newly created pipe.
     *
     * The read handle of the pipe will be appended to the return value of `spawn` invoked with a `FileActions` returned by this function, .
     */
    function pipe_write<TResult>(FileActions<TResult> $file_actions, int $file_number)[]: FileActions<(TResult, IO\CloseableReadFDHandle)>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to the a file opened in write-only mode.
     */
    function open_write_only<TResult>(
      FileActions<TResult> $file_actions,
      int $file_number,
      string $path,
      WriteMode $mode = WriteMode::OPEN_OR_CREATE,
      int $create_file_permissions = 420
    )[]: FileActions<TResult>;

    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to one of a newly created socketpair.
     *
     * The other handle of the socketpair will be appended to the return value of `spawn` invoked with a `FileActions` returned by this function, .
     */
    function socketpair<TResult>(FileActions<TResult> $file_actions, int $file_number)[]: FileActions<(TResult, IO\CloseableReadWriteFDHandle)>;


    /**
     * Returns a new `FileActions` that performs `$file_actions` and in addition redirects `$file_number` to the a file opened in read-write mode.
     */
    function open_read_write<TResult>(
      FileActions<TResult> $file_actions,
      int $file_number,
      string $path,
      WriteMode $mode = WriteMode::OPEN_OR_CREATE,
      int $create_file_permissions = 420,
    )[]: FileActions<TResult>;
  }

  interface Process extends IO\CloseableHandle {

    /** Returns the associated process identifier. */
    public function getPID(): ProcessID;

    /**
     * Returns an `Awaitable` of the exit code of the process, which would not complete until the process exited.
     */
    public function getExitCodeAsync(): Awaitable<ExitCode>;

    /**
     * Terminates the process and release the associated PID.
     */
    public function close(): void;

    /**
     * Returns a `IDisposable` that `close` this `Process` when it is disposed.
     */
    public function closeWhenDisposed(): \IDisposable;
  }

  type SIDBehavior = OS\SIDBehavior;
  type Attributes = OS\PosixSpawnAttr;

  /**
   * Creates a process by forking and executing the `$command`.
   *
   * @param command
   *   the command and arguments to be executed. `$command[0]` is the executable, and the rest elements in `$command` are arguments.
   * 
   *   The executable will be searched from `$PATH` if `$command[0]` is a file name instead of a path.
   * @param file_actions
   *   the file actions including options about changing working directory and I/O redirections. Unlike `OS\PosixSpawnFileAction`, it is possible to let `$file_actions` internally create additional pipe or socketpair.
   * @param attributes
   *   the spawn attributes object.
   * @param environment_variables
   *   the environment variables of the new process.
   *   The environment variables of the current HHVM process would be used if `$environment_variables` is null.
   *   However, the environment variables of the new process would not contain entries from current process if `$environment_variables` is not null.
   */
  public function spawn<TResult>(
    vec<string> $command,
    FileActions<TResult> $file_actions = FileAction\default(),
    Attributes $attributes = shape(),
    ?dict<string, string> $environment_variables = null,
  ): TResult;

}

High level API for short-lived sub-processes

namespace HH\Lib\Subprocess
/**
 * An exception thrown when exit code is not 0.
 */
final class NonZeroExitCodeException extends \Exception {
  /** The exit code of the process */
  public function getExitCode(): ExitCode;
  /** The standard error as a string */
  public function getStandardError(): string;
}

/**
 * Executes the `$command` and returns the standard output as a string if the exit code is 0.
 *
 * @param command
 *   the command and arguments to be executed. `$command[0]` is the executable, and the rest elements in `$command` are arguments.
 * 
 *   The executable will be searched from `$PATH` if `$command[0]` is a file name instead of a path.
 * @param stdin
 *   the standard input as a string.
 * @param attributes
 *   the spawn attributes object.
 * @param environment_variables
 *   the environment variables of the new process.
 *   The environment variables of the current HHVM process would be used if `$environment_variables` is null.
 *   However, the environment variables of the new process would not contain entries from current process if `$environment_variables` is not null.
 * @throws NonZeroExitCodeException if the exit code is not 0.
 */
function execute_and_read_output_async(
  vec<string> $command,
  string $stdin = '',
  Attributes $attributes = shape(),
  ?dict<string, string> $environment_variables = null,
): Awaitable<string>;

Use cases

Short-lived processes

For short-lived process whose standard I/O can be used as a whole string, the high-level API execute_and_read_output can be used as an alternative to shell_exec.

For example, suppose we want to use afinfo to extract the data format information from an audio file, previously the task could be done with the help of shell_exec:

$afinfo_data_format = shell_exec('afinfo ' . escapeshellarg($full_file_path) . ' | grep "Data format: "');

Now, the same functionality can be implemented with the new execute_and_read_output API:

$afinfo_data_format =
  await execute_and_read_output_async(vec['afinfo', $full_file_path])
    |> Str\split($$, "\n")
    |> C\find($$, $line ==> Str\contains($line, 'Data format: '))

Long-lived processes

execute_and_read_output_async is not suitable for a long-lived process because it does not return until the process exited. Use spawn for long-lived processes where the standard I/O can be handled at real time. The common pattern to handle standard I/O instantly is to create a pair of pipe stream, then redirect standard output or standard error to the write stream. For example, suppose we want to compile a big C++ project from make, which would take 1 hour to complete, the following example could log each line from the sub-process' stdout and stderr instantly:

list(list($process, $stdout), $stderr) =
  Subprocess\spawn(
    vec['make', '-j16'],
    Subprocess\FileAction\default()
      |> Subprocess\FileAction\pipe_write($$, STDOUT_FILENO)
      |> Subprocess\FileAction\socketpair($$, STDERR_FILENO)
  );
using $process->closeWhenDisposed();
using $stdout->closeWhenDisposed();
using $stderr->closeWhenDisposed();
concurrent {
  await async {
    foreach (new IO\BufferedReader($stdout)->linesIterator() await as $line) {
      $formatted_log = '[info]'.Timestamp::now()->format(Zone::UTC, '%Y-%m-%d %H:%M:%S').' '.$line;
      echo $formatted_log;
    }
  };
  await async {
    foreach (new IO\BufferedReader($stderr)->linesIterator() await as $line) {
      $formatted_log = '[error]'.Timestamp::now()->format(Zone::UTC, '%Y-%m-%d %H:%M:%S').' '.$line;
      echo $formatted_log;
    }
  };
  $exit_code = await $process->getExitCodeAsync();
}

Design Considerations

Do we use shell?

No.

The PHP API shell_exec executes a command as a shell script for redirecting standard I/O and piping multiple processes. This approach is essentially letting the users write shell script code generators in Hack. As a result, it is easy to create insecure shell script with shell injection loopholes, because the Hack compiler cannot detect issues in the shell scripts. Also the common practice to use shell pipe operator to process texts, with the help of utilities like grep or sed, is inefficient due to the overhead of creating unnecessary processes for simple text processing tasks.

For comparison, ProcessBuilder in Java does not use shell, while the proc_open function in PHP and the subprocess module in Python provide options to execute the command either via shell, or directly using system calls.

The proposed proposed subprocess API is similar to ProcessBuilder, avoiding using implicitly use the shell, therefore, users do not have to escape and concatenate arguments into a shell script. It always requires a vec<string> to represent the command to execute.

Is the user required to specify full path of the executable

No.

In Python, it is recommended to explicitly resolve the full path of the executable with the help of shutil.which(), for best portability between POSIX and Windows. However, explicit path resolution is not necessary in the proposed subprocess API because Hack supports only macOS and Linux. The proposed subprocess API will consider $command[0] as the executable and internally use execvpe or execvp to resolve the full path from $PATH.

Will the new API support piping multiple processes?

Yes. However it is rarely needed, often abused, and should be considered a 'code smell'

The proposed subprocess API supports I/O redirection, therefore, it is possible to pipe processes by redirecting their stdin and stdout to a pair of pipe handles. However, most use cases, if not all, of shell pipe operators should be able to be refactored to Hack code manipulating a single process. The usage of text processing utilities, including grep and sed, should be replaced by functions in HH\Lib\Str and HH\Lib\Regex.

Is there any pipe file handle internally created?

Not in spawn.

The proc_open function in PHP and the subprocess module in Python supports either preexisting file handles, or string constants as the instruction to let the API create new file handles, while ProcessBuilder in Java can only redirect I/O to newly created files or pipes.

In contrast, the new spawn API only accepts preexisting file handles, requiring the user to create file handles and pass to the newly created process, because this approach is more concise, more orthogonal and more consistent.

How does the proposed subprocess API interoperate with other HSL APIs

The proposed subprocess API conforms HSL IO Key Design Decisions. The Hack class IO\WriteFDHandle and IO\WriteFDHandle are accepted as parameters, instead of raw file handles or PHP resources. The Process interface also extends IO\CloseableHandle, supporting the closeWhenDisposed idiom.

The proposed subprocess API is as async as possible. Unlike pcntl_waitpid in PHP, we provide getExitCodeAsync to wait for the exit code asynchronously.

How to specify the process creation options?

The proc_open function in PHP and the subprocess module in Python accepts parameters with default values for process creation options, while ProcessBuilder in Java is implemented as the builder design pattern, maybe because Java does not support optional parameters.

The proposed subprocess API is similar to PHP or Python, accepting process creation options as parameters. It does not accept options in a shape, because we consider options in shape as a workaround of lacking the language feature of named parameters. Hopefully Hack would support named parameters in the future, making it easier to specify optional parameters.

[fredemmott]

This isn't 'request changes', just discussion points; I'm going to separate comments so we get some reasonable reply threading :)

fork_and_exec

Naming:

This is technically correct and matches the builtin, but pretty verbose; in most languages, 'exec' isn't a true POSIX-style 'replace the current process', but implicitly has the fork - or acts like it.

It also is describing an implementation detail - right now, we're doing fork-and-exec, but we may wish to use posix_spawn() and posix_spawnp() in the future.

[Atry]

How about just spawn?

[fredemmott]

Spawns sounds good to me :)

Just for my reference, I went digging into why I didn't use posix_spawn():

• we would generally prefer to instead of forking, but setsid and setpgid were requirements
• at the time, POSIX_SPAWN_SETSID was only available on glibc 2.26
  • we supported Ubuntu 16.04, which had an older glibc (2.23). We don't support Ubuntu 16.04 any more. Ubuntu 18.04 has 2.27, Debian 10 has 2.28
  • it was not available on MacOS. It is now available on MacOS 15 and above.

I think we could move now if we wanted to.

[fredemmott]

(vec["composer", "update"])

IMO the command should be separate to the arguments:

• semantically, the command is mandatory, arguments are optional
• the hack type system does not support 'vec with at least 1 member'

[fredemmott]

Copying from where I replied t othe wrong thread:

@fredemmott:

ah:

 * @param executable
 *   the full path of the executable. If `$executable` is null, `$command[0]` 

This feels a bit unintuitive - the meaning of /part/ of an argument changing depending on the later one.

@Atry:

This feels a bit unintuitive - the meaning of /part/ of an argument changing depending on the later one.

I think this is the behavior is consistent, as $command[0] always means the executable, even though it could be overridden by $executable.

[fredemmott]

Ah, you're it as a full argv, including argv[0] - but inferring command from argv[0] if unspecified?

That's reasonable, but now that the ability to remove argv[0] appears to have been removed, I'm back to wanting the typechecker to be able to do some enforcement here.

While the typechecker can't identify every class of error, it's unusual to design an API in a way where a mandatory parameter can be ommitted.

[Atry]

That's reasonable, but now that the ability to remove argv[0] appears to have been removed, I'm back to wanting the typechecker to be able to do some enforcement here.

I don't think the ability is very useful. ProcessBuilder in Java, proc_open in PHP and subprocess in Python they all don't provide such ability.

[Atry]

While the typechecker can't identify every class of error, it's unusual to design an API in a way where a mandatory parameter can be ommitted.

It's not unusual in other languages. For example, in Java, new ProcessBuilder().start(); just compiles.

[fredemmott]

It's unusual in Hack.

But honestly I'm probably over-weighing this due to spending a bunch of time working with and reading about the C/POSIX functions, where execv() and friends work the way I'm thinking.

[fredemmott]

the user has the responsibility to close it

I see in the interface that this terminates the process - how forceful is it? Does it do a normal kill, a kill -9? How long does it wait for the process to exit? What if it doesn't?

What if the user doesn't close it? Does HHVM clean it up at some undetermined time later like it does with file descriptors? For FDs, this is currently done at the end of the request, but could be done in the future by garbage collectors (we intentionally do not have observable refcounting in FDs)

[Atry]

I see in the interface that this terminates the process - how forceful is it? Does it do a normal kill, a kill -9? How long does it wait for the process to exit? What if it doesn't?

It's a kill -9 if getExitCodeAsync is not called. It will wait forever after sending the kill signal, assuming the subprocess should be terminated shortly. The purpose of close is a safety net to prevent resource leak, not to exit the process gracefully.

[fredemmott]

Is the user required to specify full path of the executable ...it searches executable via the $path_resolver parameter, whose default value is OS\which<>, simulating the same path resolution behavior as a shell.

Why is this a simulation? if the execvpe option is set on _OS\fork_and_execve() libc will handle PATH in the appropriate way for the current system

function which()

... which ties into: is this function needed?

[Atry]

Thank you. I will update the proposal to remove which and $path_resolver.

[fredemmott]

Do we use shell?

I have no design feedback in this comment, just more context

There's another two reasons:

using the shell requires users to escape arguments.

If the functions are defined as using the shell, this can't be done transparently - as if it is, everything should be escaped and there's no way of actually using the power of the shell:

Argument escaping is also not well-defined or reliable. Most bash-like shells handle escaping in a similar-ish way, but it's not actually identical. Even bash vs zsh have observably different behaviors when variables are involved. PHP and HHVM do a 'best effort' here, but that's not great for a security-sensitive feature.

using-shell can be implemented on top of not-using-shell, but not the other way around

Just call /bin/sh -c "str"

... but if the shell is being used for the primitives, given escaping isn't reliable, it's not possible to build something that reliably acts shell-less

proc_open

For completeness: there is currently no non-private API in HHVM to spawn a subprocess that does not use a shell: proc_open() in HHVM always uses the shell. Shell-less proc_open() is a relatively new feature in PHP (7.4), and was added after we stopped following PHP's development.

[fredemmott]

* @param working_directory
*   the working directory to override.
*   The working directory of the current HHVM process would be used if > `$working_directory` is null.

While at the C level is one true CWD per process, we currently fake a per-request/per-thread one in the implementation of the Hack builtins, which affects OS\open() etc. We probably want to keep doing that - conretely replacing 'HHVM process' with 'request' here.

[Atry]

Updated

[fredemmott]

* @param environment_variables
*   the environment variables to override.

if the current variables are a=A and b=B, what happens if I provide dict['a' => 'foo'] here?

• Is the process spawned with a=foo and b=B, or just a=Foo with b unset?
• Whichever one it is, how do I get the other behavior?

[Atry]

Updated the proposal.

@param environment_variables
the environment variables of the new process.
The environment variables of the current HHVM process would be used if $environment_variables is null.
However, the environment variables of the new process would not contain entries from current process if $environment_variables is not null.

[Atry]

Is the process spawned with a=foo and b=B, or just a=Foo with b unset?

just a=Foo with b unset

Whichever one it is, how do I get the other behavior?

To let the subprocess contain entries from the current process, the user must explicitly copy entries from the current environment variables.

[Atry]

Since we are going to mimic posix_spawn and posix_spawnp in Hack, we might want to revisit the decision of the inheritance of environment variables.

The child process will inherit the environment variables when envp is NULL in the C API posix_spawn and posix_spawnp implementions on some platforms. The behavior is not standard. Linux does not support the implicit inheritance of environment variables.

https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_spawn.html

We might not want to keep this behavior for our mimicked implementation of posix_spawn in Hack.

[fredemmott]

macos at least does not document that behavior; let's make it mandatory non-nullable to:

• increase portability
• make dependencies more explicit - where environment variables are a form of dependency

[fredemmott]

 * @param stdin
 *   the redirected standard input. The subprocess would inherit the standard input from the current HHVM process if `$stdin` is null.
 * @param stdout
 *   the redirected standard output. The subprocess would inherit the standard output from the current HHVM process if `$stdout` is null.
 * @param stderr
 *   the redirected standard error. The subprocess would inherit the standard error from the current HHVM process if `$stderr` is null.

process vs request again here; though it would need to be process as request out/error/in are not necessarily FDs.

Process doesn't feel like a good default though:

• it's breaking isolation between requests
• if I'm running hhvm -m server and either logging the output or watching it, I wouldn't expect to see the output of a subprocess created by a request
• if I'm running hhvm -m server, I wouldn't expect my keypresses to start going to a request subprocess - especially one that may not exist
• HHVM process may not have STDIN/STDOUT/STDERR

IMO:

• these should probably default to an open handle to /dev/null. I'm wanting something that feels like 'closed', but /dev/null is safer as many things make assumptions about low-numbered FDs
• while these are in FD order, having these as optional arguments in this order does not really fit usage: it's most likely that someone will want to provide an stdout

[Atry]

while these are in FD order, having these as optional arguments in this order does not really fit usage: it's most likely that someone will want to provide an stdout

One of the solutions is to pass a dict for I/O redirection. Unfortunately the dict type cannot enforce a ReadFDHandle for stdin and WriteFDHandles for stdout/stderr.

Alternatively, we can define a IORedirections as below:

newtype IORedirectionTarget<+TFDHandle as IO\FDHandle> = int;

enum class StandardIORedirectionTarget : IORedirectionTarget<IO\FDHandle> {
  IORedirectionTarget<IO\ReadFDHandle> STDIN = 0;
  IORedirectionTarget<IO\WriteFDHandle> STDOUT = 1;
  IORedirectionTarget<IO\WriteFDHandle> STDERR = 2;
}

type IORedirection<+TFDHandle as IO\FDHandle> = (IORedirectionTarget<TFDHandle>, TFDHandle);

type IORedirections = Traversable<IORedirection<IO\FDHandle>>;

This IORedirections approach is more type safe than dict, however it's more complicated and less straightforward.

[fredemmott]

One of the solutions is to pass a dict for I/O redirection. Unfortunately the dict type cannot enforce a ReadFDHandle for stdin and WriteFDHandles for stdout/stderr.

So, technically stderr should be readwrite (https://pubs.opengroup.org/onlinepubs/9699919799/functions/stdin.html) - for complete correctness, we need a few new builtins:

• OS\socketpair() for a bidirectional pipe
• OS\dup() to copy an FD
• OS\shutdown() to make an RW FD either read or write

Then for example, the FDs for ./foo in your shell could be set up with:

list($parent, $child) = OS\socketpair(OS\AF_UNIX);
$stderr = $child;
$stdin = OS\dup($stderr);
OS\shutdown($stdin, OS\SHUT_WR);
$stdout = OS\dup($stdout);
OS\shutdown($stdout, OS\SHUT_RD);

--

That said, it is not forbidden (though very very weird) to spawn a process with different use of those FDs.

If a standard utility or a conforming application is executed with file descriptor 0 not open for reading or with file descriptor 1 or 2 not open for writing, the environment in which the utility or application is executed shall be deemed non-conforming, and consequently the utility or application might not behave as described in this standard.

I read this as saying meaning that if you execute an app designed for POSIX or the C standard in such an environment, its' behavior is undefined - however, if an application is not designed to require such an environment, it's fine.

[fredemmott]

these should probably default to an open handle to /dev/null. I'm wanting something that feels like 'closed', but /dev/null is safer as many things make assumptions about low-numbered FDs

After reading though the specs, closing them appears to be banned if executing a posix-expecting process (so shouldn't be done by default), and /dev/null is likely the best choice: standard applications have undefined behavior if any of STDIN/OUT/ERR are not open for read, write, and readwrite respectively.

Inheriting from the HHVM process isn't enough as they may have already been closed.

[Atry]

I think the purpose of letting stderr be both readable and writable is to allow a process directly read and write to tty, even when the process is in a complicated piped shell expression, because the shell pipe operator redirects only stdin and stdout, not stderr.

[fredemmott]

STDIO/FDs, part 2:

 * @param stdout
 *   the redirected standard output. The subprocess would inherit the standard output from the current HHVM process if `$stdout` is null.
 * @param stderr
 *   the redirected standard error. The subprocess would inherit the standard error from the current HHVM process if `$stderr` is null.

• if the default is not 'closed', I should be able to explicitly create a subprocess where fd 1 is closed
• I should be able to specify arbitrary FDs, not just the STDIO ones

[Atry]

I changed my mind, since it's hard for the users to create pipes or socket pairs properly, we should provide a high-level API to create these FDs for the users.

/**
 * Create a subprocess whose standard I/O streams are redirected to newly created pipes and socket pairs.
 */
public function spawn_stdio(
  vec<string> $command,
  ?string $working_directory = null,
  ?dict<string, string> $environment_variables = null,
  SIDBehavior $sid_behavior = SIDBehavior::INHERIT,
  ?int $setpgid = null,
): (IO\CloseableReadFDHandle, IO\CloseableWriteFDHandle, IO\CloseableReadWriteFDHandle, Process);

At the meantime, I agree inherited stdio are not good default values. However, /dev/null does not look like a good default value, too, because people merely want to create subprocess and discard the output. Shall we provide a low level API without any default values for I/O redirection?

public function spawn(
  vec<string> $command,
  dict<int, IO\FDHandle> $io_redirections,
  ?string $working_directory = null,
  ?dict<string, string> $environment_variables = null,
  SIDBehavior $sid_behavior = SIDBehavior::INHERIT,
  ?int $setpgid = null,
): Process;

The dict parameter $io_redirections is error-prone but I suppose it's OK for this low level function, as long as most of use cases should be covered by high level API spawn_stdio or execute_and_read_output_async.

[fredemmott]

However, /dev/null does not look like a good default value, too, because people merely want to create subprocess and discard the output

I'm missing something: this is exactly why /dev/null is useful:

• this is the usual pattern in the shell, e.g. foo > /dev/null
• programs frequently misbehave if they call open and get fd0-2, thinking it's stdout->stderr. This isn't a bug in this programs because...
• the standards require these handles to be open when calling POSIX programs
• the standards suggest opening 'an unspecified file for the file descriptor'; /dev/null isn't explicitly suggested, but seems like a reasonable choice, as it's valid, accepts any writes, but reads like a 0-byte file.

https://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html

If file descriptor 0, 1, or 2 would otherwise be closed after a successful call to one of the exec family of functions, implementations may open an unspecified file for the file descriptor in the new process image. If a standard utility or a conforming application is executed with file descriptor 0 not open for reading or with file descriptor 1 or 2 not open for writing, the environment in which the utility or application is executed shall be deemed non-conforming, and consequently the utility or application might not behave as described in this standard.

--

That said, I think there's 3 separate common cases for subprocesses:

• just run and discard the output: /dev/null for everything
• run, collect stdout and stderr combined: /dev/null stdin, have both stderr and stdout as the same write-only pipe
• run, collect stdout and stderr combined: /dev/null stdin, stderr and stdout as distinct write-only pipes

Notably, I'm not including 'readable stderr' as a common case from the perspective of spawning subprocesses. This should be supported, but is primarily for interactive processes.

I think it would be useful for:

• true posix-style 'replace the current process' exec, like the PHP pcntl_exec() (which is not currently needed to be part of this design, but we should think at least about how we'd likely want to add it in the future)
• unit testing CLIs

[fredemmott]

bool $setsid = false

We generally consider bool arguments an antipattern and bad for readability - perhaps:

SIDBehavior $sid with SIDBehavior::INHERIT and SIDBehavior::NEW ?

[Atry]

Updated

[fredemmott]

Will the new API support piping multiple processes

Yes but not recommended.

I agree with the reasoning, but not the wording of this :) Perhaps: "yes, however it is rarely needed, often abused, and should be considered a 'code smell'."

[fredemmott]

The proposed subprocess API conforms HSL IO Key Design Decisions. The Hack class IO\WriteFDHandle and IO\WriteFDHandle are accepted as parameters, instead of raw file handles or PHP resources. The Process interface also extends IO\CloseableHandle, supporting the closeWhenDisposed idiom.

I have mixed feelings here: in general, OS\ does not use IO\Handles of any kind.

The current design would clearly be correct if there was a new SubProcess\ namespace

[fredemmott]

When $executable is null, the proposed subprocess API will consider command[0] as the executable and internally use execvpe to resolve the full path from $PATH.

Switching this behavior based on if the command is part of the arguments vector or a separate argument is also a bit surprising to me.

• If using path is not explicit, I would expect it to be based on whether or not the command - however it is provided - starts with a /. AIUI the other cases like ./foo are fine as they're identical whether or not $PATH is used.
• On the other hand, if a check like that is done, using-or-not-using PATH is identical except in the case that . is in $PATH

I'm ~ 60% of the way to: we should have one consistent behavior for using or respecting PATH or not, and one consistent flag to explicitly change the behavior. If so, I'm ~ 70% on the default being to use $PATH to meet user expectations

[Atry]

How about just remove $executable and always resolve the full path from $PATH? This is the Java ProcessBuilder behavior and should cover all user cases, because anyway the user can pass a full path as command[0] if the user don't want to search from $PATH.

[fredemmott]

The proposed subprocess API is similar to PHP or Python, accepting process creation options as parameters. It does not accept options in a shape, because we consider options in shape as a workaround of lacking the language feature of named parameters. Hopefully Hack would support named parameters in the future, making it easier to specify optional parameters.

We shouldn't count on this, and we should design the best API we can for the language we have, rather than the one we hope we'll have in the future :)

If we knew for a fact we were never adding named parameters, would you still want this design?

Builder objects

I'm not saying to switch to builder objects, but I think they could do with more consideration:

• yes, they're a workaround for lack of optional parameters and named parameters - however, we're working in a language without named parameters and don't being anticipate them being added in the short-term.
• specifying one non-default option does not require specifying null or defaults for a bunch of previous options (which ties into the previous two points)
• they support a distinction between 'do not provide this' and 'use default'; we have to use nullable for both - e.g. if $stdin is null, does that mean 'close stdin' or 'use default'? how do I specify the other? This is easy to fit into a builder pattern
• if there are several common and reasonable behaviors for a particular option, several methods can be added, e.g.. ->withStdoutClosed(), ->withStdoutDevNull() (just hypothetically, not concretely those ones).

The last two could be addressed in a function-based approach with nullable enum classes - this would probably be best addressed with a convention like "all process arg enum classes have a 'DEFAULT' member - specifying null is a shorthand for this".

The disadvantages of functions + enum classes are:

• those first two advantages of builder classes stay
• we can add new shortcuts-for-reasonable-behavior to builder classes in the future easily
• we need to pre-emptively use enum classes for anything where we /might/ want to provide multiple reasonable shortcuts in the future, even if we can only think of one now, otherwise it would be a BC break to replace e.g. an IO\WriteFDHandle parameter with a StdoutBehavior enum class parameter

[Atry]

_addclose(): doesn't make sense in Hack/HHVM's model

Why not? Shouldn't it behave the same as /dev/null?

[fredemmott]

_addclose(): doesn't make sense in Hack/HHVM's model

Why not? Shouldn't it behave the same as /dev/null?

Because of the lightprocess worker model, there's already several other processes in the way, and all open FDs are already implicitly closed. Whatever would be passed, it would do nothing that's not already being done

[Atry]

If I understand correctly, the issue described in facebook/folly@b258ee3 seems affecting all users calling posix_spawn_file_actions_addclose (or other equivalent APIs), not only affecting folly or lightprocess worker model.

[fredemmott]

If I understand correctly, the issue described in facebook/folly@b258ee3 seems affecting all users calling posix_spawn_file_actions_addclose (or other equivalent APIs), not only affecting folly or lightprocess worker model.

It does; what the model means is that nothing is inherited or implicitly passed - everything - including the STDIO file handles - must be explicitly passed (though we probably want to hide that from users in common cases). So _addclose doesn't make sense, as every FD will already be closed.

[fredemmott]

how to determine the return type statically

I was looking through the rust subprocess crate, and they have an approach here that we should strongly consider when adding a more complete high-level API: every subprocess has STDIN/STDOUT/STDERR - they can be redirect in different ways, but I'm not seeing a way to spawn a subprocess via the Exec builder with them actually closed. This removes the need for the varying types.

[fredemmott]

So, new version (as of 2021-12-07):

• abstract class PosixSpawnFileAction { - this doesn't really fit with the rest of OS\
  • we're usually just keeping the raw C function names, even when there's a clear grouping
  • if we made an exception, it should be namespaces, not abstract classes+static methods - those are the pattern in FB www due to namespaces being discouraged there.
• spawn:
  • I don't understand the use case here; I think it's just to execute a short-lived program and ignore output? If so, the only thing to do really is to wait for exit and check it - so why not just return Awaitable<void> and throw if non-zero?
  • it's documented as creating no internal pipes; it should set up stdin/stdout/stderr or most subprocesses have undefined behavior - and make sure they're cleaned up on exit
  • some of the comments about it in "design considerations" seem outdated
• closeWhenDisposed: I don't think we should try to make that specific naming a general pattern - terminateWhenDisposed() or killWhenDisposed would be alternatives, depending on if SIGKILL or SIGTERM is sent (or, both)
• execute_and_read_output_async(): naming is very different to spawn, and I'm not seeing a clear reason why? Also means they won't show next to each other in IDE completion, or alphabetical indexes, when they probably should. Should also clearly document what happens to stderr

--

Long-lived process high-level API:

This is very close to 'the OS\ API, but with IO handles'; this seems very verbose, and is duplicating a lot of functionality that exists in IO\ (or needs to be in OS) with a slightly different framing.

I'm not convinced it's the right approach, or that we need one (yet?) - but I don't have a better suggestion.

IMO the best thing to do is leave it out entirely for now, then see what abstractions end up making the most sense when we try to use the other APIs in HHAST, FB WWW, docs.hhvm.com test runner (when talking to the typechecker), and that other users use in their projects.

[fredemmott]

I just use echo as an example here, in the real world, it would be logging into Scuba or syslog, or more complicated interaction.

Then this should be an application-specific function that returns Awaitable<void> - and what should it be built on?

• if you want to log the whole output, wrap execute_and_return_output(): Awaitable<string> (or Awaitable<string, string>, or whatever we do for STDERR)
• if you want to log each write or each line as it is written, wrap something that exposes FDs or handles. If for writes, do as above; if lines, add a buffered reader and use linesIterator()

[fredemmott]

if you want to log each write or each line as it is written, wrap something that exposes FDs or handles. If for writes, do as above; if lines, add a buffered reader and use linesIterator()

This could be an abstract class or two (one for writes, one for lines), with a static ::spawn() method, but that feels better left for later: whatever we design now:

• is based on little knowledge of usage compared to if we built the basics and see us - and others - build on it over time
• is hard to change - becomes a BC issue

There's also a broad question of how much convenience should the HSL provide, and how much should we leave to third-party libraries?

I tend to lean towards third-party libraries beyond the essentials, at least for v1:

• our experience is very FB-biased, and doesn't necessarily doesn't lead us to good solutions for other people's problems. The HSL should contain general solutions, not FB solutions
• it reduces the maintenance and BC surface area
• if third-party libraries do solve this problem, we can evaluate merging their approaches into the HSL later, with knowledge of how well they actually work in practice
• if it's not a pressing enough issue for third party libraries to create a solution, it's likely not worth doing - unless third party libraries haven't done it because it's particularly complicated/requires particular expertise

[Atry]

Long-lived process high-level API:

This is very close to 'the OS\ API, but with IO handles'; this seems very verbose, and is duplicating a lot of functionality that exists in IO\ (or needs to be in OS) with a slightly different framing.

I'm not convinced it's the right approach, or that we need one (yet?) - but I don't have a better suggestion.

IMO the best thing to do is leave it out entirely for now, then see what abstractions end up making the most sense when we try to use the other APIs in HHAST, FB WWW, docs.hhvm.com test runner (when talking to the typechecker), and that other users use in their projects.

The distinguishing between the low level API and the high level API for long-lived sub-processes is like Python's os.posix_spawn v.s. subprocess.Popen.

The original design of this proposal did not include the high level API for long-lived sub-processes, until we explored the possibility of the builder design pattern.

I think the high level API for long-lived sub-processes could be useful because:

1. It is easy to use safely, especially with the help of the tuple typing, in comparison to the low level API that requires the users to create pipes or socketpairs manually.
2. Good default values, especially for /dev/null redirection. We can't implement the default values in the low level API, as the low level API should reflect the unbiased C API.
3. Better interoperability with types under \HH\Lib\IO.

[fredemmott]

Yep, it'll be useful - I just think we (and others) can do it better if we leave it out of v1 and learn from usage of v1 - and it's not urgent enough to override that.

Though, ignoring that, some concrete feedback:

• /dev/null should have options for r, w, rw - then seems unclear why it's a separate thing compared to the existing open_read_write etc
• socketpair feels like an implementation detail, and I don't think it's clear to users why they may want it, unless they're already very familiar with C IO - maybe 'bidirectional_pipe' or similar?
• I think it's too close to the posix_spawn API:
  • the specific shape/structs in OS should not be exposed. e.g. if we add an _np now, but change it to remove the suffix in the future, it should not break callers of a higher-level API
  • some of the libc API design is based on:
    • the limitations the C language
    • adding functionality without changing the function signature

As an example of the last point: I don't think that users are likely to think of 'working directory' as a chdir 'file action' - but as a direct property of the process/processbuilder, or distinct argument to a spawn/exec function. It seems likely that the reasons it is a 'file action' in libc are:

• it's a vendor (BSD) extension, and adding it like that was possible without breaking API or ABI BC
• even if it weren't a vendor extension, it wasn't in v1 of posix_spawn, and doing it like this kept vNext API/ABI BC

[fredemmott]

More broadly, I don't think that 'file actions' is a good concept for the high-level API - dict<int, IO\FDHandle> could be a better place to start, perhaps with an (optional) separate builder for such a dict, like the spawn_stdio() function you mentioned in another thread

[fredemmott]

posix_spawn_file_actions_addclose

I might have been misunderstanding this, and need to test: pretending that it's always implemented with fork and exec, does this do:

fork {
  close_here(); // i.e. close for the subprocess
  exec();
}
or_close_here(); // i.e. close for the parent process

If it's or_close_here() for the parent process, it is useful in HHVM's model - for example, if calling IO\pipe() to make stdin, $w would be passed with adddup2(), but $r would be passed with addclose()

if it's close_here() affecting the subprocess only, it's not useful in HHVM/ack, as all FDs that are not explicitly passed are not available to the child process already.

[Atry]

I assumed all actions specified in posix_spawn_file_actions_t would be executed between fork and exec, otherwise the API performs unexpected side-effect to the parent process, for example, I don't expect posix_spawn_file_actions_chdir would change the working directory for the parent process.

[fredemmott]

That's also my assumption, but we should test and confirm

[fredemmott]

Related note: chdir is currently posix_spawn_file_actions_addchdir_np; the 'np' means 'non-portable' - it was originally a BSD extension.

It is not currently standardized, but it is expected in the next version: https://www.austingroupbugs.net/view.php?id=1208

It is also in glibc 2.29 and above, with very similar behavior.

--

Given we're emulating it with fork_and_execve we can support it on all platforms/glibc, it doesn't matter that we don't have glibc 2.29 on ubuntu 18.04 (and we /could/ also drop support for ubuntu 18.04)

Questions:

Should we use it without a suffix?

IMO not yet, as the standard isn't final yet, and it could change

Should we use the _np suffix, or make up our own (e.g. _hhvm)?

IMO we should use the _np suffix:

• it implies non-portable; people shouldn't expect it to match any particular thing...
• ...but man pages are a useful reference for OS\. Might as well name it what it's a clone of
• whichever way we decide, we should make this a documented convention for OS\.

In a vacuum, I'd prefer some kind of vendor-based-naming, probably with namespaces, but again OS\ is special and generally follows documented standards when they exist, and glibc/BSD libc otherwise

[fredemmott]

-> hhvm/hsl#169

[fredemmott]

To summarize how I see the current state:

Low Level API

• We're agreed on posix_spawn being the appropriate function to expose/emulate.
• It's an open question about the best way to represent the attrs and file actions: Expand `OS\` design notes hhvm/hsl#169
• We've discussed handling of PATH in other contexts, but not here: I think we should expose both posix_spawnp() (uses PATH) and posix_spawn() (does not); it's easy to do both, it gives us flexibility, and fits with OS\ being unopinionated.

OS as a whole

Should it be a thinner layer? I don't think we agree here, but we don't need to to make progress on subprocesses. Being discussed here: hhvm/hsl#169 (comment)

High level API: Awaitable<string>

• I think we're agreed on this being by far the most common case.
• From the previous discussions about path flags, I think we agree that this should always use posix_spawnp(), i.e. respect PATH?
• I don't think we agree on string $command, vec<string> $arguments vs vec<$command_and_arguments>
  • I prefer the separate arguments as it gives the typechecker more insight, and feels like the C APIs (execv and posix_spawn). I don't mean to imply that 'feels like execv' is actually an objectively good thing - I'm just explaining why it feels natural to me
  • This is probably an area where we should proactively seek feedback from others
• I think we agree that this should merge stderr and stdout by default
• We may want to add more options for stderr in the future, but we should leave this for later as we can do it in a BC-compatible way, and it doesn't block us making progress. I dumped my thoughts separately

High level API with FDs, long lived processes

I think this is our biggest area of disagreement - but it doesn't block the other stuff, or - if we provide sufficient power in OS\ - letting users address these problems themselves while we figure out what this should look like.

I think to make progress here, we should try to find - and ask others for - more concrete use cases that aren't addressed by the Awaitable<string> version.

Perhaps the right solution is a single API that is flexible for whatever they need - or perhaps we should have separate functions for:

• "I just want a string/nothing, but it takes a while, but I want a "Process" thing I can interact with"
• "I just want the output, but I need to process it one write/line at a time instead of waiting for the whole process"
• "I need to feed it this string as stdin, but I don't need the output"
• "I need to feed it stdin one chunk at a time"
• "I need to feed stdin and read stdout one chunk at a time" (like a stream processor)
• "I have a request/response or 'interactive' model with this subprocess" (e.g. writing unit tests for repls - very similar to the previous case)
• "I need to provide specific FDs for stdin/stdout" (e.g. 'reinvent inetd in Hack')
• "I want to execute the process and immediately echo the output" (e.g. PHP passthru())
• "I want to execute the process and immediately feed its' output into a logging system"
• "I need to provide arbitrary FDs (e.g. FD 42) for some weird edge case"
• "I want string outputs for both stdout and stderr"

We should decide:

• which of these are important/common enough to optimize for usability
• is it better to optimize more for the most common ones of these and point users at OS\ for the rarer ones, or should we have a more powerful high-level API? I see this as a usability vs power tradeoff
• do we actively want to discourage some of these?

Next steps

• we need to add OS\waitpid_async() or similar as an HHVM builtin
• we need to agree on the function signature for OS\posix_spawn[p](), and the types of everything that feeds in to it
• we need to finalize function naming for the common Awaitable<string> case
• we need to finalize (string, vec<string>) vs (vec(string)) for the same case

I think we should then ship that, and revisit the other questions after:

• digging more into use cases and finding real-world examples
• use the real-world examples to experiment with OS\ and figure out which approaches work best

• we need to finalize function naming for the common Awaitable<string> case

The other use cases should be a factor here; we don't need to decide how to address them, but we should try to pick a name that makes sense/would be consistent with any reasonably likely decision.

[fredemmott]

Leave high level flexible until later, doesn't block high-level common case

I'm making an assumption here about the usability/verbosity of the eventual flexible thing - that people will want something more convenient.

If, for example, we copied rust subprocess exec/popen verbatim (except for not including pipeline support), would we consider this usable enough:

$out = Subprocess\exec('ls')
  ->stdout(Subprocess\Redirection::Pipe)
  ->capture()
  ?->stdout_str();

... or would we still want a dedicated helper? I think we'd still want a dedicated helper, but I'm not sure.

I'm not meaning to start a discussion about if we should base the HSL thing on rust; the important question for now is if there are plausible approaches we may take that would change our mind about the stuff we already agree on.

[azjezz]

High level API for long-lived sub-processes

This to me feels like yet another low level API, not a high level API.

a good example of high level sub-process API that come to mind:

1. https://github.com/symfony/process
2. https://github.com/amphp/process/tree/v2
3. https://docs.rs/async-std/1.10.0/async_std/process/struct.Child.html

---

However, these are the thing that the API missing in my opinion:

• ability to send signals to sub process
• ability to get the status of the current process ( running? finished? )

[fredemmott]

Recapping call:

High-level HSL APIs have different goals to high-level C APIs.

OS\ is not considered a high-level API, and is intended to give the most flexible building blocks to build higher level APIs; this mirrors the C API as these pretty much are the most flexible foundational things that everything else is built on. We aim for enough flexibility here to solve 100% of use cases. It is primarily intended to be called by other HSL functions, not used directly - but direct usage is expected to be necesssary for niche use cases.

The other (high-level) namespaces are intended to:

• make solving common cases safely easy
• make solving common cases unsafely hard
• make solving rarer problems as easy as practical without sacrificing the first 2

'can be used to solve 100% of problems well' is not a goal of the higher-level HSL APIs. For example, File\Handle does not expose high level APIs for many rarer use cases, but they are possible via OS\ and File\Handle::getFileDescriptor()

[fredemmott]

File descriptors:

As I understand it (please correct me :) ) @Atry 's goal here is to make it so you can say "Create FD 5 as a socketpair", and there's a typesafe way to retrieve FD 5 as the appropriate IO\Handle after spawning the process.

I don't think this is needed, and removing this goal allows a much simpler API.

We can provide this just for STDIN/OUT/ERR in a much simpler way as (a) we can use a shape rather than a map (b) we can constrain them. IN should be readable to the process, OUT should be writable, ERR should be read-write (though write is good enough for most).

For other FDs - or even custom behavior on STDIO - we can require that users obtain the FDs themselves (e.g. by calling OS\socketpair()) and pass them in. If a user takes this approach for STDIN/OUT/ERR, our accessors can return null for them.

[Atry]

If we don't need the ability to create socket pairs and pipes in the high level API, then the both APIs would accept OS\FileDescriptor instead of IO\Handle, and the only difference between high level API and low level API is the return type - newtype PID = int vs class Process.

[fredemmott]

both APIs would accept OS\FileDescriptor instead of File\Handle

I think we probably want OS\FileDescriptor in the low-level API, but IO\FDHandle in the high-level API; to support socketpairs, we would want IO\socketpair(), similar to how we have both OS\pipe() and IO\pipe()

the only difference between high level API and low level API is the return type - newtype PID = int vs class Process.

In terms of inputs and outputs, but I'm hoping we end up with a much friendlier spawn interface than posix_spawn() :)

[fredemmott]

hhvm/hsl#177 is also related, but socketpair is likely to be common enough for subprocesses that we shouldn't require that kind of arbitrary unsafeness.

[azjezz]

another thing to point out somehow related to complexity, is that this is promoted as a replacement for PHP function shell_exec.

however, the simplicity offered by shell_exec is much better, i suggest, aside from having the Process API, to also have HH\Lib\Shell\execute(...) function similar to Psl\Shell\execute(...) ( documentation: https://php-standard-library.github.io/#/components/shell/ ).

this can act as a more forward replacement for shell_exec as it's just one function call, with no setup required.

[azjezz]

also to note, in Psl\Shell\execute, I personally don't like $escape argument, and it's left there on purpose in version 2 because there's 1 use case for it, which is to redirect stderr to stdout.

the use case in the wild: https://github.com/laminas/automatic-releases/blob/f4a0b35bf35db0b8a66adcf9b557d4709e4b533f/src/Gpg/ImportGpgKeyFromStringViaTemporaryFile.php#L20-L21

However, in the case of HSL, i would advice against having this argument, if the user ran into a case where the need STDERR content, they can use the Process API instead of Shell.

[fredemmott]

We're pretty unlikely to offer a convenience function that uses the shell due to the security problems (escape functions are not reliable unless you know exactly which shell is being used, and users often forget to call them)

We are however likely to support convenience functions for a simple exec with args and 'just return me the output' behavior - but with no shell behavior. I suspect it would be more limited than the PSL one too - if the more flexible thing ends up being relatively user friendly, it should be easier to write and more readable than having many optional arguments.

there's 1 use case for it, which is to redirect stderr to stdout

if this were supported in such a function, I think we'd use an enum for this:

• DEFAULT: redirect to request stderr if it exists, /dev/null otherwise
• DISCARD: redirect to /dev/null
• MERGE: stdout and stderr get the same fd

[azjezz]

Hmm, enum for stderr behavior is actually an interesting idea 🤔 however, i would say its more fitting to default to discard, some cli applications might use STDERR for logging things which you don't need, and if you are building an application that calls multiple tools, you don't want your tool to be outputting irrelevant logs