socketry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dae535663b1bc19486c7766d86d1444cf097fb81
+  data.tar.gz: 31212e71094435898cd1f2937bece83f9f863708
+SHA512:
+  metadata.gz: 5e4bedb944e9683e08e6027edc585c09383c9f962eec07375a70fff0aaac3fdeedf5020ec12beaa56213de0bb96d1b1a3d66fbd0cd5655544e22b96530f52836
+  data.tar.gz: b169b991a93b8667ad3f532889751e05aa5e25a98825452da04ddcbcfc5652a8fb01218f0a48212d111e02316f677156d72190ba64e6a74b0bfbe1325ed251b2

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,5 @@
+--backtrace
+--color
+--format=documentation
+--order random
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,56 @@
+AllCops:
+  DisplayCopNames: true
+
+#
+# Style
+#
+
+LineLength:
+  Max: 128
+
+Style/AccessorMethodName:
+  Enabled: false
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/SpaceBeforeFirstArg:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+#
+# Metrics
+#
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+#
+# Lint
+#
+
+Lint/HandleExceptions:
+  Enabled: false
+
+Lint/ShadowedException:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+sudo: false
+
+bundler_args: --without development doc
+
+rvm:
+  - 2.2
+  - 2.3.1
+  - jruby-9.0.5.0
+
+matrix:
+  fast_finish: true
+
+branches:
+  only:
+    - master

data/CHANGES.md

@@ -0,0 +1,3 @@
+## 0.1.0 (2016-09-11)
+
+* Initial release

data/Gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "guard-rspec", require: false
+  gem "pry", require: false
+end
+
+group :test do
+  gem "rspec", "~> 3", require: false
+  gem "rubocop", "0.42.0", require: false
+  gem "coveralls", require: false
+end
+
+group :development, :test do
+  gem "rake"
+end

