orchestrate 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f337f0bb6cd0bea6f396f5f2cf1ac238325a5704
-  data.tar.gz: 5487fd1bf34564e6cc78eaad68a7d6a68d13184f
+  metadata.gz: 260fdf369f126768067a8bae1f0dd3671a5a9779
+  data.tar.gz: ee9677aa33a74fd362a538084ff05e98188afb89
 SHA512:
-  metadata.gz: ba3609ecc24d1c0d1f5d919d6450769efe77e737eee5d785c888b6b31139c1d2d3b7baab54fe7ff188083c226bf8d243280a9786cf39a8b5b416a636aa258707
-  data.tar.gz: 32f3f69256d28a0733d9475adeb5adfb231c4f8e44a91e49cbbf1335b66397cfb8f106e6626df1e6d169d7ac8c02ee4db797250a36919de56b572af8cde45d47
+  metadata.gz: 621a858872aaf62e4ed91ed6cf32313a014cf52f1300886220b5976acffec67d65afa99c76ba18b03b084e25d419f83b91bcc2dd07553b4084a67d1119f431e6
+  data.tar.gz: 2c086b71f2be610e25c99d8893bcfbe068ecf0e5afd82429aa0b9d4716a5a8963a7e806ada86d581fc03087d7f48b933d9fabef778dd48b88724cd550105a818

data/README.md

@@ -159,6 +159,10 @@ end
 
 ## Release Notes
 
+### September 1, 2014: release 0.9.0
+  - Implement `KeyValue#events`, `EventList` and `Events` to access events associated with a KeyValue.
+  - Removed `KeyValue#loaded` attr reader, it pointed to an instance variable no longer in use.  Use `#loaded?` instead.
+
 ### August 6, 2014: release 0.8.1
   - Implement `KeyValue#refs`, `RefList` and `Ref` to access a KeyValue's Refs.
   - Refactor `Client` api accessors on Object client to internal `#perform` methods.

data/lib/orchestrate.rb

@@ -4,6 +4,8 @@ require "orchestrate/application"
 require "orchestrate/collection"
 require "orchestrate/key_value"
 require "orchestrate/refs"
+require "orchestrate/event"
+require "orchestrate/event_source"
 require "orchestrate/graph"
 require "orchestrate/version"
 #

data/lib/orchestrate/event.rb

