path: root/src/lib.rs

extern crate failure;
extern crate serde;
extern crate futures;
extern crate galemu;
extern crate mail_core;
extern crate mail_headers;
extern crate vec1;
extern crate toml;
#[cfg(feature="handlebars")]
extern crate handlebars as hbs;

use std::{
    fs,
    collections::HashMap,
    fmt::Debug,
    path::{Path, PathBuf},
    sync::Arc
};

use serde::{
    Serialize,
    Deserialize
};
use galemu::{Bound, BoundExt};
use failure::{Fail, Error};
use futures::{
    Future, Poll, Async,
    try_ready,
    future::{self, Join, Either}
};
use vec1::Vec1;

use mail_core::{
    Resource,
    Data, Metadata,
    Context, ResourceContainerLoadingFuture,
    compose::{MailParts, BodyPart},
    Mail
};
use mail_headers::{
    HeaderKind, Header,
    header_components::MediaType,
    headers
};

pub mod serde_impl;
mod base_dir;
mod path_rebase;
mod additional_cid;

// #[cfg(feature="handlebars")]
// pub mod handlebars;

pub use self::base_dir::*;
pub use self::path_rebase::*;
pub use self::additional_cid::*;

/// Trait used to bind/implement template engines.
pub trait TemplateEngine: Sized {
    type Id: Debug;

    type LazyBodyTemplate: PathRebaseable + Debug + Send + Serialize + for<'a> Deserialize<'a>;

    fn load_body_template(&mut self, tmpl: Self::LazyBodyTemplate)
        -> Result<BodyTemplate<Self>, Error>;

    fn load_subject_template(&mut self, template_string: String)
        -> Result<Self::Id, Error>;
}

/// Additional trait a template engine needs to implement for the types it can process as input.
///
/// This could for example be implemented in a wild card impl for the template engine for
/// any data `D` which implements `Serialize`.
pub trait TemplateEngineCanHandleData<D>: TemplateEngine {

    //TODO[doc]: this is needed for all template engines which use to json serialization
    // (we have more then one template so there would be a lot of overhead)
    type PreparedData: for<'a> BoundExt<'a>;

    //TODO[design]: allow returning a result
    fn prepare_data<'a>(&self, raw: &'a D) -> PreparationData<'a, Self::PreparedData>;

    fn render<'r, 'a>(
        &'r self,
        id: &'r Self::Id,
        data: &'r Bound<'a, Self::PreparedData>,
        additional_cids: AdditionalCIds<'r>
    ) -> Result<String, Error>;
}

/// Load a template as described in a toml file.
pub fn load_toml_template_from_path<TE, C>(
    engine: TE,
    path: PathBuf,
    ctx: &C
) -> impl Future<Item=Template<TE>, Error=Error>
    where TE: TemplateEngine + 'static, C: Context
{

    let ctx2 = ctx.clone();
    ctx.offload_fn(move || {
        let content = fs::read_to_string(&path)?;
        let base: serde_impl::TemplateBase<TE> = toml::from_str(&content)?;
        let base_dir = path.parent().unwrap_or_else(||Path::new("."));
        let base_dir = CwdBaseDir::from_path(base_dir)?;
        Ok((base, base_dir))
    }).and_then(move |(base, base_dir)| base.load(engine, base_dir, &ctx2))
}

/// Load a template as described in a toml string;
pub fn load_toml_template_from_str<TE, C>(
    engine: TE,
    content: &str,
    ctx: &C
) -> impl Future<Item=Template<TE>, Error=Error>
    where TE: TemplateEngine, C: Context
{
    let base: serde_impl::TemplateBase<TE> =
        match toml::from_str(content) {
            Ok(base) => base,
            Err(err) => { return Either::B(future::err(Error::from(err))); }
        };

    let base_dir =
        match CwdBaseDir::from_path(Path::new(".")) {
            Ok(base_dir) => base_dir,
            Err(err) => { return Either::B(future::err(Error::from(err))) }
        };

    Either::A(base.load(engine, base_dir, ctx))
}

