Class: I2P::BOB::Tunnel

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

Overview

**I2P Basic Open Bridge (BOB) tunnel manager.**

Examples:

Creating and controlling a new tunnel

I2P::BOB::Tunnel.new(...) do |tunnel|
  tunnel.start
  sleep 0.1 until tunnel.running?
  # ... code that uses the tunnel goes here ...
  tunnel.stop
end

Starting a new inbound I2P tunnel in one go

I2P::BOB::Tunnel.start({
  :nickname => :inproxy,
  :inhost   => "127.0.0.1"
  :inport   => 12345, # unused port
})

Starting a new outbound I2P tunnel in one go

I2P::BOB::Tunnel.start({
  :nickname => :myssh,
  :outhost  => "127.0.0.1",
  :outport  => 22,    # SSH port
})

Starting an existing tunnel

I2P::BOB::Tunnel.start(:myssh)

Obtaining the I2P destination for a tunnel

tunnel = I2P::BOB::Tunnel.start(:mytunnel)
tunnel.destination  #=> #<I2P::Destination:...>

Stopping an existing tunnel

I2P::BOB::Tunnel.stop(:myssh)

See Also:

Since:

  • 0.1.4

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Tunnel #initialize(nickname) ⇒ Tunnel

Initializes a new tunnel instance.

Overloads:

  • #initialize(options = {}) ⇒ Tunnel

    Parameters:

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

    Options Hash (options):

    • :nickname (String, #to_s) — default: Time.now.to_i
    • :keys (KeyPair, #to_s) — default: nil
    • :quiet (Boolean) — default: false
    • :inhost (String, #to_s) — default: "localhost"
    • :inport (Integer, #to_i) — default: nil
    • :outhost (String, #to_s) — default: "localhost"
    • :outport (Integer, #to_i) — default: nil
  • #initialize(nickname) ⇒ Tunnel

    Parameters:

    • nickname (String, #to_s)

Since:

  • 0.1.4



93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/i2p/bob/tunnel.rb', line 93

def initialize(options = {})
  case options
    when Hash
      # Create a new tunnel
      @nickname = options[:nickname] || Time.now.to_i.to_s
      @debug    = options[:debug]
      setup(options)
    else
      # Access an existing tunnel
      @nickname = options.to_s
      Client.open { |client| client.getnick(@nickname) }
  end
end

Instance Attribute Details

#destination ⇒ Destination (readonly)

Returns the I2P destination for this tunnel.

Returns:

See Also:

Since:

  • 0.1.4



119
120
121
 
# File 'lib/i2p/bob/tunnel.rb', line 119

def destination
  @destination
end

#inhost ⇒ String (readonly)

Returns the inbound host name or IP address for this tunnel.

Returns:

  • (String)

See Also:

Since:

  • 0.1.4



147
148
149
 
# File 'lib/i2p/bob/tunnel.rb', line 147

def inhost
  @inhost
end

#inport ⇒ Integer (readonly)

Returns the inbound port number for this tunnel.

Returns:

  • (Integer)

See Also:

Since:

  • 0.1.4



159
160
161
 
# File 'lib/i2p/bob/tunnel.rb', line 159

def inport
  @inport
end

#keys ⇒ KeyPair (readonly)

Returns the I2P key pair for this tunnel.

Returns:

See Also:

Since:

  • 0.1.4



129
130
131
 
# File 'lib/i2p/bob/tunnel.rb', line 129

def keys
  @keys
end

#nickname ⇒ String (readonly)

Returns the nickname for this tunnel.

Returns:

  • (String)

See Also:

Since:

  • 0.1.4



112
113
114
 
# File 'lib/i2p/bob/tunnel.rb', line 112

def nickname
  @nickname
end

#outhost ⇒ String (readonly)

Returns the outbound host name or IP address for this tunnel.

Returns:

  • (String)

See Also:

Since:

  • 0.1.4



179
180
181
 
# File 'lib/i2p/bob/tunnel.rb', line 179

def outhost
  @outhost
end

#outport ⇒ Integer (readonly)

Returns the outbound port number for this tunnel.

Returns:

  • (Integer)

See Also:

Since:

  • 0.1.4



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

def outport
  @outport
end

Class Method Details

.start(options = {}, &block) ⇒ Tunnel

Starts up a new tunnel.

Parameters:

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

Options Hash (options):

  • :nickname (String, #to_s) — default: Time.now.to_i
  • :keys (KeyPair, #to_s) — default: nil
  • :quiet (Boolean) — default: false
  • :inhost (String, #to_s) — default: "localhost"
  • :inport (Integer, #to_i) — default: nil
  • :outhost (String, #to_s) — default: "localhost"
  • :outport (Integer, #to_i) — default: nil

Returns:

Since:

  • 0.1.4



53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/i2p/bob/tunnel.rb', line 53

def self.start(options = {}, &block)
  tunnel = self.new(options).start

  if block_given?
    begin
      result = block.call(tunnel)
    ensure
      tunnel.stop
    end
    result
  else
    tunnel
  end
end

.stop(nickname) ⇒ void

This method returns an undefined value.

Shuts down an existing tunnel of the given ‘nickname`.

Parameters:

  • (String, #to_s)

Since:

  • 0.1.4



73
74
75
 
# File 'lib/i2p/bob/tunnel.rb', line 73

def self.stop(nickname)
  self.new(nickname).stop
end

Instance Method Details

#client {|client| ... } ⇒ Client

Returns a Client instance for accessing low-level information about this tunnel.

Yields:

Yield Parameters:

Returns:

Since:

  • 0.1.4



299
300
301
 
# File 'lib/i2p/bob/tunnel.rb', line 299

def client(&block)
  Client.open(:nickname => nickname, :debug => @debug, &block)
end

#inbound? ⇒ Boolean

Returns ‘true` if this is an inbound tunnel.

Returns:

  • (Boolean)

Since:

  • 0.1.4



138
139
140
 
# File 'lib/i2p/bob/tunnel.rb', line 138

def inbound?
  !!inport
end

#outbound? ⇒ Boolean

Returns ‘true` if this is an outbound tunnel.

Returns:

  • (Boolean)

Since:

  • 0.1.4



170
171
172
 
# File 'lib/i2p/bob/tunnel.rb', line 170

def outbound?
  !!outport
end

#quiet? ⇒ Boolean

Returns ‘true` if quiet mode is enabled for this tunnel.

This only applies to outbound tunnels and has no effect on inbound tunnels.

Returns:

  • (Boolean)

See Also:

Since:

  • 0.1.4



206
207
208
209
210
 
# File 'lib/i2p/bob/tunnel.rb', line 206

def quiet?
  @quiet ||= begin
    nil # TODO
  end
end

#running? ⇒ Boolean Also known as: active?

Returns ‘true` if this tunnel is currently active.

Returns:

  • (Boolean)

Since:

  • 0.1.4



243
244
245
 
# File 'lib/i2p/bob/tunnel.rb', line 243

def running?
  true # FIXME
end

#setup(options = {}) ⇒ void Also known as: setup!

This method returns an undefined value.

Registers the given tunnel ‘options` with the BOB bridge.

Parameters:

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

Since:

  • 0.1.4



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/i2p/bob/tunnel.rb', line 217

def setup(options = {})
  client do |client|
    if options[:keys]
      client.setkeys(options[:keys])
    else
      begin
        client.getkeys
      rescue Error => e
        client.newkeys
      end
    end

    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]
  end
  self
end

#socket ⇒ Object

Since:

  • 0.1.4



288
289
290
 
# File 'lib/i2p/bob/tunnel.rb', line 288

def socket
  client.socket
end

#start ⇒ void Also known as: start!

This method returns an undefined value.

Starts up this tunnel.

See Also:

Since:

  • 0.1.4



253
254
255
256
 
# File 'lib/i2p/bob/tunnel.rb', line 253

def start
  client { start }
  self
end

#starting? ⇒ Boolean

Returns ‘true` if this tunnel is currently in the process of starting up.

Returns:

  • (Boolean)

Since:

  • 0.1.4



264
265
266
 
# File 'lib/i2p/bob/tunnel.rb', line 264

def starting?
  # TODO
end

#stop ⇒ void Also known as: stop!

This method returns an undefined value.

Shuts down this tunnel.

See Also:

Since:

  • 0.1.4



273
274
275
276
 
# File 'lib/i2p/bob/tunnel.rb', line 273

def stop
  client { stop }
  self
end

#stopping? ⇒ Boolean

Returns ‘true` if this tunnel is currently in the process of shutting down.

Returns:

  • (Boolean)

Since:

  • 0.1.4



284
285
286
 
# File 'lib/i2p/bob/tunnel.rb', line 284

def stopping?
  # TODO
end