i2p 0.1.4

data/AUTHORS

@@ -0,0 +1 @@
+* Arto Bendiken <arto.bendiken@gmail.com>

data/README

@@ -0,0 +1,155 @@
+I2P.rb: Anonymous Networking for Ruby
+=====================================
+
+This is a Ruby library for interacting with the [I2P][] anonymity network.
+
+* <http://github.com/bendiken/i2p-ruby>
+
+Features
+--------
+
+* Supports checking whether I2P is installed in the user's current `PATH`
+  and whether the I2P router is currently running.
+* Supports starting, restarting and stopping the I2P router daemon.
+* Implements the [I2P Basic Open Bridge (BOB)][BOB] protocol.
+* Implements the basics of the [I2P Simple Anonymous Messaging (SAM)][SAM]
+  protocol.
+* Supports I2P name resolution using both `hosts.txt` as well as SAM.
+* Compatible with Ruby 1.8.7+, Ruby 1.9.x, and JRuby 1.4/1.5.
+* Bundles the I2P 0.8 [SDK][] and [Streaming Library][Streaming] for use
+  with [JRuby][],
+
+Examples
+--------
+
+    require 'rubygems'
+    require 'i2p'
+
+### Checking whether an I2P router is running locally
+
+    I2P.available?      #=> true, if the I2P router is installed
+    I2P.running?        #=> true, if the I2P router is running
+
+### Starting and stopping the local I2P router daemon
+
+    I2P.start!          #=> executes `i2prouter start`
+    I2P.restart!        #=> executes `i2prouter restart`
+    I2P.stop!           #=> executes `i2prouter stop`
+
+### Looking up the public key for an I2P name from hosts.txt
+
+    puts I2P::Hosts["forum.i2p"].to_base64
+
+### Looking up the public key for an I2P name using SAM
+
+    I2P::SAM::Client.open(:port => 7656) do |sam|
+      puts sam.lookup_name("forum.i2p").to_base64
+    end
+
+### Generating a new key pair and I2P destination using SAM
+
+    I2P::SAM::Client.open(:port => 7656) do |sam|
+      key_pair = sam.generate_destination
+      puts key_pair.destination.to_base64
+    end
+
+### Creating an inproxy tunnel to an eepsite using BOB
+
+    I2P::BOB::Tunnel.start(:inport => 12345) do |tunnel|
+      sleep 0.1 until tunnel.running?
+
+      TCPSocket.open("127.0.0.1", 12345) do |socket|
+        socket.puts "bob.i2p" # the I2P destination
+
+        socket.write "HEAD / HTTP/1.1\r\n\r\n"
+        socket.flush
+        until (line = socket.readline).chomp.empty?
+          puts line
+        end
+        socket.close
+      end
+    end
+
+### Creating an outproxy tunnel to your SSH daemon using BOB
+
+    tunnel = I2P::BOB::Tunnel.start({
+      :nickname => :myssh,
+      :outhost  => "127.0.0.1",
+      :outport  => 22, # SSH port
+      :quiet    => true,
+    })
+    puts tunnel.destination.to_base64
+
+### Using the I2P SDK and Streaming Library directly from JRuby
+
+I2P.rb bundles the public-domain [I2P SDK][SDK] (`i2p/sdk.jar`) and
+[Streaming Library][Streaming] (`i2p/streaming.jar`) archives, which means
+that to [script][JRuby howto] the I2P Java client implementation from
+[JRuby][], you need only require these two files as follows:
+
+    require 'i2p/sdk.jar'
+    require 'i2p/streaming.jar'
+
+Documentation
+-------------
+
+* <http://cypherpunk.rubyforge.org/i2p/>
+
+Dependencies
+------------
+
+* [Ruby](http://ruby-lang.org/) (>= 1.8.7) or (>= 1.8.1 with [Backports][])
+* [I2P](http://www.i2p2.de/download.html) (>= 0.8)
+
+Installation
+------------
+
+The recommended installation method is via [RubyGems](http://rubygems.org/).
+To install the latest official release of I2P.rb, do:
+
+    % [sudo] gem install i2p                 # Ruby 1.8.7+ or 1.9.x
+    % [sudo] gem install backports i2p       # Ruby 1.8.1+
+
+Environment
+-----------
+
+The following are the default values for environment variables that let
+you customize I2P.rb's implicit configuration:
+
+    $ export I2P_PATH=$PATH
+    $ export I2P_BOB_HOST=127.0.0.1
+    $ export I2P_BOB_PORT=2827
+    $ export I2P_SAM_HOST=127.0.0.1
+    $ export I2P_SAM_PORT=7656
+
+Download
+--------
+
+To get a local working copy of the development repository, do:
+
+    % git clone git://github.com/bendiken/i2p-ruby.git
+
+Alternatively, you can download the latest development version as a tarball
+as follows:
+
+    % wget http://github.com/bendiken/i2p-ruby/tarball/master
+
+Author
+------
+
+* [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
+
+License
+-------
+
+I2P.rb is free and unencumbered public domain software. For more
+information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
+
+[I2P]:         http://www.i2p2.de/
+[SDK]:         http://www.i2p2.de/package-client.html
+[Streaming]:   http://www.i2p2.de/package-streaming.html
+[SAM]:         http://www.i2p2.de/samv3.html
+[BOB]:         http://bob.i2p.to/bridge.htm
+[JRuby]:       http://jruby.org/
+[JRuby howto]: http://kenai.com/projects/jruby/pages/CallingJavaFromJRuby
+[Backports]:   http://rubygems.org/gems/backports

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.1.4

data/lib/i2p.rb

@@ -0,0 +1,177 @@
+require 'pathname'
+require 'socket'
+require 'stringio'
+
+if RUBY_VERSION < '1.8.7'
+  # @see http://rubygems.org/gems/backports
+  begin
+    require 'backports/1.8.7'
+  rescue LoadError
+    begin
+      require 'rubygems'
+      require 'backports/1.8.7'
+    rescue LoadError
+      abort "I2P.rb requires Ruby 1.8.7 or the Backports gem (hint: `gem install backports')."
+    end
+  end
+end
+
+##
+# @example Checking whether an I2P router is running locally
+#   I2P.available?      #=> true, if the I2P router is installed
+#   I2P.running?        #=> true, if the I2P router is running
+#
+# @example Starting and stopping the local I2P router daemon
+#   I2P.start!          #=> executes `i2prouter start`
+#   I2P.restart!        #=> executes `i2prouter restart`
+#   I2P.stop!           #=> executes `i2prouter stop`
+#
+# @see http://www.i2p2.de/download.html
+module I2P
+  # Name resolution
+  autoload :Hosts,             'i2p/hosts'
+
+  # Data structures
+  autoload :Structure,         'i2p/data/structure'
+  autoload :Certificate,       'i2p/data/certificate'
+  autoload :Key,               'i2p/data/key'
+  autoload :PrivateKey,        'i2p/data/private_key'
+  autoload :SigningPrivateKey, 'i2p/data/signing_private_key'
+  autoload :PublicKey,         'i2p/data/public_key'
+  autoload :SigningPublicKey,  'i2p/data/signing_public_key'
+  autoload :Destination,       'i2p/data/destination'
+  autoload :KeyPair,           'i2p/data/key_pair'
+
+  # Client protocols
+  autoload :BOB,               'i2p/bob'
+  autoload :SAM,               'i2p/sam'
+
+  # Miscellaneous
+  autoload :VERSION,           'i2p/version'
+
+  # The path used to locate the `i2prouter` executable.
+  PATH = (ENV['I2P_PATH'] || ENV['PATH']).split(File::PATH_SEPARATOR) unless defined?(PATH)
+
+  ##
+  # Returns `true` if I2P is available, `false` otherwise.
+  #
+  # This attempts to locate the `i2prouter` executable in the user's current
+  # `PATH` environment.
+  #
+  # @example
+  #   I2P.available?    #=> true
+  #
+  # @return [Boolean]
+  def self.available?
+    !!program_path
+  end
+
+  ##
+  # Returns `true` if the I2P router is running locally, `false` otherwise.
+  #
+  # This first attempts to call `i2prouter status` if the executable can be
+  # located in the user's current `PATH` environment, falling back to
+  # attempting to establish a Simple Anonymous Messaging (SAM) protocol
+  # connection to the standard SAM port 7656 on `localhost`.
+  #
+  # If I2P isn't in the `PATH` and hasn't been configured with SAM enabled,
+  # this will return `false` regardless of whether I2P actually is running
+  # or not.
+  #
+  # @example
+  #   I2P.running?      #=> false
+  #
+  # @return [Boolean]
+  def self.running?
+    if available?
+      /is running/ === `#{program_path} status`.chomp
+    else
+      begin
+        I2P::SAM::Client.open.disconnect
+        true
+      rescue Errno::ECONNREFUSED
+        false
+      end
+    end
+  end
+
+  ##
+  # Starts the local I2P router daemon.
+  #
+  # Returns the process identifier (PID) if the I2P router daemon was
+  # successfully started, `nil` otherwise.
+  #
+  # This relies on being able to execute `i2prouter start`, which requires
+  # the `i2prouter` executable to be located in the user's current `PATH`
+  # environment.
+  #
+  # @return [Integer]
+  # @since  0.1.1
+  def self.start!
+    if available?
+      `#{program_path} start` unless running?
+      `#{program_path} status` =~ /is running \((\d+)\)/ ? $1.to_i : nil
+    end
+  end
+
+  ##
+  # Restarts the local I2P router daemon, starting it in case it wasn't
+  # already running.
+  #
+  # Returns `true` if the I2P router daemon was successfully restarted,
+  # `false` otherwise.
+  #
+  # This relies on being able to execute `i2prouter restart`, which requires
+  # the `i2prouter` executable to be located in the user's current `PATH`
+  # environment.
+  #
+  # @return [Boolean]
+  # @since  0.1.1
+  def self.restart!
+    if available?
+      /Starting I2P Service/ === `#{program_path} restart`
+    end
+  end
+
+  ##
+  # Stops the local I2P router daemon.
+  #
+  # Returns `true` if the I2P router daemon was successfully shut down,
+  # `false` otherwise.
+  #
+  # This relies on being able to execute `i2prouter stop`, which requires
+  # the `i2prouter` executable to be located in the user's current `PATH`
+  # environment.
+  #
+  # @return [Boolean]
+  # @since  0.1.1
+  def self.stop!
+    if available?
+      /Stopped I2P Service/ === `#{program_path} stop`
+    end
+  end
+
+  ##
+  # Returns the path to the `i2prouter` executable.
+  #
+  # Returns `nil` if the program could not be located in any of the
+  # directories denoted by the user's current `I2P_PATH` or `PATH`
+  # environment variables.
+  #
+  # @example
+  #   I2P.program_path  #=> "/opt/local/bin/i2prouter"
+  #
+  # @param  [String, #to_s] program_name
+  # @return [Pathname]
+  def self.program_path(program_name = :i2prouter)
+    program_name = program_name.to_s
+    @program_paths ||= {}
+    @program_paths[program_name] ||= begin
+      PATH.find do |dir|
+        if File.executable?(file = File.join(dir, program_name))
+          break Pathname(file)
+        end
+      end
+    end
+  end
+end

data/lib/i2p/bob.rb

@@ -0,0 +1,27 @@
+module I2P
+  ##
+  # **I2P Basic Open Bridge (BOB) protocol.**
+  #
+  # This is an implementation of the BOB protocol, available since I2P
+  # release [0.6.5](http://www.i2p2.de/release-0.6.5.html).
+  #
+  # Note that for security reasons, the BOB application bridge is not
+  # enabled by default in new I2P installations. To use `I2P::BOB`,
+  # you must first manually enable BOB in the router console's
+  # [client configuration](http://localhost:7657/configclients.jsp).
+  #
+  # @see http://www.i2p2.de/applications.html
+  # @see http://bob.i2p.to/bridge.html
+  module BOB
+    PROTOCOL_VERSION = 1
+    DEFAULT_HOST     = (ENV['I2P_BOB_HOST'] || '127.0.0.1').to_s
+    DEFAULT_PORT     = (ENV['I2P_BOB_PORT'] || 2827).to_i
+
+    autoload :Client, 'i2p/bob/client'
+    autoload :Tunnel, 'i2p/bob/tunnel'
+
+    ##
+    # **I2P Basic Open Bridge (BOB) protocol error conditions.**
+    class Error < StandardError; end
+  end
+end

data/lib/i2p/bob/client.rb

@@ -0,0 +1,489 @@
+module I2P; module BOB
+  ##
+  # **I2P Basic Open Bridge (BOB) client.**
+  #
+  # @example Connecting to the I2P BOB bridge (1)
+  #   bob = I2P::BOB::Client.new(:port => 2827)
+  #
+  # @example Connecting to the I2P BOB bridge (2)
+  #   I2P::BOB::Client.open(:port => 2827) do |bob|
+  #     ...
+  #   end
+  #
+  # @example Generating a new destination
+  #   I2P::BOB::Client.open(:nickname => :foo) do |bob|
+  #     bob.newkeys
+  #   end
+  #
+  # @example Generating a new key pair
+  #   I2P::BOB::Client.open(:nickname => :foo) do |bob|
+  #     bob.newkeys
+  #     bob.getkeys
+  #   end
+  #
+  # @see   http://www.i2p2.de/applications.html
+  # @see   http://bob.i2p.to/bridge.html
+  # @since 0.1.4
+  class Client
+    ##
+    # Establishes a connection to the BOB bridge.
+    #
+    # @example Connecting to the default port
+    #   bob = I2P::BOB::Client.open
+    #
+    # @example Connecting to the given port
+    #   bob = I2P::BOB::Client.open(:port => 2827)
+    #
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :host    (DEFAULT_HOST)
+    # @option options [Integer, #to_i] :port    (DEFAULT_PORT)
+    # @yield  [client]
+    # @yieldparam [Client] client
+    # @return [void]
+    def self.open(options = {}, &block)
+      client = self.new(options)
+      client.connect
+
+      if options[:nickname]
+        begin
+          client.getnick(options[:nickname])
+        rescue Error => e
+          client.setnick(options[:nickname])
+        end
+      end
+
+      client.setkeys(options[:keys])     if options[:keys]
+      client.quiet(options[:quiet])      if options[:quiet]
+      client.inhost(options[:inhost])    if options[:inhost]
+      client.inport(options[:inport])    if options[:inport]
+      client.outhost(options[:outhost])  if options[:outhost]
+      client.outport(options[:outport])  if options[:outport]
+
+      unless block_given?
+        client
+      else
+        begin
+          result = case block.arity
+            when 1 then block.call(client)
+            else client.instance_eval(&block)
+          end
+        ensure
+          client.disconnect
+        end
+        result
+      end
+    end
+
+    ##
+    # Returns the socket connection to the BOB bridge.
+    #
+    # @return [TCPSocket]
+    attr_reader :socket
+
+    ##
+    # Returns the host name or IP address of the BOB bridge.
+    #
+    # @return [String]
+    attr_reader :host
+
+    ##
+    # Returns the port number of the BOB bridge.
+    #
+    # @return [Integer]
+    attr_reader :port
+
+    ##
+    # Initializes a new client instance.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [String, #to_s]  :host    (DEFAULT_HOST)
+    # @option options [Integer, #to_i] :port    (DEFAULT_PORT)
+    # @yield  [client]
+    # @yieldparam [Client] client
+    def initialize(options = {}, &block)
+      @options = options.dup
+      @host    = (@options.delete(:host) || DEFAULT_HOST).to_s
+      @port    = (@options.delete(:port) || DEFAULT_PORT).to_i
+
+      if block_given?
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+      end
+    end
+
+    ##
+    # Returns `true` if a connection to the BOB bridge has been established
+    # and is active.
+    #
+    # @example
+    #   bob.connected?                       #=> true
+    #   bob.disconnect
+    #   bob.connected?                       #=> false
+    #
+    # @return [Boolean]
+    def connected?
+      !!@socket
+    end
+
+    ##
+    # Establishes a connection to the BOB bridge.
+    #
+    # If called after the connection has already been established,
+    # disconnects and then reconnects to the bridge.
+    #
+    # @example
+    #   bob.connect
+    #
+    # @return [void]
+    def connect
+      disconnect if connected?
+      @socket = TCPSocket.new(@host, @port)
+      @socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+      read_line # "BOB 00.00.0D"
+      read_line # "OK"
+      self
+    end
+    alias_method :reconnect, :connect
+
+    ##
+    # Closes the connection to the BOB bridge.
+    #
+    # If called after the connection has already been closed, does nothing.
+    #
+    # @example
+    #   bob.disconnect
+    #
+    # @return [void]
+    def disconnect
+      @socket.close if @socket && !@socket.closed?
+      @socket = nil
+      self
+    end
+    alias_method :close, :disconnect
+
+    ##
+    # Closes the connection to the BOB bridge cleanly.
+    #
+    # @example
+    #   bob.quit
+    #
+    # @return [void]
+    def quit
+      send_command(:quit)
+      read_response # "Bye!"
+      disconnect
+    end
+    alias_method :quit!, :quit
+
+    ##
+    # Verifies a Base64-formatted key pair or destination, returning `true`
+    # for valid input.
+    #
+    # @example
+    #   bob.verify("foobar")                 #=> false
+    #   bob.verify(I2P::Hosts["forum.i2p"])  #=> true
+    #
+    # @param  [#to_base64, #to_s] data
+    # @return [Boolean]
+    def verify(data)
+      send_command(:verify, data.respond_to?(:to_base64) ? data.to_base64 : data.to_s)
+      read_response rescue false
+    end
+
+    ##
+    # Creates a new tunnel with the given nickname.
+    #
+    # @example
+    #   bob.setnick(:foo)
+    #
+    # @param  [String, #to_s] nickname
+    # @return [void]
+    def setnick(nickname)
+      send_command(:setnick, @options[:nickname] = nickname.to_s)
+      read_response # "Nickname set to #{nickname}"
+      self
+    end
+    alias_method :nickname=, :setnick
+
+    ##
+    # Selects an existing tunnel with the given nickname.
+    #
+    # @example
+    #   bob.getnick(:foo)
+    #
+    # @param  [String, #to_s] nickname
+    # @return [void]
+    def getnick(nickname)
+      send_command(:getnick, @options[:nickname] = nickname.to_s)
+      read_response # "Nickname set to #{nickname}"
+      self
+    end
+
+    ##
+    # Generates a new keypair for the current tunnel.
+    #
+    # @example
+    #   bob.newkeys
+    #
+    # @return [Destination]
+    def newkeys
+      send_command(:newkeys)
+      Destination.parse(read_response)
+    end
+
+    ##
+    # Returns the destination for the current tunnel.
+    #
+    # @example
+    #   bob.getdest
+    #
+    # @return [Destination]
+    # @raise  [Error] if no tunnel has been selected
+    def getdest
+      send_command(:getdest)
+      Destination.parse(read_response)
+    end
+
+    ##
+    # Returns the key pair for the current tunnel.
+    #
+    # @example
+    #   bob.getkeys
+    #
+    # @return [KeyPair]
+    # @raise  [Error] if no public key has been set
+    def getkeys
+      send_command(:getkeys)
+      KeyPair.parse(read_response)
+    end
+
+    ##
+    # Sets the key pair for the current tunnel.
+    #
+    # @example
+    #   bob.setkeys(I2P::KeyPair.parse("..."))
+    #
+    # @param  [KeyPair, #to_s] key_pair
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def setkeys(key_pair)
+      send_command(:setkeys, @options[:keys] = key_pair.respond_to?(:to_base64) ? key_pair.to_base64 : key_pair.to_s)
+      read_response # the Base64-encoded destination
+      self
+    end
+    alias_method :keys=, :setkeys
+
+    ##
+    # Sets the inbound host name or IP address that the current tunnel
+    # listens on.
+    #
+    # The default for new tunnels is `inhost("localhost")`.
+    #
+    # @example
+    #   bob.inhost('127.0.0.1')
+    #
+    # @param  [String, #to_s] host
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def inhost(host)
+      send_command(:inhost, @options[:inhost] = host.to_s)
+      read_response # "inhost set"
+      self
+    end
+    alias_method :inhost=, :inhost
+
+    ##
+    # Sets the inbound port number that the current tunnel listens on.
+    #
+    # @example
+    #   bob.inport(37337)
+    #
+    # @param  [Integer, #to_i] port
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def inport(port)
+      send_command(:inport, @options[:inport] = port.to_i)
+      read_response # "inbound port set"
+      self
+    end
+    alias_method :inport=, :inport
+
+    ##
+    # Sets the outbound host name or IP address that the current tunnel
+    # connects to.
+    #
+    # The default for new tunnels is `outhost("localhost")`.
+    #
+    # @example
+    #   bob.outhost('127.0.0.1')
+    #
+    # @param  [String, #to_s] host
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def outhost(host)
+      send_command(:outhost, @options[:outhost] = host.to_s)
+      read_response # "outhost set"
+      self
+    end
+    alias_method :outhost=, :outhost
+
+    ##
+    # Sets the outbound port number that the current tunnel connects to.
+    #
+    # @example
+    #   bob.outport(80)
+    #
+    # @param  [Integer, #to_i] port
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def outport(port)
+      send_command(:outport, @options[:output] = port.to_i)
+      read_response # "outbound port set"
+      self
+    end
+    alias_method :outport=, :outport
+
+    ##
+    # Toggles whether to send the incoming destination key to listening
+    # sockets.
+    #
+    # This only applies to outbound tunnels and has no effect on inbound
+    # tunnels.
+    #
+    # The default for new tunnels is `quiet(false)`.
+    #
+    # @example Enabling quiet mode
+    #   bob.quiet
+    #   bob.quiet(true)
+    #   bob.quiet = true
+    #
+    # @example Disabling quiet mode
+    #   bob.quiet(false)
+    #   bob.quiet = false
+    #
+    # @param  [Boolean] value
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def quiet(value = true)
+      send_command(:quiet, @options[:quiet] = value.to_s)
+      read_response # "Quiet set"
+      self
+    end
+    alias_method :quiet=, :quiet
+
+    ##
+    # Sets an I2P Control Protocol (I2CP) option for the current tunnel.
+    #
+    # @example
+    #   bob.option(key, value)
+    #
+    # @param  [String, #to_s] key
+    # @param  [String, #to_s] value
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    def option(key, value)
+      send_command(:option, [key, value].join('='))
+      read_response # "#{key} set to #{value}"
+      self
+    end
+
+    ##
+    # Starts and activates the current tunnel.
+    #
+    # @example
+    #   bob.start
+    #
+    # @return [void]
+    # @raise  [Error] if the tunnel settings are incomplete
+    # @raise  [Error] if the tunnel is already active
+    def start
+      send_command(:start)
+      read_response # "tunnel starting"
+      self
+    end
+    alias_method :start!, :start
+
+    ##
+    # Stops and inactivates the current tunnel.
+    #
+    # @example
+    #   bob.stop
+    #
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    # @raise  [Error] if the tunnel is already inactive
+    def stop
+      send_command(:stop)
+      read_response # "tunnel stopping"
+      self
+    end
+    alias_method :stop!, :stop
+
+    ##
+    # Removes the current tunnel. The tunnel must be inactive.
+    #
+    # @example
+    #   bob.clear
+    #
+    # @return [void]
+    # @raise  [Error] if no tunnel has been selected
+    # @raise  [Error] if the tunnel is still active
+    def clear
+      send_command(:clear)
+      read_response # "cleared"
+      self
+    end
+    alias_method :clear!, :clear
+
+  protected
+
+    ##
+    # Sends a command over the BOB bridge socket.
+    #
+    # @param  [String, #to_s] command
+    # @param  [Array<#to_s>]  args
+    # @return [void]
+    def send_command(command, *args)
+      send_line([command.to_s, *args].join(' '))
+    end
+
+    ##
+    # Sends a text line over the BOB bridge socket.
+    #
+    # @param  [String, #to_s] line
+    # @return [void]
+    def send_line(line)
+      connect unless connected?
+      warn "-> #{line}" if @options[:debug]
+      @socket.write(line.to_s + "\n")
+      @socket.flush
+      self
+    end
+
+    ##
+    # Reads a response from the BOB bridge socket.
+    #
+    # @return [Object]
+    # @raise  [Error] on an ERROR response
+    def read_response
+      case line = read_line
+        when 'OK'             then true
+        when /^OK\s*(.*)$/    then $1.strip
+        when /^ERROR\s+(.*)$/ then raise Error.new($1.strip)
+        else line
+      end
+    end
+
+    ##
+    # Reads a text line from the BOB bridge socket.
+    #
+    # @return [String]
+    def read_line
+      line = @socket.readline.chomp
+      warn "<- #{line}" if @options[:debug]
+      line
+    end
+  end
+end; end