socketry 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c144331b5b09954959008e255335d5ac43c70be3
-  data.tar.gz: 704cb38c89f0cc0779aaeba5859877f189f5664c
+  metadata.gz: ca5c2f89cca095c9a9512b02c3dff7d7af615af2
+  data.tar.gz: 5d4ccc55cb34dcea0bb63986882c52195a1dabc3
 SHA512:
-  metadata.gz: f49d7c5ee328c0c6b7f6366aca43d147a56045b1b1f3dca05219caef2216e791454585e512a7195f61dc1fb767230a2dde82f5130e1a174474d26b6ad0fbbabb
-  data.tar.gz: 7147ec4e25e1d4af36d27452be851adbec957ce65747f95ce873e91936ec962b3576d62b0f171304079dad998030289874a55267682c7842debb7fe7d7ac0413
+  metadata.gz: c7cfa8860c9e4aa4f0685d8d707f433d1d98ecdf56bad86146d8347b5480492ad51ac03e1d18035899e1ac2457f64b77f0822b91a7ca8e24af85a0262ffe1a27
+  data.tar.gz: b63f66204999a96fe018d168d9448de66d1ad97b1793c145af5b41cd4a04e806fce9cf1d84901d99872ffbf0ec9cbbd0cafded0777db4ca14e9a5ea904fff3d9

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.3.3

data/.travis.yml

@@ -5,8 +5,8 @@ bundler_args: --without development doc
 
 rvm:
   - 2.2
-  - 2.3.1
-  - jruby-9.0.5.0
+  - 2.3.3
+  - jruby-9.1.6.0
 
 matrix:
   fast_finish: true

data/CHANGES.md

@@ -1,3 +1,10 @@
+## 0.4.0 (2016-11-25)
+
+* Specs and bugfixes for SSL sockets
+* Specs and bugfixes for UDP sockets
+* Add Socketry::UDP::Datagram class
+* Add Socketry::AddressInUseError exception
+
 ## 0.3.0 (2016-09-24)
 
 * Implement Socketry::TCP::Socket#read and #write

data/README.md

@@ -11,13 +11,9 @@
 [license-image]: https://img.shields.io/badge/license-MIT-blue.svg
 [license-link]: https://github.com/socketry/socketry/blob/master/LICENSE.txt
 
-High-level wrappers for Ruby sockets with advanced thread-safe timeout support.
+High-level Ruby socket library with support for TCP, UDP, and SSL sockets.
 
-**Does not require Celluloid!** Socketry provides sockets with thread-safe
-timeout support that can be used with any multithreaded Ruby app. That said,
-Socketry can also be used to provide asynchronous I/O with [Celluloid::IO].
-
-[Celluloid::IO]: https://github.com/celluloid/celluloid-io
+Implements thread-safe timeouts using asynchronous I/O and high-precision monotonic timers.
 
 ## Motivation
 

data/lib/socketry.rb

@@ -21,4 +21,5 @@ require "socketry/tcp/server"
 require "socketry/tcp/socket"
 require "socketry/ssl/server"
 require "socketry/ssl/socket"
+require "socketry/udp/datagram"
 require "socketry/udp/socket"

data/lib/socketry/exceptions.rb

@@ -10,6 +10,9 @@ module Socketry
   # Invalid address
   AddressError = Class.new(Socketry::Error)
 
+  # Address is already in use
+  AddressInUseError = Class.new(Socketry::Error)
+
   # Timeouts performing an I/O operation
   TimeoutError = Class.new(Socketry::Error)
 

data/lib/socketry/resolver/resolv.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "resolv"
+
 module Socketry
   module Resolver
     # Pure Ruby DNS resolver provided by the standard library

data/lib/socketry/ssl/socket.rb

@@ -26,9 +26,10 @@ module Socketry
         raise TypeError, "expected Hash, got #{ssl_params.class}" if ssl_params && !ssl_params.is_a?(Hash)
 
         @ssl_socket_class = ssl_socket_class
+
         @ssl_context = ssl_context
         @ssl_context.set_params(ssl_params) if ssl_params && !ssl_params.empty?
-        @ssl_context.freeze
+
         @ssl_socket = nil
 
         super(**args)
@@ -41,7 +42,8 @@ module Socketry
       # @param local_addr [String] DNS name or IP address to bind to locally
       # @param local_port [Fixnum] Local TCP port to bind to
       # @param timeout [Numeric] Number of seconds to wait before aborting connect
-      # @param socket_class [Class] Custom low-level socket class
+      # @param enable_sni [true, false] (default: true) Enables Server Name Indication (SNI)
+      # @param verify_hostname [true, false] (default: true) Ensure server's hostname matches cert
       # @raise [Socketry::AddressError] an invalid address was given
       # @raise [Socketry::TimeoutError] connect operation timed out
       # @raise [Socketry::SSL::Error] an error occurred negotiating an SSL connection
@@ -52,12 +54,13 @@ module Socketry
         local_addr: nil,
         local_port: nil,
         timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:connect],
+        enable_sni: true,
         verify_hostname: true
       )
         super(remote_addr, remote_port, local_addr: local_addr, local_port: local_port, timeout: timeout)
 
         @ssl_socket = OpenSSL::SSL::SSLSocket.new(@socket, @ssl_context)
-        @ssl_socket.hostname = remote_addr
+        @ssl_socket.hostname = remote_addr if enable_sni
 
         begin
           @ssl_socket.connect_nonblock
@@ -110,23 +113,13 @@ module Socketry
       # @raise [Socketry::Error] an I/O operation failed
       # @return [String, :wait_readable] data read, or :wait_readable if operation would block
       def read_nonblock(size, outbuf: nil)
-        ensure_connected
         case outbuf
         when String
-          @ssl_socket.read_nonblock(size, outbuf, exception: false)
+          perform { @ssl_socket.read_nonblock(size, outbuf, exception: false) }
         when NilClass
-          @ssl_socket.read_nonblock(size, exception: false)
+          perform { @ssl_socket.read_nonblock(size, exception: false) }
         else raise TypeError, "unexpected outbuf class: #{outbuf.class}"
         end
-      # Some buggy Rubies continue to raise exceptions in these cases
-      rescue IO::WaitReadable
-        :wait_readable
-      # Due to SSL, we may need to write to complete a read (e.g. renegotiation)
-      rescue IO::WaitWritable
-        :wait_writable
-      rescue => ex
-        # TODO: more specific exceptions
-        raise Socketry::Error, ex.message, ex.backtrace
       end
 
       # Perform a non-blocking write operation
@@ -135,26 +128,33 @@ module Socketry
       # @raise [Socketry::Error] an I/O operation failed
       # @return [Fixnum, :wait_writable] number of bytes written, or :wait_writable if op would block
       def write_nonblock(data)
+        perform { @ssl_socket.write_nonblock(data, exception: false) }
+      end
+
+      # Close the socket
+      #
+      # @return [true, false] true if the socket was open, false if closed
+      def close
+        @ssl_socket.close rescue nil
+        super
+      end
+
+      private
+
+      # Perform a non-blocking I/O operation
+      def perform
         ensure_connected
-        @ssl_socket.write_nonblock(data, exception: false)
+        yield
       # Some buggy Rubies continue to raise this exception
-      rescue IO::WaitWriteable
+      rescue IO::WaitWritable
         :wait_writable
-      # Due to SSL, we may need to write to complete a read (e.g. renegotiation)
+      # Due to SSL, we may need to write to complete a read (e.g. handshaking, renegotiation)
       rescue IO::WaitReadable
         :wait_readable
       rescue => ex
         # TODO: more specific exceptions
         raise Socketry::Error, ex.message, ex.backtrace
       end
-
-      # Close the socket
-      #
-      # @return [true, false] true if the socket was open, false if closed
-      def close
-        @ssl_socket.close
-        super
-      end
     end
   end
 end

data/lib/socketry/tcp/server.rb

@@ -43,6 +43,8 @@ module Socketry
         end
 
         start_timer(timer)
+      rescue Errno::EADDRINUSE => ex
+        raise AddressInUseError, ex.message, ex.backtrace
       end
 
       # Accept a connection to the server

data/lib/socketry/tcp/socket.rb

@@ -7,7 +7,7 @@ module Socketry
     class Socket
       include Socketry::Timeout
 
-      attr_reader :remote_addr, :remote_port, :local_addr, :local_port
+      attr_reader :addr_fmaily, :remote_addr, :remote_port, :local_addr, :local_port
       attr_reader :read_timeout, :write_timeout, :resolver, :socket_class
 
       # Create a Socketry::TCP::Socket with the default options, then connect
@@ -15,6 +15,7 @@ module Socketry
       #
       # @param remote_addr [String] DNS name or IP address of the host to connect to
       # @param remote_port [Fixnum] TCP port to connect to
+      #
       # @return [Socketry::TCP::Socket]
       def self.connect(remote_addr, remote_port, **args)
         new.connect(remote_addr, remote_port, **args)
@@ -27,6 +28,7 @@ module Socketry
       # @param timer         [Object]  A timekeeping object to use for measuring timeouts
       # @param resolver      [Object]  A resolver object to use for resolving DNS names
       # @param socket_class  [Object]  Underlying socket class which implements I/O ops
+      #
       # @return [Socketry::TCP::Socket]
       def initialize(
         read_timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:read],
@@ -41,7 +43,7 @@ module Socketry
         @socket_class = socket_class
         @resolver = resolver
 
-        @family = nil
+        @addr_family = nil
         @socket = nil
 
         @remote_addr = nil
@@ -59,9 +61,10 @@ module Socketry
       # @param local_addr   [String]  DNS name or IP address to bind to locally
       # @param local_port   [Fixnum]  Local TCP port to bind to
       # @param timeout      [Numeric] Number of seconds to wait before aborting connect
-      # @param socket_class [Class]   Custom low-level socket class
+      #
       # @raise [Socketry::AddressError] an invalid address was given
       # @raise [Socketry::TimeoutError] connect operation timed out
+      #
       # @return [self]
       def connect(
         remote_addr,
@@ -84,14 +87,12 @@ module Socketry
           local_addr  = @resolver.resolve(local_addr,  timeout: time_remaining(timeout)) if local_addr
           raise ArgumentError, "expected IPAddr from resolver, got #{remote_addr.class}" unless remote_addr.is_a?(IPAddr)
 
-          if remote_addr.ipv4?
-            @family = ::Socket::AF_INET
-          elsif remote_addr.ipv6?
-            @family = ::Socket::AF_INET6
-          else raise Socketry::AddressError, "unsupported IP address family: #{remote_addr}"
-          end
+          @addr_family = if remote_addr.ipv4?    then ::Socket::AF_INET
+                         elsif remote_addr.ipv6? then ::Socket::AF_INET6
+                         else raise Socketry::AddressError, "unsupported IP address family: #{remote_addr}"
+                         end
 
-          socket = @socket_class.new(@family, ::Socket::SOCK_STREAM, 0)
+          socket = @socket_class.new(@addr_family, ::Socket::SOCK_STREAM, 0)
           socket.bind Addrinfo.tcp(local_addr.to_s, local_port) if local_addr
           remote_sockaddr = ::Socket.sockaddr_in(remote_port, remote_addr.to_s)
 
@@ -143,7 +144,9 @@ module Socketry
       #
       # @param size [Fixnum] number of bytes to attempt to read
       # @param outbuf [String, NilClass] an optional buffer into which data should be read
+      #
       # @raise [Socketry::Error] an I/O operation failed
+      #
       # @return [String, :wait_readable] data read, or :wait_readable if operation would block
       def read_nonblock(size, outbuf: nil)
         ensure_connected
@@ -188,7 +191,9 @@ module Socketry
       # @param size [Fixnum] number of bytes to attempt to read
       # @param outbuf [String] an output buffer to read data into
       # @param timeout [Numeric] Number of seconds to wait for read operation to complete
+      #
       # @raise [Socketry::Error] an I/O operation failed
+      #
       # @return [String, :eof] bytes read, or :eof if socket closed while reading
       def read(size, outbuf: String.new, timeout: @write_timeout)
         outbuf.clear
@@ -212,7 +217,9 @@ module Socketry
       # Perform a non-blocking write operation
       #
       # @param data [String] data to write to the socket
+      #
       # @raise [Socketry::Error] an I/O operation failed
+      #
       # @return [Fixnum, :wait_writable] number of bytes written, or :wait_writable if op would block
       def write_nonblock(data)
         ensure_connected
@@ -249,7 +256,9 @@ module Socketry
       #
       # @param data [String] data to write to the socket
       # @param timeout [Numeric] Number of seconds to wait for write operation to complete
+      #
       # @raise [Socketry::Error] an I/O operation failed
+      #
       # @return [Fixnum] number of bytes written, or :eof if socket closed during writing
       def write(data, timeout: @write_timeout)
         total_written = data.size

data/lib/socketry/udp/datagram.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Socketry
+  # User Datagram Protocol: "fire-and-forget" packet protocol
+  module UDP
+    # Represents a received UDP message
+    class Datagram
+      attr_reader :message, :sockaddr, :host, :addr, :port
+
+      def initialize(message, sockaddr)
+        @message  = message
+        @sockaddr = sockaddr
+        @port     = sockaddr[1]
+        @host     = sockaddr[2]
+        @addr     = sockaddr[3]
+      end
+
+      def addrinfo
+        addr_family = case @sockaddr[0]
+                      when "AF_INET"  then ::Socket::AF_INET
+                      when "AF_INET6" then ::Socket::AF_INET6
+                      else raise Socketry::AddressError, "unsupported IP address family: #{@sockaddr[0]}"
+                      end
+
+        Addrinfo.new(@sockaddr, addr_family, ::Socket::SOCK_DGRAM)
+      end
+    end
+  end
+end

data/lib/socketry/udp/socket.rb

@@ -7,31 +7,39 @@ module Socketry
     class Socket
       include Socketry::Timeout
 
-      attr_reader :read_timeout, :write_timeout, :resolver, :socket_class
+      attr_reader :addr_family, :read_timeout, :write_timeout, :resolver, :socket_class
 
       # Create a UDP socket matching the given socket's address family
       #
-      # @param remote_addr [String] address to connect/bind to
+      # @param remote_addr [String] Address to connect/bind to
+      # @param resolver    [Object] Resolver object to use for resolving DNS names
+      #
       # @return [Socketry::UDP::Socket]
       def self.from_addr(remote_addr, resolver: Socketry::Resolver::DEFAULT_RESOLVER)
         addr = resolver.resolve(remote_addr)
-        if addr.ipv4?
-          new(family: :ipv4)
-        elsif addr.ipv6?
-          new(family: :ipv6)
+        if addr.ipv4?    then new(addr_family: :ipv4)
+        elsif addr.ipv6? then new(addr_family: :ipv6)
         else raise Socketry::AddressError, "unsupported IP address family: #{addr}"
         end
       end
 
-      # Bind to the given address and port
+      # Create a UDP server bound to the given address and port
+      #
+      # @param local_addr [String] Local DNS name or IP address to listen on
+      # @param local_port [Fixnum] Local UDP port to listen on
+      # @param resolver   [Object] Resolver object to use for resolving DNS names
       #
       # @return [Socketry::UDP::Socket]
-      def self.bind(remote_addr, remote_port, resolver: Socketry::Resolver::DEFAULT_RESOLVER)
-        from_addr(remote_addr, resolver: resolver).bind(remote_addr, remote_port)
+      def self.bind(local_addr, local_port, resolver: Socketry::Resolver::DEFAULT_RESOLVER)
+        from_addr(local_addr, resolver: resolver).bind(local_addr, local_port)
       end
 
       # Connect to the given address and port
       #
+      # @param remote_addr [String] DNS name or IP address of the host to connect to
+      # @param remote_port [Fixnum] UDP port to connect to
+      # @param resolver    [Object] Resolver object to use for resolving DNS names
+      #
       # @return [Socketry::UDP::Socket]
       def self.connect(remote_addr, remote_port, resolver: Socketry::Resolver::DEFAULT_RESOLVER)
         from_addr(remote_addr, resolver: resolver).connect(remote_addr, remote_port)
@@ -39,26 +47,32 @@ module Socketry
 
       # Create a new UDP socket
       #
+      # @param addr_family   [:ipv4, :ipv6] (default :ipv4) address family for this socket
+      # @param read_timeout  [Numeric] Seconds to wait before an uncompleted read errors
+      # @param write_timeout [Numeric] Seconds to wait before an uncompleted write errors
+      # @param timer         [Object]  Time interval object to use for measuring timeouts
+      # @param resolver      [Object]  Resolver object to use for resolving DNS names
+      # @param socket_class  [Object]  Underlying socket class which implements I/O ops
+      #
+      # @raise [ArgumentError] an invalid argument was given
+      #
       # @return [Socketry::UDP::Socket]
       def initialize(
-        family: :ipv4,
+        addr_family: :ipv4,
         read_timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:read],
         write_timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:write],
         timer: Socketry::Timeout::DEFAULT_TIMER.new,
         resolver: Socketry::Resolver::DEFAULT_RESOLVER,
         socket_class: ::UDPSocket
       )
-        case family
-        when :ipv4
-          @address_family = ::Socket::AF_INET
-        when :ipv6
-          @address_family = ::Socket::AF_INET6
-        when ::Socket::AF_INET, ::Socket::AF_INET6
-          @address_family = address_family
-        else raise ArgumentError, "invalid address family: #{address_family.inspect}"
-        end
+        @addr_family = case addr_family
+                       when :ipv4 then ::Socket::AF_INET
+                       when :ipv6 then ::Socket::AF_INET6
+                       when ::Socket::AF_INET, ::Socket::AF_INET6 then addr_family
+                       else raise ArgumentError, "invalid address family: #{addr_family.inspect}"
+                       end
 
-        @socket        = socket_class.new(@address_family)
+        @socket        = socket_class.new(@addr_family)
         @read_timeout  = read_timeout
         @write_timeout = write_timeout
         @resolver      = resolver
@@ -66,22 +80,29 @@ module Socketry
         start_timer(timer)
       end
 
-      # Bind to the given address and port
+      # Start a UDP server bound to a particular address and port
+      #
+      # @param local_addr [String] Local DNS name or IP address to listen on
+      # @param local_port [Fixnum] Local UDP port to listen on
       #
       # @return [self]
-      def bind(remote_addr, remote_port)
-        @socket.bind(@resolver.resolve(remote_addr), remote_port)
+      def bind(local_addr, local_port)
+        @socket.bind(@resolver.resolve(local_addr).to_s, local_port)
         self