data/Guardfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+directories %w(lib spec)
+clearing :on
+
+guard :rspec, cmd: "bundle exec rspec" do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})    { |m| "spec/#{m[1]}_spec.rb" }
+  watch("spec/spec_helper.rb") { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2015-2016 Tony Arcieri, Zachary Anker
+
+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,55 @@
+# Socketry [![Gem Version][gem-image]][gem-link] [![Build Status][build-image]][build-link] [![Code Climate][codeclimate-image]][codeclimate-link] [![Coverage Status][coverage-image]][coverage-link] [![MIT licensed][license-image]][license-link]
+
+[gem-image]: https://badge.fury.io/rb/socketry.svg
+[gem-link]: https://rubygems.org/gems/socketry
+[build-image]: https://secure.travis-ci.org/socketry/socketry.svg?branch=master
+[build-link]: https://travis-ci.org/socketry/socketry
+[codeclimate-image]: https://codeclimate.com/github/socketry/socketry.svg?branch=master
+[codeclimate-link]: https://codeclimate.com/github/socketry/socketry
+[coverage-image]: https://coveralls.io/repos/github/socketry/socketry/badge.svg?branch=master
+[coverage-link]: https://coveralls.io/github/socketry/socketry?branch=master
+[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.
+
+**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
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'socketry'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install socketry
+
+## Usage
+
+TODO: Coming soon!
+
+## Contributing
+
+* Fork this repository on github
+* Make your changes and send us a pull request
+* If we like them we'll merge them
+* If we've accepted a patch, feel free to ask for commit access
+
+## License
+
+Copyright (c) 2016 Tony Arcieri
+
+Distributed under the MIT License. See
+[LICENSE.txt](https://github.com/socketry/socketry/blob/master/LICENSE.txt)
+for further details.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+task default: %w(spec rubocop)

data/lib/socketry.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Ruby stdlib dependencies
+require "io/wait"
+require "ipaddr"
+require "socket"
+require "openssl"
+
+# External gems
+require "hitimes"
+
+# Socketry codebase
+require "socketry/version"
+
+require "socketry/exceptions"
+require "socketry/resolver/resolv"
+require "socketry/resolver/system"
+require "socketry/timeout"
+
+require "socketry/tcp/server"
+require "socketry/tcp/socket"
+require "socketry/ssl/server"
+require "socketry/ssl/socket"
+require "socketry/udp/socket"

data/lib/socketry/exceptions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Socketry
+  # Generic catch all for all Socketry errors
+  Error = Class.new(::IOError)
+
+  # Invalid address
+  AddressError = Class.new(Socketry::Error)
+
+  # Timeouts performing an I/O operation
+  TimeoutError = Class.new(Socketry::Error)
+
+  # Cannot perform operation in current state
+  StateError = Class.new(Socketry::Error)
+
+  # Internal consistency error within the library
+  InternalError = Class.new(Socketry::Error)
+
+  module Resolver
+    # DNS resolution errors
+    Error = Class.new(Socketry::AddressError)
+  end
+
+  module SSL
+    # Errors related to SSL
+    Error = Class.new(Socketry::Error)
+
+    # Hostname verification error
+    HostnameError = Class.new(Socketry::SSL::Error)
+  end
+end

data/lib/socketry/resolver/resolv.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Socketry
+  module Resolver
+    # Pure Ruby DNS resolver provided by the standard library
+    class Resolv
+      # Resolve a hostname by creating and discaring a Socketry::Resolver::Resolv
+      # instance. For better performance, create and reuse an instance.
+      def self.resolve(hostname, **options)
+        resolver = new
+        begin
+          resolver.resolve(hostname, **options)
+        ensure
+          resolver.close
+        end
+      end
+
+      # Create a new instance of Socketry::Resolver::Resolv.
+      #
+      # Arguments are passed directly to Resolv::DNS. See the Ruby documentation
+      # for more information:
+      #
+      # https://ruby-doc.org/stdlib-2.3.1/libdoc/resolv/rdoc/Resolv/DNS.html
+      #
+      def initialize(*args)
+        @hosts = ::Resolv::Hosts.new
+        @resolver = ::Resolv::DNS.new(*args)
+      end
+
+      # Resolve a domain name using IPSocket.getaddress. This uses getaddrinfo(3)
+      # on POSIX operating systems.
+      #
+      # @param hostname [String] name of the host whose IP address we'd like to obtain
+      # @return [IPAddr] resolved IP address
+      # @raise [Socketry::Resolver::Error] an error occurred resolving the domain name
+      # @raise [Socketry::TimeoutError] a timeout occured before the name could be resolved
+      # @raise [Socketry::AddressError] the name was resolved to an unsupported address
+      def resolve(hostname, timeout: nil)
+        raise TypeError, "expected String, got #{hostname.class}" unless hostname.is_a?(String)
+        return IPAddr.new(@hosts.getaddress(hostname).sub(/%.*$/, ""))
+      rescue ::Resolv::ResolvError
+        case timeout
+        when Integer, Float
+          @resolver.timeouts = timeout
+        when NilClass
+          # no timeout
+        else raise TypeError, "expected Numeric, got #{timeout.class}"
+        end
+
+        begin
+          IPAddr.new(@resolver.getaddress(hostname).to_s)
+        rescue ::Resolv::ResolvError => ex
+          raise Socketry::Resolver::Error, ex.message, ex.backtrace
+        rescue ::Resolv::ResolvTimeout => ex
+          raise Socketry::TimeoutError, ex.message, ex.backtrace
+        end
+      end
+
+      # Close the resolver
+      def close
+        @resolver.close
+      end
+    end
+  end
+end

data/lib/socketry/resolver/system.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Socketry
+  module Resolver
+    # System DNS resolver backed by the POSIX getaddrinfo(3) function
+    module System
+      module_function
+
+      # Resolve a domain name using IPSocket.getaddress. This uses getaddrinfo(3)
+      # on POSIX operating systems.
+      #
+      # @param hostname [String] name of the host whose IP address we'd like to obtain
+      # @return [IPAddr] resolved IP address
+      # @raise [Socketry::Resolver::Error] an error occurred resolving the domain name
+      # @raise [Socketry::TimeoutError] a timeout occured before the name could be resolved
+      # @raise [Socketry::AddressError] the name was resolved to an unsupported address
+      def resolve(hostname, timeout: nil)
+        raise TypeError, "expected String, got #{hostname.class}" unless hostname.is_a?(String)
+
+        begin
+          case timeout
+          when Integer, Float
+            # NOTE: ::Timeout is not thread safe. For thread safety, use Socketry::Resolver::Resolv
+            result = ::Timeout.timeout(timeout) { IPSocket.getaddress(hostname) }
+          when NilClass
+            result = IPSocket.getaddress(hostname)
+          else raise TypeError, "expected Numeric, got #{timeout.class}"
+          end
+        rescue ::SocketError => ex
+          raise Socketry::Resolver::Error, ex.message, ex.backtrace
+        rescue ::Timeout::Error => ex
+          raise Socketry::TimeoutError, ex.message, ex.backtrace
+        end
+
+        begin
+          IPAddr.new(result)
+        rescue IPAddr::InvalidAddressError => ex
+          raise Socketry::AddressError, ex.message, ex.backtrace
+        end
+      end
+    end
+
+    # Use Socketry::Resolver::System as the default resolver
+    DEFAULT_RESOLVER = System
+  end
+end

data/lib/socketry/ssl/server.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Socketry
+  # Secure Sockets Layer (a.k.a. Transport Layer Security, or TLS)
+  module SSL
+    # SSL Server
+    class Server < Socketry::TCP::Server
+      # Create a new SSL server
+      #
+      # @return [Socketry::SSL::Server]
+      def initialize(
+        hostname_or_port,
+        port = nil,
+        ssl_socket_class: OpenSSL::SSL::SSLSocket,
+        ssl_params: nil,
+        **args
+      )
+        raise TypeError, "expected Hash, got #{ssl_params.class}" if ssl_params && !ssl_params.is_a?(Hash)
+
+        @ssl_socket_class = ssl_socket_class
+        @ssl_context = OpenSSL::SSL::SSLContext.new
+        @ssl_context.set_params(ssl_params) if ssl_params
+        @ssl_context.freeze
+
+        super(hostname_or_port, port, **args)
+      end
+
+      # Accept a connection to the server
+      #
+      # Note that this method also performs an SSL handshake and will therefore
+      # block other sockets which are ready to be accepted.
+      #
+      # Multithreaded servers should invoke this method after spawning a thread
+      # to ensure a slow/malicious connection can't cause a denial-of-service
+      # attack against the server.
+      #
+      # @param timeout [Numeric, NilClass] seconds to wait before aborting the accept
+      # @return [Socketry::SSL::Socket]
+      def accept(timeout: nil, **args)
+        ruby_socket = super(timeout: timeout, **args).to_io
+        ssl_socket  = @ssl_socket_class.new(ruby_socket, @ssl_context)
+
+        begin
+          ssl_socket.accept_nonblock
+        rescue IO::WaitReadable
+          retry if IO.select([ruby_socket], nil, nil, timeout)
+          raise Socketry::TimeoutError, "failed to complete handshake after #{timeout} seconds"
+        rescue IO::WaitWritable
+          retry if IO.select(nil, [ruby_socket], nil, timeout)
+          raise Socketry::TimeoutError, "failed to complete handshake after #{timeout} seconds"
+        end
+
+        Socketry::SSL::Socket.new(
+          read_timeout:  @read_timeout,
+          write_timeout: @write_timeout,
+          resolver:      @resolver,
+          socket_class:  @socket_class
+        ).from_socket(ruby_socket)
+      end
+    end
+  end
+end

data/lib/socketry/ssl/socket.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Socketry
+  # Secure Sockets Layer (a.k.a. Transport Layer Security, or TLS)
+  module SSL
+    # SSL Sockets
+    class Socket < Socketry::TCP::Socket
+      # Create an unconnected Socketry::SSL::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]  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::SSL::Socket]
+      def initialize(ssl_socket_class: OpenSSL::SSL::SSLSocket, ssl_params: nil, **args)
+        raise TypeError, "expected Hash, got #{ssl_params.class}" if ssl_params && !ssl_params.is_a?(Hash)
+
+        @ssl_socket_class = ssl_socket_class
+        @ssl_context = OpenSSL::SSL::SSLContext.new
+        @ssl_context.set_params(ssl_params) if ssl_params
+        @ssl_context.freeze
+        @ssl_socket = nil
+
+        super(**args)
+      end
+
+      # Make an SSL connection to a remote host
+      #
+      # @param remote_addr  [String]  DNS name or IP address of the host to connect to
+      # @param remote_port  [Fixnum]  TCP port to connect to
+      # @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
+      # @raise [Socketry::SSL::Error] an error occurred negotiating an SSL connection
+      # @return [self]
+      def connect(
+        remote_addr,
+        remote_port,
+        local_addr: nil,
+        local_port: nil,
+        timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:connect],
+        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
+
+        begin
+          @ssl_socket.connect_nonblock
+        rescue IO::WaitReadable
+          retry if @socket.wait_readable(timeout)
+          raise Socketry::TimeoutError, "connection to #{remote_addr}:#{remote_port} timed out"
+        rescue IO::WaitWritable
+          retry if @socket.wait_writable(timeout)
+          raise Socketry::TimeoutError, "connection to #{remote_addr}:#{remote_port} timed out"
+        rescue OpenSSL::SSL::SSLError => ex
+          raise Socketry::SSL::Error, ex.message, ex.backtrace
+        end
+
+        begin
+          @ssl_socket.post_connection_check(remote_addr) if verify_hostname
+        rescue OpenSSL::SSL::SSLError => ex
+          raise Socketry::SSL::HostnameError, ex.message, ex.backtrace
+        end
+
+        self
+      rescue => ex
+        @socket.close rescue nil
+        @socket = nil
+        @ssl_socket.close rescue nil
+        @ssl_socket = nil
+        raise ex
+      end
+
+      # Wrap a Ruby OpenSSL::SSL::SSLSocket (or other low-level SSL socket)
+      #
+      # @param socket [::Socket] (or specified socket_class) low-level socket to wrap
+      # @param ssl_socket [OpenSSL::SSL::SSLSocket] SSL socket class associated with this socket
+      # @return [self]
+      def from_socket(socket, ssl_socket)
+        raise TypeError, "expected #{@socket_class}, got #{socket.class}" unless socket.is_a?(@socket_class)
+        raise TypeError, "expected #{@ssl_socket_class}, got #{ssl_socket.class}" unless ssl_socket.is_a?(@ssl_socket_class)
+        raise StateError, "already connected" if @socket && @socket != socket
+
+        @socket = socket
+        @ssl_socket = ssl_socket
+        @ssl_socket.sync_close = true
+
+        self
+      end
+
+      # Perform a non-blocking read operation
+      #
+      # @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)
+        ensure_connected
+        @ssl_socket.read_nonblock(size, exception: false)
+      # 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
+      #
+      # @param data [String] number of bytes to attempt to read
+      # @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
+        @ssl_socket.write_nonblock(data, exception: false)
+      # Some buggy Rubies continue to raise this exception
+      rescue IO::WaitWriteable
+        :wait_writable
+      # Due to SSL, we may need to write to complete a read (e.g. 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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Socketry
+  # Transmission Control Protocol
+  module TCP
+    # Transmission Control Protocol servers: Accept connections from the network
+    class Server
+      include Socketry::Timeout
+      alias uptime lifetime
+
+      attr_reader :read_timeout, :write_timeout, :resolver, :socket_class
+
+      # Create a new TCP server, yielding the server socket and auto-closing it
+      def self.open(hostname_or_port, port = nil, **args)
+        server = new(hostname_or_port, port, **args)
+        result = yield server
+        server.close
+        result
+      end
+
+      # Create a new TCP server
+      #
+      # @return [Socketry::TCP::Server]
+      def initialize(
+        hostname_or_port,
+        port = nil,
+        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,
+        server_class: ::TCPServer,
+        socket_class: ::TCPSocket
+      )
+        @read_timeout  = read_timeout
+        @write_timeout = write_timeout
+        @resolver      = resolver
+        @socket_class  = socket_class
+
+        if port
+          @server = server_class.new(@resolver.resolve(hostname_or_port).to_s, port)
+        else
+          @server = server_class.new(hostname_or_port)
+        end
+
+        start_timer(timer)
+      end
+
+      # Accept a connection to the server
+      #
+      # @param timeout [Numeric, NilClass] seconds to wait before aborting the accept
+      # @return [Socketry::TCP::Socket]
+      def accept(timeout: nil)
+        set_timeout(timeout)
+
+        begin
+          # Note: `exception: false` for TCPServer#accept_nonblock is only supported in Ruby 2.3+
+          ruby_socket = @server.accept_nonblock
+        rescue IO::WaitReadable, Errno::EAGAIN
+          # Ruby 2.2 has trouble using io/wait here
+          retry if IO.select([@server], nil, nil, time_remaining(timeout))
+          raise Socketry::TimeoutError, "no connection received after #{timeout} seconds"
+        end
+
+        Socketry::TCP::Socket.new(
+          read_timeout:  @read_timeout,
+          write_timeout: @write_timeout,
+          resolver:      @resolver,
+          socket_class:  @socket_class
+        ).from_socket(ruby_socket)
+      ensure
+        clear_timeout(timeout)
+      end
+
+      # Close the server
+      def close
+        return false unless @server
+        @server.close rescue nil
+        @server = nil
+        true
+      end
+    end
+  end
+end

data/lib/socketry/tcp/socket.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Socketry
+  # Transmission Control Protocol
+  module TCP
+    # Transmission Control Protocol sockets: Provide stream-like semantics
+    class Socket
+      include Socketry::Timeout
+
+      attr_reader :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
+      # to the given host.
+      #
+      # @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)
+      end
+
+      # Create an unconnected Socketry::TCP::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]  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],
+        write_timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:write],
+        timer: Socketry::Timeout::DEFAULT_TIMER.new,
+        resolver: Socketry::Resolver::DEFAULT_RESOLVER,
+        socket_class: ::Socket
+      )
+        @read_timeout = read_timeout
+        @write_timeout = write_timeout
+
+        @socket_class = socket_class
+        @resolver = resolver
+
+        @family = nil
+        @socket = nil
+
+        @remote_addr = nil
+        @remote_port = nil
+        @local_addr  = nil
+        @local_port  = nil
+
+        start_timer(timer)
+      end
+
+      # Connect to a remote host
+      #
+      # @param remote_addr  [String]  DNS name or IP address of the host to connect to
+      # @param remote_port  [Fixnum]  TCP port to connect to
+      # @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,
+        remote_port,
+        local_addr: nil,
+        local_port: nil,
+        timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:connect]
+      )
+        ensure_disconnected
+
+        @remote_addr = remote_addr
+        @remote_port = remote_port
+        @local_addr  = local_addr
+        @local_port  = local_port
+
+        begin
+          set_timeout(timeout)
+
+          remote_addr = @resolver.resolve(remote_addr, timeout: time_remaining(timeout))
+          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
+
+          socket = @socket_class.new(@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)
+
+          # Note: `exception: false` for Socket#connect_nonblock is only supported in Ruby 2.3+
+          begin
+            socket.connect_nonblock(remote_sockaddr)
+          rescue Errno::EINPROGRESS, Errno::EALREADY
+            # Earlier JRuby 9.x versions do not seem to correctly support Socket#wait_writable in this case
+            # Newer versions seem to behave correctly
+            retry if IO.select(nil, [socket], nil, time_remaining(timeout))
+
+            socket.close
+            raise Socketry::TimeoutError, "connection to #{remote_addr}:#{remote_port} timed out"
+          rescue Errno::EISCONN
+            # Sometimes raised when we've connected successfully
+          end
+
+          @socket = socket
+        ensure
+          clear_timeout(timeout)
+        end
+
+        self
+      end
+
+      # Re-establish a lost TCP connection
+      #
+      # @param timeout [Numeric] Number of seconds to wait before aborting re-connect
+      # @raise [Socketry::StateError] not in a disconnected state
+      def reconnect(timeout: Socketry::Timeout::DEFAULT_TIMEOUTS[:connect])
+        ensure_disconnected
+        raise StateError, "can't reconnect: never completed initial connection" unless @remote_addr
+        connect(@remote_addr, @remote_port, local_addr: @local_addr, local_port: @local_port, timeout: timeout)
+      end
+
+      # Wrap a Ruby/low-level socket in an Socketry::TCP::Socket
+      #
+      # @param socket [::Socket] (or specified socket_class) low-level socket to wrap
+      def from_socket(socket)
+        ensure_disconnected
+        raise TypeError, "expected #{@socket_class}, got #{socket.class}" unless socket.is_a?(@socket_class)
+        @socket = socket
+        self
+      end
+
+      # Perform a non-blocking read operation
+      #
+      # @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
+        case outbuf
+        when String
+          @socket.read_nonblock(size, outbuf, exception: false)
+        when NilClass
+          @socket.read_nonblock(size, exception: false)
+        else raise TypeError, "unexpected outbuf class: #{outbuf.class}"
+        end
+      rescue IO::WaitReadable
+        # Some buggy Rubies continue to raise this exception
+        :wait_readable
+      rescue IOError => ex
+        raise Socketry::Error, ex.message, ex.backtrace
+      end
+
+      # Read a partial amounth of data, blocking until it becomes available
+      #
+      # @param size [Fixnum] number of bytes to attempt to read
+      # @raise [Socketry::Error] an I/O operation failed
+      # @return [String]
+      def readpartial(size, outbuf: nil, timeout: @read_timeout)
+        set_timeout(timeout)
+
+        begin
+          while (result = read_nonblock(size, outbuf: outbuf)) == :wait_readable
+            next if @socket.wait_readable(read_timeout)
+            raise TimeoutError, "read timed out after #{timeout} seconds"
+          end
+        ensure
+          clear_timeout(timeout)
+        end
+
+        result || :eof
+      end
+
+      # Perform a non-blocking write operation
+      #
+      # @param data [String] number of bytes to attempt to read
+      # @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
+        @socket.write_nonblock(data, exception: false)
+      rescue IO::WaitWriteable
+        # Some buggy Rubies continue to raise this exception
+        :wait_writable
+      rescue IOError => ex
+        raise Socketry::Error, ex.message, ex.backtrace
+      end
+
+      # Write a partial amounth of data, blocking until it's completed
+      #
+      # @param data [String] number of bytes to attempt to read
+      # @raise [Socketry::Error] an I/O operation failed
+      # @return [Fixnum, :wait_writable] number of bytes written, or :wait_writable if op would block
+      def writepartial(data, timeout: @write_timeout)
+        set_timeout(timeout)
+
+        begin
+          while (result = write_nonblock(data)) == :wait_writable
+            next if @socket.wait_writable(read_timeout)
+            raise TimeoutError, "write timed out after #{timeout} seconds"
+          end
+        ensure
+          clear_timeout(timeout)
+        end
+
+        result || :eof
+      end
+
+      # Check whether Nagle's algorithm has been disabled
+      #
+      # @return [true]  Nagle's algorithm has been explicitly disabled
+      # @return [false] Nagle's algorithm is enabled (default)
+      def nodelay
+        ensure_connected
+        @socket.getsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_NODELAY).int.nonzero?
+      end
+
+      # Disable or enable Nagle's algorithm
+      #
+      # @param flag [true, false] disable or enable coalescing multiple writesusing Nagle's algorithm
+      def nodelay=(flag)
+        ensure_connected
+        @socket.setsockopt(::Socket::IPPROTO_TCP, ::Socket::TCP_NODELAY, flag ? 1 : 0)
+      end
+
+      # Return a raw Ruby I/O object
+      #
+      # @return [IO] Ruby I/O object
+      def to_io
+        ensure_connected
+        ::IO.try_convert(@socket)
+      end
+
+      # Close the socket
+      #
+      # @return [true, false] true if the socket was open, false if closed
+      def close
+        return false unless connected?
+        @socket.close
+        true
+      ensure
+        @socket = nil
+      end
+
+      # Is the socket currently connected?
+      #
+      # This method returns the local connection state. However, it's possible
+      # the remote side has closed the connection, so it's not actually
+      # possible to actually know if the socket is actually still open without
+      # reading from or writing to it. It's sort of like the Heisenberg
+      # uncertainty principle of sockets.
+      #
+      # @return [true, false] do we locally think the socket is open?
+      def connected?
+        @socket != nil
+      end
+
+      private
+
+      def ensure_connected
+        return true if connected?
+        raise StateError, "not connected"
+      end
+
+      def ensure_disconnected
+        return true unless connected?
+        raise StateError, "already connected"
+      end
+    end
+  end
+end

