rubylens 0.1.0 → 0.2.1

data/lib/rubylens/cli.rb

@@ -6,6 +6,35 @@ require_relative "../rubylens"
 
 module RubyLens
   class CLI
+    # One entry per generating command: everything that differs between
+    # report, showcase, and clip lives here, not in per-command methods.
+    COMMANDS = {
+      "report" => {
+        default_name: Generator::DEFAULT_REPORT_NAME,
+        generator: :generate_report,
+        warning: "RubyLens reports contain private codebase structure. Keep the output local unless you intend to share it.",
+        details_option: false,
+        output_kind: "HTML",
+        report_progress: false,
+      },
+      "clip" => {
+        default_name: ClipGenerator::DEFAULT_CLIP_NAME,
+        generator: :generate_clip,
+        warning: "RubyLens clips show the same picture as showcases: the project name plus the galaxy's shape and scale; --details adds aggregate statistics and selected Ruby and dependency names. Share them intentionally.",
+        details_option: true,
+        output_kind: "MP4",
+        report_progress: true,
+      },
+      "showcase" => {
+        default_name: ShowcaseGenerator::DEFAULT_SHOWCASE_NAME,
+        generator: :generate_showcase,
+        warning: "RubyLens showcases disclose the project name and visual codebase structure; --details also includes aggregate statistics and selected Ruby and dependency names. Share them intentionally.",
+        details_option: true,
+        output_kind: "HTML",
+        report_progress: false,
+      },
+    }.freeze
+
     def initialize(arguments)
       @arguments = arguments.dup
     end
@@ -15,8 +44,7 @@ module RubyLens
       command = arguments.shift
       return print_version if %w[-v --version version].include?(command)
       return print_help(0) if command.nil? || %w[-h --help help].include?(command)
-      return generate_report(arguments) if command == "report"
-      return generate_showcase(arguments) if command == "showcase"
+      return generate(command, arguments) if COMMANDS.key?(command)
 
       $stderr.puts "Unknown command: #{command}"
       print_help(2)
@@ -27,28 +55,8 @@ module RubyLens
 
     private
 
-    def generate_report(arguments)
-      generate_html(
-        arguments,
-        command: "report",
-        default_name: "rubylens-report.html",
-        generator: RubyLens.method(:generate_report),
-        warning: "RubyLens reports contain private codebase structure. Keep the output local unless you intend to share it.",
-      )
-    end
-
-    def generate_showcase(arguments)
-      generate_html(
-        arguments,
-        command: "showcase",
-        default_name: "rubylens-showcase.html",
-        generator: RubyLens.method(:generate_showcase),
-        warning: "RubyLens showcases disclose the project name and visual codebase structure; --details also includes aggregate statistics and selected Ruby and dependency names. Share them intentionally.",
-        details_option: true,
-      )
-    end
-
-    def generate_html(arguments, command:, default_name:, generator:, warning:, details_option: false)
+    def generate(command, arguments)
+      specification = COMMANDS.fetch(command)
       options = {}
       help = false
       parser = OptionParser.new do |option|
@@ -56,13 +64,13 @@ module RubyLens
         option.separator ""
         option.separator "TARGET defaults to the current working directory."
         option.separator ""
-        option.on("-o", "--output FILE", "Output HTML (default: TARGET/#{default_name})") do |value|
+        option.on("-o", "--output FILE", "Output #{specification.fetch(:output_kind)} (default: TARGET/#{specification.fetch(:default_name)})") do |value|
           options[:output] = value
         end
         option.on("--lockfile FILE", "Gemfile.lock used to select exact dependency versions") do |value|
           options[:lockfile] = value
         end
-        if details_option
+        if specification.fetch(:details_option)
           option.on("--details", "Include aggregate statistics and cinematic code/dependency labels") do
             options[:details] = true
           end
@@ -81,19 +89,27 @@ module RubyLens
       raise OptionParser::InvalidArgument, "unexpected argument: #{arguments.first}" unless arguments.empty?
 
       generator_options = { path: target, output: options[:output], lockfile: options[:lockfile] }
