gwasm-api 0.3.0

//! Convenience types for creating and managing gWasm tasks
use super::{
    error::{Error, FileContext},
    timeout::Timeout,
    Result,
};
use serde::Serialize;
use std::{
    collections::BTreeMap,
    convert::TryFrom,
    fs::{self, File},
    io::BufReader,
    path::{Component, Path, PathBuf},
    str::FromStr,
};

/// Wrapper type for easy passing of gWasm binary
#[derive(Debug)]
pub struct GWasmBinary<'a> {
    /// Contents of JavaScript file generated by Emscripten
    pub js: &'a [u8],
    /// Contents of Wasm file generated by Emscripten
    pub wasm: &'a [u8],
}

/// gWasm task builder
///
/// Note that when [`build`] method is executed, the `TaskBuilder` will
/// be consumed and will generate a [`Task`] and a corresponding dir
/// and file structure in the provided `workspace` [`Path`]. For more
/// details about the dir structure, see [gWasm docs].
///
/// # Example:
/// ```
/// use gwasm_api::task::{GWasmBinary, TaskBuilder};
/// use std::path::Path;
/// use tempfile::tempdir;
///
/// let binary = GWasmBinary {
///     js: &[],
///     wasm: &[],
/// };
/// let workspace = tempdir().unwrap();
/// let task = TaskBuilder::try_new(&workspace, binary).unwrap().build();
/// assert!(task.is_ok());
/// assert!(task.unwrap().options().subtasks().next().is_none());
/// ```
///
/// [`build`]: struct.TaskBuilder.html#method.build
/// [`Task`]: ../task/struct.Task.html
/// [`Path`]: https://doc.rust-lang.org/std/path/struct.Path.html
/// [gWasm docs]: https://docs.golem.network/#/Products/gWASM/gWASM-tasks?id=inputoutput
#[derive(Debug)]
pub struct TaskBuilder<'a> {
    binary: GWasmBinary<'a>,
    name: Option<String>,
    bid: Option<f64>,
    budget: Option<f64>,
    timeout: Option<Timeout>,
    subtask_timeout: Option<Timeout>,
    input_dir_path: PathBuf,
    output_dir_path: PathBuf,
    output_path: Option<PathBuf>,
    subtask_data: Vec<Vec<u8>>,
}

impl<'a> TaskBuilder<'a> {
    /// Creates new `TaskBuilder` from workspace `Path` and `GWasmBinary`
    #[deprecated(
        since = "0.3.0",
        note = "Use try_new instead, which properly handles relative paths"
    )]
    pub fn new<P: AsRef<Path>>(workspace: P, binary: GWasmBinary<'a>) -> Self {
        Self {
            binary,
            name: None,
            bid: None,
            budget: None,
            timeout: None,
            subtask_timeout: None,
            input_dir_path: workspace.as_ref().join("in"),
            output_dir_path: workspace.as_ref().join("out"),
            output_path: None,
            subtask_data: Vec::new(),
        }
    }

    /// Creates new `TaskBuilder` from workspace `Path` and `GWasmBinary`
    pub fn try_new<P: AsRef<Path>>(workspace: P, binary: GWasmBinary<'a>) -> Result<Self> {
        let abspath = workspace.as_ref().canonicalize()?;
        #[allow(deprecated)]
        Ok(Self::new(abspath, binary))
    }

    /// Sets task's name
    pub fn name<S: AsRef<str>>(mut self, name: S) -> Self {
        self.name = Some(name.as_ref().to_owned());
        self
    }

    /// Sets task's bid value
    pub fn bid(mut self, bid: f64) -> Self {
        self.bid = Some(bid);
        self
    }

    /// Sets task's budget value
    pub fn budget(mut self, budget: f64) -> Self {
        self.budget = Some(budget);
        self
    }

    /// Sets task's [`Timeout`](../timeout/struct.Timeout.html) value
    pub fn timeout(mut self, timeout: Timeout) -> Self {
        self.timeout = Some(timeout);
        self
    }

    /// Sets subtasks' [`Timeout`](../timeout/struct.Timeout.html) value
    pub fn subtask_timeout(mut self, subtask_timeout: Timeout) -> Self {
        self.subtask_timeout = Some(subtask_timeout);
        self
    }

    /// Sets task's expected output path, i.e., where the final result of
    /// the task is meant to land
    pub fn output_path<P: AsRef<Path>>(mut self, output_path: P) -> Self {
        self.output_path = Some(output_path.as_ref().into());
        self
    }

    /// Pushes subtask data into the buffer
    ///
    /// Each pushed chunk of `data` will be a separate subtask that
    /// will be executed on Golem Network.
    /// To learn how to access the input data, consult the
    /// [general crate docs].
    ///
    /// [general crate docs]: ../index.html
    pub fn push_subtask_data<T: Into<Vec<u8>>>(mut self, data: T) -> Self {
        self.subtask_data.push(data.into());
        self
    }

    /// Consumes this builder and creates a `Task`
    ///
    /// Note that when this method is executed, a corresponding dir
    /// and file structure in the provided `workspace` [`Path`]. For more
    /// details about the dir structure, see [gWasm docs].
    ///
    /// [`Path`]: https://doc.rust-lang.org/std/path/struct.Path.html
    /// [gWasm docs]: https://docs.golem.network/#/Products/gWASM/gWASM-tasks?id=inputoutput
    pub fn build(mut self) -> Result<Task> {
        let name = self.name.take().unwrap_or("unknown".to_owned());
        let bid = self.bid.unwrap_or(1.0);
        let timeout = self.timeout.unwrap_or(
            Timeout::from_str("00:10:00")
                .expect("could correctly parse default task timeout value"),
        );
        let subtask_timeout = self.subtask_timeout.unwrap_or(
            Timeout::from_str("00:10:00")
                .expect("could correctly parse default subtask timeout value"),
        );
        let js_name = format!("{}.js", name);
        let wasm_name = format!("{}.wasm", name);
        let mut options = Options::new(
            js_name,
            wasm_name,
            self.input_dir_path.clone(),
            self.output_dir_path.clone(),
            self.output_path.clone(),
        );

        // create input dir
        fs::create_dir(&options.input_dir_path).file_context(&options.input_dir_path)?;

        // save JS file
        let js_filename = options.input_dir_path.join(&options.js_name);
        fs::write(&js_filename, self.binary.js).file_context(&js_filename)?;

        // save WASM file
        let wasm_filename = options.input_dir_path.join(&options.wasm_name);
        fs::write(&wasm_filename, self.binary.wasm).file_context(&wasm_filename)?;

        // create output dir
        fs::create_dir(&options.output_dir_path).file_context(&options.output_dir_path)?;

        // subtasks
        for (i, chunk) in self.subtask_data.into_iter().enumerate() {
            let name = format!("subtask_{}", i);

            // create input subtask dir
            let input_dir_path = options.input_dir_path.join(&name);
            fs::create_dir(&input_dir_path).file_context(&input_dir_path)?;

            // create output subtask dir
            let output_dir_path = options.output_dir_path.join(&name);
            fs::create_dir(&output_dir_path).file_context(&output_dir_path)?;

            // save input data file
            let input_name = format!("in{}", i);
            let input_filename = input_dir_path.join(&input_name);
            fs::write(&input_filename, &chunk).file_context(&input_filename)?;

            let mut subtask = Subtask::new();
            subtask.exec_args.push(input_name.into());

            let output_name = "out";
            subtask.exec_args.push(output_name.into());
            subtask.output_file_paths.push(output_name.into());

            options.subtasks.insert(name, subtask);
        }

        Ok(Task::new(
            name,
            bid,
            self.budget,
            timeout,
            subtask_timeout,
            options,
        ))
    }
}

/// Struct representing gWasm task
///
/// This type serves two purposes: 1) it can be serialized to JSON manifest
/// required by Golem (see [gWasm Task JSON]), and 2) it tracks the dirs and files
/// created on disk which contain the actual subtasks' data and params.
///
/// # Example:
/// ```
/// use gwasm_api::task::{GWasmBinary, TaskBuilder};
/// use std::path::Path;
/// use serde_json::json;
/// use tempfile::tempdir;
///
/// let binary = GWasmBinary {
///     js: &[],
///     wasm: &[],
/// };
/// let workspace = tempdir().unwrap();
/// let task = TaskBuilder::try_new(&workspace, binary).unwrap().build().unwrap();
/// let json_manifest = json!(task);
/// ```
///
/// [gWasm Task JSON]: https://docs.golem.network/#/Products/gWASM/gWASM-tasks?id=task-json
/// [`TaskBuilder`]: ../task/struct.TaskBuilder.html
#[derive(Debug, Serialize, Clone)]
pub struct Task {
    #[serde(rename = "type")]
    task_type: String,
    name: String,
    bid: f64,
    #[serde(skip_serializing_if = "Option::is_none")]
    budget: Option<f64>,
    timeout: Timeout,
    subtask_timeout: Timeout,
    options: Options,
}

