Class: I2P::BOB::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/i2p/bob/client.rb

Overview

**I2P Basic Open Bridge (BOB) client.**

Examples:

Connecting to the I2P BOB bridge (1)

bob = I2P::BOB::Client.new(:port => 2827)

Connecting to the I2P BOB bridge (2)

I2P::BOB::Client.open(:port => 2827) do |bob|
  ...
end

Generating a new destination

I2P::BOB::Client.open(:nickname => :foo) do |bob|
  bob.newkeys
end

Generating a new key pair

I2P::BOB::Client.open(:nickname => :foo) do |bob|
  bob.newkeys
  bob.getkeys
end

See Also:

Since:

  • 0.1.4

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|client| ... } ⇒ Client

Initializes a new client instance.

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :host (String, #to_s) — default: DEFAULT_HOST
  • :port (Integer, #to_i) — default: DEFAULT_PORT

Yields:

  • (client)

Yield Parameters:

Since:

  • 0.1.4



103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/i2p/bob/client.rb', line 103

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

Instance Attribute Details

#host ⇒ String (readonly)

Returns the host name or IP address of the BOB bridge.

Returns:

  • (String)

Since:

  • 0.1.4



87
88
89
 
# File 'lib/i2p/bob/client.rb', line 87

def host
  @host
end

#port ⇒ Integer (readonly)

Returns the port number of the BOB bridge.

Returns:

  • (Integer)

Since:

  • 0.1.4



93
94
95
 
# File 'lib/i2p/bob/client.rb', line 93

def port
  @port
end

#socket ⇒ TCPSocket (readonly)

Returns the socket connection to the BOB bridge.

Returns:

  • (TCPSocket)

Since:

  • 0.1.4



81
82
83
 
# File 'lib/i2p/bob/client.rb', line 81

def socket
  @socket
end

Class Method Details

.open(options = {}) {|client| ... } ⇒ void

This method returns an undefined value.

Establishes a connection to the BOB bridge.

Examples:

Connecting to the default port

bob = I2P::BOB::Client.open

Connecting to the given port

bob = I2P::BOB::Client.open(:port => 2827)

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :host (String, #to_s) — default: DEFAULT_HOST
  • :port (Integer, #to_i) — default: DEFAULT_PORT

Yields:

  • (client)

Yield Parameters:

Since:

  • 0.1.4



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/i2p/bob/client.rb', line 43

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

Instance Method Details

#clear ⇒ void Also known as: clear!

This method returns an undefined value.

Removes the current tunnel. The tunnel must be inactive.

Examples:

bob.clear

Raises:

  • (Error) —

    if no tunnel has been selected

  • (Error) —

    if the tunnel is still active

Since:

  • 0.1.4



433
434
435
436
437
 
# File 'lib/i2p/bob/client.rb', line 433

def clear
  send_command(:clear)
  read_response # "cleared"
  self
end

#connect ⇒ void Also known as: reconnect

This method returns an undefined value.

Establishes a connection to the BOB bridge.

If called after the connection has already been established, disconnects and then reconnects to the bridge.

Examples:

bob.connect

Since:

  • 0.1.4



140
141
142
143
144
145
146
147
 
# File 'lib/i2p/bob/client.rb', line 140

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

#connected? ⇒ Boolean

Returns ‘true` if a connection to the BOB bridge has been established and is active.

Examples:

bob.connected?                       #=> true
bob.disconnect
bob.connected?                       #=> false

Returns:

  • (Boolean)

Since:

  • 0.1.4



126
127
128
 
# File 'lib/i2p/bob/client.rb', line 126

def connected?
  !!@socket
end

#disconnect ⇒ void Also known as: close

This method returns an undefined value.

Closes the connection to the BOB bridge.

If called after the connection has already been closed, does nothing.

Examples:

bob.disconnect

Since:

  • 0.1.4



159
160
161
162
163
 
# File 'lib/i2p/bob/client.rb', line 159

def disconnect
  @socket.close if @socket && !@socket.closed?
  @socket = nil
  self
end

#getdest ⇒ Destination

Returns the destination for the current tunnel.

Examples:

bob.getdest

Returns:

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



244
245
246
247
 
# File 'lib/i2p/bob/client.rb', line 244

def getdest
  send_command(:getdest)
  Destination.parse(read_response)
end

#getkeys ⇒ KeyPair

Returns the key pair for the current tunnel.

Examples:

bob.getkeys

Returns:

Raises:

  • (Error) —

    if no public key has been set

Since:

  • 0.1.4



257
258
259
260
 
# File 'lib/i2p/bob/client.rb', line 257

def getkeys
  send_command(:getkeys)
  KeyPair.parse(read_response)
end

#getnick(nickname) ⇒ void

This method returns an undefined value.

Selects an existing tunnel with the given nickname.

Examples:

bob.getnick(:foo)

Parameters:

  • nickname (String, #to_s)

Since:

  • 0.1.4



218
219
220
221
222
 
# File 'lib/i2p/bob/client.rb', line 218

def getnick(nickname)
  send_command(:getnick, @options[:nickname] = nickname.to_s)
  read_response # "Nickname set to #{nickname}"
  self
end

#inhost(host) ⇒ void Also known as: inhost=

This method returns an undefined value.

Sets the inbound host name or IP address that the current tunnel listens on.

The default for new tunnels is ‘inhost(“localhost”)`.

Examples:

bob.inhost('127.0.0.1')

Parameters:

  • host (String, #to_s)

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



290
291
292
293
294
 
# File 'lib/i2p/bob/client.rb', line 290

def inhost(host)
  send_command(:inhost, @options[:inhost] = host.to_s)
  read_response # "inhost set"
  self
end

#inport(port) ⇒ void Also known as: inport=

This method returns an undefined value.

Sets the inbound port number that the current tunnel listens on.

Examples:

bob.inport(37337)

Parameters:

  • port (Integer, #to_i)

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



306
307
308
309
310
 
# File 'lib/i2p/bob/client.rb', line 306

def inport(port)
  send_command(:inport, @options[:inport] = port.to_i)
  read_response # "inbound port set"
  self
end

#newkeys ⇒ Destination

Generates a new keypair for the current tunnel.

Examples:

bob.newkeys

Returns:

Since:

  • 0.1.4



231
232
233
234
 
# File 'lib/i2p/bob/client.rb', line 231

def newkeys
  send_command(:newkeys)
  Destination.parse(read_response)
end

#option(key, value) ⇒ void

This method returns an undefined value.

Sets an I2P Control Protocol (I2CP) option for the current tunnel.

Examples:

bob.option(key, value)

Parameters:

  • key (String, #to_s)
  • value (String, #to_s)

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



386
387
388
389
390
 
# File 'lib/i2p/bob/client.rb', line 386

def option(key, value)
  send_command(:option, [key, value].join('='))
  read_response # "#{key} set to #{value}"
  self
end

#outhost(host) ⇒ void Also known as: outhost=

This method returns an undefined value.

Sets the outbound host name or IP address that the current tunnel connects to.

The default for new tunnels is ‘outhost(“localhost”)`.

Examples:

bob.outhost('127.0.0.1')

Parameters:

  • host (String, #to_s)

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



325
326
327
328
329
 
# File 'lib/i2p/bob/client.rb', line 325

def outhost(host)
  send_command(:outhost, @options[:outhost] = host.to_s)
  read_response # "outhost set"
  self
end

#outport(port) ⇒ void Also known as: outport=

This method returns an undefined value.

Sets the outbound port number that the current tunnel connects to.

Examples:

bob.outport(80)

Parameters:

  • port (Integer, #to_i)

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



341
342
343
344
345
 
# File 'lib/i2p/bob/client.rb', line 341

def outport(port)
  send_command(:outport, @options[:output] = port.to_i)
  read_response # "outbound port set"
  self
end

#quiet(value = true) ⇒ void Also known as: quiet=

This method returns an undefined value.

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)`.

Examples:

Enabling quiet mode

bob.quiet
bob.quiet(true)
bob.quiet = true

Disabling quiet mode

bob.quiet(false)
bob.quiet = false

Parameters:

  • value (Boolean) (defaults to: true)

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



369
370
371
372
373
 
# File 'lib/i2p/bob/client.rb', line 369

def quiet(value = true)
  send_command(:quiet, @options[:quiet] = value.to_s)
  read_response # "Quiet set"
  self
end

#quit ⇒ void Also known as: quit!

This method returns an undefined value.

Closes the connection to the BOB bridge cleanly.

Examples:

bob.quit

Since:

  • 0.1.4



173
174
175
176
177
 
# File 'lib/i2p/bob/client.rb', line 173

def quit
  send_command(:quit)
  read_response # "Bye!"
  disconnect
end

#setkeys(key_pair) ⇒ void Also known as: keys=

This method returns an undefined value.

Sets the key pair for the current tunnel.

Examples:

bob.setkeys(I2P::KeyPair.parse("..."))

Parameters:

Raises:

  • (Error) —

    if no tunnel has been selected

Since:

  • 0.1.4



271
272
273
274
275
 
# File 'lib/i2p/bob/client.rb', line 271

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

#setnick(nickname) ⇒ void Also known as: nickname=

This method returns an undefined value.

Creates a new tunnel with the given nickname.

Examples:

bob.setnick(:foo)

Parameters:

  • nickname (String, #to_s)

Since:

  • 0.1.4



203
204
205
206
207
 
# File 'lib/i2p/bob/client.rb', line 203

def setnick(nickname)
  send_command(:setnick, @options[:nickname] = nickname.to_s)
  read_response # "Nickname set to #{nickname}"
  self
end

#start ⇒ void Also known as: start!

This method returns an undefined value.

Starts and activates the current tunnel.

Examples:

bob.start

Raises:

  • (Error) —

    if the tunnel settings are incomplete

  • (Error) —

    if the tunnel is already active

Since:

  • 0.1.4



401
402
403
404
405
 
# File 'lib/i2p/bob/client.rb', line 401

def start
  send_command(:start)
  read_response # "tunnel starting"
  self
end

#stop ⇒ void Also known as: stop!

This method returns an undefined value.

Stops and inactivates the current tunnel.

Examples:

bob.stop

Raises:

  • (Error) —

    if no tunnel has been selected

  • (Error) —

    if the tunnel is already inactive

Since:

  • 0.1.4



417
418
419
420
421
 
# File 'lib/i2p/bob/client.rb', line 417

def stop
  send_command(:stop)
  read_response # "tunnel stopping"
  self
end

#verify(data) ⇒ Boolean

Verifies a Base64-formatted key pair or destination, returning ‘true` for valid input.

Examples:

bob.verify("foobar")                 #=> false
bob.verify(I2P::Hosts["forum.i2p"])  #=> true

Parameters:

  • data (#to_base64, #to_s)

Returns:

  • (Boolean)

Since:

  • 0.1.4



190
191
192
193
 
# File 'lib/i2p/bob/client.rb', line 190

def verify(data)
  send_command(:verify, data.respond_to?(:to_base64) ? data.to_base64 : data.to_s)
  read_response rescue false
end