/// Compound POD for returning data needed for preparing for rendering a template.
pub struct PreparationData<'a, PD: for<'any> BoundExt<'any>> {
    pub attachments: Vec<Resource>,
    pub inline_embeddings: HashMap<String, Resource>,
    pub prepared_data: Bound<'a, PD>
}


/// A Mail template.
#[derive(Debug)]
pub struct Template<TE: TemplateEngine> {
    inner: Arc<InnerTemplate<TE>>
}

impl<TE> Template<TE>
    where TE: TemplateEngine
{
    pub fn inline_embeddings(&self) -> &HashMap<String, Resource> {
        &self.inner.embeddings
    }

    pub fn attachments(&self) -> &[Resource] {
        &self.inner.attachments
    }

    pub fn engine(&self) -> &TE {
        &self.inner.engine
    }

    pub fn bodies(&self) -> &[BodyTemplate<TE>] {
        &self.inner.bodies
    }

    pub fn subject_template_id(&self) -> &TE::Id {
        &self.inner.subject.template_id
    }
}

impl<TE> Clone for Template<TE>
    where TE: TemplateEngine
{
    fn clone(&self) -> Self {
        Template { inner: self.inner.clone() }
    }
}

#[derive(Debug)]
struct InnerTemplate<TE: TemplateEngine> {
    template_name: String,
    base_dir: CwdBaseDir,
    subject: Subject<TE>,
    /// This can only be in the loaded form _iff_ this is coupled
    /// with a template engine instance, as using it with the wrong
    /// template engine will lead to potential bugs and panics.
    bodies: Vec1<BodyTemplate<TE>>,
    //TODO: make sure
    embeddings: HashMap<String, Resource>,
    attachments: Vec<Resource>,
    engine: TE,
}


/// Automatically provides the `prepare_to_render` method for all `Templates`
///
/// This trait is implemented for all `Templates`/`D`(data) combinations where
/// the templates template engine can handle the given data (impl. `TemplateEngineCanHandleData<D>`)
///
/// This trait should not be implemented by hand.
pub trait TemplateExt<TE, D>
    where TE: TemplateEngine + TemplateEngineCanHandleData<D>
{
    fn prepare_to_render<'s, 'r, C>(&'s self, data: &'r D, ctx: &'s C) -> RenderPreparationFuture<'r, TE, D, C>
        where C: Context;
}


impl<TE, D> TemplateExt<TE, D> for Template<TE>
    where TE: TemplateEngine + TemplateEngineCanHandleData<D>
{
    fn prepare_to_render<'s, 'r, C>(&'s self, data: &'r D, ctx: &'s C) -> RenderPreparationFuture<'r, TE, D, C>
        where C: Context
    {
        let preps = self.inner.engine.prepare_data(data);

        let PreparationData {
            inline_embeddings,
            attachments,
            prepared_data
        } = preps;

        let loading_fut = Resource::load_container(inline_embeddings, ctx)
            .join(Resource::load_container(attachments, ctx));

        RenderPreparationFuture {
            payload: Some((
                self.clone(),
                prepared_data,
                ctx.clone()
            )),
            loading_fut
        }
    }
}

/// Future returned when preparing a template for rendering.
pub struct RenderPreparationFuture<'a, TE, D, C>
    where TE: TemplateEngine + TemplateEngineCanHandleData<D>, C: Context
{
    payload: Option<(
        Template<TE>,
        Bound<'a, <TE as TemplateEngineCanHandleData<D>>::PreparedData>,
        C
    )>,
    loading_fut: Join<
        ResourceContainerLoadingFuture<HashMap<String, Resource>>,
        ResourceContainerLoadingFuture<Vec<Resource>>
    >
}

impl<'a, TE,D,C> Future