codify "platform" into resolution logic, server-fn/fullstack overhaul (#4596)

overhaul dioxus fullstack using a new implementation of server_fn

This PR is a complete rewrite of dioxus fullstack designed to improve compatibility with axum and to fix a number of compilation errors based on feature flag unification plumbing through macros.

packages/fullstack-server/src/isrg/config.rs

@@ -0,0 +1,104 @@
+#![allow(non_snake_case)]
+
+#[cfg(not(target_arch = "wasm32"))]
+use crate::isrg::fs_cache::PathMapFn;
+
+use crate::isrg::memory_cache::InMemoryCache;
+use crate::IncrementalRenderer;
+
+use std::{
+    path::{Path, PathBuf},
+    time::Duration,
+};
+
+/// A configuration for the incremental renderer.
+#[derive(Clone)]
+pub struct IncrementalRendererConfig {
+    static_dir: PathBuf,
+    memory_cache_limit: usize,
+    invalidate_after: Option<Duration>,
+    clear_cache: bool,
+    pre_render: bool,
+
+    #[cfg(not(target_arch = "wasm32"))]
+    map_path: Option<PathMapFn>,
+}
+
+impl Default for IncrementalRendererConfig {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl IncrementalRendererConfig {
+    /// Create a new incremental renderer configuration.
+    pub fn new() -> Self {
+        Self {
+            static_dir: PathBuf::from("./static"),
+            memory_cache_limit: 10000,
+            invalidate_after: None,
+            clear_cache: false,
+            pre_render: false,
+            #[cfg(not(target_arch = "wasm32"))]
+            map_path: None,
+        }
+    }
+
+    /// Clear the cache on startup (default: true)
+    pub fn clear_cache(mut self, clear_cache: bool) -> Self {
+        self.clear_cache = clear_cache;
+        self
+    }
+
+    /// Set a mapping from the route to the file path. This will override the default mapping configured with `static_dir`.
+    /// The function should return the path to the folder to store the index.html file in.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub fn map_path<F: Fn(&str) -> PathBuf + Send + Sync + 'static>(mut self, map_path: F) -> Self {
+        self.map_path = Some(std::sync::Arc::new(map_path));
+        self
+    }
+
+    /// Set the static directory.
+    pub fn static_dir<P: AsRef<Path>>(mut self, static_dir: P) -> Self {
+        self.static_dir = static_dir.as_ref().to_path_buf();
+        self
+    }
+
+    /// Set the memory cache limit.
+    pub const fn memory_cache_limit(mut self, memory_cache_limit: usize) -> Self {
+        self.memory_cache_limit = memory_cache_limit;
+        self
+    }
+
+    /// Set the invalidation time.
+    pub fn invalidate_after(mut self, invalidate_after: Duration) -> Self {
+        self.invalidate_after = Some(invalidate_after);
+        self
+    }
+
+    /// Set whether to include hydration ids in the pre-rendered html.
+    pub fn pre_render(mut self, pre_render: bool) -> Self {
+        self.pre_render = pre_render;
+        self
+    }
+
+    /// Build the incremental renderer.
+    pub fn build(self) -> IncrementalRenderer {
+        let mut renderer = IncrementalRenderer {
+            #[cfg(not(target_arch = "wasm32"))]
+            file_system_cache: super::fs_cache::FileSystemCache::new(
+                self.static_dir.clone(),
+                self.map_path,
+                self.invalidate_after,
+            ),
+            memory_cache: InMemoryCache::new(self.memory_cache_limit, self.invalidate_after),
+            invalidate_after: self.invalidate_after,
+        };
+
+        if self.clear_cache {
+            renderer.invalidate_all();
+        }
+
+        renderer
+    }
+}

packages/fullstack-server/src/isrg/freshness.rs

@@ -0,0 +1,82 @@
+use std::time::Duration;
+
+use chrono::{DateTime, Utc};
+
+/// Information about the freshness of a rendered response
+#[derive(Debug, Clone, Copy)]
+pub struct RenderFreshness {
+    /// The age of the rendered response
+    age: u64,
+    /// The maximum age of the rendered response
+    max_age: Option<u64>,
+    /// The time the response was rendered
+    timestamp: DateTime<Utc>,
+}
+
+impl RenderFreshness {
+    /// Create new freshness information
+    pub(crate) fn new(age: u64, max_age: u64, timestamp: DateTime<Utc>) -> Self {
+        Self {
+            age,
+            max_age: Some(max_age),
+            timestamp,
+        }
+    }
+
+    /// Create new freshness information with only the age
+    pub(crate) fn new_age(age: u64, timestamp: DateTime<Utc>) -> Self {
+        Self {
+            age,
+            max_age: None,
+            timestamp,
+        }
+    }
+
+    /// Create new freshness information from a timestamp
+    pub(crate) fn created_at(timestamp: DateTime<Utc>, max_age: Option<Duration>) -> Self {
+        Self {
+            age: timestamp
+                .signed_duration_since(Utc::now())
+                .num_seconds()
+                .unsigned_abs(),
+            max_age: max_age.map(|d| d.as_secs()),
+            timestamp,
+        }
+    }
+
+    /// Create new freshness information at the current time
+    pub fn now(max_age: Option<Duration>) -> Self {
+        Self {
+            age: 0,
+            max_age: max_age.map(|d| d.as_secs()),
+            timestamp: Utc::now(),
+        }
+    }
+
+    /// Get the age of the rendered response in seconds
+    pub fn age(&self) -> u64 {
+        self.age
+    }
+
+    /// Get the maximum age of the rendered response in seconds
+    pub fn max_age(&self) -> Option<u64> {
+        self.max_age
+    }
+
+    /// Get the time the response was rendered
+    pub fn timestamp(&self) -> DateTime<Utc> {
+        self.timestamp
+    }
+
+    /// Write the freshness to the response headers.
+    pub fn write(&self, headers: &mut http::HeaderMap<http::HeaderValue>) {
+        let age = self.age();
+        headers.insert(http::header::AGE, age.into());
+        if let Some(max_age) = self.max_age() {
+            headers.insert(
+                http::header::CACHE_CONTROL,
+                http::HeaderValue::from_str(&format!("max-age={}", max_age)).unwrap(),
+            );
+        }
+    }
+}

packages/fullstack-server/src/isrg/fs_cache.rs

@@ -0,0 +1,193 @@
+#![allow(non_snake_case)]
+
+use chrono::{DateTime, Utc};
+
+use super::{IncrementalRendererError, RenderFreshness};
+use std::{path::PathBuf, sync::Arc, time::SystemTime};
+
+pub(crate) type PathMapFn = Arc<dyn Fn(&str) -> PathBuf + Send + Sync>;
+
+pub(crate) struct FileSystemCache {
+    static_dir: PathBuf,
+    map_path: PathMapFn,
+    invalidate_after: Option<std::time::Duration>,
+}
+
+impl FileSystemCache {
+    pub fn new(
+        static_dir: PathBuf,
+        map_path: Option<PathMapFn>,
+        invalidate_after: Option<std::time::Duration>,
+    ) -> Self {
+        Self {
+            static_dir: static_dir.clone(),
+            map_path: map_path.unwrap_or_else(move || {
+                Arc::new(move |route: &str| {
+                    let (before_query, _) = route.split_once('?').unwrap_or((route, ""));
+                    let mut path = static_dir.clone();
+                    for segment in before_query.split('/') {
+                        path.push(segment);
+                    }
+                    path
+                })
+            }),
+            invalidate_after,
+        }
+    }
+
+    pub fn put(
+        &mut self,
+        route: String,
+        timestamp: DateTime<Utc>,
+        data: Vec<u8>,
+    ) -> Result<(), IncrementalRendererError> {
+        use std::io::Write;
+        let file_path = self.route_as_path(&route, timestamp);
+        if let Some(parent) = file_path.parent() {
+            if !parent.exists() {
+                std::fs::create_dir_all(parent)?;
+            }
+        }
+        let file = std::fs::File::create(file_path)?;
+        let mut file = std::io::BufWriter::new(file);
+        file.write_all(&data)?;
+        Ok(())
+    }
+
+    pub fn clear(&mut self) {
+        // clear the static directory of index.html files contained within folders
+        for entry in std::fs::read_dir(&self.static_dir)
+            .into_iter()
+            .flatten()
+            .flatten()
+        {
+            if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+                for entry in walkdir::WalkDir::new(entry.path()).into_iter().flatten() {
+                    if entry.file_type().is_file() {
+                        if let Some(fnmae) = entry.file_name().to_str() {
+                            if fnmae.ends_with(".html") {
+                                if let Err(err) = std::fs::remove_file(entry.path()) {
+                                    tracing::error!("Failed to remove file: {}", err);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    pub fn invalidate(&mut self, route: &str) {
+        let file_path = self.find_file(route).unwrap().full_path;
+        if let Err(err) = std::fs::remove_file(file_path) {
+            tracing::error!("Failed to remove file: {}", err);
+        }
+    }
+
+    pub fn get(
+        &self,
+        route: &str,
+    ) -> Result<Option<(RenderFreshness, Vec<u8>)>, IncrementalRendererError> {
+        if let Some(file_path) = self.find_file(route) {
+            if let Some(freshness) = file_path.freshness(self.invalidate_after) {
+                if let Ok(file) = std::fs::File::open(file_path.full_path) {
+                    let mut file = std::io::BufReader::new(file);
+                    let mut cache_hit = Vec::new();
+                    std::io::copy(&mut file, &mut cache_hit)?;
+                    tracing::trace!("file cache hit {:?}", route);
+                    return Ok(Some((freshness, cache_hit)));
+                }
+            }
+        }
+
+        Ok(None)
+    }
+
+    fn find_file(&self, route: &str) -> Option<ValidCachedPath> {
+        let mut file_path = (self.map_path)(route);
+        if let Some(deadline) = self.invalidate_after {
+            // find the first file that matches the route and is a html file
+            file_path.push("index");
+            if let Ok(dir) = std::fs::read_dir(file_path) {
+                for entry in dir.flatten() {
+                    if let Some(cached_path) = ValidCachedPath::try_from_path(entry.path()) {
+                        if let Ok(elapsed) = cached_path.timestamp.elapsed() {
+                            if elapsed < deadline {
+                                // The timestamp is valid, return the file
+                                return Some(cached_path);
+                            }
+                        }
+                        // if the timestamp is invalid or passed, delete the file
+                        if let Err(err) = std::fs::remove_file(entry.path()) {
+                            tracing::error!("Failed to remove file: {}", err);
+                        }
+                    }
+                }
+                None
+            } else {
+                None
+            }
+        } else {
+            file_path.push("index.html");
+            file_path.exists().then_some({
+                ValidCachedPath {
+                    full_path: file_path,
+                    timestamp: SystemTime::now(),
+                }
+            })
+        }
+    }
+
+    fn route_as_path(&self, route: &str, timestamp: DateTime<Utc>) -> PathBuf {
+        let mut file_path = (self.map_path)(route);
+        if self.track_timestamps() {
+            file_path.push("index");
+            file_path.push(timestamp_to_string(timestamp));
+        } else {
+            file_path.push("index");
+        }
+        file_path.set_extension("html");
+        file_path
+    }
+
+    fn track_timestamps(&self) -> bool {
+        self.invalidate_after.is_some()
+    }
+}
+
+pub(crate) struct ValidCachedPath {
+    pub(crate) full_path: PathBuf,
+    pub(crate) timestamp: std::time::SystemTime,
+}
+
+impl ValidCachedPath {
+    pub fn try_from_path(value: PathBuf) -> Option<Self> {
+        if value.extension() != Some(std::ffi::OsStr::new("html")) {
+            return None;
+        }
+        let timestamp = decode_timestamp(value.file_stem()?.to_str()?)?;
+        let full_path = value;
+        Some(Self {
+            full_path,
+            timestamp,
+        })
+    }
+
+    pub fn freshness(&self, max_age: Option<std::time::Duration>) -> Option<RenderFreshness> {
+        let age = self.timestamp.elapsed().ok()?.as_secs();
+        let max_age = max_age.map(|max_age| max_age.as_secs());
+        Some(RenderFreshness::new(age, max_age?, self.timestamp.into()))
+    }
+}
+
+fn decode_timestamp(timestamp: &str) -> Option<std::time::SystemTime> {
+    let timestamp = u64::from_str_radix(timestamp, 16).ok()?;
+    Some(std::time::UNIX_EPOCH + std::time::Duration::from_secs(timestamp))
+}
+
+pub(crate) fn timestamp_to_string(timestamp: DateTime<Utc>) -> String {
+    let timestamp = timestamp
+        .signed_duration_since(DateTime::<Utc>::from(std::time::UNIX_EPOCH))
+        .num_seconds();
+    format!("{:x}", timestamp)
+}

packages/fullstack-server/src/isrg/memory_cache.rs

@@ -0,0 +1,89 @@
+//! Incremental file based incremental rendering
+
+#![allow(non_snake_case)]
+
+use chrono::offset::Utc;
+use chrono::DateTime;
+use rustc_hash::FxHasher;
+use std::{hash::BuildHasherDefault, num::NonZeroUsize};
+
+use super::freshness::RenderFreshness;
+
+pub(crate) struct InMemoryCache {
+    #[allow(clippy::type_complexity)]
+    lru: Option<lru::LruCache<String, (DateTime<Utc>, Vec<u8>), BuildHasherDefault<FxHasher>>>,
+    invalidate_after: Option<std::time::Duration>,
+}
+
+impl InMemoryCache {
+    pub fn new(memory_cache_limit: usize, invalidate_after: Option<std::time::Duration>) -> Self {
+        Self {
+            lru: NonZeroUsize::new(memory_cache_limit)
+                .map(|limit| lru::LruCache::with_hasher(limit, Default::default())),
+            invalidate_after,
+        }
+    }
+
+    pub fn clear(&mut self) {
+        if let Some(cache) = &mut self.lru {
+            cache.clear();
+        }
+    }
+
+    pub fn put(&mut self, route: String, timestamp: DateTime<Utc>, data: Vec<u8>) {
+        if let Some(cache) = &mut self.lru {
+            cache.put(route, (timestamp, data));
+        }
+    }
+
+    pub fn invalidate(&mut self, route: &str) {
+        if let Some(cache) = &mut self.lru {
+            cache.pop(route);
+        }
+    }
+
+    pub fn try_get_or_insert<'a, F: FnOnce() -> Result<(DateTime<Utc>, Vec<u8>), E>, E>(
+        &'a mut self,
+        route: &str,
+        or_insert: F,
+    ) -> Result<Option<(RenderFreshness, &'a [u8])>, E> {
+        if let Some(memory_cache) = self.lru.as_mut() {
+            let (timestamp, _) = memory_cache.try_get_or_insert(route.to_string(), or_insert)?;
+
+            let now = Utc::now();
+            let elapsed = timestamp.signed_duration_since(now);
+            let age = elapsed.num_seconds();
+            // The cache entry is out of date, so we need to remove it.
+            if let Some(invalidate_after) = self.invalidate_after {
+                // If we can't convert to a std duration, the duration is negative and hasn't elapsed yet.
+                if let Ok(std_elapsed) = elapsed.to_std() {
+                    if std_elapsed > invalidate_after {
+                        tracing::trace!("memory cache out of date");
+                        memory_cache.pop(route);
+                        return Ok(None);
+                    }
+                }
+            }
+
+            // We need to reborrow because we may have invalidated the lifetime if the route was removed.
+            // We know it wasn't because we returned... but rust doesn't understand that.
+            let (timestamp, cache_hit) = memory_cache.get(route).unwrap();
+
+            return match self.invalidate_after {
+                Some(invalidate_after) => {
+                    tracing::trace!("memory cache hit");
+                    let max_age = invalidate_after.as_secs();
+                    let freshness = RenderFreshness::new(age as u64, max_age, *timestamp);
+                    Ok(Some((freshness, cache_hit)))
+                }
+                None => {
+                    tracing::trace!("memory cache hit");
+                    let freshness = RenderFreshness::new_age(age as u64, *timestamp);
+                    Ok(Some((freshness, cache_hit)))
+                }
+            };
+        }
+
+        Ok(None)
+    }
+}

packages/fullstack-server/src/isrg/mod.rs

@@ -0,0 +1,164 @@
+//! Incremental file based incremental rendering
+
+#![allow(non_snake_case)]
+
+mod config;
+mod freshness;
+#[cfg(not(target_arch = "wasm32"))]
+mod fs_cache;
+mod memory_cache;
+
+use std::time::Duration;
+
+use chrono::Utc;
+pub use config::*;
+pub use freshness::*;
+
+use self::memory_cache::InMemoryCache;
+
+/// A render that was cached from a previous render.
+pub struct CachedRender<'a> {
+    /// The route that was rendered
+    pub route: String,
+    /// The freshness information for the rendered response
+    pub freshness: RenderFreshness,
+    /// The rendered response
+    pub response: &'a [u8],
+}
+
+/// An incremental renderer.
+pub struct IncrementalRenderer {
+    pub(crate) memory_cache: InMemoryCache,
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) file_system_cache: fs_cache::FileSystemCache,
+    invalidate_after: Option<Duration>,
+}
+
+impl IncrementalRenderer {
+    /// Create a new incremental renderer builder.
+    pub fn builder() -> IncrementalRendererConfig {
+        IncrementalRendererConfig::new()
+    }
+
+    /// Remove a route from the cache.
+    pub fn invalidate(&mut self, route: &str) {
+        self.memory_cache.invalidate(route);
+        #[cfg(not(target_arch = "wasm32"))]
+        self.file_system_cache.invalidate(route);
+    }
+
+    /// Remove all routes from the cache.
+    pub fn invalidate_all(&mut self) {
+        self.memory_cache.clear();
+        #[cfg(not(target_arch = "wasm32"))]
+        self.file_system_cache.clear();
+    }
+
+    /// Cache a rendered response.
+    ///
+    /// ```rust
+    /// # use dioxus_server::IncrementalRenderer;
+    /// # let mut renderer = IncrementalRenderer::builder().build();
+    /// let route = "/index".to_string();
+    /// let response = b"<html><body>Hello world</body></html>";
+    /// renderer.cache(route, response).unwrap();
+    /// ```
+    pub fn cache(
+        &mut self,
+        route: String,
+        html: impl Into<Vec<u8>>,
+    ) -> Result<RenderFreshness, IncrementalRendererError> {
+        let timestamp = Utc::now();
+        let html = html.into();
+        #[cfg(not(target_arch = "wasm32"))]
+        self.file_system_cache
+            .put(route.clone(), timestamp, html.clone())?;
+        self.memory_cache.put(route, timestamp, html);
+        Ok(RenderFreshness::created_at(
+            timestamp,
+            self.invalidate_after,
+        ))
+    }
+
+    /// Try to get a cached response for a route.
+    ///
+    /// ```rust
+    /// # use dioxus_server::IncrementalRenderer;
+    /// # let mut renderer = IncrementalRenderer::builder().build();
+    /// # let route = "/index".to_string();
+    /// # let response = b"<html><body>Hello world</body></html>";
+    /// # renderer.cache(route, response).unwrap();
+    /// let route = "/index";
+    /// let response = renderer.get(route).unwrap();
+    /// assert_eq!(response.unwrap().response, b"<html><body>Hello world</body></html>");
+    /// ```
+    ///
+    /// If the route is not cached, `None` is returned.
+    ///
+    /// ```rust
+    /// # use dioxus_server::IncrementalRenderer;
+    /// # let mut renderer = IncrementalRenderer::builder().build();
+    /// let route = "/index";
+    /// let response = renderer.get(route).unwrap();
+    /// assert!(response.is_none());
+    /// ```
+    pub fn get<'a>(
+        &'a mut self,
+        route: &str,
+    ) -> Result<Option<CachedRender<'a>>, IncrementalRendererError> {
+        let Self {
+            memory_cache,
+            #[cfg(not(target_arch = "wasm32"))]
+            file_system_cache,
+            ..
+        } = self;
+
+        #[allow(unused)]
+        enum FsGetError {
+            NotPresent,
+            Error(IncrementalRendererError),
+        }
+
+        // The borrow checker prevents us from simply using a match/if and returning early. Instead we need to use the more complex closure API
+        // non lexical lifetimes will make this possible (it works with polonius)
+        let or_insert = || {
+            // check the file cache
+            #[cfg(not(target_arch = "wasm32"))]
+            return match file_system_cache.get(route) {
+                Ok(Some((freshness, bytes))) => Ok((freshness.timestamp(), bytes)),
+                Ok(None) => Err(FsGetError::NotPresent),
+                Err(e) => Err(FsGetError::Error(e)),
+            };
+
+            #[allow(unreachable_code)]
+            Err(FsGetError::NotPresent)
+        };
+
+        match memory_cache.try_get_or_insert(route, or_insert) {
+            Ok(Some((freshness, bytes))) => Ok(Some(CachedRender {
+                route: route.to_string(),
+                freshness,
+                response: bytes,
+            })),
+            Err(FsGetError::NotPresent) | Ok(None) => Ok(None),
+            Err(FsGetError::Error(e)) => Err(e),
+        }
+    }
+}
+
+/// An error that can occur while rendering a route or retrieving a cached route.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum IncrementalRendererError {
+    /// An formatting error occurred while rendering a route.
+    #[error("RenderError: {0}")]
+    RenderError(#[from] std::fmt::Error),
+
+    /// An IO error occurred while rendering a route.
+    #[error("IoError: {0}")]
+    IoError(#[from] std::io::Error),
+
+    /// An error occurred while rendering a route.
+    #[error("Unknown error: {0}")]
+    Other(#[from] dioxus_core::CapturedError),
+}