-      generator_options[:details] = options.fetch(:details, false) if details_option
-      result = generator.call(**generator_options)
+      generator_options[:details] = options.fetch(:details, false) if specification.fetch(:details_option)
+      generator_options[:progress] = progress_printer if specification.fetch(:report_progress)
+      result = RubyLens.public_send(specification.fetch(:generator), **generator_options)
       print_result(result)
-      $stderr.puts warning
+      $stderr.puts specification.fetch(:warning)
       0
     end
 
+    def progress_printer
+      last_step = -1
+      lambda do |rendered, total|
+        step = rendered * 10 / total
+        next unless step > last_step
+
+        last_step = step
+        $stderr.puts "Rendering clip: #{rendered * 100 / total}% (#{rendered}/#{total} frames)"
+      end
+    end
+
     def print_result(result)
-      $stdout.puts JSON.generate(
-        output: result.output_path,
-        counts: result.counts,
-        warnings: result.warnings,
-      )
+      $stdout.puts JSON.generate(result.to_payload)
     end
 
     def print_version
@@ -110,10 +126,11 @@ module RubyLens
 
         Commands:
           report [OPTIONS] [TARGET]     Generate a private, interactive galaxy report
-          showcase [OPTIONS] [TARGET]   Generate a shareable, cinematic galaxy showcase
+          clip [OPTIONS] [TARGET]       Generate a shareable galaxy video (MP4, needs Chrome + ffmpeg)
+          showcase [OPTIONS] [TARGET]   Generate a shareable, cinematic galaxy showcase page
           version                       Print the RubyLens version
 
-        Run `rubylens report --help` or `rubylens showcase --help` for options.
+        Run `rubylens report --help`, `rubylens clip --help`, or `rubylens showcase --help` for options.
       HELP
       status
     end

