ferrum_pdf 0.4.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bb953e452513432ae962fdf430ca58dfda05c95ef099a3a081c280aad8b7013
-  data.tar.gz: 8eea8b0b4b4fdcd2f24c36f7da512742c1d84efca70585cefbc23207e3287a68
+  metadata.gz: a1356ce4acb8121982cca17f42a53f88595cdf6004101d60e4192d912fb6a699
+  data.tar.gz: 12cfdc58b24168b8a45f6239d668ba49f4443ea928b51554189dd565d34c15d8
 SHA512:
-  metadata.gz: b1159b7493ae224c5c2eede63d2d0e4b30b51fb33929572ed1315bc5ca59aa2f39c1778a8a12ddc8df7d7d85e0038961250c0e9073300988055e5d0be032ddfd
-  data.tar.gz: 93823c9ad5df71ffae73925c09af0bed905ec64a6192d249d9d733075e0e92bc7126aede0b952a2293dc708123a6d93c0e9c5f5399954a3bd9baf447815bdc5b
+  metadata.gz: e9078a7f52c54d9aed0b6b2840a136853c306a9f4414f92cc3c6ca5649e68b31ead2798ab9a8ec91848709222e67be188bebc570d72e150e56a1d697e19acedd
+  data.tar.gz: f7947db380dcc18275a9df3a437240d4affe52a4809d7cabdb50a46a34cbf22b93ea67c7278e3cf6a41bf75a7556cf4481f32a5c6e9bc7fd5333a149b52e70d0

data/README.md

