screentake 0.1.0

data/lib/screentake/drivers/cloudflare.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Screentake
+  module Drivers
+    class Cloudflare < Base
+      MAX_RETRIES = 3
+      INITIAL_BACKOFF = 1.0 # seconds
+
+      def initialize(account_id: nil, api_token: nil)
+        super()
+        config = Screentake.configuration
+        @account_id = account_id || config.cloudflare_account_id
+        @api_token = api_token || config.cloudflare_api_token
+        validate_credentials!
+      end
+
+      def screenshot(source:, type:, options:)
+        body = build_request_body(source, type, options)
+        response = perform_request(body)
+        handle_response(response)
+      end
+
+      private
+
+      def validate_credentials!
+        if @account_id.nil? || @account_id.to_s.strip.empty?
+          raise AuthenticationError,
+            "Cloudflare account ID is required. Set it via Screentake.configure or CLOUDFLARE_ACCOUNT_ID env var."
+        end
+
+        return unless @api_token.nil? || @api_token.to_s.strip.empty?
+
+        raise AuthenticationError,
+          "Cloudflare API token is required. Set it via Screentake.configure or CLOUDFLARE_API_TOKEN env var."
+      end
+
+      def endpoint_uri
+        URI("https://api.cloudflare.com/client/v4/accounts/#{@account_id}/browser-rendering/screenshot")
+      end
+
+      def build_request_body(source, type, options)
+        body = {}
+
+        # Source
+        if type == :url
+          body["url"] = source
+        else
+          body["html"] = source
+        end
+
+        # Viewport
+        body["viewport"] = {
+          "width" => options[:width],
+          "height" => options[:height],
+          "deviceScaleFactor" => options[:scale],
+        }
+
+        # Screenshot options
+        screenshot_opts = {}
+        screenshot_opts["fullPage"] = options[:full_page] if options[:full_page]
+        screenshot_opts["omitBackground"] = true if options[:transparent]
+
+        format = options[:format]
+        screenshot_opts["type"] = format == :jpeg ? "jpeg" : format.to_s
+
+        screenshot_opts["quality"] = options[:quality] if options[:quality] && format != :png
+
+        if options[:clip]
+          screenshot_opts["clip"] = {
+            "x" => options[:clip][:x],
+            "y" => options[:clip][:y],
+            "width" => options[:clip][:width],
+            "height" => options[:clip][:height],
+          }
+        end
+
+        body["screenshotOptions"] = screenshot_opts unless screenshot_opts.empty?
+
+        # Selector
+        body["selector"] = options[:selector] if options[:selector]
+
+        # Navigation / wait options
+        goto_options = {}
+        goto_options["waitUntil"] = options[:wait_until].to_s if options[:wait_until]
+        goto_options["timeout"] = Screentake.configuration.timeout
+        body["gotoOptions"] = goto_options unless goto_options.empty?
+
+        # Wait for selector
+        if options[:wait_for_selector]
+          body["waitForSelector"] = { "selector" => options[:wait_for_selector] }
+        end
+
+        # Wait for timeout (additional delay)
+        body["waitForTimeout"] = options[:wait_for_timeout] if options[:wait_for_timeout]
+
+        body
+      end
+
+      def perform_request(body)
+        uri = endpoint_uri
+        retries = 0
+
+        loop do
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 10
+          http.read_timeout = (Screentake.configuration.timeout / 1000.0).ceil + 5
+
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Authorization"] = "Bearer #{@api_token}"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+
+          log_request(body)
+
+          response = http.request(request)
+
+          if response.code == "429" && retries < MAX_RETRIES
+            retries += 1
+            backoff = INITIAL_BACKOFF * (2**(retries - 1))
+            log_retry(retries, backoff)
+            sleep(backoff)
+            next
+          end
+
+          return response
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          raise Screentake::TimeoutError, "Request to Cloudflare timed out: #{e.message}"
+        rescue StandardError => e
+          raise Screentake::DriverError, "Cloudflare request failed: #{e.message}"
+        end
+      end
+
+      def handle_response(response)
+        case response.code
+        when "200"
+          response.body
+        when "400"
+          error_message = parse_error(response)
+          if error_message&.include?("selector")
+            raise Screentake::ElementNotFoundError, "Element not found: #{error_message}"
+          end
+
+          raise Screentake::RenderError, "Cloudflare rendering failed: #{error_message}"
+        when "401", "403"
+          raise Screentake::AuthenticationError,
+            "Cloudflare authentication failed. Check your API token and account ID."
+        when "429"
+          raise Screentake::RateLimitError,
+            "Cloudflare rate limit exceeded. Max 2 browsers/minute, 2 concurrent."
+        else
+          error_message = parse_error(response)
+          raise Screentake::CloudflareError,
+            "Cloudflare API error (HTTP #{response.code}): #{error_message}"
+        end
+      end
+
+      def parse_error(response)
+        data = JSON.parse(response.body)
+        if data.is_a?(Hash) && data["errors"]
+          data["errors"].map { |e| e["message"] }.join(", ")
+        else
+          response.body
+        end
+      rescue JSON::ParserError
+        response.body
+      end
+
+      def log_request(body)
+        logger = Screentake.configuration.logger
+        return unless logger
+
+        logger.debug("[Screentake] Cloudflare screenshot request: #{body.reject { |k, _| k == "html" }.inspect}")
+      end
+
+      def log_retry(attempt, backoff)
+        logger = Screentake.configuration.logger
+        return unless logger
+
+        logger.warn("[Screentake] Rate limited, retrying (#{attempt}/#{MAX_RETRIES}) after #{backoff}s")
+      end
+    end
+  end
+end

data/lib/screentake/drivers/ferrum.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Screentake
+  module Drivers
+    class Ferrum < Base
+      FERRUM_REQUIRE_ERROR = "Ferrum driver requires the 'ferrum' gem. Add gem 'ferrum' to your Gemfile."
+      CHROME_NOT_FOUND_MSG = "Chrome/Chromium not found. Install Chrome or set config.ferrum_options[:browser_path]."
+      WAIT_POLL_INTERVAL = 0.05 # seconds
+
+      def initialize
+        super()
+        require_ferrum!
+        at_exit { quit }
+      end
+
+      def screenshot(source:, type:, options:)
+        context = browser.contexts.create
+        page = context.create_page
+        begin
+          configure_viewport(page, options)
+          navigate(page, source, type)
+          apply_wait_strategies(page, options)
+          take_screenshot(page, options)
+        rescue ::Ferrum::TimeoutError => e
+          raise Screentake::TimeoutError, e.message
+        rescue ::Ferrum::NodeNotFoundError => e
+          raise Screentake::ElementNotFoundError, e.message
+        rescue ::Ferrum::StatusError => e
+          raise Screentake::RenderError, e.message
+        rescue ::Ferrum::DeadBrowserError => e
+          reset_browser!
+          raise Screentake::BrowserCrashedError, e.message
+        rescue ::Ferrum::ProcessTimeoutError => e
+          reset_browser!
+          raise Screentake::BrowserCrashedError, e.message
+        rescue ::Ferrum::Error => e
+          raise Screentake::FerrumError, e.message
+        ensure
+          context&.dispose
+        end
+      end
+
+      # Shut down the browser process. Called by reset_configuration! and at_exit.
+      def quit
+        return unless @browser
+
+        log(:info, "Quitting browser")
+        @browser.quit
+        @browser = nil
+      rescue StandardError
+        @browser = nil
+      end
+
+      private
+
+      def require_ferrum!
+        require "ferrum"
+      rescue LoadError
+        raise Screentake::DriverError, FERRUM_REQUIRE_ERROR
+      end
+
+      def browser
+        @browser ||= begin
+          opts = Screentake.configuration.ferrum_options.dup
+          log(:info, "Launching browser")
+          ::Ferrum::Browser.new(**opts)
+        rescue ::Ferrum::ProcessTimeoutError
+          raise Screentake::BrowserNotFoundError, CHROME_NOT_FOUND_MSG
+        end
+      end
+
+      def reset_browser!
+        @browser&.quit rescue nil # rubocop:disable Style/RescueModifier
+        @browser = nil
+      end
+
+      def configure_viewport(page, options)
+        page.set_viewport(
+          width: options[:width],
+          height: options[:height],
+          scale_factor: options[:scale],
+        )
+      end
+
+      def navigate(page, source, type)
+        if type == :url
+          log(:debug, "Navigating to #{source}")
+          page.go_to(source)
+        else
+          log(:debug, "Loading HTML content (#{source.length} bytes)")
+          page.content = source
+        end
+      end
+
+      def apply_wait_strategies(page, options)
+        apply_network_wait(page, options[:wait_until])
+        wait_for_selector(page, options[:wait_for_selector]) if options[:wait_for_selector]
+        sleep(options[:wait_for_timeout] / 1000.0) if options[:wait_for_timeout]
+      end
+
+      def apply_network_wait(page, wait_until)
+        case wait_until
+        when :networkidle0
+          page.network.wait_for_idle(connections: 0)
+        when :networkidle2
+          page.network.wait_for_idle(connections: 2)
+        when :domcontentloaded, :load
+          # Navigation already waited for load; no extra wait needed
+          nil
+        end
+      end
+
+      def wait_for_selector(page, selector)
+        timeout_sec = Screentake.configuration.timeout / 1000.0
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_sec
+
+        loop do
+          return if page.at_css(selector)
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise Screentake::TimeoutError, "Timed out waiting for selector: #{selector}"
+          end
+
+          sleep(WAIT_POLL_INTERVAL)
+        end
+      end
+
+      def take_screenshot(page, options)
+        screenshot_opts = build_screenshot_opts(options)
+        log(:debug, "Screenshot options: #{screenshot_opts.inspect}")
+        page.screenshot(**screenshot_opts)
+      end
+
+      def build_screenshot_opts(options)
+        opts = { encoding: :binary }
+
+        # Format
+        format = options[:format]
+        opts[:format] = format.to_s
+
+        # Quality (jpeg/webp only)
+        opts[:quality] = options[:quality] if options[:quality] && format != :png
+
+        # Full page
+        opts[:full] = true if options[:full_page]
+
+        # Selector
+        opts[:selector] = options[:selector] if options[:selector]
+
+        # Clip region
+        if options[:clip]
+          opts[:area] = {
+            x: options[:clip][:x].to_i,
+            y: options[:clip][:y].to_i,
+            width: options[:clip][:width].to_i,
+            height: options[:clip][:height].to_i,
+          }
+        end
+
+        # Transparent background
+        if options[:transparent]
+          opts[:background_color] = ::Ferrum::RGBA.new(0, 0, 0, 0.0)
+        end
+
+        opts
+      end
+
+      def log(level, message)
+        logger = Screentake.configuration.logger
+        return unless logger
+
+        logger.public_send(level, "[Screentake] Ferrum: #{message}")
+      end
+    end
+  end
+end

