sscan 0.15.0

A scriptable file/process/network scanner
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

//! # Add or remove items from the global scan queue
//!
//! The [`QueueApi`] allows userscripts to enqueue data items with the
//! [global scan queue]. As such, it is possible to programmatically
//! enqueue files and other data, rather than just providing a static
//! file list.
//!
//! ## Userscript API
//!
//! This is a userscript API. The API's functionality is registered with
//! the Lua virtual machine, where userscripts can call into it.
//!
//! ## API Usage Examples
//!
//! For full API documentation, launch sscan in interactive mode and
//! enter `help 'queue'`, or see [`topics::queue`].
//!
//! [global scan queue]: crate::actors::queue::Queue
//! [`topics::queue`]: crate::userscript_api::help_system::topics::queue

use crate::{
    actors::queue::{
        data_item::{FileDatum, RawDatum},
        error::Error as QueueError,
        messages::{Dequeue, Enqueue, GetLength},
        Queue,
    },
    userscript_api::{
        fs_api::path_obj::PathObj,
        include::{LuaEither, LuaUserDataRef},
        ApiObject,
    },
};
use kameo::actor::WeakActorRef;
use mlua::{ExternalError, Lua, UserData, UserDataRef};
use std::path::PathBuf;

/// # Global Scan Queue Userscript API
///
/// This [`ApiObject`] is exposed to the Lua userscript environment,
/// allowing for scripts to queue and dequeue [`DataItem`] objects
/// programmatically.
///
/// ## API Docs
///
/// To see detailed help for this API, launch sscan and call
/// `help 'queue'`. Alternatively, the docs for this API are
/// available [here](super::help_system::topics::queue).
///
/// [`DataItem`]: crate::actors::queue::data_item::DataItem
pub struct QueueApi(WeakActorRef<Queue>);

impl QueueApi {
    /// Create the API object for [registration] with [`LuaVM`].
    ///
    /// [registration]: crate::actors::lua_vm::messages::RegisterUserApi
    /// [`LuaVM`]: crate::actors::lua_vm::LuaVM
    #[must_use]
    pub fn new(queue: WeakActorRef<Queue>) -> Self {
        Self(queue)
    }
}

impl UserData for QueueApi {
    fn add_methods<M: mlua::UserDataMethods<Self>>(methods: &mut M) {
        methods.add_async_method("add_raw", queue_add_raw);
        methods.add_async_method("add_file", queue_add_file);
        methods.add_async_method("dequeue", queue_dequeue);
        methods.add_async_method("len", queue_len);
        methods.add_async_meta_method("__len", queue_len);
    }
}

impl ApiObject for QueueApi {
    fn name(&self) -> &'static str {
        "queue"
    }
}

/// Userscript function `queue:add_raw(name, data)`
async fn queue_add_raw(
    _: Lua,
    this: UserDataRef<QueueApi>,
    (name, content): (String, String),
) -> mlua::Result<()> {
    if let Some(queue) = this.0.upgrade() {
        let data_item: Box<RawDatum> = RawDatum::new(&name, content.as_bytes().to_vec());
        if queue.ask(Enqueue::item(data_item)).await.is_err() {
            Err(QueueError::SendError.into_lua_err())
        } else {
            Ok(())
        }
    } else {
        Err(QueueError::NoGlobalQueue.into_lua_err())
    }
}

/// Userscript function `queue:add_file(path)`
async fn queue_add_file(
    _: Lua,
    this: UserDataRef<QueueApi>,
    path: LuaEither<PathBuf, LuaUserDataRef<PathObj>>,
) -> mlua::Result<()> {
    if let Some(queue) = this.0.upgrade() {
        let path: PathBuf = match path {
            LuaEither::Left(pb) => pb,
            LuaEither::Right(po) => po.0.clone(),
        };
        let data_item: Box<FileDatum> = FileDatum::new(path);
        if queue.ask(Enqueue::item(data_item)).await.is_err() {
            Err(QueueError::SendError.into_lua_err())
        } else {
            Ok(())
        }
    } else {
        Err(QueueError::NoGlobalQueue.into_lua_err())
    }
}

/// Userscript function `queue:dequeue()`
async fn queue_dequeue(
    _: Lua,
    this: UserDataRef<QueueApi>,
    (): (),
) -> mlua::Result<(String, Option<PathBuf>, impl mlua::IntoLua)> {
    if let Some(queue) = this.0.upgrade() {
        match queue.ask(Dequeue).await {
            Ok((name, path, content)) => {
                let content = mlua::String::wrap(content);
                Ok((name, path, content))
            }
            Err(error) => Err(error.into_lua_err()),
        }
    } else {
        Err(QueueError::NoGlobalQueue.into_lua_err())
    }
}

/// Userscript function `queue:len()`
async fn queue_len(_: Lua, this: UserDataRef<QueueApi>, (): ()) -> mlua::Result<usize> {
    if let Some(queue) = this.0.upgrade() {
        queue
            .ask(GetLength)
            .await
            .map_err(mlua::ExternalError::into_lua_err)
    } else {
        Err(QueueError::NoGlobalQueue.into_lua_err())
    }
}