@@ -0,0 +1,232 @@
+require 'uri'
+module Orchestrate
+
+  # Events are a way to associate Time-ordered data with a key.
+  class Event
+
+    # Instantiates an Event from a value and response without a body.
+    # @param stem [Orchestrate::EventType] The associated EventType.
+    # @param value [Hash] The value for the event.
+    # @param response [API::Response] The associated response for creating the event.
+    # @return [Event]
+    def self.from_bodyless_response(stem, value, response)
+      event = new(stem, response)
+      event.value = value
+      event
+    end
+
+    # Instantiates an Event from a value in a listing and an associated response.
+    # @param stem [Orchestrate::EventType] The associated EventType
+    # @param listing [Hash] The entry in the LIST result
+    # @param response [API::Response] The associated response for the list query.
+    # @return [Event]
+    def self.from_listing(stem, listing, response=nil)
+      event = new(stem)
+      event.value = listing['value']
+      event.instance_variable_set(:@timestamp, listing['timestamp'])
+      event.instance_variable_set(:@ordinal, listing['ordinal'])
+      event.instance_variable_set(:@ref, listing['path']['ref'])
+      event.instance_variable_set(:@last_request_time, response.request_time) if response
+      event
+    end
+
+    # @return [Orchestrate::EventType] The associated EventType.
+    attr_reader :type
+
+    # @return [String] The associated name of the event type.
+    attr_reader :type_name
+
+    # @return [Orchestrate::KeyValue] The assoicated KeyValue item.
+    attr_reader :key
+
+    # @return [String] The key of the associated item.
+    attr_reader :key_name
+
+    # @return [String] The immutable ref for the current value of this event.
+    attr_reader :ref
+
+    # @return [Integer] The timestamp of the event, in number of milliseconds since epoch.
+    # @see #time
+    attr_reader :timestamp
+
+    # @return [Integer] The ordinal of the event.
+    attr_reader :ordinal
+
+    # @return [Time] The time which the event was loaded.
+    attr_reader :last_request_time
+
+    # @return [Hash] The value for the event.
+    attr_accessor :value
+
+    # Instantiates a new Event item.  You generally don't want to call this
+    # yourself, but use accessor methods from the KeyValue and EventType.
+    # @param stem [Orchestrate::EventType] The associated EventType.
+    # @param response [nil, Orchestrate::API::Response]
+    #   If an API::Response, used to load attributes and value.
+    # @return Orchestrate::Event
+    def initialize(stem, response=nil)
+      @type = stem
+      @type_name = type.type
+      @key = stem.kv_item
+      @key_name = key.key
+      @value = nil
+      load_from_response(response) if response
+    end
+
+    # Equivalent to `String#==`.  Compares by KeyValue, Type, Timestamp and Ordinal.
+    # @param other [Orchestrate::Event] the Event to compare against.
+    # @return [true, false]
+    def ==(other)
+      other.kind_of?(Orchestrate::Event) && \
+        other.type == type && \
+        other.timestamp == timestamp && \
+        other.ordinal == ordinal
+    end
+    alias :eql? :==
+
+    # Equivalent to `String#<=>`.  Compares by KeyValue, Type, Timestamp and
+    # Ordinal.  Sorts newer timestamps before older timestamps.  If timestamps
+    # are equivalent, sorts by ordinal.  This behavior emulates the order which
+    # events are returned in a list events query from the Orchestrate API.
+    # @param other [Orchestrate::Event] the Event to compare against.
+    # @return [nil, -1, 0, 1]
+    def <=>(other)
+      return nil unless other.kind_of?(Orchestrate::Event)
+      return nil unless other.type == type
+      if other.timestamp == timestamp
+        other.ordinal <=> ordinal
+      else
+        other.timestamp > timestamp ? -1 : 1
+      end
+    end
+
+    # @return [String] A pretty-printed representation of the event.
+    def to_s
+      "#<Orchestrate::Event collection=#{key.collection_name} key=#{key_name} type=#{type_name} time=#{time} ordinal=#{ordinal} ref=#{ref} last_request_time=#{last_request_time}>"
+    end
+
+    # @group Attributes
+
+    # @return [String] The full path of the event.
+    def path
+      @path ||= "/#{key.path}/events/#{URI.escape(type_name)}/#{timestamp}/#{ordinal}"
+    end
+
+    # @return [Time] The timestamp of the event as a Time object.
+    def time
+      @time ||= Time.at(@timestamp / 1000.0)
+    end
+
+    # Accessor for a property on the event's value.
+    # @param attr_name [#to_s] the attribute name to retrieve.
+    # @return [nil, true, false, Numeric, String, Array, Hash] The value for the attribute.
+    def [](attr_name)
+      value[attr_name.to_s]
+    end
+
+    # Set an attribute on the event's value to a specified value.
+    # @param attr_name [#to_s] The name of the attribute.
+    # @param attr_val [#to_json] The new value for the attribute
+    # @return [attr_val]
+    def []=(attr_name, attr_val)
+      value[attr_name.to_s] = attr_val
+    end
+
+    # @endgroup
+    # @group Persistence
+
+    # Saves the Event item to Orchestrate using 'If-Match' with the current ref.
+    # Sets the new ref for this value to the ref attribute.
+    # Returns false on failure to save, and rescues from all Orchestrate::API errors.
+    # @return [true, false]
+    def save
+      begin
+        save!
+      rescue API::RequestError, API::ServiceError
+        false
+      end
+    end
+
+    # Saves the Event item to Orchestrate using 'If-Match' with the current ref.
+    # Sets the new ref for this value to the ref attribute.
+    # Raises an exception on failure to save.
+    # @return [true]
+    # @raise [Orchestrate::API::VersionMismatch] If the Event has been updated with a new value since this Event was loaded.
+    # @raise [Orchestrate::API::RequestError, Orchestrate::API::ServiceError] If there are any other problems with saving.
+    def save!
+      response = perform(:put_event, value, ref)
+      load_from_response(response)
+      true
+    end
+
+    # Merges a set of values into the event's existing value and saves.
+    # @param merge [#each_pair] The Hash-like to merge into #value.  Keys will be stringified.
+    # @return [true, false]
+    def update(merge)
+      begin
+        update!(merge)
+      rescue API::RequestError, API::ServiceError
+        false
+      end
+    end
+
+    # Merges a set of values into the event's existing value and saves.
+    # @param merge [#each_pair] The Hash-like to merge into #value.  Keys will be stringified.
+    # @return [true]
+    # @raise [Orchestrate::API::VersionMismatch] If the Event has been updated with a new value since this Event was loaded.
+    # @raise [Orchestrate::API::RequestError, Orchestrate::API::ServiceError] If there are any other problems with saving.
+    def update!(merge)
+      merge.each_pair {|key, value| @value[key.to_s] = value }
+      save!
+    end
+
+    # Deletes the event from Orchesrate using 'If-Match' with the current ref.
+    # Returns false if the event failed to delete because a new ref has been created since this Event was loaded.
+    # @return [true, false]
+    def purge
+      begin
+        purge!
+      rescue API::RequestError
+        false
+      end
+    end
+
+    # Deletes the event from Orchesrate using 'If-Match' with the current ref.
+    # @return [true]
+    # @raise [Orchestrate::API::VersionMismatch] If the Event has been updated with a new ref since this Event was loaded.
+    def purge!
+      response = perform(:purge_event, ref)
+      @ref = nil
+      @last_request_time = response.request_time
+      true
+    end
+
+    # @endgroup persistence
+
+    # Performs a request using the associated API client, with collection_name,
+    # key, event_type, timestamp, and ordinal pre-filled.
+    # @param api_method [Symbol] the method on API::Client to call.
+    # @param args [#to_s, #to_json, Hash] The remaining arguments for the method being called.
+    # @return [API::Request]
+    def perform(api_method, *args)
+      type.perform(api_method, timestamp, ordinal, *args)
+    end
+
+    private
+    def load_from_response(response)
+      response.on_complete do
+        @ref = response.ref if response.respond_to?(:ref)
+        if response.headers['Location']
+          loc = response.headers['Location'].split('/')
+          @timestamp = loc[6].to_i
+          @ordinal = loc[7].to_i
+        elsif response.body.kind_of?(Hash)
+          @value = response.body['value']
+          @timestamp = response.body['timestamp']
+          @ordinal = response.body['ordinal']
+        end
+        @last_request_time = response.request_time
+      end
+    end
+  end
+end

data/lib/orchestrate/event_source.rb