data/lib/screentake/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Screentake
+  # Base error class for all Screentake errors
+  class Error < StandardError; end
+
+  # Raised when a required method is not implemented by a subclass
+  class NotImplementedError < Error; end
+
+  # Raised when a URL is malformed or invalid
+  class InvalidUrlError < Error; end
+
+  # Raised when HTML content is invalid
+  class InvalidHtmlError < Error; end
+
+  # Raised when viewport dimensions are out of range
+  class InvalidDimensionError < Error; end
+
+  # Raised when an option value is invalid
+  class InvalidOptionError < Error; end
+
+  # Raised when a clip region is invalid
+  class InvalidClipError < Error; end
+
+  # Raised when a CSS selector matches no elements
+  class ElementNotFoundError < Error; end
+
+  # Raised when an operation exceeds its timeout
+  class TimeoutError < Error; end
+
+  # Raised when the rendering engine fails
+  class RenderError < Error; end
+
+  # Base error for driver-specific failures
+  class DriverError < Error; end
+
+  # Base error for Cloudflare driver failures
+  class CloudflareError < DriverError; end
+
+  # Raised when Cloudflare returns a 429 rate limit response
+  class RateLimitError < CloudflareError; end
+
+  # Raised when Cloudflare API authentication fails
+  class AuthenticationError < CloudflareError; end
+
+  # Base error for Ferrum driver failures
+  class FerrumError < DriverError; end
+
+  # Raised when Chrome/Chromium binary not found
+  class BrowserNotFoundError < FerrumError; end
+
+  # Raised when browser process crashes or becomes unresponsive
+  class BrowserCrashedError < FerrumError; end
+end

