natpmp 0.8 → 0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b79a17201396b0daf760a7454fd50ca223fdd6ab
-  data.tar.gz: db52b1791207f0330e968f380afdab5238160327
+  metadata.gz: 504f5dbfbf0b924f579d4cc21c3329c415bb0d66
+  data.tar.gz: 2d29eb61c29f70a0876c5592781518c3514064e3
 SHA512:
-  metadata.gz: d287cc858eaecd16279e928acd2a63bc74c9c1f207494ec81d8480c25a74f86bba9ba37bc362da4a64d018fce9ee14d0a4961557d2837884f28abb333a24572d
-  data.tar.gz: 7436eb03437d9a262c7a97df52d14a45dd1c0061ded6a6a9ba1566a7dee0fad5cedb107b72bf85a85606100bd9b0fa84354011f6202359160c7c835a9048dcad
+  metadata.gz: 933f2b1277663de3fe5ac5c7110c53ab4ae65161ff1459ad1a1fe4e684c109719540c537647a822e2ffb11de01bde089d49ccadba8f165caefa602a29153e5f2
+  data.tar.gz: d776e773dc7c29c404d896a040120efa19634ba0e88b8d8250e57c94d0f1cfa825539226c1d5ef054fc406751d9f23ee1dbc038e50a67b567b0443ce94cf99be

data/README.md

@@ -0,0 +1,52 @@
+# Ruby Gem for NAT-PMP
+
+This is a client implementation of [NAT-PMP](http://tools.ietf.org/html/rfc6886)
+
+For a server implementation suitable for Linux see [Stallone](https://github.com/tedjp/stallone)
+
+Upon request NAT-PMP can open either a UDP or TCP port on the gateway and bidirectionally relay traffic to a specific external server.
+
+## Usage
+The GEM includes a command-line utility as well as Ruby classes and can be used in several ways
+
+### To open a mapping from the command line
+To open a mapping on specific ports use:
+
+    natpmp -p 1234
+
+This command will hold the port open for the requested time, whereafter it _may_ be closed. To extend the mapping simply re-open it using the same port number.
+
+### To run a command with a mapping
+To run a command with specific port mappings:
+
+    natpmp -p 1234 'echo using the mapping && sleep 5'
+
+The mapping will be held open until the command completes. The command string may contain the tokens %H, %P, %h and %p which will be substituted for the remote (uppercase) and local (lowercase) host (h) and ports (p). The ports can be automatically assigned by the command.
+
+### Example Ruby Code
+To open a port and run code using it:
+    
+    require 'natpmp'
+    NATPMP.map 633, 13033, 10, :tcp do |map|
+      ... # the mapping will be renewed until this exits
+    end
+
+### Command Line Utility
+The command line utility has the following options:
+
+    usage: natpmp [options] [command]
+    Open a port on a NAT-PMP gateway. Options:
+        -t, --type TYPE                  Type: tcp, udp (default: tcp)
+        -p, --port PORT                  Private port (default: auto)
+            --ttl TIME                   TTL if no command (default 7200 sec)
+        -P, --public PUBPORT             External port (default: auto)
+        -v, --verbose                    Verbose
+            --version                    Version
+    In the command string the following substitutions will be made:
+      %p the local port
+      %h the local IP address
+      %P the gateway port
+      %H the gateway IP address
+    (Use %% to avoid this)
+    The mapping will be closed on completion of the command
+        -?, --help                       Display this screen

data/bin/natpmp

@@ -5,9 +5,6 @@ require 'natpmp/version'
 require 'ostruct'
 require 'optparse'
 
-# TODO Extend the mapping if the command takes longer
-# than the timeout.
-
 types = [:tcp, :udp]
 
 opts = OpenStruct.new(port: nil, type: :tcp, verbose: false, public: 0, ttl: 7200)
@@ -69,7 +66,7 @@ end
 
 if ARGV.size > 0
   command = ARGV.join(' ')
-  NATPMP.map opts.port, opts.public, opts.ttl, opts.type do |map|
+  NATPMP.map opts.port, opts.public, nil, opts.type do |map|
     command.gsub! /(?<!%)%p/, map.priv.to_s
     command.gsub! /(?<!%)%h/, opts.localhost.to_s
     command.gsub! /(?<!%)%P/, map.mapped.to_s
@@ -79,7 +76,6 @@ if ARGV.size > 0
     system command
   end
 else
-  puts "noarg"
   map = NATPMP.map opts.port, opts.public, opts.ttl, opts.type
 end
 

data/lib/natpmp.rb

@@ -41,7 +41,7 @@ class NATPMP
     end
   end
 
-  def self.verbose flag = true
+  def self.verbose flag
     @verbose = flag
   end
 
@@ -93,8 +93,8 @@ class NATPMP
     @priv = priv
     @pub = pub
     @maxlife = maxlife
-    raise "Time must be >= 0" if maxlife < 0
     @type = type
+    @renew = nil # Renewal thread
 
     # These are filled in when a request is made
     #
@@ -104,16 +104,18 @@ class NATPMP
 
   # See section 3.3
   def request!
-    rsp = NATPMP.send [0, OPCODE[@type], 0, @priv, @pub, @maxlife].pack("CCnnnN")
+    rsp = NATPMP.send [0, OPCODE[@type], 0, @priv, @pub, @maxlife||DEFAULT_LIFETIME].pack("CCnnnN")
     (sssoe, priv, @mapped, @life) = rsp.unpack("x4NnnN")
     raise "Port mismatch: requested #{@priv} received #{priv}" if @priv != priv
-    STDERR.puts "Mapped #{inspect}" if NATPMP.verbose
+    STDERR.puts "Mapped (at #{sssoe}) #{inspect}" if NATPMP.verbose?
+    schedule_renew! if @maxlife.nil?
   end
 
   # See section 3.4
   def revoke!
+    @renew.exit if @renew
     rsp = NATPMP.send [0, OPCODE[@type], 0, @priv, 0, 0].pack("CCnnnN")
-    STDERR.puts "Revoked #{inspect}" if NATPMP.verbose
+    STDERR.puts "Revoked #{inspect}" if NATPMP.verbose?
   end
 
   def inspect
@@ -122,7 +124,7 @@ class NATPMP
 
   def self.map priv, pub, maxlife = DEFAULT_LIFETIME, type = :tcp, &block
 
-    map = NATPMP.new(priv, pub, maxlife, type)
+    map = NATPMP.new(priv, pub, block_given? ? nil: maxlife, type)
     map.request!
     if block_given?
       begin
@@ -135,4 +137,22 @@ class NATPMP
     return map
 
   end
+
+  private
+
+  # As per section 3.3 re-issue the request using the actual mapped port
+  def schedule_renew!
+    Thread.abort_on_exception = true
+    # As per section 3.3 re-issue the request using the actual mapped port
+    @renew = Thread.new @life do |life|
+      wait_time = life/2
+      STDERR.puts "Renewal in #{wait_time} seconds" if NATPMP.verbose?
+      sleep wait_time
+      rsp = NATPMP.send [0, OPCODE[@type], 0, @priv, @mapped, @life].pack("CCnnnN")
+      (sssoe, priv, @mapped, @life) = rsp.unpack("x4NnnN")
+      STDERR.puts "Renewed (at #{sssoe}) #{inspect}" if NATPMP.verbose?
+      schedule_renew!
+    end
+  end
+
 end

data/lib/natpmp/version.rb

@@ -1,3 +1,3 @@
 class NATPMP
-  VERSION='0.8'
+  VERSION='0.9'
 end

data/test/test_natpmp.rb

@@ -1,9 +1,26 @@
-# Simple smoke test
-# To be improved!
+# Simple tests
+# Only work if the network gateway has NAT-PMP
+# TODO Mock out the gateway object
 #
-require 'natpmp.rb'
+require 'test/unit'
+require 'natpmp'
 
-NATPMP.map 633, 13033, 30, :tcp do |map|
-  puts "Executing sleep 10 with #{map.inspect}"
-  sleep 10
+class TestNATPMP < Test::Unit::TestCase
+  def test_gw
+    gw = NATPMP.GW
+    assert_match(/^(\d{1,3}\.){3}\d{1,3}$/, gw, "Return IPv4 address")
+  end
+  def test_basic
+    map = NATPMP.map 633, 13033, 30, :tcp
+    assert_equal(633, map.priv)
+    assert_equal(13033, map.pub)
+    assert_equal(30, map.life)
+    assert_equal(:tcp, map.type)
+  end
+  def test_block
+    m = NATPMP.map 633, 13033, 10, :tcp do |map|
+      assert_equal(NATPMP::DEFAULT_LIFETIME, map.life)
+    end
+    assert_nil(m)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: natpmp
 version: !ruby/object:Gem::Version
-  version: '0.8'
+  version: '0.9'
 platform: ruby
 authors:
 - Nick Townsend
@@ -18,6 +18,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/natpmp.rb
 - bin/natpmp
 - lib/natpmp/version.rb