elevate 0.5.0 → 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 960a321bb02005b2ff94c974ae37afbd9905b027
+  data.tar.gz: c5a04645e4e674e4d7285ab4c705a8b52c0561e2
+SHA512:
+  metadata.gz: f56b43560ddf1be5e5c1cd9cc940bf15cc44719442e5d28fb7ff7022958f67e699245ef4698e6f1ec34210f00ede2e7e57f01f07d9ec144ef8f3eab1d51af700
+  data.tar.gz: 64a8d83ae84ec87a4daf9f78c40f220b1763bc15a6d6370e3ff142b9619acf6e718571e033085a2675c175e031f0ddee2f1d962b40149e2c0c51a11e3410ab6f

data/.gitignore

@@ -6,3 +6,5 @@ resources/*.momd
 resources/*.storyboardc
 .rvmrc
 Gemfile.lock
+doc
+.yardoc

data/README.md

@@ -3,20 +3,19 @@ Elevate
 
 Stop scattering your domain logic across your view controller. Consolidate it to a single conceptual unit with Elevate.
 
-[![Code Climate](https://codeclimate.com/github/mattgreen/elevate.png)](https://codeclimate.com/github/mattgreen/elevate) [![Travis](https://api.travis-ci.org/mattgreen/elevate.png)](https://travis-ci.org/mattgreen/elevate)
+[![Code Climate](https://codeclimate.com/github/mattgreen/elevate.png)](https://codeclimate.com/github/mattgreen/elevate) [![Travis](https://api.travis-ci.org/mattgreen/elevate.png)](https://travis-ci.org/mattgreen/elevate) [![Gem Version](https://badge.fury.io/rb/elevate.png)](http://badge.fury.io/rb/elevate)
 
 Example
 -------
 
 ```ruby
 @login_task = async username: username.text, password: password.text do
+  # This block runs on a background thread.
   task do
-    # This block runs on a background thread.
-    #
-    # The @username and @password instance variables correspond to the args
-    # passed into async. API is a thin wrapper class over Elevate::HTTP,
-    # which blocks until the request returns, yet can be interrupted.
-    credentials = API.login(@username, @password)
+    # @username and @password correspond to the Hash keys provided to async.
+    args = { username: @username, password: @password }
+
+    credentials = Elevate::HTTP.post(LOGIN_URL, args)
     if credentials
       UserRegistration.store(credentials.username, credentials.token)
     end
@@ -57,7 +56,7 @@ end
 
 Background
 -----------
-Many iOS apps have fairly simple domain logic that is obscured by several programming 'taxes':
+Many iOS/OS X apps have fairly simple domain logic that is obscured by several programming 'taxes':
 
 * UI management
 * asynchronous network requests
@@ -65,23 +64,21 @@ Many iOS apps have fairly simple domain logic that is obscured by several progra
 
 These are necessary to ensure a good user experience, but they splinter your domain logic (that is, what your application does) through your view controller. Gross.
 
-Elevate is a mini task queue for your iOS app, much like Resque or Sidekiq. Rather than defining part of an operation to run on the UI thread, and a CPU-intensive portion on a background thread, Elevate is designed so you run the *entire* operation in the background, and receive notifications when it starts and finishes. This has a nice side effect of consolidating all the interaction for a particular task to one place. The UI code is cleanly isolated from the non-UI code. When your tasks become complex, you can elect to extract them out to a service object.
+Elevate is a mini task queue for your app, much like Resque or Sidekiq. Rather than defining part of an operation to run on the UI thread, and a CPU-intensive portion on a background thread, Elevate is designed so you run the *entire* operation in the background, and receive notifications at various times. This has a nice side effect of consolidating all the interaction for a particular task to one place. The UI code is cleanly isolated from the non-UI code. When your tasks become complex, you can elect to extract them out to a service object.
 
-In a sense, Elevate is almost a control-flow library: it bends the rules of iOS development a bit to ensure that the unique value your application provides is as clear as possible. This is most apparent with how Elevate handles network I/O: it provides a blocking HTTP client built from NSURLRequest for use within your tasks. This lets you write your tasks in a simple, blocking manner, while letting Elevate handle concerns relating to cancellation, and errors. 
+In a sense, Elevate is almost a control-flow library: it bends the rules of app development a bit to ensure that the unique value your application provides is as clear as possible.
 
-Features
+Documentation
 --------
+- [Tutorial](https://github.com/mattgreen/elevate/wiki/Tutorial) - start here
 
-* Small, beautiful DSL for describing your tasks
-* Actor-style concurrency
-* Simplifies asynchronous HTTP requests when used with Elevate::HTTP
-* Built atop of NSOperationQueue
+- [Wiki](https://github.com/mattgreen/elevate/wiki)
 
 Installation
 ------------
 Update your Gemfile:
 
-    gem "elevate", "~> 0.5.0"
+    gem "elevate", "~> 0.6.0"
 
 Bundle:
 
@@ -98,21 +95,15 @@ class ArtistsSearchViewController < UIViewController
 ```
 
 Launch an async task with the `async` method:
-
-* Pass all the data the task needs to operate (such as credentials or search terms) in to the `async` method.
-* Define a block that contains a `task` block. The `task` block should contain all of your non-UI code. It will be run on a background thread. Any data passed into the `async` method will be available as instance variables, keyed by the provided hash key.
-* Optionally:
-    * Define an `on_start` block to be run when the task starts
-    * Define an `on_finish` block to be run when the task finishes
-    * Define an `on_update` block to be called any time the task calls yield (useful for relaying status information back during long operations)
-
-All of the `on_` blocks are called on the UI thread. `on_start` is guaranteed to precede `on_update` and `on_finish`.
-
 ```ruby
 @track_task = async artist: searchBar.text do
   task do
-    artist = API.track(@artist)
+    response = Elevate::HTTP.get("http://example.com/artists", query: { artist: @artist })
+
+    artist = Artist.from_hash(response)
     ArtistDB.update(artist)
+
+    response["name"]
   end
 
   on_start do
@@ -125,13 +116,36 @@ All of the `on_` blocks are called on the UI thread. `on_start` is guaranteed to
 end
 ```
 
-To cancel a task (like when the view controller is being dismissed), call `cancel` on the task returned by the `async` method. This causes a `CancelledError` to be raised within the task itself, which is handled by the Elevate runtime. This also prevents any callbacks you have defined from running.
+If you might need to cancel the task later, call `cancel` on the object returned by `async`:
+```ruby
+@track_task.cancel
+```
+
+Timeouts
+--------
+Elevate 0.6.0 includes support for timeouts. Timeouts are declared using the `timeout` method within the `async` block. They start when an operation is queued, and automatically abort the task when the duration passes. If the task takes longer than the specified duration, the `on_timeout` callback is run.
 
-**NOTE: Within tasks, do not access the UI or containing view controller! It is extremely dangerous to do so. You must pass data into the `async` method to use it safely.**
+Example:
 
-To Do
------
-* Need ability to set timeout for tasks
+```ruby
+async do
+  timeout 0.1
+
+  task do
+    Elevate::HTTP.get("http://example.com/")
+  end
+
+  on_timeout do
+    puts 'timed out'
+  end
+
+  on_finish do |result, exception|
+    puts 'completed!'
+  end
+end
+
+
+```
 
 Caveats
 ---------

data/Rakefile

@@ -1,6 +1,16 @@
 $:.unshift("/Library/RubyMotion/lib")
 
-require 'motion/project'
+begin
+  if ENV['osx']
+    require 'motion/project/template/osx'
+  else
+    require 'motion/project/template/ios'
+  end
+
+rescue LoadError
+  require 'motion/project'
+end
+
 require "bundler/gem_tasks"
 require "bundler/setup"
 Bundler.require :default

data/elevate.gemspec

@@ -15,7 +15,5 @@ Gem::Specification.new do |gem|
   gem.version       = Elevate::VERSION
 
   gem.add_development_dependency 'rake', '>= 0.9.0'
-  gem.add_development_dependency 'guard-motion', '~> 0.1.1'
-  gem.add_development_dependency 'rb-fsevent', '~> 0.9.1'
-  gem.add_development_dependency 'webstub', '~> 0.3.3'
+  gem.add_development_dependency 'webstub', '~> 0.6.0'
 end

data/lib/elevate/dsl.rb

@@ -9,6 +9,9 @@ module Elevate
     attr_reader :task_callback
     attr_reader :update_callback
 
+    attr_reader :timeout_callback
+    attr_reader :timeout_interval
+
     def on_finish(&block)
       raise "on_finish blocks must accept two parameters" unless block.arity == 2
 
@@ -21,6 +24,12 @@ module Elevate
       @start_callback = block
     end
 
+    def on_timeout(&block)
+      raise "on_timeout blocks must accept zero parameters" unless block.arity == 0
+
+      @timeout_callback = block
+    end
+
     def on_update(&block)
       @update_callback = block
     end
@@ -30,5 +39,11 @@ module Elevate
 
       @task_callback = block
     end
+
+    def timeout(seconds)
+      raise "timeout argument must be a number" unless seconds.is_a?(Numeric)
+
+      @timeout_interval = seconds
+    end
   end
 end

data/lib/elevate/{api.rb → elevate.rb}

@@ -1,4 +1,13 @@
 module Elevate
+  # Launches a new asynchronous task.
+  #
+  # @param args [Hash]
+  #   input arguments for the task, available to the +task+ block
+  #
+  # @return [NSOperation]
+  #   operation representing this task
+  #
+  # @api public
   def async(args = {}, &block)
     with_operation(args, block) do |operation|
       queue.addOperation(operation)
@@ -25,6 +34,9 @@ module Elevate
     operation.on_start  = Callback.new(self, dsl.start_callback)  if dsl.start_callback
     operation.on_finish = Callback.new(self, dsl.finish_callback) if dsl.finish_callback
     operation.on_update = Callback.new(self, dsl.update_callback)   if dsl.update_callback
+    operation.on_timeout= Callback.new(self, dsl.timeout_callback)  if dsl.timeout_callback
+
+    operation.timeout = dsl.timeout_interval if dsl.timeout_interval
 
     yield operation
 

data/lib/elevate/http.rb

@@ -0,0 +1,25 @@
+module Elevate
+module HTTP
+  Request::METHODS.each do |m|
+    define_singleton_method(m) do |url, options = {}|
+      coordinator = IOCoordinator.for_thread
+
+      request = Request.new(m, url, options)
+
+      coordinator.signal_blocked(request) if coordinator
+      response = request.response
+      coordinator.signal_unblocked(request) if coordinator
+
+      if error = response.error
+        if error.code == NSURLErrorNotConnectedToInternet
+          raise OfflineError, error
+        else
+          raise RequestError, response.error
+        end
+      end
+
+      response
+    end
+  end
+end
+end

data/lib/elevate/http/errors.rb

@@ -1,5 +1,6 @@
 module Elevate
 module HTTP
+  # Raised when a request could not be completed.
   class RequestError < RuntimeError
     def initialize(error)
       super(error.localizedDescription)
@@ -10,6 +11,7 @@ module HTTP
     attr_reader :code
   end
 
+  # Raised when the internet connection is offline.
   class OfflineError < RequestError
   end
 end

data/lib/elevate/http/http_client.rb

@@ -7,7 +7,7 @@ module HTTP
     end
 
     def get(path, query={}, &block)
-      issue(:GET, path, nil, query: query, &block)
+      issue(:get, path, nil, query: query, &block)
     end
 
     def post(path, body, &block)
@@ -43,37 +43,7 @@ module HTTP
         options[:headers]["Content-Type"] = "application/json"
       end
 
-      response = send_request(method, url, options)
-      raise_error(response.error) if response.error
-
-      response = JSONHTTPResponse.new(response)
-      if response.error == nil && block_given?
-        result = yield response.body
-
-        result
-      else
-        response
-      end
-    end
-
-    def raise_error(error)
-      if error.code == -1009
-        raise OfflineError, error
-      else
-        raise RequestError, response.error
-      end
-    end
-
-    def send_request(method, url, options)
-      request = HTTPRequest.new(method, url, options)
-
-      coordinator = IOCoordinator.for_thread
-
-      coordinator.signal_blocked(request) if coordinator
-      response = request.response
-      coordinator.signal_unblocked(request) if coordinator
-
-      response
+      Elevate::HTTP.send(method, url, options)
     end
 
     def url_for(path)
@@ -82,34 +52,5 @@ module HTTP
       NSURL.URLWithString(path, relativeToURL:@base_url).absoluteString
     end
   end
-
-  class JSONHTTPResponse
-    def initialize(response)
-      @response = response
-      @body = decode(response.body)
-    end
-
-    def decode(data)
-      return nil if data.nil?
-
-      NSJSONSerialization.JSONObjectWithData(data, options:0, error:nil)
-    end
-
-    attr_reader :body
-
-    # TODO: delegate
-    def error
-      @response.error
-    end
-
-    def headers
-      @response.headers
-    end
-
-    def status_code
-      @response.status_code
-    end
-    
-  end
 end
 end

data/lib/elevate/http/request.rb

@@ -1,9 +1,46 @@
 module Elevate
 module HTTP
-  # TODO: redirects
-  class HTTPRequest
+  # Encapsulates a HTTP request.
+  #
+  # +NSURLConnection+ is responsible for fulfilling the request. The response
+  # is buffered in memory as it is received, and made available through the
+  # +response+ method.
+  #
+  # @api public
+  class Request
     METHODS = [:get, :post, :put, :delete, :patch, :head, :options].freeze
 
+    # Initializes a HTTP request with the specified parameters.
+    #
+    # @param [String] method
+    #   HTTP method to use
+    # @param [String] url
+    #   URL to load
+    # @param [Hash] options
+    #   Options to use
+    #
+    # @option options [Hash] :query
+    #   Hash to construct the query string from.
+    # @option options [Hash] :headers
+    #   Headers to append to the request.
+    # @option options [Hash] :credentials
+    #   Credentials to be used with HTTP Basic Authentication. Must have a
+    #   +:username+ and/or +:password+ key.
+    # @option options [NSData] :body
+    #   Raw bytes to use as the body.
+    # @option options [Hash,Array] :json
+    #   Hash/Array to be JSON-encoded as the request body. Sets the
+    #   +Content-Type+ header to +application/json+.
+    # @option options [Hash] :form
+    #   Hash to be form encoded as the request body. Sets the +Content-Type+
+    #   header to +application/x-www-form-urlencoded+.
+    #
+    # @raise [ArgumentError]
+    #   if an illegal HTTP method is used
+    # @raise [ArgumentError]
+    #   if the URL does not start with 'http'
+    # @raise [ArgumentError]
+    #   if the +:body+ option is not an instance of +NSData+
     def initialize(method, url, options={})
       raise ArgumentError, "invalid HTTP method" unless METHODS.include? method.downcase
       raise ArgumentError, "invalid URL" unless url.start_with? "http"
@@ -13,6 +50,16 @@ module HTTP
         url += "?" + URI.encode_query(options[:query])
       end
 
+      options[:headers] ||= {}
+
+      if root = options.delete(:json)
+        options[:body] = NSJSONSerialization.dataWithJSONObject(root, options: 0, error: nil)
+        options[:headers]["Content-Type"] = "application/json"
+      elsif root = options.delete(:form)
+        options[:body] = URI.encode_www_form(root).dataUsingEncoding(NSASCIIStringEncoding)
+        options[:headers]["Content-Type"] ||= "application/x-www-form-urlencoded"
+      end
+
       @request = NSMutableURLRequest.alloc.init
       @request.CachePolicy = NSURLRequestReloadIgnoringLocalCacheData
       @request.HTTPBody = options[:body]
@@ -29,14 +76,22 @@ module HTTP
         @request.setValue(value.to_s, forHTTPHeaderField:key.to_s)
       end
 
-      @response = HTTPResponse.new
+      @response = Response.new
+      @response.url = url
 
       @connection = nil
       @promise = Promise.new
     end
 
+    # Cancels an in-flight request.
+    #
+    # This method is safe to call from any thread.
+    #
+    # @return [void]
+    #
+    # @api public
     def cancel
-      return unless started?
+      return unless sent?
 
       NetworkThread.cancel(@connection)
       ActivityIndicator.instance.hide
@@ -44,22 +99,41 @@ module HTTP
       @promise.fulfill(nil)
     end
 
+    # Returns a response to this request, sending it if necessary
+    #
+    # This method blocks the calling thread, unless interrupted.
+    #
+    # @return [Elevate::HTTP::Response, nil]
+    #   response to this request, or nil, if this request was canceled
+    #
+    # @api public
     def response
-      unless started?
-        start()
+      unless sent?
+        send
       end
 
       @promise.value
     end
 
-    def start
+    # Sends this request. The caller is not blocked.
+    #
+    # @return [void]
+    #
+    # @api public
+    def send
       @connection = NSURLConnection.alloc.initWithRequest(@request, delegate:self, startImmediately:false)
 
       NetworkThread.start(@connection)
       ActivityIndicator.instance.show
     end
 
-    def started?
+    # Returns true if this request is in-flight
+    #
+    # @return [Boolean]
+    #   true if this request is in-flight
+    #
+    # @api public
+    def sent?
       @connection != nil
     end
 
@@ -75,7 +149,7 @@ module HTTP
     end
 
     def connection(connection, didFailWithError: error)
-      puts "ERROR: #{error.localizedDescription} (code: #{error.code})"
+      puts "ERROR: #{error.localizedDescription} (code: #{error.code})" unless RUBYMOTION_ENV == "test"
 
       @response.error = error
       @response.freeze
@@ -93,6 +167,12 @@ module HTTP
       @promise.fulfill(@response)
     end
 
+    def connection(connection, willSendRequest: request, redirectResponse: response)
+      @response.url = request.URL.absoluteString
+
+      request
+    end
+
     def get_authorization_header(credentials)
       "Basic " + Base64.encode("#{credentials[:username]}:#{credentials[:password]}")
     end