attention 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b48770e4d6245a630343d966765eac85af863ea0
-  data.tar.gz: 2be0077411ce85b73a2cf2f4aac3438dad9b657d
+  metadata.gz: 7a3c5fb2f9ae19b5dcfb4eb7fff6d17dc33cdc4a
+  data.tar.gz: d7adfc321e1f26471f6f1f0d4099b06136ae92fe
 SHA512:
-  metadata.gz: 48bfb49370698125f8cddac048e6fb7416377c146e26ec17ade58dd2ec182ec1758459dd1a94432267c1734ccbe10df74ee000a9ea754645ca54ac3f88947977
-  data.tar.gz: 3707fda7d1a9d014db0f4314ff0c8dd02929d4dff7efb1662cc289a371496d4539b6bc0d4d951f643d1d9c782093822de906eb4f8679256e903069ba5fd296fc
+  metadata.gz: b53f4dde91d7de78f85e826d92dce285b79e8536e29af80df9b31f77befa88e54d6962bc8413225cdc510f2b62d7bcd3c89ae923d77176cc32dd6bb2685b7f48
+  data.tar.gz: 6beac8bb89eaf9b221b31f4cb220da1c125950462037c089110dafbb319e7a7cbd0239b04e27f70ca763ba345c7883ccd77882f017c031d7b3b9d30e3b33333e

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+.DS_Store
+

data/README.md

@@ -1,5 +1,10 @@
 # Attention
 
+[![Build Status](https://travis-ci.org/parrish/Attention.svg?branch=master)](https://travis-ci.org/parrish/Attention)
+[![Test Coverage](https://codeclimate.com/github/parrish/Attention/badges/coverage.svg)](https://codeclimate.com/github/parrish/Attention)
+[![Code Climate](https://codeclimate.com/github/parrish/Attention/badges/gpa.svg)](https://codeclimate.com/github/parrish/Attention)
+[![Gem Version](https://badge.fury.io/rb/attention.svg)](http://badge.fury.io/rb/attention)
+
 Redis-based server awareness for distributed applications
 
 ## Installation
@@ -20,7 +25,56 @@ Or install it yourself as:
 
 ## Usage
 
+Activate the instance:
+```ruby
+# Autodiscover the ip and exclude the port
+Attention.activate
+
+# Or specify them explicitly
+Attention.activate ip: '1.2.3.4', port: 9000
+```
+
+The current instance is accessible at:
+```ruby
+Attention.instance
+```
+
+Deactivate the instance:
+```ruby
+Attention.deactivate
+```
+
+Subscribe to instance availability changes:
+```ruby
+Attention.on_change do |change, instances|
+  # This block is asynchronously called on each change
+end
+```
+
+Or get the list of available instances:
+```ruby
+Attention.instances
+```
+
+## Configuration
+
+Options can be set on `Attention.options`
 
+```ruby
+Attention.options = {
+  namespace: 'attention',                # Redis key namespace
+  ttl: 60,                               # Instance heartbeat TTL in seconds
+  redis_url: 'redis://localhost:6379/0', # Redis connection string
+  pool_size: 5,                          # Size of the publishing Redis connection pool
+  timeout: 5                             # Redis connection timeout
+}
+```
+
+## Notes
+
+The top-level API provides a simple way to keep track of instance availability.  More complex schemes of communication could be implemented by using the [`Subscriber`](http://www.rubydoc.info/github/parrish/attention/master/Attention/Subscriber) and [`Publisher`](http://www.rubydoc.info/github/parrish/attention/master/Attention/Publisher) classes directly.
+
+Instances attempt to deactivate themselves when the program terminates(`at_exit`).  If the instance crashes in a dramatic fashion (or a `kill -9`), the instance will continue to be listed as available until the TTL (`Attention.options[:ttl]`) expires.
 
 ## Development
 
@@ -36,4 +90,3 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/parris
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/attention.gemspec

@@ -29,4 +29,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec-its', '~> 1.2'
   spec.add_development_dependency 'pry', '~> 0.10'
   spec.add_development_dependency 'guard-rspec', '~> 4.5'
+  spec.add_development_dependency 'yard'
 end

data/examples/awareness.rb

@@ -0,0 +1,11 @@
+require 'bundler/setup'
+require 'attention'
+
+# Listen to changes from other servers
+Attention.on_change do |change, instances|
+  p change, instances
+end
+
+Attention.activate port: ARGV[0]
+
+sleep

data/lib/attention/connection.rb

@@ -2,7 +2,11 @@ require 'redis'
 require 'redis-namespace'
 
 module Attention
+  # Provides a namespaced Redis connection
   module Connection
+    # Creates a Redis connection
+    # @return [Redis] A namespaced Redis connection with configuration
+    #   from Attention.options
     def self.new
       connection = Redis.new url: Attention.options[:redis_url],
           connect_timeout: Attention.options[:timeout],

data/lib/attention/instance.rb

@@ -3,31 +3,62 @@ require 'attention/publisher'
 require 'attention/timer'
 
 module Attention
+  # A publishable representation of the current server
+  # 
+  # When an instance is {#publish}ed, an event is sent in the format
+  #   {
+  #      'added' => {
+  #        'id' => '123',
+  #        'ip' => '127.0.0.1',
+  #        'port' => 9000
+  #      }
+  #   }
+  # 
+  # When an instance is {#unpublish}ed, an event is sent in the format
+  #   {
+  #      'removed' => {
+  #        'id' => '123',
+  #        'ip' => '127.0.0.1',
+  #        'port' => 9000
+  #      }
+  #   }
   class Instance
-    attr_reader :id, :publisher
+    attr_reader :id
 
+    # @!visibility private
+    attr_reader :publisher
+
+    # Creates an Instance
+    # @param ip [String] Optionally override the IP of the server
+    # @param port [Fixnum, Numeric] Optionally specify the port of the server
     def initialize(ip: nil, port: nil)
       @id = Attention.redis.call.incr('instances').to_s
       @ip = ip
       @port = port
-      @publisher = Publisher.new 'instance'
+      @publisher = Publisher.new
     end
 
+    # Publishes this server and starts the {#heartbeat}
     def publish
-      redis = Attention.redis.call
-      redis.setex "instance_#{ @id }", Attention.options[:ttl], JSON.dump(info)
-      publisher.publish added: info
+      publisher.publish('instance', added: info) do |redis|
+        redis.setex "instance_#{ @id }", Attention.options[:ttl], JSON.dump(info)
+      end
       heartbeat
     end
 
+    # Unpublishes this server and stops the {#heartbeat}
     def unpublish
       return unless @heartbeat
-      Attention.redis.call.del "instance_#{ @id }"
-      publisher.publish removed: info
+      publisher.publish('instance', removed: info) do |redis|
+        redis.del "instance_#{ @id }"
+      end
       @heartbeat.stop
       @heartbeat = nil
     end
 
+    # Published information about this instance
+    # @return [Hash<id: Fixnum, ip: String, port: Numeric>]
+    # @option @return [Fixnum] :id The instance id
     def info
       { id: @id, ip: ip }.tap do |h|
         h[:port] = @port if @port
@@ -36,16 +67,24 @@ module Attention
 
     private
 
+    # Uses a {Timer} to periodically tell Redis that this
+    # server is still online
+    # @!visibility public
+    # @api private
     def heartbeat
       @heartbeat ||= Timer.new(heartbeat_frequency) do
         Attention.redis.call.expire "instance_#{ @id }", Attention.options[:ttl]
       end
     end
 
+    # The frequency of the {#heartbeat} is based on Attention.options[:ttl]
+    # @!visibility public
+    # @api private
     def heartbeat_frequency
       [1, Attention.options[:ttl] - 5].max
     end
 
+    # Attempts to automatically discover the IP address of the server
     def ip
       return @ip if @ip
       address = Socket.ip_address_list.find &:ipv4_private?

data/lib/attention/publisher.rb

@@ -1,17 +1,19 @@
 module Attention
+  # Uses Redis pub/sub to publish events
   class Publisher
-    attr_reader :key
-
-    def initialize(key)
-      @key = key
-    end
-
-    def publish(value)
+    # Publishes the value to the channel
+    # @param channel [String] The channel to publish to
+    # @param value [Object] The value to publish
+    # @yield Allows an optional block to use the Redis connection
+    # @yieldparam redis [Redis] The Redis connection
+    def publish(channel, value)
       redis = Attention.redis.call
-      redis.publish key, payload_for(value)
+      redis.publish channel, payload_for(value)
       yield redis if block_given?
     end
 
+    # Converts published values to JSON if possible
+    # @api private
     def payload_for(value)
       case value
       when Array, Hash

data/lib/attention/redis_pool.rb

@@ -3,9 +3,12 @@ require 'redis-namespace'
 require 'connection_pool'
 
 module Attention
+  # A ConnectionPool of Redis connections used by {Publisher}s
   class RedisPool
+    # @!visibility private
     attr_reader :pool
 
+    # @return [RedisPool] A singleton instance of the ConnectionPool
     def self.instance
       @instance ||= new
       @pool ||= ->{ @instance.pool.with{ |redis| redis } }
@@ -13,6 +16,9 @@ module Attention
 
     private
 
+    # As this is a singleton, +RedisPool.new+ is not public
+    # @!visibility public
+    # @api private
     def initialize
       pool_config = {
         size: Attention.options[:pool_size],

data/lib/attention/subscriber.rb

@@ -4,39 +4,62 @@ require 'attention/connection'
 require 'attention/publisher'
 
 module Attention
+  # Uses Redis pub/sub to asynchronously respond to events
+  # 
+  # Each Subscriber uses a Redis connection to listen to a channel for events.
   class Subscriber
-    attr_reader :key, :redis
+    # The channel subscribed to
+    attr_reader :channel
 
+    # @!visibility private
+    attr_reader :redis
+
+    # Raised when attempting to subscribe multiple times
+    # 
+    # Rather than attempting to reuse a subscriber,
+    # unsubscribe and create a new one
     class AlreadySubscribedError < StandardError; end
 
-    def initialize(key, &callback)
-      @key = key
+    # Creates a subscription to the given channel
+    # @param channel [String] The channel to listen to
+    # @yield The code to execute on a published event
+    # @yieldparam channel [String] The channel the subscriber is listening to
+    # @yieldparam data [Object] The event published on the channel
+    def initialize(channel, &callback)
+      @channel = channel
       @redis = Connection.new
       subscribe &callback
     end
 
+    # Sets up the Redis pub/sub subscription
+    # @yield The code to execute on a published event
+    # @raise [AlreadySubscribedError] If the subscriber is already subscribed
     def subscribe(&callback)
       raise AlreadySubscribedError.new if @thread
       @thread = Thread.new do
-        redis.subscribe(key) do |on|
+        redis.subscribe(channel) do |on|
           on.message do |channel, payload|
             data = JSON.parse(payload) rescue payload
             if data == 'unsubscribe'
               redis.unsubscribe
             else
-              callback.call key, data
+              callback.call channel, data
             end
           end
         end
       end
     end
 
+    # The {Publisher} used to send the unsubscribe message
+    # @api private
     def publisher
-      @publisher ||= Publisher.new(key)
+      @publisher ||= Publisher.new
     end
 
+    # Unsubscribes from the channel
     def unsubscribe
-      publisher.publish 'unsubscribe'
+      publisher.publish channel, 'unsubscribe'
+      @thread.kill
       @thread = nil
     end
   end

data/lib/attention/timer.rb

@@ -1,9 +1,16 @@
 require 'thread'
 
 module Attention
+  # Periodic asynchronous code execution
   class Timer
-    attr_reader :frequency, :callback, :lock, :thread
+    attr_reader :frequency
 
+    # @!visibility private
+    attr_reader :callback, :lock, :thread
+
+    # Creates and {#start}s the timer
+    # @param frequency [Numeric] How often to execute
+    # @yield The code to be executed
     def initialize(frequency, &callback)
       @frequency = frequency
       @callback = callback
@@ -11,6 +18,7 @@ module Attention
       start
     end
 
+    # Starts the timer
     def start
       @thread ||= Thread.new do
         loop do
@@ -22,10 +30,12 @@ module Attention
       end
     end
 
+    # @return [Boolean] True if the timer is started
     def started?
       !!thread
     end
 
+    # Stops the timer if it's started
     def stop
       return if stopped?
       lock.synchronize do
@@ -34,6 +44,7 @@ module Attention
       end
     end
 
+    # @return [Boolean] True if the timer is stopped
     def stopped?
       !started?
     end

data/lib/attention/version.rb

@@ -1,3 +1,3 @@
 module Attention
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

data/lib/attention.rb

@@ -5,48 +5,85 @@ require 'attention/subscriber'
 require 'attention/instance'
 require 'attention/timer'
 
+# The top-level API
+# 
+# Default options:
+#   {
+#     namespace: 'attention',                # Redis key namespace
+#     ttl: 60,                               # Instance heartbeat TTL in seconds
+#     redis_url: 'redis://localhost:6379/0', # Redis connection string
+#     pool_size: 5,                          # Size of the publishing Redis pool
+#     timeout: 5                             # Redis connection timeout
+#   }
 module Attention
   class << self
+    # Configuration options
     attr_accessor :options
+
+    # The server {Instance}
     attr_reader :instance
   end
 
   self.options = {
     namespace: 'attention',                # Redis key namespace
-    ttl: 60,                               # Heartbeat TTL in seconds
+    ttl: 60,                               # Instance heartbeat TTL in seconds
     redis_url: 'redis://localhost:6379/0', # Redis connection string
     pool_size: 5,                          # Size of the publishing Redis pool
     timeout: 5                             # Redis connection timeout
   }
 
+  # Provides access to the {RedisPool} connections
+  # @return [Redis] A Redis connection
   def self.redis
     RedisPool.instance
   end
 
+  # Publishes this server {Instance}
+  # @param ip [String] Optionally override the IP of the server
+  # @param port [Fixnum, Numeric] Optionally specify the port of the server
+  # @see Instance#publish
   def self.activate(ip: nil, port: nil)
     return if @instance
     @instance = Instance.new ip: ip, port: port
     instance.publish
   end
 
+  # Unpublishes this server {Instance}
+  # @see Instance#unpublish
   def self.deactivate
     @instance.unpublish if @instance
   end
 
+  # Uses a {Subscriber} to listen to changes to {Instance} statuses
+  # @yield The callback triggered on {Instance} changes
+  # @yieldparam change [Hash] The change event
+  # @yieldparam instances [Array<Hash>] The list of active {Instance}s
+  # @see Instance Format of the change events
+  # @see .instances Format of the instance information
   def self.on_change(&callback)
     Subscriber.new('instance') do |channel, change|
       callback.call change, instances
     end
   end
 
+  # A list of the active {Instance}s
+  # @return [Array<Hash>]
+  #  [
+  #    { 'id' => '1', 'ip' => '127.0.0.1', 'port' => 3000 },
+  #    { 'id' => '2', 'ip' => '127.0.0.1', 'port' => 3001 }
+  #  ]
   def self.instances
     resolve info_for instance_keys
   end
 
+  # Finds instance keys
+  # @!visibility private
   def self.instance_keys
     redis.call.keys 'instance_*'
   end
 
+  # Maps the Redis key +get+s into a multi operation
+  # @!visibility private
   def self.info_for(keys)
     [].tap do |list|
       redis.call.multi do |multi|
@@ -57,11 +94,14 @@ module Attention
     end
   end
 
+  # Resolves the list of future values from the multi operation
+  # @!visibility private
   def self.resolve(list)
     list.map do |future|
       JSON.parse future.value
     end
   end
 
+  # Attempt to remove this instance when the server shuts down
   at_exit{ deactivate }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: attention
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Michael Parrish
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-29 00:00:00.000000000 Z
+date: 2015-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -136,6 +136,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.5'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Redis-based server awareness for distributed applications
 email:
 - michael@zooniverse.org
@@ -155,6 +169,7 @@ files:
 - attention.gemspec
 - bin/console
 - bin/setup
+- examples/awareness.rb
 - lib/attention.rb
 - lib/attention/connection.rb
 - lib/attention/instance.rb
@@ -188,3 +203,4 @@ signing_key:
 specification_version: 4
 summary: Redis-based server awareness
 test_files: []
+has_rdoc: