krakow 0.2.2 → 0.3.0

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v0.3.0
+* Include jitter to discovery interval lookups
+* Typecast to String on PUB and MPUB
+* Update exception types used for not implemented methods
+* Add #confirm, #requeue, and #touch helpers to FrameType::Message instances
+* Update Utils::Lazy implementation to be faster and clearer
+* Add #safe_socket method on Connection to add stability
+* Rebuild connections on error to prevent consumer teardown
+* Reference connections without requirement of connection instance being alive
+* Use #read over #recv on underlying socket to ensure proper number of bytes (thanks @thomas-holmes)
+* Expand spec testing
+
+A big thanks to @bschwartz for a large contribution in this changeset
+including expanded spec coverage, message proxy helper methods, and
+isolation of instability around Connection interactions.
+
 ## v0.2.2
 * Fix `nsqlookupd` attribute in `Consumer` and `Discovery`
 

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Branches
+
+### `master` branch
+
+The master branch is the current stable released version.
+
+### `develop` branch
+
+The develop branch is the current edge of development.
+
+## Pull requests
+
+* https://github.com/chrisroberts/krakow/pulls
+
+Please base all pull requests of the `develop` branch. Merges to
+`master` only occur through the `develop` branch. Pull requests
+based on `master` will likely be cherry picked.
+
+## Issues
+
+Need to report an issue? Use the github issues:
+
+* https://github.com/chrisroberts/krakow/issues

data/LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2014 Chris Roberts
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -86,7 +86,8 @@ Krakow::Utils::Logging.level = :warn # :debug / :info / :warn / :error / :fatal
 
 ### Why is it forcing something called an "unready state"?
 
-Because forcing starvation is mean.
+Because forcing starvation is mean. We don't want to be mean, so we'll ensure we
+are consuming from all registered connections.
 
 ### I just want to connect to a producer, not a lookup service
 
