Dhalang 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 835393ff0f501220a6c71edd20db19897e874b578f0921b37f70b5403840c928
-  data.tar.gz: 285639cb8e59c0416d82a15c15ef7e656c00e5d2498b19f885d8635dafc05314
+  metadata.gz: 4bd71cb9e8eb643b85d2d2e68909db725b088b10ef29cd717634bc5429067ed4
+  data.tar.gz: 77b10c45d0c30132e3888c2cc04998502b34ae24a0e363e70b971987ec6a722c
 SHA512:
-  metadata.gz: aeacd63e036366dcd4f61da1b06fe65965378c6d4dba61de5401daa67f7f3f06744f01e7e4d24bd0d28a157e052eb5ff597695e978f73b9290594787ef48a482
-  data.tar.gz: 1888bee0d744f67529fa7927740fbe057ceb73c571c3d06d7de74e24ee028f0769592bc7107bb1696e31e448fd02f7ead676b57f0a94bb2d8ee68192e1382c18
+  metadata.gz: d36638644a8b02e167b76f4b943b527fd06dd20cdc6ef4c77ce37af1e41bb24f4f03f13549b0b3cfcd9a1693b7aad535448ebbfd01b6a54cb53be39d32bbd063
+  data.tar.gz: e31806a5c74557130c558eda263a0b72045814db398c1554fe5bfaa5ce0240f14b22b52ce1afd1d8c488936097a8c407ff255c53c166cf346054d57cff749c80

data/README.md

@@ -3,11 +3,14 @@
 > Dhalang is a Ruby wrapper for Google's Puppeteer.
 
 
+
 ## Features
 * Generate PDFs from pages
 * Generate PDFs from html ( external images/stylesheets supported )  
 * Capture a screenshot of a webpage
 
+
+
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -40,21 +43,43 @@ All methods return a string containing the PDF or JPEG/PNG in binary.
   
   
   
-## Custom configuration
-Depending on your use case you may want to change the way Dhalang interacts with Puppeteer. You can do this by passing a Hash with custom configuration parameters as last argument to any calls you make to the library.
+## Custom PDF/screenshot options
+To override the default options that are set by Dhalang you can pass as last argument a hash with the custom options you want to set.
+
+For example to set custom margins for PDFs:
+
+`Dhalang::PDF.get_from_url("https://www.google.com", {margin: { top: 100, right: 100, bottom: 100, left: 100}})
+`
+
+For example to only take a screenshot of the visible part of the page:
+`Dhalang::Screenshot.get_from_url_as_png("https://www.google.com", {fullPage: false})
+`
+
+A list of all possible PDF options that can be set, can be found at: https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagepdfoptions
 
-So for example:
-`Dhalang::Screenshot.get_from_url_as_jpeg("https://www.google.com", {navigation_timeout: 20000})`  
+A list of all possible screenshot options that can be set, can be found at: https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagescreenshotoptions
 
-Below table list the possible configuration parameters you can set:
+
+
+
+## Custom user options
+You may want to change the way Dhalang interacts with Puppeteer in general. User options can be set by providing them in a hash as last argument to any calls you make to the library. Are you setting both custom PDF and user options? Then they should be passed as a single hash. 
+
+For example to set a custom navigation timeout:
+`Dhalang::Screenshot.get_from_url_as_jpeg("https://www.google.com", {navigationTimeout: 20000})`  
+
+Below table lists all possible configuration parameters that can be set:
 | Key                | Description                                                                             | Default                         |
 |--------------------|-----------------------------------------------------------------------------------------|---------------------------------|