@@ -0,0 +1,330 @@
+module Orchestrate
+
+  # Manages Event Types for a KeyValue item.
+  class EventSource
+
+    # @return [Orchestrate::KeyValue] The KeyValue to which the sourced events belong.
+    attr_reader :kv_item
+
+    # Instantiages a new EventSource manager.
+    # @param kv_item [Orchestrate::KeyValue] The KeyValue item to which events belong.
+    def initialize(kv_item)
+      @kv_item = kv_item
+      @types = {}
+    end
+
+    # Accessor for event types.
+    # @param event_type [#to_s] The type key for the events.
+    # @return [EventType]
+    def [](event_type)
+      @types[event_type.to_s] ||= EventType.new(@kv_item, event_type)
+    end
+
+    # Equivalent to `String#==`.  Compares by kv_item.
+    # @param other [Orchestrate::EventSource] the EventSource to compare against.
+    # @return [true, false]
+    def ==(other)
+      other.kind_of?(Orchestrate::EventSource) && other.kv_item == kv_item
+    end
+    alias :eql? :==
+
+    # @return Pretty-Printed string representation
+    def to_s
+      "#<Orchestrate::EventSource key_value=#{kv_item}>"
+    end
+  end
+
+  # Manages events of a specific type that belong to a specific KeyValue item.
+  class EventType
+
+    # @return [Orchestrate::KeyValue] The KeyValue this EventType is managing events for.
+    attr_reader :kv_item
+
+    # @return [String] The name for the type of events this EventType manages.
+    attr_reader :type
+
+    # Instantiates a new EventType.
+    # @param kv_item [Orchestrate::KeyValue] The KeyValue this EventType manages events for.
+    # @param event_type [#to_s] The type of events this EventType manages.
+    def initialize(kv_item, event_type)
+      @kv_item = kv_item
+      @type = event_type.to_s
+    end
+
+    # Equivalent to `String#==`.  Compares by KeyValue and Type.
+    # @param other [Orchestrate::EventType] The EventType to compare against.
+    # @return [true, false]
+    def ==(other)
+      other.kind_of?(Orchestrate::EventType) && \
+        other.kv_item == kv_item && \
+        other.type == type
+    end
+    alias :eql? :==
+
+    # Equivalent to `String#<=>`.  Comapres by key_value and type.
+    # @param other [Orchestrate::EventType] The EventType to compare against.
+    # @return [nil, -1, 0, 1]
+    def <=>(other)
+      return nil unless other.kind_of?(Orchestrate::EventType)
+      return nil unless other.kv_item == kv_item
+      other.type <=> type
+    end
+
+    # @return A pretty-printed string representation of the EventType
+    def to_s
+      "#<Orchestrate::EventType key_value=#{kv_item} type=#{type}>"
+    end
+
+    # Calls a method on the KeyValue's Collection's API Client, providing the event type.
+    # @param api_method [Symbol] The method on the client to call.
+    # @param args [#to_s, #to_json, Hash] The remaining arguments for the specified method.
+    # @return [API::Response]
+    def perform(api_method, *args)
+      kv_item.perform(api_method, type, *args)
+    end
+
+    # Creates a new Event of the given type for the associated KeyValue.
+    # @param body [#to_json] The value for the event.
+    # @return [Orchestrate::Event] The event that was created.
+    def <<(body)
+      TimeSlice.new(self).push(body)
+    end
+    alias :push :<<
+
+    # Instantiates a new EventType::List with the given bounds.  Can be used to
+    # access single events or create events with a specific timestamp.
+    # @param bounds [#to_s, Time, Date, Integer, Hash] The bounds value for the List.
+    # @see EventType::List#initialize
+    # @example Accessing an existing event by timestamp/ordinal
+    #   kv.events[:checkins][timestamp][1]
+    # @example Creating an Event with a specified timestamp
+    #   kv.events[:checkins][Time.now - 3600] << {"place" => "home"}
+    # @example Listing events within a time range
+    #   kv.events[:checkins][{before: Time.now - 3600, after: Time.now - 24 * 3600}].to_a
+    #   # equivalent to:
+    #   # kv.events[:checkins].before(Time.now - 3600).after(Time.now - 24 * 3600).to_a
+    def [](bounds)
+      TimeSlice.new(self, bounds)
+    end
+
+    include Enumerable
+
+    # Iterates over events belonging to the KeyValue of the specified Type.
+    # Used as the basis for enumerable methods.  Events are provided in reverse
+    # chronological order by timestamp and ordinal value.
+    # @overlaod each
+    #   @return Enumerator
+    # @overload each(&block)
+    #   @yieldparam [Orchestrate::Event] event The Event item
+    def each(&block)
+      TimeSlice.new(self).each(&block)
+    end
+
+    # Creates a Lazy Enumerator for the EventList.  If called inside the app's
+    # `#in_parallel` block, will prefetch results.
+    # @return Enumerator::Lazy
+    def lazy
+      TimeSlice.new(self).lazy
+    end
+
+    # Returns the first n items.  Equivalent to Enumerable#take.  Sets the `limit`
+    # parameter on the query to Orchestrate, so we don't ask for more than is needed.
+    # @param count [Integer] The number of events to limit to.
+    # @return [Array]
+    def take(count)
+      TimeSlice.new(self).take(count)
+    end
+
+    # Sets the inclusive start boundary for enumeration over events.
+    # Overwrites any value given to #before.
+    # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The inclusive start of the event range.
+    # @return [EventType::TimeSlice]
+    def start(bound)
+      TimeSlice.new(self).start(bound)
+    end
+
+    # Sets the exclusive start boundary for enumeration over events.
+    # Overwrites any value given to #start
+    # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The exclusive start of the event range.
+    # @return [EventType::TimeSlice]
+    def after(bound)
+      TimeSlice.new(self).after(bound)
+    end
+
+    # Sets the exclusive end boundary for enumeration over events.
+    # Overwrites any value given to #end
+    # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The exclusive end of the event range.
+    # @return [EventType::TimeSlice]
+    def before(bound)
+      TimeSlice.new(self).before(bound)
+    end
+
+    # Sets the inclusive end boundary for enumeration over events.
+    # Overwrites any value given to #before
+    # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The inclusive end of the event range.
+    # @return [EventType::TimeSlice]
+    def end(bound)
+      TimeSlice.new(self).start(bound)
+    end
+
+    # Manages events in a specified duration of time.
+    class TimeSlice
+
+      # @return [EventType] The associated EventType
+      attr_reader :type
+
+      # @return [String] The associated event type name
+      attr_reader :type_name
+
+      # @return [KeyValue] The associated KeyValue
+      attr_reader :kv_item
+
+      # Instantiates a new TimeSlice
+      # @param type [EventType] The associated EventType
+      # @param bounds [nil, String, Integer, Time, Date, Hash] Boundaries for the Time
+      #   If `nil`, no boundaries are set.  Used to enumerate over all events.
+      #   If `String`, `Integer`, `Time`, `Date`, used as `:start` option, below.
+      #   If `Hash`, see options.
+      # @option bounds [nil, String, Integer, Time, Date] :start Used as the 'startEvent' key.
+      # @option bounds [nil, String, Integer, Time, Date] :after Used as the 'afterEvent' key.
+      # @option bounds [nil, String, Integer, Time, Date] :before Used as the 'beforeEvent' key.
+      # @option bounds [nil, String, Integer, Time, Date] :end Used as the 'endEvent' key.
+      # @option bounds [Integer] :limit (100) The number of results to return.
+      def initialize(type, bounds=nil)
+        @type = type
+        @type_name = type.type
+        @kv_item = type.kv_item
+        if bounds.kind_of?(Hash)
+          @bounds = bounds
+        else
+          @bounds = {}
+          @bounds[:start] = bounds if bounds
+        end
+        @bounds[:limit] ||= 100
+      end
+
+      # Calls a method on the associated API Client, with collection, key and
+      # event_type being provided by EventType.
+      # @param api_method [Symbol] The method to call
+      # @param args [#to_s, #to_json, Hash] The arguments for the method being called.
+      # @return [API::Response]
+      def perform(api_method, *args)
+        type.perform(api_method, *args)
+      end
+
+      # Creates a new Event of the given type for the associated KeyValue.
+      # @param body [#to_json] The value for the event.
+      # @return [Orchestrate::Event] The event that was created.
+      def <<(body)
+        response = perform(:post_event, body, @bounds[:start])
+        Event.from_bodyless_response(type, body, response)
+      end
+      alias :push :<<
+
+      # Retrieves a single ID by timestamp and ordinal.  Uses the timestamp
+      # value from the associated bounds, by `start`, `before`, `after`, or
+      # `end` in that order.
+      # @param ordinal [Integer, #to_s] The ordinal value for the event to retrieve.
+      # @return [Orchestrate::Event]
+      def [](ordinal)
+        begin
+          timestamp = @bounds[:start] || @bounds[:before] || @bounds[:after] || @bounds[:end]
+          response = perform(:get_event, timestamp, ordinal)
+          Event.new(type, response)
+        rescue API::NotFound
+          nil
+        end
+      end
+
+      include Enumerable
+
+      # Iterates over events belonging to the KeyValue of the specified Type
+      # within the given bounds.  Used as the basis for enumerable methods.
+      # Events are provided in reverse chronological order by timestamp and
+      # ordinal value.
+      # @overlaod each
+      #   @return Enumerator
+      # @overload each(&block)
+      #   @yieldparam [Orchestrate::Event] event The Event item
+      def each(&block)
+        @response = perform(:list_events, @bounds)
+        return enum_for(:each) unless block_given?
+        raise ResultsNotReady.new if type.kv_item.collection.app.inside_parallel?
+        loop do
+          @response.results.each do |listing|
+            yield Event.from_listing(type, listing, @response)
+          end
+          break unless @response.next_link
+          @response = @response.next_results
+        end
+        @response = nil
+      end
+
+      # Creates a Lazy Enumerator for the EventList.  If called inside the app's
+      # `#in_parallel` block, will prefetch results.
+      # @return Enumerator::Lazy
+      def lazy
+        return each.lazy if type.kv_item.collection.app.inside_parallel?
+        super
+      end
+
+      # Returns the first n items.  Equivalent to Enumerable#take.  Sets the `limit`
+      # parameter on the query to Orchestrate, so we don't ask for more than is needed.
+      # @param count [Integer] The number of events to limit to.
+      # @return [Array]
+      def take(count)
+        count = 1 if count < 1
+        @bounds[:limit] = count > 100 ? 100 : count
+        super(count)
+      end
+
+      # Sets the inclusive start boundary for enumeration over events.
+      # Overwrites any value given to #before.
+      # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The inclusive start of the event range.
+      # @return [EventType::TimeSlice]
+      def start(bound)
+        @bounds[:start] = extract_bound_from(bound)
+        @bounds.delete(:after)
+        self
+      end
+
+      # Sets the exclusive start boundary for enumeration over events.
+      # Overwrites any value given to #start
+      # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The exclusive start of the event range.
+      # @return [EventType::TimeSlice]
+      def after(bound)
+        @bounds[:after] = extract_bound_from(bound)
+        @bounds.delete(:start)
+        self
+      end
+
+      # Sets the exclusive end boundary for enumeration over events.
+      # Overwrites any value given to #end
+      # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The exclusive end of the event range.
+      # @return [EventType::TimeSlice]
+      def before(bound)
+        @bounds[:before] = extract_bound_from(bound)
+        @bounds.delete(:end)
+        self
+      end
+
+      # Sets the inclusive end boundary for enumeration over events.
+      # Overwrites any value given to #before
+      # @param bound [Orchestrate::Event, Time, Date, Integer, #to_s] The inclusive end of the event range.
+      # @return [EventType::TimeSlice]
+      def end(bound)
+        @bounds[:end] = extract_bound_from(bound)
+        @bounds.delete(:before)
+        self
+      end
+
+      private
+      def extract_bound_from(bound)
+        if bound.kind_of?(Event)
+          "#{bound.timestamp}/#{bound.ordinal}"
+        else bound
+        end
+      end
+    end
+  end
+end

data/lib/orchestrate/graph.rb

@@ -35,6 +35,10 @@ module Orchestrate
         @type = type_name.to_s
       end
 
+      # Calls a method on the KeyValue's Collection's API Client, providing the relation type.
+      # @param api_method [Symbol] The method on the client to call.
+      # @param args [#to_s, #to_json, Hash] The remaining arguments for the specified method.
+      # @return [API::Response]
       def perform(api_method, *args)
         kv_item.perform(api_method, type, *args)
       end

data/lib/orchestrate/key_value.rb

@@ -1,3 +1,4 @@
+require 'uri'
 module Orchestrate
   # Key/Value pairs are pieces of data identified by a unique key for
   # a collection and have corresponding value.
@@ -58,6 +59,10 @@ module Orchestrate
     # @return [String]
     attr_reader :key
 
+    # The 'address' of this KeyValue item, representated as #[collection_name]/#[key]
+    # @return [String]
+    attr_reader :path
+
     # For comparison purposes only, the 'address' of this KeyValue item.
     # Represented as "[collection_name]/[key]"
     # @return [String]
@@ -75,10 +80,6 @@ module Orchestrate
     # @return [#to_json]
     attr_accessor :value
 
-    # Whether the KeyValue has been loaded from Orchestrate or not.
-    # @return boolean
-    attr_reader :loaded
-
     # When the KeyValue was last loaded from Orchestrate.
     # @return [Time]
     attr_reader :last_request_time