data/lib/rubylens/clip/chrome_page.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "base64"
+require "fileutils"
+require "json"
+require "net/http"
+require "tmpdir"
+require "uri"
+require_relative "../errors"
+require_relative "deadline_io"
+require_relative "web_socket_channel"
+
+module RubyLens
+  module Clip
+    # Runs a headless Chrome/Chromium with an ephemeral DevTools port and a
+    # throwaway profile, attaches to the page that loads the showcase HTML,
+    # and exposes the two operations clip rendering needs: evaluate and
+    # screenshot. The port comes from the profile's DevToolsActivePort file,
+    # so parallel clips never race for a fixed port.
+    class ChromePage
+      HEADLESS_FLAGS = %w[
+        --headless=new
+        --remote-debugging-port=0
+        --no-first-run
+        --no-default-browser-check
+        --disable-background-networking
+        --disable-component-update
+        --disable-sync
+        --mute-audio
+        --hide-scrollbars
+        --force-device-scale-factor=1
+        --force-color-profile=srgb
+        --enable-unsafe-swiftshader
+      ].freeze
+      LAUNCH_TIMEOUT_SECONDS = 30
+
+      def self.open(executable:, url:, width:, height:)
+        page = new(executable:, url:, width:, height:)
+        begin
+          yield page
+        ensure
+          page.close
+        end
+      end
+
+      def initialize(executable:, url:, width:, height:)
+        @profile = Dir.mktmpdir("rubylens-clip-")
+        @next_id = 0
+        @responses = {}
+        flags = HEADLESS_FLAGS.dup
+        # Chrome refuses its sandbox as root (typical for containers and CI).
+        flags << "--no-sandbox" if Process.euid.zero?
+        flags << "--window-size=#{width},#{height}"
+        flags << "--user-data-dir=#{@profile}"
+        @pid = Process.spawn(executable, *flags, url, %i[out err] => File::NULL)
+        port = wait_for_devtools_port
+        @channel = WebSocketChannel.new("127.0.0.1", port, page_target_path(port))
+        # The headless window includes non-viewport space; pin the viewport so
+        # captures are exactly the stage size.
+        command("Emulation.setDeviceMetricsOverride", {
+          "width" => width, "height" => height, "deviceScaleFactor" => 1, "mobile" => false
+        }, timeout: 30)
+      rescue Errno::ENOENT => error
+        abort_start
+        raise Error, "could not launch Chrome at #{executable}: #{error.message}"
+      rescue SystemCallError => error
+        # A startup race (Chrome exiting or closing its port mid-attach) must
+        # surface as a normal rubylens error, not a raw Errno stack trace.
+        abort_start
+        raise Error, "could not attach to Chrome's DevTools endpoint: #{error.message}"
+      rescue StandardError
+        abort_start
+        raise
+      end
+
+      def evaluate(expression, await: false, timeout: 30)
+        result = command("Runtime.evaluate", {
+          "expression" => expression,
+          "returnByValue" => true,
+          "awaitPromise" => await,
+        }, timeout:)
+        if (details = result["exceptionDetails"])
+          raise Error, "the showcase page raised: #{details.dig("exception", "description") || details["text"]}"
+        end
+        result.dig("result", "value")
+      end
+
+      def screenshot_png(timeout: 60)
+        data = command("Page.captureScreenshot", { "format" => "png", "optimizeForSpeed" => true }, timeout:)
+        Base64.decode64(data.fetch("data"))
+      end
+
+      def close
+        begin
+          command("Browser.close", {}, timeout: 3) if @channel
+        rescue Error
+          terminate
+        end
+        Process.wait(@pid) if @pid
+      rescue Errno::ECHILD
+        nil
+      ensure
+        @channel&.close
+        FileUtils.remove_entry(@profile) if @profile && File.directory?(@profile)
+      end
+
+      private
+
+      # A failed start never reaches ChromePage.open's ensure, so the spawned
+      # browser and throwaway profile must be cleaned up before re-raising.
+      # The unconditional kill keeps close's Process.wait from hanging on a
+      # live Chrome with no channel.
+      def abort_start
+        terminate if @pid
+        close
+      end
+
+      def terminate
+        Process.kill("KILL", @pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def command(method, params, timeout:)
+        id = (@next_id += 1)
+        @channel.send_text(JSON.generate({ "id" => id, "method" => method, "params" => params }))
+        loop do
+          if (message = @responses.delete(id))
+            if (error = message["error"])
+              raise Error, "Chrome rejected #{method}: #{error["message"]}"
+            end
+            return message.fetch("result")
+          end
+          message = JSON.parse(@channel.read_text(timeout:))
+          @responses[message["id"]] = message if message["id"]
+        end
+      end
+
+      def wait_for_devtools_port
+        port_path = File.join(@profile, "DevToolsActivePort")
+        deadline = DeadlineIO.deadline(LAUNCH_TIMEOUT_SECONDS)
+        while DeadlineIO.monotonic < deadline
+          if File.exist?(port_path)
+            # to_i reads the leading port line and tolerates a mid-write file.
+            port = File.read(port_path).to_i
+            return port if port.positive?
+          end
+          if Process.waitpid(@pid, Process::WNOHANG)
+            @pid = nil
+            raise Error, "Chrome exited while starting up; it may not support headless rendering here"
+          end
+          sleep 0.05
+        end
+        raise Error, "Chrome did not publish a DevTools port within #{LAUNCH_TIMEOUT_SECONDS} seconds"
+      end
+
+      def page_target_path(port)
+        deadline = DeadlineIO.deadline(LAUNCH_TIMEOUT_SECONDS)
+        while DeadlineIO.monotonic < deadline
+          begin
+            target = JSON.parse(http_get(port, "/json/list")).find { |info| info["type"] == "page" }
+            if (socket_url = target&.fetch("webSocketDebuggerUrl", nil))
+              return URI(socket_url).path
+            end
+          rescue Error, SystemCallError, JSON::ParserError, Timeout::Error, EOFError
+            # The HTTP endpoint can lag DevToolsActivePort; retry until the deadline.
+          end
+          sleep 0.05
+        end
+        raise Error, "Chrome never exposed the showcase page for capture"
+      end
+
+      # The explicit nil proxy argument keeps this loopback request off any
+      # configured HTTP proxy.
+      def http_get(port, path, timeout: 10)
+        http = Net::HTTP.new("127.0.0.1", port, nil)
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.get(path).body
+      end
+    end
+  end
+end

data/lib/rubylens/clip/deadline_io.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module RubyLens
+  module Clip
+    # Deadline-bounded, non-blocking socket reads shared by the DevTools
+    # WebSocket channel and the local DevTools HTTP client.
+    module DeadlineIO
+      module_function
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def deadline(timeout) = monotonic + timeout
+
+      def read_chunk(socket, deadline, closed_message:, timeout_message:)
+        remaining = deadline - monotonic
+        raise Error, timeout_message if remaining <= 0
+        IO.select([socket], nil, nil, remaining) or raise Error, timeout_message
+        chunk = socket.read_nonblock(1 << 20, exception: false)
+        raise Error, closed_message if chunk.nil?
+        chunk.is_a?(String) ? chunk : "".b
+      rescue SystemCallError, IOError => error
+        raise Error, "#{closed_message}: #{error.message}"
+      end
+    end
+  end
+end

data/lib/rubylens/clip/renderer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "open3"
+require "uri"
+require_relative "../errors"
+require_relative "chrome_page"
+require_relative "deadline_io"
+
+module RubyLens
+  module Clip
+    # Renders a showcase HTML file into an H.264 MP4: headless Chrome steps
+    # the showcase's deterministic clip frames, and each captured frame is
+    # streamed straight into ffmpeg so no frame images ever touch disk. One
+    # render covers exactly one camera loop, so the video loops seamlessly.
+    class Renderer
+      STAGE_WIDTH = 1920
+      STAGE_HEIGHT = 1080
+      DEFAULT_FPS = 30
+      READY_TIMEOUT_SECONDS = 120
+      MARKER_COMMENT = "RubyLens clip"
+
+      def initialize(chrome:, ffmpeg:, fps: DEFAULT_FPS, frame_limit: nil, progress: nil)
+        @chrome = chrome
+        @ffmpeg = ffmpeg
+        @fps = Integer(fps)
+        @frame_limit = frame_limit
+        @progress = progress
+      end
+
+      def render(showcase_html:, output:)
+        ChromePage.open(executable: @chrome, url: file_url(showcase_html), width: STAGE_WIDTH, height: STAGE_HEIGHT) do |page|
+          wait_until_ready(page)
+          preset = begin_clip(page)
+          frames = frame_count(preset)
+          encode(page, frames, output)
+        end
+        output
+      end
+
+      private
+
+      def file_url(path)
+        "file://#{URI::DEFAULT_PARSER.escape(File.expand_path(path))}"
+      end
+
+      def wait_until_ready(page)
+        deadline = DeadlineIO.deadline(READY_TIMEOUT_SECONDS)
+        until page.evaluate("document.documentElement?.dataset.showcaseReady === 'true'")
+          raise Error, "the showcase page never finished loading" if DeadlineIO.monotonic > deadline
+
+          sleep 0.1
+        end
+      end
+
+      def begin_clip(page)
+        preset = page.evaluate("beginShowcaseClip()")
+        status = preset.is_a?(Hash) ? preset["status"] : nil
+        raise Error, "Chrome could not initialize WebGL2, which clip rendering requires" if status == "renderer-unavailable"
+        raise Error, "the page is not a RubyLens showcase" unless status == "ok"
+
+        preset
+      end
+
+      def frame_count(preset)
+        frames = Integer(preset.fetch("durationMs")) * @fps / 1000
+        @frame_limit ? [frames, Integer(@frame_limit)].min : frames
+      end
+
+      def ffmpeg_arguments(output)
+        [
+          @ffmpeg, "-loglevel", "error", "-y",
+          "-f", "image2pipe", "-c:v", "png", "-framerate", @fps.to_s, "-i", "-",
+          "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p",
+          "-movflags", "+faststart",
+          "-metadata", "comment=#{MARKER_COMMENT}",
+          "-f", "mp4", output
+        ]
+      end
+
+      def encode(page, frames, output)
+        stdin, stderr, waiter = Open3.popen3(*ffmpeg_arguments(output)).then { |i, o, e, t| o.close; [i, e, t] }
+        stdin.binmode
+        stderr_reader = Thread.new { stderr.read }
+        begin
+          frames.times do |index|
+            page.evaluate("renderShowcaseClipFrame(#{index}, #{@fps})", await: true)
+            stdin.write(page.screenshot_png)
+            @progress&.call(index + 1, frames)
+          end
+          stdin.close
+          raise Error, "ffmpeg failed while encoding the clip: #{failure_reason(stderr_reader.value)}" unless waiter.value.success?
+        rescue Errno::EPIPE
+          raise Error, "ffmpeg stopped accepting frames: #{failure_reason(stderr_reader.value)}"
+        ensure
+          # On a capture-side failure, closing stdin lets ffmpeg finish and
+          # exit, the waiter reaps it, and the stderr reader ends on EOF, so
+          # only the original error surfaces.
+          stdin.close unless stdin.closed?
+          waiter.value
+          stderr_reader.value
+          stderr.close unless stderr.closed?
+        end
+      rescue Errno::ENOENT => error
+        raise Error, "could not run ffmpeg at #{@ffmpeg}: #{error.message}"
+      end
+
+      def failure_reason(stderr_output)
+        lines = stderr_output.to_s.strip.lines.last(3).map(&:strip)
+        lines.empty? ? "no error output" : lines.join(" / ")
+      end
+    end
+  end
+end

data/lib/rubylens/clip/toolchain.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module RubyLens
+  module Clip
+    # Locates the two external tools clip rendering needs: a Chrome/Chromium
+    # binary and ffmpeg. Environment overrides win, then PATH, then well-known
+    # install locations. Discovery failures raise with install guidance so the
+    # command fails fast, before any indexing work.
+    module Toolchain
+      CHROME_ENV = "RUBYLENS_CHROME"
+      FFMPEG_ENV = "RUBYLENS_FFMPEG"
+      CHROME_COMMANDS = %w[google-chrome google-chrome-stable chromium chromium-browser chrome].freeze
+      CHROME_KNOWN_PATHS = [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      ].freeze
+      PLAYWRIGHT_CHROME_GLOBS = %w[
+        chromium
+        chromium-*/chrome-linux/chrome
+        chromium-*/chrome-mac/Chromium.app/Contents/MacOS/Chromium
+      ].freeze
+
+      module_function
+
+      def chrome_path
+        from_environment(CHROME_ENV) ||
+          from_path(CHROME_COMMANDS) ||
+          from_known_paths(CHROME_KNOWN_PATHS + playwright_chrome_candidates) ||
+          raise(Error, "clip rendering needs Chrome or Chromium; install Google Chrome, " \
+                       "or point #{CHROME_ENV} at a Chrome-compatible browser binary")
+      end
+
+      def ffmpeg_path
+        from_environment(FFMPEG_ENV) ||
+          from_path(%w[ffmpeg]) ||
+          raise(Error, "clip rendering needs ffmpeg; install it (for example `brew install ffmpeg` " \
+                       "or `apt install ffmpeg`), or point #{FFMPEG_ENV} at an ffmpeg binary")
+      end
+
+      def from_environment(name)
+        value = ENV.fetch(name, nil)
+        return nil if value.nil? || value.empty?
+        raise Error, "#{name} is set to #{value}, which is not an executable file" unless executable?(value)
+
+        value
+      end
+
+      def from_path(commands)
+        directories = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+        commands.each do |command|
+          directories.each do |directory|
+            next if directory.empty?
+
+            candidate = File.join(directory, command)
+            return candidate if executable?(candidate)
+          end
+        end
+        nil
+      end
+
+      def from_known_paths(paths)
+        paths.find { |path| executable?(path) }
+      end
+
+      def playwright_chrome_candidates
+        root = ENV.fetch("PLAYWRIGHT_BROWSERS_PATH", nil)
+        root = File.expand_path("~/.cache/ms-playwright") if root.nil? || root.empty?
+        PLAYWRIGHT_CHROME_GLOBS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }.sort
+      rescue ArgumentError
+        # File.expand_path("~") raises when HOME is unset.
+        []
+      end
+
+      def executable?(path)
+        File.file?(path) && File.executable?(path)
+      end
+    end
+  end
+end

data/lib/rubylens/clip/web_socket_channel.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest/sha1"
+require "securerandom"
+require "socket"
+require_relative "../errors"
+require_relative "deadline_io"
+
+module RubyLens
+  module Clip
+    # Minimal RFC 6455 client for Chrome's local DevTools WebSocket endpoint,
+    # so clip rendering needs no gem or Node dependencies. Client frames are
+    # masked text; ping, close, and fragmented server frames are handled;
+    # extensions are never negotiated.
+    class WebSocketChannel
+      HANDSHAKE_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+      TEXT_OPCODE = 1
+      CONTINUATION_OPCODE = 0
+      CLOSE_OPCODE = 8
+      PING_OPCODE = 9
+      PONG_OPCODE = 10
+
+      def initialize(host, port, path, timeout: 15)
+        @socket = TCPSocket.new(host, port)
+        @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        @buffer = +"".b
+        handshake(host, port, path, timeout)
+      end
+
+      def send_text(payload)
+        bytes = payload.b
+        length = bytes.bytesize
+        header = if length < 126 then [0x80 | TEXT_OPCODE, 0x80 | length].pack("CC")
+                 elsif length < 65_536 then [0x80 | TEXT_OPCODE, 0x80 | 126, length].pack("CCn")
+                 else [0x80 | TEXT_OPCODE, 0x80 | 127, length].pack("CCQ>")
+                 end
+        mask = SecureRandom.bytes(4)
+        @socket.write(header + mask + apply_mask(bytes, mask))
+      rescue SystemCallError, IOError => error
+        raise Error, "lost the Chrome DevTools connection: #{error.message}"
+      end
+
+      def read_text(timeout: 30)
+        deadline = DeadlineIO.deadline(timeout)
+        message = +"".b
+        loop do
+          finished, opcode, payload = read_frame(deadline)
+          case opcode
+          when TEXT_OPCODE, CONTINUATION_OPCODE then message << payload
+          when CLOSE_OPCODE then raise Error, "Chrome closed the DevTools connection"
+          when PING_OPCODE then send_control(PONG_OPCODE, payload)
+          end
+          return message.force_encoding(Encoding::UTF_8) if finished && opcode <= TEXT_OPCODE && !message.empty?
+        end
+      end
+
+      def close
+        @socket.close unless @socket.closed?
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def handshake(host, port, path, timeout)
+        deadline = DeadlineIO.deadline(timeout)
+        key = SecureRandom.base64(16)
+        @socket.write("GET #{path} HTTP/1.1\r\nHost: #{host}:#{port}\r\n" \
+                      "Upgrade: websocket\r\nConnection: Upgrade\r\n" \
+                      "Sec-WebSocket-Key: #{key}\r\nSec-WebSocket-Version: 13\r\n\r\n")
+        response = +"".b
+        response << read_chunk(deadline) until response.include?("\r\n\r\n")
+        head, _, rest = response.partition("\r\n\r\n")
+        raise Error, "Chrome refused the DevTools WebSocket: #{head.lines.first&.strip}" unless head.start_with?("HTTP/1.1 101")
+
+        expected = Base64.strict_encode64(Digest::SHA1.digest(key + HANDSHAKE_GUID))
+        unless head.match?(/^sec-websocket-accept:\s*#{Regexp.escape(expected)}\s*$/i)
+          raise Error, "Chrome DevTools WebSocket handshake failed verification"
+        end
+
+        @buffer << rest
+      end
+
+      def apply_mask(bytes, mask)
+        masked = bytes.dup
+        masked.bytesize.times { |index| masked.setbyte(index, masked.getbyte(index) ^ mask.getbyte(index % 4)) }
+        masked
+      end
+
+      def send_control(opcode, payload)
+        mask = SecureRandom.bytes(4)
+        @socket.write([0x80 | opcode, 0x80 | payload.bytesize].pack("CC") + mask + apply_mask(payload, mask))
+      end
+
+      def read_frame(deadline)
+        first, second = read_exact(2, deadline).unpack("CC")
+        length = second & 0x7F
+        length = read_exact(2, deadline).unpack1("n") if length == 126
+        length = read_exact(8, deadline).unpack1("Q>") if length == 127
+        [first.anybits?(0x80), first & 0x0F, read_exact(length, deadline)]
+      end
+
+      def read_exact(length, deadline)
+        @buffer << read_chunk(deadline) while @buffer.bytesize < length
+        @buffer.slice!(0, length)
+      end
+
+      def read_chunk(deadline)
+        DeadlineIO.read_chunk(@socket, deadline,
+                              closed_message: "Chrome closed the DevTools connection",
+                              timeout_message: "timed out waiting for Chrome")
+      end
+    end
+  end
+end