impl Task {
    /// Creates a new `Task` instance
    pub fn new<S: Into<String>>(
        name: S,
        bid: f64,
        budget: Option<f64>,
        timeout: Timeout,
        subtask_timeout: Timeout,
        options: Options,
    ) -> Self {
        Self {
            task_type: "wasm".into(),
            name: name.into(),
            bid,
            budget,
            timeout,
            subtask_timeout,
            options,
        }
    }

    /// Task's name
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Task's bid value
    pub fn bid(&self) -> f64 {
        self.bid
    }

    /// Task's budget value
    pub fn budget(&self) -> Option<f64> {
        self.budget
    }

    /// Task's [`Timeout`](../timeout/struct.Timeout.html) value
    pub fn timeout(&self) -> &Timeout {
        &self.timeout
    }

    /// Subtasks' [`Timeout`](../timeout/struct.Timeout.html) value
    pub fn subtask_timeout(&self) -> &Timeout {
        &self.subtask_timeout
    }

    /// [`Options`](../task/struct.Options.html) substructure
    pub fn options(&self) -> &Options {
        &self.options
    }
}

/// Struct representing gWasm task's options substructure
///
/// Stores information such as the name of JavaScript file, or the
/// name of Wasm binary. This struct should only ever be used in conjunction
/// with the [`Task`] structure.
///
/// [`Task`]: ../task/struct.Task.html
#[derive(Debug, Serialize, Clone)]
pub struct Options {
    js_name: String,
    wasm_name: String,
    #[serde(rename = "input_dir")]
    input_dir_path: PathBuf,
    #[serde(rename = "output_dir")]
    output_dir_path: PathBuf,
    #[serde(skip_serializing_if = "Option::is_none")]
    output_path: Option<PathBuf>,
    subtasks: BTreeMap<String, Subtask>,
}

impl Options {
    /// Creates a new `Options` instance
    pub fn new<S: Into<String>, P: Into<PathBuf>>(
        js_name: S,
        wasm_name: S,
        input_dir_path: P,
        output_dir_path: P,
        output_path: Option<P>,
    ) -> Self {
        Self {
            js_name: js_name.into(),
            wasm_name: wasm_name.into(),
            input_dir_path: input_dir_path.into(),
            output_dir_path: output_dir_path.into(),
            output_path: output_path.map(Into::into),
            subtasks: BTreeMap::new(),
        }
    }

    /// Name of the JavaScript file
    pub fn js_name(&self) -> &str {
        &self.js_name
    }

    /// Name of the Wasm binary
    pub fn wasm_name(&self) -> &str {
        &self.wasm_name
    }

    /// Path to the task's input dir
    pub fn input_dir_path(&self) -> &Path {
        &self.input_dir_path
    }

    /// Path to the task's output dir
    pub fn output_dir_path(&self) -> &Path {
        &self.output_dir_path
    }

    /// Path to the dir where the final output of the task
    /// is expected
    pub fn output_path(&self) -> Option<&Path> {
        self.output_path.as_ref().map(AsRef::as_ref)
    }

    /// Returns an [`Iterator`] over created [`Subtask`]'s
    ///
    /// [`Subtask`]: ../task/struct.Subtask.html
    /// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
    pub fn subtasks(&self) -> impl Iterator<Item = (&str, &Subtask)> {
        self.subtasks
            .iter()
            .map(|(name, subtask)| (name.as_str(), subtask))
    }

    /// Adds a new [`Subtask`] under the given name.
    pub fn add_subtask(&mut self, name: String, subtask: Subtask) {
        self.subtasks.insert(name, subtask);
    }
}

/// Struct representing gWasm task's subtask substructure
///
/// Stores information such as the execution arguments for the Wasm binary,
/// and output file paths for the computed results.
#[derive(Debug, Serialize, Clone)]
pub struct Subtask {
    /// CLI arguments to be passed for this subtask
    pub exec_args: Vec<String>,
    /// Paths to output files that will be used by this subtask
    pub output_file_paths: Vec<PathBuf>,
}

impl Subtask {
    /// Creates a new `Subtask` instance
    pub fn new() -> Self {
        Self {
            exec_args: Vec::new(),
            output_file_paths: Vec::new(),
        }
    }

    /// Returns an [`Iterator`] over the execution arguments of this subtask
    ///
    /// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
    pub fn exec_args(&self) -> impl Iterator<Item = &str> {
        self.exec_args.iter().map(|s| s.as_str())
    }

    /// Returns an [`Iterator`] over the output file paths of this subtask
    ///
    /// [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
    pub fn output_file_paths(&self) -> impl Iterator<Item = &Path> {
        self.output_file_paths.iter().map(|p| p.as_ref())
    }
}

/// Struct representing computed gWasm task
///
/// This struct in addition to storing some information about the
/// computed task such as its name, or timeouts, it first and foremost
/// contains a [`Vec`] of [`ComputedSubtask`]s.
///
/// # Example:
/// ```
/// use gwasm_api::task::{GWasmBinary, TaskBuilder, ComputedTask};
/// use std::path::Path;
/// use tempfile::tempdir;
/// use std::convert::TryInto;
///
/// let binary = GWasmBinary {
///     js: &[],
///     wasm: &[],
/// };
/// let workspace = tempdir().unwrap();
/// let task = TaskBuilder::try_new(&workspace, binary).unwrap().build().unwrap();
/// let computed_task: Result<ComputedTask, _> = task.try_into();
///
/// assert!(computed_task.is_ok());
/// assert!(computed_task.unwrap().subtasks.is_empty());
/// ```
///
/// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
/// [`ComputedSubtask`]: ../task/struct.ComputedSubtask.html
#[derive(Debug)]
pub struct ComputedTask {
    /// Task's name
    pub name: String,
    /// Used task bid value
    pub bid: f64,
    /// Used task [`Timeout`] value
    ///
    /// [`Timeout`]: ../timeout/struct.Timeout.html
    pub timeout: Timeout,
    /// Used subtask [`Timeout`] value
    ///
    /// [`Timeout`]: ../timeout/struct.Timeout.html
    pub subtask_timeout: Timeout,
    /// [`Vec`] of [`ComputedSubtask`]s, ordered by subtask data insertion
    /// using [`TaskBuilder::push_subtask_data`]
    ///
    /// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
    /// [`ComputedSubtask`]: ../task/struct.ComputedSubtask.html
    /// [`TaskBuilder::push_subtask_data`]:
    /// ../task/struct.TaskBuilder.html#method.push_subtask_data
    pub subtasks: Vec<ComputedSubtask>,
}

/// Struct representing computed subtask
///
/// It contains, for each [output file path], an instance of
/// [`BufReader`] which can be used to read the computed data from file
/// to a container.
///
/// [output file path]: ../task/struct.Subtask.html#method.output_file_paths
/// [`BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
#[derive(Debug)]
pub struct ComputedSubtask {
    /// [`BTreeMap`] of results for the `ComputedSubtask` where
    /// key is each path matching the output of [`Subtask::output_file_paths`],
    /// and the value is [`BufReader`] pointing to a file with computation
    /// results
    ///
    /// [`BTreeMap`]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html
    /// [`Subtask::output_file_paths`]: ../task/struct.Subtask.html#method.output_file_paths
    /// [`BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
    pub data: BTreeMap<PathBuf, BufReader<File>>,
    /// Subtask's name
    pub name: String,
}

impl TryFrom<Task> for ComputedTask {
    type Error = Error;

    fn try_from(task: Task) -> Result<Self> {
        let name = task.name;
        let bid = task.bid;
        let timeout = task.timeout;
        let subtask_timeout = task.subtask_timeout;
        let mut computed_subtasks = Vec::new();

        for (s_name, subtask) in task.options.subtasks() {
            let output_dir = task.options.output_dir_path().join(s_name);
            let mut computed_subtask = ComputedSubtask {
                data: BTreeMap::new(),
                name: String::from(s_name),
            };

            for out_path in subtask.output_file_paths() {
                let relative_path = out_path
                    .strip_prefix(Component::RootDir)
                    .unwrap_or(out_path);
                let fname = output_dir.join(relative_path);
                let f = File::open(&fname).file_context(&fname)?;
                let reader = BufReader::new(f);
                computed_subtask.data.insert(out_path.into(), reader);
            }

            computed_subtasks.push(computed_subtask);
        }

        Ok(Self {
            name,
            bid,
            timeout,
            subtask_timeout,
            subtasks: computed_subtasks,
        })
    }
}