@@ -88,7 +89,7 @@ module Orchestrate
     # @param coll [Orchestrate::Collection] The collection to which this KeyValue belongs.
     # @param key_name [#to_s] The name of the key
     # @param associated_response [nil, Orchestrate::API::Response]
-    #   If an API::Request, used to load attributes and value.
+    #   If an API::Response, used to load attributes and value.
     # @return Orchestrate::KeyValue
     def initialize(coll, key_name, associated_response=nil)
       @collection = coll
@@ -96,6 +97,7 @@ module Orchestrate
       @app = coll.app
       @key = key_name.to_s
       @id = "#{collection_name}/#{key}"
+      @path = "#{URI.escape(collection_name)}/#{URI.escape(key)}"
       @value = {}
       @ref = false
       load_from_response(associated_response) if associated_response
@@ -285,6 +287,15 @@ module Orchestrate
     end
 
     # @!endgroup relations
+    # @!group events
+
+    # Entry point for managing events associated with this KeyValue item.
+    # @return [Orchestrate::EventSource]
+    def events
+      @events ||= EventSource.new(self)
+    end
+
+    # @!endgroup events
 
     # Calls a method on the Collection's Application's client, providing the
     # Collection's name and KeyValue's key.

data/lib/orchestrate/version.rb

@@ -1,4 +1,4 @@
 module Orchestrate
   # @return [String] The version number of the Orchestrate Gem
-  VERSION = "0.8.1"
+  VERSION = "0.9.0"
 end

data/test/orchestrate/api/event_test.rb

@@ -1,6 +1,6 @@
 require_relative '../../test_helper'
 
-class EventTest < MiniTest::Unit::TestCase
+class EventAPITest < MiniTest::Unit::TestCase
 
   def setup
     @collection = 'tests'

data/test/orchestrate/event_enumeration_test.rb