data/lib/socketry/timeout.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Socketry
+  # Timeout subsystem
+  module Timeout
+    DEFAULT_TIMER = Hitimes::Interval
+
+    # Default timeouts (in seconds)
+    DEFAULT_TIMEOUTS = {
+      read:    5,
+      write:   5,
+      connect: 5
+    }.freeze
+
+    # Start a timer in the included object
+    #
+    # @param timer [#start, #to_f] a timer object (ideally monotonic)
+    # @return [true] timer started successfully
+    # @raise [Socketry::InternalError] if timer is already started
+    def start_timer(timer = DEFAULT_TIMER_CLASS.new)
+      raise Socketry::InternalError, "timer already started" if defined?(@timer)
+      raise Socketry::InternalError, "deadline already set"  if defined?(@deadline)
+
+      @deadline = nil
+      @timer = timer
+      @timer.start
+      true
+    end
+
+    # Return how long since the timer has been started
+    #
+    # @return [Float] number of seconds since the timer has been started
+    # @raise [Socketry::InternalError] if timer has not been started
+    def lifetime
+      raise Socketry::InternalError, "timer not started" unless @timer
+      @timer.to_f
+    end
+
+    # Set a timeout. Only one timeout may be active at a given time for a given object.
+    #
+    # @param timeout [Numeric] number of seconds until the timeout is reached
+    # @return [Float] deadline (relative to #lifetime) at which the timeout is reached
+    # @raise [Socketry::InternalError] if timeout is already set
+    def set_timeout(timeout)
+      raise Socketry::InternalError, "deadline already set" if @deadline
+      return unless timeout
+      @deadline = lifetime + timeout
+    end
+
+    # Clear an already-set timeout
+    #
+    # @param timeout [Numeric] to gauge whether the timeout actually needs to be cleared
+    # @raise [Socketry::InternalError] if timeout has not been set
+    def clear_timeout(timeout)
+      return unless timeout
+      raise Socketry::InternalError, "no deadline set" unless @deadline
+      @deadline = nil
+    end
+
+    # Calculate number of seconds remaining until we hit the timeout
+    #
+    # @param timeout [Numeric] to gauge whether a timeout needs to be calculated
+    # @return [Float] number of seconds remaining until we hit the timeout
+    # @raise [Socketry::TimeoutError] if we've already hit the timeout
+    # @raise [Socketry::InternalError] if timeout has not been set
+    def time_remaining(timeout)
+      return unless timeout
+      raise Socketry::InternalError, "no deadline set" unless @deadline
+      remaining = @deadline - lifetime
+      raise Socketry::TimeoutError, "time expired" if remaining <= 0
+      remaining
+    end
+  end
+end

