html2pdf_api/factory/
mod.rs

1//! Browser factory implementations.
2//!
3//! This module provides the [`BrowserFactory`] trait and implementations
4//! for creating browser instances.
5//!
6//! # Overview
7//!
8//! The factory pattern abstracts browser creation, allowing:
9//! - Different browser implementations (Chrome, Chromium, etc.)
10//! - Custom launch configurations
11//! - Mock factories for testing
12//!
13//! # Available Factories
14//!
15//! | Factory | Description |
16//! |---------|-------------|
17//! | [`ChromeBrowserFactory`] | Creates Chrome/Chromium browsers |
18//! | [`mock::MockBrowserFactory`] | For testing (feature-gated) |
19//!
20//! # Example
21//!
22//! ```rust,ignore
23//! use html2pdf_api::{BrowserFactory, ChromeBrowserFactory};
24//!
25//! // Create factory with auto-detected Chrome
26//! let factory = ChromeBrowserFactory::with_defaults();
27//!
28//! // Create a browser
29//! let browser = factory.create()?;
30//! ```
31//!
32//! # Custom Factory
33//!
34//! You can implement [`BrowserFactory`] for custom browser creation:
35//!
36//! ```rust,ignore
37//! use html2pdf_api::{BrowserFactory, BrowserPoolError, Result};
38//! use headless_chrome::Browser;
39//!
40//! struct MyCustomFactory {
41//!     // your configuration
42//! }
43//!
44//! impl BrowserFactory for MyCustomFactory {
45//!     fn create(&self) -> Result<Browser> {
46//!         // Your custom browser creation logic
47//!         todo!()
48//!     }
49//! }
50//! ```
51
52mod chrome;
53
54#[cfg(any(test, feature = "test-utils"))]
55pub mod mock;
56
57pub use chrome::{ChromeBrowserFactory, create_chrome_options};
58
59use crate::error::Result;
60use headless_chrome::Browser;
61
62/// Trait for browser factory pattern.
63///
64/// Abstracts browser creation to allow different implementations
65/// (Chrome, Firefox, mock browsers for testing, etc.)
66///
67/// # Thread Safety
68///
69/// This trait requires `Send + Sync` because factories are shared
70/// across threads in the browser pool.
71///
72/// # Implementors
73///
74/// - [`ChromeBrowserFactory`] - Creates Chrome/Chromium browsers
75/// - [`mock::MockBrowserFactory`] - For testing (when `test-utils` feature enabled)
76///
77/// # Example
78///
79/// ```rust,ignore
80/// use html2pdf_api::{BrowserFactory, ChromeBrowserFactory};
81///
82/// fn use_factory(factory: &dyn BrowserFactory) {
83///     match factory.create() {
84///         Ok(browser) => println!("Browser created!"),
85///         Err(e) => eprintln!("Failed: {}", e),
86///     }
87/// }
88///
89/// let factory = ChromeBrowserFactory::with_defaults();
90/// use_factory(&factory);
91/// ```
92pub trait BrowserFactory: Send + Sync {
93    /// Create a new browser instance.
94    ///
95    /// # Errors
96    ///
97    /// Returns error if browser creation fails:
98    /// - [`BrowserPoolError::Configuration`](crate::BrowserPoolError::Configuration) -
99    ///   Invalid launch options
100    /// - [`BrowserPoolError::BrowserCreation`](crate::BrowserPoolError::BrowserCreation) -
101    ///   Binary not found, launch fails, etc.
102    ///
103    /// # Example
104    ///
105    /// ```rust,ignore
106    /// use html2pdf_api::{BrowserFactory, ChromeBrowserFactory};
107    ///
108    /// let factory = ChromeBrowserFactory::with_defaults();
109    /// let browser = factory.create()?;
110    /// // Use browser...
111    /// ```
112    fn create(&self) -> Result<Browser>;
113}
html2pdf_api/factory/mod.rs

html2pdf_api/factory/
mod.rs
