socketry 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dae535663b1bc19486c7766d86d1444cf097fb81
-  data.tar.gz: 31212e71094435898cd1f2937bece83f9f863708
+  metadata.gz: 3035f86108ed663a3bae8c6ef3d50b09925e9628
+  data.tar.gz: f21df11ab03cbddfe484f6f73ec2c08e501d7d88
 SHA512:
-  metadata.gz: 5e4bedb944e9683e08e6027edc585c09383c9f962eec07375a70fff0aaac3fdeedf5020ec12beaa56213de0bb96d1b1a3d66fbd0cd5655544e22b96530f52836
-  data.tar.gz: b169b991a93b8667ad3f532889751e05aa5e25a98825452da04ddcbcfc5652a8fb01218f0a48212d111e02316f677156d72190ba64e6a74b0bfbe1325ed251b2
+  metadata.gz: a659f5c5b1be2398364efe1a0a088476d1ec85594c8986c88836baea15fe235d99d58e29b8e0a765de89691a843f35658757dab17586f490bb21adf7be80997d
+  data.tar.gz: 4e96517be39871436dcd8afe7bf22752a58f906fc1da5aef8e0edf3189987fe11905fb7cb6cd2f01332083e1146e4312280c41d51f9c4152bce24aa10ff6a6ac

data/.rspec

@@ -1,4 +1,3 @@
---backtrace
 --color
 --format=documentation
 --order random

data/CHANGES.md

@@ -1,3 +1,7 @@
+## 0.2.0 (2016-09-12)
+
+* Rename Socketry::TCP::Socket#connected? -> #closed?
+
 ## 0.1.0 (2016-09-11)
 
 * Initial release

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2015-2016 Tony Arcieri, Zachary Anker
+Copyright (c) 2016 Tony Arcieri
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -19,12 +19,29 @@ Socketry can also be used to provide asynchronous I/O with [Celluloid::IO].
 
 [Celluloid::IO]: https://github.com/celluloid/celluloid-io
 
+## Motivation
+
+By default, Ruby sockets do not provide a built-in timeout mechanism. The only
+timeout mechanism provided by the language leverages [timeout.rb], which uses
+[unsafe multithreaded behaviors] to implement timeouts.
+
+While Socketry provides a synchronous, blocking API similar to Ruby's own
+`TCPSocket` and `UDPSocket` classes, behind the scenes it uses non-blocking I/O
+to implement thread-safe timeouts.
+
+Highly modular and pluggable, Socketry also provides the flexibility to
+seamlessly leverage [Celluloid::IO] for event-driven I/O.
+
+[timeout.rb]: http://ruby-doc.org/stdlib-2.3.1/libdoc/timeout/rdoc/Timeout.html
+[unsafe multithreaded behaviors]: http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html
+[Celluloid::IO]: https://github.com/celluloid/celluloid-io
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'socketry'
+gem "socketry"
 ```
 
 And then execute:
@@ -35,9 +52,31 @@ Or install it yourself as:
 
     $ gem install socketry
 
-## Usage
+## Basic Usage
+
+Below is a basic example of how to use Socketry to make an HTTPS request:
+
+```ruby
+require "socketry"
+
+socket = Socketry::SSL::Socket.connect("github.com", 443)
+socket.writepartial("GET / HTTP/1.0\r\nHost: github.com\r\n\r\n")
+p socket.readpartial(1024)
+```
+
+[TCP], [UDP], and [SSL] servers and sockets also available.
 
-TODO: Coming soon!
+[TCP]: https://github.com/socketry/socketry/wiki/TCP
+[UDP]: https://github.com/socketry/socketry/wiki/UDP
+[SSL]: https://github.com/socketry/socketry/wiki/SSL
+
+## Documentation
+
+[Please see the Socketry wiki](https://github.com/socketry/socketry/wiki)
+for more detailed documentation and usage notes.
+
+[YARD API documentation](http://www.rubydoc.info/gems/socketry/)
+is also available.
 
 ## Contributing
 
@@ -48,8 +87,6 @@ TODO: Coming soon!
 
 ## License
 
-Copyright (c) 2016 Tony Arcieri
-
-Distributed under the MIT License. See
+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/lib/socketry/ssl/socket.rb

@@ -100,9 +100,15 @@ module Socketry
       # @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)
+      def read_nonblock(size, outbuf: nil)
         ensure_connected
-        @ssl_socket.read_nonblock(size, exception: false)
+        case outbuf
+        when String
+          @ssl_socket.read_nonblock(size, outbuf, exception: false)
+        when NilClass
+          @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

data/lib/socketry/tcp/socket.rb

@@ -243,14 +243,14 @@ module Socketry
       #
       # @return [true, false] true if the socket was open, false if closed
       def close
-        return false unless connected?
+        return false if closed?
         @socket.close
         true
       ensure
         @socket = nil
       end
 
-      # Is the socket currently connected?
+      # Is the socket closed?
       #
       # This method returns the local connection state. However, it's possible
       # the remote side has closed the connection, so it's not actually
@@ -258,20 +258,20 @@ module Socketry
       # 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
+      # @return [true, false] do we locally think the socket is closed?
+      def closed?
+        @socket.nil?
       end
 
       private
 
       def ensure_connected
-        return true if connected?
-        raise StateError, "not connected"
+        raise StateError, "not connected" if closed?
+        true
       end
 
       def ensure_disconnected
-        return true unless connected?
+        return true if closed?
         raise StateError, "already connected"
       end
     end

data/lib/socketry/version.rb

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

data/socketry.gemspec

@@ -6,10 +6,10 @@ require "socketry/version"
 Gem::Specification.new do |spec|
   spec.name        = "socketry"
   spec.version     = Socketry::VERSION
-  spec.authors     = ["Tony Arcieri", "Zachary Anker"]
+  spec.authors     = ["Tony Arcieri"]
   spec.email       = ["bascule@gmail.com"]
   spec.licenses    = ["MIT"]
-  spec.homepage    = "https://github.com/celluloid/socketry/"
+  spec.homepage    = "https://github.com/socketry/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

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: socketry
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tony Arcieri
-- Zachary Anker
 autorequire: 
 bindir: exe
 cert_chain: []
@@ -70,7 +69,7 @@ files:
 - lib/socketry/udp/socket.rb
 - lib/socketry/version.rb
 - socketry.gemspec
-homepage: https://github.com/celluloid/socketry/
+homepage: https://github.com/socketry/socketry/
 licenses:
 - MIT
 metadata: {}