@@ -0,0 +1,165 @@
+require "test_helper"
+
+class EventEnumerationTest < MiniTest::Unit::TestCase
+  def setup
+    @app, @stubs = make_application({parallel: true})
+    @kv = make_kv_item(@app[:items], @stubs)
+    @type = :events
+    @limit = "100"
+    @called = false
+    @stubs.get("/v0/items/#{@kv.key}/events/#{@type}") do |env|
+      @called = true
+      assert_equal @limit, env.params['limit']
+      body = case env.params['beforeEvent']
+      when nil
+        events = 100.times.map{|i| make_event({ts: @start_time - i}) }
+        next_event = events.last.values_at("timestamp", "ordinal").join('/')
+        { "results" => events, "count" => 100,
+          "next" => "/v0/items/#{@kv.key}/events/#{@type}?beforeEvent=#{next_event}&limit=100" }
+      when "#{@start_time - 99}/1"
+        events = 10.times.map{|i| make_event({ts: @start_time - 100 - i})}
+        { "results" => events, "count" => 10 }
+      else
+        raise ArgumentError.new("unexpected beforeEvent: #{env.params['beforeEvent']}")
+      end
+      [200, response_headers, body.to_json]
+    end
+    @start_time = (Time.now.to_f * 1000).to_i
+  end
+
+  def make_event(opts={})
+    timestamp = opts[:ts] || @start_time
+    ordinal = opts[:ord] || 1
+    ref = opts[:ref] || make_ref
+    value = opts[:val] || { "msg" => "hello world" }
+    { "path" => { "collection" => @kv.collection_name, "key" => @kv.key, "type" => @type.to_s,
+                  "timestamp" => timestamp, "ordinal" => ordinal, "ref" => ref },
+      "value" => value,
+      "timestamp" => timestamp, "ordinal" => ordinal }
+  end
+
+  def test_enumerates_all_from_event_type
+    events = @kv.events[@type].to_a
+    assert_equal 110, events.length
+    events.each_with_index do |event, index|
+      assert_equal @kv, event.key
+      assert_equal @type.to_s, event.type_name
+      assert_equal @start_time - index, event.timestamp
+      assert_equal 1, event.ordinal
+      assert event.ref
+      assert event.value
+      assert_in_delta Time.now.to_f, event.last_request_time.to_f, 1.1
+    end
+  end
+
+  def test_enumerates_over_range_from_start_end
+    app, stubs = make_application
+    kv = make_kv_item(app[:items], stubs)
+    start_event = Orchestrate::Event.new(kv.events[@type])
+    start_event.instance_variable_set(:@timestamp, @start_time - 1000)
+    start_event.instance_variable_set(:@ordinal, 5)
+    end_event = @start_time
+    stubs.get("/v0/items/#{@kv.key}/events/#{@type}") do |env|
+      assert_equal "#{start_event.timestamp}/#{start_event.ordinal}", env.params['startEvent']
+      assert_equal "#{end_event}", env.params['endEvent']
+      [200, response_headers, {"count" => 0, "results" => []}.to_json]
+    end
+    response = kv.events[@type].start(start_event).end(end_event).to_a
+    assert_equal [], response
+  end
+
+  def test_enumerates_over_range_from_after_before
+    app, stubs = make_application
+    kv = make_kv_item(app[:items], stubs)
+    after_event = Orchestrate::Event.new(kv.events[@type])
+    after_event.instance_variable_set(:@timestamp, @start_time - 1000)
+    after_event.instance_variable_set(:@ordinal, 5)
+    before_event = Time.at(@start_time)
+    stubs.get("/v0/items/#{@kv.key}/events/#{@type}") do |env|
+      assert_equal "#{after_event.timestamp}/#{after_event.ordinal}", env.params['afterEvent']
+      assert_equal "#{(before_event.to_f * 1000).to_i}", env.params['beforeEvent']
+      [200, response_headers, {"count" => 0, "results" => []}.to_json]
+    end
+    response = kv.events[@type].before(before_event).after(after_event).to_a
+    assert_equal [], response
+  end
+
+  def test_enumerator_sets_limit_from_limit
+    @limit = "5"
+    events = @kv.events[@type].take(5)
+    assert_equal 5, events.length
+  end
+
+  def test_enumerator_in_parallel_raises_not_ready_if_forced
+    assert_raises Orchestrate::ResultsNotReady do
+      @app.in_parallel { @kv.events[@type].to_a }
+    end
+  end
+
+  def test_enumerator_in_parallel_prefetches_lazy_enums
+    return unless [].respond_to?(:lazy)
+    events = nil
+    @app.in_parallel { events = @kv.events[@type].lazy.map{|e| e } }
+    assert @called, "lazy enumerator wasn't prefetched inside of parallel"
+    events = events.force
+    assert_equal 110, events.to_a.size
+    events.each_with_index do |event, index|
+      assert_equal @kv, event.key
+      assert_equal @type.to_s, event.type_name
+      assert_equal @start_time - index, event.timestamp
+      assert_equal 1, event.ordinal
+      assert event.ref
+      assert event.value
+      assert_in_delta Time.now.to_f, event.last_request_time.to_f, 1.1
+    end
+  end
+
+  def test_enumerator_in_parallel_prefetches_enums
+    events = nil
+    @app.in_parallel { events = @kv.events[@type].each }
+    assert @called, "enumerator wasn't prefetched inside of parallel"
+    assert_equal 110, events.to_a.size
+    events.each_with_index do |event, index|
+      assert_equal @kv, event.key
+      assert_equal @type.to_s, event.type_name
+      assert_equal @start_time - index, event.timestamp
+      assert_equal 1, event.ordinal
+      assert event.ref
+      assert event.value
+      assert_in_delta Time.now.to_f, event.last_request_time.to_f, 1.1
+    end
+  end
+
+  def test_enumerator_doesnt_prefetch_lazy_enums
+    return unless [].respond_to?(:lazy)
+    events = @kv.events[@type].lazy.map{|e| e }
+    refute @called, "lazy enumerator was prefetched"
+    events = events.force
+    assert_equal 110, events.to_a.size
+    events.each_with_index do |event, index|
+      assert_equal @kv, event.key
+      assert_equal @type.to_s, event.type_name
+      assert_equal @start_time - index, event.timestamp
+      assert_equal 1, event.ordinal
+      assert event.ref
+      assert event.value
+      assert_in_delta Time.now.to_f, event.last_request_time.to_f, 1.1
+    end
+  end
+
+  def test_enumerator_prefetches_enums
+    events = @kv.events[@type].each
+    assert @called, "enumerator wasn't prefetched"
+    assert_equal 110, events.to_a.size
+    events.each_with_index do |event, index|
+      assert_equal @kv, event.key
+      assert_equal @type.to_s, event.type_name
+      assert_equal @start_time - index, event.timestamp
+      assert_equal 1, event.ordinal
+      assert event.ref
+      assert event.value
+      assert_in_delta Time.now.to_f, event.last_request_time.to_f, 1.1
+    end
+  end
+
+end

data/test/orchestrate/event_test.rb

