nah_overrides.h

Go to the documentation of this file.

/*
 * NAH Overrides - Override Parsing and Application
 * 
 * This file provides helpers for parsing and applying NAH_OVERRIDE_* 
 * environment variables. It uses nlohmann/json for JSON parsing.
 * 
 * Include this header if you want automatic override handling.
 * Otherwise, implement override parsing yourself and modify the
 * CompositionResult.contract.environment after calling nah_compose().
 * 
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef NAH_OVERRIDES_H
#define NAH_OVERRIDES_H
 
#ifdef __cplusplus
 
#include "nah_core.h"
#include <nlohmann/json.hpp>
#include <cstdlib>
 
namespace nah {
namespace overrides {
 
using json = nlohmann::json;
using namespace nah::core;
 
// Portable getenv that avoids MSVC warnings
namespace detail {
inline std::string safe_getenv(const char* name) {
#ifdef _WIN32
    char* buf = nullptr;
    size_t sz = 0;
    if (_dupenv_s(&buf, &sz, name) == 0 && buf != nullptr) {
        std::string result(buf);
        free(buf);
        return result;
    }
    return "";
#else
    const char* val = std::getenv(name);
    return val ? val : "";
#endif
}
} // namespace detail
 
// ============================================================================
// OVERRIDE PARSING
// ============================================================================
 
struct EnvOverrideParseResult {
    bool present = false;       
    bool ok = false;            
    std::string error;          
    std::unordered_map<std::string, std::string> values;  
};
 
inline EnvOverrideParseResult parse_env_override() {
    EnvOverrideParseResult result;
    
    std::string env_val = detail::safe_getenv("NAH_OVERRIDE_ENVIRONMENT");
    if (env_val.empty()) {
        return result;  // Not present
    }
    
    result.present = true;
    
    // Validate JSON first (no exceptions)
    if (!json::accept(env_val)) {
        result.error = "invalid JSON";
        return result;
    }
    
    // Parse with noexcept overload
    auto j = json::parse(env_val, nullptr, false);
    
    if (j.is_discarded()) {
        result.error = "JSON parse failed";
        return result;
    }
    
    if (!j.is_object()) {
        result.error = "expected object";
        return result;
    }
    
    for (auto& [key, val] : j.items()) {
        if (!val.is_string()) {
            result.error = "value for '" + key + "' must be string";
            return result;
        }
        result.values[key] = val.get<std::string>();
    }
    
    result.ok = true;
    return result;
}
 
inline EnvOverrideParseResult parse_env_override(
    const std::unordered_map<std::string, std::string>& process_env)
{
    EnvOverrideParseResult result;
    
    auto it = process_env.find("NAH_OVERRIDE_ENVIRONMENT");
    if (it == process_env.end()) {
        return result;  // Not present
    }
    
    result.present = true;
    
    const std::string& env_val = it->second;
    
    // Validate JSON first (no exceptions)
    if (!json::accept(env_val)) {
        result.error = "invalid JSON";
        return result;
    }
    
    // Parse with noexcept overload
    auto j = json::parse(env_val, nullptr, false);
    
    if (j.is_discarded()) {
        result.error = "JSON parse failed";
        return result;
    }
    
    if (!j.is_object()) {
        result.error = "expected object";
        return result;
    }
    
    for (auto& [key, val] : j.items()) {
        if (!val.is_string()) {
            result.error = "value for '" + key + "' must be string";
            return result;
        }
        result.values[key] = val.get<std::string>();
    }
    
    result.ok = true;
    return result;
}
 
// ============================================================================
// OVERRIDE POLICY HELPERS
// ============================================================================
 
inline bool is_key_allowed(const std::string& key, const HostEnvironment& host_env) {
    if (!host_env.overrides.allow_env_overrides) {
        return false;
    }
    if (host_env.overrides.allowed_env_keys.empty()) {
        return true;  // No allowlist = all keys allowed
    }
    for (const auto& allowed : host_env.overrides.allowed_env_keys) {
        if (allowed == key) {
            return true;
        }
    }
    return false;
}
 
// ============================================================================
// OVERRIDE APPLICATION
// ============================================================================
 
inline void apply_overrides(
    CompositionResult& result,
    const HostEnvironment& host_env,
    const std::unordered_map<std::string, std::string>& process_env)
{
    if (!result.ok) {
        return;  // Don't apply overrides to failed compositions
    }
    
    auto parsed = parse_env_override(process_env);
    
    if (!parsed.present) {
        return;  // No override to apply
    }
    
    if (!parsed.ok) {
        // Parse failure
        result.warnings.push_back({
            warning_to_string(Warning::override_invalid),
            "warn",
            {
                {"target", "NAH_OVERRIDE_ENVIRONMENT"},
                {"reason", "parse_failure"},
                {"source_kind", trace_source::PROCESS_ENV},
                {"source_ref", "NAH_OVERRIDE_ENVIRONMENT"}
            }
        });
        return;
    }
    
    // Check global override permission
    if (!host_env.overrides.allow_env_overrides) {
        result.warnings.push_back({
            warning_to_string(Warning::override_denied),
            "warn",
            {
                {"target", "NAH_OVERRIDE_ENVIRONMENT"},
                {"reason", "overrides_disabled"},
                {"source_kind", trace_source::PROCESS_ENV},
                {"source_ref", "NAH_OVERRIDE_ENVIRONMENT"}
            }
        });
        return;
    }
    
    // Apply overrides, checking per-key permissions
    for (const auto& [key, value] : parsed.values) {
        if (is_key_allowed(key, host_env)) {
            result.contract.environment[key] = value;
        } else {
            result.warnings.push_back({
                warning_to_string(Warning::override_denied),
                "warn",
                {
                    {"target", key},
                    {"reason", "key_not_allowed"},
                    {"source_kind", trace_source::PROCESS_ENV},
                    {"source_ref", "NAH_OVERRIDE_ENVIRONMENT"}
                }
            });
        }
    }
}
 
inline void apply_overrides(CompositionResult& result, const HostEnvironment& host_env)
{
    if (!result.ok) {
        return;
    }
    
    auto parsed = parse_env_override();
    
    if (!parsed.present) {
        return;
    }
    
    if (!parsed.ok) {
        result.warnings.push_back({
            warning_to_string(Warning::override_invalid),
            "warn",
            {
                {"target", "NAH_OVERRIDE_ENVIRONMENT"},
                {"reason", "parse_failure"},
                {"source_kind", trace_source::PROCESS_ENV},
                {"source_ref", "NAH_OVERRIDE_ENVIRONMENT"}
            }
        });
        return;
    }
    
    if (!host_env.overrides.allow_env_overrides) {
        result.warnings.push_back({
            warning_to_string(Warning::override_denied),
            "warn",
            {
                {"target", "NAH_OVERRIDE_ENVIRONMENT"},
                {"reason", "overrides_disabled"},
                {"source_kind", trace_source::PROCESS_ENV},
                {"source_ref", "NAH_OVERRIDE_ENVIRONMENT"}
            }
        });
        return;
    }
    
    for (const auto& [key, value] : parsed.values) {
        if (is_key_allowed(key, host_env)) {
            result.contract.environment[key] = value;
        } else {
            result.warnings.push_back({
                warning_to_string(Warning::override_denied),
                "warn",
                {
                    {"target", key},
                    {"reason", "key_not_allowed"},
                    {"source_kind", trace_source::PROCESS_ENV},
                    {"source_ref", "NAH_OVERRIDE_ENVIRONMENT"}
                }
            });
        }
    }
}
 
} // namespace overrides
} // namespace nah
 
#endif // __cplusplus
 
#endif // NAH_OVERRIDES_H