+      rescue Errno::EADDRINUSE => ex
+        raise AddressInUseError, ex.message, ex.backtrace
       rescue => ex
-        # TODO: more specific exceptions
         raise Socketry::Error, ex.message, ex.backtrace
       end
 
-      # Create a new UDP socket
+      # Make a UDP client connection to the given address and port
+      #
+      # @param remote_addr [String] DNS name or IP address of the host to connect to
+      # @param remote_port [Fixnum] UDP port to connect to
       #
       # @return [self]
       def connect(remote_addr, remote_port)
-        @socket.connect(@resolver.resolve(remote_addr), remote_port)
+        @socket.connect(@resolver.resolve(remote_addr).to_s, remote_port)
         self
       rescue => ex
         # TODO: more specific exceptions
@@ -90,9 +111,11 @@ module Socketry
 
       # Perform a non-blocking receive
       #
-      # @return [String, :wait_readable] received packet or indication to wait
+      # @param maxlen [Fixnum] Maximum packet length to receive
+      #
+      # @return [Socketry::UDP::Datagram, :wait_readable] Received datagram or indication to wait
       def recvfrom_nonblock(maxlen)
-        @socket.recvfrom_nonblock(maxlen)
+        Socketry::UDP::Datagram.new(*@socket.recvfrom_nonblock(maxlen))
       rescue ::IO::WaitReadable
         :wait_readable
       rescue => ex
@@ -102,7 +125,10 @@ module Socketry
 
       # Perform a blocking receive
       #
-      # @return [String] received data
+      # @param maxlen  [Fixnum] Maximum packet length to receive
+      # @param timeout [Numeric] Number of seconds to wait for recvfrom operation to complete
+      #
+      # @return [String] Received data
       def recvfrom(maxlen, timeout: @read_timeout)
         set_timeout(timeout)
 
@@ -112,19 +138,48 @@ module Socketry
             raise Socketry::TimeoutError, "recvfrom timed out after #{timeout} seconds"
           end
         ensure
-          clear_timeout(imeout)
+          clear_timeout(timeout)
         end
 
         result
       end
 
-      # Send data to the given host and port
-      def send(msg, host:, port:)
-        @socket.send(msg, 0, @resolver.resolve(host), port)
+      # Send a UDP packet to a remote host
+      #
+      # @param msg  [String] Data to write to the remote host/port
+      # @param host [String] Remote host to send data to. May be omitted if `connect` was called previously
+      # @param port [Fixnum] UDP port to send data to. May be omitted if `connect` was called previously
+      #
+      # @return [Fixum] Number of bytes sent
+      def send(msg, host: nil, port: nil)
+        host = @resolver.resolve(host).to_s if host
+        if host || port
+          @socket.send(msg, 0, host, port)
+        else
+          @socket.send(msg, 0)
+        end
       rescue => ex
         # TODO: more specific exceptions
         raise Socketry::Error, ex.message, ex.backtrace
       end
+
+      # Close the socket
+      #
+      # @return [true, false] true if the socket was open, false if closed
+      def close
+        return false if closed?
+        @socket.close
+        true
+      ensure
+        @socket = nil
+      end
+
+      # Is the socket closed?
+      #
+      # @return [true, false] do we locally think the socket is closed?
+      def closed?
+        @socket.nil?
+      end
     end
   end
 end

data/lib/socketry/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Socketry
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: socketry
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-24 00:00:00.000000000 Z
+date: 2016-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hitimes
@@ -66,6 +66,7 @@ files:
 - lib/socketry/tcp/server.rb
 - lib/socketry/tcp/socket.rb
 - lib/socketry/timeout.rb
+- lib/socketry/udp/datagram.rb
 - lib/socketry/udp/socket.rb
 - lib/socketry/version.rb
 - socketry.gemspec
@@ -89,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: High-level wrappers for Ruby sockets with advanced thread-safe timeout support