phantom_frame/
lib.rs

1#[cfg(all(feature = "native-tls", feature = "rustls"))]
2compile_error!("Features `native-tls` and `rustls` are mutually exclusive — enable only one.");
3
4pub mod cache;
5pub mod compression;
6pub mod config;
7pub mod control;
8pub mod path_matcher;
9pub mod proxy;
10
11use axum::{extract::Extension, Router};
12use cache::{CacheHandle, CacheStore};
13use proxy::ProxyState;
14use serde::{Deserialize, Serialize};
15use std::path::PathBuf;
16use std::sync::Arc;
17use tokio::sync::mpsc;
18
19/// Controls which backend responses are eligible for caching.
20#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum CacheStrategy {
23    /// Cache every response that passes the existing path and method filters.
24    #[default]
25    All,
26    /// Disable caching entirely, including 404 cache entries.
27    None,
28    /// Cache HTML documents only.
29    OnlyHtml,
30    /// Cache everything except image responses.
31    NoImages,
32    /// Cache image responses only.
33    OnlyImages,
34    /// Cache non-HTML static/application assets.
35    OnlyAssets,
36}
37
38impl CacheStrategy {
39    /// Check whether a response with the given content type can be cached.
40    pub fn allows_content_type(&self, content_type: Option<&str>) -> bool {
41        let content_type = content_type
42            .and_then(|value| value.split(';').next())
43            .map(|value| value.trim().to_ascii_lowercase());
44
45        match self {
46            Self::All => true,
47            Self::None => false,
48            Self::OnlyHtml => content_type
49                .as_deref()
50                .is_some_and(|value| value == "text/html" || value == "application/xhtml+xml"),
51            Self::NoImages => !content_type
52                .as_deref()
53                .is_some_and(|value| value.starts_with("image/")),
54            Self::OnlyImages => content_type
55                .as_deref()
56                .is_some_and(|value| value.starts_with("image/")),
57            Self::OnlyAssets => content_type.as_deref().is_some_and(|value| {
58                value.starts_with("image/")
59                    || value.starts_with("font/")
60                    || value == "text/css"
61                    || value == "text/javascript"
62                    || value == "application/javascript"
63                    || value == "application/x-javascript"
64                    || value == "application/json"
65                    || value == "application/manifest+json"
66                    || value == "application/wasm"
67                    || value == "application/xml"
68                    || value == "text/xml"
69            }),
70        }
71    }
72}
73
74impl std::fmt::Display for CacheStrategy {
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        let value = match self {
77            Self::All => "all",
78            Self::None => "none",
79            Self::OnlyHtml => "only_html",
80            Self::NoImages => "no_images",
81            Self::OnlyImages => "only_images",
82            Self::OnlyAssets => "only_assets",
83        };
84
85        f.write_str(value)
86    }
87}
88
89/// Controls how cacheable responses are stored in memory.
90#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
91#[serde(rename_all = "snake_case")]
92pub enum CompressStrategy {
93    /// Store cache entries without additional compression.
94    None,
95    /// Store cache entries with Brotli compression.
96    #[default]
97    Brotli,
98    /// Store cache entries with gzip compression.
99    Gzip,
100    /// Store cache entries with deflate compression.
101    Deflate,
102}
103
104impl std::fmt::Display for CompressStrategy {
105    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
106        let value = match self {
107            Self::None => "none",
108            Self::Brotli => "brotli",
109            Self::Gzip => "gzip",
110            Self::Deflate => "deflate",
111        };
112
113        f.write_str(value)
114    }
115}
116
117/// Controls where cached response bodies are stored.
118#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
119#[serde(rename_all = "snake_case")]
120pub enum CacheStorageMode {
121    /// Keep cached bodies in process memory.
122    #[default]
123    Memory,
124    /// Persist cached bodies to the filesystem and load them on cache hits.
125    Filesystem,
126}
127
128impl std::fmt::Display for CacheStorageMode {
129    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
130        let value = match self {
131            Self::Memory => "memory",
132            Self::Filesystem => "filesystem",
133        };
134
135        f.write_str(value)
136    }
137}
138
139/// The type of a webhook — controls whether the webhook gates access or just receives a notification.
140#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
141#[serde(rename_all = "snake_case")]
142pub enum WebhookType {
143    /// The webhook call must complete with a 2xx response before the request is forwarded.
144    /// A non-2xx response (or a timeout / network error) causes the request to be denied.
145    /// A 3xx response is forwarded to the client as a redirect with the `Location` header intact.
146    Blocking,
147    /// The webhook call is dispatched in the background without blocking the request.
148    #[default]
149    Notify,
150    /// The webhook response body (plain text) is used as the cache key for this request.
151    /// On failure, a non-2xx response, or an empty body, the default cache key is used instead.
152    /// Works in both Dynamic and PreGenerate modes.
153    CacheKey,
154}
155
156/// Configuration for a single webhook attached to a server.
157#[derive(Clone, Debug, Serialize, Deserialize)]
158pub struct WebhookConfig {
159    /// The URL to POST the request metadata to.
160    pub url: String,
161
162    /// Whether this webhook is blocking (gates access) or notify (fire-and-forget).
163    #[serde(rename = "type", default)]
164    pub webhook_type: WebhookType,
165
166    /// Timeout in milliseconds for the webhook call (default: 5000 ms).
167    /// On timeout, a blocking webhook denies the request with 503.
168    #[serde(default)]
169    pub timeout_ms: Option<u64>,
170}
171
172/// Controls the operating mode of the proxy.
173#[derive(Clone, Debug, Default)]
174pub enum ProxyMode {
175    /// Dynamic mode: every request is served from cache when available, or
176    /// forwarded to the upstream backend on a cache miss (default).
177    #[default]
178    Dynamic,
179    /// Pre-generate (SSG) mode: a fixed list of `paths` is fetched from the
180    /// upstream server at startup and served exclusively from the cache.
181    ///
182    /// On a cache miss:
183    /// - `fallthrough = false` (default): return 404 immediately.
184    /// - `fallthrough = true`: fall through to the upstream backend.
185    ///
186    /// Use the [`CacheHandle`] returned by [`create_proxy`] to manage snapshots
187    /// at runtime via `add_snapshot`, `refresh_snapshot`, `remove_snapshot`, and
188    /// `refresh_all_snapshots`.
189    PreGenerate {
190        /// The paths to pre-generate at startup (e.g. `"/book/1"`).
191        paths: Vec<String>,
192        /// When `true`, cache misses fall through to the upstream backend.
193        /// Defaults to `false`.
194        fallthrough: bool,
195    },
196}
197
198/// Information about an incoming request for cache key generation
199#[derive(Clone, Debug)]
200pub struct RequestInfo<'a> {
201    /// HTTP method (e.g., "GET", "POST", "PUT", "DELETE")
202    pub method: &'a str,
203    /// Request path (e.g., "/api/users")
204    pub path: &'a str,
205    /// Query string (e.g., "id=123&sort=asc")
206    pub query: &'a str,
207    /// Request headers (for custom cache key logic based on headers)
208    pub headers: &'a axum::http::HeaderMap,
209}
210
211/// Configuration for creating a proxy
212#[derive(Clone)]
213pub struct CreateProxyConfig {
214    /// The backend URL to proxy requests to
215    pub proxy_url: String,
216
217    /// Paths to include in caching (empty means include all)
218    /// Supports wildcards and method prefixes: "/api/*", "POST /api/*", "GET /*/users", etc.
219    pub include_paths: Vec<String>,
220
221    /// Paths to exclude from caching (empty means exclude none)
222    /// Supports wildcards and method prefixes: "/admin/*", "POST *", "PUT /api/*", etc.
223    /// Exclude overrides include
224    pub exclude_paths: Vec<String>,
225
226    /// Enable WebSocket and protocol upgrade support (default: true)
227    /// When enabled, requests with Connection: Upgrade headers will bypass
228    /// the cache and establish a direct bidirectional TCP tunnel
229    pub enable_websocket: bool,
230
231    /// Only allow GET requests, reject all others (default: false)
232    /// When true, only GET requests are processed; POST, PUT, DELETE, etc. return 405 Method Not Allowed
233    /// Useful for static site prerendering where mutations shouldn't be allowed
234    pub forward_get_only: bool,
235
236    /// Custom cache key generator
237    /// Takes request info and returns a cache key
238    /// Default: method + path + query string
239    pub cache_key_fn: Arc<dyn Fn(&RequestInfo) -> String + Send + Sync>,
240    /// Capacity for special 404 cache. When 0, 404 caching is disabled.
241    pub cache_404_capacity: usize,
242
243    /// When true, treat a response containing the meta tag `<meta name="phantom-404" content="true">` as a 404
244    /// This is an optional performance-affecting fallback to detect framework-generated 404 pages.
245    pub use_404_meta: bool,
246
247    /// Controls which responses should be cached after the backend responds.
248    pub cache_strategy: CacheStrategy,
249
250    /// Controls how cached bodies are stored in memory.
251    pub compress_strategy: CompressStrategy,
252
253    /// Controls where cached response bodies are stored.
254    pub cache_storage_mode: CacheStorageMode,
255
256    /// Optional override for filesystem-backed cache bodies.
257    pub cache_directory: Option<PathBuf>,
258
259    /// Controls the operating mode of the proxy (Dynamic vs PreGenerate/SSG).
260    pub proxy_mode: ProxyMode,
261
262    /// Webhooks called for every request before cache reads.
263    /// Blocking webhooks gate access; notify webhooks are fire-and-forget.
264    pub webhooks: Vec<WebhookConfig>,
265}
266
267impl CreateProxyConfig {
268    /// Create a new config with default settings
269    pub fn new(proxy_url: String) -> Self {
270        Self {
271            proxy_url,
272            include_paths: vec![],
273            exclude_paths: vec![],
274            enable_websocket: true,
275            forward_get_only: false,
276            cache_key_fn: Arc::new(|req_info| {
277                if req_info.query.is_empty() {
278                    format!("{}:{}", req_info.method, req_info.path)
279                } else {
280                    format!("{}:{}?{}", req_info.method, req_info.path, req_info.query)
281                }
282            }),
283            cache_404_capacity: 100,
284            use_404_meta: false,
285            cache_strategy: CacheStrategy::All,
286            compress_strategy: CompressStrategy::Brotli,
287            cache_storage_mode: CacheStorageMode::Memory,
288            cache_directory: None,
289            proxy_mode: ProxyMode::Dynamic,
290            webhooks: vec![],
291        }
292    }
293
294    /// Set include paths
295    pub fn with_include_paths(mut self, paths: Vec<String>) -> Self {
296        self.include_paths = paths;
297        self
298    }
299
300    /// Set exclude paths
301    pub fn with_exclude_paths(mut self, paths: Vec<String>) -> Self {
302        self.exclude_paths = paths;
303        self
304    }
305
306    /// Enable or disable WebSocket and protocol upgrade support
307    pub fn with_websocket_enabled(mut self, enabled: bool) -> Self {
308        self.enable_websocket = enabled;
309        self
310    }
311
312    /// Only allow GET requests, reject all others
313    pub fn with_forward_get_only(mut self, enabled: bool) -> Self {
314        self.forward_get_only = enabled;
315        self
316    }
317
318    /// Set custom cache key function
319    pub fn with_cache_key_fn<F>(mut self, f: F) -> Self
320    where
321        F: Fn(&RequestInfo) -> String + Send + Sync + 'static,
322    {
323        self.cache_key_fn = Arc::new(f);
324        self
325    }
326
327    /// Set 404 cache capacity. When 0, 404 caching is disabled.
328    pub fn with_cache_404_capacity(mut self, capacity: usize) -> Self {
329        self.cache_404_capacity = capacity;
330        self
331    }
332
333    /// Treat pages that include the special meta tag as 404 pages
334    pub fn with_use_404_meta(mut self, enabled: bool) -> Self {
335        self.use_404_meta = enabled;
336        self
337    }
338
339    /// Set the cache strategy used to decide which response types are stored.
340    pub fn with_cache_strategy(mut self, strategy: CacheStrategy) -> Self {
341        self.cache_strategy = strategy;
342        self
343    }
344
345    /// Alias for callers that prefer a more fluent builder name.
346    pub fn caching_strategy(self, strategy: CacheStrategy) -> Self {
347        self.with_cache_strategy(strategy)
348    }
349
350    /// Set the compression strategy used for stored cache entries.
351    pub fn with_compress_strategy(mut self, strategy: CompressStrategy) -> Self {
352        self.compress_strategy = strategy;
353        self
354    }
355
356    /// Alias for callers that prefer a more fluent builder name.
357    pub fn compression_strategy(self, strategy: CompressStrategy) -> Self {
358        self.with_compress_strategy(strategy)
359    }
360
361    /// Set the backing store for cached response bodies.
362    pub fn with_cache_storage_mode(mut self, mode: CacheStorageMode) -> Self {
363        self.cache_storage_mode = mode;
364        self
365    }
366
367    /// Set the filesystem directory used for disk-backed cache bodies.
368    pub fn with_cache_directory(mut self, directory: impl Into<PathBuf>) -> Self {
369        self.cache_directory = Some(directory.into());
370        self
371    }
372
373    /// Set the proxy operating mode.
374    /// Use `ProxyMode::PreGenerate { paths, fallthrough }` to enable SSG mode.
375    pub fn with_proxy_mode(mut self, mode: ProxyMode) -> Self {
376        self.proxy_mode = mode;
377        self
378    }
379
380    /// Set the webhooks for this server.
381    /// Blocking webhooks gate access; notify webhooks are fire-and-forget.
382    pub fn with_webhooks(mut self, webhooks: Vec<WebhookConfig>) -> Self {
383        self.webhooks = webhooks;
384        self
385    }
386}
387
388/// The main library interface for using phantom-frame as a library
389/// Returns a proxy handler function and a cache handle
390pub fn create_proxy(config: CreateProxyConfig) -> (Router, CacheHandle) {
391    let upstream_client =
392        proxy::build_upstream_client().expect("failed to build shared upstream HTTP client");
393    let webhook_client =
394        proxy::build_webhook_client().expect("failed to build shared webhook HTTP client");
395
396    // In PreGenerate mode, create a channel for the snapshot worker
397    let (handle, snapshot_rx) = if let ProxyMode::PreGenerate { .. } = &config.proxy_mode {
398        let (tx, rx) = mpsc::channel(32);
399        (CacheHandle::new_with_snapshots(tx), Some(rx))
400    } else {
401        (CacheHandle::new(), None)
402    };
403
404    let cache = CacheStore::with_storage(
405        handle.clone(),
406        config.cache_404_capacity,
407        config.cache_storage_mode.clone(),
408        config.cache_directory.clone(),
409    );
410
411    // Spawn background task to listen for invalidation events
412    spawn_invalidation_listener(cache.clone());
413
414    // Spawn snapshot worker (warm-up + runtime snapshot management) in PreGenerate mode
415    if let (Some(rx), ProxyMode::PreGenerate { paths, .. }) = (snapshot_rx, &config.proxy_mode) {
416        let worker = SnapshotWorker {
417            rx,
418            cache: cache.clone(),
419            upstream_client: upstream_client.clone(),
420            proxy_url: config.proxy_url.clone(),
421            compress_strategy: config.compress_strategy.clone(),
422            cache_key_fn: config.cache_key_fn.clone(),
423            snapshots: paths.clone(),
424        };
425        tokio::spawn(worker.run());
426    }
427
428    let proxy_state = Arc::new(ProxyState::new(
429        cache,
430        config,
431        upstream_client,
432        webhook_client,
433    ));
434
435    let app = Router::new()
436        .fallback(proxy::proxy_handler)
437        .layer(Extension(proxy_state));
438
439    (app, handle)
440}
441
442/// Create a proxy handler with an existing cache handle.
443/// Useful for sharing a single handle across multiple proxy instances so that
444/// invalidation propagates to all caches simultaneously.
445///
446/// Note: snapshot operations (PreGenerate mode warm-up) are not available
447/// through this variant — use [`create_proxy`] for full PreGenerate support.
448pub fn create_proxy_with_handle(config: CreateProxyConfig, handle: CacheHandle) -> Router {
449    let upstream_client =
450        proxy::build_upstream_client().expect("failed to build shared upstream HTTP client");
451    let webhook_client =
452        proxy::build_webhook_client().expect("failed to build shared webhook HTTP client");
453
454    let cache = CacheStore::with_storage(
455        handle,
456        config.cache_404_capacity,
457        config.cache_storage_mode.clone(),
458        config.cache_directory.clone(),
459    );
460
461    // Spawn background task to listen for invalidation events
462    spawn_invalidation_listener(cache.clone());
463
464    let proxy_state = Arc::new(ProxyState::new(
465        cache,
466        config,
467        upstream_client,
468        webhook_client,
469    ));
470
471    Router::new()
472        .fallback(proxy::proxy_handler)
473        .layer(Extension(proxy_state))
474}
475
476/// Spawn a background task to listen for cache invalidation events.
477fn spawn_invalidation_listener(cache: CacheStore) {
478    let mut receiver = cache.handle().subscribe();
479
480    tokio::spawn(async move {
481        loop {
482            match receiver.recv().await {
483                Ok(cache::InvalidationMessage::All) => {
484                    tracing::debug!("Cache invalidation triggered: clearing all entries");
485                    cache.clear().await;
486                }
487                Ok(cache::InvalidationMessage::Pattern(pattern)) => {
488                    tracing::debug!(
489                        "Cache invalidation triggered: clearing entries matching pattern '{}'",
490                        pattern
491                    );
492                    cache.clear_by_pattern(&pattern).await;
493                }
494                Err(e) => {
495                    tracing::error!("Invalidation channel error: {}", e);
496                    break;
497                }
498            }
499        }
500    });
501}
502
503/// Background worker that handles snapshot warm-up and runtime snapshot operations
504/// for `ProxyMode::PreGenerate`.
505struct SnapshotWorker {
506    rx: mpsc::Receiver<cache::SnapshotRequest>,
507    cache: CacheStore,
508    upstream_client: reqwest::Client,
509    proxy_url: String,
510    compress_strategy: CompressStrategy,
511    cache_key_fn: Arc<dyn Fn(&RequestInfo) -> String + Send + Sync>,
512    /// Current snapshot list — grows/shrinks via add/remove operations.
513    snapshots: Vec<String>,
514}
515
516impl SnapshotWorker {
517    async fn run(mut self) {
518        // Warm-up: pre-generate all initial snapshot paths before handling requests.
519        let initial = self.snapshots.clone();
520        for path in &initial {
521            if let Err(e) = self.fetch_and_store(path).await {
522                tracing::warn!("Failed to pre-generate snapshot '{}': {}", path, e);
523            }
524        }
525
526        // Process runtime snapshot requests.
527        while let Some(req) = self.rx.recv().await {
528            match req.op {
529                cache::SnapshotOp::Add(path) => match self.fetch_and_store(&path).await {
530                    Ok(()) => self.snapshots.push(path),
531                    Err(e) => tracing::warn!("add_snapshot '{}' failed: {}", path, e),
532                },
533                cache::SnapshotOp::Refresh(path) => {
534                    if let Err(e) = self.fetch_and_store(&path).await {
535                        tracing::warn!("refresh_snapshot '{}' failed: {}", path, e);
536                    }
537                }
538                cache::SnapshotOp::Remove(path) => {
539                    let empty_headers = axum::http::HeaderMap::new();
540                    let req_info = RequestInfo {
541                        method: "GET",
542                        path: &path,
543                        query: "",
544                        headers: &empty_headers,
545                    };
546                    let key = (self.cache_key_fn)(&req_info);
547                    self.cache.clear_by_pattern(&key).await;
548                    self.snapshots.retain(|s| s != &path);
549                }
550                cache::SnapshotOp::RefreshAll => {
551                    let paths: Vec<String> = self.snapshots.clone();
552                    for path in &paths {
553                        if let Err(e) = self.fetch_and_store(path).await {
554                            tracing::warn!("refresh_all_snapshots '{}' failed: {}", path, e);
555                        }
556                    }
557                }
558            }
559            // Signal completion to the caller.
560            let _ = req.done.send(());
561        }
562    }
563
564    async fn fetch_and_store(&self, path: &str) -> anyhow::Result<()> {
565        proxy::fetch_and_cache_snapshot(
566            path,
567            &self.upstream_client,
568            &self.proxy_url,
569            &self.cache,
570            &self.compress_strategy,
571            &self.cache_key_fn,
572        )
573        .await
574    }
575}
576
577#[cfg(test)]
578mod tests {
579    use super::*;
580
581    #[test]
582    fn test_cache_strategy_content_types() {
583        assert!(CacheStrategy::All.allows_content_type(None));
584        assert!(!CacheStrategy::None.allows_content_type(Some("text/html")));
585        assert!(CacheStrategy::OnlyHtml.allows_content_type(Some("text/html; charset=utf-8")));
586        assert!(!CacheStrategy::OnlyHtml.allows_content_type(Some("image/png")));
587        assert!(CacheStrategy::NoImages.allows_content_type(Some("text/css")));
588        assert!(!CacheStrategy::NoImages.allows_content_type(Some("image/webp")));
589        assert!(CacheStrategy::OnlyImages.allows_content_type(Some("image/svg+xml")));
590        assert!(!CacheStrategy::OnlyImages.allows_content_type(Some("application/javascript")));
591        assert!(CacheStrategy::OnlyAssets.allows_content_type(Some("application/javascript")));
592        assert!(CacheStrategy::OnlyAssets.allows_content_type(Some("image/png")));
593        assert!(!CacheStrategy::OnlyAssets.allows_content_type(Some("text/html")));
594        assert!(!CacheStrategy::OnlyAssets.allows_content_type(None));
595    }
596
597    #[test]
598    fn test_compress_strategy_display() {
599        assert_eq!(CompressStrategy::default().to_string(), "brotli");
600        assert_eq!(CompressStrategy::None.to_string(), "none");
601        assert_eq!(CompressStrategy::Gzip.to_string(), "gzip");
602        assert_eq!(CompressStrategy::Deflate.to_string(), "deflate");
603    }
604
605    #[tokio::test]
606    async fn test_create_proxy() {
607        let config = CreateProxyConfig::new("http://localhost:8080".to_string());
608        assert_eq!(config.compress_strategy, CompressStrategy::Brotli);
609        let (_app, handle) = create_proxy(config);
610        handle.invalidate_all();
611        handle.invalidate("GET:/api/*");
612        // Just ensure it compiles and runs without panic
613    }
614}
phantom_frame/lib.rs

phantom_frame/
lib.rs