data/lib/socketry/udp/socket.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Socketry
+  # User Datagram Protocol: "fire-and-forget" packet protocol
+  module UDP
+    # User Datagram Protocol sockets
+    class Socket
+      include Socketry::Timeout
+
+      attr_reader :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
+      # @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)
+        else raise Socketry::AddressError, "unsupported IP address family: #{addr}"
+        end
+      end
+
+      # Bind to the given address and port
+      #
+      # @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)
+      end
+
+      # Connect to the given address and port
+      #
+      # @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)
+      end
+
+      # Create a new UDP socket
+      #
+      # @return [Socketry::UDP::Socket]
+      def initialize(
+        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
+
+        @socket        = socket_class.new(@address_family)
+        @read_timeout  = read_timeout
+        @write_timeout = write_timeout
+        @resolver      = resolver
+
+        start_timer(timer)
+      end
+
+      # Bind to the given address and port
+      #
+      # @return [self]
+      def bind(remote_addr, remote_port)
+        @socket.bind(@resolver.resolve(remote_addr), remote_port)
+        self
+      rescue => ex
+        # TODO: more specific exceptions
+        raise Socketry::Error, ex.message, ex.backtrace
+      end
+
+      # Create a new UDP socket
+      #
+      # @return [self]
+      def connect(remote_addr, remote_port)
+        @socket.connect(@resolver.resolve(remote_addr), remote_port)
+        self
+      rescue => ex
+        # TODO: more specific exceptions
+        raise Socketry::Error, ex.message, ex.backtrace
+      end
+
+      # Perform a non-blocking receive
+      #
+      # @return [String, :wait_readable] received packet or indication to wait
+      def recvfrom_nonblock(maxlen)
+        @socket.recvfrom_nonblock(maxlen)
+      rescue ::IO::WaitReadable
+        :wait_readable
+      rescue => ex
+        # TODO: more specific exceptions
+        raise Socketry::Error, ex.message, ex.backtrace
+      end
+
+      # Perform a blocking receive
+      #
+      # @return [String] received data
+      def recvfrom(maxlen, timeout: @read_timeout)
+        set_timeout(timeout)
+
+        begin
+          while (result = recvfrom_nonblock(maxlen)) == :wait_readable
+            next if @socket.wait_readable(time_remaining(timeout))
+            raise Socketry::TimeoutError, "recvfrom timed out after #{timeout} seconds"
+          end
+        ensure
+          clear_timeout(imeout)
+        end
+
+        result
+      end
+
+      # Send data to the given host and port
+      def send(msg, host:, port:)
+        @socket.send(msg, 0, @resolver.resolve(host), port)
+      rescue => ex
+        # TODO: more specific exceptions
+        raise Socketry::Error, ex.message, ex.backtrace
+      end
+    end
+  end
+end

data/lib/socketry/version.rb

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

data/socketry.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "socketry/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "socketry"
+  spec.version     = Socketry::VERSION
+  spec.authors     = ["Tony Arcieri", "Zachary Anker"]
+  spec.email       = ["bascule@gmail.com"]
+  spec.licenses    = ["MIT"]
+  spec.homepage    = "https://github.com/celluloid/socketry/"
+  spec.summary     = "High-level wrappers for Ruby sockets with advanced thread-safe timeout support"
+  spec.description = <<-DESCRIPTION.strip.gsub(/\s+/, " ")
+    Socketry wraps Ruby's sockets with an advanced timeout engine which is able to provide multiple
+    simultaneous timeout behaviors in a thread-safe way.
+  DESCRIPTION
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.2.2"
+
+  spec.add_runtime_dependency "hitimes", ">= 1.2"
+
+  spec.add_development_dependency "bundler", "~> 1.0"
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: socketry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tony Arcieri
+- Zachary Anker
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-09-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hitimes
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Socketry wraps Ruby's sockets with an advanced timeout engine which is
+  able to provide multiple simultaneous timeout behaviors in a thread-safe way.
+email:
+- bascule@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGES.md
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/socketry.rb
+- lib/socketry/exceptions.rb
+- lib/socketry/resolver/resolv.rb
+- lib/socketry/resolver/system.rb
+- lib/socketry/ssl/server.rb
+- lib/socketry/ssl/socket.rb
+- lib/socketry/tcp/server.rb
+- lib/socketry/tcp/socket.rb
+- lib/socketry/timeout.rb
+- lib/socketry/udp/socket.rb
+- lib/socketry/version.rb
+- socketry.gemspec
+homepage: https://github.com/celluloid/socketry/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: High-level wrappers for Ruby sockets with advanced thread-safe timeout support
+test_files: []