Module: Html2img::Request Private

Defined in:
lib/html2img/request.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Builds and validates the JSON bodies sent to the render endpoints.

The range checks mirror the server-side validation rules, so an obvious mistake fails fast with a clear message before a request is sent, and before a credit is spent. Any option left nil is omitted from the body, so the server applies its own default.

Constant Summary collapse

MIN_DIMENSION =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

1
MAX_DIMENSION =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

5000
MIN_DPI =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

1
MAX_DPI =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

4
MIN_MS_DELAY =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

1
MAX_MS_DELAY =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

5000
FORMATS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

%w[png pdf].freeze
COMMON_OPTIONS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Options accepted by both render endpoints.

%i[
  css width height fullpage dpi webhook_url ms_delay wait_for_selector format scale_to_fit
].freeze
SCREENSHOT_OPTIONS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

selector crops a screenshot to one element. There is no equivalent for an HTML render, since you control the markup.

(COMMON_OPTIONS + %i[selector]).freeze

Class Method Summary collapse

Class Method Details

.boolean!(name, value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError) 


100
101
102
103
104
105
 
# File 'lib/html2img/request.rb', line 100

def boolean!(name, value)
  return nil if value.nil?
  return value if [true, false].include?(value)

  raise ArgumentError, "The #{name} must be true or false, got #{value.inspect}."
end

.common(options) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The options shared by both endpoints, mapped onto their API field names.



59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/html2img/request.rb', line 59

def common(options)
  {
    "css" => optional_string!("css", options[:css]),
    "width" => dimension!("width", options[:width]),
    "height" => dimension!("height", options[:height]),
    "fullpage" => boolean!("fullpage", options[:fullpage]),
    "dpi" => dpi!(options[:dpi]),
    "webhook_url" => optional_string!("webhook_url", options[:webhook_url]),
    "ms_delay" => ms_delay!(options[:ms_delay]),
    "wait_for_selector" => optional_string!("wait_for_selector", options[:wait_for_selector]),
    "format" => format!(options[:format]),
    "scale_to_fit" => boolean!("scale_to_fit", options[:scale_to_fit])
  }
end

.dimension!(name, value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



107
108
109
 
# File 'lib/html2img/request.rb', line 107

def dimension!(name, value)
  integer_in_range!(name, value, MIN_DIMENSION, MAX_DIMENSION)
end

.dpi!(value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



111
112
113
 
# File 'lib/html2img/request.rb', line 111

def dpi!(value)
  integer_in_range!("dpi", value, MIN_DPI, MAX_DPI)
end

.format!(value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError) 


131
132
133
134
135
136
137
138
139
 
# File 'lib/html2img/request.rb', line 131

def format!(value)
  return nil if value.nil?

  normalised = value.to_s.downcase

  return normalised if FORMATS.include?(normalised)

  raise ArgumentError, "The format must be one of: #{FORMATS.join(", ")}. Got #{value.inspect}."
end

.html_body(html, options) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Build the body for POST /api/html.

Parameters:

  • html (String) —

    a complete HTML document

Returns:

  • (Hash) 


37
38
39
40
41
42
43
 
# File 'lib/html2img/request.rb', line 37

def html_body(html, options)
  validate_keys!(options, COMMON_OPTIONS)

  body = { "html" => required_string!("html", html) }

  body.merge(common(options)).compact
end

.integer_in_range!(name, value, low, high) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError) 


119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/html2img/request.rb', line 119

def integer_in_range!(name, value, low, high)
  return nil if value.nil?

  raise ArgumentError, "The #{name} must be an Integer, got #{value.class}." unless value.is_a?(Integer)

  unless value.between?(low, high)
    raise ArgumentError, "The #{name} must be between #{low} and #{high}, got #{value}."
  end

  value
end

.ms_delay!(value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



115
116
117
 
# File 'lib/html2img/request.rb', line 115

def ms_delay!(value)
  integer_in_range!("ms_delay", value, MIN_MS_DELAY, MAX_MS_DELAY)
end

.optional_string!(name, value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError) 


92
93
94
95
96
97
98
 
# File 'lib/html2img/request.rb', line 92

def optional_string!(name, value)
  return nil if value.nil?

  raise ArgumentError, "The #{name} must be a String, got #{value.class}." unless value.is_a?(String)

  value
end

.required_string!(name, value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError) 


84
85
86
87
88
89
90
 
# File 'lib/html2img/request.rb', line 84

def required_string!(name, value)
  raise ArgumentError, "The #{name} must be a String, got #{value.class}." unless value.is_a?(String)

  raise ArgumentError, "The #{name} must not be empty." if value.empty?

  value
end

.screenshot_body(url, options) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Build the body for POST /api/screenshot.

Parameters:

  • url (String) —

    a publicly reachable URL

Returns:

  • (Hash) 


49
50
51
52
53
54
55
56
 
# File 'lib/html2img/request.rb', line 49

def screenshot_body(url, options)
  validate_keys!(options, SCREENSHOT_OPTIONS)

  body = { "url" => required_string!("url", url) }
  body["selector"] = optional_string!("selector", options[:selector])

  body.merge(common(options)).compact
end

.validate_keys!(options, allowed) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError) 


74
75
76
77
78
79
80
81
82
 
# File 'lib/html2img/request.rb', line 74

def validate_keys!(options, allowed)
  unknown = options.keys - allowed

  return if unknown.empty?

  raise ArgumentError,
        "Unknown option(s): #{unknown.join(", ")}. " \
        "Valid options are: #{allowed.sort.join(", ")}."
end