zccache_protocol/

messages.rs

//! Protocol message definitions.

use serde::{Deserialize, Serialize};
use std::sync::Arc;
use zccache_core::NormalizedPath;

/// A request from client to daemon.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Request {
    /// Health check.
    Ping,
    /// Request daemon shutdown.
    Shutdown,
    /// Request daemon status/statistics.
    Status,
    /// Look up a cached artifact by cache key.
    Lookup {
        /// Hex-encoded cache key.
        cache_key: String,
    },
    /// Store a compilation artifact.
    Store {
        /// Hex-encoded cache key.
        cache_key: String,
        /// The artifact data to store.
        artifact: ArtifactData,
    },
    /// Start a new session with the daemon.
    SessionStart {
        /// Client process ID.
        client_pid: u32,
        /// Client working directory.
        working_dir: NormalizedPath,
        /// Optional path to a log file for this session.
        log_file: Option<NormalizedPath>,
        /// Whether to track per-session statistics.
        track_stats: bool,
        /// Path for per-session JSONL compile journal (must end in .jsonl).
        journal_path: Option<NormalizedPath>,
    },
    /// Compile a source file within an existing session.
    Compile {
        /// Session ID from a prior SessionStart (UUID string).
        session_id: String,
        /// Compiler arguments (e.g., ["-c", "hello.cpp", "-o", "hello.o"]).
        args: Vec<String>,
        /// Working directory for the compilation.
        cwd: NormalizedPath,
        /// Path to the compiler executable (required).
        compiler: NormalizedPath,
        /// Client environment variables to pass to the compiler process.
        /// If `None`, the daemon's own environment is inherited (backward compat).
        /// If `Some`, the compiler process uses exactly these env vars.
        env: Option<Vec<(String, String)>>,
    },
    /// End a session.
    SessionEnd {
        /// Session ID to end (UUID string).
        session_id: String,
    },
    /// Clear all caches (artifacts, metadata, dep graph).
    Clear,
    /// Single-roundtrip ephemeral compile: session start + compile + session end
    /// in one message. Used by the CLI in drop-in wrapper mode to avoid 3 IPC
    /// roundtrips per invocation.
    CompileEphemeral {
        /// Client process ID.
        client_pid: u32,
        /// Client working directory.
        working_dir: NormalizedPath,
        /// Path to the compiler executable.
        compiler: NormalizedPath,
        /// Compiler arguments (e.g., ["-c", "hello.cpp", "-o", "hello.o"]).
        args: Vec<String>,
        /// Working directory for the compilation.
        cwd: NormalizedPath,
        /// Client environment variables to pass to the compiler process.
        env: Option<Vec<(String, String)>>,
    },
    /// Single-roundtrip ephemeral link/archive: used for `zccache ar ...` or
    /// `zccache ld ...` in drop-in wrapper mode.
    LinkEphemeral {
        /// Client process ID.
        client_pid: u32,
        /// Path to the linker/archiver tool (ar, ld, lib.exe, link.exe, etc.).
        tool: NormalizedPath,
        /// Tool arguments (e.g., ["rcs", "libfoo.a", "a.o", "b.o"]).
        args: Vec<String>,
        /// Working directory for the link operation.
        cwd: NormalizedPath,
        /// Client environment variables.
        env: Option<Vec<(String, String)>>,
    },
    /// Query per-session statistics without ending the session.
    /// NOTE: Appended at end to preserve bincode variant indices.
    SessionStats {
        /// Session ID to query (UUID string).
        session_id: String,
    },
    /// Check if files have changed since last successful fingerprint.
    /// NOTE: Appended at end to preserve bincode variant indices.
    FingerprintCheck {
        /// Path to the cache file (e.g., .cache/lint.json).
        cache_file: NormalizedPath,
        /// Cache algorithm: "hash" or "two-layer".
        cache_type: String,
        /// Root directory to scan.
        root: NormalizedPath,
        /// File extensions to include (without dot, e.g., "rs", "cpp").
        /// Empty = all files. Conflicts with `include_globs`.
        extensions: Vec<String>,
        /// Glob patterns for files to include (e.g., "**/*.rs").
        /// Empty = use extensions filter.
        include_globs: Vec<String>,
        /// Patterns or directory names to exclude.
        exclude: Vec<String>,
    },
    /// Mark the previous fingerprint check as successful.
    FingerprintMarkSuccess {
        /// Path to the cache file.
        cache_file: NormalizedPath,
    },
    /// Mark the previous fingerprint check as failed.
    FingerprintMarkFailure {
        /// Path to the cache file.
        cache_file: NormalizedPath,
    },
    /// Invalidate a fingerprint cache (delete all state).
    FingerprintInvalidate {
        /// Path to the cache file.
        cache_file: NormalizedPath,
    },
}

