system_browser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a327e613373ddd9ce65d00f6709939646690211e
+  data.tar.gz: e2fa5ca9c87a732d6ec25579d2f90ef185f0d11b
+SHA512:
+  metadata.gz: 24af54e9b78af57ee3ec68a3b4f49d43cdfe2dbb956950476492578c025e57cc9f77208324e035d436d64a634a14a5b148553e8041581aff672882b02070a6d0
+  data.tar.gz: 332ec858e408c9dd782d72f97ed3dcd43fbc4093ad3411c6cfe7419d27c856034f5e13f8f8439cd34f3077e6082cfb365dedcbc3e5c597adc45bb20318c39b3d

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+System Browser
+==============
+
+### v0.1.0 (July 20, 2015)
+
+* Initial release

data/LICENCE.txt

@@ -0,0 +1,19 @@
+Copyright (C) 2015 Kyrylo Silin
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

data/README.md

@@ -0,0 +1,72 @@
+System Browser
+==
+
+* [Repository](https://github.com/kyrylo/system_browser_server/)
+* [Client][client]
+
+Description
+-----------
+
+System Browser is a Ruby gem that serves as a bridge between a Ruby process
+and the [System Browser Client][client]. It allows you to browse Ruby
+behaviours (classes and modules), its methods and the methods' source code.
+_Make sure that you have the client installed_.
+
+Examples
+--------
+
+### Basic example
+
+```ruby
+require 'system_browser'
+
+SystemBrowser.start
+```
+
+### Nonblocking start
+
+By default `SystemBrowser.start` blocks the current thread. This is useful if you
+launch the browser from a small script. If you start the browser inside a
+complex framework such as Rails, blocking may be unwanted. In this case start
+the browser like this:
+
+```ruby
+SystemBrowser.start(block: false)
+```
+
+The `block` flag will run the browser in a separate thread and return it (it's
+up to you if you want to join it).
+
+### Debugging
+
+If you wish to contribute, you may find the `debug` flag useful. For debugging
+purposes invoke the browser like this:
+
+```ruby
+SystemBrowser.start(debug: true)
+```
+
+For additional information see the `examples/` directory.
+
+Installation
+------------
+
+All you need is to install the gem.
+
+    gem install system_browser
+
+Limitations
+-----------
+
+Supports *only* CRuby.
+
+* CRuby 2.2.2 and higher
+
+Other Ruby versions were not tested, but in theory Ruby 2.2.x should work fine.
+
+License
+-------
+
+The project uses the Zlib License. See LICENCE.txt file for more information.
+
+[client]: https://github.com/kyrylo/system_browser_client/

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/system_browser.rb

@@ -0,0 +1,52 @@
+require 'socket'
+require 'json'
+require 'logger'
+require 'shellwords'
+
+require 'system_navigation'
+require 'core_classes'
+require 'coderay'
+
+require_relative 'system_browser/server'
+require_relative 'system_browser/client'
+require_relative 'system_browser/session'
+require_relative 'system_browser/request'
+require_relative 'system_browser/request_processor'
+require_relative 'system_browser/response'
+require_relative 'system_browser/slogger'
+require_relative 'system_browser/behaviour'
+require_relative 'system_browser/gem2markdown'
+require_relative 'system_browser/helpers/gem_service_helper'
+require_relative 'system_browser/helpers/behaviour_service_helper'
+require_relative 'system_browser/services/abstract_service'
+require_relative 'system_browser/services/gem_service'
+require_relative 'system_browser/services/behaviour_service'
+require_relative 'system_browser/services/method_service'
+require_relative 'system_browser/services/source_service'
+
+module SystemBrowser
+  ##
+  # Starts the system browser.
+  #
+  # @param debug [Boolean] If true, prints debugging information
+  # @param nonblock [Boolean] If true, then creates a new thread. Otherwise
+  #   runs in the current thread
+  # @return [Session.init]
+  def self.start(debug: false, block: true)
+    $DEBUG_SB = debug
+
+    if $DEBUG_SB
+      Thread.abort_on_exception = true
+    end
+
+    if block
+      SLogger.debug('[browser] Initialising a session, blocking')
+
+      Session.init
+    else
+      SLogger.debug('[browser] Initialising a session, NOT blocking')
+
+      Thread.new { Session.init }
+    end
+  end
+end

data/lib/system_browser/behaviour.rb

@@ -0,0 +1,30 @@
+module SystemBrowser
+  class Behaviour
+    DEFAULT_INSPECT = /#<(?:Module|Class):(0x[0-9a-f]+)>/
+
+    def self.from_str(behaviour_str)
+      self.new(behaviour_str).extract
+    end
+
+    def initialize(behaviour_str)
+      @behaviour_str = behaviour_str
+      @sn = SystemNavigation.default
+    end
+
+    def extract
+      behaviour = eval(@behaviour_str)
+
+      if behaviour.nil? && @behaviour_str.match(DEFAULT_INSPECT)
+        self.find_behaviour_by_object_id(Integer($1))
+      else
+        behaviour
+      end
+    end
+
+    protected
+
+    def find_behaviour_by_object_id(behaviour_id)
+      @sn.all_objects.find { |obj| (obj.__id__ << 1) == behaviour_id  }
+    end
+  end
+end

data/lib/system_browser/client.rb

@@ -0,0 +1,56 @@
+module SystemBrowser
+  class Client
+    ##
+    # The command that the client sends to the server at the session
+    # initialisation.
+    PID_COMMAND = 'set-window-pid'
+
+    ##
+    # The name of the executable of the client application.
+    CLIENT_EXECUTABLE = 'system_browser'
+
+    ##
+    # @return [SystemBrowser::Session]
+    attr_writer :session
+
+    def initialize
+      @init_pid = nil
+    end
+
+    ##
+    # Spawns a new process in a new process group. I really wanted to find the
+    # way to spawn the process in the same group. However, when I do that, I
+    # cannot send any signals to the window anymore (the app crashes, because
+    # the ruby process exits).
+    #
+    # @note +@init_pid+ and +@window_pid+ are two different processes. The
+    # client uses +@init_id+ to bootstrap itself and +@window_pid+ is the
+    # process that can be used to send signals to the client.
+    #
+    # @return [Integer] the process ID of the client application
+    def start
+      @init_pid = spawn(CLIENT_EXECUTABLE, pgroup: true)
+      Process.wait(@init_pid)
+
+      @init_pid
+    end
+
+    ##
+    # @return [Integer] the process ID of the client process (window).
+    def window_pid=(window_pid)
+      SLogger.debug("[client] setting window pid (#{window_pid})")
+      @window_pid = window_pid
+    end
+
+    ##
+    # Destroys the window by sending the SIGINT signal (the window has its own
+    # handlers to destroy itself, so it's not our job). Does not wait for
+    # anything.
+    # @return [void]
+    def close
+      SLogger.debug("[client] interrupting window (#{@window_pid})...")
+
+      Process.kill(:INT, @window_pid)
+    end
+  end
+end

data/lib/system_browser/gem2markdown.rb

@@ -0,0 +1,117 @@
+module SystemBrowser
+  class Gem2Markdown
+    def self.convert(gem)
+      self.new(gem).convert
+    end
+
+    def initialize(gem)
+      @gem = gem
+    end
+
+    def convert
+      description = ''
+
+      [header,
+       summary,
+       homepage,
+       license,
+       author,
+       email,
+       newline,
+       description,
+       newline(2)
+      ].each do |desc|
+        description += (desc || '')
+       end
+
+      {
+        description: description,
+        development_deps: development_deps,
+        runtime_deps: runtime_deps
+      }
+    end
+
+    private
+
+    def header
+      "#{@gem.full_name}\n==" + newline
+    end
+
+    def summary
+      if @gem.summary
+        @gem.summary + newline
+      end
+    end
+
+    def homepage
+      if @gem.homepage
+        li("homepage: #{@gem.homepage}") + newline
+      end
+    end
+
+    def license
+      if @gem.licenses.any?
+        licenses = @gem.licenses.join(', ')
+        li("license: #{licenses}") + newline
+      end
+    end
+
+    def author
+      if @gem.authors.any?
+        authors = @gem.authors.join(', ')
+        li("by #{authors}") + newline
+      end
+    end
+
+    def description
+      if @gem.description
+        @gem.description + newline
+      end
+    end
+
+    def email
+      if @gem.email
+        li_h = 'email: '
+        email = @gem.email
+        item = nil
+
+        item = case email
+               when String
+                 li(li_h + email)
+               when Array
+                 li(li_h + email.join(', '))
+               else
+                 fail RuntimeError, 'wrong email format'
+               end
+
+        item + newline
+      end
+
+    end
+
+    def runtime_deps
+      if @gem.runtime_dependencies.any?
+        @gem.runtime_dependencies.map do |(name, _ver, _type)|
+          name.to_s
+        end
+      end
+    end
+
+    def development_deps
+      if @gem.development_dependencies.any?
+        @gem.development_dependencies.map do |(name, _ver, _type)|
+          name.to_s
+        end
+      end
+    end
+
+
+    def li(item)
+      '* ' + item
+    end
+
+    def newline(n = 1)
+      "\n" * n
+    end
+  end
+end

data/lib/system_browser/helpers/behaviour_service_helper.rb

@@ -0,0 +1,14 @@
+module SystemBrowser
+  module Helpers
+    module BehaviourServiceHelper
+      def stdlib_behaviours
+        CoreClasses::Stdlib.as_set.map do |behaviour|
+          begin
+            eval(behaviour)
+          rescue
+          end
+        end.compact
+      end
+    end
+  end
+end

data/lib/system_browser/helpers/gem_service_helper.rb

@@ -0,0 +1,13 @@
+module SystemBrowser
+  module Helpers
+    module GemServiceHelper
+      def all_gems
+        Gem.loaded_specs
+      end
+
+      def find_gem(gem_name)
+        self.all_gems[gem_name]
+      end
+    end
+  end
+end

data/lib/system_browser/request.rb

@@ -0,0 +1,43 @@
+module SystemBrowser
+  class Request
+    ##
+    # Represents a request that ends connection.
+    FIN = 'FIN'
+
+    attr_reader :action, :resource, :scope, :other, :callback_id
+
+    def initialize(json)
+      @req = self.get_data(json)
+      @data = @req['system_browser_server']
+
+      @action = nil
+      @resource = nil
+      @scope = nil
+      @other = nil
+    end
+
+    def parse
+      @callback_id = @req['callbackId']
+
+      @action = @data['action']
+      @resource = @data['resource']
+      @scope = @data['scope']
+
+      @other = @data['other']
+    end
+
+    def sets_client_pid?
+      @action == Client::PID_COMMAND
+    end
+
+    def client_pid
+      @resource
+    end
+
+    protected
+
+    def get_data(json)
+      JSON.parse(json)
+    end
+  end
+end

data/lib/system_browser/request_processor.rb

@@ -0,0 +1,74 @@
+module SystemBrowser
+  class RequestProcessor
+    ACTIONS = {
+      'get' => 'add',
+      'autoget' => 'autoadd'
+    }.tap { |h| h.default = 'add' }
+
+    def initialize(request:, session:)
+      @request = request
+      @session = session
+      @services = [
+        Services::GemService,
+        Services::BehaviourService,
+        Services::MethodService,
+        Services::SourceService
+      ]
+    end
+
+    def process
+      @request.parse
+
+      if @request.sets_client_pid?
+        @session.set_client_pid(@request.client_pid)
+      else
+        self.process_services
+      end
+    end
+
+    protected
+
+    def process_services
+      service = self.find_service_for(@request.resource).new(
+        data: @request.scope,
+        other: @request.other)
+
+      data = service.__send__(@request.action)
+      data = self.replace_weird_characters(data) if data.instance_of?(String)
+
+      action = self.process_action
+      scope = self.process_scope(action)
+
+      data[:behaviour] = @request.scope if scope.empty?
+
+      action_str = "#{action}:#{@request.resource}:#{scope}"
+      response = Response.new(action: action_str, data: data)
+      response.set_callback_id(@request.callback_id)
+
+      @session.send(response)
+    end
+
+    def process_action
+      ACTIONS[@request.action]
+    end
+
+    def process_scope(action)
+      case action
+      when 'add' then @request.scope
+      when 'autoadd' then ''
+      else @request.scope
+      end
+    end
+
+    def find_service_for(req_service)
+      @services.find { |service| service.service_name == req_service }
+    end
+
+    ##
+    # Temporary hack before we support weird characters for real.
+    def replace_weird_characters(str)
+      ascii_str = str.force_encoding('ASCII-8BIT')
+      ascii_str.encode('UTF-8', undef: :replace, replace: '')
+    end
+  end
+end

data/lib/system_browser/response.rb

@@ -0,0 +1,22 @@
+module SystemBrowser
+  class Response
+    def initialize(data: nil, action: nil, resource: nil)
+      @response = {
+        callback_id: nil,
+        system_browser_client: {
+          action: action,
+          data: data,
+          resource: resource
+        }
+      }
+    end
+
+    def set_callback_id(callback_id)
+      @response[:callback_id] = callback_id
+    end
+
+    def to_json
+      JSON.generate(@response) + "\n"
+    end
+  end
+end

data/lib/system_browser/server.rb

@@ -0,0 +1,82 @@
+module SystemBrowser
+  class Server
+    ##
+    # @return [SystemBrowser::Session]
+    attr_accessor :session
+
+    def initialize(port = 9696)
+      self.create_tcpserver(port)
+    end
+
+    ##
+    # Starts the TCP server.
+    #
+    # @note This method blocks the thread.
+    def start
+      Socket.accept_loop(@tcpserver) do |connection|
+        SLogger.debug("[server] accepted a new connection (#{connection})")
+
+        self.session.connection = connection
+        self.handle_connection(connection)
+      end
+    rescue IOError
+      Thread.exit
+    end
+
+    def shutdown
+      SLogger.debug("[server] shutting down the TCP server...")
+
+      @tcpserver.close
+    end
+
+    protected
+
+    ##
+    # Creates a new TCP server and tries to find a free port.
+    # @return [void]
+    def create_tcpserver(port)
+      @tcpserver = TCPServer.new(port)
+    rescue Errno::EADDRINUSE
+      SLogger.debug("[server] port #{port} is occupied. Trying port #{port + 1}")
+
+      port += 1
+      retry
+    end
+
+    ##
+    # Handles incoming connections.
+    #
+    # @param connection [TCPSocket]
+    # @return [void]
+    def handle_connection(connection)
+      loop do
+        unless readval = connection.gets
+          SLogger.debug("[server] connection #{connection} interrupted")
+
+          shutdown
+          break
+        end
+
+        if readval == Request::FIN
+          SLogger.debug("[server] received the FIN request")
+
+          self.session.destroy
+          break
+        else
+          SLogger.debug("[server] received a request")
+
+          self.process_request(Request.new(readval))
+        end
+      end
+    end
+
+    ##
+    # @param request [SystemBrowser::Request]
+    # @return [void]
+    def process_request(request)
+      RequestProcessor.new(request: request, session: self.session).process
+    rescue => e
+      SLogger.log_error(e)
+    end
+  end
+end

data/lib/system_browser/services/abstract_service.rb

@@ -0,0 +1,15 @@
+module SystemBrowser
+  module Services
+    class AbstractService
+      def self.service_name
+        self.name.split('::').last.split('Service').first.downcase
+      end
+
+      def initialize(data:, other: nil)
+        @sn = SystemNavigation.default
+        @data = data
+        @other = other
+      end
+    end
+  end
+end

data/lib/system_browser/services/behaviour_service.rb

@@ -0,0 +1,68 @@
+module SystemBrowser
+  module Services
+    class BehaviourService < AbstractService
+      CACHED_BEHAVIOURS = {}
+
+      def self.all_from(gem)
+        if CACHED_BEHAVIOURS.has_key?(gem)
+          CACHED_BEHAVIOURS[gem]
+        else
+          CACHED_BEHAVIOURS[gem] = SystemNavigation.new.all_classes_and_modules_in_gem_named(gem)
+        end
+      end
+
+      def get
+         self.behaviours.map do |behaviour|
+          is_module = behaviour.instance_of?(Module)
+
+          superclass = unless is_module
+                         behaviour.superclass
+                       end
+
+          {name: (behaviour.name ? behaviour.name : behaviour.inspect),
+           isModule: is_module,
+           isException: behaviour.ancestors.include?(Exception),
+           superclass: superclass}
+        end
+      end
+
+      def autoget
+        behaviour = SystemBrowser::Behaviour.from_str(@data)
+
+        if CoreClasses.as_set.find { |c| c == behaviour }
+          {gem: GemService::CORE_LABEL}
+        elsif self.stdlib_behaviours.find { |c| c == behaviour }
+          {gem: GemService::STDLIB_LABEL}
+        else
+          behaviours = @sn.all_classes_and_modules_in_gem_named(@other)
+          gem = if behaviours.include?(behaviour)
+                  @other
+                else
+                  self.all_gems.keys.find do |g|
+                    behaviours = @sn.all_classes_and_modules_in_gem_named(g)
+                    behaviours.include?(behaviour)
+                  end
+                end
+
+          {gem: gem}
+        end
+      end
+
+      protected
+
+      include SystemBrowser::Helpers::GemServiceHelper
+      include SystemBrowser::Helpers::BehaviourServiceHelper
+
+      def behaviours
+        case @data
+        when GemService::CORE_LABEL
+          CoreClasses.as_set
+        when GemService::STDLIB_LABEL
+          self.stdlib_behaviours
+        else
+          self.class.all_from(@data)
+        end
+      end
+    end
+  end
+end

data/lib/system_browser/services/gem_service.rb

@@ -0,0 +1,82 @@
+module SystemBrowser
+  module Services
+    class GemService < AbstractService
+      CORE_LABEL = 'Ruby Core'
+      STDLIB_LABEL = 'Ruby Stdlib'
+      DEFAULT_GEMS = [{name: CORE_LABEL}, {name: STDLIB_LABEL}]
+
+      def get
+        gems = self.all_gems.map { |gem| {name: gem.first} }
+        [*DEFAULT_GEMS, *gems]
+      end
+
+      def description(*args)
+        gem = self.find_gem(@data)
+
+        case @data
+        when CORE_LABEL
+          desc = <<DESC
+Ruby Core-#{RUBY_VERSION}
+===
+The Ruby Core defines common Ruby behaviours available to every program.
+DESC
+
+          {
+            description: desc,
+            behaviours: self.count_behaviours(CoreClasses.as_set),
+            development_deps: [],
+            runtime_deps: [],
+          }
+        when STDLIB_LABEL
+          desc = <<DESC
+Ruby Standard Library-#{RUBY_VERSION}
+===
+The Ruby Standard Library is a vast collection of classes and modules that you can require in your code for additional features. System Browser shows only those behaviours that were required by this Ruby process.
+DESC
+          {
+            description: desc,
+            behaviours: self.count_behaviours(BehaviourService.stdlib_behaviours),
+            development_deps: [],
+            runtime_deps: []
+          }
+        else
+          gemdata = Gem2Markdown.convert(gem)
+          behs = BehaviourService.all_from(gem.name)
+          gemdata[:behaviours] = count_behaviours(behs)
+          gemdata
+        end
+      end
+
+      def open
+        editor = [ENV['VISUAL'], ENV['EDITOR']].find{|e| !e.nil? && !e.empty? }
+        path = self.find_gem(@data).full_gem_path
+
+        command = [*Shellwords.split(editor), path]
+
+        system(*command)
+
+        :ok
+      end
+
+      protected
+
+      include SystemBrowser::Helpers::GemServiceHelper
+
+      def count_behaviours(collection)
+        behaviours = {}
+
+        grouped = collection.group_by(&:class)
+
+        exceptions = (grouped[Class] || []).group_by do |beh|
+          beh.ancestors.include?(Exception)
+        end
+
+        behaviours['modules'] = (grouped[Module] || []).count
+        behaviours['classes'] = (exceptions[false] || []).count
+        behaviours['exceptions'] = (exceptions[true] || []).count
+
+        behaviours
+      end
+    end
+  end
+end

data/lib/system_browser/services/method_service.rb

@@ -0,0 +1,30 @@
+module SystemBrowser
+  module Services
+    class MethodService < AbstractService
+      def get
+        behaviour = SystemBrowser::Behaviour.from_str(@data)
+        method_hash = @sn.all_methods_in_behavior(behaviour)
+        method_names_hash(method_hash)
+      end
+
+      protected
+
+      def method_names_hash(method_hash)
+        new_h = {}
+
+        method_hash.keys.each do |key|
+          new_val = method_hash[key].map do |k, values|
+            {
+              k => values.map do |m|
+               {name: m.name.to_s, c_method: m.source_location.nil? }
+              end
+            }
+          end
+          new_h[key] = new_val.first.merge(new_val.last)
+        end
+
+        new_h
+      end
+    end
+  end
+end

data/lib/system_browser/services/source_service.rb

@@ -0,0 +1,60 @@
+module SystemBrowser
+  module Services
+    class SourceService < AbstractService
+      def get
+        method = @other['method']['displayName']
+        owner = SystemBrowser::Behaviour.from_str(@other['owner'])
+
+        owner = (method.start_with?('#') ? owner : owner.singleton_class)
+        unbound_method = owner.instance_method(method[1..-1].to_sym)
+        source = FastMethodSource.comment_and_source_for(unbound_method)
+
+        CodeRay.scan(self.unindent(source), :ruby).div
+      end
+
+      protected
+
+      # Remove any common leading whitespace from every line in `text`.
+      #
+      # This can be used to make a HEREDOC line up with the left margin, without
+      # sacrificing the indentation level of the source code.
+      #
+      # e.g.
+      #   opt.banner unindent <<-USAGE
+      #     Lorem ipsum dolor sit amet, consectetur adipisicing elit,
+      #     sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+      #       "Ut enim ad minim veniam."
+      #   USAGE
+      #
+      # Heavily based on textwrap.dedent from Python, which is:
+      #   Copyright (C) 1999-2001 Gregory P. Ward.
+      #   Copyright (C) 2002, 2003 Python Software Foundation.
+      #   Written by Greg Ward <gward@python.net>
+      #
+      #   Licensed under <http://docs.python.org/license.html>
+      #   From <http://hg.python.org/cpython/file/6b9f0a6efaeb/Lib/textwrap.py>
+      #
+      # @param [String] text The text from which to remove indentation
+      # @return [String] The text with indentation stripped.
+      def unindent(text, left_padding = 0)
+        # Empty blank lines
+        text = text.sub(/^[ \t]+$/, '')
+
+        # Find the longest common whitespace to all indented lines
+        # Ignore lines containing just -- or ++ as these seem to be used by
+        # comment authors as delimeters.
+        margin = text.scan(/^[ \t]*(?!--\n|\+\+\n)(?=[^ \t\n])/).inject do |current_margin, next_indent|
+          if next_indent.start_with?(current_margin)
+            current_margin
+          elsif current_margin.start_with?(next_indent)
+            next_indent
+          else
+            ""
+          end
+        end
+
+        text.gsub(/^#{margin}/, ' ' * left_padding)
+      end
+    end
+  end
+end

data/lib/system_browser/session.rb

@@ -0,0 +1,108 @@
+module SystemBrowser
+  ##
+  # This class glues {SystemBrowser::Server} and {SystemBrowser::Client}
+  # providing the support for interaction between them.
+  class Session
+    @@running_session = false
+
+    ##
+    # Initialises a new session.
+    def self.init
+      if @@running_session
+        SLogger.debug("can't init a new session! Kill the old one first")
+        return
+      else
+        @@running_session = true
+      end
+
+      self.new(Server.new, Client.new).init
+    end
+
+    # @return [TCPSocket] the connection between the server and the client
+    attr_reader :connection
+
+    def initialize(server, client)
+      @server = server
+      @client = client
+      [@server, @client].each { |o| o.session = self }
+
+      @previous_sigint_callback = nil
+
+      self.register_sigint_hook
+    end
+
+    ##
+    # Runs {SystemBrowser::Server} in background. Invokes {SystemBrowser::Client}
+    # and suspends the calling thread for the duration of the client.
+    # @return [void]
+    def init
+      Thread.new { @server.start }
+      Thread.new { @client.start }.join
+
+      true
+    end
+
+    def destroy
+      self.restore_previous_sigint
+
+      @client.close
+      @server.shutdown
+
+      @@running_session = false
+
+      SLogger.debug('[SESSION] the session was destroyed')
+    end
+
+    ##
+    # Sets the client's window pid (real pid).
+    def set_client_pid(pid)
+      @client.window_pid = pid
+    end
+
+    ##
+    # Sends a response to the client.
+    #
+    # @param response [SystemBrowser::Response] the data to be sent to the client
+    # @return [void]
+    def send(response)
+      self.connection.puts(response.to_json)
+    end
+
+    ##
+    # @param connection [TCPSocket] the connection between the server and the
+    # client
+    # @return [void]
+    def connection=(connection)
+      @connection = connection
+      self.initialize_connection
+    end
+
+    protected
+
+    ##
+    # This method bootstraps the connection between the server and the client.
+    # @return [void]
+    def initialize_connection
+      self.send(Response.new(action: 'init'))
+    end
+
+    def restore_previous_sigint
+      Signal.trap(:INT, @previous_sigint_callback)
+    end
+
+    def register_sigint_hook
+      @previous_sigint_callback = Signal.trap(:INT, '')
+
+      Signal.trap(:INT) do
+        SLogger.debug('[SESSION] received Ctrl-C, killing myself softly')
+
+        self.destroy
+
+        if @previous_sigint_callback.instance_of?(Proc)
+          self.restore_previous_sigint
+          @previous_sigint_callback.call
+        end
+      end
+    end
+  end
+end

data/lib/system_browser/slogger.rb

@@ -0,0 +1,22 @@
+module SystemBrowser
+  module SLogger
+    class << self
+      @@logger = ::Logger.new(STDOUT)
+
+      [:debug, :error, :info].each do |m|
+        define_method(m) do |*args, &block|
+          if $DEBUG_SB
+            # Avoid the 'log writing failed due to trap' message in trap contexts.
+            Thread.new { @@logger.__send__(m, *args, &block) }.join
+          end
+        end
+      end
+
+      def log_error(error)
+        SLogger.error(error.class) do
+          [error.to_s, error.backtrace].join("\n")
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: system_browser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kyrylo Silin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: system_navigation
+  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: core_classes
+  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: coderay
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+description: ''
+email: silin@kyrylo.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENCE.txt
+- README.md
+- VERSION
+- lib/system_browser.rb
+- lib/system_browser/behaviour.rb
+- lib/system_browser/client.rb
+- lib/system_browser/gem2markdown.rb
+- lib/system_browser/helpers/behaviour_service_helper.rb
+- lib/system_browser/helpers/gem_service_helper.rb
+- lib/system_browser/request.rb
+- lib/system_browser/request_processor.rb
+- lib/system_browser/response.rb
+- lib/system_browser/server.rb
+- lib/system_browser/services/abstract_service.rb
+- lib/system_browser/services/behaviour_service.rb
+- lib/system_browser/services/gem_service.rb
+- lib/system_browser/services/method_service.rb
+- lib/system_browser/services/source_service.rb
+- lib/system_browser/session.rb
+- lib/system_browser/slogger.rb
+homepage: https://github.com/kyrylo/system_browser
+licenses:
+- Zlib
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: ''
+test_files: []
+has_rdoc: