palapala_pdf 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 717b57250c5722d66ac2310681959abc3ef56498d026b797f13b293077369d2b
-  data.tar.gz: cef8fc4f830a237020cfa6379add09c40da64c818b1758261d560e5ed3482fdc
+  metadata.gz: e06d55c5dca6e14014e1154d4cd4fdcdddcd61844ccd138f38e1d9d803d1094e
+  data.tar.gz: 89ed6d300a9e4c804d3bfcb54516ec921ed741df1718d68b4d160b36e3fd2792
 SHA512:
-  metadata.gz: a31ddde9c4617397ff1a1ae13a708dbe4e54085c5d85043bf149bc602b0d6ebc3c1d9ee87d6fa42077146a159b045e398d599c0d3819b64eaeb4e31081afb0dc
-  data.tar.gz: a064e6622c5eb1737a0baa43a56fff6fd896b69c850b2120a3441b214fd8165ade5988f8bc971a0ddb37a19c900631f6935337e2682a1b8071e5a8c33ecd167c
+  metadata.gz: f0bd26fe4c402e06f1f75ab4a5ccfad05834b78bcb125024967134149b7738b2cbd8121dd985332907644ecfd167f44fc3109b322099ebb9c0e988971f74f42e
+  data.tar.gz: c95f8931ce1538af9b0cb63d93fcc179016cfe05cd4920b7ead1bf6933f4712bfbaee3ae8d243e1112353c1c2b4af875c92b6e1e6373ad219aa0c409f7db117a

data/README.md

@@ -31,49 +31,47 @@ $ gem install palapala_pdf
 ```
 
 Palapala PDF connects to Chrome over a web socket connection.
-An external Chrome/Chromium is expected. Start it with the following
-command (9222 is the default port):
+An external Chrome/Chromium is preferred. Start it with the following
+command (9222 is the default/expected port):
 
 ```sh
 /path/to/chrome --headless --disable-gpu --remote-debugging-port=9222
 ```
 
-### Installing Chrome / Headless Chrome
+### Connecting to Chrome
 
-Seems the august 2024 release 128.0.6613.85 is seriously performance impacted. So to avoid regression issues, it's suggested to install a specific version of Chrome, test it and stick with it.  This is easiest using npx and some tooling provided by Puppeteer. Unfortunately it depends on node/npm, but it's worth it. E.g. install a specific version like this:
+Palapa PDF will go through this process
 
-```
-npx @puppeteer/browsers install chrome@127.0.6533.88
-````
+- check if a Chrome is running and exposing port 9222 (and if so, use it)
+- if `Palapala.headless_chrome_path` is defined, launch Chrome as a child process using that path
+- if **NPX** is avalaillable, install a **Chrome-Headless-Shell** variant locally and launch it as a child process. It will install the 'stable' version or the version identified by `Palapala.chrome_headless_shell_version` setting (or from ENV `CHROME_HEADLESS_SHELL_VERSION`).
+- as a last fallback it will guess a chrome path from the detected OS and try to launch a Chrome with that
 
-This installs chrome in a `chrome` folder in the current working dir and it outputs the path where it's installed when it's finished.
+A Chrome-Headless-Shell version gives the best performance and resource useage
 
-If you installed it using puppeteer from above
+### Installing Chrome / Headless Chrome manually
+
+This is easiest using npx and some tooling provided by Puppeteer. Unfortunately it depends on node/npm, but it's worth it. E.g. install a specific version like this:
 
-```sh
-./chrome/mac_arm-127.0.6533.88/chrome-mac-arm64/Google\ Chrome\ for\ Testing.app/Contents/MacOS/Google\ Chrome\ for\ Testing --headless --disable-gpu --remote-debugging-port=9222
 ```
+npx @puppeteer/browsers install chrome@127.0.6533.88
+````
 
-Currently i'd advise for the `chrome-headless-shell`variant that is a light version meant just for this use case. The chrome-headless-shell is a minimal, headless version of the Chrome browser designed specifically for environments where you need to run Chrome without a graphical user interface (GUI). This is particularly useful in scenarios like server-side rendering, automated testing, web scraping, or any situation where you need the power of the Chrome browser engine without the overhead of displaying a UI. Headless by design, reduced size and overhead but still the same engine.
+This installs chrome in a `chrome` folder in the current working dir and it outputs the path where it's installed when it's finished which then could be started like this
+
+Currently we'd advise for the `chrome-headless-shell` variant that is a light version meant just for this use case. The chrome-headless-shell is a minimal, headless version of the Chrome browser designed specifically for environments where you need to run Chrome without a graphical user interface (GUI). This is particularly useful in scenarios like server-side rendering, automated testing, web scraping, or any situation where you need the power of the Chrome browser engine without the overhead of displaying a UI. Headless by design, reduced size and overhead but still the same engine.
 
 ```
 npx @puppeteer/browsers install chrome-headless-shell@stable
 ```
 
