daylight 0.9.0.rc1

data/doc/environment.md

@@ -0,0 +1,109 @@
+# Build Environment
+
+This is the environment that Daylight was built with that may not be obvious
+simply from the Gemfile.
+
+## Requirements
+
+Only items requrired are [ruby](https://www.ruby-lang.org/en/downloads/)
+and [bundler](http://bundler.io/) to contribute to Daylight.
+
+All other [dependencies](#dependencies) are loaded via `bundler`.
+
+    ruby                      2.0.0-p247
+    bundler                   1.3.5
+
+## Developer Preferences
+
+We use [rbenv](https://github.com/sstephenson/rbenv) to help manage
+our ruby versions and [pow](http://pow.cx/) as our application
+(rack) server.
+
+    rbenv                      0.4.0
+    pow                        0.4.1
+    powder                     0.2.0
+
+FWIW, we also use rbenv plugin
+[rbenv-gemset](https://github.com/jf/rbenv-gemset),
+[rbenv-bundler](https://github.com/carsomyr/rbenv-bundler), and
+[rbenv-gem-rehash](https://github.com/sstephenson/rbenv-gem-rehash)
+
+We control pow using the [powder](https://github.com/Rodreegez/powder) CLI.
+
+_YMMV, and can use any tool to handle these functions._
+
+## Runtime Dependencies
+
+    rails                      4.0.5
+    activeresource             4.0.0
+    active_model_serializers   0.8.1
+
+[Rails](https://github.com/rails/rails)) and
+[ActiveModelSerializers](https://github.com/rails-api/active_model_serializers)
+are required by Daylight run the server and extend it.
+[ActiveResource](https://github.com/rails/activeresource) is required by Daylight to run the client and extend it.
+
+    haml                       4.0.5
+    hanna-bootstrap            0.0.5
+    actionpack-page_caching    1.0.2
+
+These are for the Documentation Rails Engine.
+[Haml](https://github.com/haml/haml) is a
+templating engine to generate the API documentation.
+[actionpack-page_caching](https://github.com/rails/actionpack-page_caching)
+will cache the generated documenation so there is no penalty to the server.
+
+[hanna-bootstrap](https://github.com/ngs/hanna-bootstrap) to generate
+rdoc using the twitter bootstrap theme.
+
+
+## API Development Dependencies
+
+We have used the following for API Development.  Without any motification we
+expect you to develop your API using:
+
+    rails                      4.0
+    activeresource             4.0
+    active_model_serializers   0.8
+
+In our own API, we use the following to assist us to build our API, these
+libraries are in no way required to use Daylight.  These are only offered
+as suggestions:
+
+    rails-api                  0.1.0
+    versionist                 1.2.1
+
+## Development & Test Dependencies
+
+    rspec                      2.14.1
+    rspec-rails                2.14.2
+    simplecov-rcov             0.2.3
+
+We use [rspec](https://github.com/rspec/rspec) and
+[rspec-rails](https://github.com/rspec/rspec-rails)
+for rails testing and
+[simplecov-rcov](https://github.com/fguillen/simplecov-rcov)
+for coverage testing.
+
+    webmock                    1.18.0
+
+Daylight request and responses occur through [webmock](https://github.com/bblimke/webmock).
+`Daylight::Mock` is built on top of it.
+
+    sqlite3-ruby               1.3.9
+    factory_girl               2.0
+    faker                      1.2.0
+
+Database backend is handled by [sqlite3](https://github.com/sparklemotion/sqlite3-ruby),
+you will need to [download](https://www.sqlite.org/download.html)
+the binaries or use your favorite package manager.
+
+  ````
+    brew install sqlite3
+  ````
+
+We use [factory_girl](https://github.com/thoughtbot/factory_girl)
+to build our fixtures and [faker](https://github.com/stympy/faker)
+to populate its data.
+
+

data/doc/example.md

@@ -0,0 +1,3 @@
+## Example Application
+
+Placeholder for explaining how the [example application](example) works and how it was put together.

data/doc/framework.md

@@ -0,0 +1,31 @@
+# Framework Overview
+
+`Daylight` alters or extends Rails components.  The framework are tiny
+extensions on the shoulders of giants.  See [stats](#loc-statistics).
+Generally, there are 5 main parts to `Daylight`:
+
+| Directory        | Function         |                                                                 |
+| ---------------- | ---------------- | --------------------------------------------------------------- |
+| lib              | Client Modules   | Additions and fixes to `ActiveResource::Base`                   |
+| rails/daylight   | Server Modules   | Additions to the Rails MVC environment                          |
+| rails/extensions | Rails Extensions | Patches/Fixes to Rails components and ActiveModelSerializer     |
+| app, config      | Documentation    | `Rails::Engine` to provide documentation of the API             |
+| spec, test       | Mock Testing     | Mock to assist API testing in either RSpec or TestUnit/MiniTest |
+
+`Daylight` is a tiny extension on the shoulders of giants and wouldn't be possible without
+
+## Rails Extensions
+
+The Rails extensions are loaded along with the Server modules. This is the list
+of extensions and the reason why they are required:
+
+| Extension                | Reason                                                                       |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| autosave_association_fix | fix `ActiveRecord::Base` autosaving `inverse_of` associations                |
+| has_one_serializer_ext   | modify `ActiveModel::Serializer` to recognize belong_to :through association |
+| read_only_attributes     | modfiy `ActiveModel::Serializer` to support `read_only` attributes           |
+| render_json_meta         | mofify `ActiveModel::Serializer` to include metadata to the json response    |
+| nested_attributes_ext    | allows `ActiveRecord::Base` association between previously existing records  |
+| route_options            | extend routes to allow `associated` and `remoted` options                    |
+| versioned_url_for        | uses any versioned paths for `url_for`                                       |
+

data/doc/install.md

@@ -0,0 +1,128 @@
+# Installation Steps
+
+## Client Setup
+
+Install the gem or add it to your bundler's Gemfile:
+
+    gem install daylight
+
+Require and run setup, no options are needed:
+
+  ````ruby
+    require 'daylight'
+
+    Daylight::API.setup!
+  ````
+
+This is the same as specifying `setup!` with the following defaults:
+
+  ````ruby
+    require 'daylight'
+
+    Daylight::API.setup!({
+      namespace: 'API',
+      password:  nil,
+      endpoint:  'http://localhost',
+      version:   'v1',
+      versions:  ['v1'],
+      timeout:   60
+    })
+  ````
+
+You can customize each of these options:
+* `namespace` is the module to which you wish ActiveResource client models to belong
+* `password` supplied in the `X-Http-Authentication` header to be used for simple authentication
+* `endpoint` is the URL where your server is running (a synonym for `ActiveResource#site`)
+* `version` is the active version of your API client models
+* `version` the set of all versions of your API client models
+* `timeout` the duration in seconds in which to timeout a request
+
+You can customize any combination of these options.
+
+## Server Setup
+
+Install the gem or add it to your bundler's Gemfile:
+
+    gem install daylight
+
+In an initializer add the Daylight's Rails extensions and patches:
+
+  ````ruby
+    require 'daylight/server'
+  ````
+
+## API Documentation
+
+Daylight provides a Rails App Engine for autogenerated API documentation. All
+docs are created on the fly by examining your routes, controllers and
+ActiveRecord models.
+
+Add this to `config/application.rb`:
+
+  ````ruby
+      require 'daylight/documentation'
+  ````
+
+And mount it in your routes:
+
+  ````ruby
+      mount Daylight::Documentation => '/docs/api'
+  ````
+
+You will also need to include your client models in your application through
+Bundler or some other method.
+
+### Rake Tasks
+
+Add this to your `Rakefile`:
+
+  ```ruby
+    require 'daylight/tasks'
+  ```
+
+This provides two rake tasks:
+
+  ````
+    rake doc:api:generate # Pre-generate the API documentation
+    rake doc:api:clean    # Clear the API documentation
+  ````
+
+The `doc:api:generate` tasks requests every page in the documentation so it can
+be pre-cached.  Make sure to run it in an environment where caching is turned
+on:
+
+  ````ruby
+    config.action_controller.perform_caching = true
+  ````
+
+  ````
+    RAILS_ENV=production rake doc:api:generate
+  ````
+
+The `doc:api:clean` tasks clears out the documentation cache directory.
+
+
+## Testing
+
+You can use the supplied mock for [testing](testing.md) when developing your
+API.
+
+Add the following to your `test_helper.rb` or `spec_helper.rb`:
+
+  ````ruby
+    require 'daylight/mock'
+
+    Daylight::Mock.setup
+  ````
+
+## Console
+
+When developing your API, you will want to ensure your aliases are also updated
+when you `reload!` Add the following to an initializer on your server:
+
+  ````ruby
+    require 'daylight/client_reloader'
+  ````
+
+More information about the [client reloader](develop.md#client-reloader) is
+available in the development guide.

data/doc/principles.md

@@ -0,0 +1,42 @@
+# Guiding Principles
+
+Here are decisions we made when developing Daylight. We often referred back to these
+to help us decide which approach to take. These are not hard-and-fast rules and can
+be reviewed and changed as the need arises.
+
+1. Let Rails do all of the database work
+   * The client should require the least amount of data to peform the database task
+   * Avoid replicating `ActiveRecord` functionality in the client framework
+   * Improvements to Rails will benefit the client
+   * **Examples**: `through: :associations`, `where_values`, `nested_attributes`
+
+2. Maintain symantic URLs and formatted responses
+   * Symantic URLs and query parameters are logically grouped and executed without the client
+   * Axiomatically, DSL on the client-side is done through symantic URLs and query parameters
+   * Consistency on responses allows the client to _just work_ without adjustment
+   * Additions are expressed as additions to the formatted responses
+   * **Examples**: associations treated like nested routes, properly named root elements in data, metadata is supported
+
+3. The most granualar objects in responses represent models or their collections
+   * Return values only in the context of models (not literals like strings, integers etc.)
+   * These objects can be manipulated and saved
+   * Rails and `ActiveRecord` don't need to be patched to handle this edgecase
+   * **Examples**:associated routes, remote methods
+
+4. Expected behavior of dependent software _should_ not change when extended
+   * Developers should not be surprised by unexpected results from software they know and love
+   * Exception is to fix exposed problems in the underlying software or if the benefits are highly valueble
+   * Changes to the underlying software can be triggered through configuration
+   * **Examples**:`AutosaveAssociationFix`, `ActiveResource::Base#has_one`, `ReflectionExt`
+
+5. Extend dependent software (gems) by including changes using `ActiveSupport::Concerns`
+   * Concerns show in ancestor lists and can chain to original methods via `super`
+   * Extensions remain modular and may be extracted individually when needed
+   * **Examples**: `read_only`, `where_values` metadata on `Serializer`, `ResourceProxy`, `Refinements`
+
+6. Behavior driven tests drive towards integration testing
+   * Use `ActiveRecord` to do the work for retrieving models instead of mocking it out
+   * Server responses are a natural place to mock for the client
+   * Build models and factories on the fly for the backing test data
+   * **Examples**: `Daylight::Mock`, `MigrationHelper`
+

data/doc/testing.md

@@ -0,0 +1,107 @@
+# API Testing
+
+Daylight offers a simple mocking framework that simplifies the process of writing tests for your client code.
+
+## Daylight::Mock
+
+Works with both Rspec and TestUnit/Minitest.
+
+To start add this to your `test_helper.rb` or `spec_helper.rb`:
+
+  ```ruby
+    Daylight::Mock.setup
+  ```
+
+The mock will simulate valid JSON responses to calls so you don't have to stub out anything, especially not the HTTP calls themselves.
+At the end of the test you can examine the calls that were made by calling *daylight_mock*.
+
+For example, say you want to test code that updates a User object.
+
+  ```ruby
+    user = API::V1::User.find(1)
+    user.title = 'Grand Poobah'
+    user.save
+  ```
+
+This call to +daylight_mock+ returns a list of all the update calls made on a *User* object:
+
+  ```ruby
+    daylight_mock.updated(:user)
+  ```
+
+To get only the last update use:
+
+  ```ruby
+    daylight_mock.last_updated(:user)
+  ```
+
+Here's some things you can do with the recorded request:
+
+  ```ruby
+    mock = daylight_mock.last_updated(:user)
+
+    mock.post_data
+    #=> {"user"=>{"id"=>1, "title"=>"Grand Poobah"}}
+
+    mock.status
+    #=> 201
+  ```
+
+Each recorded request keeps some data to check against:
+
+| Attribute       | Description                                                                                               |
+|-----------------|---------------------------------------------------------------------------------------------------------- |
+| resource        | The resouce name                                                                                          |
+| path_parts      | A `Struct` of the request's path split into resource parts (`version`, `resource`, `id` and `associated`) |
+| path            | The request's path                                                                                        |
+| response_body   | `Daylight::Mock`'s response to the request                                                                |
+| post_data       | The request's POST data                                                                                   |
+| params          | The request's parsed parameters                                                                           |
+| action          | The request's action (`:created`, `:updated`, `:associated`...)                                           |
+| status          | Response status                                                                                           |
+| target_object   | The target object response if available (e.g. the response object to a `find(1)` call)                    |
+| request         | The raw request object                                                                                    |
+| response        | The raw response object                                                                                   |
+
+Supported Calls: *created, updated, associated, indexed, shown, deleted*
+
+
+#### More Examples
+
+  ```ruby
+    # assert the number of `Posts`
+    daylight_mock.updated(:post).count.must_equal 2
+
+    # assert that the `Post` has a title of "Grand Poobah"
+    daylight_mock.last_updated(:post).target_object.title.must_equal "Grand Poobah"
+
+    # assert that the `User` was created
+    daylight_mock.last_created(:user).status.must_equal 201
+  ```
+
+## API Integration Testing
+
+If you are developing the Rails API and Client models, here is a technique for integration testing:
+
+Keeping client and server code in sync is vitally important. It's all too easy for updates on the server to accidently break client integration. Any changes that are not backwards-compatible should induce a version change in the API. Though sometimes it is difficult to recognize when a change breaks some client endpoint.
+
+This is where integration testing comes in. We want to write tests that call methods on the client models, hit the rails application and eventually call the database, then all the way back up the chain.
+
+In the project that eventually spawned Daylight, we did this without spawning the rails application by using [Artifice](https://github.com/wycats/artifice). Artifice routes all Net::HTTP calls to a Rack application. Rails is a rack application! So now with one line of code, any call we make to our Daylight client library hits the Rails application without having to spin up a server.
+
+In your +test_helper.rb+ or +spec_helper.rb+:
+
+  ```ruby
+    require 'artifice'
+    Artifice.activate_with(Example::Application)
+  ```
+
+You applicaiton code must require your client models in your test suite.
+
+For instance, we develop our client models alongside our Rails application and link them together using Bundler file path:
+
+  ```ruby
+    gem 'api', '0.0.1', path: '../api'
+  ```
+
+Your your mileage may vary depending on how you develop in your environment.