reload_controller.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/format/reload/reload_transaction.hpp>
#include <pulp/format/reload/reload_trust_policy.hpp>
#include <pulp/runtime/crypto.hpp>
 
#include <array>
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <fstream>
#include <optional>
#include <string>
#include <system_error>
#include <utility>
 
#if defined(_WIN32)
#include <process.h>
#else
#include <cerrno>
#include <csignal>
#include <unistd.h>
#endif
 
namespace pulp::format::reload {
 
// True if `pid` names a live process. On POSIX, kill(pid,0) succeeds (0) or
// fails with EPERM when the process exists but we lack permission; ESRCH means
// it's gone. On Windows we have no cheap portable check, so we report "not
// alive" and rely on the fact that a loaded module's file is locked — remove()
// then fails harmlessly, so we never delete a live instance's mapped image.
inline bool staged_pid_is_alive(long pid) {
#if defined(_WIN32)
    (void)pid;
    return false;
#else
    if (::kill(static_cast<::pid_t>(pid), 0) == 0) return true;
    return errno == EPERM;
#endif
}
 
// Reap stale staged copies (`<stem>.initial.<pid>.*` / `<stem>.reload.<pid>.*`)
// left by DEAD processes — dev-loop litter that accumulates because each run
// stages under a unique pid+counter name (ReloadableShell::stage_initial and
// ReloadController::stage_and_reload). Best-effort and startup-only. Files whose
// embedded PID is still a live process are left untouched, so a concurrently
// running instance's staged images are never removed.
inline void reap_stale_staged(const std::filesystem::path& dir,
                              const std::string& stem) {
    namespace fs = std::filesystem;
    std::error_code ec;
    if (!fs::is_directory(dir, ec)) return;
    const std::string prefixes[2] = {stem + ".initial.", stem + ".reload."};
    for (fs::directory_iterator it(dir, ec), end; !ec && it != end; it.increment(ec)) {
        const std::string fn = it->path().filename().string();
        std::size_t pos = std::string::npos;
        for (const auto& p : prefixes)
            if (fn.rfind(p, 0) == 0) { pos = p.size(); break; }
        if (pos == std::string::npos) continue;
        const std::size_t dot = fn.find('.', pos);          // pid runs up to the next '.'
        if (dot == std::string::npos || dot == pos) continue;
        long pid = 0;
        const std::string pid_str = fn.substr(pos, dot - pos);
        try { pid = std::stol(pid_str); } catch (...) { continue; }
        if (pid <= 0 || staged_pid_is_alive(pid)) continue;  // keep live-owned files
        std::error_code rm;
        fs::remove(it->path(), rm);                          // best-effort
    }
}
 
class ReloadController {
public:
    ReloadController(ReloadSession& session, std::filesystem::path logic_path,
                     std::filesystem::path stage_dir = {},
                     ReloadTrustPolicy trust_policy = {})
        : session_(session), path_(std::move(logic_path)),
          stage_dir_(stage_dir.empty() ? path_.parent_path() : std::move(stage_dir)),
          trust_policy_(std::move(trust_policy)) {
        // Startup housekeeping: clear dead-process staged litter so a long dev
        // history doesn't leave hundreds of <stem>.initial.*/<stem>.reload.*
        // copies behind (bounds staged-copy accumulation across restarts).
        reap_stale_staged(stage_dir_, path_.stem().string());
    }

    std::optional<ReloadOutcome> poll() {
        const auto mtime = current_mtime();
        if (!mtime) return std::nullopt;          // missing / unreadable — nothing to do
        if (!baseline_set_) {                     // first sight: record, don't reload
            last_mtime_ = *mtime;
            if (const auto h = hash_file(path_)) { last_hash_ = *h; hash_valid_ = true; }
            baseline_set_ = true;
            return std::nullopt;
        }
        if (*mtime == last_mtime_) return std::nullopt;  // unchanged mtime
        last_mtime_ = *mtime;                     // act once per distinct mtime
 
        // Content-hash gate: an mtime bump does not prove the BYTES
        // changed. Distinguish the three non-reload cases from a real edit:
        //   - empty / unreadable right now (a rebuild mid-write) → skip; the next
        //     completed write (new mtime) is retried.
        //   - identical content (a `touch`, or a rebuild that produced byte-
        //     identical output) → skip; no redundant stage + dlopen + gate churn.
        //   - genuinely new bytes → record the hash and reload.
        const auto hash = hash_file(path_);
        if (!hash) return std::nullopt;           // empty / unreadable → not a real version yet
        if (hash_valid_ && *hash == last_hash_) return std::nullopt;  // unchanged content
        last_hash_ = *hash;
        hash_valid_ = true;
        return stage_and_reload();
    }

