html2pdf-api 0.3.3

Thread-safe headless browser pool for high-performance HTML to PDF conversion with native Rust web framework integration.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Browser factory implementations.
//!
//! This module provides the [`BrowserFactory`] trait and implementations
//! for creating browser instances.
//!
//! # Overview
//!
//! The factory pattern abstracts browser creation, allowing:
//! - Different browser implementations (Chrome, Chromium, etc.)
//! - Custom launch configurations
//! - Mock factories for testing
//!
//! # Available Factories
//!
//! | Factory | Description |
//! |---------|-------------|
//! | [`ChromeBrowserFactory`] | Creates Chrome/Chromium browsers |
//! | [`mock::MockBrowserFactory`] | For testing (feature-gated) |
//!
//! # Example
//!
//! ```rust,ignore
//! use html2pdf_api::{BrowserFactory, ChromeBrowserFactory};
//!
//! // Create factory with auto-detected Chrome
//! let factory = ChromeBrowserFactory::with_defaults();
//!
//! // Create a browser
//! let browser = factory.create()?;
//! ```
//!
//! # Custom Factory
//!
//! You can implement [`BrowserFactory`] for custom browser creation:
//!
//! ```rust,ignore
//! use html2pdf_api::{BrowserFactory, BrowserPoolError, Result};
//! use headless_chrome::Browser;
//!
//! struct MyCustomFactory {
//!     // your configuration
//! }
//!
//! impl BrowserFactory for MyCustomFactory {
//!     fn create(&self) -> Result<Browser> {
//!         // Your custom browser creation logic
//!         todo!()
//!     }
//! }
//! ```

mod chrome;

#[cfg(any(test, feature = "test-utils"))]
pub mod mock;

pub use chrome::{ChromeBrowserFactory, create_chrome_options};

use crate::error::Result;
use headless_chrome::Browser;

/// Trait for browser factory pattern.
///
/// Abstracts browser creation to allow different implementations
/// (Chrome, Firefox, mock browsers for testing, etc.)
///
/// # Thread Safety
///
/// This trait requires `Send + Sync` because factories are shared
/// across threads in the browser pool.
///
/// # Implementors
///
/// - [`ChromeBrowserFactory`] - Creates Chrome/Chromium browsers
/// - [`mock::MockBrowserFactory`] - For testing (when `test-utils` feature enabled)
///
/// # Example
///
/// ```rust,ignore
/// use html2pdf_api::{BrowserFactory, ChromeBrowserFactory};
///
/// fn use_factory(factory: &dyn BrowserFactory) {
///     match factory.create() {
///         Ok(browser) => println!("Browser created!"),
///         Err(e) => eprintln!("Failed: {}", e),
///     }
/// }
///
/// let factory = ChromeBrowserFactory::with_defaults();
/// use_factory(&factory);
/// ```
pub trait BrowserFactory: Send + Sync {
    /// Create a new browser instance.
    ///
    /// # Errors
    ///
    /// Returns error if browser creation fails:
    /// - [`BrowserPoolError::Configuration`](crate::BrowserPoolError::Configuration) -
    ///   Invalid launch options
    /// - [`BrowserPoolError::BrowserCreation`](crate::BrowserPoolError::BrowserCreation) -
    ///   Binary not found, launch fails, etc.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use html2pdf_api::{BrowserFactory, ChromeBrowserFactory};
    ///
    /// let factory = ChromeBrowserFactory::with_defaults();
    /// let browser = factory.create()?;
    /// // Use browser...
    /// ```
    fn create(&self) -> Result<Browser>;
}