data/lib/screentake/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Screentake
+  class Railtie < ::Rails::Railtie
+    initializer "screentake.configure" do
+      config = Screentake.configuration
+      config.logger ||= Rails.logger
+
+      if config.cloudflare_account_id.nil?
+        config.cloudflare_account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID", nil)
+      end
+
+      if config.cloudflare_api_token.nil?
+        config.cloudflare_api_token =  ENV.fetch("CLOUDFLARE_API_TOKEN", nil)
+      end
+    end
+  end
+end

data/lib/screentake/screenshot.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "uri"
+require "base64"
+require "pathname"
+
+module Screentake
+  class Screenshot
+    VALID_FORMATS = [:png, :jpeg, :webp].freeze
+    VALID_WAIT_UNTIL = [:load, :domcontentloaded, :networkidle0, :networkidle2].freeze
+    MIN_DIMENSION = 1
+    MAX_DIMENSION = 10_000
+    MIN_SCALE = 1
+    MAX_SCALE = 4
+    MIN_QUALITY = 1
+    MAX_QUALITY = 100
+    MAX_WAIT_TIMEOUT = 30_000
+
+    attr_reader :options
+
+    def initialize(**kwargs)
+      @options = build_options(**kwargs)
+      validate!
+    end
+
+    # Save screenshot to a file path. Returns the path.
+    def save(path)
+      path = Pathname(path)
+      resolved = resolve_format_from_path(path)
+      data = perform_capture(resolved)
+      path.dirname.mkpath
+      path.binwrite(data)
+      path.to_s
+    end
+
+    # Return raw binary screenshot data.
+    def capture
+      perform_capture(@options)
+    end
+
+    # Return base64-encoded screenshot data.
+    def base64
+      Base64.strict_encode64(capture)
+    end
+
+    # Return a hash of all resolved options for debugging.
+    def debug
+      {
+        source_type: @options[:source_type],
+        source: @options[:source_type] == :url ? @options[:url] : "(html)",
+        width: @options[:width],
+        height: @options[:height],
+        scale: @options[:scale],
+        format: @options[:format],
+        quality: @options[:quality],
+        full_page: @options[:full_page],
+        selector: @options[:selector],
+        clip: @options[:clip],
+        transparent: @options[:transparent],
+        wait_until: @options[:wait_until],
+        wait_for_selector: @options[:wait_for_selector],
+        wait_for_timeout: @options[:wait_for_timeout],
+        driver: Screentake.configuration.driver,
+      }
+    end
+
+    private
+
+    def build_options(**kwargs)
+      config = Screentake.configuration
+
+      source_type, source_value = resolve_source(kwargs[:url], kwargs[:html])
+      width, height = resolve_dimensions(kwargs, config)
+
+      {
+        source_type: source_type,
+        url: source_type == :url ? source_value : nil,
+        html: source_type == :html ? source_value : nil,
+        width: width,
+        height: height,
+        scale: kwargs.fetch(:scale, config.default_scale),
+        format: kwargs.fetch(:format, config.default_format),
+        quality: kwargs[:quality],
+        full_page: kwargs.fetch(:full_page, false),
+        selector: kwargs[:selector],
+        clip: kwargs[:clip],
+        transparent: kwargs.fetch(:transparent, false),
+        wait_until: kwargs.fetch(:wait_until, :networkidle0),
+        wait_for_selector: kwargs[:wait_for_selector],
+        wait_for_timeout: kwargs[:wait_for_timeout],
+      }
+    end
+
+    def resolve_source(url, html)
+      if url && html
+        raise ArgumentError, "Cannot specify both url: and html: options"
+      end
+
+      if url
+        [:url, url]
+      elsif html
+        [:html, html]
+      else
+        raise ArgumentError, "Must specify either url: or html: option"
+      end
+    end
+
+    def resolve_dimensions(kwargs, config)
+      if kwargs[:size]
+        size = kwargs[:size]
+        unless size.is_a?(Array) && size.length == 2
+          raise InvalidDimensionError, "size: must be a [width, height] array"
+        end
+
+        [size[0], size[1]]
+      else
+        [
+          kwargs.fetch(:width, config.default_viewport[:width]),
+          kwargs.fetch(:height, config.default_viewport[:height]),
+        ]
+      end
+    end
+
+    def validate!
+      validate_source!
+      validate_dimensions!
+      validate_scale!
+      validate_format!
+      validate_quality!
+      validate_clip!
+      validate_wait!
+    end
+
+    def validate_source!
+      if @options[:source_type] == :url
+        validate_url!(@options[:url])
+      else
+        validate_html!(@options[:html])
+      end
+    end
+
+    def validate_url!(url)
+      uri = URI.parse(url)
+      unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+        raise InvalidUrlError, "URL must use http or https scheme: #{url}"
+      end
+    rescue URI::InvalidURIError
+      raise InvalidUrlError, "Malformed URL: #{url}"
+    end
+
+    def validate_html!(html)
+      unless html.is_a?(String) && !html.strip.empty?
+        raise InvalidHtmlError, "HTML must be a non-empty string"
+      end
+    end
+
+    def validate_dimensions!
+      [:width, :height].each do |dim|
+        value = @options[dim]
+        unless value.is_a?(Integer) && value >= MIN_DIMENSION && value <= MAX_DIMENSION
+          raise InvalidDimensionError,
+            "#{dim}: must be an integer between #{MIN_DIMENSION} and #{MAX_DIMENSION}, got #{value.inspect}"
+        end
+      end
+    end
+
+    def validate_scale!
+      scale = @options[:scale]
+      unless scale.is_a?(Numeric) && scale >= MIN_SCALE && scale <= MAX_SCALE
+        raise InvalidOptionError,
+          "scale: must be between #{MIN_SCALE} and #{MAX_SCALE}, got #{scale.inspect}"
+      end
+    end
+
+    def validate_format!
+      format = @options[:format]
+      unless VALID_FORMATS.include?(format)
+        raise InvalidOptionError,
+          "format: must be one of #{VALID_FORMATS.inspect}, got #{format.inspect}"
+      end
+    end
+
+    def validate_quality!
+      quality = @options[:quality]
+      return if quality.nil?
+
+      if @options[:format] == :png
+        raise InvalidOptionError, "quality: is not supported for PNG format"
+      end
+
+      unless quality.is_a?(Integer) && quality >= MIN_QUALITY && quality <= MAX_QUALITY
+        raise InvalidOptionError,
+          "quality: must be an integer between #{MIN_QUALITY} and #{MAX_QUALITY}, got #{quality.inspect}"
+      end
+    end
+
+    def validate_clip!
+      clip = @options[:clip]
+      return if clip.nil?
+
+      required_keys = [:x, :y, :width, :height]
+      missing = required_keys - clip.keys
+      unless missing.empty?
+        raise InvalidClipError, "clip: missing required keys: #{missing.inspect}"
+      end
+
+      clip.each do |key, value|
+        unless value.is_a?(Numeric) && value >= 0
+          raise InvalidClipError, "clip[:#{key}] must be a non-negative number, got #{value.inspect}"
+        end
+      end
+    end
+
+    def validate_wait!
+      wait_until = @options[:wait_until]
+      unless VALID_WAIT_UNTIL.include?(wait_until)
+        raise InvalidOptionError,
+          "wait_until: must be one of #{VALID_WAIT_UNTIL.inspect}, got #{wait_until.inspect}"
+      end
+
+      timeout = @options[:wait_for_timeout]
+      return if timeout.nil?
+
+      unless timeout.is_a?(Numeric) && timeout > 0 && timeout <= MAX_WAIT_TIMEOUT
+        raise InvalidOptionError,
+          "wait_for_timeout: must be between 1 and #{MAX_WAIT_TIMEOUT}, got #{timeout.inspect}"
+      end
+    end
+
+    def resolve_format_from_path(path)
+      ext = path.extname.downcase.delete(".")
+      format = case ext
+      when "jpg", "jpeg" then :jpeg
+      when "webp" then :webp
+      when "png" then :png
+      else @options[:format]
+      end
+      @options.merge(format: format)
+    end
+
+    def perform_capture(opts)
+      driver = Screentake.driver
+      driver.screenshot(
+        source: opts[:source_type] == :url ? opts[:url] : opts[:html],
+        type: opts[:source_type],
+        options: opts,
+      )
+    end
+  end
+end

data/lib/screentake/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Screentake
+  VERSION = "0.1.0"
+end