futu_core/

log.rs

use std::path::Path;
use std::sync::OnceLock;

use tracing_subscriber::{
    EnvFilter, Layer, filter::filter_fn, fmt, layer::SubscriberExt, reload, util::SubscriberInitExt,
};

/// 全局人类可读日志时间戳：使用系统本地时区并输出 RFC3339 offset。
///
/// 默认 tracing formatter 使用 UTC (`Z`)；本项目排障通常发生在 Asia/Shanghai /
/// Asia/Hong_Kong 时区，UTC 时间会让用户对照真机事件时多一层换算。这里不写死
/// `+08:00`，而是读取 OS local timezone；部署到其他地区时仍按当地日志习惯输出。
#[derive(Clone, Copy, Debug)]
pub struct LocalRfc3339Timer;

impl fmt::time::FormatTime for LocalRfc3339Timer {
    fn format_time(&self, w: &mut fmt::format::Writer<'_>) -> std::fmt::Result {
        write!(
            w,
            "{}",
            chrono::Local::now().to_rfc3339_opts(chrono::SecondsFormat::Micros, true)
        )
    }
}

/// **v1.4.106 codex 1110 F7 [P2]** — 全局 EnvFilter reload handle，
/// 支持运行时通过 `RemoteCmd set_log_level` 修改 tracing filter。
///
/// 在 `init_logging_with_level` / `init_json_logging_with_level` /
/// `init_logging_with_audit` 三个入口里 install reload layer 时写入；
/// `set_runtime_log_level` 在外部业务 handler 里 reload。
///
/// **唯一性约束**：tracing global subscriber 只能 init 一次，所以同进程仅一份
/// reload handle。重复 init 会被 `tracing_subscriber::registry().try_init()`
/// 失败，此 handle 也只 set 一次（`OnceLock`）。
static GLOBAL_RELOAD_HANDLE: OnceLock<reload::Handle<EnvFilter, tracing_subscriber::Registry>> =
    OnceLock::new();

/// 解析 RemoteCmd 风格的 level 字符串（"no" / "debug" / "info" / ...）到
/// EnvFilter 字符串（"off" / "debug" / "info" / ...）。
///
/// 对齐 C++ RemoteCmd `set_log_level` 支持的 6 个 level 值。
fn map_remote_level_to_env_filter(level: &str) -> Option<&'static str> {
    match level.to_lowercase().as_str() {
        "no" => Some("off"),
        "debug" => Some("debug"),
        "info" => Some("info"),
        "warning" => Some("warn"),
        "error" => Some("error"),
        "fatal" => Some("error"), // tracing 没 fatal，等价 error
        _ => None,
    }
}

/// **v1.4.106 codex 1110 F7 [P2] Stable API** — 运行时修改 tracing filter level。
///
/// - 接受 RemoteCmd 风格的 level 值（"no" / "debug" / "info" / "warning" /
///   "error" / "fatal"），内部映射到 `EnvFilter` 接受的等价值。
/// - 修改成功 → 返 `Ok(applied_filter_string)`，调用方可作 verify 提示。
/// - 修改失败 → 返 `Err(reason)`：
///   - "level invalid": level 字符串不在合法集合
///   - "reload handle not initialized": init_logging 没用 reload-aware 入口
///     （或 .init() 失败）
///   - "reload failed: <e>": tracing_subscriber 内部 reload 错（一般极罕见）
///
/// 调用此函数后，所有现有 `tracing::*!` 宏的过滤器会立刻按新 filter 工作，
/// 不需要重启进程。这是真"effect"，配 `RemoteCmd set_log_level` 修复
/// silent-success 反模式。
pub fn set_runtime_log_level(level: &str) -> Result<String, String> {
    let mapped = match map_remote_level_to_env_filter(level) {
        Some(s) => s,
        None => return Err("level invalid".to_string()),
    };

    let handle = match GLOBAL_RELOAD_HANDLE.get() {
        Some(h) => h,
        None => return Err("reload handle not initialized".to_string()),
    };

    let new_filter = EnvFilter::try_new(mapped)
        .map_err(|e| format!("EnvFilter parse failed for '{mapped}': {e}"))?;

    handle
        .reload(new_filter)
        .map_err(|e| format!("reload failed: {e}"))?;

    Ok(mapped.to_string())
}

/// **v1.4.106 codex 1110 F7 [P2]** — query 当前 reload handle 是否已 install。
/// handler 用来给用户 helpful error message。
pub fn is_runtime_reload_available() -> bool {
    GLOBAL_RELOAD_HANDLE.get().is_some()
}

/// **Stable API** — 初始化日志系统（stderr fmt layer）。
///
/// 优先级: RUST_LOG 环境变量 > level 参数 > 默认 info
///
/// v1.4.106 codex 1110 F7 [P2]：install runtime reload handle（用于
/// `RemoteCmd set_log_level` 真切 filter）。
pub fn init_logging_with_level(level: &str) {
    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(level));
    let (filter_layer, reload_handle) = reload::Layer::new(filter);

    let fmt_layer = fmt::layer()
        .with_timer(LocalRfc3339Timer)
        .with_target(true)
        .with_thread_ids(true)
        .with_file(true)
        .with_line_number(true)
        .with_writer(std::io::stderr);

    let registry = tracing_subscriber::registry()
        .with(filter_layer)
        .with(fmt_layer);
    if registry.try_init().is_ok() {
        // 仅 init 成功时 set 全局 handle（重复 init 不覆盖）。
        let _ = GLOBAL_RELOAD_HANDLE.set(reload_handle);
    }
}

/// **Stable API** — 初始化日志系统（默认 info 级别）。examples / 测试程序
/// 常用入口。
pub fn init_logging() {
    init_logging_with_level("info");
}

/// **Stable API** — 初始化 JSON 格式日志（生产环境 / 日志聚合用）。
///
/// v1.4.106 codex 1110 F7 [P2]：install runtime reload handle。
pub fn init_json_logging_with_level(level: &str) {
    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(level));
    let (filter_layer, reload_handle) = reload::Layer::new(filter);

    let fmt_layer = fmt::layer()
        .json()
        .with_timer(LocalRfc3339Timer)
        .with_target(true)
        .with_thread_ids(true);

    let registry = tracing_subscriber::registry()
        .with(filter_layer)
        .with(fmt_layer);
    if registry.try_init().is_ok() {
        let _ = GLOBAL_RELOAD_HANDLE.set(reload_handle);
    }
}

/// **Stable API** — 初始化 JSON 格式日志（默认 info 级别）。
pub fn init_json_logging() {
    init_json_logging_with_level("info");
}

/// **Stable API** — 初始化日志 + 可选的 audit JSONL 文件。
///
/// - 常规事件走 stderr（与 [`init_logging_with_level`] 一致）
/// - 如果 `audit_path` 传了，额外加一个 JSON 层，只捕获 `target = "futu_audit"` 的
///   事件并写到文件 / 目录。返回的 `WorkerGuard` 必须保留到进程退出，否则
///   tracing-appender 的后台线程可能丢事件。
/// - 传 `None` 时返回 `Ok(None)`，等价于 `init_logging_with_level`。
pub fn init_logging_with_audit(
    level: &str,
    audit_path: Option<&Path>,
) -> std::io::Result<Option<tracing_appender::non_blocking::WorkerGuard>> {
    let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new(level));
    // v1.4.106 codex 1110 F7 [P2]: install reload handle for runtime set_log_level.
    let (filter_layer, reload_handle) = reload::Layer::new(filter);

    let fmt_layer = fmt::layer()
        .with_timer(LocalRfc3339Timer)
        .with_target(true)
        .with_thread_ids(true)
        .with_file(true)
        .with_line_number(true)
        .with_writer(std::io::stderr);

    let registry = tracing_subscriber::registry()
        .with(filter_layer)
        .with(fmt_layer);

    let init_ok = if let Some(path) = audit_path {
        // 用 futu-auth 的 open_writer（单文件 or 每日滚动目录）
        let (writer, guard) = open_audit_writer(path)?;
        let audit_layer = fmt::layer()
            .json()
            .flatten_event(true)
            .with_current_span(false)
            .with_span_list(false)
            .with_target(true)
            .with_writer(writer)
            .with_filter(filter_fn(|meta| meta.target() == "futu_audit"));
        let init_ok = registry.with(audit_layer).try_init().is_ok();
        if init_ok {
            let _ = GLOBAL_RELOAD_HANDLE.set(reload_handle);
        }
        return Ok(if init_ok { Some(guard) } else { None });
    } else {
        let ok = registry.try_init().is_ok();
        if ok {
            let _ = GLOBAL_RELOAD_HANDLE.set(reload_handle);
        }
        ok
    };
    let _ = init_ok;
    Ok(None)
}

/// 打开 audit 日志 writer。为了避免 futu-core 反向依赖 futu-auth，
/// 这里复制了 `futu_auth::audit::open_writer` 的启发式逻辑。两者行为必须一致，
/// 任一改动都要同步对方。
///
/// v1.4.87 CLAUDE.md 坑 #49: 目录 0700 / 文件 0600 + /tmp/ world-readable warn.
/// futu-core 不依赖 futu-auth, 所以 helper 在本文件 duplicate.
fn open_audit_writer(
    path: &Path,
) -> std::io::Result<(
    tracing_appender::non_blocking::NonBlocking,
    tracing_appender::non_blocking::WorkerGuard,
)> {
    let is_dir_hint = path.is_dir()
        || path.as_os_str().to_string_lossy().ends_with('/')
        || path.extension().is_none();

    // v1.4.87: /tmp world-readable warn
    warn_if_world_readable_path(path);

    if is_dir_hint {
        std::fs::create_dir_all(path)?;
        tighten_dir_perms(path); // v1.4.87: 0700
        // v1.4.93 BUG-5318-001 (跨 4 版半修补完): rolling::daily 创建文件不带
        // mode → 默认 umask-dependent (典型 0644). 见 futu-auth audit.rs 同款修法.
        tighten_log_files_in_dir(path);
        let appender = tracing_appender::rolling::daily(path, "futu-audit.log");
        let wrapped = Mode0600Appender::new(appender, path.to_path_buf());
        Ok(tracing_appender::non_blocking(wrapped))
    } else {
        if let Some(parent) = path.parent()
            && !parent.as_os_str().is_empty()
        {
            std::fs::create_dir_all(parent)?;
            tighten_dir_perms(parent); // v1.4.87: 0700
        }
        let file = open_file_0600(path)?; // v1.4.87: 0600
        Ok(tracing_appender::non_blocking(file))
    }
}

/// v1.4.87 CLAUDE.md 坑 #49: 同 `futu_auth::audit::tighten_dir_perms`.
/// 必须和 futu-auth 版本同步, 当前 duplicate 避免循环依赖.
fn tighten_dir_perms(path: &Path) {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        if let Ok(meta) = std::fs::metadata(path) {
            let cur = meta.permissions().mode() & 0o777;
            if cur & 0o077 != 0 {
                let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700));
            }
        }
    }
    #[cfg(not(unix))]
    {
        let _ = path;
    }
}

/// v1.4.87 CLAUDE.md 坑 #49: 同 `futu_auth::audit::open_file_0600`.
fn open_file_0600(path: &Path) -> std::io::Result<std::fs::File> {
    let mut opts = std::fs::OpenOptions::new();
    opts.append(true).create(true);
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        opts.mode(0o600);
    }
    let file = opts.open(path)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        if let Ok(meta) = file.metadata() {
            let cur = meta.permissions().mode() & 0o777;
            if cur & 0o077 != 0 {
                let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600));
            }
        }
    }
    Ok(file)
}

/// v1.4.87 CLAUDE.md 坑 #49: 同 `futu_auth::audit::warn_if_world_readable_path`.
fn warn_if_world_readable_path(path: &Path) {
    let s = path.as_os_str().to_string_lossy();
    let world_readable_prefixes = ["/tmp/", "/var/tmp/", "/private/tmp/", "/tmp"];
    for prefix in &world_readable_prefixes {
        if s == *prefix || s.starts_with(prefix) {
            eprintln!(
                "⚠️  audit log path {s:?} 位于 world-readable 目录 (mode 1777). \
                 audit log 含账户 id + redacted token 占位 + timestamp, 同机其他\n\
                 用户 (包括 agent skill) 可读. 建议改用 ~/.futu-opend-rs/logs/ \
                 或 /var/log/futu/ 等 0700 目录."
            );
            break;
        }
    }
}

/// v1.4.93 BUG-5318-001: 同 `futu_auth::audit::Mode0600Appender`. 必须和
/// futu-auth 版本同步, 当前 duplicate 避免循环依赖.
struct Mode0600Appender {
    inner: tracing_appender::rolling::RollingFileAppender,
    dir: std::path::PathBuf,
    last_tighten: std::sync::atomic::AtomicU64,
}

impl Mode0600Appender {
    fn new(inner: tracing_appender::rolling::RollingFileAppender, dir: std::path::PathBuf) -> Self {
        Self {
            inner,
            dir,
            last_tighten: std::sync::atomic::AtomicU64::new(0),
        }
    }

    fn maybe_tighten(&self) {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .map(|d| d.as_secs())
            .unwrap_or(0);
        let last = self.last_tighten.load(std::sync::atomic::Ordering::Relaxed);
        if now > last
            && self
                .last_tighten
                .compare_exchange(
                    last,
                    now,
                    std::sync::atomic::Ordering::Relaxed,
                    std::sync::atomic::Ordering::Relaxed,
                )
                .is_ok()
        {
            tighten_log_files_in_dir(&self.dir);
        }
    }
}

impl std::io::Write for Mode0600Appender {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        let n = self.inner.write(buf)?;
        self.maybe_tighten();
        Ok(n)
    }

    fn flush(&mut self) -> std::io::Result<()> {
        self.inner.flush()
    }
}

/// v1.4.93 BUG-5318-001: 同 `futu_auth::audit::tighten_log_files_in_dir`.
fn tighten_log_files_in_dir(dir: &Path) {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let Ok(rd) = std::fs::read_dir(dir) else {
            return;
        };
        for entry in rd.flatten() {
            let p = entry.path();
            let name = match p.file_name().and_then(|n| n.to_str()) {
                Some(n) => n,
                None => continue,
            };
            if !name.starts_with("futu-audit.log") {
                continue;
            }
            if let Ok(meta) = std::fs::metadata(&p) {
                if !meta.is_file() {
                    continue;
                }
                let cur = meta.permissions().mode() & 0o777;
                if cur & 0o077 != 0 {
                    let _ = std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o600));
                }
            }
        }
    }
    #[cfg(not(unix))]
    {
        let _ = dir;
    }
}