@@ -212,21 +212,44 @@ RUN apt-get update && apt-get install gnupg wget -y && \
     rm -rf /var/lib/apt/lists/*
 ```
 
-### Multiple Browser Support
+### Browser Management
+
+FerrumPdf uses a single browser instance per Ruby process that is automatically created when needed using your configuration settings:
+
+```ruby
+# Browser is auto-created on first use
+FerrumPdf.render_pdf(url: "https://example.org")
+```
+
+You can also set a custom browser instance:
 
 ```ruby
-# Create two browsers using the FerrumPdf config, but overriding `window_size`
-FerrumPdf.add_browser(:small, window_size: [1024, 768]))
-FerrumPdf.add_browser(:large, window_size: [1920, 1080]))
+# Set a custom browser with specific options
+custom_browser = Ferrum::Browser.new(window_size: [800, 600], headless: false)
+FerrumPdf.browser = custom_browser
 
-FerrumPdf.render_pdf(url: "https://example.org", browser: :small)
-FerrumPdf.render_pdf(url: "https://example.org", browser: :large)
+# All subsequent calls will use this browser
+FerrumPdf.render_pdf(url: "https://example.org")
 ```
 
-You can also create a `Ferrum::Browser` instance and pass it in as `browser`:
+To safely shut down the browser process:
+
+```ruby
+# This will quit the current browser and set it to nil
+FerrumPdf.browser = nil
+
+# Next call will auto-create a new browser
+FerrumPdf.render_pdf(url: "https://example.org")
+```
+
+> [!TIP]
+> **Thread Safety**: FerrumPdf is thread-safe within a single Ruby process. Multiple threads can safely use FerrumPdf concurrently, and they will share the same Chrome browser instance. However, each Ruby worker process will have its own separate Chrome instance.
+
+If you need multiple browsers, you can pass the browser option when rendering:
 
 ```ruby
-FerrumPdf.render_pdf(url: "https://example.org", browser: Ferrum::Browser.new)
+other_browser = Ferrum::Browser.new
+FerrumPdf.render_pdf(url: "https://example.org", browser: other_browser)
 ```
 
 ## Debugging

data/lib/ferrum_pdf/version.rb

@@ -1,3 +1,3 @@
 module FerrumPdf
-  VERSION = "0.4.2"
+  VERSION = "1.0.0"
 end

data/lib/ferrum_pdf.rb

@@ -13,23 +13,43 @@ module FerrumPdf
   autoload :Controller, "ferrum_pdf/controller"
   autoload :HTMLPreprocessor, "ferrum_pdf/html_preprocessor"
 
+  mattr_accessor :browser_mutex, default: Mutex.new
   mattr_accessor :include_assets_helper_module, default: true
   mattr_accessor :include_controller_module, default: true
-  mattr_accessor :browsers, default: {}
   mattr_accessor :config, default: ActiveSupport::OrderedOptions.new.merge(
     window_size: [ 1920, 1080 ]
   )
 
+  # This doesn't use mattr_accessor because having a `.browser` getter and also
+  # having local variables named `browser` would be confusing. For simplicity,
+  # this is explicitly accessed.
+  @@browser = nil
+
   class << self
     def configure
       yield config
     end
 
-    # Creates and registers a new browser for exports
-    # If a browser with the same name already exists, it will be shut down before instantiating the new one
-    def add_browser(name, **options)
-      @@browsers[name].quit if @@browsers[name]
-      @@browsers[name] = Ferrum::Browser.new(@@config.merge(options))
+    # Sets the browser instance to use for all operations
+    # If a browser is already set, it will be shut down before setting the new one
+    def browser=(browser_instance)
+      browser_mutex.synchronize do
+        @@browser&.quit
+        @@browser = browser_instance
+      end
+    end
+
+    # Provides thread-safe access to the browser instance
+    def with_browser(browser = nil)
+      if browser
+        yield browser
+      else
+        browser_mutex.synchronize do
+          @@browser ||= Ferrum::Browser.new(config)
+          @@browser.restart unless @@browser.client.present?
+          yield @@browser
+        end
+      end
     end
 
     # Renders HTML or URL to PDF
@@ -68,36 +88,32 @@ module FerrumPdf
     #
     # This automatically applies HTML preprocessing if `html:` is present
     #
-    def load_page(url: nil, html: nil, base_url: nil, authorize: nil, wait_for_idle_options: nil, browser: :default, retries: 1)
+    def load_page(url: nil, html: nil, base_url: nil, authorize: nil, wait_for_idle_options: nil, browser: nil, retries: 1)
       try = 0
 
-      # Lookup browser if a name was passed
-      browser = @@browsers[browser] || add_browser(browser) if browser.is_a? Symbol
+      with_browser(browser) do |browser|
+        # Closes page automatically after block finishes
+        # https://github.com/rubycdp/ferrum/blob/main/lib/ferrum/browser.rb#L169
+        browser.create_page do |page|
+          page.network.authorize(**authorize) { |req| req.continue } if authorize
 
-      # Automatically restart the browser if it was disconnected
-      browser.restart unless browser.client.present?
+          # Load content
+          if html
+            page.content = FerrumPdf::HTMLPreprocessor.process(html, base_url)
+          else
+            page.go_to(url)
+          end
 
-      # Closes page automatically after block finishes
-      # https://github.com/rubycdp/ferrum/blob/main/lib/ferrum/browser.rb#L169
-      browser.create_page do |page|
-        page.network.authorize(**authorize) { |req| req.continue } if authorize
+          # Wait for everything to load
+          page.network.wait_for_idle(**wait_for_idle_options)
 
-        # Load content
-        if html
-          page.content = FerrumPdf::HTMLPreprocessor.process(html, base_url)
-        else
-          page.go_to(url)
+          yield browser, page
         end
-
-        # Wait for everything to load
-        page.network.wait_for_idle(**wait_for_idle_options)
-
-        yield browser, page
       end
     rescue Ferrum::DeadBrowserError
       try += 1
       if try <= retries
-        browser.restart
+        with_browser(&:restart)
         retry
       else
         raise

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ferrum_pdf
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Chris Oliver
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.0
 specification_version: 4
 summary: PDFs & screenshots for Rails using Ferrum & headless Chrome
 test_files: []