    ReloadOutcome reload_now() {
        if (const auto mtime = current_mtime()) {
            last_mtime_ = *mtime;
            baseline_set_ = true;
        }
        if (const auto hash = hash_file(path_)) {   // resync the content baseline too
            last_hash_ = *hash;
            hash_valid_ = true;
        }
        return stage_and_reload();
    }
 
    const std::filesystem::path& path() const { return path_; }
    std::uint64_t reload_attempts() const { return attempts_; }

    struct Baseline {
        std::filesystem::file_time_type mtime{};
        std::uint64_t hash = 0;
    };
    std::optional<Baseline> baseline() const {
        if (!baseline_set_ || !hash_valid_)
            return std::nullopt;
        return Baseline{last_mtime_, last_hash_};
    }

    void set_baseline(const Baseline& b) {
        last_mtime_ = b.mtime;
        last_hash_ = b.hash;
        hash_valid_ = true;
        baseline_set_ = true;
    }

    static std::optional<std::uint64_t> content_hash(const std::filesystem::path& p) {
        return hash_file(p);
    }
 
private:
    std::optional<std::filesystem::file_time_type> current_mtime() const {
        std::error_code ec;
        const auto t = std::filesystem::last_write_time(path_, ec);
        if (ec) return std::nullopt;
        return t;
    }
 
    // FNV-1a 64-bit over the watched file's bytes — a content fingerprint for
    // change detection only (not security; the fail-closed ABI/fingerprint/
    // contract gates are the trust boundary). Returns nullopt for an unreadable
    // OR empty file (an empty logic image is never a real version — usually a
    // rebuild mid-write), so the caller skips rather than acting on it.
    static std::optional<std::uint64_t> hash_file(const std::filesystem::path& p) {
        std::ifstream f(p, std::ios::binary);
        if (!f) return std::nullopt;
        std::uint64_t h = 1469598103934665603ULL;   // FNV offset basis
        std::array<char, 64 * 1024> buf{};
        std::size_t total = 0;
        while (f) {
            f.read(buf.data(), static_cast<std::streamsize>(buf.size()));
            const std::streamsize got = f.gcount();
            for (std::streamsize i = 0; i < got; ++i) {
                h ^= static_cast<unsigned char>(buf[static_cast<std::size_t>(i)]);
                h *= 1099511628211ULL;                // FNV prime
            }
            total += static_cast<std::size_t>(got);
        }
        if (f.bad() || total == 0) return std::nullopt;  // unreadable or empty
        return h;
    }
 
    // SHA-256 (hex) of a file's bytes, for confirming the staged image matches the
    // signed manifest hash. std::nullopt if the file can't be read.
    static std::optional<std::string> sha256_of_file(const std::filesystem::path& p) {
        std::ifstream f(p, std::ios::binary);
        if (!f) return std::nullopt;
        const std::string bytes((std::istreambuf_iterator<char>(f)),
                                std::istreambuf_iterator<char>());
        return runtime::sha256_hex(bytes);
    }
 
    // Copy the watched file to a fresh, uniquely-named path and reload THAT, so
    // the loader reads the new bytes rather than returning a cached image for a
    // path it already opened.
    ReloadOutcome stage_and_reload() {
        ++attempts_;
        // require_signed enforcement (opt-in; default OFF = the frictionless dev
        // loop). Verify the WATCHED file's signed pack BEFORE staging, then confirm
        // AFTER the stage copy that the staged bytes we actually load still match the
        // signed hash. The copy re-reads path_, so verifying only the source would
        // leave a verify→copy TOCTOU (a racing writer could swap in unsigned bytes
        // between the check and the copy); re-hashing the staged image closes it,
        // mirroring pack_install's verify-the-published-bytes rule. Fail closed
        // throughout — a refusal returns without loading anything.
        std::string expected_signed_sha;  // signed SHA-256 of the watched member
        if (trust_policy_.require_signed) {
            auto decision = resolve_reload_trust(path_, trust_policy_);
            if (auto* refused = std::get_if<ReloadOutcome>(&decision)) return *refused;
            if (auto* trust = std::get_if<SwapPackTrust>(&decision)) {
                if (auto rejected = verify_pack_before_load(*trust, path_.string()))
                    return *rejected;
                const std::string member = path_.filename().string();
                for (const auto& f : trust->manifest.files)
                    if (f.path == member) { expected_signed_sha = f.sha256_hex; break; }
                if (expected_signed_sha.empty())
                    return {ReloadOutcome::Status::RejectedIntegrity,
                            "require_signed: watched file is not a named member of its "
                            "signed manifest"};
            }
        }
        // Stage to a name unique per-INSTANCE and per-process. Two shells
        // watching the same logic_path share a default stage_dir (the watched
        // file's directory), so a name keyed only on a per-controller counter
        // (both start at 1) collides: the second instance's copy_file races the
        // first's dlopen of the same path, and on Linux an overwrite-while-mapped
        // corrupts the other instance's live image (see the header note + the
        // identical hazard ReloadableShell::stage_initial guards). PID
        // disambiguates processes; the process-wide atomic counter disambiguates
        // instances and successive reloads within a process.
        static std::atomic<std::uint64_t> global_counter{0};
        const long pid =
#if defined(_WIN32)
            static_cast<long>(::_getpid());
#else
            static_cast<long>(::getpid());
#endif
        const auto staged =
            stage_dir_ /
            (path_.stem().string() + ".reload." + std::to_string(pid) + "." +
             std::to_string(global_counter.fetch_add(1, std::memory_order_relaxed)) +
             path_.extension().string());
        std::error_code ec;
        std::filesystem::copy_file(
            path_, staged, std::filesystem::copy_options::overwrite_existing, ec);
        if (ec) {
            return {ReloadOutcome::Status::RejectedLoadFailed,
                    "stage copy failed: " + ec.message()};
        }
        // Close the verify→copy TOCTOU: the bytes we are about to load are the
        // staged copy, so re-hash IT against the signed member hash. If path_ was
        // swapped between the verify above and the copy, the staged bytes won't
        // match and we refuse (and drop the untrusted stage copy) before any load.
        if (!expected_signed_sha.empty()) {
            const auto staged_sha = sha256_of_file(staged);
            if (!staged_sha || *staged_sha != expected_signed_sha) {
                std::error_code rm;
                std::filesystem::remove(staged, rm);
                return {ReloadOutcome::Status::RejectedIntegrity,
                        "require_signed: staged bytes do not match the signed hash "
                        "(source changed after verification) — refused"};
            }
        }
        // Best-effort reap THIS instance's previous staged copy so a long dev
        // session doesn't accumulate one file per reload. Safe: on POSIX the
        // prior image was dlopen'd (LeakPolicy::Retain) and its mapping survives
        // unlink, so the fading-out processor keeps running; on Windows a loaded
        // module's file is locked, so remove() fails and is ignored. Only reaps
        // our own files — never another instance's, and never the just-staged
        // one. (Cross-restart orphans from dead PIDs are a separate startup-reap
        // follow-up under the staged-file bookkeeping.)
        if (!last_staged_.empty() && last_staged_ != staged) {
            std::error_code rm_ec;
            std::filesystem::remove(last_staged_, rm_ec);
        }
        last_staged_ = staged;
        return session_.reload(staged.string());
    }
 
    ReloadSession& session_;
    std::filesystem::path path_;
    std::filesystem::path stage_dir_;
    ReloadTrustPolicy trust_policy_;  // opt-in require_signed enforcement (default OFF)
    std::filesystem::file_time_type last_mtime_{};
    std::filesystem::path last_staged_;  // this instance's prior staged copy (reaped on next stage)
    std::uint64_t last_hash_ = 0;        // content hash last acted on
    bool hash_valid_ = false;            // last_hash_ has been established
    bool baseline_set_ = false;
    std::uint64_t attempts_ = 0;
};
 
} // namespace pulp::format::reload