btape 0.1.0 → 0.2.0

data/lib/btape/runner.rb

@@ -2,39 +2,85 @@
 
 require 'fileutils'
 require 'ferrum'
+require 'monitor'
+require 'timeout'
 require 'tmpdir'
 
 module Btape
-  # Drives a headless browser through the parsed commands and captures a
-  # screenshot per step, handing the frames off to GifEncoder.
+  # The recording session around a script: opens the browser, starts the
+  # recorder, hands the commands to Executor, and turns the captured frames
+  # into a GIF.
   class Runner
     DEFAULT_VIEWPORT = [1280, 720].freeze
 
+    # How long unwinding gets. Set Timeout bounds the run, but the thing that
+    # usually trips it is a wedged browser, and both stopping the recorder and
+    # quitting the browser then talk to it — so without a deadline of their
+    # own they would hang the process after the timeout had already fired.
+    CLEANUP_TIMEOUT = 10
+
+    # Everything one run threads through recording, kept in one object rather
+    # than a parameter list that grows with each new command.
+    Context = Struct.new(:commands, :directory, :settings, :geometry, :sink, :output_path, :on_frame, :keep_frames,
+                         keyword_init: true)
+
+    # An encoder passed here is used as given; otherwise one is built from the
+    # settings the tape and the caller supplied.
     def initialize(browser_factory: lambda { |options|
       Ferrum::Browser.new(**options)
-    }, recorder_class: Recorder, gif_encoder: GifEncoder.new)
+    }, recorder_class: Recorder, gif_encoder: nil, logger: NullLogger.new)
       @browser_factory = browser_factory
       @recorder_class = recorder_class
       @gif_encoder = gif_encoder
+      @logger = logger
     end
 
-    def run(commands, base_directory: Dir.pwd)
-      output_path = resolve_output_path(commands, base_directory)
-      width, height = resolve_viewport(commands)
-
-      Dir.mktmpdir('btape-') { |directory| record(commands, directory, width, height, output_path) }
-      output_path
+    # Returns a Result. Pass `frames_directory:` to keep the PNG frames after
+    # the run, `on_frame:` to be handed each one as it is captured, and
+    # `output:` to override the tape's Output with another path or with an IO
+    # to write the GIF into.
+    def run(commands, base_directory: Dir.pwd, settings: {}, frames_directory: nil, on_frame: nil, output: nil)
+      settings = Settings.from_commands(commands).merge(settings)
+      sink, output_path = resolve_output(commands, base_directory, output)
+      context = Context.new(
+        commands: commands,
+        settings: settings,
+        geometry: resolve_viewport(commands),
+        sink: sink,
+        output_path: output_path,
+        on_frame: on_frame,
+        keep_frames: !frames_directory.nil?
+      )
+
+      within_frames_directory(frames_directory, base_directory) do |directory|
+        context.directory = directory
+        record(context)
+      end
     end
 
     private
 
-    def resolve_output_path(commands, base_directory)
-      output = commands.find { |command| command.name == 'Output' }&.arguments&.first
-      raise Error, 'script must contain an Output command' unless output
+    # Frames go to a temporary directory that is cleaned up as the run
+    # unwinds, unless the caller named a directory to keep them in.
+    def within_frames_directory(frames_directory, base_directory, &block)
+      return Dir.mktmpdir('btape-', &block) unless frames_directory
+
+      directory = File.expand_path(frames_directory, base_directory)
+      FileUtils.mkdir_p(directory)
+      block.call(directory)
+    end
 
-      path = File.expand_path(output, base_directory)
+    # Returns where the GIF goes and, when that is a file, its path. Writing
+    # into an IO leaves no path behind, so Result reports nil rather than a
+    # path nothing was written to.
+    def resolve_output(commands, base_directory, override)
+      declared = commands.find { |command| command.name == 'Output' }&.arguments&.first
+      raise Error, 'script must contain an Output command' unless declared
+      return [override, nil] if override.respond_to?(:write)
+
+      path = File.expand_path(override || declared, base_directory)
       FileUtils.mkdir_p(File.dirname(path))
-      path
+      [path, path]
     end
 
     def resolve_viewport(commands)
@@ -42,70 +88,108 @@ module Btape
       viewport ? viewport.split('x').map(&:to_i) : DEFAULT_VIEWPORT
     end
 
-    def record(commands, directory, width, height, output_path)
+    def record(context)
       browser = nil
       recorder = nil
+      lock = Monitor.new
       begin
-        browser = @browser_factory.call(window_size: [width, height])
-        recorder = @recorder_class.new(browser, directory)
-        recorder.start
-        execute(commands, browser)
-        recorder.stop
-        @gif_encoder.write(recorder.paths, output_path)
-      ensure
-        begin
-          recorder&.stop
-        rescue StandardError
-          nil
+        timed(context.settings.timeout) do
+          browser = open_browser(context.settings, context.geometry)
+          recorder = build_recorder(browser, context, lock)
+          recorder.start
+          execute(context, browser, recorder, lock)
+          recorder.stop
         end
-        browser&.quit
+        # Outside the deadline: it is there to bound the browser session, and
+        # interrupting a write part-way through would leave a truncated GIF at
+        # the output path that nothing downstream could tell from a whole one.
+        encoder(context.settings).write(recorder.paths, context.sink)
+        result(context, recorder)
+      ensure
+        cleanup(recorder, browser)
       end
     end
 
-    def execute(commands, browser)
-      commands.each do |command|
-        perform(command, browser)
-      rescue StandardError => e
-        raise ScriptError.new(command.line_number, "#{command.name} failed: #{e.message}")
-      end
+    # A page that never finishes loading would otherwise record until the
+    # frame limit or the disk stopped it.
+    def timed(seconds, &)
+      Timeout.timeout(seconds, TimeoutError, "run timed out after #{seconds}s", &)
+    end
+
+    def execute(context, browser, recorder, lock)
+      Executor.new(
+        browser: browser, recorder: recorder, settings: context.settings, lock: lock, logger: @logger
+      ).call(context.commands)
+    end
+
+    # Giving up on the cleanup is not a failure worth raising: the run has
+    # already produced its answer, or its exception, and this is only the
+    # tidying afterwards.
+    def cleanup(recorder, browser)
+      Timeout.timeout(CLEANUP_TIMEOUT) { unwind(recorder, browser) }
+    rescue Timeout::Error
+      @logger.warn("btape: cleanup did not finish within #{CLEANUP_TIMEOUT}s")
     end
 
-    def perform(command, browser)
-      case command.name
-      when 'Output', 'Viewport' then nil
-      when 'Goto' then browser.go_to(command.arguments.first)
-      when 'Click' then find(browser, command.arguments.first).click
-      when 'Type' then type(browser, command.arguments)
-      when 'Sleep' then sleep_seconds(command.arguments.first)
+    # stop and quit are reached again here after they have already run, which
+    # is a no-op; the case that matters is the run failing before them. A
+    # failure to unwind must not replace the exception on its way out, since
+    # that is the one that says why the run failed — so it is logged, not
+    # swallowed and not raised.
+    def unwind(recorder, browser)
+      recorder&.stop
+    rescue StandardError => e
+      @logger.warn("btape: could not stop the recorder: #{e.message}")
+    ensure
+      begin
+        browser&.quit
+      rescue StandardError => e
+        @logger.warn("btape: could not quit the browser: #{e.message}")
       end
     end
 
-    def type(browser, arguments)
-      element = find(browser, arguments.first)
-      element.focus
-      element.type(arguments.last)
+    def encoder(settings)
+      @gif_encoder || GifEncoder.for(settings)
     end
 
-    def find(browser, selector)
-      element = if selector.start_with?('text=')
-                  literal = xpath_literal(selector.delete_prefix('text='))
-                  browser.at_xpath("//*[normalize-space(text())=#{literal}]")
-                else
-                  browser.at_css(selector)
-                end
-      element || raise("element not found: #{selector}")
+    def build_recorder(browser, context, lock)
+      @recorder_class.new(
+        browser,
+        context.directory,
+        interval: 1.0 / context.settings.framerate,
+        mode: context.settings.capture_mode,
+        on_frame: context.on_frame,
+        max_frames: context.settings.max_frames,
+        lock: lock
+      )
     end
 
-    def xpath_literal(text)
-      return %("#{text}") unless text.include?('"')
+    def result(context, recorder)
+      width, height = context.geometry
+      Result.new(
+        output_path: context.output_path,
+        frame_paths: context.keep_frames ? recorder.paths.dup : [],
+        named_frames: context.keep_frames ? recorder.named_paths.dup : {},
+        frame_count: recorder.paths.length,
+        width: width,
+        height: height
+      )
+    end
 
-      parts = text.split('"', -1).map { |part| %("#{part}") }
-      "concat(#{parts.join(%q(, '"', ))})"
+    def open_browser(settings, geometry)
+      width, height = geometry
+      browser = @browser_factory.call(browser_options(settings, geometry))
+      # window_size only ever reaches Chrome as a launch flag, so a browser we
+      # connected to over ws_url keeps whatever size it was started with and
+      # has to be resized over the wire instead.
+      browser.resize(width: width, height: height) if settings.ws_url
+      browser
     end
 
-    def sleep_seconds(duration)
-      value, unit = duration.match(/\A(\d+(?:\.\d+)?)(ms|s)\z/).captures
-      sleep(value.to_f / (unit == 'ms' ? 1000 : 1))
+    def browser_options(settings, geometry)
+      return { ws_url: settings.ws_url } if settings.ws_url
+
+      { window_size: geometry }
     end
   end
 end

data/lib/btape/settings.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative 'duration'
+
+module Btape
+  # The knobs a script turns with `Set NAME VALUE`, along with their defaults,
+  # their coercions, and the validation the parser calls while reading a tape.
+  #
+  # Values arrive from three places, in increasing order of precedence: the
+  # defaults here, the `Set` lines in the tape, and whatever the caller passes
+  # to Runner#run or the CLI passes from its flags.
+  class Settings
+    CAPTURE_MODES = %w[interval manual].freeze
+    QUANTIZERS = %w[adaptive rgb332].freeze
+    URL_SCHEMES = %w[ws:// wss:// http:// https://].freeze
+
+    # Script name => [attribute, coercion, default]. Defaults are already
+    # coerced, so durations are seconds and not "100ms".
+    DEFINITIONS = {
+      'WsUrl' => [:ws_url, :url, nil],
+      'CaptureMode' => [:capture_mode, CAPTURE_MODES, 'interval'],
+      'Framerate' => [:framerate, :positive_float, 10.0],
+      'FrameDelay' => [:frame_delay, :duration, 0.1],
+      'Loop' => [:loop_count, :count, 0],
+      'Scale' => [:scale, :positive_float, 1.0],
+      'OutputWidth' => [:output_width, :positive_integer, nil],
+      'Quantizer' => [:quantizer, QUANTIZERS, 'adaptive'],
+      'Timeout' => [:timeout, :duration, 120.0],
+      'WaitTimeout' => [:wait_timeout, :duration, 10.0],
+      'WaitInterval' => [:wait_interval, :duration, 0.1],
+      'WaitStable' => [:wait_stable, :positive_integer, 1],
+      'MaxFrames' => [:max_frames, :positive_integer, 600]
+    }.freeze
+
+    ATTRIBUTES = DEFINITIONS.each_value.map(&:first).freeze
+
+    ATTRIBUTES.each { |attribute| define_method(attribute) { @values.fetch(attribute) } }
+
+    class << self
+      def defaults
+        DEFINITIONS.each_value.to_h { |attribute, _coercion, default| [attribute, default] }
+      end
+
+      # Validates one `Set` line and returns the coerced value. Raises
+      # ArgumentError, which Parser turns into a ScriptError carrying the line.
+      def validate!(name, value)
+        attribute, coercion, = DEFINITIONS.fetch(name) { raise ArgumentError, "unknown setting #{name.inspect}" }
+        [attribute, coerce(coercion, value, name)]
+      end
+
+      def from_commands(commands)
+        values = commands.select { |command| command.name == 'Set' }.to_h do |command|
+          validate!(*command.arguments)
+        rescue ArgumentError => e
+          raise ScriptError.new(command.line_number, e.message)
+        end
+        new(values)
+      end
+
+      private
+
+      def coerce(coercion, value, name)
+        return enum(coercion, value, name) if coercion.is_a?(Array)
+
+        case coercion
+        when :duration then duration(value, name)
+        when :url then url(value, name)
+        when :count then integer(value, name, minimum: 0)
+        when :positive_integer then integer(value, name, minimum: 1)
+        when :positive_float then positive_float(value, name)
+        end
+      end
+
+      def enum(allowed, value, name)
+        return value if allowed.include?(value)
+
+        raise ArgumentError, "Set #{name} must be one of #{allowed.join(', ')}"
+      end
+
+      def duration(value, name)
+        raise ArgumentError, "Set #{name} #{Duration::DESCRIPTION}" unless Duration.valid?(value)
+
+        Duration.parse(value)
+      end
+
+      # A String key means the value has not been coerced yet, but nothing
+      # says it arrived as a String: `merge('Loop' => 3)` is a reasonable
+      # thing for a caller to write. These read it as the text a Set line
+      # would have carried, so a value of the wrong type fails validation
+      # rather than raising TypeError past the ArgumentError rescue.
+      def url(value, name)
+        text = value.to_s
+        return text if URL_SCHEMES.any? { |scheme| text.start_with?(scheme) }
+
+        raise ArgumentError, "Set #{name} must start with #{URL_SCHEMES.join(', ')}"
+      end
+
+      def integer(value, name, minimum:)
+        text = value.to_s
+        number = Integer(text, 10) if /\A\d+\z/.match?(text)
+        raise ArgumentError, "Set #{name} must be an integer of at least #{minimum}" if number.nil? || number < minimum
+
+        number
+      end
+
+      def positive_float(value, name)
+        text = value.to_s
+        number = Float(text) if /\A\d+(?:\.\d+)?\z/.match?(text)
+        raise ArgumentError, "Set #{name} must be a positive number" unless number&.positive?
+
+        number
+      end
+    end
+
+    def initialize(values = {})
+      @values = defaults_merged_with(values).freeze
+      freeze
+    end
+
+    def merge(overrides)
+      return self if overrides.nil? || (overrides.respond_to?(:empty?) && overrides.empty?)
+
+      self.class.new(@values.merge(normalize(overrides)))
+    end
+
+    def to_h
+      @values.dup
+    end
+
+    private
+
+    def defaults_merged_with(values)
+      values.is_a?(Settings) ? values.to_h : self.class.defaults.merge(normalize(values))
+    end
+
+    # Symbol keys are attributes the caller has already coerced (`frame_delay:
+    # 0.15`); String keys are script names that go through the same validation
+    # a `Set` line would. nil values are dropped so callers can pass unset
+    # flags straight through.
+    def normalize(values)
+      values.to_h.compact.to_h do |key, value|
+        next self.class.validate!(key, value) if key.is_a?(String)
+        raise Error, "unknown setting #{key.inspect}" unless ATTRIBUTES.include?(key)
+
+        [key, value]
+      end
+    rescue ArgumentError => e
+      raise Error, e.message
+    end
+  end
+end

data/lib/btape/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Btape
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/btape.rb

@@ -2,8 +2,14 @@
 
 require_relative 'btape/version'
 require_relative 'btape/error'
+require_relative 'btape/null_logger'
+require_relative 'btape/duration'
+require_relative 'btape/settings'
 require_relative 'btape/parser'
+require_relative 'btape/result'
+require_relative 'btape/palette'
 require_relative 'btape/gif_encoder'
 require_relative 'btape/recorder'
+require_relative 'btape/executor'
 require_relative 'btape/runner'
 require_relative 'btape/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: btape
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - btape contributors
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 description: A small VHS-inspired browser recorder driven by .tape files.
 executables:
 - btape
@@ -48,16 +62,27 @@ files:
 - exe/btape
 - lib/btape.rb
 - lib/btape/cli.rb
+- lib/btape/duration.rb
 - lib/btape/error.rb
+- lib/btape/executor.rb
 - lib/btape/gif_encoder.rb
 - lib/btape/lzw_compressor.rb
+- lib/btape/null_logger.rb
+- lib/btape/palette.rb
 - lib/btape/parser.rb
 - lib/btape/recorder.rb
+- lib/btape/result.rb
 - lib/btape/runner.rb
+- lib/btape/settings.rb
 - lib/btape/version.rb
+homepage: https://github.com/slidict/btape
 licenses:
 - MIT
 metadata:
+  source_code_uri: https://github.com/slidict/btape
+  changelog_uri: https://github.com/slidict/btape/releases
+  bug_tracker_uri: https://github.com/slidict/btape/issues
+  documentation_uri: https://github.com/slidict/btape#readme
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: