elevate 0.5.0 → 0.6.0

data/lib/elevate/http/response.rb

@@ -1,22 +1,112 @@
 module Elevate
 module HTTP
-  class HTTPResponse
+  # Encapsulates a response received from a HTTP server.
+  #
+  # @api public
+  class Response
     def initialize
       @body = nil
       @headers = nil
       @status_code = nil
       @error = nil
+      @raw_body = nil
+      @url = nil
     end
 
+    # Appends a chunk of data to the body.
+    #
+    # @api private
     def append_data(data)
-      @body ||= NSMutableData.alloc.init
-      @body.appendData(data)
+      @raw_body ||= NSMutableData.alloc.init
+      @raw_body.appendData(data)
     end
 
-    attr_reader   :body
+    # Returns the body of the response.
+    #
+    # If the body is JSON-encoded, it will be decoded and returned.
+    #
+    # @return [NSData, Hash, Array, nil]
+    #   response body, if any. If the response is JSON-encoded, the decoded body.
+    #
+    # @api public
+    def body
+      @body ||= begin
+        if json?
+          NSJSONSerialization.JSONObjectWithData(@raw_body, options: 0, error: nil)
+        else
+          @raw_body
+        end
+      end
+    end
+
+    # Freezes this instance, making it immutable.
+    #
+    # @api private
+    def freeze
+      body
+
+      super
+    end
+
+    # Forwards unknown methods to +body+, enabling this object to behave like +body+.
+    #
+    # This only occurs if +body+ is a Ruby collection.
+    #
+    # @api public
+    def method_missing(m, *args, &block)
+      return super unless json?
+
+      body.send(m, *args, &block)
+    end
+
+    # Handles missing method queries, allowing +body+ masquerading.
+    #
+    # @api public
+    def respond_to_missing?(m, include_private = false)
+      return false unless json?
+
+      body.respond_to_missing?(m, include_private)
+    end
+
+    # Returns the HTTP headers
+    #
+    # @return [Hash]
+    #   returned headers
+    #
+    # @api public
     attr_accessor :headers
+
+    # Returns the HTTP status code
+    #
+    # @return [Integer]
+    #   status code of the response
+    #
+    # @api public
     attr_accessor :status_code
+
     attr_accessor :error
+
+    # Returns the raw body
+    #
+    # @return [NSData]
+    #   response body
+    #
+    # @api public
+    attr_reader   :raw_body
+
+    # Returns the URL
+    #
+    # @return [String]
+    #   URL of the response
+    #
+    # @api public
+    attr_accessor :url
+
+    private
+
+    def json?
+      headers && headers["Content-Type"] =~ %r{application/json}
+    end
   end
 end
 end

data/lib/elevate/http/uri.rb

@@ -1,6 +1,35 @@
 module Elevate
 module HTTP
   module URI
+    def self.encode_www_form(enum)
+      enum.map do |k,v|
+        if v.nil?
+          encode_www_form_component(k)
+        elsif v.respond_to?(:to_ary)
+          v.to_ary.map do |w|
+            str = encode_www_form_component(k)
+
+            if w.nil?
+              str
+            else
+              str + "=" + encode_www_form_component(w)
+            end
+          end.join('&')
+        else
+          encode_www_form_component(k) + "=" + encode_www_form_component(v)
+        end
+      end.join('&')
+    end
+
+    def self.encode_www_form_component(str)
+      # From AFNetworking :)
+      CFURLCreateStringByAddingPercentEscapes(nil,
+                                              str,
+                                              "[].",
+                                              ":/?&=;+!@\#$()~',*",
+                                              CFStringConvertNSStringEncodingToEncoding(NSUTF8StringEncoding))
+    end
+
     def self.encode_query(hash)
       return "" if hash.nil? || hash.empty?
 

data/lib/elevate/io_coordinator.rb

@@ -1,58 +1,114 @@
 module Elevate
+  # Implements task cancellation.
+  #
+  # Compliant I/O mechanisms (such as HTTP requests) register long-running
+  # operations with a well-known instance of this class. When a cancellation
+  # request is received from another thread, the long-running operation is
+  # cancelled.
   class IOCoordinator
+    # Retrieves the current IOCoordinator for this thread.
+    #
+    # @return [IOCoordinator,nil]
+    #   IOCoordinator previously installed to this thread
+    #
+    # @api public
     def self.for_thread
       Thread.current[:io_coordinator]
     end
 
+    # Initializes a new IOCoordinator with the default state.
+    #
+    # @api private
     def initialize
       @lock = NSLock.alloc.init
       @blocking_operation = nil
       @cancelled = false
+      @exception_class = nil
     end
 
-    def cancel
+    # Cancels the I/O operation (if any), raising an exception of type 
+    # +exception_class+ in the worker thread.
+    #
+    # If the thread is not currently blocked, then set a flag requesting cancellation.
+    #
+    # @return [void]
+    #
+    # @api private
+    def cancel(exception_class = CancelledError)
       blocking_operation = nil
 
-      @lock.lock()
+      @lock.lock
       @cancelled = true
+      @exception_class = exception_class
       blocking_operation = @blocking_operation
-      @lock.unlock()
+      @lock.unlock
 
       if blocking_operation
-        blocking_operation.cancel()
+        blocking_operation.cancel
       end
     end
 
+    # Returns the cancelled flag.
+    #
+    # @return [Boolean]
+    #   true if this coordinator has been +cancel+ed previously.
+    #
+    # @api private
     def cancelled?
       cancelled = nil
 
-      @lock.lock()
+      @lock.lock
       cancelled = @cancelled
-      @lock.unlock()
+      @lock.unlock
 
       cancelled
     end
 
+    # Installs this IOCoordinator to a well-known thread-local.
+    #
+    # @return [void]
+    #
+    # @api private
     def install
       Thread.current[:io_coordinator] = self
     end
 
+    # Marks the specified operation as one that will potentially block the
+    # worker thread for a significant amount of time.
+    #
+    # @param operation [#cancel]
+    #   operation responsible for blocking
+    #
+    # @return [void]
+    #
+    # @api public
     def signal_blocked(operation)
       check_for_cancellation
 
-      @lock.lock()
+      @lock.lock
       @blocking_operation = operation
-      @lock.unlock()
+      @lock.unlock
     end
 
+    # Signals that the specified operation has completed, and is no longer
+    # responsible for blocking the worker thread.
+    #
+    # @return [void]
+    #
+    # @api public
     def signal_unblocked(operation)
-      @lock.lock()
+      @lock.lock
       @blocking_operation = nil
-      @lock.unlock()
+      @lock.unlock
 
       check_for_cancellation
     end
 
+    # Removes the thread-local for the calling thread.
+    #
+    # @return [void]
+    #
+    # @api private
     def uninstall
       Thread.current[:io_coordinator] = nil
     end
@@ -60,10 +116,19 @@ module Elevate
     private
 
     def check_for_cancellation
-      raise CancelledError if cancelled?
+      raise @exception_class if cancelled?
     end
   end
 
+  # Raised when a task is cancelled.
+  #
+  # @api public
   class CancelledError < StandardError
   end
+
+  # Raised when a task's timeout expires
+  #
+  # @api public
+  class TimeoutError < CancelledError
+  end
 end

data/lib/elevate/operation.rb

@@ -1,9 +1,19 @@
 module Elevate
+  # Executes an Elevate task, firing callbacks along the way.
+  #
   class ElevateOperation < NSOperation
+    # Designated initializer.
+    #
+    # @return [ElevateOperation]
+    #   newly initialized instance
+    #
+    # @api private
     def initWithTarget(target, args:args)
-      if init()
+      if init
         @coordinator = IOCoordinator.new
         @context = TaskContext.new(args, &target)
+        @timeout_callback = nil
+        @timer = nil
         @update_callback = nil
         @finish_callback = nil
 
@@ -14,6 +24,13 @@ module Elevate
 
           Dispatch::Queue.main.sync do
             @context = nil
