//! The contract between the credential pipeline and the script runtime that runs item validators
//! and transforms. `cred::v8` implements it; the pipeline (`cred::inject`) and its tests use it.
//! It keeps the behavior of the earlier `jsrun::evaluate` runtime.

/// Requested limits. The runtime clamps them: time 1..1000 ms (default 100), heap 256 KiB..32 MiB
/// (default 8 MiB).
#[derive(Clone, Copy, Debug, Default)]
pub struct Limits {
    pub max_time_ms: Option<u64>,
    pub max_memory_bytes: Option<usize>,
}

/// Stable error categories, independent of the engine's exception wording.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ErrorKind {
    /// Time or heap limit exceeded.
    Limit,
    Syntax,
    /// The script threw or its Promise rejected.
    Throw,
    /// The result is not JSON-serializable.
    NonJson,
    Engine,
}

/// An evaluation failure. The message can contain script-provided text.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Error {
    pub kind: ErrorKind,
    pub message: String,
}

/// Evaluate an item's script. `source` is an ES module. `export` names the function to call
/// (`None` means `default`). The function gets the parsed `input` JSON as its one argument and may
/// return a Promise. The result is `JSON.stringify` of the settled value.
///
/// Each call runs in fresh state, with the limits applied to compile, run and serialization. The
/// script has `atob` and `btoa` only: no network, file system, timers, module loader, `Date` or
/// `Math.random`. Implementations must be callable from any thread.
pub trait Script: Send + Sync {
    fn evaluate(
        &self,
        source: &str,
        input: &str,
        export: Option<&str>,
        limits: Limits,
    ) -> Result<String, Error>;
}