-It installs to a path like this `./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell`. As it's headless by design, it only needs one parameter
+It installs to a path like this `./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell`. As it's headless by design, it only needs one parameter:
 
 ```
 ./chrome-headless-shell/mac_arm-128.0.6613.84/chrome-headless-shell-mac-arm64/chrome-headless-shell --remote-debugging-port=9222
 ```
 
-Alternatively, Palapala PDF will try to launch Chrome as a child process.
-It guesses the path to Chrome, or you configure it like this:
-
-```ruby
-Palapala.setup do |config|
-  config.headless_chrome_path = '/usr/bin/google-chrome-stable' # path to Chrome executable
-end
-```
+*Note: Seems the august 2024 release 128.0.6613.85 is seriously performance impacted. So to avoid regression issues, it's suggested to install a specific version of Chrome, test it and stick with it. The chrome-headless-shell does not seem to suffer from this though.*
 
 ### Installing Node/NPX
 
@@ -92,7 +90,6 @@ nvm --version
 nvm install node
 ````
 
-
 ## Usage Instructions
 
 To create a PDF from HTML content using the `Palapala` library, follow these steps:

data/bin/chrome-headless-server

@@ -1,33 +1,11 @@
 #!/usr/bin/env ruby
 
-require 'open3'
-require 'pathname'
+# $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "palapala"
 
-# Run the command and capture the output
-puts "Installing latest stable chrome-headless-shell..."
-output, status = Open3.capture2('npx --yes @puppeteer/browsers install chrome-headless-shell@stable')
-
-if status.success?
-  # Extract the path from the output
-  result = output.lines.find { |line| line.include?("chrome-headless-shell@") }
-  if result.nil?
-    puts "Failed to install chrome-headless-shell"
-    exit 1
-  end
-  _, chrome_path = result.split(' ', 2).map(&:strip)
-
-  # Directory you want the relative path from (current working directory)
-  base_dir = Dir.pwd
-
-  # Convert absolute path to relative path
-  relative_path = Pathname.new(chrome_path).relative_path_from(Pathname.new(base_dir)).to_s
-
-  puts "Launching chrome-headless-shell at #{relative_path}"
-  # Display the version
-  system("#{chrome_path} --version")
-  # Launch chrome-headless-shell with the --remote-debugging-port parameter
-  exec("#{chrome_path} --remote-debugging-port=9222")
-else
-  puts "Failed to install chrome-headless-shell"
-  exit 1
+Palapala.setup do |config|
+  config.debug = true
 end
+
+pid = Palapala::ChromeProcess.spawn_chrome_headless_server
+Process.wait(pid)

data/examples/headers_and_footers.rb

@@ -25,25 +25,20 @@ HEADER_HTML = <<~HTML
 HTML
 
 Palapala.setup do |config|
-  config.debug = true
-  config.headless_chrome_url = 'http://localhost:9222' # run against a remote Chrome instance
+  # config.debug = true
+  # config.headless_chrome_url = 'http://localhost:9222' # run against a remote Chrome instance
   # config.headless_chrome_path = '/usr/bin/google-chrome-stable' # path to Chrome executable
 end
 
 result = Palapala::Pdf.new(
   # "<style>@page { size: A4 landscape; }</style><p>Hello world #{Time.now}</>",
   "<h1>Title</h1><p>Hello world #{Time.now}</>",
-  header_html: HEADER_HTML,
-  footer_html: '<div style="text-align: center;">Generated with Palapala PDF</div>',
+  header_template: HEADER_HTML,
+  footer_template: '<div style="text-align: center; font-size: 12pt; width: 100%;">Generated with Palapala PDF</div>',
   scale: 0.75,
   prefer_css_page_size: false,
-  margin: { top: 3, bottom: 2 }
-).save('tmp/headers_and_footers.pdf',
-       generateDocumentOutline: false,
-       #  marginTop: 1,
-       #  paperWidth: 3,
-       displayHeaderFooter: true,
-       #  landscape: false,
-       headerTemplate: HEADER_HTML)
+  margin_top: 3,
+  margin_bottom: 2).save('tmp/headers_and_footers.pdf')
 
 puts result
+`open tmp/headers_and_footers.pdf`

data/examples/js_based_rendering.rb

@@ -15,8 +15,9 @@ DOCUMENT = <<~HTML
 HTML
 
 Palapala.setup do |config|
-  config.debug = true
+  # config.debug = true
+  # config.defaults = { header_template: '<div></div>', footer_template: '<div></div>' }
 end
 
-result = Palapala::Pdf.new(DOCUMENT).save('tmp/js_based_rendering.pdf')
-puts result
+Palapala::Pdf.new(DOCUMENT).save('tmp/js_based_rendering.pdf')
+`open tmp/js_based_rendering.pdf`

data/lib/palapala/chrome_process.rb

@@ -25,9 +25,9 @@ module Palapala
       end
     end
 
-    # Check if a Chrome is running
+    # Check if a Chrome is running locally
     def self.chrome_running?
-      port_in_use? || # Check if the port is in use and Chrome is running externally
+      port_in_use? || # Check if the port is in use
       chrome_process_healthy? # Check if the process is still alive
     end
 
@@ -59,9 +59,9 @@ module Palapala
       system("which npx > /dev/null 2>&1")
     end
 
-    def self.spawn_chrome_headless_server
+    def self.spawn_chrome_headless_server_with_npx
       # Run the command and capture the output
-      puts "Installing latest stable chrome-headless-shell..."
+      puts "Installing/launching chrome-headless-shell@#{Palapala.chrome_headless_shell_version}"
       output, status = Open3.capture2("npx --yes @puppeteer/browsers install chrome-headless-shell@#{Palapala.chrome_headless_shell_version}")
 
       if status.success?
@@ -82,29 +82,37 @@ module Palapala
         # Display the version
         system("#{chrome_path} --version") if Palapala.debug
         # Launch chrome-headless-shell with the --remote-debugging-port parameter
-        if Palapala.debug
-          puts "spawning with output"
-          spawn(chrome_path, "--remote-debugging-port=9222", "--disable-gpu")
+        params = [ "--disable-gpu", "--remote-debugging-port=9222" ]
+        params.merge!(Palapala.chrome_params) if Palapala.chrome_params
+        pid = if Palapala.debug
+          spawn(chrome_path, *params)
         else
-          spawn(chrome_path, "--remote-debugging-port=9222", "--disable-gpu", out: "/dev/null", err: "/dev/null")
+          spawn(chrome_path, *params, out: "/dev/null", err: "/dev/null")
         end
+        Palapala.headless_chrome_url = "http://localhost:9222"
+        pid
       else
         raise "Failed to install chrome-headless-shell"
       end
     end
 
+    def self.spawn_chrome_from_path
+      params = [ "--headless", "--disable-gpu", "--remote-debugging-port=9222" ]
+      params.merge!(Palapala.chrome_params) if Palapala.chrome_params
+      # Spawn an existing chrome with the path and parameters
+      Process.spawn(chrome_path, *params)
+    end
+
     # Spawn a Chrome child process
     def self.spawn_chrome
       return if chrome_running?
 
-      if self.npx_installed?
-        @chrome_process_id = spawn_chrome_headless_server
-      else
-        params = [ "--headless", "--disable-gpu", "--remote-debugging-port=9222" ]
-        params.merge!(Palapala.chrome_params) if Palapala.chrome_params
-        # Spawn an existing chrome with the path and parameters
-        @chrome_process_id = Process.spawn(chrome_path, *params)
-      end
+      @chrome_process_id =
+        if Palapala.headless_chrome_path.nil? && self.npx_installed?
+          spawn_chrome_headless_server_with_npx
+        else
+          spawn_chrome_from_path
+        end
 
       # Wait until the port is in use
       sleep 0.1 until port_in_use?

data/lib/palapala/pdf.rb

@@ -42,20 +42,22 @@ module Palapala
                    scale: nil)
       @content = content || raise(ArgumentError, "Content is required and can't be nil")
       @opts = {}
-      @opts[:headerTemplate]    = header_template      || Palapala.defaults[:header_template]
-      @opts[:footerTemplate]    = footer_template      || Palapala.defaults[:footer_template]
-      @opts[:pageRanges]        = page_ranges          || Palapala.defaults[:page_ranges]
-      @opts[:generateTaggedPDF] = generate_tagged_pdf  || Palapala.defaults[:generate_tagged_pdf]
-      @opts[:paperWidth]        = paper_width          || Palapala.defaults[:paper_width]
-      @opts[:paperHeight]       = paper_height         || Palapala.defaults[:paper_height]
-      @opts[:landscape]         = landscape            || Palapala.defaults[:landscape]
-      @opts[:marginTop]         = margin_top           || Palapala.defaults[:margin_top]
-      @opts[:marginLeft]        = margin_left          || Palapala.defaults[:margin_left]
-      @opts[:marginBottom]      = margin_bottom        || Palapala.defaults[:margin_bottom]
-      @opts[:marginRight]       = margin_right         || Palapala.defaults[:margin_right]
-      @opts[:preferCSSPageSize] = prefer_css_page_size || Palapala.defaults[:prefer_css_page_size]
-      @opts[:printBackground]   = print_background     || Palapala.defaults[:print_background]
-      @opts[:scale]             = scale                || Palapala.defaults[:scale]
+      @opts[:headerTemplate]      = header_template      || Palapala.defaults[:header_template]
+      @opts[:footerTemplate]      = footer_template      || Palapala.defaults[:footer_template]
+      @opts[:pageRanges]          = page_ranges          || Palapala.defaults[:page_ranges]
+      @opts[:generateTaggedPDF]   = generate_tagged_pdf  || Palapala.defaults[:generate_tagged_pdf]
+      @opts[:paperWidth]          = paper_width          || Palapala.defaults[:paper_width]
+      @opts[:paperHeight]         = paper_height         || Palapala.defaults[:paper_height]
+      @opts[:landscape]           = landscape            || Palapala.defaults[:landscape]
+      @opts[:marginTop]           = margin_top           || Palapala.defaults[:margin_top]
+      @opts[:marginLeft]          = margin_left          || Palapala.defaults[:margin_left]
+      @opts[:marginBottom]        = margin_bottom        || Palapala.defaults[:margin_bottom]
+      @opts[:marginRight]         = margin_right         || Palapala.defaults[:margin_right]
+      @opts[:preferCSSPageSize]   = prefer_css_page_size || Palapala.defaults[:prefer_css_page_size]
+      @opts[:printBackground]     = print_background     || Palapala.defaults[:print_background]
+      @opts[:scale]               = scale                || Palapala.defaults[:scale]
+      @opts[:displayHeaderFooter] = true
+      @opts[:encoding]            = :binary
       @opts.compact!
     end
 

data/lib/palapala/renderer.rb

@@ -22,6 +22,13 @@ module Palapala
       send_command_and_wait_for_result("Page.enable")
     end
 
+    def websocket_url
+      self.class.websocket_url
+    rescue Errno::ECONNREFUSED
+      ChromeProcess.spawn_chrome # Spawn a new Chrome process
+      self.class.websocket_url # Retry (once)
+    end
+
     # Create a thread-local instance of the renderer
     def self.thread_local_instance
       Thread.current[:renderer] ||= Renderer.new
@@ -102,16 +109,8 @@ module Palapala
       @client.close
     end
 
-    private
-
-    # Convert the HTML content to a data URL
-    def data_url_for_html(html)
-      "data:text/html;base64,#{Base64.strict_encode64(html)}"
-    end
-
     # Open a new tab in the remote chrome and return the WebSocket URL
-    def websocket_url
-      ChromeProcess.spawn_chrome
+    def self.websocket_url
       uri = URI("#{Palapala.headless_chrome_url}/json/new")
       http = Net::HTTP.new(uri.host, uri.port)
       request = Net::HTTP::Put.new(uri)
@@ -122,5 +121,12 @@ module Palapala
       puts "WebSocket URL: #{websocket_url}" if Palapala.debug
       websocket_url
     end
+
+    private
+
+    # Convert the HTML content to a data URL
+    def data_url_for_html(html)
+      "data:text/html;base64,#{Base64.strict_encode64(html)}"
+    end
   end
 end

data/lib/palapala/version.rb

@@ -1,3 +1,3 @@
 module Palapala
-  VERSION = "0.1.8"
+  VERSION = "0.1.10"
 end

data/lib/palapala.rb

@@ -19,16 +19,20 @@ module Palapala
     # path to the headless Chrome executable when using the child process renderer
     attr_accessor :headless_chrome_path
 
-    # URL to the headless Chrome instance when using the remote renderer
+    # URL to the headless Chrome instance when using the remote renderer (priority)
     attr_accessor :headless_chrome_url
 
-    # Chrome headless shell version to use
+    # Chrome headless shell version to use (stable, beta, dev, canary, etc.)
+    # when launching a new Chrome instance using npx
     attr_accessor :chrome_headless_shell_version
   end
-
   self.debug = false
-  self.defaults = { displayHeaderFooter: true, encoding: :binary }
+  self.defaults = {
+    header_template: "<div></div>",
+    footer_template: "<div></div>"
+    # footer_template: '<div style="text-align: center; font-size: 12pt; width: 100%;">Generated with Palapala PDF</div>'
+  }
   self.headless_chrome_path = nil
-  self.headless_chrome_url = "http://localhost:9222"
-  self.chrome_headless_shell_version = "stable"
+  self.headless_chrome_url = ENV.fetch("HEADLESS_CHROME_URL", "http://localhost:9222")
+  self.chrome_headless_shell_version = ENV.fetch("CHROME_HEADLESS_SHELL_VERSION", "stable")
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: palapala_pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Koen Handekyn