hootenanny 0.0.1 → 0.1.0

data/lib/hootenanny/request.rb

@@ -0,0 +1,40 @@
+require 'active_support/inflector'
+require 'hootenanny/request/subscription'
+require 'hootenanny/request/publish_notification'
+
+module  Hootenanny
+class   Request
+  attr_accessor :type
+
+  ###
+  # Private: Builds a specific request object based on the options passed in.
+  #
+  # options - A Hash of options representing the request that will be built. The
+  #           only option that is required for _this_ method is :type, however
+  #           depending on the class that is to be built, it may require other
+  #           options.  See each class in turn for details.
+  #
+  #           :type - The type of request that should be built. Currently, valid
+  #                   opitons are:
+  #
+  #                   * :subscription
+  #
+  # Examples:
+  #
+  #   Hootenanny::Request.build(type:     :subscription,
+  #                             callback: 'http://example.com',)
+  #   # => <Hootenanny::Request::Subscription>
+  #
+  # Returns an indeterminate type of object based on the :type option
+  # Raises Hootenanny::Request::BuildError if there is a problem
+  #
+  def self.build(options = {})
+    type  = options.fetch(:type).to_s.camelize
+    klass = "Hootenanny::Request::#{type}".constantize
+
+    klass.build options
+  rescue KeyError => e
+    raise Hootenanny::Request::BuildError.wrap(e)
+  end
+end
+end

data/lib/hootenanny/request/publish_notification.rb

@@ -0,0 +1,94 @@
+require 'active_support/core_ext/array/wrap'
+require 'hootenanny/request'
+require 'hootenanny/publish_notification'
+
+module  Hootenanny
+class   Request
+class   PublishNotification < Hootenanny::Request
+
+  attr_reader :topics
+
+  def initialize(options = {})
+    self.topics = options.fetch(:topics)
+  rescue KeyError => e
+    raise Hootenanny::Request::BuildError.wrap(e)
+  end
+
+  ###
+  # Private: Builds a publication request object based on the options passed in.
+  #
+  # options - A Hash of options representing the publish notification request
+  #           that will be built.
+  #
+  #           :topics - A String or Array representing the topics which have
+  #                     been proposed to have been updated.
+  #
+  # Examples:
+  #
+  #   # When more than one topic is passed in
+  #
+  #   Hootenanny::Request::PublishNotification.build(topics: [
+  #                                                   'http://another.org',
+  #                                                   'http://other.com'
+  #                                                 ])
+  #   # => <Hootenanny::Request::PublishNotification topics: [
+  #                                                    'http://another.org',
+  #                                                    'http://other.com'
+  #                                                  ]>
+  #
+  #
+  #   # When only one topic is passed in
+  #
+  #   Hootenanny::Request::PublishNotification.build(topics: 'http://another.org')
+  #   # => <Hootenanny::Request::Publish topics: ['http://another.org']>
+  #
+  # Returns a Hootenanny::Request::PublishNotification
+  # Raises Hootenanny::Request::BuildError if there is a problem
+  #
+  def self.build(options = {})
+    options = normalize_build_options(options)
+    request = allocate
+
+    request.send(:initialize, options)
+
+    request
+  end
+
+  ###
+  # Private: Generates one ore more (one for each topic in the request) records
+  # of the publish notification to be consumed at a later time by the hub.  If
+  # the hub has already been notified of the content update, a second item is
+  # not created but rather the original one is retrieved and returned.
+  #
+  # Example:
+  #
+  #   Hootenanny::Request::PublishNotification.build(topics: 'http://another.org')
+  #
+  #   publish_notification_request.apply
+  #
+  #   # => <Hootenanny::PublishNotification topic: 'http://another.org'>
+  #
+  # Returns a Hootenanny::PublishNotification if the request is verified
+  # Raises Hootenanny::PublishNotificationError if there is a problem
+  #
+  def apply
+    topics.map do |topic|
+      Hootenanny::PublishNotification.notify(topic)
+    end
+  end
+
+  protected
+
+  attr_writer :topics
+
+  private
+
+  def self.normalize_build_options(options)
+    options[:topics] = options[:url]                if options[:url]
+    options[:topics] = Array.wrap(options[:topics]) if options[:topics]
+
+    options
+  end
+end
+end
+end

data/lib/hootenanny/request/subscription.rb

@@ -0,0 +1,153 @@
+require 'hootenanny/request'
+require 'hootenanny/subscription'
+require 'hootenanny/verification'
+
+module  Hootenanny
+class   Request
+class   Subscription < Hootenanny::Request
+
+  attr_reader :subscriber,
+              :topic,
+              :lease_duration,
+              :requester_token,
+              :digest_secret,
+              :verification_class
+
+  def initialize(options = {})
+    self.subscriber         = options.fetch(:subscriber)
+    self.topic              = options.fetch(:topic)
+    self.lease_duration     = options.fetch(:lease_duration)
+    self.requester_token    = options.fetch(:requester_token, nil)
+    self.digest_secret      = options.fetch(:secret, nil)
+    self.verification_class = options.fetch(:verification_class,
+                                            Hootenanny::Verification)
+  rescue KeyError => e
+    raise Hootenanny::Request::BuildError.wrap(e)
+  end
+
+  ###
+  # Private: Builds a subscription request object based on the options passed
+  # in.
+  #
+  # options - A Hash of options representing the subscription request that will
+  #           be built.
+  #
+  #           :subscriber      - A String or Ruby URI representing the URI which
+  #                              the topic updates will be sent to.
+  #           :topic           - A String or Ruby URI representing the URI which
+  #                              publish the activities for a given topic.
+  #           :requester_token - A String token sent from the requester which
+  #                              they can use to identify the request on their
+  #                              system (optional).
+  #           :digest_secret   - A String token of no more than 200 bytes which
+  #                              will be used during content distribution so
+  #                              that the subscriber can verify that the request
+  #                              is from the hub and not a undesired 3rd party
+  #                              (optional).
+  #           :lease_duration  - A Number representing the amount of time after
+  #                              the subscription is created during which time
+  #                              the subscription will be active. This is
+  #                              a _request_ and may be overridden (optional).
+  #
+  # Examples:
+  #
+  #   Hootenanny::Request::Subscription.build(callback:   'http://example.com',
+  #                                           topic:      'http://another.org')
+  #
+  #   # => <Hootenanny::Request::Subscription subscriber: 'http://example.com',
+  #                                           topic:      'http://another.org'>
+  #
+  # Returns a Hootenanny::Request::Subscription
+  # Raises Hootenanny::Request::BuildError if there is a problem
+  #
+  def self.build(options = {})
+    options = normalize_build_options(options)
+    request = allocate
+
+    request.send(:initialize, options)
+
+    request
+  end
+
+  ###
+  # Private: Applies the subscription that the request is asking for. It does
+  # this in an idempotent way.  If the subscription being requested already
+  # exists, it is not modified but is instead retrieved and returned.
+  #
+  # The request itself must be verified prior to the request being applied.  An
+  # unverifiable request will raise a Hootenanny::SubscriptionError.
+  #
+  # Example:
+  #
+  #   # If the request for the subscription is verified
+  #
+  #   subscription_request =  Hootenanny::Request::Subscription.build(
+  #                             callback: 'http://example.com',
+  #                             topic:    'http://another.org')
+  #
+  #   subscription_request.apply
+  #
+  #   # => <Hootenanny::Subscription subscriber: 'http://example.com',
+  #                                  topic:      'http://another.org'>
+  #
+  #
+  #
+  #   # If the request for the subscription is unverifiable
+  #
+  #   subscription_request =  Hootenanny::Request::Subscription.build(
+  #                             callback: 'http://iamahacker.com',
+  #                             topic:    'http://thisdoesnotexist.org')
+  #
+  #   subscription_request.apply
+  #
+  #   # => <Hootenanny::SubscriptionError>
+  #
+  # Returns a Hootenanny::Subscription if the request is verified
+  # Raises Hootenanny::SubscriptionError if there is a problem
+  #
+  def apply
+    raise Hootenanny::SubscriptionError.new('Request could not be verified.') unless verified?
+
+    Hootenanny::Subscription.subscribe( subscriber:     subscriber,
+                                        to:             topic,
+                                        lease_duration: lease_duration,
+                                        digest_secret:  digest_secret)
+  end
+
+  def verified?
+    verification.verified?
+  end
+
+  def verification
+    @verification ||= verification_class.new(
+                        url:             subscriber,
+                        mode:            :subscribe,
+                        topic:           topic,
+                        requester_token: requester_token,
+                      )
+  end
+
+  protected
+
+  attr_writer :subscriber,
+              :topic,
+              :lease_duration,
+              :requester_token,
+              :digest_secret,
+              :verification_class
+
+  private
+
+  def self.normalize_build_options(options)
+    options[:subscriber]     = options[:callback]      if options.has_key?(:callback)
+    options[:lease_duration] = options[:lease_seconds] if options.has_key?(:lease_seconds)
+
+    options[:lease_duration] = options[:lease_duration] ?
+                               options[:lease_duration].to_i :
+                               1_577_880_000 # 50 Year Duration = 60 * 60 * 24 * 365.25 * 50
+
+    options
+  end
+end
+end
+end

data/lib/hootenanny/subscription_delivery.rb

@@ -0,0 +1,47 @@
+require 'faraday'
+require 'digest'
+
+module  Hootenanny
+class   SubscriptionDelivery
+  def initialize(options = {})
+    self.subscriber_url = options.fetch(:subscriber)
+    self.digest_secret  = options.fetch(:digest_secret, nil)
+    self.feed           = options.fetch(:feed)
+  end
+
+  def self.deliver(options = {})
+    delivery = allocate
+    delivery.send(:initialize, options)
+
+    delivery.deliver
+  end
+
+  def deliver
+    self.response = Faraday.post subscriber_url.to_s do |request|
+      request.headers['Content-Type']    = feed.content_type
+      request.headers['X-Hub-Signature'] = "sha1=#{signature}" unless signature == ''
+      request.body                       = feed.to_s
+    end
+
+    self.successful = response.success?
+  end
+
+  def successful?
+    successful
+  end
+
+  def signature
+    return '' if digest_secret == '' or digest_secret.nil?
+
+    @signature ||= OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('SHA'), digest_secret, feed.to_s)
+  end
+
+  protected
+
+  attr_accessor :subscriber_url,
+                :digest_secret,
+                :feed,
+                :response,
+                :successful
+end
+end

data/lib/hootenanny/topic.rb

@@ -0,0 +1,38 @@
+require 'hootenanny/uri'
+
+module  Hootenanny
+class   Topic
+
+  attr_reader :url
+
+  def initialize(options = {})
+    self.url = Hootenanny::URI.parse(options.fetch(:url))
+  end
+
+  ###
+  # Private: Creates a topic from a String representing the URL of the topic
+  #
+  # url - A String representing the URL of the topic
+  #
+  # Examples:
+  #
+  #   Hootenanny::Topic.from_url('http://example.com')
+  #
+  # Returns a Hootenanny::Topic
+  # Raises a Hootenanny::URI::InvalidError if the URI cannot be parsed
+  # Raises a Hootenanny::URI::InvalidSchemeError if the URI is not either HTTP
+  #   or HTTPS
+  #
+  def self.from_url(url, options = {})
+    topic = allocate
+
+    topic.send(:initialize, options.merge(:url => url))
+
+    topic
+  end
+
+  protected
+
+  attr_writer :url
+end
+end

data/lib/hootenanny/topic_synchronizer.rb

@@ -0,0 +1,71 @@
+require 'hootenanny/configuration'
+
+module  Hootenanny
+class   TopicSynchronizer
+  def initialize(options = {})
+    self.subscriber_url        = options.fetch(:subscriber)
+    self.topic_url             = options.fetch(:topic)
+    self.digest_secret         = options.fetch(:digest_secret, nil)
+
+    self.local_feed_store      = options[:local_feed_store] ||
+                                 Hootenanny.config.default_local_feed_store
+    self.remote_feed_store     = options[:remote_feed_store] ||
+                                 Hootenanny.config.default_remote_feed_store
+    self.subscription_delivery = options[:subscription_delivery] ||
+                                 Hootenanny.config.default_subscription_delivery
+  end
+
+  def self.sync(options = {})
+    self.new(options).sync
+  end
+
+  def sync
+    return true if unsynchronized_feed.empty?
+
+    if subscription_delivery.deliver( feed:       unsynchronized_feed,
+                                      url:        topic_url,
+                                      subscriber: subscriber_url)
+
+      local_feed_store.store( feed:  remote_feed.to_digest_feed,
+                              url:   topic_url,
+                              type:  'digest',
+                              path:  subscriber_url.to_digest)
+    else
+      false
+    end
+  end
+
+  protected
+
+  attr_accessor :subscriber_url,
+                :topic_url,
+                :digest_secret,
+                :local_feed_store,
+                :remote_feed_store,
+                :subscription_delivery
+
+  private
+
+  def unsynchronized_feed
+    remote_feed - local_feed
+  end
+
+  def subscriber_url=(other)
+    @subscriber_url = Hootenanny::URI.parse(other)
+  end
+
+  def topic_url=(other)
+    @topic_url = Hootenanny::URI.parse(other)
+  end
+
+  def local_feed
+    local_feed_store.fetch(url:   topic_url,
+                           path:  subscriber_url.to_digest)
+  end
+
+  def remote_feed
+    remote_feed_store.fetch(url:   topic_url,
+                            path:  subscriber_url.to_digest)
+  end
+end
+end