-| navigation_timeout | Amount of milliseconds until Puppeteer while timeout when navigating to the given page  | 10000                           |
-| user_agent         | User agent to send with the request                                                     | Default Puppeteer one           |
-| view_port          | Custom viewport to use for the request                                                  | Default Puppeteer one           |
-| http_authentication_credentials | Custom HTTP authentication credentials to use for the request              | None                            |
+| navigationTimeout  | Amount of milliseconds until Puppeteer while timeout when navigating to the given page  | 10000                           |
+| userAgent          | User agent to send with the request                                                     | Default Puppeteer one           |
+| isHeadless         | Indicates if Chromium should be launched headless                                       | true                            |
+| viewPort           | Custom viewport to use for the request                                                  | Default Puppeteer one           |
+| httpAuthenticationCredentials | Custom HTTP authentication credentials to use for the request                | None                            |
+
+
 
-## Examples
+## Examples of using Dhalang
 To return a PDF from a Rails controller you can do the following:  
 ```
 def example_controller_method  

data/lib/Dhalang.rb

@@ -4,9 +4,11 @@ module Dhalang
   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'
-end
+  require 'open3'
+end

data/lib/Dhalang/error.rb

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

data/lib/Dhalang/puppeteer.rb

@@ -4,22 +4,17 @@ module Dhalang
         NODE_MODULES_PATH = Dir.pwd + '/node_modules/'.freeze
         private_constant :NODE_MODULES_PATH
 
-        NAVIGATION_TIMEOUT = 10000
-        private_constant :NAVIGATION_TIMEOUT
-
-        NAVIGATION_WAIT_UNTIL = 'load'
-        private_constant :NAVIGATION_WAIT_UNTIL
-
-        USER_AGENT = ''
-        private_constant :USER_AGENT
-
-        VIEW_PORT = ''
-        private_constant :VIEW_PORT
-
-        HTTP_AUTHENTICATION_CREDENTIALS = ''
-        private_constant :HTTP_AUTHENTICATION_CREDENTIALS
+        USER_OPTIONS = {
+                navigationTimeout: 10000,
+                navigationWaitUntil: 'load',
+                userAgent: '',
+                isHeadless: true,
+                viewPort: '',
+                httpAuthenticationCredentials: ''
+        }
+        private_constant :USER_OPTIONS
 
-        DEFAULT_OPTIONS = {
+        DEFAULT_PDF_OPTIONS = {
             scale: 1,
             displayHeaderFooter: false,
             headerTemplate: '',
@@ -33,7 +28,22 @@ module Dhalang
             margin: { top: 36, right: 36, bottom: 20, left: 36 },
             preferCSSPageSiz: false
         }
-        private_constant :DEFAULT_OPTIONS
+        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.
@@ -45,7 +55,17 @@ module Dhalang
         # @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)
-            Kernel.system("node #{script_path} #{Shellwords.escape(configuration)}")
+
+            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
 
 
@@ -62,16 +82,10 @@ module Dhalang
                 tempFilePath: temp_file_path,
                 puppeteerPath: NODE_MODULES_PATH,
                 imageType: temp_file_extension,
-                userOptions: {
-                    navigationParameters: {
-                        timeout: options.has_key?(:navigation_timeout) ? options[:navigation_timeout] : NAVIGATION_TIMEOUT,
-                        waitUntil: NAVIGATION_WAIT_UNTIL
-                    },
-                    userAgent: options.has_key?(:user_agent) ? options[:user_agent] : USER_AGENT,
-                    viewPort: options.has_key?(:view_port) ? options[:view_port] : VIEW_PORT,
-                    httpAuthenticationCredentials: options.has_key?(:http_authentication_credentials) ? options[:http_authentication_credentials] : HTTP_AUTHENTICATION_CREDENTIALS
-                },
-                pdfOptions: DEFAULT_OPTIONS.map { |option, value| [option, options.has_key?(option) ? options[option] : value] }.to_h
+                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

data/lib/Dhalang/version.rb

@@ -1,3 +1,3 @@
 module Dhalang
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/Screenshot.rb

@@ -33,6 +33,7 @@ module Dhalang
     # @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)
@@ -42,5 +43,15 @@ module Dhalang
       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

@@ -4,14 +4,20 @@
  * @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 with Puppeteer.
+ * @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.
+ * @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 {NavigationParameters} navigationParameters    - The parameters to use when navigating to pages with Puppeteer.
- * @property {string} userAgent                             - The user agent to send with requests.
- * @property {Object} viewPort                              - The view port to use.
- * @property {Object} httpAuthenticationCredentials         - The credentials to use for HTTP authentication.
+ * @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} 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.
  */
 
 /**
@@ -31,15 +37,17 @@ exports.getConfiguration = function () {
 
 /**
  * Launches Puppeteer and returns its instance.
- * @param {string} puppeteerModulePath - The path puppeteer is under.
+ * @param {UserOptions} configuration - The configuration to use.
  * @returns {Promise<Object>} 
  * The launched instance of Puppeteer.
  */
-exports.launchPuppeteer = async function (puppeteerModulePath) {
-    module.paths.push(puppeteerModulePath);
+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: ['--no-sandbox', '--disable-setuid-sandbox']
+        args: launchArgs,
+        headless: configuration.userOptions.isHeadless
     });
 }
 
@@ -60,4 +68,17 @@ exports.configurePage = async function (page, configuration) {
     if (configuration.httpAuthenticationCredentials !== "") {
         await page.authenticate(configuration.authenticationCredentials)
     }
+}
+
+/**
+ * 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
+    }
 }

data/lib/js/pdf-generator.js

@@ -6,10 +6,10 @@ const createPdf = async () => {
 
     let browser;
     try {
-        browser = await dhalang.launchPuppeteer(configuration.puppeteerPath);
+        browser = await dhalang.launchPuppeteer(configuration);
         const page = await browser.newPage();
         await dhalang.configurePage(page, configuration.userOptions);
-        await page.goto(configuration.webPageUrl, configuration.userOptions.navigationParameters);
+        await page.goto(configuration.webPageUrl, dhalang.getNavigationParameters(configuration));
         await page.waitForTimeout(250);
         await page.pdf({
             ...{
@@ -18,7 +18,8 @@ const createPdf = async () => {
             ...configuration.pdfOptions
         });
     } catch (error) {
-        console.log(error.message);
+        console.error(error.message);
+        process.exit(1);
     } finally {
         if (browser) {
             browser.close();

data/lib/js/screenshot-generator.js

@@ -6,18 +6,22 @@ const createPdf = async () => {
 
     let browser;
     try {
-        browser = await dhalang.launchPuppeteer(configuration.puppeteerPath);
+        browser = await dhalang.launchPuppeteer(configuration);
         const page = await browser.newPage();
         await dhalang.configurePage(page, configuration.userOptions);
-        await page.goto(configuration.webPageUrl, configuration.userOptions.navigationParameters);
+        await page.goto(configuration.webPageUrl, dhalang.getNavigationParameters(configuration));
         await page.waitForTimeout(250);
+        const screenshotOptions = configuration.imageType === "png" ? configuration.pngOptions : configuration.jpegOptions
         await page.screenshot({
-            path: configuration.tempFilePath,
-            type: configuration.imageType,
-            fullPage: true
+            ...{
+                path: configuration.tempFilePath,
+                type: configuration.imageType,
+            },
+            ...screenshotOptions
         });
     } catch (error) {
-        console.log(error.message);
+        console.error(error.message);
+        process.exit(1);
     } finally {
         if (browser) {
             browser.close();

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dhalang",
-  "version": "1.0.0",
+  "version": "0.5.0",
   "description": "",
   "main": "index.js",
   "directories": {
@@ -14,7 +14,7 @@
     "url": "git+https://github.com/NielsSteensma/Dhalang.git"
   },
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/NielsSteensma/Dhalang/issues"
   },

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: Dhalang
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Niels Steensma
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-10-29 00:00:00.000000000 Z
+date: 2020-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,6 +96,7 @@ files:
 - README.md
 - Rakefile
 - lib/Dhalang.rb
+- lib/Dhalang/error.rb
 - lib/Dhalang/file_utils.rb
 - lib/Dhalang/puppeteer.rb
 - lib/Dhalang/url_utils.rb