trmnl_preview 0.7.2 → 0.8.0

data/lib/trmnlp/poller.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/conversions'
+require 'faraday'
+require 'json'
+
+require_relative 'reporter'
+
+module TRMNLP
+  class Poller
+    def initialize(config:, paths:, reporter: Reporter.new)
+      @config = config
+      @paths = paths
+      @reporter = reporter
+    end
+
+    def poll_data
+      return unless config.plugin.polling?
+      raise InvalidConfig, 'config must specify polling_url or polling_urls' if config.plugin.polling_urls.empty?
+
+      data = aggregate_responses
+      write_user_data(data)
+      data
+    # NOTE: trmnlp is a dev tool — a flaky upstream API should surface a warning
+    # and keep the preview server alive, not crash the user's session. We
+    # deliberately swallow here and return {} so the renderer keeps rendering.
+    rescue StandardError => e
+      reporter.info("warning: #{e.message}")
+      {}
+    end
+
+    def put_webhook(payload)
+      write_user_data(wrap_array(JSON.parse(payload)))
+    # NOTE: Same rationale as #poll_data — a bad webhook payload shouldn't take
+    # down the dev server. Report a warning and keep serving.
+    rescue StandardError => e
+      reporter.info("webhook warning: #{e.message}")
+    end
+
+    private
+
+    attr_reader :config, :paths, :reporter
+
+    def aggregate_responses
+      responses = config.plugin.polling_urls.map { |url| fetch_one(url) }
+      return responses.first if responses.size == 1
+
+      responses.each_with_index.with_object({}) { |(r, i), h| h["IDX_#{i}"] = r }
+    end
+
+    def fetch_one(url)
+      verb = config.plugin.polling_verb.upcase
+      response = perform_request(url, verb)
+      reporter.info("#{verb} #{url} — received #{response.body.length} bytes (#{response.status} status)")
+      parse_response(response)
+    end
+
+    def perform_request(url, verb)
+      conn = Faraday.new(url:, headers: config.plugin.polling_headers)
+      verb == 'POST' ? conn.post { |req| req.body = config.plugin.polling_body } : conn.get
+    end
+
+    def parse_response(response)
+      return parse_failure(response.body) unless response.status == 200
+
+      parse_body(response.body, response.headers['content-type'])
+    end
+
+    def parse_failure(body)
+      reporter.info(body)
+      {}
+    end
+
+    def parse_body(body, content_type_header)
+      content_type = content_type_header&.split(';')&.first&.strip
+      case content_type
+      when 'application/json', %r{^application/.+\+json} then wrap_array(JSON.parse(body))
+      when 'text/xml', 'application/xml', %r{^application/.+\+xml} then wrap_array(Hash.from_xml(body))
+      when 'text/html', 'text/plain' then sniff_json(body) || { 'text' => body }
+      else log_unknown_type(content_type_header)
+      end
+    end
+
+    def log_unknown_type(header)
+      reporter.info("unknown content type received: #{header}")
+      {}
+    end
+
+    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+
+    def sniff_json(body)
+      trimmed = body.to_s.strip
+      return nil unless trimmed.start_with?('{', '[')
+
+      wrap_array(JSON.parse(trimmed))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_user_data(data)
+      paths.create_cache_dir
+      paths.user_data.write(JSON.generate(data))
+    end
+  end
+end

data/lib/trmnlp/renderer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'trmnl/liquid'
+
+require_relative 'screen'
+
+module TRMNLP
+  class Renderer
+    def initialize(config:, paths:, user_data_assembler:)
+      @config = config
+      @paths = paths
+      @user_data_assembler = user_data_assembler
+    end
+
+    def render_full_page(view, params = {})
+      device = user_data_assembler.device_from_params(params)
+      binding_obj = TemplateBinding.new(self, view, params)
+      ERB.new(paths.render_template.read).result(
+        binding_obj.get_binding { render_or_error(view, device:) }
+      )
+    end
+
+    def framework = config.plugin.framework_version
+
+    def screen_classes(classes = 'screen')
+      classes ||= 'screen' # an explicit nil (omitted screen_classes param) still needs a base
+      classes += ' screen--no-bleed' if config.plugin.no_screen_padding == 'yes'
+      classes
+    end
+
+    private
+
+    attr_reader :config, :paths, :user_data_assembler
+
+    # NOTE: a missing template or Liquid syntax error is a user-facing
+    # signal — the plugin author needs to *see* what broke. We surface
+    # those as RenderError, then #render_or_error embeds the message
+    # inside the preview frame so the dev server keeps serving instead
+    # of 500-ing. Anything that's not a RenderError bubbles up as a bug.
+    def render_liquid_template(view, device: {})
+      template_path = paths.template(view)
+      raise RenderError, "Missing template: #{template_path}" unless template_path.exist?
+
+      parse_and_render(template_path, device:)
+    end
+
+    def parse_and_render(template_path, device:)
+      Liquid::Template.parse(full_markup(template_path), environment: liquid_environment)
+                      .render(user_data_assembler.call(device:))
+    rescue StandardError => e
+      raise RenderError, e.message
+    end
+
+    def render_or_error(view, device:)
+      render_liquid_template(view, device:)
+    rescue RenderError => e
+      e.message
+    end
+
+    def full_markup(template_path)
+      shared = paths.shared_template
+      shared.exist? ? shared.read + template_path.read : template_path.read
+    end
+
+    def liquid_environment
+      @liquid_environment ||= TRMNL::Liquid.new do |env|
+        config.project.user_filters.each do |module_name, relative_path|
+          require paths.root_dir.join(relative_path)
+          env.register_filter(Object.const_get(module_name))
+        end
+      end
+    end
+
+    # bindings must match the `GET /render/{view}.html` route in app.rb
+    class TemplateBinding
+      def initialize(renderer, view, params)
+        @view = view
+        @screen_classes = renderer.screen_classes(params[:screen_classes])
+        @framework = renderer.framework
+        @mashup_classes = Screen.find(view)&.mashup_classes
+      end
+
+      def get_binding = binding
+    end
+  end
+end

data/lib/trmnlp/reporter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  # Single sink for user-facing command output. Records every message so
+  # specs can assert on what a command would have said, and writes to the
+  # underlying stream unless quiet:.
+  class Reporter
+    attr_reader :messages
+
+    def initialize(quiet: false, stream: $stdout)
+      @quiet = quiet
+      @stream = stream
+      @messages = []
+    end
+
+    def info(message)
+      @messages << message
+      @stream.puts(message) unless @quiet
+    end
+
+    def green(text) = colorize(text, 32)
+    def yellow(text) = colorize(text, 33)
+
+    private
+
+    def colorize(text, code) = "\e[#{code}m#{text}\e[0m"
+  end
+end

data/lib/trmnlp/screen.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  class Screen < Data.define(:name, :mashup_classes)
+    FULL             = new(name: 'full',             mashup_classes: nil)
+    HALF_HORIZONTAL  = new(name: 'half_horizontal',  mashup_classes: 'mashup mashup--1Tx1B')
+    HALF_VERTICAL    = new(name: 'half_vertical',    mashup_classes: 'mashup mashup--1Lx1R')
+    QUADRANT         = new(name: 'quadrant',         mashup_classes: 'mashup mashup--2x2')
+
+    ALL = [FULL, HALF_HORIZONTAL, HALF_VERTICAL, QUADRANT].freeze
+
+    def self.all = ALL
+    def self.find(name) = ALL.find { it.name == name }
+    def self.names = ALL.map(&:name)
+  end
+end

data/lib/trmnlp/screen_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'screenshot'
+require_relative 'image_quantizer'
+
+module TRMNLP
+  class ScreenGenerator
+    def initialize(html, opts = {})
+      @input = html
+      @screenshot = opts[:screenshot]
+      @requested_width = opts[:width]
+      @requested_height = opts[:height]
+      @requested_color_depth = opts[:color_depth]
+    end
+
+    def process
+      output = @screenshot.call(html: @input, width:, height:)
+      ImageQuantizer.new(depth: color_depth).call(output.path)
+      output
+    end
+
+    private
+
+    def width = @requested_width || 800
+    def height = @requested_height || 480
+
+    def color_depth
+      return @requested_color_depth if @requested_color_depth
+      return ::Regexp.last_match(1).to_i if @input&.match(/screen--(\d+)bit/)
+
+      1
+    end
+  end
+end

data/lib/trmnlp/screenshot.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+require 'tempfile'
+
+module TRMNLP
+  class Screenshot
+    def initialize(pool:)
+      @pool = pool
+    end
+
+    def call(html:, width:, height:)
+      attempts = 0
+
+      begin
+        @pool.with_driver { |driver| render(driver, html, width, height) }
+      rescue Selenium::WebDriver::Error::TimeoutError,
+             Selenium::WebDriver::Error::WebDriverError
+        attempts += 1
+        retry if attempts <= 1
+        raise
+      end
+    end
+
+    private
+
+    def render(driver, html, width, height)
+      resize(driver, width, height)
+      load_page(driver, html)
+      capture(driver)
+    end
+
+    def resize(driver, width, height)
+      apply_window_size(driver, width, height)
+      wait_for_viewport(driver, width, height)
+    end
+
+    def apply_window_size(driver, width, height)
+      borders = driver.execute_script(<<~JS)
+        return {
+          width: window.outerWidth - window.innerWidth,
+          height: window.outerHeight - window.innerHeight
+        }
+      JS
+
+      dim = Selenium::WebDriver::Dimension.new(width + borders['width'], height + borders['height'])
+      driver.manage.window.size = dim
+    end
+
+    # NOTE: A cold Firefox — e.g. the first render after the container boots —
+    # applies a window resize lazily. The old fixed sleep raced that reflow and
+    # clipped the first screenshot short (800x433 instead of 800x480). Poll the
+    # real viewport instead, re-applying the size until it lands; a resize that
+    # never settles surfaces as a TimeoutError that #call already retries.
+    def wait_for_viewport(driver, width, height)
+      Selenium::WebDriver::Wait.new(timeout: 5, interval: 0.1).until do
+        next true if viewport(driver) == [width, height]
+
+        apply_window_size(driver, width, height)
+        false
+      end
+    end
+
+    def viewport(driver)
+      driver.execute_script('return [window.innerWidth, window.innerHeight]')
+    end
+
+    def load_page(driver, html)
+      driver.navigate.to('about:blank')
+
+      driver.execute_script(<<~JS, html)
+        document.open();
+        document.write(arguments[0]);
+        document.close();
+      JS
+
+      Selenium::WebDriver::Wait.new(timeout: 5).until do
+        driver.execute_script('return document.readyState') == 'complete'
+      end
+
+      driver.execute_script('return document.fonts && document.fonts.ready')
+
+      driver.execute_script(<<~JS)
+        document.documentElement.style.overflow = 'hidden';
+        document.body.style.overflow = 'hidden';
+      JS
+    end
+
+    def capture(driver)
+      file = Tempfile.new(['screenshot', '.png'])
+      driver.save_screenshot(file.path)
+      file.close
+      file
+    end
+  end
+end

data/lib/trmnlp/transform_backend/http.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+require_relative '../transform_client'
+require_relative 'wrapper'
+
+module TRMNLP
+  module TransformBackend
+    # Remote-daemon transform execution. Speaks the production daemon's
+    # wire format over HTTP so trmnlp can target a real remote transform
+    # daemon (or any compatible server) instead of running transforms
+    # locally. Selected by TransformClient.from_config when
+    # serverless_daemon_url is set in the project's .trmnlp.yml.
+    #
+    # The daemon expects code that already includes its own harness
+    # (reading stdin, dispatching to run/transform/result, writing the
+    # canonical JSON result to FD 3). The shared Wrapper module emits
+    # the same harness Subprocess uses, parameterized on a FD-3 sink
+    # so a transform behaves identically whether previewed against the
+    # daemon or run locally.
+    class Http
+      SUPPORTED_LANGUAGES = %w[python ruby php node].freeze
+      DEFAULT_TIMEOUT = 30
+      HTTP_TIMEOUT = 60
+
+      def initialize(url:, api_key: nil, http_timeout: HTTP_TIMEOUT)
+        @url = url
+        @api_key = api_key
+        @http_timeout = http_timeout
+      end
+
+      def execute(code:, language:, stdin: '', timeout_seconds: DEFAULT_TIMEOUT)
+        lang = language.to_s
+        return failure("unsupported serverless_language: #{lang}") unless SUPPORTED_LANGUAGES.include?(lang)
+
+        post(code: Wrapper.for(lang, code, sink_for(lang)), stdin:, timeout: timeout_seconds, language: lang)
+      end
+
+      private
+
+      def post(code:, stdin:, timeout:, language:)
+        response = connection.post('/execute') do |req|
+          req.body = JSON.generate(code:, stdin:, timeout:, language:)
+        end
+
+        return failure("daemon HTTP #{response.status}: #{response.body}") unless response.status == 200
+
+        parse(response.body)
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+        failure("transform daemon unreachable at #{@url}: #{e.message}")
+      rescue JSON::ParserError => e
+        failure("daemon returned non-JSON response: #{e.message}")
+      end
+
+      def parse(body)
+        parsed = JSON.parse(body)
+        TransformClient::Result.new(
+          stdout: parsed['stdout'] || '',
+          stderr: parsed['stderr'] || '',
+          # Fall back to stdout for daemons that haven't been upgraded to
+          # the separate `output` channel yet.
+          output: (parsed['output'].to_s.empty? ? parsed['stdout'] : parsed['output']).to_s,
+          exit_code: parsed['exit_code'] || 0,
+          duration_ms: parsed['duration_ms'] || 0,
+          error: parsed['error']
+        )
+      end
+
+      # NOTE: the connection is memoized and never explicitly closed. That is
+      # safe only because Faraday's default adapter opens a fresh socket per
+      # request — swapping in a persistent adapter here would leak sockets.
+      def connection
+        @connection ||= Faraday.new(url: @url) do |f|
+          f.headers['Content-Type'] = 'application/json'
+          f.headers['Authorization'] = "Bearer #{@api_key}" if @api_key
+          f.options.timeout = @http_timeout
+          f.options.open_timeout = 5
+        end
+      end
+
+      def failure(message)
+        TransformClient::Result.new(stdout: '', stderr: '', output: '', exit_code: -1, duration_ms: 0, error: message)
+      end
+
+      # Language-specific FD-3 sink snippets — what the daemon's
+      # harness reads from to capture canonical JSON output.
+      def sink_for(language)
+        case language
+        when 'python'
+          "os.write(3, json.dumps(output).encode('utf-8'))"
+        when 'ruby'
+          'IO.new(3).write(JSON.generate(output))'
+        when 'node'
+          <<~JS.chomp
+            Promise.resolve(output).then(o => {
+              require('fs').writeSync(3, JSON.stringify(o));
+            });
+          JS
+        when 'php'
+          "$fd = fopen('php://fd/3', 'w');\n          fwrite($fd, json_encode($output));\n          fclose($fd);"
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/transform_backend/subprocess.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tmpdir'
+
+require_relative '../transform_client'
+require_relative 'wrapper'
+
+module TRMNLP
+  module TransformBackend
+    # Local subprocess execution of user transform code. Mirrors the
+    # remote-daemon wrapper contract so a transform behaves the same
+    # locally as it does in production. Output flows back via
+    # a tempfile per-execution instead of FD 3, but the
+    # run/result/input dispatch logic is preserved verbatim via the
+    # shared Wrapper module.
+    class Subprocess
+      DEFAULT_TIMEOUT = 30
+      # Seconds a TERM'd process is given to exit before escalating to KILL.
+      GRACE_PERIOD = 0.1
+
+      INTERPRETERS = {
+        'python' => { cmd: 'python3', ext: 'py' },
+        'ruby' => { cmd: 'ruby',    ext: 'rb' },
+        'node' => { cmd: 'node',    ext: 'js' },
+        'php' => { cmd: 'php', ext: 'php' }
+      }.freeze
+
+      def execute(code:, language:, stdin: '', timeout_seconds: DEFAULT_TIMEOUT)
+        spec = INTERPRETERS[language.to_s]
+        return failure("unsupported language: #{language}") unless spec
+
+        invoke(spec, language.to_s, code, stdin, timeout_seconds)
+      end
+
+      private
+
+      def invoke(spec, language, code, stdin, timeout_seconds)
+        Dir.mktmpdir('trmnlp-tx-') do |dir|
+          output_path = File.join(dir, 'output.json')
+          src_path = File.join(dir, "transform.#{spec[:ext]}")
+          File.write(src_path, Wrapper.for(language, code, sink_for(language, output_path)))
+          run_process(spec[:cmd], src_path, stdin, timeout_seconds, output_path)
+        end
+      rescue Errno::ENOENT, Errno::EACCES => e
+        failure("interpreter not available: #{e.message}")
+      end
+
+      def run_process(cmd, src_path, stdin, timeout_seconds, output_path)
+        started = monotonic_ms
+
+        Open3.popen3(cmd, src_path) do |stdin_io, stdout_io, stderr_io, wait_thr|
+          stdin_io.write(stdin)
+          stdin_io.close
+
+          unless wait_thr.join(timeout_seconds)
+            kill(wait_thr)
+            return failure("timeout after #{timeout_seconds}s", monotonic_ms - started)
+          end
+
+          build_result(stdout_io.read, stderr_io.read, wait_thr.value, output_path, monotonic_ms - started)
+        end
+      end
+
+      def build_result(stdout, stderr, status, output_path, duration_ms)
+        TransformClient::Result.new(
+          stdout: stdout,
+          stderr: stderr,
+          output: read_output(output_path),
+          exit_code: status.exitstatus || -1,
+          duration_ms: duration_ms,
+          error: nil
+        )
+      end
+
+      # A transform that crashes before writing leaves no output file; a
+      # permissions/IO error on read is treated the same — empty output,
+      # which the pipeline surfaces as a non-JSON-output failure.
+      def read_output(path)
+        File.exist?(path) ? File.read(path) : ''
+      rescue SystemCallError
+        ''
+      end
+
+      # TERM first, escalating to KILL only if the process outlives the
+      # grace period. join returns the moment it exits, so a process that
+      # dies promptly on TERM costs near-zero wait, not a fixed sleep.
+      def kill(wait_thr)
+        Process.kill('TERM', wait_thr.pid)
+        return if wait_thr.join(GRACE_PERIOD)
+
+        Process.kill('KILL', wait_thr.pid)
+      rescue Errno::ESRCH
+        # already exited between TERM and KILL — fine
+      end
+
+      def failure(message, duration_ms = 0)
+        TransformClient::Result.new(
+          stdout: '', stderr: '', output: '',
+          exit_code: -1, duration_ms: duration_ms, error: message
+        )
+      end
+
+      def monotonic_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+
+      # Language-specific tempfile sink snippets. The dispatch harness
+      # in Wrapper.* writes `output` (a serializable value); these
+      # snippets get it onto disk so the parent process can read it.
+      def sink_for(language, output_path)
+        case language
+        when 'python'
+          # A single statement — no block indentation to keep in sync with
+          # the Wrapper.python heredoc. open() is flushed and closed when
+          # CPython drops the temporary as the process exits.
+          "json.dump(output, open(#{output_path.inspect}, 'w'))"
+        when 'ruby'
+          "File.write(#{output_path.inspect}, JSON.generate(output))"
+        when 'node'
+          <<~JS.chomp
+            Promise.resolve(output)
+              .then((o) => require('fs').writeFileSync(#{output_path.inspect}, JSON.stringify(o)))
+              .catch((err) => { process.stderr.write(err.stack || String(err)); process.exit(1); });
+          JS
+        when 'php'
+          "file_put_contents(#{output_path.inspect}, json_encode($output));"
+        end
+      end
+    end
+  end
+end