/// A response from daemon to client.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Response {
    /// Response to Ping.
    Pong,
    /// Shutdown acknowledged.
    ShuttingDown,
    /// Daemon status information.
    Status(DaemonStatus),
    /// Cache lookup result.
    LookupResult(LookupResult),
    /// Store result.
    StoreResult(StoreResult),
    /// Session successfully started.
    SessionStarted {
        /// Assigned session ID (UUID string).
        session_id: String,
        /// Path to the per-session JSONL journal file (if journal was requested).
        journal_path: Option<NormalizedPath>,
    },
    /// Result of a compilation request.
    CompileResult {
        /// Compiler exit code.
        exit_code: i32,
        /// Captured stdout (Arc-wrapped to avoid copies on cache hits).
        stdout: Arc<Vec<u8>>,
        /// Captured stderr (Arc-wrapped to avoid copies on cache hits).
        stderr: Arc<Vec<u8>>,
        /// Whether this was served from cache.
        cached: bool,
    },
    /// Session ended successfully.
    SessionEnded {
        /// Per-session stats, if the session opted in to tracking.
        stats: Option<SessionStats>,
    },
    /// Result of a link/archive request.
    LinkResult {
        /// Tool exit code.
        exit_code: i32,
        /// Captured stdout (Arc-wrapped to avoid copies on cache hits).
        stdout: Arc<Vec<u8>>,
        /// Captured stderr (Arc-wrapped to avoid copies on cache hits).
        stderr: Arc<Vec<u8>>,
        /// Whether this was served from cache.
        cached: bool,
        /// Non-determinism warning (if tool invocation uses non-deterministic flags).
        warning: Option<String>,
    },
    /// An error occurred processing the request.
    Error {
        /// Human-readable error message.
        message: String,
    },
    /// Cache cleared successfully.
    Cleared {
        /// Number of in-memory artifacts removed.
        artifacts_removed: u64,
        /// Number of metadata cache entries cleared.
        metadata_cleared: u64,
        /// Number of dep graph contexts cleared.
        dep_graph_contexts_cleared: u64,
        /// Bytes freed from on-disk artifact cache.
        on_disk_bytes_freed: u64,
    },
    /// Mid-session statistics snapshot.
    /// NOTE: Appended at end to preserve bincode variant indices.
    SessionStatsResult {
        /// Per-session stats, if the session exists and opted in to tracking.
        stats: Option<SessionStats>,
    },
    /// Result of a fingerprint check.
    /// NOTE: Appended at end to preserve bincode variant indices.
    FingerprintCheckResult {
        /// "skip" or "run".
        decision: String,
        /// Reason for run (e.g., "no cache file", "content changed").
        reason: Option<String>,
        /// Files that changed (if available).
        changed_files: Vec<String>,
    },
    /// Fingerprint mark/invalidate acknowledged.
    FingerprintAck,
}

/// Daemon status information.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DaemonStatus {
    /// Daemon version (e.g. "1.0.8"). Used by CLI to detect stale daemons.
    pub version: String,
    /// Number of artifacts in cache.
    pub artifact_count: u64,
    /// Total size of cached artifacts in bytes.
    pub cache_size_bytes: u64,
    /// Number of entries in the metadata cache.
    pub metadata_entries: u64,
    /// Daemon uptime in seconds.
    pub uptime_secs: u64,
    /// Total cache hits since startup.
    pub cache_hits: u64,
    /// Total cache misses since startup.
    pub cache_misses: u64,
    /// Total compile requests received.
    pub total_compilations: u64,
    /// Non-cacheable invocations (linking, preprocessing, etc.).
    pub non_cacheable: u64,
    /// Compilations that exited with non-zero status.
    pub compile_errors: u64,
    /// Estimated wall-clock time saved in milliseconds.
    pub time_saved_ms: u64,
    /// Total link/archive requests received.
    pub total_links: u64,
    /// Link cache hits.
    pub link_hits: u64,
    /// Link cache misses.
    pub link_misses: u64,
    /// Non-cacheable link invocations.
    pub link_non_cacheable: u64,
    /// Number of compilation contexts in the dependency graph.
    pub dep_graph_contexts: u64,
    /// Number of tracked files in the dependency graph.
    pub dep_graph_files: u64,
    /// Total sessions created since daemon start.
    pub sessions_total: u64,
    /// Currently active sessions.
    pub sessions_active: u64,
    /// Path to the cache directory.
    pub cache_dir: NormalizedPath,
    /// On-disk depgraph snapshot format version.
    pub dep_graph_version: u32,
    /// Size of the depgraph snapshot file on disk (0 = not persisted).
    pub dep_graph_disk_size: u64,
}

/// Result of a cache lookup.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum LookupResult {
    /// Cache hit.
    Hit {
        /// The cached artifact data.
        artifact: ArtifactData,
    },
    /// Cache miss.
    Miss,
}

/// Result of storing an artifact.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum StoreResult {
    /// Successfully stored.
    Stored,
    /// Already existed in cache.
    AlreadyExists,
}

/// Artifact data exchanged over the protocol.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactData {
    /// The output files (filename to contents).
    pub outputs: Vec<ArtifactOutput>,
    /// Captured stdout from the compiler.
    pub stdout: Arc<Vec<u8>>,
    /// Captured stderr from the compiler.
    pub stderr: Arc<Vec<u8>>,
    /// Compiler exit code.
    pub exit_code: i32,
}

/// Per-session statistics, returned when the session opted in to tracking.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SessionStats {
    /// Wall-clock duration of the session in milliseconds.
    pub duration_ms: u64,
    /// Total compile requests in this session.
    pub compilations: u64,
    /// Cache hits in this session.
    pub hits: u64,
    /// Cache misses (cold compiles) in this session.
    pub misses: u64,
    /// Non-cacheable invocations (linking, preprocessing, etc.).
    pub non_cacheable: u64,
    /// Compilations that exited with non-zero status.
    pub errors: u64,
    /// Estimated wall-clock time saved in milliseconds.
    pub time_saved_ms: u64,
    /// Distinct source files compiled.
    pub unique_sources: u64,
    /// Total artifact bytes served from cache.
    pub bytes_read: u64,
    /// Total artifact bytes stored into cache.
    pub bytes_written: u64,
}

/// A single output file from compilation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArtifactOutput {
    /// Relative filename (e.g., "foo.o").
    pub name: String,
    /// File contents (Arc-wrapped to avoid deep copies during caching).
    pub data: Arc<Vec<u8>>,
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Helper: roundtrip a value through bincode.
    fn roundtrip<T: Serialize + serde::de::DeserializeOwned + PartialEq + std::fmt::Debug>(
        val: &T,
    ) {
        let bytes = bincode::serialize(val).unwrap();
        let decoded: T = bincode::deserialize(&bytes).unwrap();
        assert_eq!(*val, decoded);
    }

    #[test]
    fn session_stats_roundtrip() {
        let stats = SessionStats {
            duration_ms: 12345,
            compilations: 100,
            hits: 80,
            misses: 15,
            non_cacheable: 5,
            errors: 2,
            time_saved_ms: 8000,
            unique_sources: 42,
            bytes_read: 1024 * 1024,
            bytes_written: 512 * 1024,
        };
        roundtrip(&stats);
    }

    #[test]
    fn session_stats_default_zeros() {
        let stats = SessionStats {
            duration_ms: 0,
            compilations: 0,
            hits: 0,
            misses: 0,
            non_cacheable: 0,
            errors: 0,
            time_saved_ms: 0,
            unique_sources: 0,
            bytes_read: 0,
            bytes_written: 0,
        };
        roundtrip(&stats);
    }

    #[test]
    fn daemon_status_expanded_roundtrip() {
        let status = DaemonStatus {
            version: env!("CARGO_PKG_VERSION").to_string(),
            artifact_count: 892,
            cache_size_bytes: 147_000_000,
            metadata_entries: 5430,
            uptime_secs: 8040,
            cache_hits: 1089,
            cache_misses: 143,
            total_compilations: 1247,
            non_cacheable: 15,
            compile_errors: 3,
            time_saved_ms: 750_000,
            total_links: 50,
            link_hits: 38,
            link_misses: 10,
            link_non_cacheable: 2,
            dep_graph_contexts: 892,
            dep_graph_files: 4201,
            sessions_total: 41,
            sessions_active: 3,
            cache_dir: "/home/user/.zccache".into(),
            dep_graph_version: 1,
            dep_graph_disk_size: 2_500_000,
        };
        roundtrip(&status);
    }

    #[test]
    fn session_start_with_track_stats_roundtrip() {
        let req = Request::SessionStart {
            client_pid: 1234,
            working_dir: "/home/user/project".into(),
            log_file: None,
            track_stats: true,
            journal_path: None,
        };
        roundtrip(&req);

        let req_no_stats = Request::SessionStart {
            client_pid: 1234,
            working_dir: "/home/user/project".into(),
            log_file: None,
            track_stats: false,
            journal_path: None,
        };
        roundtrip(&req_no_stats);
    }

    #[test]
    fn session_start_with_journal_path_roundtrip() {
        let req = Request::SessionStart {
            client_pid: 5678,
            working_dir: "/home/user/project".into(),
            log_file: None,
            track_stats: false,
            journal_path: Some("/tmp/build.jsonl".into()),
        };
        roundtrip(&req);

        let req_no_journal = Request::SessionStart {
            client_pid: 5678,
            working_dir: "/home/user/project".into(),
            log_file: None,
            track_stats: false,
            journal_path: None,
        };
        roundtrip(&req_no_journal);
    }

    #[test]
    fn session_started_with_journal_path_roundtrip() {
        let resp = Response::SessionStarted {
            session_id: "550e8400-e29b-41d4-a716-446655440000".into(),
            journal_path: Some("/home/user/.zccache/logs/sessions/test.jsonl".into()),
        };
        roundtrip(&resp);

        let resp_no_journal = Response::SessionStarted {
            session_id: "550e8400-e29b-41d4-a716-446655440000".into(),
            journal_path: None,
        };
        roundtrip(&resp_no_journal);
    }

    #[test]
    fn session_ended_with_stats_roundtrip() {
        let stats = SessionStats {
            duration_ms: 34000,
            compilations: 32,
            hits: 28,
            misses: 3,
            non_cacheable: 1,
            errors: 0,
            time_saved_ms: 8200,
            unique_sources: 30,
            bytes_read: 2_000_000,
            bytes_written: 500_000,
        };
        let resp = Response::SessionEnded { stats: Some(stats) };
        roundtrip(&resp);

        let resp_no_stats = Response::SessionEnded { stats: None };
        roundtrip(&resp_no_stats);
    }

    #[test]
    fn clear_request_roundtrip() {
        roundtrip(&Request::Clear);
    }

    #[test]
    fn cleared_response_roundtrip() {
        roundtrip(&Response::Cleared {
            artifacts_removed: 42,
            metadata_cleared: 100,
            dep_graph_contexts_cleared: 25,
            on_disk_bytes_freed: 1024 * 1024,
        });
    }

    #[test]
    fn compile_ephemeral_roundtrip() {
        roundtrip(&Request::CompileEphemeral {
            client_pid: 9876,
            working_dir: "/home/user/project".into(),
            compiler: "/usr/bin/clang++".into(),
            args: vec!["-c".into(), "main.cpp".into(), "-o".into(), "main.o".into()],
            cwd: "/home/user/project/build".into(),
            env: Some(vec![("PATH".into(), "/usr/bin".into())]),
        });
        // Also test with env = None
        roundtrip(&Request::CompileEphemeral {
            client_pid: 1,
            working_dir: ".".into(),
            compiler: "gcc".into(),
            args: vec![],
            cwd: ".".into(),
            env: None,
        });
    }

    #[test]
    fn link_ephemeral_roundtrip() {
        roundtrip(&Request::LinkEphemeral {
            client_pid: 5555,
            tool: "/usr/bin/ar".into(),
            args: vec!["rcs".into(), "libfoo.a".into(), "a.o".into(), "b.o".into()],
            cwd: "/home/user/project/build".into(),
            env: Some(vec![("PATH".into(), "/usr/bin".into())]),
        });
        roundtrip(&Request::LinkEphemeral {
            client_pid: 1,
            tool: "lib.exe".into(),
            args: vec!["/OUT:foo.lib".into(), "a.obj".into()],
            cwd: ".".into(),
            env: None,
        });
    }

    #[test]
    fn link_result_roundtrip() {
        roundtrip(&Response::LinkResult {
            exit_code: 0,
            stdout: Arc::new(vec![]),
            stderr: Arc::new(vec![]),
            cached: true,
            warning: None,
        });
        roundtrip(&Response::LinkResult {
            exit_code: 0,
            stdout: Arc::new(vec![]),
            stderr: Arc::new(b"some warning".to_vec()),
            cached: false,
            warning: Some("non-deterministic: missing D flag".into()),
        });
    }

    #[test]
    fn session_stats_request_roundtrip() {
        roundtrip(&Request::SessionStats {
            session_id: "550e8400-e29b-41d4-a716-446655440000".into(),
        });
    }

    #[test]
    fn session_stats_result_roundtrip() {
        let stats = SessionStats {
            duration_ms: 5000,
            compilations: 10,
            hits: 7,
            misses: 2,
            non_cacheable: 1,
            errors: 0,
            time_saved_ms: 3000,
            unique_sources: 9,
            bytes_read: 50_000,
            bytes_written: 20_000,
        };
        roundtrip(&Response::SessionStatsResult { stats: Some(stats) });
        roundtrip(&Response::SessionStatsResult { stats: None });
    }

    #[test]
    fn existing_request_variants_still_work() {
        roundtrip(&Request::Ping);
        roundtrip(&Request::Shutdown);
        roundtrip(&Request::Status);
        roundtrip(&Request::SessionEnd {
            session_id: "550e8400-e29b-41d4-a716-446655440000".into(),
        });
        roundtrip(&Request::Compile {
            session_id: "550e8400-e29b-41d4-a716-446655440000".into(),
            args: vec!["-c".into(), "foo.c".into()],
            cwd: "/tmp".into(),
            compiler: "/usr/bin/gcc".into(),
            env: None,
        });
    }

    #[test]
    fn existing_response_variants_still_work() {
        roundtrip(&Response::Pong);
        roundtrip(&Response::ShuttingDown);
        roundtrip(&Response::CompileResult {
            exit_code: 0,
            stdout: Arc::new(vec![]),
            stderr: Arc::new(vec![]),
            cached: true,
        });
        roundtrip(&Response::Error {
            message: "test".into(),
        });
    }

    #[test]
    fn daemon_status_version_field_roundtrips() {
        let with_version = DaemonStatus {
            version: "1.2.3".to_string(),
            artifact_count: 0,
            cache_size_bytes: 0,
            metadata_entries: 0,
            uptime_secs: 0,
            cache_hits: 0,
            cache_misses: 0,
            total_compilations: 0,
            non_cacheable: 0,
            compile_errors: 0,
            time_saved_ms: 0,
            total_links: 0,
            link_hits: 0,
            link_misses: 0,
            link_non_cacheable: 0,
            dep_graph_contexts: 0,
            dep_graph_files: 0,
            sessions_total: 0,
            sessions_active: 0,
            cache_dir: "".into(),
            dep_graph_version: 0,
            dep_graph_disk_size: 0,
        };
        roundtrip(&with_version);
    }

    // Compile-time check: PROTOCOL_VERSION must be positive.
    const _: () = assert!(crate::PROTOCOL_VERSION > 0);
    // Compile-time check: PROTOCOL_VERSION == 5 after LinkEphemeral working_dir removal.
    const _FINGERPRINT_VERSION: () = assert!(crate::PROTOCOL_VERSION == 5);

    #[test]
    fn fingerprint_check_roundtrip() {
        roundtrip(&Request::FingerprintCheck {
            cache_file: "/tmp/lint.json".into(),
            cache_type: "two-layer".into(),
            root: "/home/user/project/src".into(),
            extensions: vec!["rs".into(), "toml".into()],
            include_globs: vec![],
            exclude: vec![".git".into(), "target".into()],
        });
        roundtrip(&Request::FingerprintCheck {
            cache_file: "cache.json".into(),
            cache_type: "hash".into(),
            root: ".".into(),
            extensions: vec![],
            include_globs: vec!["**/*.cpp".into(), "**/*.h".into()],
            exclude: vec![],
        });
    }

    #[test]
    fn fingerprint_mark_success_roundtrip() {
        roundtrip(&Request::FingerprintMarkSuccess {
            cache_file: "/tmp/lint.json".into(),
        });
    }

    #[test]
    fn fingerprint_mark_failure_roundtrip() {
        roundtrip(&Request::FingerprintMarkFailure {
            cache_file: "/tmp/lint.json".into(),
        });
    }

    #[test]
    fn fingerprint_invalidate_roundtrip() {
        roundtrip(&Request::FingerprintInvalidate {
            cache_file: "/tmp/lint.json".into(),
        });
    }

    #[test]
    fn fingerprint_check_result_roundtrip() {
        roundtrip(&Response::FingerprintCheckResult {
            decision: "skip".into(),
            reason: None,
            changed_files: vec![],
        });
        roundtrip(&Response::FingerprintCheckResult {
            decision: "run".into(),
            reason: Some("content changed".into()),
            changed_files: vec!["src/main.rs".into(), "src/lib.rs".into()],
        });
        roundtrip(&Response::FingerprintCheckResult {
            decision: "run".into(),
            reason: Some("no cache file".into()),
            changed_files: vec![],
        });
    }

    #[test]
    fn fingerprint_ack_roundtrip() {
        roundtrip(&Response::FingerprintAck);
    }

    #[test]
    fn artifact_clone_shares_payload_via_arc() {
        let artifact = ArtifactData {
            outputs: vec![ArtifactOutput {
                name: "test.o".into(),
                data: Arc::new(vec![1, 2, 3, 4]),
            }],
            stdout: Arc::new(vec![5, 6]),
            stderr: Arc::new(vec![7, 8]),
            exit_code: 0,
        };

        let cloned = artifact.clone();

        // Arc::clone bumps refcount — both point to the same allocation.
        assert!(Arc::ptr_eq(
            &artifact.outputs[0].data,
            &cloned.outputs[0].data
        ));
        assert!(Arc::ptr_eq(&artifact.stdout, &cloned.stdout));
        assert!(Arc::ptr_eq(&artifact.stderr, &cloned.stderr));
    }

    #[test]
    fn arc_vec_u8_roundtrip_matches_plain_vec() {
        // Prove Arc<Vec<u8>> serializes identically to Vec<u8>.
        let plain: Vec<u8> = vec![0xDE, 0xAD, 0xBE, 0xEF];
        let arc_wrapped: Arc<Vec<u8>> = Arc::new(plain.clone());

        let plain_bytes = bincode::serialize(&plain).unwrap();
        let arc_bytes = bincode::serialize(&arc_wrapped).unwrap();
        assert_eq!(
            plain_bytes, arc_bytes,
            "Arc<Vec<u8>> must serialize identically to Vec<u8>"
        );

        // Deserialize Arc bytes back as plain Vec and vice versa.
        let decoded_plain: Vec<u8> = bincode::deserialize(&arc_bytes).unwrap();
        let decoded_arc: Arc<Vec<u8>> = bincode::deserialize(&plain_bytes).unwrap();
        assert_eq!(decoded_plain, plain);
        assert_eq!(*decoded_arc, plain);
    }
}