palapala_pdf 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ceecc9fff4323ef8cdf26b9e20aeb35f21610e8b55f716a0b8e0c27c0e38613
+  data.tar.gz: 4f9f412514ad9a9b63e4b6484488ff245bb0769352374a652845749ac230b6e6
+SHA512:
+  metadata.gz: 62c62530b7034a687012bea224b8d284616cef97a2e749ab26151ee2e925ffb3b72ab0d96b13e970ab9d2630bca188c1e134ca59e81bcb37f245dbb1b888f000
+  data.tar.gz: 352245729e62e3df55c23848b684af2deb642b3d506de83ef71f8cf0bc4964ac94219baac3e06e776957f15cb15fba41cf3f864ecb4a381c7e057bed75e598f6

data/.rubocop.yml

@@ -0,0 +1,14 @@
+inherit_from: .rubocop_todo.yml
+
+# This is a basic RuboCop configuration file
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - db/schema.rb
+    - bin/**/*
+    - draft/**/*
+
+require:
+  - rubocop-minitest
+  - rubocop-rake

data/.rubocop_todo.yml

@@ -0,0 +1,44 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-08-23 11:11:08 UTC using RuboCop version 1.65.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 33
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 13
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 19
+
+# Offense count: 1
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 10
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 13
+
+# Offense count: 2
+Style/ClassVars:
+  Exclude:
+    - 'lib/palapala/pdf.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 121

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Quine & Partners
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# PDF Generation for your Rubies
+
+This project is a Ruby gem that provides functionality for generating PDF files from HTML using the Chrome browser. It allows you to easily convert HTML content into PDF documents, making it convenient for tasks such as generating reports, invoices, or any other printable documents. The gem provides a simple and intuitive API for converting HTML to PDF, and it leverages the power and flexibility of the Chrome browser's rendering engine to ensure accurate and high-quality PDF output. With this gem, you can easily integrate PDF generation capabilities into your Ruby applications.
+
+At the core, this project leverages the same rendering engine as [Grover](https://github.com/Studiosity/grover), but with significantly reduced overhead and dependencies. Instead of relying on the full Grover stack, this project builds on [Ferrum](https://github.com/rubycdp/ferrum) to enable direct communication from Ruby to a headless Chrome or Chromium browser. This approach ensures efficient, thread-safe operations, providing a streamlined alternative for rendering tasks without sacrificing performance or flexibility.
+
+This is how easy and powerfull PDF generation should be:
+
+```ruby
+require "palapala"
+Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')
+```
+
+And this while having the most modern HTML/CSS/JS availlable to you: flex, grid, canvas, you name it.
+
+## Installation
+
+To install the gem and add it to your application's Gemfile, execute the following command:
+
+```
+$ bundle add palapala_pdf
+```
+
+If you are not using bundler to manage dependencies, you can install the gem by running:
+
+```
+$ gem install palapala_pdf
+```
+
+Palapala PDF uses [Ferrum](https://github.com/rubycdp/ferrum) inside and that one is pretty good at finding your Chrome or Chromium.
+
+If you want the highest throughput, then use an external Chrome/Chromium. Just start it with (9222 is the default port):
+
+```sh
+chrome --headless --disable-gpu --remote-debugging-port=9222
+```
+
+Then you can run Palapala PDF against that Chrome/Chromium instance (see configuration).
+
+## Usage Instructions
+
+To create a PDF from HTML content using the `Palapala` library, follow these steps:
+
+1. **Configuration**:
+
+Configure the `Palapala` library with the necessary options, such as the URL for the Ferrum browser and default settings like scale and format.
+
+In a Rails context, this could be inside an initializer.
+
+```ruby
+Palapala.setup do |config|
+    # run against an external chrome/chromium or leave this out to run against a chrome that is started as a child process
+    config.ferrum_opts = { url: 'http://localhost:9222' }
+    config.defaults = { scale: 1, format: :A4 }
+end
+```
+
+2. **Create a PDF from HTML**:
+
+Create a PDF file from HTML in IRB
+
+```sh
+gem install palapala_pdf
+```
+
+in IRB, load palapala and create a PDF from an HTML snippet:
+
+```sh
+>irb
+```
+
+```ruby
+require "palapala"
+Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").save('hello.pdf')
+```
+
+Instantiate a new Palapala::Pdf object with your HTML content and generate the PDF binary data.
+
+```ruby
+require "palapala"
+binary_data = Palapala::Pdf.new("<h1>Hello, world! #{Time.now}</h1>").binary_data
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/palapala-app/palapala_pdf.
+
+## Contributors
+
+- [Kenneth Geerts](https://github.com/kennethgeerts) - Your foundational contributions to simplicity are greatly appreciated.
+- [Eugen Neagoe](https://github.com/eneagoe) - Thank you for your valuable input, feedback and opinions.
+
+## Sponsor This Project
+
+If you find this project useful and would like to support its development, consider sponsoring or buying a coffee to help keep it going:
+
+- **GitHub Sponsors:** [Sponsor on GitHub](https://github.com/sponsors/koenhandekyn)
+- **Buy Me a Coffee:** [Buy a Coffee](https://buymeacoffee.com/koenhandekyn)
+
+Your support is greatly appreciated and helps maintain the project!
+
+## Findings
+
+For Chrome, mode headless=new seems to be slower for pdf rendering cases.
+
+## Primitive benchmark
+
+On a macbook m3, the throughput for 'hello world' PDF generation can reach around 25 docs/second when allowing for some concurrency. As Chrome is actually also very efficient, it scales really well for complex documents also. If you run this in Rails, the concurrency is being taken care of either by the front end thread pool or by the workers and you shouldn't have to think about this. (Using an external Chrome)
+
+
+```
+benchmarking 20 docs: 1x20, 2x10, 4x5, 5x4, 20x1 (c is concurrency, n is iterations)
+Total time c:1, n:20 = 1.2048690000083297 seconds
+Total time c:2, n:10 = 0.8969700000016019 seconds
+Total time c:4, n:5 = 0.7497870000079274 seconds
+Total time c:5, n:4 = 0.72492800001055 seconds
+Total time c:20, n:1 = 0.7156629998935387 seconds
+```
+
+## Advanced stuf
+
+### Headers and Footers
+
+### Title pages
+
+### Page sizes in CSS

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end
+
+task default: :test

data/lib/palapala/pdf.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'ferrum'
+
+module Palapala
+  # Page class to generate PDF from HTML content using Chrome in headless mode in a thread-safe way
+  class Pdf
+    def initialize(content = nil,
+                   url: nil,
+                   path: nil,
+                   header_html: nil,
+                   footer_html: nil,
+                   generate_tagged_pdf: false,
+                   prefer_css_page_size: true,
+                   scale: Palapala.defaults.fetch(:scale, 1),
+                   page_ranges: Palapala.defaults.fetch(:page_ranges, ''),
+                   margin: Palapala.defaults.fetch(:margin, {}))
+      @content = content
+      @url = url
+      @path = path
+      @header_html = header_html
+      @footer_html = footer_html
+      @generate_tagged_pdf = generate_tagged_pdf
+      @prefer_css_page_size = prefer_css_page_size
+      @page_ranges = page_ranges
+      @scale = scale
+      @margin = margin
+    end
+
+    def pdf(**opts)
+      browser_context = browser.contexts.create
+      browser_page = browser_context.page
+      # # output console logs for this page
+      if opts[:debug]
+        browser_page.on('Runtime.consoleAPICalled') do |params|
+          params['args'].each { |r| puts(r['value']) }
+        end
+      end
+      # open the page
+      url = @url || data_url
+      browser_page.go_to(url)
+      # Wait for the page to load
+      browser_page.network.wait_for_idle
+      # Generate PDF
+      pdf_binary_data = browser_page.pdf(**opts_with_defaults.merge(opts))
+      # Dispose the context
+      browser_context.dispose
+      # Return the PDF data
+      pdf_binary_data
+    end
+
+    def binary_data(**opts)
+      pdf(**opts)
+    end
+
+    def save(path, **opts)
+      pdf(path:, **opts)
+    end
+
+    private
+
+    def data_url
+      encoded_html = Base64.strict_encode64(@content)
+      "data:text/html;base64,#{encoded_html}"
+    end
+
+    def opts_with_defaults
+      opts = { scale: @scale,
+               printBackground: true,
+               dispayHeaderFooter: true,
+               pageRanges: @page_ranges, # Empty string means all pages, e.g., "1-3, 5, 7-9"
+               encoding: :binary,
+               preferCSSPageSize: true,
+               headerTemplate: @header_html || '',
+               footerTemplate: @footer_html || '' }
+
+      opts[:path] = @path unless @path.nil?
+      opts[:generateTaggedPDF] = @generate_tagged_pdf unless @generate_tagged_pdf.nil?
+      opts[:format] = @format unless @format.nil?
+      opts[:paperWidth] = @paper_width unless @paper_width.nil?
+      opts[:paperHeight] = @paper_height unless @paper_height.nil?
+      opts[:landscape] = @landscape unless @landscape.nil?
+      opts[:marginTop] = @margin[:top] unless @margin[:top].nil?
+      opts[:marginLeft] = @margin[:left] unless @margin[:left].nil?
+      opts[:marginBottom] = @margin[:bottom] unless @margin[:bottom].nil?
+      opts[:marginRight] = @margin[:right] unless @margin[:right].nil?
+
+      opts
+    end
+
+    def browser
+      # accordng to the docs ferrum is thread safe, however, under heavy load
+      # we are seeing some issues, so we are using thread locals to have a
+      # browser per thread
+      Thread.current[:browser] ||= new_browser
+      # @@browser ||= new_browser
+    end
+
+    def new_browser
+      Ferrum::Browser.new(Palapala.ferrum_opts)
+    end
+
+    # # TODO use method from template class
+    # def cm_to_inches(value)
+    #   value / 2.54
+    # end
+  end
+end

data/lib/palapala/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Palapala
+  VERSION = '0.1.1'
+end

data/lib/palapala.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'palapala/pdf'
+
+# Main module for the gem
+module Palapala
+  def self.setup
+    yield self
+  end
+
+  def self.ferrum_opts=(ferrum_opts)
+    @ferrum_opts = ferrum_opts
+  end
+
+  def self.ferrum_opts
+    @ferrum_opts
+  end
+
+  def self.defaults=(defaults)
+    @defaults = defaults
+  end
+
+  def self.defaults
+    @defaults ||= {}
+  end
+end

data/palapala_pdf.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'lib/palapala/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'palapala_pdf'
+  spec.version = Palapala::VERSION
+  spec.authors = ['Koen Handekyn']
+  spec.email = ['github.com@handekyn.com']
+
+  spec.summary = 'Convert HTML into PDF directly from Ruby using Chrome/Chromium.'
+  spec.description = 'This gem uses Ferrum to render HTML into a PDF using Chrom(e)(ium) with minimal dependencies.'
+  spec.homepage = 'https://github.com/palapala-app/palapala_pdf'
+  spec.required_ruby_version = '>= 3.1'
+  spec.license = 'MIT'
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  # spec.metadata['source_code_uri'] = 'https://github.com/palapala-app/palapala_pdf'
+  spec.metadata['changelog_uri'] = 'https://github.com/palapala-app/palapala_pdf/blob/main/changelog.md'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ draft/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'ferrum', '~> 0.15'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: palapala_pdf
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Koen Handekyn
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-08-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+description: This gem uses Ferrum to render HTML into a PDF using Chrom(e)(ium) with
+  minimal dependencies.
+email:
+- github.com@handekyn.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- ".ruby-version"
+- LICENSE
+- README.md
+- Rakefile
+- lib/palapala.rb
+- lib/palapala/pdf.rb
+- lib/palapala/version.rb
+- palapala_pdf.gemspec
+homepage: https://github.com/palapala-app/palapala_pdf
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/palapala-app/palapala_pdf
+  changelog_uri: https://github.com/palapala-app/palapala_pdf/blob/main/changelog.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Convert HTML into PDF directly from Ruby using Chrome/Chromium.
+test_files: []