rails-console 0.1.0

data/lib/rails-console/broker.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'socket'
+
+module RailsConsole
+  # Owns the single PTY console session per container. Puma workers reach it over a local
+  # Unix socket, so any worker can serve the browser's WebSocket and hit the same session.
+  class Broker
+    include Logging
+
+    # Ctrl-L: tells the console to redraw its prompt so a just-attached client sees it.
+    REDRAW = "\f"
+
+    # Sent to clients when the session is replaced (safe!/unsafe!), so the frontend resets the
+    # screen and shows the booting spinner again. NUL-delimited so it never collides with real
+    # terminal output.
+    RELOAD_MARKER = "\x00CONSOLE_RELOAD\x00"
+
+    # The console prints this to ask for sandbox (safe) mode. NUL bytes never appear in terminal
+    # output, so it can't be triggered by accident.
+    SAFE_MARKER = "\x00CONSOLE_SAFE_REQUEST\x00"
+
+    # Seconds to wait for a freshly spawned broker to start listening.
+    SPAWN_TIMEOUT = 15
+
+    # The console prints this to ask for write (unsafe) mode. NUL bytes never appear in terminal
+    # output, so it can't be triggered by accident.
+    UNSAFE_MARKER = "\x00CONSOLE_UNSAFE_REQUEST\x00"
+
+    attr_reader :console_session, :owner_label
+
+    def self.boot(socket_path: nil) # rubocop:disable Naming/PredicateMethod
+      socket_path ||= RailsConsole.socket_path
+
+      return true if running?(socket_path:)
+
+      broker_bin = Gem.bin_path('rails-console', 'rails_console')
+
+      Process.spawn('bundle', 'exec', broker_bin, chdir: Rails.root.to_s)
+
+      SPAWN_TIMEOUT.times do
+        return true if running?(socket_path:)
+
+        sleep(1)
+      end
+
+      false
+    end
+
+    def self.running?(socket_path: nil)
+      socket_path ||= RailsConsole.socket_path
+
+      UNIXSocket.new(socket_path.to_s).close
+
+      true
+    rescue Errno::ENOENT, Errno::ECONNREFUSED
+      false
+    end
+
+    def initialize(safe_command: nil, socket_path: nil, unsafe_command: nil)
+      @clients = []
+      @console_session = nil
+      @idle_timer = nil
+      @mutex = Mutex.new
+      @owner_label = nil
+      @pty_session = nil
+      @safe_command = safe_command
+      @server = nil
+      @shutting_down = false
+      @socket_path = socket_path || RailsConsole.socket_path
+      @unsafe_command = unsafe_command
+    end
+
+    def run
+      return log("Already listening on #{@socket_path}, aborting.") if already_running?
+
+      prepare_socket_path
+
+      @server = UNIXServer.new(@socket_path)
+
+      log("Listening on #{@socket_path}")
+
+      loop { Thread.new(@server.accept) { |client| handle_client(client) } }
+    rescue IOError
+      nil
+    ensure
+      @server&.close
+    end
+
+    def shutdown
+      @shutting_down = true
+
+      @mutex.synchronize do
+        @idle_timer&.kill
+        @idle_timer = nil
+
+        @clients.each do |item|
+          item.close
+        rescue IOError
+          nil
+        end
+
+        @clients.clear
+
+        @pty_session&.kill!
+      end
+
+      @server&.close
+      @server = nil
+    end
+
+    private
+
+    def already_running?
+      self.class.running?(socket_path: @socket_path)
+    end
+
+    def attach_client(client)
+      @mutex.synchronize do
+        @idle_timer&.kill
+        @idle_timer = nil
+
+        @clients << client
+      end
+    end
+
+    def broadcast(bytes)
+      @mutex.synchronize do
+        @clients.each { |item| item.write(bytes) }
+      rescue IOError, Errno::EPIPE
+        nil
+      end
+    end
+
+    def claim(label)
+      @mutex.synchronize do
+        if !@pty_session&.alive?
+          @owner_label = label
+
+          :start
+        elsif owner_label == label
+          :attach
+        else
+          :reject
+        end
+      end
+    end
+
+    def detach_client(client)
+      @mutex.synchronize do
+        @clients.delete(client)
+
+        schedule_idle_shutdown if @clients.empty?
+      end
+
+      client.close
+    rescue IOError
+      nil
+    end
+
+    def end_session
+      @mutex.synchronize do
+        next if @clients.any?
+
+        log("Ending idle session for #{owner_label}")
+
+        @pty_session&.kill!
+        console_session&.update(ended_at: Time.current)
+
+        @console_session = nil
+        @owner_label = nil
+      end
+    end
+
+    def handle_client(client)
+      start_message = read_start_message(client)
+
+      return if start_message.nil?
+
+      action = claim(start_message.fetch('label'))
+
+      return reject_client(client) if action == :reject
+
+      if action == :start
+        start_session(
+          ip_address: start_message['ip_address'],
+          user_id: start_message.fetch('user_id'),
+          user_label: start_message.fetch('label')
+        )
+      end
+
+      attach_client(client)
+
+      # Only redraw when joining a console that's already up; on :start the boot output
+      # itself fills the screen, and a Ctrl-L would just be echoed as "^L" mid-boot.
+      wake_pty if action == :attach
+
+      relay_client_input(client)
+    ensure
+      detach_client(client)
+    end
+
+    def idle_timeout
+      RailsConsole.idle_timeout
+    end
+
+    def prepare_socket_path
+      FileUtils.mkdir_p(File.dirname(@socket_path))
+      FileUtils.rm_f(@socket_path)
+    end
+
+    def read_loop(pty_session)
+      loop do
+        break if !pty_session.equal?(@pty_session)
+        break if !pty_session.alive?
+
+        bytes = pty_session.read_nonblock
+
+        next sleep(0.02) if bytes.nil?
+
+        requested = requested_mode(bytes)
+
+        relay_pty_output(bytes.gsub(SAFE_MARKER, '').gsub(UNSAFE_MARKER, ''))
+
+        next if requested.nil?
+
+        switch_mode(sandbox: requested == :safe)
+
+        break
+      end
+    end
+
+    def read_start_message(client)
+      line = client.gets&.chomp
+
+      return if line.nil?
+
+      JSON.parse(line)
+    rescue IOError, JSON::ParserError
+      nil
+    end
+
+    def record_log_line(content:, direction:)
+      return if !RailsConsole.audit
+      return if console_session.nil?
+      return if content.blank?
+
+      RailsConsole::LogLine.create(content:, direction:, session: console_session)
+    end
+
+    def reject_client(client)
+      client.write("Session in use by #{owner_label}, please try again later.\n")
+      client.close
+    end
+
+    def relay_client_input(client)
+      loop do
+        bytes = client.readpartial(RailsConsole::PtySession::READ_SIZE)
+
+        @pty_session&.write(bytes)
+
+        record_log_line(content: bytes, direction: :input)
+      end
+    rescue IOError, Errno::ECONNRESET
+      nil
+    end
+
+    def relay_pty_output(bytes)
+      broadcast(bytes)
+      record_log_line(content: bytes, direction: :output)
+    end
+
+    # Which mode the console asked to switch to, or nil when the output has no marker.
+    def requested_mode(bytes)
+      return :safe if bytes.include?(SAFE_MARKER)
+      return :unsafe if bytes.include?(UNSAFE_MARKER)
+
+      nil
+    end
+
+    def schedule_idle_shutdown
+      return if @shutting_down
+      return if @idle_timer&.alive?
+
+      @idle_timer = Thread.new do
+        sleep(idle_timeout)
+
+        end_session unless @shutting_down
+      end
+    rescue ThreadError
+      nil
+    end
+
+    def start_session(ip_address:, user_id:, user_label:)
+      @console_session = RailsConsole::Session.create!(
+        ip_address:,
+        started_at: Time.current,
+        user_id:,
+        user_label:
+      )
+      @pty_session = RailsConsole::PtySession.new(command: @safe_command, sandbox: true)
+
+      log("Session started for #{owner_label}, pid=#{@pty_session.pid}, sandbox=true")
+
+      Thread.new { read_loop(@pty_session) }
+    end
+
+    def switch_mode(sandbox:)
+      mode = sandbox ? 'SAFE' : 'UNSAFE'
+      command = sandbox ? @safe_command : @unsafe_command
+
+      log_warn("Switching to #{mode} mode for #{owner_label}")
+
+      console_session.update(unsafe_at: Time.current) if !sandbox
+      record_log_line(content: "Switched to #{mode} mode", direction: :transition)
+
+      broadcast(RELOAD_MARKER)
+
+      old_session = @pty_session
+      @pty_session = RailsConsole::PtySession.new(command:, sandbox:)
+
+      old_session.kill!
+
+      log_warn("Session is now #{mode}, pid=#{@pty_session.pid}")
+
+      Thread.new { read_loop(@pty_session) }
+    end
+
+    # Nudges the console to redraw so a just-attached client isn't left staring at a blank screen.
+    def wake_pty
+      @pty_session&.write(REDRAW)
+    end
+  end
+end

