Process.hpp

// SPDX-FileCopyrightText: 2026 Vincent Leroy
// SPDX-License-Identifier: MIT
//
// This file is part of dfx.
//
// Licensed under the MIT License. See the LICENSE file in the project root
// for full license information.
 
#pragma once
 
// Standard includes
#include <chrono>
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <sys/types.h>
#include <variant>
#include <vector>
 
// Project includes
#include <dfx-fdwatch/Events.hpp>
#include <dfx-fdwatch/PollerFd.hpp>
#include <dfx-utilities/EnumString.hpp>
#include <dfx-utilities/FileSystem.hpp>
#include <dfx-utilities/PrivateState.hpp>
 
namespace dfx::FdWatch
{
class Poller;
} // !namespace dfx::FdWatch
 
namespace dfx::Subprocess
{
class Process
{
    DFX_PRIVATE_STATE(Process, DFX_SUBPROCESS_LOGGER())
 
public:
    enum class StreamMode : std::uint8_t
    {
        Forward,

        Close,

        Pipe,
    };

    enum class Which : std::uint8_t
    {
        Stdin,  
        Stdout, 
        Stderr  
    };

    enum class EnvMode : std::uint8_t
    {
        Replace, 
        Merge,   
    };
 
public:
    using NotificationCallback = std::move_only_function<void ()>;

    using ReadCallback         = std::move_only_function<void (std::string)>;
 
public:
    struct CaptureConfig
    {
        std::size_t maxSize = 1 * 1024 * 1024;
    };

    struct Config
    {
        fs::path bin;
        std::vector<std::string> args;
        std::vector<std::string> env;

        std::optional<fs::path> cwd;

        EnvMode envMode = EnvMode::Merge;

        StreamMode stdinMode = StreamMode::Forward;
        StreamMode stdoutMode = StreamMode::Forward;
        StreamMode stderrMode = StreamMode::Forward;

        CaptureConfig stdoutCaptureConfig;
        CaptureConfig stderrCaptureConfig;

        bool useParentDeathSignal = true;

        std::optional<uid_t> uid;
        std::optional<gid_t> gid;
        bool newSid = false;
    };
 
public:
    enum class ChildExecStage : std::uint32_t
    {
        SigmaskUnblock,         
        SetParentDeathSignal,   
        CheckParentAlive,       
        SetUid,                 
        SetGid,                 
        SetSid,                 
        ChangeWorkingDirectory, 
        DupStdin,               
        DupStdout,              
        DupStderr,              
        Execve,                 
    };

    struct SpawnError
    {
        ChildExecStage stage; 
        int err;              
    };

    struct Exited
    {
        int code; 
    };

    struct Signaled
    {
        int signal;      
        bool coreDumped; 
    };

    struct ExitStatus : public std::variant<std::monostate, SpawnError, Exited, Signaled>
    {
        using std::variant<std::monostate, SpawnError, Exited, Signaled>::variant;

        bool isSet() const noexcept        { return !std::holds_alternative<std::monostate>(*this); }
        bool isSpawnError() const noexcept { return std::holds_alternative<SpawnError>(*this); }
        bool isExited() const noexcept     { return std::holds_alternative<Exited>(*this); }
        bool isSignaled() const noexcept   { return std::holds_alternative<Signaled>(*this); }

        SpawnError const & toSpawnError() const { return std::get<SpawnError>(*this); }
        Exited const & toExited() const         { return std::get<Exited>(*this); }
        Signaled const & toSignaled() const     { return std::get<Signaled>(*this); }
    };
 
public:
    static constexpr auto infinite = std::chrono::milliseconds(-1);
 
public:
    Process(FdWatch::Poller & poller, Config config);
    DFX_PRIVATE_STATE_DECLARE_RULE_OF_5(Process);

    Utils::BorrowedFd pidfd() const noexcept;
    pid_t pid() const noexcept;
    bool isRunning() const noexcept;
    Config const & config() const noexcept;
    fs::path const & resolvedBinPath() const noexcept;

    ExitStatus const & lastExitStatus() const noexcept;
 
public:
    std::string takeStdout() noexcept;
    std::string takeStderr() noexcept;
 
public:
    void start();

    void stop(std::chrono::milliseconds timeout = infinite);

    void kill();

    void sendSignal(int sig);

    void write(std::string data, NotificationCallback onWriteFinishedCb = nullptr);

    void registerReadCallback(Which stream, ReadCallback onReadyReadCb);

    void registerTerminationCallback(NotificationCallback onChildFinishedCb);

    void close(Which stream) noexcept;
 
public:
    static fs::path resolveProgramPath(fs::path const & bin);
 
public:
    static pid_t forkWithPidfd(int & pidfd) noexcept;
    static int pidfdSendSignal(int pidfd, int sig) noexcept;
};
} // !namespace dfx::Subprocess
 
DFX_DECLARE_ENUM_STRING_FUNCTIONS(dfx::Subprocess::Process::StreamMode);
DFX_DECLARE_ENUM_STRING_FUNCTIONS(dfx::Subprocess::Process::Which);
DFX_DECLARE_ENUM_STRING_FUNCTIONS(dfx::Subprocess::Process::ChildExecStage);