stitches 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 37541ea41d74a49dd809ec68dfcaf44a3bfb1221
+  data.tar.gz: d3d0eceb9b3a231d7535622f161c5100d6686c5d
+SHA512:
+  metadata.gz: 6e566f80064dffdd94b5fd0f181d9751a1999869d778c970c3f791c3d673c062c4ae7da06acc60aa6aed0def394584ad962c6b7a9ff6b93f7cd9d6d046cd2172
+  data.tar.gz: b8f6160025a9cafe573452b9cc907c484f0909980a070709b2612b3d5f3645cafc93dcf7e973b4c797d47560b05a626cb16a6e62861770ccdcfdbcb04ba01d59

data/.gitignore

@@ -0,0 +1,10 @@
+pkg
+spec/reports
+.vimrc
+*.sw?
+.idea/
+config/database.yml
+.tddium*
+.DS_Store
+.jhw-cache
+**.orig

data/.ruby-gemset

@@ -0,0 +1 @@
+stitches

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://www.rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,126 @@
+PATH
+  remote: .
+  specs:
+    stitches (3.0.0)
+      rails
+      rspec (~> 3)
+
+GEM
+  remote: https://www.rubygems.org/
+  specs:
+    actionmailer (4.2.0)
+      actionpack (= 4.2.0)
+      actionview (= 4.2.0)
+      activejob (= 4.2.0)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+    actionpack (4.2.0)
+      actionview (= 4.2.0)
+      activesupport (= 4.2.0)
+      rack (~> 1.6.0)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.1)
+    actionview (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.1)
+    activejob (4.2.0)
+      activesupport (= 4.2.0)
+      globalid (>= 0.3.0)
+    activemodel (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+    activerecord (4.2.0)
+      activemodel (= 4.2.0)
+      activesupport (= 4.2.0)
+      arel (~> 6.0)
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    arel (6.0.0)
+    builder (3.2.2)
+    diff-lcs (1.2.5)
+    erubis (2.7.0)
+    globalid (0.3.0)
+      activesupport (>= 4.1.0)
+    hike (1.2.3)
+    i18n (0.7.0)
+    json (1.8.2)
+    loofah (2.0.1)
+      nokogiri (>= 1.5.9)
+    mail (2.6.3)
+      mime-types (>= 1.16, < 3)
+    mime-types (2.4.3)
+    mini_portile (0.6.2)
+    minitest (5.5.1)
+    multi_json (1.10.1)
+    nokogiri (1.6.6.2)
+      mini_portile (~> 0.6.0)
+    rack (1.6.0)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (4.2.0)
+      actionmailer (= 4.2.0)
+      actionpack (= 4.2.0)
+      actionview (= 4.2.0)
+      activejob (= 4.2.0)
+      activemodel (= 4.2.0)
+      activerecord (= 4.2.0)
+      activesupport (= 4.2.0)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.2.0)
+      sprockets-rails
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.5)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.1)
+      loofah (~> 2.0)
+    railties (4.2.0)
+      actionpack (= 4.2.0)
+      activesupport (= 4.2.0)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.3.2)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.0)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.0)
+    sprockets (2.12.3)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-rails (2.2.4)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      sprockets (>= 2.8, < 4.0)
+    thor (0.19.1)
+    thread_safe (0.3.4)
+    tilt (1.4.1)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  stitches!

data/README.md

@@ -0,0 +1,220 @@
+You'll be in stitches at how easy it is to get your API service up and running!
+
+This gem provides:
+
+* Rails plugin to handle api key and versioned requests
+* Generator to get you set up and validate your API before you write any code
+* Spec helpers to use when building your API
+
+## To install
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'stitches'
+```
+
+Then of course:
+
+```
+bundle install
+```
+
+If your app is brand new or you don't already have rspec or Apitome, be sure to run those generators and set them up first. You can skip this if you've done either of these before:
+
+```
+rails generate rspec:install
+rails generate apitome:install
+```
+
+Then, run the Stitches generator:
+
+```
+rails g stitches:api
+```
+
+Run database migrations (do `rake db:create` first if you haven't yet set up a database)
+
+```
+rake db:migrate
+```
+
+
+## Test the install
+
+In your app run:
+
+```
+rake generate_api_key[some_name_you_pick]
+```
+
+Then follow the instructions it outputs.
+
+If you are doing this locally and get an error like the following:
+
+> WEBrick::HTTPStatus::LengthRequired
+
+that's because WEBrick doesn't want an empty body. Throw on a `-d ''` to the end of the command.
+
+## Rails Plugin
+
+Just using this gem will get you:
+
+* Middleware that requires an api key in the request.  See `Stitches::ApiKey`.
+* Middleware that requires a versioned JSON mime type.  We aren't using version numbers in the URLs but putting versions in the `Accept` header.  See `Stitches::ValidMimeType`.
+* Monkeypatch ActiveSupport's `TimeWithZone` to use ISO8601 UTC as the encoding for all timestamps.  This ensures that every JSON response is using the same timezone and can be parsed properly with JavaScript.
+* `Error` and `Errors` objects for creating error reponses that will be rendered properly in API responses.  These can work with exceptions, ActiveRecord objects, or whatever you like.
+
+The plugin works in conjunction with other pieces of this gem set up by using the generator.
+
+### A word on errors
+
+The error format generated by `Errors` and friends is designed for two purposes:
+
+* provide a "programmer key" upon which logic can be based for each error
+* provide a message to explain the error to the programmer and, in times of desperation, the user
+
+The idea is that the caller should not have made a call that generates an error, although this isn't always 100% possible to avoid.  As such, the error messages that come back are not as "rich" as you might get
+from ActiveRecord.  APIs aren't intended to be used for validating user input.  The messages are aimed at a programmer trying to understand why a call failed.
+
+## Generator
+
+When you run the generator via `rails g stitches:api`, you'll get a lot of handy setup done for you:
+
+* Two "ping" controllers that do nothing but respond to requests.  This are useful when creating an API client or when validating
+a deployed instance, as they will succeed when all the moving parts are working, but won't actually hit a database or depend on
+any particular business logic.
+* Routes configured using `Stitches::ApiVersionConstraint` to route to your ping controllers based on the version in
+the `Accept` header.  This allows your api client to fully validate that it's using the versioning system properly.
+* An `ApiClient` model and migration for your database.  This additionally sets up UUID support in Postgres.
+* An `api_spec.rb` spec that will spin up your application and check that all the RESTful/HTTP stuff is working as designed.
+* A means to write API documentation via [rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation), and serve it nicely via [apitome](https://github.com/modeset/apitome).  You write tests using a slightly modified DSL that allows you to document the API.  The produced documentation shows the headers and wire formats with your test data.
+
+Once this is done, you can (and possibly should) deploy your app to validate everything's working before you get too into your
+business logic.
+
+Once you start writing your app, there's a few spec helpers available.
+
+## Generator-provided tests
+
+The generator will provide some tests for your app to test a base level of functionality. To use them, add the Capybara gem to your app:
+
+```
+gem 'capybara'
+```
+
+And in your `spec_helper.rb`:
+
+```ruby
+require 'capybara/rails'
+```
+
+## Spec Helpers
+
+```ruby
+# in your spec_helper.rb
+require 'stitches/spec'
+```
+
+### `have_api_error` 
+
+This can be used in a feature spec on a response object to check that the error format is in our "canonical" format, which is as
+follows:
+
+```json
+{
+  "errors": [
+    {
+      "code": "some_code",
+      "message": "some readable message"
+    },
+    {
+      "code": "some_other_code",
+      "message": "some other readable message"
+    }
+    # etc.
+  ]
+}
+```
+
+To assert this in your specs:
+
+```ruby
+expect(response).to have_api_error(status: 404,
+                                   code: "not_found",
+                                   message: "the exact error message")
+
+# regexps also work
+expect(response).to have_api_error(status: 404,
+                                   code: "name_invalid",
+                                   message: /can't be blank/)
+```
+
+Omitting `status` will use a default of 422, which is Rails' default for validation errors.
+
+### `be_iso8601_utc_encoded`
+
+This can be used to ensure that your JSON-encoded timestamps meet the recommended format of IS8601 UTC-encoded strings.
+
+```ruby
+expect(json["created_at"]).to be_iso8601_utc_encoded
+```
+
+### `TestHeaders`
+
+This class is useful when creating headers in feature specs that will conform to what's needed by the API you are building.
+The generated `api_spec.rb` is a complete example, but here's a sampling:
+
+```ruby
+# Create headers for a version 2 request
+headers = TestHeaders.new(version: 2)
+post "/api/ping", {}.to_json, headers.headers
+
+# Create headers that have the wrong mime type in them
+headers = TestHeaders.new(mime_type: "application/foobar")
+post "/api/ping", {}.to_json, headers.headers
+```
+
+### `ApiClients` module
+
+Mixing this in provides the method `api_client` that will return the one api client.  This is because fixtures have been so flaky
+in our tests, and factories don't always work for stuff like this.  Also, why require the use of factories?
+
+## Configuration
+
+You'll see in the initializer that you can configure aspects of the library globally.  `Stitches::Configuration` documents the available
+options.
+
+## Avoiding auto-magical Set-up
+
+Instead of requiring `stitches`, you can avoid the railtie and configure things yourself:
+
+```
+# Gemfile
+gem 'stitches', require: false
+
+# config/initializers/stitches.rb
+require 'stitches_norailtie'
+
+Stitches.configure do |config|
+  config.whatever = :foo
+end
+
+# config/application.rb
+config.app_middleware.use "Stitches::ApiKey", except: %r{/super-secret}
+config.app_middleware.use "Stitches::ValidMimeType", except: %r{/super-secret}
+# or whatever you want to do
+```
+
+## Developing
+
+Although `Stitches.configuration` is global, do not depend directly on that in your logic.  Instead, allow all classes to receive a
+configuration object in their constructor.  This makes the classes easier to deal with and change, without incurring much of a real cost to development.
+Glaobl symbols suck, but are convienient.  This is how you make the most of it.
+
+
+---
+
+Provided with love by your friends at [Stitch Fix Engineering](http://technology.stitchfix.com)
+
+![stitches](https://s3.amazonaws.com/stitchfix-stitches/stitches.png)

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler/gem_tasks'
+require 'rubygems/package_task'
+require 'rspec/core/rake_task'
+
+$: << File.join(File.dirname(__FILE__),'lib')
+
+include Rake::DSL
+
+gemspec = eval(File.read('stitches.gemspec'))
+Gem::PackageTask.new(gemspec) {}
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/stitches.rb

@@ -0,0 +1,3 @@
+require 'stitches_norailtie'
+require 'stitches/railtie'
+require 'apitome'

data/lib/stitches/api_generator.rb

@@ -0,0 +1,97 @@
+require 'rails/generators'
+
+module Stitches
+  class ApiGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root(File.expand_path(File.join(File.dirname(__FILE__),"generator_files")))
+
+    def self.next_migration_number(path)
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    desc "Bootstraps your API service with a basic ping controller and spec to ensure everything is setup properly"
+    def bootstrap_api
+      inject_into_file "Gemfile", after: /^gem ["']pg['"].*$/ do<<-GEM
+
+gem "apitome"
+gem "responders"
+      GEM
+      end
+      inject_into_file "config/routes.rb", before: /^end/ do<<-ROUTES
+namespace :api do
+  scope module: :v1, constraints: Stitches::ApiVersionConstraint.new(1) do
+    resource 'ping', only: [ :create ]
+    # Add your V1 resources here
+  end
+  scope module: :v2, constraints: Stitches::ApiVersionConstraint.new(2) do
+    resource 'ping', only: [ :create ]
+    # This is here simply to validate that versioning is working
+    # as well as for your client to be able to validate this as well.
+  end
+end
+api_docs = Rack::Auth::Basic.new(Apitome::Engine ) do |_,password|
+  password == ENV['HTTP_AUTH_PASSWORD']
+end
+mount api_docs, at: "docs"
+      ROUTES
+      end
+
+      run 'bundle install'
+
+      copy_file "app/controllers/api.rb"
+      copy_file "app/controllers/api/api_controller.rb"
+      copy_file "app/controllers/api/v1.rb"
+      copy_file "app/controllers/api/v2.rb"
+      copy_file "app/controllers/api/v1/pings_controller.rb"
+      copy_file "app/controllers/api/v2/pings_controller.rb"
+      copy_file "app/models/api_client.rb"
+      copy_file "config/initializers/stitches.rb"
+      copy_file "lib/tasks/generate_api_key.rake"
+      copy_file "spec/features/api_spec.rb", "spec/features/api_spec.rb"
+      copy_file "spec/acceptance/ping_v1_spec.rb", "spec/acceptance/ping_v1_spec.rb"
+
+      inject_into_file "Gemfile", after: /^group :test, :development do.*$/ do<<-GEM
+
+gem "rspec_api_documentation"
+      GEM
+      end
+      run 'bundle install'
+
+      migration_template "db/migrate/enable_uuid_ossp_extension.rb", "db/migrate/enable_uuid_ossp_extension.rb"
+      sleep 1 # allow clock to tick so we get different numbers
+      migration_template "db/migrate/create_api_clients.rb", "db/migrate/create_api_clients.rb"
+
+      inject_into_file 'spec/spec_helper.rb', %q{
+config.include RSpec::Rails::RequestExampleGroup, type: :feature
+}, before: /^end/
+
+      inject_into_file 'spec/spec_helper.rb', before: /^RSpec.configure/ do<<-REQUIRE
+require 'stitches/spec'
+      REQUIRE
+      end
+
+      append_to_file 'spec/spec_helper.rb' do<<-RSPEC_API
+RspecApiDocumentation.configure do |config|
+config.format = :json
+config.request_headers_to_include = %w(
+  Accept
+  Content-Type
+  Authorization
+  If-Modified-Since
+)
+config.response_headers_to_include = %w(
+  Last-Modified
+  ETag
+)
+config.api_name = "YOUR SERVICE NAME HERE"
+end
+      RSPEC_API
+      end
+      run "rails g apitome:install"
+      gsub_file 'config/initializers/apitome.rb', /config.mount_at = .*$/, "config.mount_at = nil"
+      gsub_file 'config/initializers/apitome.rb', /config.title = .*$/, "config.title = 'Service Documentation'"
+
+    end
+  end
+end