@@ -133,8 +134,10 @@ consumer = Krakow::Consumer.new(
   :nsqlookupd => 'http://HOST:PORT',
   :topic => 'target',
   :channel => 'ship',
-  :connection_features => {
-    :tls_v1 => true
+  :connection_options => {
+    :features => {
+      :tls_v1 => true
+    }
   }
 )
 ```
@@ -148,8 +151,10 @@ consumer = Krakow::Consumer.new(
   :nsqlookupd => 'http://HOST:PORT',
   :topic => 'target',
   :channel => 'ship',
-  :connection_features => {
-    :snappy => true
+  :connection_options => {
+    :features => {
+      :snappy => true
+    }
   }
 )
 ```
@@ -163,23 +168,71 @@ consumer = Krakow::Consumer.new(
   :nsqlookupd => 'http://HOST:PORT',
   :topic => 'target',
   :channel => 'ship',
-  :connection_features => {
-    :deflate => true
+  :connection_options => {
+    :features => {
+      :deflate => true
+    }
   }
 )
 ```
 
+### I want to use TLS based authentication!
+
+OK!
+
+```ruby
+consumer = Krakow::Consumer.new(
+  :nsqlookupd => 'http://HOST:PORT',
+  :topic => 'target',
+  :channel => 'ship',
+  :connection_options => {
+    :features => {
+      :tls_v1 => true
+    },
+    :config => {
+      :ssl_context => {
+        :certificate => '/path/to/cert',
+        :key => '/path/to/key'
+      }
+    }
+  }
+)
+```
+
+### Running the tests
+
+Run them all!
+
+```
+bundle exec ruby test/run.rb
+```
+
+Or, run part of them:
+
+```
+bundle exec ruby test/specs/consumer_spec.rb
+```
+
 ### It doesn't work
 
-Create an issue on the github repository.
+Create an issue on the github repository
+* https://github.com/chrisroberts/krakow/issues
 
 ### It doesn't do `x`
 
-Create an issue, or even better, send a PR. Just base it off the `develop` branch.
+Create an issue, or even better, send a PR.
+* https://github.com/chrisroberts/krakow/pulls
 
 # Info
 * Repo: https://github.com/chrisroberts/krakow
+* Docs: http://code.chrisroberts.org/krakow
 * IRC: Freenode @ spox
 
 [1]: http://bitly.github.io/nsq/ "NSQ: a realtime distributed messaging platform"
 [2]: http://celluloid.io "Celluloid: Actor-based concurrent object framework for Ruby"
+
+# Contributors
+
+* Brendan Schwartz (@bschwartz)
+* Thomas Holmes (@thomas-holmes)
+* Jeremy Hinegardner (@copiousfreetime)

data/krakow.gemspec

@@ -8,11 +8,13 @@ Gem::Specification.new do |s|
   s.email = 'code@chrisroberts.org'
   s.homepage = 'http://github.com/chrisroberts/krakow'
   s.description = 'NSQ ruby library'
+  s.license = 'Apache 2.0'
   s.require_path = 'lib'
   s.add_dependency 'celluloid-io'
   s.add_dependency 'http'
   s.add_dependency 'multi_json'
   s.add_dependency 'snappy'
   s.add_dependency 'digest-crc'
-  s.files = Dir['**/*']
+  s.files = Dir['lib/**/*'] + %w(krakow.gemspec README.md CHANGELOG.md CONTRIBUTING.md LICENSE)
+  s.extra_rdoc_files = %w(CHANGELOG.md CONTRIBUTING.md LICENSE)
 end

data/lib/krakow/command/cls.rb

@@ -1,11 +1,10 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Close connection
     class Cls < Command
 
-      def initialize(args={})
-        super
-      end
-
       def to_line
         "#{name}\n"
       end

data/lib/krakow/command/fin.rb

@@ -1,11 +1,20 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Finish a message
     class Fin < Command
 
-      def initialize(args={})
-        super
-        required! :message_id
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :message_id, String, :required => true
+
+      # @!endgroup
 
       def to_line
         "#{name} #{message_id}\n"

data/lib/krakow/command/identify.rb

@@ -1,18 +1,31 @@
 require 'multi_json'
+require 'krakow'
 
 module Krakow
   class Command
+    # Update client metadata on server / negotiate features
     class Identify < Command
 
-      def initialize(args={})
-        super
-        required! :short_id, :long_id
-        optional(
-          :feature_negotiation, :heartbeat_interval, :output_buffer_size,
-          :output_buffer_timeout, :tls_v1, :snappy, :deflate, :deflate_level,
-          :sample_rate
-        )
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :short_id, [String, Numeric], :required => true
+      attribute :long_id, [String, Numeric], :required => true
+      attribute :feature_negotiation, [TrueClass, FalseClass]
+      attribute :heartbeat_interval, Numeric
+      attribute :output_buffer_size, Integer
+      attribute :output_buffer_timeout, Integer
+      attribute :tls_v1, [TrueClass, FalseClass]
+      attribute :snappy, [TrueClass, FalseClass]
+      attribute :deflate, [TrueClass, FalseClass]
+      attribute :deflate_level, Integer
+      attribute :sample_rate, Integer
+
+      # @!endgroup
 
       def to_line
         filtered = Hash[*

data/lib/krakow/command/mpub.rb

@@ -1,14 +1,24 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Publish multiple messages
     class Mpub < Command
 
-      def initialize(args={})
-        super
-        required! :topic_name, :messages
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :topic_name, String, :required => true
+      attribute :messages, Array, :required => true
 
+      # @!endgroup
       def to_line
         formatted_messages = messages.map do |message|
+          message = message.to_s
           [message.length, message].pack('l>a*')
         end.join
         [name, ' ', topic_name, "\n", formatted_messages.length, messages.size, formatted_messages].pack('a*a*a*a*l>l>a*')

data/lib/krakow/command/nop.rb

@@ -1,11 +1,10 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # No-op
     class Nop < Command
 
-      def initialize(args={})
-        super
-      end
-
       def to_line
         "#{name}\n"
       end

data/lib/krakow/command/pub.rb

@@ -1,15 +1,25 @@
+require 'krakow'
 
 module Krakow
   class Command
+    # Publish single message
     class Pub < Command
 
-      def initialize(args={})
-        super
-        required! :topic_name, :message
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :topic_name, String, :required => true
+      attribute :message, Object, :required => true
+
+      # @!endgroup
 
       def to_line
-        [name, ' ', topic_name, "\n", message.length, message].pack('a*a*a*a*l>a*')
+        msg = message.to_s
+        [name, ' ', topic_name, "\n", msg.length, msg].pack('a*a*a*a*l>a*')
       end
 
       class << self

data/lib/krakow/command/rdy.rb

@@ -1,11 +1,20 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Update RDY state
     class Rdy < Command
 
-      def initialize(args={})
-        super
-        required! :count
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :count, Integer, :required => true
+
+      # @!endgroup
 
       def to_line
         "#{name} #{count}\n"

data/lib/krakow/command/req.rb

@@ -1,11 +1,21 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Re-queue a message
     class Req < Command
 
-      def initialize(args={})
-        super
-        required! :message_id, :timeout
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :message_id, String, :required => true
+      attribute :timeout, Integer, :required => true
+
+      # @!endgroup
 
       def to_line
         "#{name} #{message_id} #{self.timeout}\n"

data/lib/krakow/command/sub.rb

@@ -1,11 +1,21 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Subscribe to topic/channel
     class Sub < Command
 
-      def initialize(args={})
-        super
-        required! :topic_name, :channel_name
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :topic_name, String, :required => true
+      attribute :channel_name, String, :required => true
+
+      # @!endgroup
 
       def to_line
         "#{name} #{topic_name} #{channel_name}\n"

data/lib/krakow/command/touch.rb

@@ -1,11 +1,20 @@
+require 'krakow'
+
 module Krakow
   class Command
+    # Reset timeout for in-flight message
     class Touch < Command
 
-      def initialize(args={})
-        super
-        required! :message_id
-      end
+      # @!group Attributes
+
+      # @!macro [attach] attribute
+      #   @!method $1
+      #     @return [$2] the $1 $0
+      #   @!method $1?
+      #     @return [TrueClass, FalseClass] truthiness of the $1 $0
+      attribute :message_id, String, :required => true
+
+      # @!endgroup
 
       def to_line
         "#{name} #{message_id}\n"

data/lib/krakow/command.rb

@@ -1,20 +1,33 @@
+require 'krakow'
+
 module Krakow
+  # Messages for sending to remote server
   class Command
 
     include Utils::Lazy
+    # @!parse include Utils::Lazy::InstanceMethods
+    # @!parse extend Utils::Lazy::ClassMethods
 
     class << self
 
+      # Allowed OK return values
+      #
+      # @return [Array<String>]
       def ok
         []
       end
 
+      # Allowed ERROR return values
+      #
+      # @return [Array<String>]
       def error
         []
       end
 
-      # message:: Krakow::Message
-      # Returns type of response expected (:none, :error_only, :required)
+      # Response type expected
+      #
+      # @param message [Krakow::Message] message to check
+      # @return [Symbol] response expected (:none, :error_only, :required)
       def response_for(message)
         if(message.class.ok.empty?)
           if(message.class.error.empty?)
@@ -29,23 +42,32 @@ module Krakow
 
     end
 
+    # @return [Krakow::FrameType] response to command
     attr_accessor :response
 
-    # Return command name
+    # @return [String] name of command
     def name
       self.class.name.split('::').last.upcase
     end
 
     # Convert to line output
+    #
+    # @return [String] socket ready string
     def to_line(*args)
       raise NotImplementedError.new 'No line conversion method defined!'
     end
 
+    # Is response OK
+    #
+    # @return [TrueClass, FalseClass]
     def ok?(response)
       response = response.content if response.is_a?(FrameType)
       self.class.ok.include?(response)
     end
 
+    # Is response ERROR
+    #
+    # @return [TrueClass, FalseClass]
     def error?(response)
       response = response.content if response.is_a?(FrameType)
       self.class.error.include?(response)