data/lib/rails-console/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/numeric/time'
+
+module RailsConsole
+  class << self
+    attr_accessor :audit,
+      :authorize,
+      :command,
+      :current_user,
+      :idle_timeout,
+      :sandbox_command,
+      :user_class
+
+    attr_writer :socket_path
+
+    def config
+      self
+    end
+
+    def configure
+      yield(self)
+    end
+
+    def default_socket_path
+      Rails.root.join('tmp/sockets/rails_console.sock')
+    end
+
+    def socket_path
+      @socket_path || default_socket_path
+    end
+  end
+
+  self.audit = true
+  self.authorize = ->(_user) { false }
+  self.command = 'bundle exec rails console'
+  self.current_user = ->(user) { { id: user&.id, label: user.try(:email) || 'unknown' } }
+  self.idle_timeout = 10.minutes
+  self.sandbox_command = 'bundle exec rails console --sandbox'
+  self.user_class = 'User'
+end

data/lib/rails-console/engine.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsConsole
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsConsole
+
+    # Pagers hang inside the web console PTY, so disable them on whichever REPL the host app uses.
+    console do
+      IRB.conf[:USE_PAGER] = false if defined?(IRB)
+
+      begin
+        require 'pry'
+
+        Pry.config.pager = false
+      rescue LoadError
+        nil
+      end
+    end
+
+    initializer 'rails_console.assets' do |app|
+      next if !app.config.respond_to?(:assets)
+
+      app.config.assets.precompile += %w[rails_console.css rails_console.js]
+    end
+  end
+end

data/lib/rails-console/logging.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsConsole
+  module Logging
+    PREFIX = '[RailsConsole]'
+
+    def log(message)
+      Rails.logger.info("#{PREFIX} #{message}")
+    end
+
+    def log_warn(message)
+      Rails.logger.warn("#{PREFIX} #{message}")
+    end
+  end
+end

data/lib/rails-console/pty_session.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'pty'
+
+module RailsConsole
+  class PtySession
+    READ_SIZE = 8192
+
+    attr_reader :pid
+
+    delegate :write, to: :@input
+
+    def initialize(command: nil, sandbox: true)
+      command ||= sandbox ? RailsConsole.sandbox_command : RailsConsole.command
+
+      @output, @input, @pid = PTY.spawn(self.class.spawn_env, command)
+    end
+
+    # Pagers hang inside the web terminal, so force a pass-through one.
+    def self.spawn_env
+      {
+        'PAGER' => 'cat',
+        'TERM' => 'xterm-256color',
+      }
+    end
+
+    def alive?
+      Process.waitpid(pid, Process::WNOHANG).nil?
+    rescue Errno::ECHILD
+      false
+    end
+
+    def kill!
+      Process.kill('TERM', pid)
+      Process.waitpid(pid)
+    rescue Errno::ESRCH, Errno::ECHILD
+      nil
+    end
+
+    def read_nonblock(size = READ_SIZE)
+      @output.read_nonblock(size)
+    rescue IO::WaitReadable, EOFError
+      nil
+    end
+  end
+end

data/lib/rails-console/unsafe.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+def safe!
+  $stdout.puts(RailsConsole::Broker::SAFE_MARKER)
+  $stdout.flush
+end
+
+def unsafe!
+  $stdout.puts(RailsConsole::Broker::UNSAFE_MARKER)
+  $stdout.flush
+end

data/lib/rails-console/user.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RailsConsole
+  def self.authorized?(context)
+    config.authorize.call(user_from(context))
+  end
+
+  def self.user_from(context)
+    return context.current_user if context.respond_to?(:current_user)
+
+    context.env['warden']&.user
+  end
+end

data/lib/rails-console/version.rb

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

data/lib/rails-console.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsConsole
+end
+
+require 'rails-console/version'
+require 'rails-console/config'
+require 'rails-console/user'
+require 'rails-console/logging'
+require 'rails-console/unsafe'
+require 'rails-console/pty_session'
+require 'rails-console/broker'
+
+require 'rails-console/engine' if defined?(::Rails::Engine)

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: rails-console
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Washington Botelho
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A safe, browser-based Rails console you mount on your app.
+email: wbotelhos@gmail.com
+executables:
+- rails_console
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/rails_console/rails_console.css
+- app/assets/rails_console/rails_console.js
+- app/assets/rails_console/src/application.css
+- app/assets/rails_console/src/console.js
+- app/channels/rails_console/console_channel.rb
+- app/controllers/rails_console/consoles_controller.rb
+- app/models/rails_console/application_record.rb
+- app/models/rails_console/log_line.rb
+- app/models/rails_console/session.rb
+- app/views/layouts/rails_console/application.html.erb
+- app/views/rails_console/consoles/show.html.erb
+- bin/rails_console
+- config/routes.rb
+- lib/generators/rails_console/install_generator.rb
+- lib/generators/rails_console/templates/db/migrate/create_rails_console_log_lines.rb
+- lib/generators/rails_console/templates/db/migrate/create_rails_console_sessions.rb
+- lib/generators/rails_console/templates/rails_console.rb
+- lib/rails-console.rb
+- lib/rails-console/broker.rb
+- lib/rails-console/config.rb
+- lib/rails-console/engine.rb
+- lib/rails-console/logging.rb
+- lib/rails-console/pty_session.rb
+- lib/rails-console/unsafe.rb
+- lib/rails-console/user.rb
+- lib/rails-console/version.rb
+homepage: https://github.com/wbotelhos/rails-console
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A safe, browser-based Rails console you mount on your app.
+test_files: []