Feat/tera: Support Tera Templating

examples/poem/tera-i18n/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "example-tera-i18n"
+version.workspace = true
+edition.workspace = true
+publish.workspace = true
+
+[dependencies]
+poem = { workspace = true, features = ["tera", "i18n"] }
+tokio = { workspace = true, features = ["full"] }
+once_cell = "1.17.0"

examples/poem/tera-i18n/resources/en-US/simple.ftl

@@ -0,0 +1,2 @@
+hello-world = Hello world!
+welcome = welcome { $name }!

examples/poem/tera-i18n/resources/fr/simple.ftl

@@ -0,0 +1,2 @@
+hello-world = Bonjour le monde!
+welcome = Bienvenue { $name }!

examples/poem/tera-i18n/resources/zh-CN/simple.ftl

@@ -0,0 +1,2 @@
+hello-world = 你好世界！
+welcome = 欢迎 { $name }!

examples/poem/tera-i18n/src/main.rs

@@ -0,0 +1,37 @@
+use poem::{
+ ctx, get, handler,
+ i18n::I18NResources,
+ listener::TcpListener,
+ tera::{filters, Tera, TeraTemplate, TeraTemplating},
+ web::Path,
+ EndpointExt, Route, Server,
+};
+
+#[handler]
+fn index(tera: Tera) -> TeraTemplate {
+ tera.render("index.html.tera", &ctx! {})
+}
+
+#[handler]
+fn hello(Path(name): Path<String>, tera: Tera) -> TeraTemplate {
+ tera.render("hello.html.tera", &ctx! { "name": &name })
+}
+
+#[tokio::main]
+async fn main() -> Result<(), std::io::Error> {
+ let resources = I18NResources::builder()
+ .add_path("resources")
+ .build()
+ .unwrap();
+
+ let app = Route::new()
+ .at("/", get(index))
+ .at("/hello/:name", get(hello))
+ .with(TeraTemplating::from_glob("templates/**/*"))
+ .using(filters::i18n::translate)
+ .data(resources);
+
+ Server::new(TcpListener::bind("127.0.0.1:3000"))
+ .run(app)
+ .await
+}

examples/poem/tera-i18n/templates/hello.html.tera

@@ -0,0 +1 @@
+<h1>{{ "welcome" | translate(name=name) }}</h1>

examples/poem/tera-i18n/templates/index.html.tera

@@ -0,0 +1 @@
+<h1>{{ "hello-world" | translate }}</h1>

examples/poem/tera-templating/Cargo.toml

@@ -5,7 +5,6 @@ edition.workspace = true
 publish.workspace = true
 
 [dependencies]
-poem.workspace = true
+poem = { workspace = true, features = ["tera"] }
 tokio = { workspace = true, features = ["full"] }
-tera = "1.17.1"
 once_cell = "1.17.0"

examples/poem/tera-templating/src/main.rs

@@ -1,38 +1,22 @@
-use once_cell::sync::Lazy;
 use poem::{
- error::InternalServerError,
- get, handler,
+ ctx, get, handler,
  listener::TcpListener,
- web::{Html, Path},
- Route, Server,
+ tera::{Tera, TeraTemplate, TeraTemplating},
+ web::Path,
+ EndpointExt, Route, Server,
 };
-use tera::{Context, Tera};
-
-static TEMPLATES: Lazy<Tera> = Lazy::new(|| {
- let mut tera = match Tera::new("templates/**/*") {
- Ok(t) => t,
- Err(e) => {
- println!("Parsing error(s): {e}");
- ::std::process::exit(1);
- }
- };
- tera.autoescape_on(vec![".html", ".sql"]);
- tera
-});
 
 #[handler]
-fn hello(Path(name): Path<String>) -> Result<Html<String>, poem::Error> {
- let mut context = Context::new();
- context.insert("name", &name);
- TEMPLATES
- .render("index.html.tera", &context)
- .map_err(InternalServerError)
- .map(Html)
+fn hello(Path(name): Path<String>, tera: Tera) -> TeraTemplate {
+ tera.render("index.html.tera", &ctx! { "name": &name })
 }
 
 #[tokio::main]
 async fn main() -> Result<(), std::io::Error> {
- let app = Route::new().at("/hello/:name", get(hello));
+ let app = Route::new()
+ .at("/hello/:name", get(hello))
+ .with(TeraTemplating::from_glob("templates/**/*"));
+
  Server::new(TcpListener::bind("127.0.0.1:3000"))
  .run(app)
  .await

poem-openapi/src/base.rs

@@ -1,6 +1,7 @@
 use std::{
  collections::HashMap,
  fmt::{self, Debug, Display},
+ marker::Send,
  ops::Deref,
 };
 
@@ -198,7 +199,7 @@ pub trait ApiExtractor<'a>: Sized {
 }
 
 #[poem::async_trait]
-impl<'a, T: FromRequest<'a>> ApiExtractor<'a> for T {
+impl<'a, T: FromRequest<'a> + Send> ApiExtractor<'a> for T {
  const TYPE: ApiExtractorType = ApiExtractorType::PoemExtractor;
 
  type ParamType = ();

poem/Cargo.toml

@@ -64,6 +64,7 @@ acme = [
 embed = ["rust-embed", "hex", "mime_guess"]
 xml = ["quick-xml"]
 yaml = ["serde_yaml"]
+tera = ["dep:tera"]
 
 [dependencies]
 poem-derive.workspace = true
@@ -153,6 +154,7 @@ hex = { version = "0.4", optional = true }
 quick-xml = { workspace = true, optional = true }
 serde_yaml = { workspace = true, optional = true }
 tokio-stream = { workspace = true, optional = true }
+tera = { version = "1.17.1", optional = true }
 
 # Feature optional dependencies
 anyhow = { version = "1.0.0", optional = true }

poem/README.md

@@ -51,7 +51,7 @@ which are disabled by default:
 
 | Feature | Description |
 |---------------|-------------------------------------------------------------------------------------------|
-| server | Server and listener APIs (enabled by default)  | |
+| server | Server and listener APIs (enabled by default) |
 | compression | Support decompress request body and compress response body |
 | cookie | Support for Cookie |
 | csrf | Support for Cross-Site Request Forgery (CSRF) protection |
@@ -75,7 +75,8 @@ which are disabled by default:
 | tokio-metrics | Integrate with [`tokio-metrics`](https://crates.io/crates/tokio-metrics) crate. |
 | embed | Integrate with [`rust-embed`](https://crates.io/crates/rust-embed) crate. |
 | xml | Integrate with [`quick-xml`](https://crates.io/crates/quick-xml) crate. |
-| yaml | Integrate with [`serde-yaml`](https://crates.io/crates/serde-yaml) crate. |
+| yaml | Integrate with [`serde-yaml`](https://crates.io/crates/serde-yaml) crate. |
+| tera | Support for [`tera`](https://crates.io/crates/tera) templating. |
 
 ## Safety
 

poem/src/i18n/locale.rs

@@ -86,7 +86,7 @@ impl Locale {
 
 #[async_trait::async_trait]
 impl<'a> FromRequest<'a> for Locale {
- async fn from_request(req: &'a Request, _body: &mut RequestBody) -> Result<Self> {
+ fn from_request_sync(req: &'a Request, _body: &mut RequestBody) -> Result<Self> {
  let resources = req
  .extensions()
  .get::<I18NResources>()

poem/src/lib.rs

@@ -254,6 +254,7 @@
 //! | embed | Integrate with [`rust-embed`](https://crates.io/crates/rust-embed) crate. |
 //! | xml | Integrate with [`quick-xml`](https://crates.io/crates/quick-xml) crate. |
 //! | yaml | Integrate with [`serde-yaml`](https://crates.io/crates/serde-yaml) crate. |
+//! | tera | Support for [`tera`](https://crates.io/crates/tera) templating. |
 
 #![doc(html_favicon_url = "https://raw.githubusercontent.com/poem-web/poem/master/favicon.ico")]
 #![doc(html_logo_url = "https://raw.githubusercontent.com/poem-web/poem/master/logo.png")]
@@ -274,6 +275,9 @@ pub mod middleware;
 #[cfg(feature = "session")]
 #[cfg_attr(docsrs, doc(cfg(feature = "session")))]
 pub mod session;
+#[cfg(feature = "tera")]
+#[cfg_attr(docsrs, doc(cfg(feature = "tera")))]
+pub mod tera;
 #[cfg(feature = "test")]
 #[cfg_attr(docsrs, doc(cfg(feature = "test")))]
 pub mod test;

poem/src/tera/middleware.rs

@@ -0,0 +1,135 @@
+use tera::Tera;
+
+use crate::{
+ error::{InternalServerError, IntoResult},
+ web::Html,
+ Endpoint, FromRequest, Middleware, Request, RequestBody, Result,
+};
+
+/// Tera Templating Middleware
+pub struct TeraTemplatingMiddleware {
+ tera: Tera,
+}
+
+impl TeraTemplatingMiddleware {
+ /// Create a new instance of TeraTemplating, containing all the parsed
+ /// templates found in the glob The errors are already handled. Use
+ /// TeraTemplating::custom(tera: Tera) to modify tera settings.
+ ///
+ /// ```no_compile
+ /// use poem::tera::TeraTemplating;
+ ///
+ /// let templating = TeraTemplating::from_glob("templates/**/*");
+ /// ```
+ pub fn from_glob(glob: &str) -> Self {
+ let tera = match Tera::new(glob) {
+ Ok(t) => t,
+ Err(e) => {
+ println!("Parsing error(s): {e}");
+ ::std::process::exit(1);
+ }
+ };
+
+ Self { tera }
+ }
+
+ /// Create a new instance of TeraTemplating, using the provided Tera
+ /// instance
+ ///
+ /// ```no_compile
+ /// use poem::tera::{TeraTemplating, Tera};
+ ///
+ /// let mut tera = match Tera::new("templates/**/*") {
+ /// Ok(t) => t,
+ /// Err(e) => {
+ /// println!("Parsing error(s): {e}");
+ /// ::std::process::exit(1);
+ /// }
+ /// };
+ /// tera.autoescape_on(vec![".html", ".sql"]);
+ /// let templating = TeraTemplating::custom(tera);
+ /// ```
+ pub fn custom(tera: Tera) -> Self {
+ Self { tera }
+ }
+}
+
+impl<E: Endpoint> Middleware<E> for TeraTemplatingMiddleware {
+ type Output = TeraTemplatingEndpoint<E>;
+
+ fn transform(&self, inner: E) -> Self::Output {
+ Self::Output {
+ tera: self.tera.clone(),
+ inner,
+ transformers: Vec::new(),
+ }
+ }
+}
+
+/// Tera Templating Endpoint
+pub struct TeraTemplatingEndpoint<E> {
+ tera: Tera,
+ inner: E,
+ transformers: Vec<fn(&mut Tera, &mut Request)>,
+}
+
+#[async_trait::async_trait]
+impl<E: Endpoint> Endpoint for TeraTemplatingEndpoint<E> {
+ type Output = E::Output;
+
+ async fn call(&self, mut req: Request) -> Result<Self::Output> {
+ let mut tera = self.tera.clone();
+
+ for transformer in &self.transformers {
+ transformer(&mut tera, &mut req);
+ }
+
+ req.extensions_mut().insert(tera);
+
+ self.inner.call(req).await
+ }
+}
+
+#[async_trait::async_trait]
+impl<'a> FromRequest<'a> for Tera {
+ async fn from_request(req: &'a Request, _body: &mut RequestBody) -> Result<Self> {
+ let tera = req
+ .extensions()
+ .get::<Tera>()
+ .expect("To use the `Tera` extractor, the `TeraTemplating` endpoit is required.")
+ .clone();
+
+ Ok(tera)
+ }
+}
+
+/// Shortcut (or not) for a Tera Templating handler Response
+pub type TeraTemplatingResult = tera::Result<String>;
+
+impl IntoResult<Html<String>> for TeraTemplatingResult {
+ fn into_result(self) -> Result<Html<String>> {
+ if let Err(err) = &self {
+ println!("{err:?}");
+ }
+
+ self.map_err(InternalServerError).map(Html)
+ }
+}
+
+impl<E: Endpoint> TeraTemplatingEndpoint<E> {
+ /// Add a transformer that apply changes to each tera instances (for
+ /// instance, registering a dynamic filter) before passing tera to
+ /// request handlers
+ ///
+ /// ```no_compile
+ /// use poem::{Route, EndpointExt, tera::TeraTemplating};
+ ///
+ /// let app = Route::new()
+ /// .with(TeraTemplating::from_glob("templates/**/*"))
+ /// .using(|tera, req| println!("{tera:?}\n{req:?}"));
+ /// ```
+ pub fn using(mut self, transformer: fn(&mut Tera, &mut Request)) -> Self {
+ self.transformers.push(transformer);
+ self
+ }
+}