+
+            if @timer
+              @timer.invalidate
+              @timer = nil
+            end
+
+            @timeout_callback = nil
             @update_callback = nil
             @finish_callback = nil
           end
@@ -23,12 +40,23 @@ module Elevate
       self
     end
 
+    # Cancels the currently running task.
+    #
+    # @return [void]
+    #
+    # @api public
     def cancel
       @coordinator.cancel
 
       super
     end
 
+    # Returns information about this task.
+    #
+    # @return [String]
+    #   String suitable for debugging purposes.
+    #
+    # @api public
     def inspect
       details = []
       details << "<canceled>" if @coordinator.cancelled?
@@ -36,10 +64,20 @@ module Elevate
       "#<#{self.class.name}: #{details.join(" ")}>"
     end
 
+    # Logs debugging information in certain configurations.
+    #
+    # @return [void]
+    #
+    # @api private
     def log(line)
       puts line unless RUBYMOTION_ENV == "test"
     end
 
+    # Runs the specified task.
+    #
+    # @return [void]
+    #
+    # @api private
     def main
       log " START: #{inspect}"
 
@@ -54,6 +92,10 @@ module Elevate
 
       rescue Exception => e
         @exception = e
+
+        if e.is_a?(TimeoutError)
+          @timeout_callback.call if @timeout_callback
+        end
       end
 
       @coordinator.uninstall
@@ -61,13 +103,49 @@ module Elevate
       log "FINISH: #{inspect}"
     end
 
+    # Returns the exception that terminated this task, if any.
+    #
+    # If the task has not finished, returns nil.
+    #
+    # @return [Exception, nil]
+    #   exception that terminated the task
+    #
+    # @api public
     attr_reader :exception
+
+    # Returns the result of the task block.
+    #
+    # If the task has not finished, returns nil.
+    #
+    # @return [Object, nil]
+    #   result of the task block
+    #
+    # @api public
     attr_reader :result
 
+    # Sets the callback to be run upon completion of this task. Do not call
+    # this method after the task has started.
+    #
+    # @param callback [Elevate::Callback]
+    #   completion callback
+    #
+    # @return [void]
+    #
+    # @api private
     def on_finish=(callback)
       @finish_callback = callback
     end
 
+    # Sets the callback to be run when this task is queued.
+    #
+    # Do not call this method after the task has started.
+    #
+    # @param callback [Elevate::Callback]
+    #   callback to be invoked when queueing
+    #
+    # @return [void]
+    #
+    # @api private
     def on_start=(callback)
       start_callback = callback
       start_callback.retain
@@ -78,8 +156,63 @@ module Elevate
       end
     end
 
+    # Handles timeout expiration.
+    #
+    # @return [void]
+    #
+    # @api private
+    def on_timeout_elapsed(timer)
+      @coordinator.cancel(TimeoutError)
+    end
+
+    # Sets the timeout callback.
+    #
+    # @param callback [Elevate::Callback]
+    #   callback to run on timeout
+    #
+    # @return [void]
+    #
+    # @api private
+    def on_timeout=(callback)
+      @timeout_callback = callback
+    end
+
+    # Sets the update callback, which is invoked for any yield statements in the task.
+    #
+    # @param callback [Elevate::Callback]
+    # @return [void]
+    #
+    # @api private
     def on_update=(callback)
       @update_callback = callback
     end
+
+    # Sets the timeout interval for this task.
+    #
+    # The timeout starts when the task is queued, not when it is started.
+    #
+    # @param interval [Fixnum]
+    #   seconds to allow for task completion
+    #
+    # @return [void]
+    #
+    # @api private
+    def timeout=(interval)
+      @timer = NSTimer.scheduledTimerWithTimeInterval(interval,
+                                                      target: self,
+                                                      selector: :"on_timeout_elapsed:",
+                                                      userInfo: nil,
+                                                      repeats: false)
+    end
+
+    # Returns whether this task timed out.
+    #
+    # @return [Boolean]
+    #   true if this task was aborted due to a time out.
+    #
+    # @api public
+    def timed_out?
+      @exception.class == TimeoutError
+    end
   end
 end