net-natpmp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9450b999925ebdbe97f8cf23f24bbdc5dc5177bc29a4782a88b667ab5bbeeb06
+  data.tar.gz: b0afc58710a87288c518878a7079583651c0d10f3eba5ac1b3c17a7b9b2b91e9
+SHA512:
+  metadata.gz: d5aac53925fc713efbebe52bfc94f3f2b8ea632e7fe407e828c02e367aa6b9509a519b6a0117b66e0c75c6e234085933464bd8a5accd17f5bab728da12213dc4
+  data.tar.gz: cd672c6ca071227b65d9aac5e74f3f7db5dd3cf0d4ddb2d2a879fb9f9b85d499bba22e67616f62c63ed265486ee99d5b7b1138470a2527bb0cfd33ee02e80306

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Octavian Vaideanu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

data/README.md

@@ -0,0 +1,6 @@
+# net-natpmp
+NATPMP client implementation in ruby
+
+TODO: Write Readme file
+TODO: Maybe add tests
+TODO: Give the option to use the default gateway instead of requiring it as an argument

data/lib/net/natpmp/client.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Net
+  module NATPMP
+    # Client class
+    class Client
+      include Constants
+
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      # Replies with the external address of the gateway
+      def external_address
+        ExternalAddressRequest.req(@config)
+      end
+
+      # Maps a port on the gateway
+      def map_port(
+        proto: DEFAULT_PROTO,
+        inside_port: DEFAULT_INSIDE_PORT,
+        outside_port: DEFAULT_OUTSIDE_PORT,
+        lifetime: DEFAULT_LIFETIME
+      )
+        MappingRequest.req(
+          @config,
+          proto: proto,
+          inside_port: inside_port,
+          outside_port: outside_port,
+          lifetime: lifetime
+        )
+      end
+
+      # Destroys a port mapping on the gateway
+      def destroy_mapping(port: 0, proto: DEFAULT_PROTO)
+        MappingRequest.req(@config, proto: proto, inside_port: port, outside_port: 0, lifetime: 0)
+      end
+    end
+  end
+end

data/lib/net/natpmp/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Net
+  module NATPMP
+    # Provides all necessary configuration with some defaults
+    class Config
+      NATPMP_PORT = 5351
+      BIND_ADDRESS = '0.0.0.0'
+      BIND_PORT = 5350
+
+      attr_reader :bind_address, :bind_port, :gw, :port
+
+      def initialize(
+        gw:,
+        port: NATPMP_PORT,
+        bind_address: BIND_ADDRESS,
+        bind_port: BIND_PORT
+      )
+
+        @bind_address = IPAddr.new(bind_address)
+        @bind_port = bind_port
+        @gw = IPAddr.new(gw)
+        @port = port
+      rescue IPAddr::InvalidAddressError
+        raise InvalidParameter, 'Value must be a valid IP Address'
+      end
+    end
+  end
+end

data/lib/net/natpmp/constants.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Net
+  module NATPMP
+    module Constants
+      VERSION = 0
+
+      PROTO_CODES = {
+        udp: :map_udp,
+        tcp: :map_tcp
+      }.freeze
+
+      OP_CODES = {
+        address: 0,
+        map_udp: 1,
+        map_tcp: 2
+      }.freeze
+
+      # 0 - Success
+      # 1 - Unsupported Version
+      # 2 - Not Authorized/Refused
+      #     (e.g., box supports mapping, but user has turned feature off)
+      # 3 - Network Failure
+      #     (e.g., NAT box itself has not obtained a DHCP lease)
+      # 4 - Out of resources
+      #     (NAT box cannot create any more mappings at this time)
+      # 5 - Unsupported opcode
+      RESULT_CODES = {
+        success: 0,
+        unsupported_version: 1,
+        not_authorized: 2,
+        network_failure: 3,
+        out_of_resources: 4,
+        unsupported_opcode: 5
+      }.freeze
+
+      RESULT_CODES_DESC = {
+        1 => 'Unsupported Version',
+        2 => 'Not Authorized/Refused',
+        3 => 'Network Failure',
+        4 => 'Out of resources',
+        5 => 'Unsupported opcode'
+      }.freeze
+
+      # This is the initial delay before doubling it
+      BASE_DELAY = 0.25
+      MAX_WAIT = 60
+
+      DEFAULT_INSIDE_PORT = 0
+      DEFAULT_OUTSIDE_PORT = 0
+      DEFAULT_LIFETIME = 7200
+      DEFAULT_PROTO = :udp
+    end
+  end
+end

data/lib/net/natpmp/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Net
+  module NATPMP
+    # General exception
+    class Exception < ::RuntimeError; end
+
+    class InvalidParameter < Exception; end
+
+    # Timeout exception
+    class TimeoutException < Exception
+      def initialize(msg = 'Request timed out')
+        super
+      end
+    end
+
+    class InvalidVersion < Exception; end
+
+    class InvalidReply < Exception; end
+
+    # Exception should be thrown when the request fails
+    class RequestFailed < Exception
+      include Constants
+
+      def initialize(opts = {})
+        msg = opts[:msg] || 'Failed to send the request'
+
+        if (@result_code = opts[:result_code])
+          msg = "#{msg}. Server replied: #{RESULT_CODES_DESC[@result_code]}(#{@result_code})"
+        end
+
+        super(msg)
+      end
+    end
+
+    class ConnectionRefused < Exception; end
+  end
+end

data/lib/net/natpmp/requests.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'ipaddr'
+
+module Net
+  module NATPMP
+    # Main request class
+    class Request
+      include Constants
+
+      attr_reader :socket, :config
+
+      def initialize(config)
+        @config = config
+
+        @socket = UDPSocket.new
+        @socket.bind(config.bind_address.to_s, config.bind_port)
+        @socket.connect(config.gw.to_s, config.port)
+      end
+
+      def self.req(config, _opts = {})
+        new(config)
+      end
+
+      # Send a message to the NAT-PMP server. Takes a message and an optional response size
+      def send(msg, expected_response_size = 16)
+        sent_op = msg.unpack1('xC') # To verify the response
+        size_sent = @socket.send(msg, 0)
+
+        raise RequestFailed unless size_sent == msg.size
+
+        delay = Constants::BASE_DELAY
+        attempts = 1
+
+        begin
+          sleep delay
+          reply, = @socket.recvfrom_nonblock(expected_response_size)
+
+          check_reply(reply, sent_op)
+
+          reply
+        rescue IO::WaitReadable
+          if delay < MAX_WAIT
+            delay *= 2
+            puts "Timeout, retrying after #{delay} seconds"
+            attempts += 1
+            retry
+          end
+
+          raise TimeoutException, "Timeout after #{attempts} attempts"
+        rescue Errno::ECONNREFUSED
+          raise ConnectionRefused, 'Connection refused'
+        end
+      ensure
+        sleep 0.25 # Sleep for a bit to make sure the socket is not closed too soon
+        @socket.close # Close the socket because we don't need it anymore
+      end
+
+      def check_reply(reply, sent_op)
+        # Check the first 4 bytes only (the rest are variable)
+        version, opcode, result = reply.unpack('CCn')
+
+        # Check the version in the reply
+        raise InvalidVersion, "Invalid version #{version}" unless version == VERSION
+
+        # Check the operation code in the reply. Always (128 + sent opcode)
+        expected_opcode = 128 + sent_op
+        if opcode != expected_opcode
+          raise InvalidReply,
+                "Invalid reply opcode. Was expecting #{expected_opcode}, got: #{opcode}"
+        end
+
+        # Check the result code in the reply
+        raise RequestFailed, result_code: result unless result == RESULT_CODES[:success]
+      end
+    end
+
+    # Request class specific to External address
+    class ExternalAddressRequest < Request
+      def self.req(config)
+        instance = super(config)
+        msg = [VERSION, OP_CODES[:address]].pack('CC')
+
+        ExternalAddressResponse.new(instance.send(msg, 12))
+      end
+    end
+
+    # Represents a port mapping request
+    class MappingRequest < Request
+      def self.req(config, proto:, inside_port:, outside_port:, lifetime:)
+        # TODO: Ensure proto is either :udp or :tcp
+
+        instance = super(config)
+        msg = [
+          VERSION, OP_CODES[PROTO_CODES[proto]], 0,
+          inside_port, outside_port,
+          lifetime
+        ].pack('CCnnnN')
+
+        MappingResponse.new(instance.send(msg, 16), proto: proto)
+      end
+    end
+  end
+end

data/lib/net/natpmp/responses.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Net
+  module NATPMP
+    # Response class
+    class Response
+      attr_reader :raw_response
+
+      def initialize(response, _ = {})
+        @raw_response = response
+      end
+    end
+
+    # Response for the external address request
+    class ExternalAddressResponse < Response
+      attr_reader :ip_int
+
+      def initialize(response)
+        super
+        @ip_int = response.unpack1('@8N')
+      end
+
+      def address
+        IPAddr.new(ip_int, Socket::AF_INET)
+      end
+
+      def to_s
+        address.to_s
+      end
+
+      def inspect
+        "External address: #{address}"
+      end
+    end
+
+    # Response for the mapping request
+    class MappingResponse < Response
+      attr_reader :inside_port, :outside_port, :lifetime, :proto
+
+      def initialize(response, proto:)
+        super
+
+        @proto = proto
+        @inside_port, @outside_port, @lifetime = response.unpack('@8nnN')
+      end
+
+      def inspect
+        "Port mapping: #{@outside_port} -> #{@proto}:#{@inside_port} (lifetime: #{@lifetime})"
+      end
+    end
+  end
+end

data/lib/net/natpmp.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'natpmp/constants'
+require_relative 'natpmp/config'
+require_relative 'natpmp/client'
+require_relative 'natpmp/errors'
+require_relative 'natpmp/requests'
+require_relative 'natpmp/responses'
+
+module Net
+  # Main class
+  module NATPMP
+    # Instantiate class with default params.
+    # Takes a config instance or any other params.
+    # :gw is mandatory if config instance not provided
+    def self.client(config)
+      return Client.new(config) if config.is_a?(Config)
+
+      unless config[:gw]
+        raise Net::NATPMP::Exception,
+              'Gateway is missing. Call with: Net::NATPMP.client(gw: "x.x.x.x")'
+      end
+
+      Client.new(Config.new(**config))
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: net-natpmp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Octavian Vaideanu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-07-26 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      A NAT-PMP client for Ruby.
+      This gem allows you to interact with NAT-PMP enabled routers to map ports and get the external IP address.
+email: octav@devroot.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/net/natpmp.rb
+- lib/net/natpmp/client.rb
+- lib/net/natpmp/config.rb
+- lib/net/natpmp/constants.rb
+- lib/net/natpmp/errors.rb
+- lib/net/natpmp/requests.rb
+- lib/net/natpmp/responses.rb
+homepage: https://rubygems.org/gems/net-natpmp
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: NAT-PMP client for Ruby
+test_files: []