massa_module_cache/
controller.rs

1use massa_hash::Hash;
2use massa_models::prehash::BuildHashMapper;
3use massa_sc_runtime::{Compiler, CondomLimits, RuntimeModule};
4use schnellru::{ByLength, LruMap};
5use tracing::debug;
6
7use crate::{
8    config::ModuleCacheConfig, error::CacheError, hd_cache::HDCache, lru_cache::LRUCache,
9    types::ModuleInfo,
10};
11
12/// `LruMap` specialization for `PreHashed` keys
13pub type PreHashLruMap<K, V> = LruMap<K, V, ByLength, BuildHashMapper<K>>;
14
15/// Cache controller of compiled runtime modules
16pub struct ModuleCache {
17    /// Cache config.
18    /// See `CacheConfig` documentation for more information.
19    cfg: ModuleCacheConfig,
20    /// RAM stored LRU cache.
21    /// See `LRUCache` documentation for more information.
22    lru_cache: LRUCache,
23    /// Disk stored cache.
24    /// See the `HDCache` documentation for more information.
25    hd_cache: HDCache,
26}
27
28impl ModuleCache {
29    /// Creates a new `ModuleCache`
30    pub fn new(cfg: ModuleCacheConfig) -> Self {
31        Self {
32            lru_cache: LRUCache::new(cfg.lru_cache_size),
33            hd_cache: HDCache::new(
34                cfg.hd_cache_path.clone(),
35                cfg.hd_cache_size,
36                cfg.snip_amount,
37            ),
38            cfg,
39        }
40    }
41
42    pub fn reset(&mut self) {
43        self.lru_cache.reset();
44        self.hd_cache.reset();
45    }
46
47    /// Internal function to compile and build `ModuleInfo`
48    fn compile_cached(
49        &mut self,
50        bytecode: &[u8],
51        hash: Hash,
52        condom_limits: CondomLimits,
53    ) -> ModuleInfo {
54        match RuntimeModule::new(
55            bytecode,
56            self.cfg.gas_costs.clone(),
57            Compiler::CL,
58            condom_limits,
59        ) {
60            Ok(module) => {
61                debug!("compilation of module {} succeeded", hash);
62                ModuleInfo::Module(module)
63            }
64            Err(e) => {
65                let err_msg = format!("compilation of module {} failed: {}", hash, e);
66                debug!(err_msg);
67                ModuleInfo::Invalid(err_msg)
68            }
69        }
70    }
71
72    /// Save a new or an already existing module in the cache
73    pub fn save_module(&mut self, bytecode: &[u8], condom_limits: CondomLimits) {
74        let hash = Hash::compute_from(bytecode);
75        if let Some(lru_module_info) = self.lru_cache.get(hash) {
76            debug!("save_module: {} present in lru", hash);
77            self.hd_cache.insert(hash, lru_module_info);
78        } else if let Some(hd_module_info) =
79            self.hd_cache
80                .get(hash, self.cfg.gas_costs.clone(), condom_limits.clone())
81        {
82            debug!("save_module: {} missing in lru but present in hd", hash);
83            self.lru_cache.insert(hash, hd_module_info);
84        } else {
85            debug!("save_module: {} missing", hash);
86            let module_info = self.compile_cached(bytecode, hash, condom_limits);
87            self.hd_cache.insert(hash, module_info.clone());
88            self.lru_cache.insert(hash, module_info);
89        }
90    }
91
92    /// Set the initialization cost of a cached module
93    pub fn set_init_cost(&mut self, bytecode: &[u8], init_cost: u64) {
94        let hash = Hash::compute_from(bytecode);
95        self.lru_cache.set_init_cost(hash, init_cost);
96        self.hd_cache.set_init_cost(hash, init_cost);
97    }
98
99    /// Set a cached module as invalid
100    pub fn set_invalid(&mut self, bytecode: &[u8], err_msg: String) {
101        let hash = Hash::compute_from(bytecode);
102        self.lru_cache.set_invalid(hash, err_msg.clone());
103        self.hd_cache.set_invalid(hash, err_msg);
104    }
105
106    /// Load a cached module for execution
107    ///
108    /// Returns the module information, it can be:
109    /// * `ModuleInfo::Invalid` if the module is invalid
110    /// * `ModuleInfo::Module` if the module is valid and has no delta
111    /// * `ModuleInfo::ModuleAndDelta` if the module is valid and has a delta
112    fn load_module_info(&mut self, bytecode: &[u8], condom_limits: CondomLimits) -> ModuleInfo {
113        if let Some(invalid) = self.check_module_length(bytecode.len()) {
114            return invalid;
115        }
116        let hash = Hash::compute_from(bytecode);
117        self.load_module_info_with_hash(bytecode, hash, condom_limits)
118    }
119
120    /// Length checks of `load_module_info`, done before hashing the bytecode
121    fn check_module_length(&self, bytecode_len: usize) -> Option<ModuleInfo> {
122        if bytecode_len == 0 {
123            let error_msg = "load_module: bytecode is absent".to_string();
124            debug!(error_msg);
125            return Some(ModuleInfo::Invalid(error_msg));
126        }
127        if bytecode_len > self.cfg.max_module_length as usize {
128            let error_msg = format!(
129                "load_module: bytecode length {} exceeds max module length {}",
130                bytecode_len, self.cfg.max_module_length
131            );
132            debug!(error_msg);
133            return Some(ModuleInfo::Invalid(error_msg));
134        }
135        None
136    }
137
138    /// Looks up the module info of a bytecode whose hash is already known in the
139    /// LRU then the HD cache.
140    fn get_cached_module_info(
141        &mut self,
142        hash: Hash,
143        condom_limits: CondomLimits,
144    ) -> Option<ModuleInfo> {
145        if let Some(lru_module_info) = self.lru_cache.get(hash) {
146            debug!("load_module: {} present in lru", hash);
147            Some(lru_module_info)
148        } else if let Some(hd_module_info) =
149            self.hd_cache
150                .get(hash, self.cfg.gas_costs.clone(), condom_limits)
151        {
152            debug!("load_module: {} missing in lru but present in hd", hash);
153            self.lru_cache.insert(hash, hd_module_info.clone());
154            Some(hd_module_info)
155        } else {
156            None
157        }
158    }
159
160    /// `load_module_info` after the length checks, with `hash == Hash::compute_from(bytecode)`
161    fn load_module_info_with_hash(
162        &mut self,
163        bytecode: &[u8],
164        hash: Hash,
165        condom_limits: CondomLimits,
166    ) -> ModuleInfo {
167        if let Some(module_info) = self.get_cached_module_info(hash, condom_limits.clone()) {
168            module_info
169        } else {
170            debug!("load_module: {} missing", hash);
171            let module_info = self.compile_cached(bytecode, hash, condom_limits);
172            self.hd_cache.insert(hash, module_info.clone());
173            self.lru_cache.insert(hash, module_info.clone());
174            module_info
175        }
176    }
177
178    /// Load a cached module for execution and check its validity for execution.
179    /// Also checks that the provided execution gas is enough to pay for the instance creation cost.
180    ///
181    /// Returns the module after loading.
182    pub fn load_module(
183        &mut self,
184        bytecode: &[u8],
185        execution_gas: u64,
186        condom_limits: CondomLimits,
187    ) -> Result<RuntimeModule, CacheError> {
188        self.check_execution_gas(execution_gas)?;
189        let module_info = self.load_module_info(bytecode, condom_limits);
190        Self::module_from_info(module_info, execution_gas)
191    }
192
193    /// Same as `load_module`, when the caller already knows `hash == Hash::compute_from(bytecode)`.
194    pub fn load_module_with_hash(
195        &mut self,
196        bytecode: &[u8],
197        hash: Hash,
198        execution_gas: u64,
199        condom_limits: CondomLimits,
200    ) -> Result<RuntimeModule, CacheError> {
201        debug_assert_eq!(hash, Hash::compute_from(bytecode));
202        self.check_execution_gas(execution_gas)?;
203        let module_info = match self.check_module_length(bytecode.len()) {
204            Some(invalid) => invalid,
205            None => self.load_module_info_with_hash(bytecode, hash, condom_limits),
206        };
207        Self::module_from_info(module_info, execution_gas)
208    }
209
210    /// Same as `load_module` for a bytecode known only by its hash and length,
211    /// without access to the bytecode itself.
212    ///
213    /// Returns `None` when the result cannot be decided without the bytecode
214    /// (module in neither the LRU nor the HD cache, or invalid length): the
215    /// caller must then fall back to `load_module_with_hash`. Otherwise, returns
216    /// exactly what `load_module` would for that bytecode.
217    pub fn load_cached_module_by_hash(
218        &mut self,
219        hash: Hash,
220        bytecode_len: usize,
221        execution_gas: u64,
222        condom_limits: CondomLimits,
223    ) -> Option<Result<RuntimeModule, CacheError>> {
224        if let Err(err) = self.check_execution_gas(execution_gas) {
225            return Some(Err(err));
226        }
227        if self.check_module_length(bytecode_len).is_some() {
228            return None;
229        }
230        let module_info = self.get_cached_module_info(hash, condom_limits)?;
231        Some(Self::module_from_info(module_info, execution_gas))
232    }
233
234    /// Gas check done by `load_module` before loading anything
235    fn check_execution_gas(&self, execution_gas: u64) -> Result<(), CacheError> {
236        // Do not actually debit the instance creation cost from the provided gas
237        // This is only supposed to be a check
238        execution_gas
239            .checked_sub(self.cfg.gas_costs.max_instance_cost)
240            .ok_or(CacheError::LoadError(format!(
241                "Provided gas {} is lower than the base instance creation gas cost {}",
242                execution_gas, self.cfg.gas_costs.max_instance_cost
243            )))?;
244        // TODO: interesting but unimportant optim
245        // remove max_instance_cost hard check if module is cached and has a delta
246        Ok(())
247    }
248
249    /// Turns the loaded module info into a module, checking the instance creation cost
250    fn module_from_info(
251        module_info: ModuleInfo,
252        execution_gas: u64,
253    ) -> Result<RuntimeModule, CacheError> {
254        let module = match module_info {
255            ModuleInfo::Invalid(err) => {
256                let err_msg = format!("invalid module: {}", err);
257                return Err(CacheError::LoadError(err_msg));
258            }
259            ModuleInfo::Module(module) => module,
260            ModuleInfo::ModuleAndDelta((module, delta)) => {
261                if delta > execution_gas {
262                    return Err(CacheError::LoadError(format!(
263                        "Provided gas {} is below the gas cost of instance creation ({})",
264                        execution_gas, delta
265                    )));
266                } else {
267                    module
268                }
269            }
270        };
271        Ok(module)
272    }
273
274    /// Load a temporary module from arbitrary bytecode.
275    /// Also checks that the provided execution gas is enough to pay for the instance creation cost.
276    ///
277    /// Returns the module after compilation.
278    pub fn load_tmp_module(
279        &self,
280        bytecode: &[u8],
281        limit: u64,
282        condom_limits: CondomLimits,
283    ) -> Result<RuntimeModule, CacheError> {
284        debug!("load_tmp_module");
285        if bytecode.is_empty() {
286            let error_msg = "load_tmp_module: bytecode is absent".to_string();
287            debug!(error_msg);
288            return Err(CacheError::LoadError(error_msg));
289        }
290        if bytecode.len() > self.cfg.max_module_length as usize {
291            let error_msg = format!(
292                "load_tmp_module: bytecode length {} exceeds max module length {}",
293                bytecode.len(),
294                self.cfg.max_module_length
295            );
296            debug!(error_msg);
297            return Err(CacheError::LoadError(error_msg));
298        }
299        // Do not actually debit the instance creation cost from the provided gas
300        // This is only supposed to be a check
301        limit
302            .checked_sub(self.cfg.gas_costs.max_instance_cost)
303            .ok_or(CacheError::LoadError(format!(
304                "Provided gas {} is lower than the base instance creation gas cost {}",
305                limit, self.cfg.gas_costs.max_instance_cost
306            )))?;
307        let module = RuntimeModule::new(
308            bytecode,
309            self.cfg.gas_costs.clone(),
310            Compiler::SP,
311            condom_limits,
312        )?;
313        Ok(module)
314    }
315
316    /// Returns the memory usage of the LRU cache
317    pub fn get_module_lru_cache_memory_usage(&self) -> usize {
318        self.lru_cache.cache.memory_usage()
319    }
320
321    /// Returns the number of modules currently held in the in-RAM LRU cache
322    pub fn lru_cache_len(&self) -> usize {
323        self.lru_cache.cache.len()
324    }
325}
326
327#[cfg(test)]
328mod tests {
329    use super::*;
330    use massa_sc_runtime::{CondomLimits, GasCosts};
331    use serial_test::serial;
332    use std::sync::atomic::Ordering;
333    use tempfile::TempDir;
334
335    /// Minimal valid wasm module (an `add_one` function).
336    const TEST_BYTECODE: &[u8] = &[
337        0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x06, 0x01, 0x60, 0x01, 0x7f, 0x01,
338        0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x0b, 0x01, 0x07, 0x61, 0x64, 0x64, 0x5f, 0x6f, 0x6e,
339        0x65, 0x00, 0x00, 0x0a, 0x09, 0x01, 0x07, 0x00, 0x20, 0x00, 0x41, 0x01, 0x6a, 0x0b, 0x00,
340        0x1a, 0x04, 0x6e, 0x61, 0x6d, 0x65, 0x01, 0x0a, 0x01, 0x00, 0x07, 0x61, 0x64, 0x64, 0x5f,
341        0x6f, 0x6e, 0x65, 0x02, 0x07, 0x01, 0x00, 0x01, 0x00, 0x02, 0x70, 0x30,
342    ];
343
344    fn setup(max_module_length: u64) -> (ModuleCache, TempDir) {
345        let cache_dir = TempDir::new().unwrap();
346        let cache = ModuleCache::new(ModuleCacheConfig {
347            hd_cache_path: cache_dir.path().to_path_buf(),
348            gas_costs: GasCosts::default(),
349            lru_cache_size: 10,
350            hd_cache_size: 10,
351            snip_amount: 1,
352            max_module_length,
353            condom_limits: CondomLimits::default(),
354        });
355        (cache, cache_dir)
356    }
357
358    /// When a module is already resident in the LRU cache, `save_module` must not
359    /// perform a redundant RocksDB read/deserialize via the HD cache.
360    #[test]
361    #[serial]
362    fn test_save_module_skips_hd_read_when_in_lru() {
363        let (mut cache, _cache_dir) = setup(1_000_000);
364        let condom_limits = CondomLimits::default();
365
366        // First save: nothing is cached yet, so the HD cache is probed once (a miss)
367        // before compiling and inserting into both caches.
368        cache.save_module(TEST_BYTECODE, condom_limits.clone());
369        assert_eq!(
370            cache.hd_cache.read_count.load(Ordering::Relaxed),
371            1,
372            "first save_module should probe the HD cache exactly once"
373        );
374
375        // Second save: the module is already present in the LRU cache, so we must
376        // short-circuit and never touch the HD cache for a read.
377        cache.save_module(TEST_BYTECODE, condom_limits);
378        assert_eq!(
379            cache.hd_cache.read_count.load(Ordering::Relaxed),
380            1,
381            "save_module must not read the HD cache when the module is in the LRU cache"
382        );
383    }
384
385    /// `load_cached_module_by_hash` must return what `load_module` returns, and
386    /// `None` whenever that cannot be decided without the bytecode.
387    #[test]
388    #[serial]
389    fn test_load_cached_module_by_hash_matches_load_module() {
390        let (mut cache, _cache_dir) = setup(1_000_000);
391        let condom_limits = CondomLimits::default();
392        let hash = Hash::compute_from(TEST_BYTECODE);
393        let len = TEST_BYTECODE.len();
394
395        // not cached yet: the caller must fall back to the bytecode path
396        assert!(cache
397            .load_cached_module_by_hash(hash, len, u64::MAX, condom_limits.clone())
398            .is_none());
399
400        cache
401            .load_module_with_hash(TEST_BYTECODE, hash, u64::MAX, condom_limits.clone())
402            .expect("valid module");
403        assert!(matches!(
404            cache.load_cached_module_by_hash(hash, len, u64::MAX, condom_limits.clone()),
405            Some(Ok(_))
406        ));
407
408        // not enough gas: same error as load_module
409        let low_gas = cache.cfg.gas_costs.max_instance_cost - 1;
410        let expected = cache
411            .load_module(TEST_BYTECODE, low_gas, condom_limits.clone())
412            .err()
413            .expect("gas check must fail")
414            .to_string();
415        let got = cache
416            .load_cached_module_by_hash(hash, len, low_gas, condom_limits.clone())
417            .expect("gas check needs no bytecode")
418            .err()
419            .expect("gas check must fail")
420            .to_string();
421        assert_eq!(got, expected);
422
423        // invalid lengths are left to the bytecode path, which reports them
424        assert!(cache
425            .load_cached_module_by_hash(hash, 0, u64::MAX, condom_limits.clone())
426            .is_none());
427        assert!(cache
428            .load_cached_module_by_hash(hash, 1_000_001, u64::MAX, condom_limits.clone())
429            .is_none());
430
431        // a module marked invalid is reported as invalid, as by load_module
432        cache.set_invalid(TEST_BYTECODE, "test error".to_string());
433        let expected = cache
434            .load_module(TEST_BYTECODE, u64::MAX, condom_limits.clone())
435            .err()
436            .expect("invalid module")
437            .to_string();
438        let got = cache
439            .load_cached_module_by_hash(hash, len, u64::MAX, condom_limits)
440            .expect("invalid module is cached")
441            .err()
442            .expect("invalid module")
443            .to_string();
444        assert_eq!(got, expected);
445    }
446
447    #[test]
448    fn test_load_tmp_module_rejects_empty_bytecode() {
449        let (cache, _cache_dir) = setup(4);
450
451        let result = cache.load_tmp_module(&[], u64::MAX, CondomLimits::default());
452
453        assert!(matches!(
454            result,
455            Err(CacheError::LoadError(error)) if error == "load_tmp_module: bytecode is absent"
456        ));
457    }
458
459    #[test]
460    fn test_load_tmp_module_rejects_oversized_bytecode() {
461        let (cache, _cache_dir) = setup(4);
462
463        // Invalid Wasm confirms the size check runs before RuntimeModule compilation.
464        let result = cache.load_tmp_module(&[0; 5], u64::MAX, CondomLimits::default());
465
466        assert!(matches!(
467            result,
468            Err(CacheError::LoadError(error))
469                if error == "load_tmp_module: bytecode length 5 exceeds max module length 4"
470        ));
471    }
472}