Dhalang 0.2.0 → 0.6.0

data/Rakefile

@@ -1,6 +1,6 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/Dhalang.rb

@@ -1,4 +1,14 @@
-module Dhalang
-  require 'PDF'
-  require 'Screenshot'
-end
+module Dhalang
+  require_relative 'PDF'
+  require_relative 'Screenshot'
+  require_relative 'Dhalang/version'
+  require_relative 'Dhalang/url_utils'
+  require_relative 'Dhalang/file_utils'
+  require_relative 'Dhalang/error'
+  require_relative 'Dhalang/puppeteer'
+  require 'uri'
+  require 'tempfile'
+  require 'shellwords'
+  require 'json'
+  require 'open3'
+end

data/lib/Dhalang/error.rb

@@ -0,0 +1 @@
+class DhalangError < StandardError; end

data/lib/Dhalang/file_utils.rb

@@ -0,0 +1,37 @@
+module Dhalang
+    # Contains common logic for files. 
+    class FileUtils
+
+        # Reads the file under the given filepath as a binary.
+        #
+        # @param [String] file_path The absolute path of the file to read.
+        #
+        # @return [String]      The binary content under the file_path.
+        def self.read_binary(file_path)
+            IO.binread(file_path)
+        end
+
+        # Creates a new temp file.
+        #
+        # @param [String] extension The extension of the file.
+        # @param [String] content   The content of the file. (Optional)
+        #
+        # @return [Tempfile]    The created temp file.
+        def self.create_temp_file(extension, content = nil)
+            temp_file = Tempfile.new(["dhalang",".#{extension}"])
+            unless(content == nil)
+                temp_file.write(content)
+                temp_file.rewind
+            end
+            temp_file
+        end
+
+        # Deletes the given file.
+        #
+        # @param [File] file    The file to delete.
+        def self.delete(file)
+            file.close unless file.closed?
+            file.unlink
+        end
+    end
+end

data/lib/Dhalang/puppeteer.rb

@@ -0,0 +1,95 @@
+module Dhalang
+    # Contains common logic for interacting with Puppeteer.
+    class Puppeteer
+        NODE_MODULES_PATH = Dir.pwd + '/node_modules/'.freeze
+        private_constant :NODE_MODULES_PATH
+
+        USER_OPTIONS = {
+                navigationTimeout: 10000,
+                navigationWaitUntil: 'load',
+                navigationWaitForSelector: '',
+                navigationWaitForXPath: '',
+                userAgent: '',
+                isHeadless: true,
+                viewPort: '',
+                httpAuthenticationCredentials: '',
+                isAutoHeight: false
+        }
+        private_constant :USER_OPTIONS
+
+        DEFAULT_PDF_OPTIONS = {
+            scale: 1,
+            displayHeaderFooter: false,
+            headerTemplate: '',
+            footerTemplate: '',
+            printBackground: true,
+            landscape: false,
+            pageRanges: '',
+            format: 'A4',
+            width: '',
+            height: '',
+            margin: { top: 36, right: 36, bottom: 20, left: 36 },
+            preferCSSPageSiz: false
+        }
+        private_constant :DEFAULT_PDF_OPTIONS
+
+        DEFAULT_PNG_OPTIONS = {
+            fullPage: true,
+            clip: nil,
+            omitBackground: false
+        }
+        private_constant :DEFAULT_PNG_OPTIONS
+
+        DEFAULT_JPEG_OPTIONS = {
+            quality: 100,
+            fullPage: true,
+            clip: nil,
+            omitBackground: false
+        }
+        private_constant :DEFAULT_JPEG_OPTIONS
+
+
+        # Launches a new Node process, executing the (Puppeteer) script under the given script_path.
+        #
+        # @param [String] page_url              The url to pass to the goTo method of Puppeteer.
+        # @param [String] script_path           The absolute path of the JS script to execute.
+        # @param [String] temp_file_path        The absolute path of the temp file to use to write any actions from Puppeteer.
+        # @param [String] temp_file_extension   The extension of the temp file.
+        # @param [Object] options               Set of options to use, configurable by the user.
+        def self.visit(page_url, script_path, temp_file_path, temp_file_extension, options)
+            configuration = create_configuration(page_url, script_path, temp_file_path, temp_file_extension, options)
+
+            command = "node #{script_path} #{Shellwords.escape(configuration)}"
+
+            Open3.popen2e(command) do |_stdin, stdouterr, wait|
+                return nil if wait.value.success?
+
+                output = stdouterr.read.strip
+                output = nil if output == ''
+                message = output || "Exited with status #{wait.value.exitstatus}"
+                raise DhalangError, message
+            end
+        end
+
+
+        # Returns a JSON string with the configuration to use within the Puppeteer script.
+        #
+        # @param [String] page_url              The url to pass to the goTo method of Puppeteer.
+        # @param [String] script_path           The absolute path of the JS script to execute.
+        # @param [String] temp_file_path        The absolute path of the temp file to use to write any actions from Puppeteer.
+        # @param [String] temp_file_extension   The extension of the temp file.
+        # @param [Hash]   options               Set of options to use, configurable by the user.
+        private_class_method def self.create_configuration(page_url, script_path, temp_file_path, temp_file_extension, options)
+            {
+                webPageUrl: page_url,
+                tempFilePath: temp_file_path,
+                puppeteerPath: NODE_MODULES_PATH,
+                imageType: temp_file_extension,
+                userOptions: USER_OPTIONS.map { |option, value| [option, options.has_key?(option) ? options[option] : value]}.to_h,
+                pdfOptions: DEFAULT_PDF_OPTIONS.map { |option, value| [option, options.has_key?(option) ? options[option] : value] }.to_h,
+                pngOptions: DEFAULT_PNG_OPTIONS.map { |option, value| [option, options.has_key?(option) ? options[option] : value] }.to_h,
+                jpegOptions: DEFAULT_JPEG_OPTIONS.map { |option, value| [option, options.has_key?(option) ? options[option] : value] }.to_h
+            }.to_json
+        end
+    end
+end

data/lib/Dhalang/url_utils.rb

@@ -0,0 +1,14 @@
+module Dhalang
+    # Contains common logic for URL's. 
+    class UrlUtils
+
+        # Raises an error if the given URL cannot be used for navigation with Puppeteer.
+        #
+        # @param [String] url The url to validate
+        def self.validate(url)
+            if (url !~ URI::DEFAULT_PARSER.regexp[:ABS_URI])
+                raise URI::InvalidURIError, 'The given url was invalid, use format http://www.example.com'
+            end
+        end
+    end
+end

data/lib/Dhalang/version.rb

@@ -1,3 +1,3 @@
-module Dhalang
-  VERSION = "0.2.0"
-end
+module Dhalang
+  VERSION = "0.6.0"
+end

data/lib/PDF.rb

@@ -1,65 +1,54 @@
-require "Dhalang/version"
-require 'uri'
-require 'tempfile'
-
-module Dhalang
-  class PDF
-    PDF_GENERATOR_JS_PATH = File.expand_path('../js/pdfgenerator.js', __FILE__)
-    PROJECT_PATH = Dir.pwd + '/node_modules/'
-
-    def self.get_from_url(url)
-      validate_url(url)
-      temporary_pdf_save_file = create_temporary_pdf_file
-      begin
-        visit_page_with_puppeteer(url, temporary_pdf_save_file.path)
-        binary_pdf_content = get_file_content_as_binary_string(temporary_pdf_save_file)
-      ensure
-        temporary_pdf_save_file.close unless temporary_pdf_save_file.closed?
-        temporary_pdf_save_file.unlink
-      end
-      return binary_pdf_content
-    end
-
-    def self.get_from_html(html)
-      html_file = create_temporary_html_file(html)
-      temporary_pdf_save_file = create_temporary_pdf_file
-      begin
-        visit_page_with_puppeteer("file://" + html_file.path, temporary_pdf_save_file.path)
-        binary_pdf_content = get_file_content_as_binary_string(temporary_pdf_save_file)
-      ensure
-        temporary_pdf_save_file.close unless temporary_pdf_save_file.closed?
-        html_file.close unless html_file.closed?
-        temporary_pdf_save_file.unlink
-        html_file.unlink
-      end
-      return binary_pdf_content
-    end
-
-    private
-    def self.validate_url(url)
-      if (url !~ URI::DEFAULT_PARSER.regexp[:ABS_URI])
-        raise URI::InvalidURIError, 'The given url was invalid, use format http://www.example.com'
-      end
-    end
-
-    def self.create_temporary_pdf_file
-      Tempfile.new("pdf")
-    end
-
-    ## Creates a temp .html file which can be browsed to by puppeteer for creating a pdf
-    def self.create_temporary_html_file(content)
-      html_file = Tempfile.new(['page', '.html'])
-      html_file.write(content)
-      html_file.rewind
-      return html_file
-    end
-
-    def self.visit_page_with_puppeteer(page_to_visit, path_to_save_pdf_to)
-      system("node #{PDF_GENERATOR_JS_PATH} #{page_to_visit} #{Shellwords.escape(path_to_save_pdf_to)} #{Shellwords.escape(PROJECT_PATH)}")
-    end
-
-    def self.get_file_content_as_binary_string(file)
-      IO.binread(file.path)
-    end
-  end
-end
+module Dhalang
+  # Allows consumers of this library to create PDFs with Puppeteer. 
+  class PDF
+    PUPPETEER_SCRIPT_PATH = File.expand_path('../js/pdf-generator.js', __FILE__).freeze
+    private_constant :PUPPETEER_SCRIPT_PATH
+    
+    # Captures the full webpage under the given url as PDF.
+    #
+    # @param  [String] url      The url to get as PDF.
+    # @param  [Hash]   options  User configurable options.
+    #
+    # @return [String] The PDF that was created as binary.
+    def self.get_from_url(url, options = {})
+      UrlUtils.validate(url)
+      get(url, options)
+    end
+
+    # Captures the full HTML as PDF.
+    # Useful when creating dynamic content, for example invoices.
+    #
+    # @param  [String]  html     The html to get as PDF.
+    # @param  [Hash]    options  User configurable options.
+    #
+    # @return [String] The PDF that was created as binary.
+    def self.get_from_html(html, options = {})
+      html_file = FileUtils.create_temp_file("html", html)
+      url = "file://" + html_file.path
+      begin
+          binary_pdf_content = get(url, options)
+      ensure
+        FileUtils.delete(html_file)
+      end
+      return binary_pdf_content
+    end
+
+    
+    # Groups and executes the logic for creating a PDF of a webpage.
+    #
+    # @param  [String]  url      The url to create a PDF for.
+    # @param  [Hash]    options  Set of options to use, passed by the user of this library.
+    #
+    # @return [String] The PDF that was created as binary.
+    private_class_method def self.get(url, options)
+      temp_file = FileUtils.create_temp_file("pdf")
+      begin
+        Puppeteer.visit(url, PUPPETEER_SCRIPT_PATH, temp_file.path, "pdf", options)
+        binary_pdf_content = FileUtils.read_binary(temp_file.path)
+      ensure
+        FileUtils.delete(temp_file)
+      end
+      return binary_pdf_content
+    end
+  end
+end

