Add cache_stale_duration_ms configuration option

Introduces a new configuration option `cache_stale_duration_ms` which
allows users to control how long files are cached before their freshness
is checked. This provides more fine-grained control over caching
behavior, especially in production environments.

Author: lovasoa

CHANGELOG.md

@@ -8,8 +8,9 @@
 - fix: `sqlpage.variables()` now does not return json objects with duplicate keys when post, get and set variables of the same name are present. The semantics of the returned values remains the same (precedence: set > post > get).
 - add support for some duckdb-specific (like `select {'a': 1, 'b': 2}`), and oracle-specific syntax dynamically when connected through odbc.
 - better oidc support. Single-sign-on now works with sites:
-- using a non-default `site_prefix`
-- hosted behind an ssl-terminating reverse proxy
+  - using a non-default `site_prefix`
+  - hosted behind an ssl-terminating reverse proxy
+- New config option: `cache_stale_duration_ms` to control the duration for which cached sql files are considered fresh.
 
 ## 0.41.0 (2025-12-28)
 

configuration.md

@@ -39,6 +39,7 @@ Here are the available configuration options and their default values:
 | `https_certificate_cache_dir`                 | ./sqlpage/https                                             | A writeable directory where to cache the certificates, so that SQLPage can serve https traffic immediately when it restarts.                                                                                                                           |
 | `https_acme_directory_url`                    | https://acme-v02.api.letsencrypt.org/directory              | The URL of the ACME directory to use when requesting a certificate.                                                                                                                                                                                    |
 | `environment`                                 | development                                                 | The environment in which SQLPage is running. Can be either `development` or `production`. In `production` mode, SQLPage will hide error messages and stack traces from the user, and will cache sql files in memory to avoid reloading them from disk. |
+| `cache_stale_duration_ms`                     | 1000 (prod), 0 (dev)                                        | The duration in milliseconds that a file can be cached before its freshness is checked against the filesystem. Defaults to 1000ms (1 second) in production and 0ms in development. |
 | `content_security_policy`                     | `script-src 'self' 'nonce-{NONCE}'`                          | The [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) to set in the HTTP headers. If you get CSP errors in the browser console, you can set this to the empty string to disable CSP. If you want a custom CSP that contains a nonce, include the `'nonce-{NONCE}'` directive in your configuration string and it will be populated with a random value per request.                                                                                                           |
 | `system_root_ca_certificates`                 | false                                                      | Whether to use the system root CA certificates to validate SSL certificates when making http requests with `sqlpage.fetch`. If set to false, SQLPage will use its own set of root CA certificates. If the `SSL_CERT_FILE` or `SSL_CERT_DIR` environment variables are set, they will be used instead of the system root CA certificates. |
 | `max_recursion_depth`                         | 10                                                           | Maximum depth of recursion allowed in the `run_sql` function. Maximum value is 255. |

src/app_config.rs

@@ -305,9 +305,22 @@ pub struct AppConfig {
 
     #[serde(default = "default_markdown_allow_dangerous_protocol")]
     pub markdown_allow_dangerous_protocol: bool,
+
+    pub cache_stale_duration_ms: Option<u64>,
 }
 
 impl AppConfig {
+    #[must_use]
+    pub fn cache_stale_duration_ms(&self) -> u64 {
+        self.cache_stale_duration_ms.unwrap_or_else(|| {
+            if self.environment.is_prod() {
+                1000
+            } else {
+                0
+            }
+        })
+    }
+
     #[must_use]
     pub fn listen_on(&self) -> SocketAddr {
         let mut addr = self.listen_on.unwrap_or_else(|| {

src/file_cache.rs

@@ -15,10 +15,6 @@ use std::sync::Arc;
 use std::time::SystemTime;
 use tokio::sync::RwLock;
 
-/// The maximum time in milliseconds that a file can be cached before its freshness is checked
-/// (in production mode)
-const MAX_STALE_CACHE_MS: u64 = 150;
-
 #[derive(Default)]
 struct Cached<T> {
     last_checked_at: AtomicU64,
@@ -35,34 +31,32 @@ impl<T> Cached<T> {
         s
     }
     fn last_check_time(&self) -> DateTime<Utc> {
-        self.last_checked_at
-            .load(Acquire)
-            .saturating_mul(MAX_STALE_CACHE_MS)
-            .try_into()
-            .ok()
-            .and_then(|millis| Utc.timestamp_millis_opt(millis).single())
+        let millis = self.last_checked_at.load(Acquire);
+        Utc.timestamp_millis_opt(millis as i64)
+            .single()
             .expect("file timestamp out of bound")
     }
     fn update_check_time(&self) {
-        self.last_checked_at.store(Self::elapsed(), Release);
+        self.last_checked_at.store(Self::now_millis(), Release);
     }
-    fn elapsed() -> u64 {
-        let timestamp_millis = (SystemTime::now().duration_since(SystemTime::UNIX_EPOCH))
+    fn now_millis() -> u64 {
+        SystemTime::now()
+            .duration_since(SystemTime::UNIX_EPOCH)
             .expect("invalid duration")
-            .as_millis();
-        let elapsed_intervals = timestamp_millis / u128::from(MAX_STALE_CACHE_MS);
-        u64::try_from(elapsed_intervals).expect("invalid date")
+            .as_millis()
+            .try_into()
+            .expect("invalid date")
     }
-    fn needs_check(&self) -> bool {
+    fn needs_check(&self, stale_cache_duration_ms: u64) -> bool {
         self.last_checked_at
             .load(Acquire)
-            .saturating_add(MAX_STALE_CACHE_MS)
-            < Self::elapsed()
+            .saturating_add(stale_cache_duration_ms)
+            < Self::now_millis()
     }
     /// Creates a new cached entry with the same content but a new check time set to now
     fn make_fresh(&self) -> Self {
         Self {
-            last_checked_at: AtomicU64::from(Self::elapsed()),
+            last_checked_at: AtomicU64::from(Self::now_millis()),
             content: Arc::clone(&self.content),
         }
     }
@@ -126,7 +120,7 @@ impl<T: AsyncFromStrWithState> FileCache<T> {
     ) -> anyhow::Result<Arc<T>> {
         log::trace!("Attempting to get from cache {}", path.display());
         if let Some(cached) = self.cache.read().await.get(path) {
-            if app_state.config.environment.is_prod() && !cached.needs_check() {
+            if !cached.needs_check(app_state.config.cache_stale_duration_ms()) {
                 log::trace!(
                     "Cache answer without filesystem lookup for {}",
                     path.display()
@@ -223,3 +217,26 @@ pub trait AsyncFromStrWithState: Sized {
         source_path: &Path,
     ) -> anyhow::Result<Self>;
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_cache_duration() {
+        let cached = Cached::new(());
+        assert!(
+            !cached.needs_check(1000),
+            "Should not need check immediately after creation"
+        );
+        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+        assert!(
+            !cached.needs_check(1000),
+            "Should not need check before duration expires"
+        );
+        assert!(
+            cached.needs_check(1),
+            "Should need check after duration expires"
+        );
+    }
+}