artichoke_backend/load_path/
memory.rs

1use std::borrow::Cow;
2use std::collections::hash_map::Entry as HashEntry;
3use std::collections::{HashMap, HashSet};
4use std::fmt;
5use std::io;
6use std::path::{Path, PathBuf};
7
8use bstr::{BString, ByteSlice};
9use scolapasta_path::{ConvertBytesError, absolutize_relative_to, normalize_slashes};
10
11use super::{ExtensionHook, RUBY_LOAD_PATH};
12
13const CODE_DEFAULT_CONTENTS: &[u8] = b"# virtual source file";
14
15#[derive(Clone, Copy)]
16pub struct Extension {
17    hook: ExtensionHook,
18}
19
20impl From<ExtensionHook> for Extension {
21    fn from(hook: ExtensionHook) -> Self {
22        Self { hook }
23    }
24}
25
26impl Extension {
27    pub fn new(hook: ExtensionHook) -> Self {
28        Self { hook }
29    }
30}
31
32impl fmt::Debug for Extension {
33    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
34        f.debug_struct("Extension")
35            .field("hook", &"fn(&mut Artichoke) -> Result<(), Exception>")
36            .finish()
37    }
38}
39
40#[derive(Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
41pub struct Code {
42    content: Cow<'static, [u8]>,
43}
44
45impl fmt::Debug for Code {
46    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
47        f.debug_struct("Code")
48            .field("content", &self.content.as_bstr())
49            .finish()
50    }
51}
52
53impl Default for Code {
54    fn default() -> Self {
55        Self::new()
56    }
57}
58
59impl From<Code> for Cow<'static, [u8]> {
60    fn from(code: Code) -> Self {
61        code.into_inner()
62    }
63}
64
65impl From<Vec<u8>> for Code {
66    fn from(content: Vec<u8>) -> Self {
67        let content = content.into();
68        Self { content }
69    }
70}
71
72impl From<&'static [u8]> for Code {
73    fn from(content: &'static [u8]) -> Self {
74        let content = content.into();
75        Self { content }
76    }
77}
78
79impl From<Cow<'static, [u8]>> for Code {
80    fn from(content: Cow<'static, [u8]>) -> Self {
81        Self { content }
82    }
83}
84
85impl From<String> for Code {
86    fn from(content: String) -> Self {
87        let content = content.into_bytes().into();
88        Self { content }
89    }
90}
91
92impl From<&'static str> for Code {
93    fn from(content: &'static str) -> Self {
94        let content = content.as_bytes().into();
95        Self { content }
96    }
97}
98
99impl From<Cow<'static, str>> for Code {
100    fn from(content: Cow<'static, str>) -> Self {
101        match content {
102            Cow::Borrowed(content) => Self::from(content.as_bytes()),
103            Cow::Owned(content) => Self::from(content.into_bytes()),
104        }
105    }
106}
107
108impl Code {
109    #[must_use]
110    pub const fn new() -> Self {
111        let content = Cow::Borrowed(CODE_DEFAULT_CONTENTS);
112        Self { content }
113    }
114
115    #[must_use]
116    pub fn into_inner(self) -> Cow<'static, [u8]> {
117        self.content
118    }
119}
120
121#[derive(Default, Debug)]
122pub struct Entry {
123    code: Option<Code>,
124    extension: Option<Extension>,
125}
126
127impl From<Code> for Entry {
128    fn from(code: Code) -> Self {
129        let mut entry = Self::new();
130        entry.code = Some(code);
131        entry
132    }
133}
134
135impl From<Vec<u8>> for Entry {
136    fn from(content: Vec<u8>) -> Self {
137        let mut entry = Self::new();
138        entry.code = Some(content.into());
139        entry
140    }
141}
142
143impl From<&'static [u8]> for Entry {
144    fn from(content: &'static [u8]) -> Self {
145        let mut entry = Self::new();
146        entry.code = Some(content.into());
147        entry
148    }
149}
150
151impl From<Cow<'static, [u8]>> for Entry {
152    fn from(content: Cow<'static, [u8]>) -> Self {
153        let mut entry = Self::new();
154        entry.code = Some(content.into());
155        entry
156    }
157}
158
159impl From<String> for Entry {
160    fn from(content: String) -> Self {
161        let mut entry = Self::new();
162        entry.code = Some(content.into());
163        entry
164    }
165}
166
167impl From<&'static str> for Entry {
168    fn from(content: &'static str) -> Self {
169        let mut entry = Self::new();
170        entry.code = Some(content.into());
171        entry
172    }
173}
174
175impl From<Cow<'static, str>> for Entry {
176    fn from(content: Cow<'static, str>) -> Self {
177        let mut entry = Self::new();
178        entry.code = Some(content.into());
179        entry
180    }
181}
182
183impl From<ExtensionHook> for Entry {
184    fn from(hook: ExtensionHook) -> Self {
185        let mut entry = Self::new();
186        entry.extension = Some(hook.into());
187        entry
188    }
189}
190
191impl Entry {
192    const fn new() -> Self {
193        Self {
194            code: None,
195            extension: None,
196        }
197    }
198
199    pub fn replace_content<T>(&mut self, content: T)
200    where
201        T: Into<Cow<'static, [u8]>>,
202    {
203        self.code.replace(Code::from(content.into()));
204    }
205
206    pub fn set_extension(&mut self, hook: ExtensionHook) {
207        self.extension.replace(Extension::new(hook));
208    }
209
210    pub fn extension(&self) -> Option<ExtensionHook> {
211        self.extension.as_ref().map(|ext| ext.hook)
212    }
213}
214
215/// Virtual file system for sources, extensions, and require metadata.
216///
217/// `Memory` is a [`HashMap`] from paths to an entry struct that contains:
218///
219/// - A bit for whether the path that points to the entry has been required
220///   before.
221/// - Optional binary content representing Ruby source code.
222/// - Optional hook to a Rust function to be executed on `require` (similar to a
223///   MRI C extension rubygem).
224///
225/// Sources in `Memory` are only writable via the [`LoadSources`] trait. Sources
226/// can only be completely replaced.
227///
228/// These APIs are consumed primarily by the `Kernel::require` implementation in
229/// `extn::core::kernel::require`.
230///
231/// [`LoadSources`]: artichoke_core::load::LoadSources
232#[derive(Debug)]
233pub struct Memory {
234    fs: HashMap<BString, Entry>,
235    loaded_features: HashSet<BString>,
236    cwd: PathBuf,
237}
238
239impl Default for Memory {
240    /// Virtual file system with current working directory set to
241    /// [`RUBY_LOAD_PATH`].
242    fn default() -> Self {
243        let cwd = PathBuf::from(RUBY_LOAD_PATH);
244        Self {
245            fs: HashMap::default(),
246            loaded_features: HashSet::default(),
247            cwd,
248        }
249    }
250}
251
252impl Memory {
253    /// Create a new in memory virtual file system.
254    ///
255    /// Sets the current working directory of the virtual file system to
256    /// [`RUBY_LOAD_PATH`] for storing Ruby source files. This path is searched
257    /// by [`Kernel::require`], [`Kernel::require_relative`], and [`Kernel::load`].
258    ///
259    /// [`Kernel::require`]: https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
260    /// [`Kernel::require_relative`]: https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require_relative
261    /// [`Kernel::load`]: https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-load
262    #[must_use]
263    pub fn new() -> Self {
264        Self::default()
265    }
266
267    /// Create a new in memory virtual file system with the given working
268    /// directory.
269    #[must_use]
270    pub fn with_working_directory<T>(cwd: T) -> Self
271    where
272        T: Into<PathBuf>,
273    {
274        let cwd = cwd.into();
275        Self {
276            fs: HashMap::default(),
277            loaded_features: HashSet::default(),
278            cwd,
279        }
280    }
281
282    /// Check whether `path` points to a file in the virtual file system and
283    /// return the absolute path if it exists.
284    ///
285    /// This API is infallible and will return [`None`] for non-existent paths.
286    #[must_use]
287    pub fn resolve_file(&self, path: &Path) -> Option<Vec<u8>> {
288        let path = absolutize_relative_to(path, &self.cwd);
289        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
290            return None;
291        }
292        match normalize_slashes(path) {
293            Ok(path) if self.fs.contains_key(path.as_bstr()) => Some(path),
294            _ => None,
295        }
296    }
297
298    /// Check whether `path` points to a file in the virtual file system.
299    ///
300    /// This API is infallible and will return `false` for non-existent paths.
301    #[must_use]
302    pub fn is_file(&self, path: &Path) -> bool {
303        let path = absolutize_relative_to(path, &self.cwd);
304        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
305            return false;
306        }
307        if let Ok(path) = normalize_slashes(path) {
308            self.fs.contains_key(path.as_bstr())
309        } else {
310            false
311        }
312    }
313
314    /// Read file contents for the file at `path`.
315    ///
316    /// Returns a byte slice of complete file contents. If `path` is relative,
317    /// it is absolutized relative to the current working directory of the
318    /// virtual file system.
319    ///
320    /// # Errors
321    ///
322    /// If `path` does not exist, an [`io::Error`] with error kind
323    /// [`io::ErrorKind::NotFound`] is returned.
324    pub fn read_file(&self, path: &Path) -> io::Result<Vec<u8>> {
325        let path = absolutize_relative_to(path, &self.cwd);
326        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
327            let mut message = String::from("Only paths beginning with ");
328            message.push_str(RUBY_LOAD_PATH);
329            message.push_str(" are readable");
330            return Err(io::Error::new(io::ErrorKind::NotFound, message));
331        }
332        let path =
333            normalize_slashes(path).map_err(|_| io::Error::new(io::ErrorKind::NotFound, ConvertBytesError::new()))?;
334        if let Some(entry) = self.fs.get(path.as_bstr()) {
335            if let Some(ref code) = entry.code {
336                match code.content {
337                    Cow::Borrowed(content) => Ok(content.into()),
338                    Cow::Owned(ref content) => Ok(content.clone()),
339                }
340            } else {
341                Ok(Code::new().content.into())
342            }
343        } else {
344            Err(io::Error::new(
345                io::ErrorKind::NotFound,
346                "file not found in virtual file system",
347            ))
348        }
349    }
350
351    /// Write file contents into the virtual file system at `path`.
352    ///
353    /// Writes the full file contents. If any file contents already exist at
354    /// `path`, they are replaced. Extension hooks are preserved.
355    ///
356    /// # Errors
357    ///
358    /// This API is currently infallible but returns [`io::Result`] to reserve
359    /// the ability to return errors in the future.
360    pub fn write_file(&mut self, path: &Path, buf: Cow<'static, [u8]>) -> io::Result<()> {
361        let path = absolutize_relative_to(path, &self.cwd);
362        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
363            let mut message = String::from("Only paths beginning with ");
364            message.push_str(RUBY_LOAD_PATH);
365            message.push_str(" are writable");
366            return Err(io::Error::new(io::ErrorKind::PermissionDenied, message));
367        }
368        let path =
369            normalize_slashes(path).map_err(|_| io::Error::new(io::ErrorKind::NotFound, ConvertBytesError::new()))?;
370        match self.fs.entry(path.into()) {
371            HashEntry::Occupied(mut entry) => {
372                entry.get_mut().replace_content(buf);
373            }
374            HashEntry::Vacant(entry) => {
375                entry.insert(Entry::from(buf));
376            }
377        }
378        Ok(())
379    }
380
381    /// Retrieve an extension hook for the file at `path`.
382    ///
383    /// This API is infallible and will return `None` for non-existent paths.
384    #[must_use]
385    pub fn get_extension(&self, path: &Path) -> Option<ExtensionHook> {
386        let path = absolutize_relative_to(path, &self.cwd);
387        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
388            return None;
389        }
390        let path = normalize_slashes(path).ok()?;
391        if let Some(entry) = self.fs.get(path.as_bstr()) {
392            entry.extension()
393        } else {
394            None
395        }
396    }
397
398    /// Write extension hook into the virtual file system at `path`.
399    ///
400    /// If any extension hooks already exist at `path`, they are replaced. File
401    /// contents are preserved.
402    ///
403    /// # Errors
404    ///
405    /// This API is currently infallible but returns [`io::Result`] to reserve
406    /// the ability to return errors in the future.
407    pub fn register_extension(&mut self, path: &Path, extension: ExtensionHook) -> io::Result<()> {
408        let path = absolutize_relative_to(path, &self.cwd);
409        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
410            let mut message = String::from("Only paths beginning with ");
411            message.push_str(RUBY_LOAD_PATH);
412            message.push_str(" are writable");
413            return Err(io::Error::new(io::ErrorKind::PermissionDenied, message));
414        }
415        let path =
416            normalize_slashes(path).map_err(|_| io::Error::new(io::ErrorKind::NotFound, ConvertBytesError::new()))?;
417        match self.fs.entry(path.into()) {
418            HashEntry::Occupied(mut entry) => {
419                entry.get_mut().set_extension(extension);
420            }
421            HashEntry::Vacant(entry) => {
422                entry.insert(Entry::from(extension));
423            }
424        }
425        Ok(())
426    }
427
428    /// Check whether a file at `path` has been required already.
429    ///
430    /// This API is infallible and will return `false` for non-existent paths.
431    #[must_use]
432    pub fn is_required(&self, path: &Path) -> Option<bool> {
433        let path = absolutize_relative_to(path, &self.cwd);
434        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
435            return None;
436        }
437        if let Ok(path) = normalize_slashes(path) {
438            Some(self.loaded_features.contains(path.as_bstr()))
439        } else {
440            None
441        }
442    }
443
444    /// Mark a source at `path` as required on the interpreter.
445    ///
446    /// This metadata is used by `Kernel#require` and friends to enforce that
447    /// Ruby sources are only loaded into the interpreter once to limit side
448    /// effects.
449    ///
450    /// # Errors
451    ///
452    /// If `path` does not exist, an [`io::Error`] with error kind
453    /// [`io::ErrorKind::NotFound`] is returned.
454    pub fn mark_required(&mut self, path: &Path) -> io::Result<()> {
455        let path = absolutize_relative_to(path, &self.cwd);
456        if path.strip_prefix(RUBY_LOAD_PATH).is_err() {
457            let mut message = String::from("Only paths beginning with ");
458            message.push_str(RUBY_LOAD_PATH);
459            message.push_str(" are writable");
460            return Err(io::Error::new(io::ErrorKind::PermissionDenied, message));
461        }
462        match normalize_slashes(path) {
463            Ok(path) => {
464                self.loaded_features.insert(path.into());
465                Ok(())
466            }
467            Err(_) => Err(io::Error::new(io::ErrorKind::NotFound, ConvertBytesError::new())),
468        }
469    }
470}
471
472#[cfg(test)]
473mod tests {
474    use super::Extension;
475    use crate::test::prelude::*;
476
477    struct TestFile;
478
479    impl File for TestFile {
480        type Artichoke = Artichoke;
481        type Error = Error;
482
483        fn require(_interp: &mut Artichoke) -> Result<(), Self::Error> {
484            Ok(())
485        }
486    }
487
488    #[test]
489    fn extension_hook_prototype() {
490        // must compile
491        let _extension = Extension::new(TestFile::require);
492    }
493}
artichoke_backend/load_path/memory.rs

artichoke_backend/load_path/
memory.rs