data/lib/Screenshot.rb

@@ -1,51 +1,57 @@
-require "Dhalang/version"
-require 'uri'
-require 'tempfile'
-
-module Dhalang
-  class Screenshot
-    SCREENSHOT_GENERATOR_JS_PATH = File.expand_path('../js/screenshotgenerator.js', __FILE__)
-    PROJECT_PATH = Dir.pwd + '/node_modules/'
-
-    def self.get_from_url_as_jpeg(url)
-      validate_url(url)
-      get_image(url, :jpeg)
-    end
-
-    def self.get_from_url_as_png(url)
-      validate_url(url)
-      get_image(url, :png)
-    end
-
-    private
-    def self.validate_url(url)
-      if (url !~ URI::DEFAULT_PARSER.regexp[:ABS_URI])
-        raise URI::InvalidURIError, 'The given url was invalid, use format http://www.example.com'
-      end
-    end
-
-    def self.create_temporary_screenshot_file
-      Tempfile.new("png")
-    end
-
-    def self.get_image(url, type)
-      temporary_screenshot_save_file = create_temporary_screenshot_file
-      begin
-        visit_page_with_puppeteer(url, temporary_screenshot_save_file.path, type)
-        binary_image_content = get_file_content_as_binary_string(temporary_screenshot_save_file)
-      ensure
-        temporary_screenshot_save_file.close unless temporary_screenshot_save_file.closed?
-        temporary_screenshot_save_file.unlink
-      end
-      return binary_image_content
-    end
-
-    def self.visit_page_with_puppeteer(page_to_visit, path_to_save_pdf_to, image_save_type)
-      system("node #{SCREENSHOT_GENERATOR_JS_PATH} #{page_to_visit} #{Shellwords.escape(path_to_save_pdf_to)} #{Shellwords.escape(PROJECT_PATH)} #{Shellwords.escape(image_save_type)}")
-    end
-
-    def self.get_file_content_as_binary_string(file)
-      IO.binread(file.path)
-    end
-  end
-end
+module Dhalang
+  # Allows consumers of this library to take screenshots with Puppeteer. 
+  class Screenshot
+    PUPPETEER_SCRIPT_PATH = File.expand_path('../js/screenshot-generator.js', __FILE__).freeze
+    private_constant :PUPPETEER_SCRIPT_PATH
+    
+    # Captures a full JPEG screenshot of the webpage under the given url.
+    #
+    # @param  [String] url        The url to take a screenshot of.
+    # @param  [Hash]   options    User configurable options.
+    #
+    # @return [String] the screenshot that was taken as binary.
+    def self.get_from_url_as_jpeg(url, options = {})
+      get(url, "jpeg", options)
+    end
+
+    # Captures a full PNG screenshot of the webpage under the given url.
+    #
+    # @param  [String] url        The url to take a screenshot of.
+    # @param  [Hash]   options    User configurable options.
+    #
+    # @return [String] The screenshot that was taken as binary.
+    def self.get_from_url_as_png(url, options = {})
+      get(url, "png", options)
+    end
+    
+    # Groups and executes the logic for taking a screenhot of a webpage.
+    #
+    # @param  [String] url        The url to take a screenshot of.
+    # @param  [String] image_type The image type to use for storing the screenshot.
+    # @param  [Hash]   options    Set of options to use, passed by the user of this library.
+    #
+    # @return [String] The screenshot that was taken as binary.
+    private_class_method def self.get(url, image_type, options)
+      UrlUtils.validate(url)
+      validate_options(options)
+      temp_file = FileUtils.create_temp_file(image_type)
+      begin
+        Puppeteer.visit(url, PUPPETEER_SCRIPT_PATH, temp_file.path, image_type, options)
+        binary_image_content = FileUtils.read_binary(temp_file.path)
+      ensure
+        FileUtils.delete(temp_file)
+      end
+      return binary_image_content
+    end
+
+    # Raises an error if the given options might conflict with the Puppeteer configuration.
+    #
+    # @param [Hash] options The options to validate
+    private_class_method def self.validate_options(options)
+      symbolized_options = options.transform_keys(&:to_sym)
+      if symbolized_options.has_key?(:type)
+        raise DhalangError, 'Invalid option set: "type"'
+      end
+    end
+  end
+end