@@ -0,0 +1,266 @@
+require "test_helper"
+
+class EventTest < MiniTest::Unit::TestCase
+
+  def setup
+    @app, @stubs = make_application
+    @kv = make_kv_item(@app[:items], @stubs)
+    @body = {"place" => 'Home'}
+    @time = Time.now
+    @timestamp = (@time.to_f * 1000).to_i
+    @ord = 6
+    @type = 'checkins'
+    @ref = nil
+  end
+
+  def make_event
+    @stubs.get("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do
+      @ref = make_ref
+      body = {value: @body, timestamp: @timestamp, ordinal: @ord}
+      [200, response_headers({"Etag" => %|"#{@ref}"|}), body.to_json]
+    end
+    @kv.events[@type][@timestamp][@ord]
+  end
+
+  def assert_event_data(event)
+    assert_kind_of Orchestrate::Event, event
+    assert_equal @kv.key, event.key_name
+    assert_equal @kv, event.key
+    assert_equal @type, event.type_name
+    assert_equal @kv.events[:checkins], event.type
+    assert_equal @ref, event.ref
+    assert_kind_of Time, event.time
+    assert_in_delta @time.to_f, event.time.to_f, 1.1
+    assert_equal @timestamp, event.timestamp
+    assert_equal @ord, event.ordinal
+    assert_equal "/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}", event.path
+    assert_equal @body, event.value
+    @body.each do |key, value|
+      assert_equal value, event[key]
+    end
+    assert_in_delta Time.now.to_f, event.last_request_time.to_f, 1.1
+  end
+
+  def test_creates_event_without_timestamp
+    @stubs.post("/v0/items/#{@kv.key}/events/#{@type}") do |env|
+      assert_equal @body, JSON.parse(env.body)
+      loc = "/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}"
+      @ref = make_ref
+      [201, response_headers({"Location" => loc, "Etag" => %|"#{@ref}"|}), '']
+    end
+    event = @kv.events[:checkins] << @body
+    @stubs.verify_stubbed_calls
+    assert_event_data(event)
+  end
+
+  def test_creates_event_with_time
+    @stubs.post("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}") do |env|
+      assert_equal @body, JSON.parse(env.body)
+      loc = "/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}"
+      @ref = make_ref
+      [201, response_headers({"Location" => loc, "Etag" => %|"#{@ref}"|}), '']
+    end
+    event = @kv.events[:checkins][@time].push(@body)
+    @stubs.verify_stubbed_calls
+    assert_event_data(event)
+  end
+
+  def test_retrieves_single_event
+    @stubs.get("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      @ref = make_ref
+      body = {value: @body, timestamp: @timestamp, ordinal: @ord}
+      [200, response_headers({"Etag" => %|"#{@ref}-gzip"|}), body.to_json]
+    end
+    event = @kv.events[:checkins][@time][@ord]
+    assert_event_data(event)
+  end
+
+  def test_retrieves_single_event_returns_nil_on_not_found
+    @stubs.get("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      [404, response_headers, response_not_found('')]
+    end
+    assert_nil @kv.events[@type][@time][@ord]
+  end
+
+  def test_save_on_success_returns_true_and_updates
+    event = make_event
+    new_body = @body.merge({'foo' => 'bar'})
+    event[:foo] = "bar"
+    assert_equal new_body, event.value
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_equal new_body, JSON.parse(env.body)
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      @ref = make_ref
+      [ 204, response_headers({"Etag" => %|"#{@ref}"|}), '' ]
+    end
+    assert_equal true, event.save
+    assert_equal @ref, event.ref
+  end
+
+  def test_save_on_error_returns_false
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do
+      error_response(:version_mismatch)
+    end
+    event = make_event
+    assert_equal false, event.save
+  end
+
+  def test_save_bang_on_success_returns_true_and_updates
+    event = make_event
+    new_body = @body.merge({'foo' => 'bar'})
+    event[:foo] = "bar"
+    assert_equal new_body, event.value
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_equal new_body, JSON.parse(env.body)
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      @ref = make_ref
+      [ 204, response_headers({"Etag" => %|"#{@ref}"|}), '' ]
+    end
+    assert_equal true, event.save!
+    assert_equal @ref, event.ref
+  end
+
+  def test_save_bang_on_error_raises
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do
+      error_response(:version_mismatch)
+    end
+    event = make_event
+    assert_raises Orchestrate::API::VersionMismatch do
+      event.save!
+    end
+  end
+
+  def test_update_modifies_values_and_saves
+    event = make_event
+    update = {'foo' => 'bar'}
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_equal @body.update(update), JSON.parse(env.body)
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      @ref = make_ref
+      [ 204, response_headers({"Etag" => %|"#{@ref}"|}), '' ]
+    end
+    assert_equal true, event.update(update)
+    assert_equal @body.update(update), event.value
+    assert_equal @ref, event.ref
+  end
+
+  def test_update_modifies_values_and_returns_false_on_error
+    event = make_event
+    update = {'foo' => 'bar'}
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_equal @body.update(update), JSON.parse(env.body)
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      error_response(:version_mismatch)
+    end
+    assert_equal false, event.update(update)
+    assert_equal @body.update(update), event.value
+  end
+
+  def test_update_bang_modifies_values_and_saves
+    event = make_event
+    update = {'foo' => 'bar'}
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_equal @body.update(update), JSON.parse(env.body)
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      @ref = make_ref
+      [ 204, response_headers({"Etag" => %|"#{@ref}"|}), '' ]
+    end
+    assert_equal true, event.update!(update)
+    assert_equal @body.update(update), event.value
+    assert_equal @ref, event.ref
+  end
+
+  def test_update_bang_modifies_value_and_raises_on_error
+    event = make_event
+    update = {'foo' => 'bar'}
+    @stubs.put("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_equal @body.update(update), JSON.parse(env.body)
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      error_response(:version_mismatch)
+    end
+    assert_raises Orchestrate::API::VersionMismatch do
+      event.update!(update)
+    end
+    assert_equal @body.update(update), event.value
+  end
+
+  def test_purge_performs_delete_if_match_returns_true_on_success
+    event = make_event
+    @stubs.delete("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      [204, response_headers, '']
+    end
+    assert_equal true, event.purge
+    assert_nil event.ref
+  end
+
+  def test_purge_performs_delete_if_match_returns_false_on_error
+    event = make_event
+    @stubs.delete("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      error_response(:version_mismatch)
+    end
+    assert_equal false, event.purge
+    assert_equal @ref, event.ref
+  end
+
+  def test_purge_bang_performs_delete_if_match_raises_on_error
+    event = make_event
+    @stubs.delete("/v0/items/#{@kv.key}/events/#{@type}/#{@timestamp}/#{@ord}") do |env|
+      assert_header 'If-Match', %|"#{event.ref}"|, env
+      error_response(:version_mismatch)
+    end
+    assert_raises Orchestrate::API::VersionMismatch do
+      event.purge!
+    end
+    assert_equal @ref, event.ref
+  end
+
+  def test_equality_and_comparison
+    app, stubs = make_application
+    items = app[:items]
+
+    foo = Orchestrate::KeyValue.new(items, :foo)
+    bar = Orchestrate::KeyValue.new(items, :bar)
+    assert_equal foo.events, Orchestrate::KeyValue.new(items, :foo).events
+    assert foo.events.eql?(Orchestrate::KeyValue.new(items, :foo).events)
+    refute_equal foo.events, bar.events
+    refute foo.events.eql?(bar.events)
+
+    tweets = foo.events[:tweets]
+    assert_equal tweets, Orchestrate::KeyValue.new(items, :foo).events['tweets']
+    assert tweets.eql?(Orchestrate::KeyValue.new(items, :foo).events['tweets'])
+    refute_equal tweets, foo.events[:checkins]
+    refute tweets.eql?(foo.events[:checkins])
+    assert_equal(1, foo.events[:checkins] <=> tweets)
+    assert_equal(0, tweets <=> foo.events[:tweets])
+    assert_equal(-1, tweets <=> foo.events[:checkins])
+    refute_equal tweets, bar.events['tweets']
+    refute tweets.eql?(bar.events['tweets'])
+    assert_nil tweets <=> bar.events['tweets']
+
+    ts = (Time.now.to_f * 1000).floor
+    make_tweet_1 = lambda { Orchestrate::Event.from_listing(tweets, {"path" => {"ref" => make_ref}, "timestamp" => ts, "ordinal" => 10}) }
+    tweet1 = make_tweet_1.call
+    assert_equal tweet1, make_tweet_1.call
+    assert tweet1.eql?(make_tweet_1.call)
+    assert_equal 0, tweet1 <=> make_tweet_1.call
+
+    tweet2 = Orchestrate::Event.from_listing(tweets, {"path" => {"ref" => make_ref}, "timestamp" => ts, "ordinal" => 11})
+    refute_equal tweet1, tweet2
+    refute tweet1.eql?(tweet2)
+    assert_equal 1, tweet1 <=> tweet2
+    assert_equal(-1, tweet2 <=> tweet1)
+
+    tweet3 = Orchestrate::Event.from_listing(tweets, {"path" => {"ref" => make_ref}, "timestamp" => ts - 1, "ordinal" => 2})
+    assert_equal(1, tweet1 <=> tweet3)
+    assert_equal(-1, tweet3 <=> tweet1)
+    assert_equal(1, tweet2 <=> tweet3)
+    assert_equal(-1, tweet3 <=> tweet2)
+
+    checkin = Orchestrate::Event.from_listing(foo.events[:checkins], {"path" => {"ref" => make_ref}, "timestamp" => ts, "ordinal" => 40})
+    refute_equal tweet1, checkin
+    refute tweet1.eql?(checkin)
+    assert_nil tweet1 <=> checkin
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orchestrate
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Matthew Lyon
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-06 00:00:00.000000000 Z
+date: 2014-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -134,6 +134,8 @@ files:
 - lib/orchestrate/application.rb
 - lib/orchestrate/client.rb
 - lib/orchestrate/collection.rb
+- lib/orchestrate/event.rb
+- lib/orchestrate/event_source.rb
 - lib/orchestrate/graph.rb
 - lib/orchestrate/key_value.rb
 - lib/orchestrate/refs.rb
@@ -151,6 +153,8 @@ files:
 - test/orchestrate/collection_kv_accessors_test.rb
 - test/orchestrate/collection_searching_test.rb
 - test/orchestrate/collection_test.rb
+- test/orchestrate/event_enumeration_test.rb
+- test/orchestrate/event_test.rb
 - test/orchestrate/key_value_persistence_test.rb
 - test/orchestrate/key_value_test.rb
 - test/orchestrate/ref_test.rb
@@ -193,9 +197,10 @@ test_files:
 - test/orchestrate/collection_kv_accessors_test.rb
 - test/orchestrate/collection_searching_test.rb
 - test/orchestrate/collection_test.rb
+- test/orchestrate/event_enumeration_test.rb
+- test/orchestrate/event_test.rb
 - test/orchestrate/key_value_persistence_test.rb
 - test/orchestrate/key_value_test.rb
 - test/orchestrate/ref_test.rb
 - test/orchestrate/relations_test.rb
 - test/test_helper.rb
-has_rdoc: