canic_host/canister_protocol/

mod.rs

//! Module: canister_protocol
//!
//! Responsibility: invoke typed Canic Candid methods through ICP-selected transports.
//! Does not own: domain sequencing, endpoint authorization, or management-Canister effects.
//! Boundary: domain workflows supply exact Canister, method, and arguments through explicit
//! query or update operations.

pub mod contract;
pub mod inspection;

use crate::{
    icp::{
        IcpCli, IcpCommandError, IcpJsonResponseError, cleanup_candid_argument_file,
        decode_json_result_response, write_candid_argument_file,
    },
    protocol_binding::ResolvedProtocolBinding,
};
use candid::{CandidType, Principal};
use canic_contracts::diagnostics::RegisteredDiagnosticCode;
use serde::de::DeserializeOwned;
use std::io;
use thiserror::Error as ThisError;

const ICP_JSON_OUTPUT: &str = "json";

#[derive(Clone, Copy)]
enum ProtocolCallMode {
    Query,
    Update,
}

#[derive(Debug, ThisError)]
pub enum CanisterProtocolError {
    #[error("read-only query {method} on Canister {canister} failed: {source}")]
    ReadOnlyQuery {
        canister: Principal,
        method: &'static str,
        #[source]
        source: crate::icp::IcpQueryError,
    },

    #[error("invalid bound inspection contract for Root {caller}: {detail}")]
    InspectionContract { caller: Principal, detail: String },

    #[error("Root {} inspection preflight for {} observed native={} cycles, liquid={} cycles, required outbound reserve={} cycles. Inspection was not attempted. Review Root funding or freezing reserve and retry with a fresh observation.", .0.caller, .0.canister_id, .0.native_cycles, .0.available_liquid_cycles, .0.required_liquid_cycles)]
    InspectionPreflightReserve(
        Box<canic_contracts::dto::canister::CanisterInspectionReserveResponse>,
    ),

    #[error("{}: Root {} cannot inspect {}: native={} cycles, liquid={} cycles, required outbound reserve={} cycles. Review Root funding or freezing reserve before retrying.", canic_contracts::diagnostics::codes::PLATFORM_INSUFFICIENT_LIQUID_CYCLES, .0.caller, .0.canister_id, .0.native_cycles, .0.available_liquid_cycles, .0.required_liquid_cycles)]
    InspectionReserve(Box<canic_contracts::dto::canister::CanisterInspectionReserveResponse>),

    #[error("Root {caller} returned invalid reserve evidence for inspection of {target}")]
    InvalidInspectionReserve {
        caller: Principal,
        target: Principal,
    },

    #[error("failed to encode Candid arguments for {method} on Canister {canister}: {source}")]
    ArgumentEncoding {
        canister: Principal,
        method: &'static str,
        #[source]
        source: candid::Error,
    },

    #[error(
        "failed to manage binary Candid arguments for {method} on Canister {canister}: {source}"
    )]
    ArgumentFile {
        canister: Principal,
        method: &'static str,
        #[source]
        source: io::Error,
    },

    #[error("failed to invoke {method} on Canister {canister}: {source}")]
    Invocation {
        canister: Principal,
        method: &'static str,
        #[source]
        source: IcpCommandError,
    },

    #[error("invalid {method} response from Canister {canister}: {source}")]
    Response {
        canister: Principal,
        method: &'static str,
        #[source]
        source: IcpJsonResponseError,
    },
}

impl CanisterProtocolError {
    pub(crate) fn inspection_reserve(
        caller: Principal,
        target: Principal,
        evidence: canic_contracts::dto::canister::CanisterInspectionReserveResponse,
    ) -> Self {
        if evidence.caller != caller
            || evidence.canister_id != target
            || evidence.available_liquid_cycles >= evidence.required_liquid_cycles
            || evidence.available_liquid_cycles > evidence.native_cycles
        {
            return Self::InvalidInspectionReserve { caller, target };
        }
        Self::InspectionReserve(Box::new(evidence))
    }

    pub(crate) fn is_rejected_with(&self, code: RegisteredDiagnosticCode) -> bool {
        if matches!(self, Self::InspectionReserve(_)) {
            return code
                == canic_contracts::diagnostics::codes::PLATFORM_INSUFFICIENT_LIQUID_CYCLES;
        }
        matches!(
            self,
            Self::Response {
                source: IcpJsonResponseError::Rejected(error),
                ..
            } if error.code() == code.raw_code()
        )
    }
}

pub fn call_with_arg<I, O>(
    icp: &IcpCli,
    binding: &ResolvedProtocolBinding,
    canister: Principal,
    method: &'static str,
    input: &I,
) -> Result<O, CanisterProtocolError>
where
    I: CandidType,
    O: CandidType + DeserializeOwned,
{
    invoke_with_candid(
        icp,
        &binding.candid_path,
        canister,
        method,
        input,
        ProtocolCallMode::Update,
    )
}

pub fn query_with_arg<I, O>(
    icp: &IcpCli,
    binding: &ResolvedProtocolBinding,
    canister: Principal,
    method: &'static str,
    input: &I,
) -> Result<O, CanisterProtocolError>
where
    I: CandidType,
    O: CandidType + DeserializeOwned,
{
    invoke_with_candid(
        icp,
        &binding.candid_path,
        canister,
        method,
        input,
        ProtocolCallMode::Query,
    )
}

/// Invoke one typed current-generation call after its exact Candid bytes were
/// independently bound into the reviewed Fleet action.
pub fn call_with_candid<I, O>(
    icp: &IcpCli,
    candid_path: &std::path::Path,
    canister: Principal,
    method: &'static str,
    input: &I,
) -> Result<O, CanisterProtocolError>
where
    I: CandidType,
    O: CandidType + DeserializeOwned,
{
    invoke_with_candid(
        icp,
        candid_path,
        canister,
        method,
        input,
        ProtocolCallMode::Update,
    )
}

/// Query one typed current-generation status after its exact Candid bytes were
/// independently bound into the reviewed Fleet action.
pub fn query_with_candid<I, O>(
    icp: &IcpCli,
    candid_path: &std::path::Path,
    canister: Principal,
    method: &'static str,
    input: &I,
) -> Result<O, CanisterProtocolError>
where
    I: CandidType,
    O: CandidType + DeserializeOwned,
{
    invoke_with_candid(
        icp,
        candid_path,
        canister,
        method,
        input,
        ProtocolCallMode::Query,
    )
}

/// Read a compiled Canic status contract while preserving typed transport failures.
pub fn query_authenticated<I: CandidType, O: CandidType + DeserializeOwned>(
    icp: &IcpCli,
    canister: Principal,
    method: &'static str,
    input: &I,
) -> Result<O, CanisterProtocolError> {
    let response: Result<O, canic_contracts::dto::error::Error> = icp
        .query_candid_readonly(canister, method, input)
        .map_err(|source| CanisterProtocolError::ReadOnlyQuery {
            canister,
            method,
            source,
        })?;
    response.map_err(|error| CanisterProtocolError::Response {
        canister,
        method,
        source: IcpJsonResponseError::Rejected(error),
    })
}

fn invoke_with_candid<I, O>(
    icp: &IcpCli,
    candid_path: &std::path::Path,
    canister: Principal,
    method: &'static str,
    input: &I,
    mode: ProtocolCallMode,
) -> Result<O, CanisterProtocolError>
where
    I: CandidType,
    O: CandidType + DeserializeOwned,
{
    let output = invoke_output(icp, Some(candid_path), canister, method, input, mode)?;
    decode_response(canister, method, &output)
}

fn invoke_output<I>(
    icp: &IcpCli,
    candid_path: Option<&std::path::Path>,
    canister: Principal,
    method: &'static str,
    input: &I,
    mode: ProtocolCallMode,
) -> Result<String, CanisterProtocolError>
where
    I: CandidType,
{
    let bytes =
        candid::encode_one(input).map_err(|source| CanisterProtocolError::ArgumentEncoding {
            canister,
            method,
            source,
        })?;
    let args_path = write_candid_argument_file(&bytes).map_err(|source| {
        CanisterProtocolError::ArgumentFile {
            canister,
            method,
            source,
        }
    })?;
    let canister_text = canister.to_text();
    let output = match mode {
        ProtocolCallMode::Query => icp.canister_query_binary_args_output_with_candid(
            &canister_text,
            method,
            &args_path,
            Some(ICP_JSON_OUTPUT),
            candid_path,
        ),
        ProtocolCallMode::Update => icp.canister_call_binary_args_output_with_candid(
            &canister_text,
            method,
            &args_path,
            Some(ICP_JSON_OUTPUT),
            candid_path,
        ),
    };
    cleanup_candid_argument_file(&args_path);
    let output = output.map_err(|source| CanisterProtocolError::Invocation {
        canister,
        method,
        source,
    })?;
    Ok(output)
}