data/lib/js/dhalang.js

@@ -0,0 +1,146 @@
+/**
+ * @typedef {Object} Configuration
+ * @property {string} webPageUrl            - The url of the webpage to visit.
+ * @property {string} tempFilePath          - The path of the tempfile to write the screenshot/pdf to.
+ * @property {string} puppeteerModulePath   - The path of the Puppeteer module.
+ * @property {string} imageType             - The type of image to save ( undefined for pdfgenerator ).
+ * @property {UserOptions} userOptions      - User defined and default parameters to use when navigating to pages.
+ * @property {Object} pdfOptions            - User defined and default parameters to use when creating PDFs. Note: Do not use directly, rather use {@link getConfiguredPdfOptions}.
+ * @property {Object} pngOptions            - User defined and default parameters to use when creating PNGs.
+ * @property {Object} jpegOptions           - User defined and default parameters to use when creating JPEGs.
+ */
+
+/**
+ * @typedef {Object} UserOptions
+ * @property {number} navigationTimeout             - Maximum in milliseconds until navigation times out, we use a default of 10 seconds as timeout.
+ * @property {string} navigationWaitUntil           - Determines when the navigation was finished, we wait here until the Window.load event is fired ( meaning all images, stylesheet, etc was loaded ).
+ * @property {string} navigationWaitForSelector     - If set, specifies the selector Puppeteer should wait for to appear before continuing.
+ * @property {string} navigationWaitForXPath        - If set, specifies the XPath Puppeteer should wait for to appear before continuing.
+ * @property {string} userAgent                     - The user agent to send with requests.
+ * @property {boolean} isHeadless                   - Indicates if Puppeteer should launch Chromium in headless mode.
+ * @property {Object} viewPort                      - The view port to use.
+ * @property {Object} httpAuthenticationCredentials - The credentials to use for HTTP authentication.
+ * @property {boolean} isAutoHeight                 - The height is automatically set
+ */
+
+/**
+ * @typedef {Object} NavigationParameters
+ * @property {number} timeout               - Maximum in milliseconds until navigation times out, we use a default of 10 seconds as timeout.
+ * @property {string} waituntil             - Determines when the navigation was finished, we wait here until the Window.load event is fired ( meaning all images, stylesheet, etc was loaded ).
+ */
+
+/**
+ * @typedef {Object} WaitingParameters
+ * @property {number} timeout               - Maximum in milliseconds until navigation times out, we use a default of 10 seconds as timeout.
+ */
+
+/**
+ * Parses the given configuration process argument from Ruby to a JS object.
+ * @returns {Configuration}
+ * The configuration object.
+ */
+exports.getConfiguration = function () {
+    return JSON.parse(process.argv[2])
+}
+
+/**
+ * Launches Puppeteer and returns its instance.
+ * @param {UserOptions} configuration - The configuration to use.
+ * @returns {Promise<Object>}
+ * The launched instance of Puppeteer.
+ */
+exports.launchPuppeteer = async function (configuration) {
+    module.paths.push(configuration.puppeteerPath);
+    const puppeteer = require('puppeteer');
+    const launchArgs = ['--no-sandbox', '--disable-setuid-sandbox'];
+    return await puppeteer.launch({
+        args: launchArgs,
+        headless: configuration.userOptions.isHeadless
+    });
+}
+
+/**
+ * Configures the given Puppeteer page object.
+ * @param {Object} page - The Puppeteer page object to configure.
+ * @param {UserOptions} userOptions - The user options to use.
+ */
+exports.configure = async function (page, userOptions) {
+    if (userOptions.userAgent !== "") {
+        await page.setUserAgent(userOptions.userAgent)
+    }
+
+    if (userOptions.viewPort !== "") {
+        await page.setViewport(userOptions.viewPort)
+    }
+
+    if (userOptions.httpAuthenticationCredentials !== "") {
+        await page.authenticate(userOptions.authenticationCredentials)
+    }
+}
+
+/**
+ * Makes the Puppeteer page object open the url with the specified navigation logic as specified in the given configuration.
+ * @param {Object} page - The Puppeteer page object to use for navigation.
+ * @param {Configuration} configuration - The configuration to use. 
+ */
+exports.navigate = async function (page, configuration) {
+    const navigationWaitForSelector = configuration.userOptions.navigationWaitForSelector;
+    const navigationWaitForXPath = configuration.userOptions.navigationWaitForXPath;
+
+    await page.goto(configuration.webPageUrl, this.getNavigationParameters(configuration));
+
+    if (navigationWaitForSelector !== "") {
+        await page.waitForSelector(navigationWaitForSelector, this.getWaitingParameters(configuration));
+    } else if (navigationWaitForXPath !== "") {
+        await page.waitForXPath(navigationWaitForXPath, this.getWaitingParameters(configuration));
+    } else {
+        await page.waitForTimeout(250);
+    }
+}
+
+/**
+ * Returns the PDF options to pass to Puppeteer based on the set user options and the documents body.  
+ * @param {Object} page - The Puppeteer page to configure.
+ * @param {UserOptions} configuration - The configuration to use.
+ * @returns {Object} - pdfOptions
+ */
+exports.getConfiguredPdfOptions = async function (page, configuration) {
+    const pdfOptions = configuration.pdfOptions
+
+    if (configuration.userOptions.isAutoHeight === true) {
+        const pageHeight = await page.evaluate(() => {
+            return Math.max(document.body.scrollHeight, document.body.offsetHeight);
+        })
+        if (pageHeight) {
+            pdfOptions['height'] = pageHeight + 1 + 'px'
+        }
+    }
+
+    return pdfOptions
+}
+
+/**
+ * Extracts the navigation parameters from the configuration in a format that is usable by Puppeteer.
+ * @param {Configuration} configuration - The configuration to extract the navigation parameters from.
+ * @returns {NavigationParameters}
+ * The extracted navigation parameters.
+ */
+exports.getNavigationParameters = function (configuration) {
+    return {
+        timeout: configuration.userOptions.navigationTimeout,
+        waituntil: configuration.userOptions.navigationWaitUntil
+    }
+}
+
+
+/**
+ * Extracts the waiting parameters from the configuration in a format that is usable by Puppeteer.
+ * @param {Configuration} configuration - The configuration to extract the waiting parameters from.
+ * @returns {WaitingParameters} 
+ * The extracted waiting parameters.
+ */
+exports.getWaitingParameters = function (configuration) {
+    return {
+        timeout: configuration.userOptions.navigationTimeout
+    }
+}