fn decode_response<O>(
    canister: Principal,
    method: &'static str,
    output: &str,
) -> Result<O, CanisterProtocolError>
where
    O: CandidType + DeserializeOwned,
{
    decode_json_result_response(output).map_err(|source| CanisterProtocolError::Response {
        canister,
        method,
        source,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde::Deserialize;
    use std::fs;

    #[derive(CandidType, Debug, Deserialize, Eq, PartialEq)]
    struct EmptyVectorArgument {
        values: Vec<u64>,
    }

    #[cfg(unix)]
    #[test]
    fn cleanup_failure_preserves_typed_update_and_query_outcomes() {
        use canic_core::cdk::utils::hash::hex_bytes;
        use std::{os::unix::fs::PermissionsExt, path::PathBuf};

        let root = crate::test_support::temp_dir("canister-protocol-cleanup");
        fs::create_dir_all(&root).unwrap();
        let executable = root.join("icp");
        fs::write(
            &executable,
            crate::test_support::tool_script(
                r#"#!/bin/sh
if [ "$1" = --version ]; then echo 'icp @ICP_VERSION@'; exit 0; fi
while [ "$#" -gt 0 ]; do
  case "$1" in --args-file) shift; argument=$1 ;; esac
  shift
done
printf '%s\n' "$argument" > argument-path
rm "$argument"; mkdir "$argument"
cat response
exit "$(cat exit-code)"
"#,
            ),
        )
        .unwrap();
        fs::set_permissions(&executable, fs::Permissions::from_mode(0o700)).unwrap();
        let icp = IcpCli::new(executable.to_str().unwrap(), None).with_cwd(&root);
        let reply: Result<u64, canic_contracts::dto::error::Error> = Ok(42);
        let response = serde_json::json!({
            "response_bytes": hex_bytes(candid::encode_one(reply).unwrap()),
        });
        for mode in [ProtocolCallMode::Update, ProtocolCallMode::Query] {
            for outcome in 0..3 {
                fs::write(root.join("exit-code"), if outcome == 1 { "1" } else { "0" }).unwrap();
                fs::write(
                    root.join("response"),
                    if outcome == 2 {
                        "{}".to_string()
                    } else {
                        response.to_string()
                    },
                )
                .unwrap();
                let result = invoke_with_candid::<_, u64>(
                    &icp,
                    &root.join("probe.did"),
                    Principal::from_slice(&[1]),
                    "probe",
                    &(),
                    mode,
                );
                match outcome {
                    0 => assert_eq!(result.unwrap(), 42),
                    1 => assert!(matches!(
                        result,
                        Err(CanisterProtocolError::Invocation { .. })
                    )),
                    _ => assert!(matches!(
                        result,
                        Err(CanisterProtocolError::Response { .. })
                    )),
                }
                let argument_path = PathBuf::from(
                    fs::read_to_string(root.join("argument-path"))
                        .unwrap()
                        .trim(),
                );
                assert!(argument_path.is_dir());
                fs::remove_dir(argument_path).unwrap();
            }
        }
        fs::remove_dir_all(root).unwrap();
    }

    #[test]
    fn inspection_reserve_requires_exact_authority_and_retains_numeric_cause() {
        use canic_contracts::{
            diagnostics::codes, dto::canister::CanisterInspectionReserveResponse,
        };
        let root = Principal::from_slice(&[1]);
        let target = Principal::from_slice(&[2]);
        let evidence = CanisterInspectionReserveResponse {
            caller: root,
            canister_id: target,
            native_cycles: 1000,
            available_liquid_cycles: 50,
            required_liquid_cycles: 100,
        };
        let error = CanisterProtocolError::inspection_reserve(root, target, evidence.clone());
        assert!(error.is_rejected_with(codes::PLATFORM_INSUFFICIENT_LIQUID_CYCLES));
        assert!(!error.is_rejected_with(codes::PLATFORM_UNAVAILABLE));
        let CanisterProtocolError::InspectionReserve(actual) = &error else {
            panic!("reserve evidence");
        };
        assert_eq!(**actual, evidence);
        assert!(error.to_string().contains(
            "native=1000 cycles, liquid=50 cycles, required outbound reserve=100 cycles"
        ));
        for invalid in [
            CanisterInspectionReserveResponse {
                caller: target,
                ..evidence.clone()
            },
            CanisterInspectionReserveResponse {
                canister_id: root,
                ..evidence.clone()
            },
            CanisterInspectionReserveResponse {
                available_liquid_cycles: 100,
                ..evidence.clone()
            },
            CanisterInspectionReserveResponse {
                native_cycles: 49,
                ..evidence
            },
        ] {
            let error = CanisterProtocolError::inspection_reserve(root, target, invalid);
            assert!(matches!(
                error,
                CanisterProtocolError::InvalidInspectionReserve { .. }
            ));
            assert!(!error.is_rejected_with(codes::PLATFORM_INSUFFICIENT_LIQUID_CYCLES));
        }
    }

    #[test]
    fn typed_arguments_are_written_to_private_binary_files() {
        let argument = EmptyVectorArgument { values: Vec::new() };
        let path =
            write_candid_argument_file(&candid::encode_one(&argument).expect("encode argument"))
                .expect("write argument file");

        let decoded: EmptyVectorArgument =
            candid::decode_one(&fs::read(&path).expect("read argument file"))
                .expect("decode argument");
        assert_eq!(decoded, argument);
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;

            assert_eq!(
                fs::metadata(&path)
                    .expect("argument metadata")
                    .permissions()
                    .mode()
                    & 0o777,
                0o600
            );
        }
        fs::remove_file(path).expect("remove argument file");
    }
}